qdk_chemistry.plugins.pyscf.stability module

PySCF stability analysis module for QDK.

This module provides wavefunction stability analysis capabilities using the PySCF library and integrates PySCF stability algorithms into the QDK framework.

The implementation supports both restricted (RHF, ROHF) and unrestricted (UHF) wavefunction stability analysis including:

• Internal stability analysis (within the same wavefunction type)

• RHF external stability analysis (RHF -> UHF instabilities)

This module registers a pyscf stability checker with the QDK stability checker registry at import time, making the functionality available via qdk_chemistry.algorithms.create(‘stability_checker’, ‘pyscf’).

Requires: PySCF (the code uses pyscf.lib, pyscf.scf, pyscf.soscf, and pyscf.scf.stability routines).

class qdk_chemistry.plugins.pyscf.stability.PyscfStabilityChecker

Bases: StabilityChecker

PySCF-based stability checker for quantum chemistry wavefunctions.

This class implements wavefunction stability analysis using routines from PySCF. It supports multiple wavefunction types and can perform internal stability analysis of RHF, ROHF, UHF and external stability analysis (RHF -> UHF instability).

Internal stability eigenvalues are rescaled to follow the convention used in the original stability analysis formulation (J. Chem. Phys. 66, 3045-3050 (1977)) and to be consistent with the QDK implementation:

• RHF internal eigenvalues are scaled by 1/4

• UHF internal eigenvalues are scaled by 1/2

• RHF external eigenvalues are left unscaled

Key behavior: - Automatically detects wavefunction type (RHF, ROHF, UHF) and applies appropriate analysis - Internal stability analysis is performed within the same wavefunction type - External stability analysis (RHF -> UHF) only supported for RHF wavefunctions - Raises an error for ROHF or UHF when external analysis is requested - Returns StabilityResult with separate internal and external stability information

Raises:

ValueError – If wavefunction is not a SlaterDeterminantContainer (container type “sd”).

Examples

>>> checker = PyscfStabilityChecker()
>>> is_stable, result = checker.run(wavefunction)
>>> print(f"Overall stable: {is_stable}")
>>> print(f"Internal stable: {result.is_internal_stable()}")
>>> print(f"External stable: {result.is_external_stable()}")

__init__()

Initialize the PySCF stability checker with default settings.

name()

Return the name for the stability checker.

Return type:

str

class qdk_chemistry.plugins.pyscf.stability.PyscfStabilitySettings

Bases: Settings

Configuration settings for PySCF stability analysis.

This class manages settings for wavefunction stability analysis procedures using PySCF. It inherits from the Settings base class and exposes the configurable options used by PyscfStabilityChecker.

Available settings:

• internal: Whether to perform internal stability analysis (within the same wavefunction type).

• external: Whether to perform external stability analysis (RHF -> UHF instabilities).

  Only supported for RHF wavefunctions. Will raise an error if enabled for ROHF or UHF.

• with_symmetry: Whether to respect point group symmetry during stability analysis.

• nroots: Number of eigenvalue roots to compute in the Davidson solver.

• davidson_tolerance: Convergence threshold for the Davidson eigenvalue solver.

• stability_tolerance: Threshold for determining stability from eigenvalues.

• method: The electronic structure method (“hf” for Hartree-Fock or a DFT functional name).

• xc_grid: Integer DFT integration grid density level passed to PySCF (0=coarse, 9=very fine).

• pyscf_verbose: PySCF verbosity level for lib.davidson logging (0=silent, 4=info, 5=debug).

Examples

>>> settings = PyscfStabilitySettings()
>>> settings.get("nroots")
3
>>> settings.set("nroots", 5)
>>> settings.set("external", False)  # Only internal stability
>>> settings.set("method", "b3lyp")  # Use B3LYP DFT

__init__()

Initialize the stability checker with default parameters.