qrunch.chemistry.problem_builders.ground_state_problem.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 from the orbital occupation numbers. This requires that the ground-state problem carries fractional (correlated) molecular_orbital_occupations, e.g. from the MP2 or CCSD molecular orbital calculator.

__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, correlation_balance_tolerance=0.005, 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.

How active-space orbitals are selected is determined by the data rather than by an option: when the ground-state problem carries fractional (correlated) occupation numbers, orbitals are ranked by their deviation from nominal occupation; otherwise a contiguous window in the incoming orbital order is used.

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 tolerance used to detect degenerate orbitals at the active-space boundary. It is applied to two different spectra and is therefore dimensioned on one and dimensionless on the other: in Hartree when comparing orbital energies, and in electrons when comparing occupation numbers. If two values straddling a boundary differ by less than this tolerance they are considered degenerate, and a warning is logged when the chosen active space would split such a degenerate set. The calculation is not stopped. (default=1e-6)
correlation_balance_tolerance – Absolute tolerance (dimensionless, in electrons) used to detect orbitals that are correlated to essentially the same degree at the active-space boundary. It is applied to the occupation deviations min(n, 2 - n), which is the quantity the active window is cut against, rather than to the occupation numbers themselves. Two deviations straddling a boundary are considered equally correlated when they differ by less than this tolerance and agree to within a factor of about 1.12. A warning is logged when the chosen active space would split such a set; the calculation is not stopped. Only pairs in which at least one orbital is appreciably correlated (a deviation above occupation_deviation_threshold) can trigger the warning. (default=0.005)
occupation_deviation_threshold – Maximum deviation from full occupation (on the spin-summed scale) for an orbital to be considered fully occupied. When number_of_active_alpha_electrons is None, the number of active occupied orbitals is determined automatically: occupied orbitals whose occupation deviates from nominal full occupation by more than this value are included in the active space. For restricted calculations and unrestricted calculations with shared spatial orbitals, nominal full occupation is 2.0 (using the combined alpha + beta occupations); when unrestricted spatial orbitals differ, each spin channel is evaluated with nominal full occupation 1.0 using a halved per-spin threshold. 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, correlation_balance_tolerance: float = 0.005, occupation_deviation_threshold: float = 0.02, log_orbital_info: bool = False) → None

Parameters:

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

Return type:

None

correlation_balance_tolerance: float = 0.005

degeneracy_tolerance: float = 1e-06

log_orbital_info: 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, correlation_balance_tolerance=0.005, 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.

The active space corresponds to the contiguous index window [n_inactive, n_inactive + n_active) in the incoming molecular orbital ordering; orbitals are never reordered here. When fractional (correlated) occupation numbers are present and the caller did not specify the number of active occupied orbitals, they are inferred from these occupations, and the orbital ordering is validated against the contiguous window assumption. With integer-valued (mean-field) occupation numbers, the number of active occupied orbitals must be provided explicitly. The active space is the contiguous index window

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, correlation_balance_tolerance=0.005, 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.

The active space corresponds to the contiguous index window [n_inactive, n_inactive + n_active) in the incoming molecular orbital ordering, applied equally to both spin channels; orbitals are never reordered here. When fractional (correlated) occupation numbers are present and the caller did not specify the number of active occupied orbitals, they are inferred based on whether the two spins share spatial orbitals: using the index-wise spin sum when shared, and a per-spin correlation score when distinct. With integer-valued (mean-field) occupation numbers, the number of active occupied orbitals must be provided explicitly.

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, correlation_balance_tolerance=0.005, occupation_deviation_threshold=0.02, log_orbital_info=False): The default options for the active space modification.