qrunch.chemistry.problem_builders.ground_state_problem.problems

Protocols for ground state problem builders.

Module Attributes

`GeneralRestrictedGroundStateProblem`	A restricted ground state problem, possibly in lazy on-disk form.
`GeneralUnrestrictedGroundStateProblem`	An unrestricted ground state problem, possibly in lazy on-disk form.
`GeneralGroundStateProblem`	A ground state problem of either spin treatment, possibly in lazy on-disk form.

Functions

manifest_problem(...)

Manifest a lazy problem into an in-memory GroundStateProblem, or return it directly if already materialized.

Classes

`LazyRestrictedGroundStateProblem`	Lazy reference to a `RestrictedGroundStateProblem` stored via a DataPersisterManager.
`LazyUnrestrictedGroundStateProblem`	Lazy reference to an `UnrestrictedGroundStateProblem` stored via a DataPersisterManager.
`RestrictedGroundStateProblem`	Restricted ground state problem.
`UnrestrictedGroundStateProblem`	Unrestricted ground state problem.

GeneralGroundStateProblem = qrunch.chemistry.problem_builders.ground_state_problem.problems.RestrictedGroundStateProblem | qrunch.chemistry.problem_builders.ground_state_problem.problems.LazyRestrictedGroundStateProblem | qrunch.chemistry.problem_builders.ground_state_problem.problems.UnrestrictedGroundStateProblem | qrunch.chemistry.problem_builders.ground_state_problem.problems.LazyUnrestrictedGroundStateProblem: A ground state problem of either spin treatment, possibly in lazy on-disk form.

GeneralRestrictedGroundStateProblem = qrunch.chemistry.problem_builders.ground_state_problem.problems.RestrictedGroundStateProblem | qrunch.chemistry.problem_builders.ground_state_problem.problems.LazyRestrictedGroundStateProblem: A restricted ground state problem, possibly in lazy on-disk form.

GeneralUnrestrictedGroundStateProblem = qrunch.chemistry.problem_builders.ground_state_problem.problems.UnrestrictedGroundStateProblem | qrunch.chemistry.problem_builders.ground_state_problem.problems.LazyUnrestrictedGroundStateProblem: An unrestricted ground state problem, possibly in lazy on-disk form.

class LazyRestrictedGroundStateProblem

Bases: object

Lazy reference to a RestrictedGroundStateProblem stored via a DataPersisterManager.

Holding a lazy reference avoids keeping the (potentially very large) problem instance in memory. The full problem can be reconstructed on demand via manifest(), used, and then released so that only one problem is materialized at a time.

Parameters:

data_persister_manager – Manager that handles loading the persisted problem.
key – Persistence key used when the problem was saved.
metadata – Metadata that uniquely identifies the persisted problem within key. Must match the metadata used during saving.

__init__(data_persister_manager: DataPersisterManager, key: str, metadata: Mapping[str, str | Mapping[str, str | NestedStrDict]]) → None

Parameters:

data_persister_manager (DataPersisterManager)
key (str)
metadata (Mapping[str, str | Mapping[str, str | NestedStrDict]])

Return type:

None

data_persister_manager: DataPersisterManager

property is_lazy: Literal[True]: Whether it is lazy.

property is_restricted: Literal[True]: Whether it is restricted.

key: str

manifest() → RestrictedGroundStateProblem

Load the persisted problem via the data persister manager into memory.

Return type:: RestrictedGroundStateProblem

metadata: Mapping[str, str | Mapping[str, str | NestedStrDict]]

class LazyUnrestrictedGroundStateProblem

Bases: object

Lazy reference to an UnrestrictedGroundStateProblem stored via a DataPersisterManager.

Holding a lazy reference avoids keeping the (potentially very large) problem instance in memory. The full problem can be reconstructed on demand via manifest(), used, and then released so that only one problem is materialized at a time.

Parameters:

data_persister_manager – Manager that handles loading the persisted problem.
key – Persistence key used when the problem was saved.
metadata – Metadata that uniquely identifies the persisted problem within key. Must match the metadata used during saving.

__init__(data_persister_manager: DataPersisterManager, key: str, metadata: Mapping[str, str | Mapping[str, str | NestedStrDict]]) → None

Parameters:

data_persister_manager (DataPersisterManager)
key (str)
metadata (Mapping[str, str | Mapping[str, str | NestedStrDict]])

Return type:

None

data_persister_manager: DataPersisterManager

property is_lazy: Literal[True]: Whether it is lazy.

property is_restricted: Literal[False]: Whether it is restricted.

key: str

manifest() → UnrestrictedGroundStateProblem

Load the persisted problem via the data persister manager into memory.

Return type:: UnrestrictedGroundStateProblem

metadata: Mapping[str, str | Mapping[str, str | NestedStrDict]]

class RestrictedGroundStateProblem

Bases: HasMetadataHashMethod

Restricted ground state problem.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

electronic_structure_integrals – Integrals for the problem.
electron_configuration – Electronic configuration for the problem.
energy_contributions – Energy contributions needed for the final energy.
molecular_orbital_energies – Molecular orbital energies for the problem, if available.
molecular_orbital_occupations – Molecular orbital occupations for the problem, if available.
molecular_orbitals – Molecular orbitals (AO-basis coefficients) for the problem, if available.

__init__(electronic_structure_integrals: RestrictedElectronicStructureIntegrals, electron_configuration: MolecularElectronConfiguration, energy_contributions: MolecularEnergyContributions, molecular_orbital_energies: RestrictedMolecularOrbitalEnergies | None, molecular_orbital_occupations: RestrictedMolecularOrbitalOccupations | None, molecular_orbitals: RestrictedMolecularOrbitals | None = None) → None

Parameters:

electronic_structure_integrals (RestrictedElectronicStructureIntegrals)
electron_configuration (MolecularElectronConfiguration)
energy_contributions (MolecularEnergyContributions)
molecular_orbital_energies (RestrictedMolecularOrbitalEnergies | None)
molecular_orbital_occupations (RestrictedMolecularOrbitalOccupations | None)
molecular_orbitals (RestrictedMolecularOrbitals | None)

Return type:

None

electron_configuration: MolecularElectronConfiguration

electronic_structure_integrals: RestrictedElectronicStructureIntegrals

energy_contributions: MolecularEnergyContributions

property is_lazy: Literal[False]: Whether it is lazy.

property is_restricted: Literal[True]: Whether it is restricted.

molecular_orbital_energies: RestrictedMolecularOrbitalEnergies | None

molecular_orbital_occupations: RestrictedMolecularOrbitalOccupations | None

molecular_orbitals: RestrictedMolecularOrbitals | None = None

rotate(rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...], *, molecular_orbital_energies: RestrictedMolecularOrbitalEnergies | None = None, molecular_orbital_occupations: RestrictedMolecularOrbitalOccupations | None = None) → RestrictedGroundStateProblem

Create a new problem with integrals and molecular orbitals rotated by the given matrix.

The rotation is applied to both the one-body and two-body integrals, and the molecular orbital coefficients are updated as C_new = C_old @ U.

Since orbital energies and occupations are generally invalidated by an arbitrary rotation, they are set to None unless explicitly provided.

Parameters:

rotation_matrices (tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) – Tuple containing a single rotation matrix U of shape (n, n).
molecular_orbital_energies (RestrictedMolecularOrbitalEnergies | None) – New molecular orbital energies for the rotated problem. Defaults to None (invalidated by rotation).
molecular_orbital_occupations (RestrictedMolecularOrbitalOccupations | None) – New molecular orbital occupations for the rotated problem. Defaults to None (invalidated by rotation).

Return type:

RestrictedGroundStateProblem

class UnrestrictedGroundStateProblem

Bases: HasMetadataHashMethod

Unrestricted ground state problem.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

electronic_structure_integrals – Integrals for the problem.
electron_configuration – Electronic configuration for the problem.
energy_contributions – Energy contributions needed for the final energy.
molecular_orbital_energies – Molecular orbital energies for the problem, if available.
molecular_orbital_occupations – Molecular orbital occupations for the problem, if available.
molecular_orbitals – Molecular orbitals (AO-basis coefficients) for the problem, if available.

__init__(electronic_structure_integrals: UnrestrictedElectronicStructureIntegrals, electron_configuration: MolecularElectronConfiguration, energy_contributions: MolecularEnergyContributions, molecular_orbital_energies: UnrestrictedMolecularOrbitalEnergies | None, molecular_orbital_occupations: UnrestrictedMolecularOrbitalOccupations | None, molecular_orbitals: UnrestrictedMolecularOrbitals | None = None) → None

Parameters:

electronic_structure_integrals (UnrestrictedElectronicStructureIntegrals)
electron_configuration (MolecularElectronConfiguration)
energy_contributions (MolecularEnergyContributions)
molecular_orbital_energies (UnrestrictedMolecularOrbitalEnergies | None)
molecular_orbital_occupations (UnrestrictedMolecularOrbitalOccupations | None)
molecular_orbitals (UnrestrictedMolecularOrbitals | None)

Return type:

None

electron_configuration: MolecularElectronConfiguration

electronic_structure_integrals: UnrestrictedElectronicStructureIntegrals

energy_contributions: MolecularEnergyContributions

property is_lazy: Literal[False]: Whether it is lazy.

property is_restricted: Literal[False]: Whether it is restricted.

molecular_orbital_energies: UnrestrictedMolecularOrbitalEnergies | None

molecular_orbital_occupations: UnrestrictedMolecularOrbitalOccupations | None

molecular_orbitals: UnrestrictedMolecularOrbitals | None = None

rotate(rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...], *, molecular_orbital_energies: UnrestrictedMolecularOrbitalEnergies | None = None, molecular_orbital_occupations: UnrestrictedMolecularOrbitalOccupations | None = None) → UnrestrictedGroundStateProblem

Create a new problem with integrals and molecular orbitals rotated by the given matrices.

The rotation is applied to both the one-body and two-body integrals, and the molecular orbital coefficients are updated as C_alpha_new = C_alpha_old @ U_alpha and C_beta_new = C_beta_old @ U_beta.

Since orbital energies and occupations are generally invalidated by an arbitrary rotation, they are set to None unless explicitly provided.

Parameters:

rotation_matrices (tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]) – Tuple of two rotation matrices (U_alpha, U_beta), each of shape (n, n).
molecular_orbital_energies (UnrestrictedMolecularOrbitalEnergies | None) – New molecular orbital energies for the rotated problem. Defaults to None (invalidated by rotation).
molecular_orbital_occupations (UnrestrictedMolecularOrbitalOccupations | None) – New molecular orbital occupations for the rotated problem. Defaults to None (invalidated by rotation).

Return type:

UnrestrictedGroundStateProblem

manifest_problem(problem: RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem) → RestrictedGroundStateProblem

manifest_problem(problem: UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem) → UnrestrictedGroundStateProblem

Manifest a lazy problem into an in-memory GroundStateProblem, or return it directly if already materialized.

Parameters:: problem (RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem | UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem) – A ground state problem that may be lazy (on-disk) or already in memory.
Return type:: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem