qdk_chemistry.algorithms.stability_checker module

Public entry point for the SCF stability checking algorithms.

This module re-exports the core StabilityChecker so that consumers can import it directly from qdk_chemistry.algorithms without depending on internal package paths.

class qdk_chemistry.algorithms.stability_checker.QdkStabilityChecker

Bases: StabilityChecker

QDK implementation of the stability checker.

This class provides a concrete implementation of the stability checker using the backend. It inherits from the base StabilityChecker class and implements the run method to perform stability analysis on wavefunctions.

Typical usage:

import qdk_chemistry.algorithms as alg
import qdk_chemistry.data as data

# Assume you have a wavefunction from an SCF calculation
scf_solver = algorithms.create("scf_solver", backend)
energy, wavefunction = scf_solver.run(structure, 0, 1, "basis_set")

# Create a stability checker instance
stability_checker = algorithms.create("stability_checker", backend)

# Configure settings if needed
stability_checker.settings().set("internal", True)
stability_checker.settings().set("external", True)

# Perform stability analysis
is_stable, result = stability_checker.run(wavefunction)

See also

StabilityChecker qdk_chemistry.data.StabilityResult qdk_chemistry.data.Wavefunction

__init__(self: qdk_chemistry.algorithms.QdkStabilityChecker) → None

Default constructor.

Initializes a stability checker with default settings.

class qdk_chemistry.algorithms.stability_checker.StabilityChecker

Bases: pybind11_object

Abstract base class for wavefunction stability checkers.

This class defines the interface for checking the stability of wavefunctions in quantum chemistry calculations. Stability checking examines the second-order response of a wavefunction to determine if it corresponds to a true minimum or if there are directions in which the energy can be lowered.

Examples

>>> # To create a custom stability checker, inherit from this class.
>>> import qdk_chemistry.algorithms as alg
>>> import qdk_chemistry.data as data
>>> class MyStabilityChecker(alg.StabilityChecker):
...     def __init__(self):
...         super().__init__()  # Call the base class constructor
...     # Implement the _run_impl method
...     def _run_impl(self, wavefunction: data.Wavefunction) -> tuple[bool, data.StabilityResult]:
...         # Custom stability checking implementation
...         import numpy as np
...         internal_eigenvalues = np.array([1.0, 2.0, 3.0])
...         external_eigenvalues = np.array([0.5, 1.5])
...         internal_eigenvectors = np.eye(3)
...         external_eigenvectors = np.eye(2)
...         internal_stable = np.all(internal_eigenvalues > 0)
...         external_stable = np.all(external_eigenvalues > 0)
...         result = data.StabilityResult(internal_stable, external_stable,
...                                       internal_eigenvalues, internal_eigenvectors,
...                                       external_eigenvalues, external_eigenvectors)
...         return (result.is_stable(), result)

__init__(self: qdk_chemistry.algorithms.StabilityChecker) → None

Create a StabilityChecker instance.

Initializes a new stability checker with default settings. Configuration options can be modified through the settings() method.

Examples

>>> checker = alg.StabilityChecker()
>>> checker.settings().set("nroots", 5)
>>> checker.settings().set("convergence_threshold", 1e-6)

name(self: qdk_chemistry.algorithms.StabilityChecker) → str

The algorithm’s name.

Returns:

The name of the algorithm

Return type:

str

run(self: qdk_chemistry.algorithms.StabilityChecker, wavefunction: qdk_chemistry.data.Wavefunction) → tuple[bool, qdk_chemistry.data.StabilityResult]

Check the stability of the given wavefunction.

This method automatically locks settings before execution and performs stability analysis on the input wavefunction by examining the eigenvalues of the electronic Hessian matrix. A stable wavefunction should have all positive eigenvalues for both internal and external stability.

Parameters:

wavefunction (qdk_chemistry.data.Wavefunction) – The wavefunction to analyze for stability

Returns:

Tuple of the overall stability flag and the detailed stability information (eigenvalues, eigenvectors, and helper accessors).

Return type:

tuple[bool, qdk_chemistry.data.StabilityResult]

settings(self: qdk_chemistry.algorithms.StabilityChecker) → qdk_chemistry.data.Settings

Access the stability checker’s configuration settings.

Returns:

Reference to the settings object for configuring the stability checker

Return type:

qdk_chemistry.data.Settings

type_name(self: qdk_chemistry.algorithms.StabilityChecker) → str

The algorithm’s type name.

Returns:

The type name of the algorithm

Return type:

str