qrunch.chemistry.ground_state_problem.builders.active_space_ground_state_problem_modifier

Complete active space ground state problem modifier.

Module Attributes

DEFAULT_ACTIVE_SPACE_OPTIONS

The default options for the active space modification.

Classes

`ActiveSpaceElectronConfiguration`	Active space electron configuration.
`ActiveSpaceGroundStateProblemModifier`	A Active space (AS) ground state problem modifier.
`ActiveSpaceOptions`	Options controlling the active-space reduction of two-body integrals.
`ActiveSpaceRestrictedGroundStateProblemModifier`	Modifier that can build a restricted active space ground state problem modifier.
`ActiveSpaceUnrestrictedGroundStateProblemModifier`	Modifier that can build a active space unrestricted ground state problem modifier.

class ActiveSpaceElectronConfiguration

Bases: object

Active space electron configuration.

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

Parameters:

number_of_active_spatial_orbitals – The number of spatial orbitals in the active space.
number_of_active_alpha_electrons – The number of alpha electrons in the active space. Set to None to automatically determine the number of active alpha electrons based on occupation numbers. Requires that occupation_based_selection is enabled in ActiveSpaceOptions and that molecular_orbital_occupations are available in the ground-state problem.

__init__(number_of_active_spatial_orbitals: int, number_of_active_alpha_electrons: int | None) → None

Parameters:

number_of_active_spatial_orbitals (int)
number_of_active_alpha_electrons (int | None)

Return type:

None

number_of_active_alpha_electrons: int | None

number_of_active_spatial_orbitals: int

class ActiveSpaceGroundStateProblemModifier

Bases: GroundStateProblemModifier

A Active space (AS) ground state problem modifier.

__init__(active_space_electron_configuration: ActiveSpaceElectronConfiguration, options: ActiveSpaceOptions = ActiveSpaceOptions(reduction_tolerance=1e-10, degeneracy_tolerance=1e-06, occupation_based_selection=False, occupation_deviation_threshold=0.02, log_orbital_info=False)) → None

Initialize a ActiveSpaceGroundStateProblemModifier.

The ActiveSpaceGroundStateProblemModifier modify an existing ground state problem to account for a active space (AS) calculation. It does so by creating a new ground state problem with a well-defined active space. This means that the integrals only include contributions from the active orbitals and the core Hamiltonian is replaced by the inactive Fock matrix, which includes contributions from the inactive orbitals.

The new ground state problem include the inactive energy contribution, which is a constant energy arising from the inactive orbitals.

Parameters:

active_space_electron_configuration (ActiveSpaceElectronConfiguration) – The active space configuration to use in the builder.
options (ActiveSpaceOptions) – Options controlling the active-space integral reduction.

Return type:

None

modify(problem: RestrictedGroundStateProblem) → RestrictedGroundStateProblem

modify(problem: UnrestrictedGroundStateProblem) → UnrestrictedGroundStateProblem

Calculate the inactive Fock matrices and return the active space integrals.

The inactive Fock matrices include contributions from the inactive orbitals and are used in the Active Space (AS) calculation to account for interactions between active and inactive orbitals.

Parameters:: problem (RestrictedGroundStateProblem | UnrestrictedGroundStateProblem) – The ground state problem to modify.
Return type:: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem

classmethod persistence_key() → str

Provide a unique persistence key for checkpointing after this modifier is applied.

Return type:: str

classmethod short_name() → str

Provide a short name for logging purposes.

Return type:: str

class ActiveSpaceOptions

Bases: DataclassPublicAPI

Options controlling the active-space reduction of two-body integrals.

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

Parameters:

reduction_tolerance – A reduction threshold. Currently, this is only used for RI-integrals, where the reduction tolerance is used as a relative threshold for pruning auxiliary basis functions. Thus, eigenvalues smaller than this relative threshold are discarded. (default=1e-10)
degeneracy_tolerance – Absolute energy tolerance (in Hartree) used to detect degenerate molecular orbitals at the active-space boundary. If two orbital energies differ by less than this value they are considered degenerate, and an error is raised when the chosen active space would split such a degenerate set. (default=1e-6)
occupation_based_selection – If True, select active-space orbitals based on orbital occupation numbers rather than using a contiguous energy-ordered window. Occupied orbitals with the lowest occupation numbers and virtual orbitals with the highest occupation numbers are chosen. Requires that molecular_orbital_occupations is available in the ground-state problem. Note that this only makes sense when the orbital occupation numbers are derived from a correlated calculation, e.g., MP2. (default=False)
occupation_deviation_threshold – Maximum deviation from full occupation for an orbital to be considered fully occupied. When occupation_based_selection is True, occupied orbitals whose occupation deviates from the nominal full occupation by more than this value are included in the active space. Specifically, orbitals with occupation below nominal_max - deviation or above nominal_max + deviation are selected. The nominal full occupation is 2.0 for restricted and 1.0 for unrestricted calculations (handled automatically). Must be positive. (default=0.02)
log_orbital_info – If True, log the orbital energies and occupation numbers for all orbitals (frozen occupied + active occupied + active virtual + frozen virtual). Useful for debugging active-space choices. (default=False)

__init__(*, reduction_tolerance: float = 1e-10, degeneracy_tolerance: float = 1e-06, occupation_based_selection: bool = False, occupation_deviation_threshold: float = 0.02, log_orbital_info: bool = False) → None

Parameters:

reduction_tolerance (float)
degeneracy_tolerance (float)
occupation_based_selection (bool)
occupation_deviation_threshold (float)
log_orbital_info (bool)

Return type:

None

degeneracy_tolerance: float = 1e-06

log_orbital_info: bool = False

occupation_based_selection: bool = False

occupation_deviation_threshold: float = 0.02

reduction_tolerance: float = 1e-10

class ActiveSpaceRestrictedGroundStateProblemModifier

Bases: object

Modifier that can build a restricted active space ground state problem modifier.

__init__(active_space_electron_configuration: ActiveSpaceElectronConfiguration, options: ActiveSpaceOptions = ActiveSpaceOptions(reduction_tolerance=1e-10, degeneracy_tolerance=1e-06, occupation_based_selection=False, occupation_deviation_threshold=0.02, log_orbital_info=False)) → None

Initialize a ActiveSpaceRestrictedGroundStateProblemModifier.

Parameters:

active_space_electron_configuration (ActiveSpaceElectronConfiguration) – The active space configuration to use in the builder.
options (ActiveSpaceOptions) – Options controlling the active-space integral reduction.

Return type:

None

modify(problem: RestrictedGroundStateProblem) → RestrictedGroundStateProblem

Calculate the inactive Fock matrices and return the active space integrals.

The inactive Fock matrices include contributions from the inactive orbitals and are used in the active space calculation to account for interactions between active and inactive orbitals.

When occupation_based_selection is enabled in the options, orbitals are first reordered according to their occupation numbers so that the most correlated occupied and virtual orbitals form the active space.

Parameters:: problem (RestrictedGroundStateProblem) – The ground state problem to modify.
Return type:: RestrictedGroundStateProblem

classmethod short_name() → str

Provide a short name for logging purposes.

Return type:: str

class ActiveSpaceUnrestrictedGroundStateProblemModifier

Bases: object

Modifier that can build a active space unrestricted ground state problem modifier.

__init__(active_space_electron_configuration: ActiveSpaceElectronConfiguration, options: ActiveSpaceOptions = ActiveSpaceOptions(reduction_tolerance=1e-10, degeneracy_tolerance=1e-06, occupation_based_selection=False, occupation_deviation_threshold=0.02, log_orbital_info=False)) → None

Initialize a ActiveSpaceRestrictedGroundStateProblemModifier.

Parameters:

active_space_electron_configuration (ActiveSpaceElectronConfiguration) – The active space configuration to use in the builder.
options (ActiveSpaceOptions) – Options controlling the active-space integral reduction.

Return type:

None

modify(problem: UnrestrictedGroundStateProblem) → UnrestrictedGroundStateProblem

Calculate the inactive Fock matrices and return the active space integrals.

The inactive Fock matrices include contributions from the inactive orbitals and are used in the Active Space calculation to account for interactions between active and inactive orbitals.

When occupation_based_selection is enabled in the options, orbitals are first reordered according to their occupation numbers so that the most correlated occupied and virtual orbitals form the active space.

Parameters:: problem (UnrestrictedGroundStateProblem) – The ground state problem to modify.
Return type:: UnrestrictedGroundStateProblem

classmethod short_name() → str

Provide a short name for logging purposes.

Return type:: str

DEFAULT_ACTIVE_SPACE_OPTIONS = ActiveSpaceOptions(reduction_tolerance=1e-10, degeneracy_tolerance=1e-06, occupation_based_selection=False, occupation_deviation_threshold=0.02, log_orbital_info=False): The default options for the active space modification.