qrunch.chemistry.problem_builders.tools.active_space_selector

Active-space selection based on natural-orbital occupation numbers.

This module identifies natural orbitals at a given geometry based on how far their occupation numbers deviate from the closed-shell ideal values (2 for fully occupied, 0 for virtual). A natural orbital with occupation number \(n_i\) is selected when

\[\min(n_i, 2 - n_i) > \tau\]

for a user-supplied threshold \(\tau\). Orbitals with anomalous occupation numbers (outside the physical range \([0, 2]\)) are always included, since they indicate strong multi-reference character.

This module operates on both restricted and unrestricted natural orbital results. For unrestricted results, this module expects spin-summed natural orbitals (identical alpha_orbitals and beta_orbitals coefficients). The total occupation per orbital is computed as \(n_i = n^\alpha_i + n^\beta_i\) (per-spin occupations need not be identical).

Functions

select_active_space(natural_orbital_results, ...)

Select natural orbitals based on their occupation-number deviation.

split_active_space_orbitals_by_occupation(...)

Split natural orbital coefficients into occupied-like and virtual-like halves.

Classes

ActiveSpaceResult

Container for active-space natural orbitals at a single geometry.
class ActiveSpaceResult

Bases: object

Container for active-space natural orbitals at a single geometry.

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

Parameters:

  • orbital_indices – Indices (into the original natural-orbital array) of orbitals that pass the occupation-number threshold. Sorted ascending.

  • orbital_coefficients – Natural-orbital coefficients of the orbitals in the AO basis. Shape (num_aos, num_orbitals).

  • orbital_occupations – Occupation numbers of the orbitals. Shape (num_orbitals,).

  • occupation_deviations – Non-negative deviations for the orbitals, useful for downstream importance ranking. Shape (num_orbitals,). For orbitals with occupation in \([0, 2]\), this is \(\min(n_i, 2 - n_i)\). For anomalous orbitals (outside \([0, 2]\)), the deviation is \(1 + |\min(n_i, 2 - n_i)|\), ensuring they rank above all well-behaved orbitals.

__init__(orbital_indices: ndarray[tuple[Any, ...], dtype[int64]], orbital_coefficients: ndarray[tuple[Any, ...], dtype[float64]], orbital_occupations: ndarray[tuple[Any, ...], dtype[float64]], occupation_deviations: ndarray[tuple[Any, ...], dtype[float64]]) → None
Parameters:

  • orbital_indices (ndarray[tuple[Any, ...], dtype[int64]])

  • orbital_coefficients (ndarray[tuple[Any, ...], dtype[float64]])

  • orbital_occupations (ndarray[tuple[Any, ...], dtype[float64]])

  • occupation_deviations (ndarray[tuple[Any, ...], dtype[float64]])

Return type:

None

property num_orbitals: int

Number of orbitals.

occupation_deviations: ndarray[tuple[Any, ...], dtype[float64]]
orbital_coefficients: ndarray[tuple[Any, ...], dtype[float64]]
orbital_indices: ndarray[tuple[Any, ...], dtype[int64]]
orbital_occupations: ndarray[tuple[Any, ...], dtype[float64]]
select_active_space(natural_orbital_results: RestrictedNaturalOrbitalResults | UnrestrictedNaturalOrbitalResults, occupation_deviation_threshold: float) → ActiveSpaceResult

Select natural orbitals based on their occupation-number deviation.

An orbital with occupation \(n_i\) qualifies when \(\min(n_i, 2 - n_i) > \tau\), where \(\tau\) is occupation_deviation_threshold. Orbitals with anomalous occupations (outside \([0, 2]\)) are always included, since they indicate strong multi-reference character.

Parameters:

  • natural_orbital_results (RestrictedNaturalOrbitalResults | UnrestrictedNaturalOrbitalResults) – Restricted or unrestricted natural-orbital results (e.g., from MP2 or CCSD).

  • occupation_deviation_threshold (float) – Minimum occupation-number deviation \(\tau\) for an orbital to be included in the active space. Must be strictly positive and strictly less than 1 (since \(\min(n_i, 2 - n_i) \leq 1\)).

Return type:

ActiveSpaceResult

split_active_space_orbitals_by_occupation(active_space: ActiveSpaceResult) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]

Split natural orbital coefficients into occupied-like and virtual-like halves.

Occupied-like orbitals have occupation \(n_i > 1\) and virtual-like orbitals have occupation \(n_i < 1\). Orbitals with exactly \(n_i = 1\) (if any) are placed in the occupied-like set.

Parameters:

active_space (ActiveSpaceResult) – Active space (from restricted or unrestricted selection).

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]