qdk_chemistry.utils package

QDK/Chemistry Utilities Module.

class qdk_chemistry.utils.CaseInsensitiveStrEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

StrEnum that allows case-insensitive lookup of values.

qdk_chemistry.utils.compute_valence_space_parameters(wavefunction: qdk_chemistry.data.Wavefunction, charge: SupportsInt) → tuple[int, int]

Get the default number of active electrons, active orbitals, which are obtained from the valence electrons and orbitals of the atomic element types in the structure. The structure is automatically extracted from the wavefunction.

Returns:

Pair of ( n_active_electrons, n_active_orbitals )

Return type:

tuple

Examples

(active_electrons, active_orbitals) = compute_valence_space(wavefunction, charge)

qdk_chemistry.utils.rotate_orbitals(orbitals: qdk_chemistry.data.Orbitals, rotation_vector: Annotated[numpy.typing.ArrayLike, numpy.float64, '[m, 1]'], num_alpha_occupied_orbitals: SupportsInt, num_beta_occupied_orbitals: SupportsInt, restricted_external: bool = False) → qdk_chemistry.data.Orbitals

Rotate molecular orbitals using a rotation vector.

This function takes Orbitals and applies orbital rotations using a rotation vector, typically taken from stability analysis eigenvectors.

The rotation is performed by: 1. Unpacking the rotation vector into an anti-Hermitian matrix 2. Computing the unitary rotation matrix via matrix exponential 3. Applying the rotation to the molecular orbital coefficients

Parameters:

  • orbitals (qdk_chemistry.data.Orbitals) – The Orbitals to rotate

  • rotation_vector (numpy.ndarray) – The rotation vector (typically from stability analysis, corresponding to the lowest eigenvalue)

  • num_alpha_occupied_orbitals (int) – Number of alpha occupied orbitals

  • num_beta_occupied_orbitals (int) – Number of beta occupied orbitals

  • restricted_external (bool, optional) – If True and orbitals are restricted, creates unrestricted orbitals with rotated coefficients for alpha spin and unrotated coefficients for beta spin. Default is False.

Returns:

A new Orbitals object with rotated molecular orbital coefficients

Return type:

qdk_chemistry.data.Orbitals

Notes

  • restricted_external can break spin symmetry and solve external instabilities of RHF/RKS.

  • For unrestricted calculations, the rotation vector should contain alpha rotations first (n_occ_alpha * n_vir_alpha elements), then beta rotations (n_occ_beta * n_vir_beta elements).

  • This function assumes aufbau filling for occupation numbers.

  • Orbital energies are invalidated by rotation and set to null.

Raises:

RuntimeError – If rotation vector size is invalid

Examples

>>> # After stability analysis that finds instability
>>> rotation_vector = ...  # eigenvector from stability analysis
>>> rotated_orbitals = rotate_orbitals(orbitals, rotation_vector,
...                                     num_alpha_occupied_orbitals,
...                                     num_beta_occupied_orbitals)

Submodules