qrunch.chemistry.problem_builders.ground_state_problem.full_ground_state_problem_builders

Module containing builders for a full ground state problem.

Functions

persistence_checkpoints()

Define the persistence checkpoints used during the process.

Classes

`FullGroundStateProblemBuilder`	Full ground state problem builder.
`FullGroundStateProblemBuilderOptions`	Default options for the FullGroundStateProblemBuilder.
`FullRestrictedGroundStateProblemBuilder`	Restricted full ground state problem builder.
`FullUnrestrictedGroundStateProblemBuilder`	Unrestricted full ground state problem builder.

class FullGroundStateProblemBuilder

Bases: GroundStateProblemBuilder

Full ground state problem builder.

__init__(*, verbose: bool = False, molecular_orbital_calculator: MolecularOrbitalCalculator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, options: FullGroundStateProblemBuilderOptions | None = None) → None

Initialize a full ground state problem builder.

This builder uses a general MolecularOrbitalCalculator to obtain the molecular orbitals required for defining the ground state problem.

The builder can build a restricted or unrestricted ground state problem.

The ground state problem is an object that contains all the information needed to solve the electronic structure problem for a given molecular configuration. This includes the molecular electronic integrals, the electron configuration, and any additional energy contributions (e.g., nuclear repulsion energy).

Parameters:

verbose (bool) – If True, enables verbose output for the calculation process.
molecular_orbital_calculator (MolecularOrbitalCalculator | None) – Solver used to find orbitals for the system. HartreeFockCalculator is used as default.
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. UnrestrictedTwoBodyElectronRepulsionIntegralBuilder is used as default.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
options (FullGroundStateProblemBuilderOptions | None) – The options for the full ground state problem builder.

Return type:

None

apply_restricted_post_active_space_modifiers(problem: RestrictedGroundStateProblem) → RestrictedGroundStateProblem

Apply modifiers that follow the active space modifier to a restricted problem.

Parameters:: problem (RestrictedGroundStateProblem) – The restricted ground state problem with active space already applied.
Return type:: RestrictedGroundStateProblem

apply_restricted_post_active_space_modifiers_lazy(problem: RestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → LazyRestrictedGroundStateProblem

Apply post-active-space modifiers to a restricted problem and return a lazy on-disk reference.

Parameters:

problem (RestrictedGroundStateProblem) – The restricted ground state problem with active space already applied.
molecular_configuration (MolecularConfiguration) – The molecular configuration used to derive the persistence metadata.

Return type:

LazyRestrictedGroundStateProblem

apply_unrestricted_post_active_space_modifiers(problem: UnrestrictedGroundStateProblem) → UnrestrictedGroundStateProblem

Apply modifiers that follow the active space modifier to an unrestricted problem.

Parameters:: problem (UnrestrictedGroundStateProblem) – The unrestricted ground state problem with active space already applied.
Return type:: UnrestrictedGroundStateProblem

apply_unrestricted_post_active_space_modifiers_lazy(problem: UnrestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → LazyUnrestrictedGroundStateProblem

Apply post-active-space modifiers to an unrestricted problem and return a lazy on-disk reference.

Parameters:

problem (UnrestrictedGroundStateProblem) – The unrestricted ground state problem with active space already applied.
molecular_configuration (MolecularConfiguration) – The molecular configuration used to derive the persistence metadata.

Return type:

LazyUnrestrictedGroundStateProblem

build_restricted(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build restricted full ground state problem containing all atomic orbitals.

This method uses the restricted formalism which assumes that the alpha and beta spin components are identical, simplifying the electronic structure problem. This is suitable for systems where the electron spins are paired, such as closed-shell molecules.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: RestrictedGroundStateProblem

build_restricted_lazy(molecular_configuration: MolecularConfiguration) → LazyRestrictedGroundStateProblem

Build the restricted ground state problem and return a lazy on-disk reference.

Requires that a DataPersisterManager was provided at construction time. See FullRestrictedGroundStateProblemBuilder.build_lazy() for details.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to build the problem for.
Return type:: LazyRestrictedGroundStateProblem

build_restricted_pre_active_space_problem(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build the restricted problem up to (but not including) the active space modifier.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: RestrictedGroundStateProblem

build_unrestricted(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build unrestricted full ground state problem containing all atomic orbitals.

This method uses the unrestricted formalism, where the alpha and beta spin components are treated independently, leading to a more flexible (but computationally more demanding) calculation. This flexibility allows the problem to describe systems with unpaired electrons (e.g., radicals) more accurately.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: UnrestrictedGroundStateProblem

build_unrestricted_lazy(molecular_configuration: MolecularConfiguration) → LazyUnrestrictedGroundStateProblem

Build the unrestricted ground state problem and return a lazy on-disk reference.

Requires that a DataPersisterManager was provided at construction time. See FullUnrestrictedGroundStateProblemBuilder.build_lazy() for details.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to build the problem for.
Return type:: LazyUnrestrictedGroundStateProblem

build_unrestricted_pre_active_space_problem(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build the unrestricted problem up to (but not including) the active space modifier.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: UnrestrictedGroundStateProblem

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

is_mean_field() → bool

Return whether the molecular orbital calculator is a mean-field method.

Return type:: bool

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

class FullGroundStateProblemBuilderOptions

Bases: DataclassPublicAPI

Default options for the FullGroundStateProblemBuilder.

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

Parameters:: lazy_integral_threshold – The threshold for the number of molecular orbitals above which lazy integrals will be used when an active space modifier is present. (default=120)

__init__(*, lazy_integral_threshold: int = 120) → None

Parameters:: lazy_integral_threshold (int)
Return type:: None

lazy_integral_threshold: int = 120

class FullRestrictedGroundStateProblemBuilder

Bases: object

Restricted full ground state problem builder.

__init__(*, verbose: bool = False, molecular_orbital_calculator: MolecularOrbitalCalculator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, options: FullGroundStateProblemBuilderOptions | None = None) → None

Initialize a restricted full ground state problem builder.

This builder uses a general MolecularOrbitalCalculator to obtain the molecular orbitals required for defining the ground state problem. The restricted formalism assumes that the alpha and beta spin components are identical, simplifying the electronic structure problem.

Parameters:

verbose (bool) – If True, enables verbose output for the calculation process.
molecular_orbital_calculator (MolecularOrbitalCalculator | None) – Solver used to find molecular orbitals for the system. MollerPlesset2Calculator is used as default.
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. TwoBodyElectronRepulsionIntegralBuilder is used as default.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
options (FullGroundStateProblemBuilderOptions | None) – The options for the full ground state problem builder.

Return type:

None

apply_post_active_space_modifiers(problem: RestrictedGroundStateProblem) → RestrictedGroundStateProblem

Apply the modifiers that follow the active space modifier.

This method applies modifiers that come after the ActiveSpaceGroundStateProblemModifier in the configured modifier list.

Parameters:: problem (RestrictedGroundStateProblem) – The restricted ground state problem with active space already applied.
Return type:: RestrictedGroundStateProblem

apply_post_active_space_modifiers_lazy(problem: RestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → LazyRestrictedGroundStateProblem

Apply post-active-space modifiers, persist the final problem and return a lazy reference.

Behaves like apply_post_active_space_modifiers() but persists the fully modified problem via this builder’s DataPersisterManager and releases the in-memory copy, returning a lazy reference that can be materialised later via LazyRestrictedGroundStateProblem.manifest().

Parameters:

problem (RestrictedGroundStateProblem) – The restricted ground state problem with active space already applied.
molecular_configuration (MolecularConfiguration) – The molecular configuration used to derive the persistence metadata.

Return type:

LazyRestrictedGroundStateProblem

build(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build full ground state problem containing all atomic orbitals.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: RestrictedGroundStateProblem

build_lazy(molecular_configuration: MolecularConfiguration) → LazyRestrictedGroundStateProblem

Build the full restricted ground state problem and return a lazy on-disk reference.

The problem is built and persisted through this builder’s DataPersisterManager, then released from memory. The returned LazyRestrictedGroundStateProblem can later be materialized via its manifest() method.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to build the problem for.
Return type:: LazyRestrictedGroundStateProblem

build_pre_active_space_problem(molecular_configuration: MolecularConfiguration) → RestrictedGroundStateProblem

Build the restricted ground state problem, applying modifiers up to the active space modifier.

This method creates the unmodified problem (MO calculation + integrals) and applies any modifiers that precede the ActiveSpaceGroundStateProblemModifier in the modifier list.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: RestrictedGroundStateProblem

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

class FullUnrestrictedGroundStateProblemBuilder

Bases: object

Unrestricted full ground state problem builder.

__init__(*, verbose: bool = False, molecular_orbital_calculator: MolecularOrbitalCalculator | None = None, repulsion_integral_builder: TwoBodyElectronRepulsionIntegralBuilderProtocol | None = None, data_persister_manager: DataPersisterManager | None = None, problem_modifiers: list[GroundStateProblemModifier] | None = None, options: FullGroundStateProblemBuilderOptions | None = None) → None

Initialize an unrestricted full ground state problem builder.

This builder uses a general MolecularOrbitalCalculator to obtain the molecular orbitals required for defining the ground state problem. In the unrestricted formalism, the alpha and beta spin components are treated independently, leading to a more flexible (but computationally more demanding) calculation. This flexibility allows the problem to describe systems with unpaired electrons (e.g., radicals) more accurately.

Parameters:

verbose (bool) – If True, enables verbose output for the calculation process.
molecular_orbital_calculator (MolecularOrbitalCalculator | None) – Solver used to find orbitals for the system. MollerPlesset2Calculator is used as default.
repulsion_integral_builder (TwoBodyElectronRepulsionIntegralBuilderProtocol | None) – The object that can build two electron repulsion integrals. UnrestrictedTwoBodyElectronRepulsionIntegralBuilder is used as default.
data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy full system calculations.
problem_modifiers (list[GroundStateProblemModifier] | None) – A list of problem modifiers
options (FullGroundStateProblemBuilderOptions | None) – The options for the full ground state problem builder.

Return type:

None

apply_post_active_space_modifiers(problem: UnrestrictedGroundStateProblem) → UnrestrictedGroundStateProblem

Apply the modifiers that follow the active space modifier.

This method applies modifiers that come after the ActiveSpaceGroundStateProblemModifier in the configured modifier list.

Parameters:: problem (UnrestrictedGroundStateProblem) – The unrestricted ground state problem with active space already applied.
Return type:: UnrestrictedGroundStateProblem

apply_post_active_space_modifiers_lazy(problem: UnrestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → LazyUnrestrictedGroundStateProblem

Apply post-active-space modifiers, persist the final problem and return a lazy reference.

Behaves like apply_post_active_space_modifiers() but persists the fully modified problem via this builder’s DataPersisterManager and releases the in-memory copy, returning a lazy reference that can be materialised later via LazyUnrestrictedGroundStateProblem.manifest().

Parameters:

problem (UnrestrictedGroundStateProblem) – The unrestricted ground state problem with active space already applied.
molecular_configuration (MolecularConfiguration) – The molecular configuration used to derive the persistence metadata.

Return type:

LazyUnrestrictedGroundStateProblem

build(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build full ground state problem containing all atomic orbitals.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: UnrestrictedGroundStateProblem

build_lazy(molecular_configuration: MolecularConfiguration) → LazyUnrestrictedGroundStateProblem

Build the full unrestricted ground state problem and return a lazy on-disk reference.

The problem is built and persisted through this builder’s DataPersisterManager, then released from memory. The returned LazyUnrestrictedGroundStateProblem can later be materialized via its manifest() method.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to build the problem for.
Return type:: LazyUnrestrictedGroundStateProblem

build_pre_active_space_problem(molecular_configuration: MolecularConfiguration) → UnrestrictedGroundStateProblem

Build the unrestricted ground state problem, applying modifiers up to the active space modifier.

This method creates the unmodified problem (MO calculation + integrals) and applies any modifiers that precede the ActiveSpaceGroundStateProblemModifier in the modifier list.

Parameters:: molecular_configuration (MolecularConfiguration) – The molecular configuration to calculate the integrals from.
Return type:: UnrestrictedGroundStateProblem

data_persister_manager() → DataPersisterManager | None

Return the data persister manager.

Return type:: DataPersisterManager | None

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]

persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the process.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:: list[str]