qrunch.chemistry.problem_builders.reaction_path_problem.consistent_active_space_procedure

Consistent active-space procedure for use in the SimpleReactionPathProblemBuilder.

Classes

ConsistentActiveSpaceOptions	Options controlling the consistent active-space selection for a reaction path.
ConsistentActiveSpaceProcedure	Procedure that determines and applies a consistent active space across multiple configurations.
PreActiveSpaceRestrictedResult	Intermediate result from building a restricted problem up to the active space modifier.
PreActiveSpaceUnrestrictedResult	Intermediate result from building an unrestricted problem up to the active space modifier.

class ConsistentActiveSpaceOptions

Bases: DataclassPublicAPI

Options controlling the consistent active-space selection for a reaction path.

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

Parameters:

• occupation_deviation_threshold – Used in Pass 1 to pick which correlated natural orbitals become active-space candidates. A natural orbital with occupation \(n_i\) becomes a candidate only when \(\min(n_i,\,2 - n_i)\) exceeds this threshold, i.e. when it is neither cleanly doubly occupied nor cleanly empty. Raising the threshold keeps only the most strongly partially occupied orbitals (smaller candidate set, smaller active space); lowering it lets weakly correlated orbitals through as well. (default=0.02)

• population_contribution_threshold – Used in Pass 1, at the end of the per-orbital fingerprinting step, to decide which atom-shell labels (e.g. C 2p, N 2p) are kept for a candidate orbital. Each candidate’s contributions are normalized so they sum to \(1\) across shells, so this threshold is effectively the minimum fraction of the candidate’s density that must sit on a given atom-shell for that label to survive. Raising the threshold gives sparser fingerprints and hence a smaller master label set and active space; lowering it keeps weakly contributing shells, which is useful when the chemically important density is spread across many atoms. (default=0.1)

• overlap_contribution_threshold – Used in Pass 1, inside the fingerprinting step, to decide which localized bonding orbitals (IBOs) are allowed to describe each candidate orbital. Only IBOs whose squared overlap with the candidate exceeds this threshold contribute to that candidate’s atom-shell fingerprint; the rest are discarded to keep numerical noise from distant IBOs out of the aggregate. Raising the threshold restricts each candidate to its most dominant IBO partners and can produce empty fingerprints for strongly delocalized orbitals; lowering it lets weakly overlapping IBOs contribute, which is useful for delocalized \(\pi\) systems where no single IBO dominates. (default=0.1)

• avas_threshold – Used in Pass 2 by AVAS to decide which molecular orbitals become active. AVAS computes, for every molecular orbital, its squared projection onto the target atom-shell subspace (the master label set built in Pass 1); orbitals whose projection exceeds this threshold are declared active. Lowering the threshold enlarges the active space and reduces the risk of AVAS picking different numbers of active orbitals at different configurations; raising it tightens the selection. (default=0.2)

• reference_basis –

  Atomic reference basis that defines both the IAOs used for fingerprinting in Pass 1 and the target AO space AVAS projects onto in Pass 2. The default "ano-rcc-mb" is a minimal basis, so the reference space is the valence only. Using a larger basis (the next rungs are "ano-rcc-vdzp" and "ano-rcc-vtzp") adds correlating shells such as \(3s\), \(3p\) and \(3d\) to the reference, which the fingerprints can then select and AVAS can then project onto. The cost is a larger active space and a more expensive IAO construction, so raise it only when the valence-only space is too small to be useful.

  Prefer this family over PySCF’s "minao". The two are equivalent for H-Kr, where they carry the same shells and span almost the same subspace, but "minao" is built from cc-pVTZ-PP from yttrium onwards, so it supplies only pseudopotential-valence shells. Since this codebase is all-electron throughout, such a reference is smaller than the occupied space it is supposed to span, and the IAOs it produces are meaningless. "minao" is also undefined for K, Rb, Sr, Cs, Ba and La. (default: ano-rcc-mb)

• localize_virtual_ibos – Controls how virtual (empty) orbitals are fingerprinted in Pass 1. When True (recommended) the virtual orbitals are first localized into virtual IBOs and treated in the same way as occupied orbitals, giving cleaner atom-shell assignments. When False, virtual-like candidates fall back to a direct atomic-shell population analysis, which is faster but usually gives noisier fingerprints. (default=True)

• avas_with_iao – Forwards the with_iao flag to PySCF’s AVAS in Pass 2. When True, AVAS performs its own IAO localisation internally as part of the projection step. This is normally unnecessary here because the master label set has already been produced from an external IBO-based fingerprinting, so leaving this off is usually correct. Enable it only if you observe AVAS behaving oddly on the natural orbitals. (default=False)

• conjugated_orbitals_only – Enables an extra filter step at the end of Pass 1 that keeps only candidate orbitals whose fingerprints consist exclusively of \(np\) shells on non-hydrogen atoms (\(2p\), \(3p\), …). Candidates with any \(s\)-shell mixing, hydrogen character, or core-shell character are dropped – these are the signatures of \(\sigma\) bonds, sp²/sp³ lone pairs and X-H bonds, which are not part of a \(\pi\) system. Use this for systems whose chemically relevant active space is the \(\pi\) subsystem of one or more aromatic or conjugated fragments (for example, \(\pi\)-stacked nucleobases), where the occupation-deviation criterion alone tends to sweep in the whole correlated valence and produce a saturated master label set. (default=False)

• use_unrestricted_natural_orbitals – When True, the restricted builder pathway obtains natural orbitals by calling solve_unrestricted on the natural-orbital calculator instead of solve_restricted. This allows options that only take effect during UHF/UMP2 – notably break_spin_symmetry and stability_analysis on the MP2 (or CCSD) calculator – to influence the natural occupation numbers used to pick active-space candidates for a restricted problem. The unrestricted result is then folded into a synthetic restricted natural-orbital result following the same spin-summed convention used elsewhere in this codebase: the alpha natural orbitals are taken as the representative MO coefficients, and the double occupations are set to alpha_occupations + beta_occupations. This is the standard approach for building an RHF-like active space from a broken-symmetry unrestricted reference and typically gives more physical fractional occupations for singlet biradicals and other strongly correlated closed-shell systems. Has no effect on the unrestricted builder pathway, which always calls solve_unrestricted and therefore honors these options unconditionally. (default=False)

• max_active_spatial_orbitals – Optional hard cap on the number of active spatial orbitals produced per configuration. If left as None, AVAS is run once at avas_threshold and the resulting active space is used as-is. If a positive integer is given, the builder first runs AVAS at avas_threshold and, if any configuration exceeds the cap, searches for a slightly stricter AVAS threshold (by bisection, towards \(1\)) that keeps the largest active space across configurations at or below the cap, then re-runs AVAS at that single threshold everywhere so the active space stays consistent along the reaction path. Useful for large systems with diffuse correlation where you want to bound the downstream cost. If the cap cannot be met even at very tight AVAS thresholds, a warning is logged and the tightest available result is returned; in that case, consider raising occupation_deviation_threshold to shrink the candidate set instead. Mutually exclusive with num_active_spatial_orbitals. (default=None)

• num_active_spatial_orbitals –

  Optional request for an active space of exactly this many spatial orbitals at every configuration along the path. Mutually exclusive with max_active_spatial_orbitals: use that one when an upper bound is enough, and this one when you need a specific size, for example to compare several reaction paths on an equal footing or to fit a fixed qubit budget.

  The builder adjusts the other options for you until it reaches the requested size, starting from the values you configured, so this is normally the only option you need to set. avas_threshold is ignored while this is active, because the builder determines it itself.

  The size can only change in whole orbitals and sometimes jumps past the requested number, so an exact hit is not guaranteed. In that case a warning reports the size that was used instead, which is the closest one that is still the same at every configuration. (default=None)

__init__(*, occupation_deviation_threshold: float = 0.02, population_contribution_threshold: float = 0.1, overlap_contribution_threshold: float = 0.1, avas_threshold: float = 0.2, reference_basis: str | BasisSet = BasisSet.ANO_RCC_MB, localize_virtual_ibos: bool = True, avas_with_iao: bool = False, conjugated_orbitals_only: bool = False, use_unrestricted_natural_orbitals: bool = False, max_active_spatial_orbitals: int | None = None, num_active_spatial_orbitals: int | None = None) → None

Parameters:

• occupation_deviation_threshold (float)

• population_contribution_threshold (float)

• overlap_contribution_threshold (float)

• avas_threshold (float)

• reference_basis (str | BasisSet)

• localize_virtual_ibos (bool)

• avas_with_iao (bool)

• conjugated_orbitals_only (bool)

• use_unrestricted_natural_orbitals (bool)

• max_active_spatial_orbitals (int | None)

• num_active_spatial_orbitals (int | None)

Return type:

None

avas_threshold: float = 0.2

avas_with_iao: bool = False

conjugated_orbitals_only: bool = False

localize_virtual_ibos: bool = True

max_active_spatial_orbitals: int | None = None

num_active_spatial_orbitals: int | None = None

occupation_deviation_threshold: float = 0.02

overlap_contribution_threshold: float = 0.1

population_contribution_threshold: float = 0.1

reference_basis: str | BasisSet = 'ano-rcc-mb'

use_unrestricted_natural_orbitals: bool = False

class ConsistentActiveSpaceProcedure

Bases: object

Procedure that determines and applies a consistent active space across multiple configurations.

This procedure implements the same two-pass workflow as ActiveSpaceReactionPathProblemBuilder but is designed to be composed into the SimpleReactionPathProblemBuilder.

The procedure reads the molecular orbitals and their occupations directly from the pre-active-space problems. This means the underlying ground state problem builder must be configured with an appropriate MO calculator (e.g. MP2 or CCSD natural orbitals) and the resulting problems must carry molecular_orbitals and molecular_orbital_occupations.

Pass 1 — Discovering which atomic shells matter.

For each configuration, candidate orbitals are identified by their fractional occupation deviation, then fingerprinted using IBO overlap to determine which atom-shell labels they belong to. The union of all per-configuration fingerprints forms the master label set.

Pass 2 — Building a consistent active space at every configuration.

For each configuration, AVAS is run on the molecular orbitals using the master label set. The AVAS-reordered MOs are used to rebuild the ground state problem, and the active space modifier (with AVAS-determined parameters) is applied.

Sizing the active space.

By default the active space is whatever AVAS selects at avas_threshold. max_active_spatial_orbitals bounds it from above by tightening that single threshold, while num_active_spatial_orbitals asks for one exact size and therefore also varies the Pass 1 parameters that reshape the master label set. Both keep a single parameter set across all configurations, so the active space stays consistent along the path.

__init__(options: ConsistentActiveSpaceOptions | None = None) → None

Initialize the consistent active-space procedure.

Parameters:

options (ConsistentActiveSpaceOptions | None) – Options controlling the active-space selection workflow.

Return type:

None

apply_restricted(pre_results: list[PreActiveSpaceRestrictedResult]) → list[RestrictedGroundStateProblem]

Apply the consistent active-space procedure to restricted pre-active-space results.

Runs the two-pass workflow (fingerprinting + AVAS) across all configurations and returns problems with the active space modifier applied. The returned problems are ready for post-active-space modifiers.

Parameters:

pre_results (list[PreActiveSpaceRestrictedResult]) – Pre-active-space results for each configuration in the reaction path.

Return type:

list[RestrictedGroundStateProblem]

apply_unrestricted(pre_results: list[PreActiveSpaceUnrestrictedResult]) → list[UnrestrictedGroundStateProblem]

Apply the consistent active-space procedure to unrestricted pre-active-space results.

Runs the two-pass workflow (fingerprinting + AVAS) across all configurations and returns problems with the active space modifier applied. The returned problems are ready for post-active-space modifiers.

Parameters:

pre_results (list[PreActiveSpaceUnrestrictedResult]) – Pre-active-space results for each configuration in the reaction path.

Return type:

list[UnrestrictedGroundStateProblem]

class PreActiveSpaceRestrictedResult

Bases: object

Intermediate result from building a restricted problem up to the active space modifier.

This dataclass holds the ground state problem built with all modifiers applied before the active space modifier, along with the molecular configuration.

Parameters:

• problem – The restricted ground state problem with pre-active-space modifiers applied.

• molecular_configuration – The molecular configuration for this geometry.

__init__(problem: RestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → None

Parameters:

• problem (RestrictedGroundStateProblem)

• molecular_configuration (MolecularConfiguration)

Return type:

None

molecular_configuration: MolecularConfiguration

problem: RestrictedGroundStateProblem

class PreActiveSpaceUnrestrictedResult

Bases: object

Intermediate result from building an unrestricted problem up to the active space modifier.

This dataclass holds the ground state problem built with all modifiers applied before the active space modifier, along with the molecular configuration.

Parameters:

• problem – The unrestricted ground state problem with pre-active-space modifiers applied.

• molecular_configuration – The molecular configuration for this geometry.

__init__(problem: UnrestrictedGroundStateProblem, molecular_configuration: MolecularConfiguration) → None

Parameters:

• problem (UnrestrictedGroundStateProblem)

• molecular_configuration (MolecularConfiguration)

Return type:

None

molecular_configuration: MolecularConfiguration

problem: UnrestrictedGroundStateProblem