qrunch.chemistry.ground_state_problem.calculators.trim_configuration_interaction_calculators

Ground state energy calculator using Trimmed Configuration Interaction (TrimCI).

Classes

`TrimCIGroundStateProblemCalculator`	Ground state calculator using Trimmed Configuration Interaction (TrimCI).
`TrimCIGroundStateProblemCalculatorResult`	Result dataclass returned by the TrimCI ground state calculator.
`TrimCIOptions`	Options for Trimmed Configuration Interaction (TrimCI) calculations.

class TrimCIGroundStateProblemCalculator

Bases: object

Ground state calculator using Trimmed Configuration Interaction (TrimCI).

The algorithm is described in arxiv.org/abs/2511.14734. The algorithm iteratively alternates between two phases:

Expansion – all single and double excitations of the current core determinants are generated to form a candidate pool.
Trimming – the pool is partitioned into random groups, each group is diagonalized and the most important determinants (by CI coefficient magnitude) are retained. A final global diagonalization selects the new core set.

__init__(options: TrimCIOptions | None = None, *, paired_electron_approximation: bool = False) → None

Initialize the TrimCI calculator.

Parameters:

options (TrimCIOptions | None) – Calculation options. None uses default values.
paired_electron_approximation (bool) – If True, only paired alpha/beta excitations are used during expansion. This restricts the CI space to determinants reachable via simultaneous identical excitations in both spin channels.

Return type:

None

calculate(ground_state_problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem) → TrimCIGroundStateProblemCalculatorResult

Run the TrimCI calculation.

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

class TrimCIGroundStateProblemCalculatorResult

Bases: GroundStateProblemCalculatorResult

Result dataclass returned by the TrimCI ground state calculator.

Extends the base result with per-iteration energy tracking.

Parameters:

initial_active_electrons_energy – Initial (Hartree-Fock) active electrons energy.
non_active_electrons_energy – Energy of non-active electrons.
nuclear_repulsion – Nuclear repulsion energy.
second_order_correction – Second-order energy correction.
uncorrected_active_electrons_energy – Final uncorrected active electrons energy.
active_electrons_energy_per_macro_iteration – Active electrons energy at each TrimCI iteration.

__init__(initial_active_electrons_energy: float, non_active_electrons_energy: float, nuclear_repulsion: float, second_order_correction: ExpectationValue, uncorrected_active_electrons_energy: ExpectationValue, active_electrons_energy_per_macro_iteration: ListOfExpectationValues) → None

Parameters:

initial_active_electrons_energy (float)
non_active_electrons_energy (float)
nuclear_repulsion (float)
second_order_correction (ExpectationValue)
uncorrected_active_electrons_energy (ExpectationValue)
active_electrons_energy_per_macro_iteration (ListOfExpectationValues)

Return type:

None

property active_electrons_correlation_energy: ExpectationValue

Correlation energy of the active electrons.

This is the difference between the active electrons energy and the initial (Hartree-Fock) active electrons energy.

property active_electrons_energy: ExpectationValue

Energy of the active electrons.

This does not include nuclear repulsion or the energy of frozen electrons from, e.g., active space or projective embedding.

It may also include a second-order correction, if applicable.

active_electrons_energy_per_macro_iteration: ListOfExpectationValues

property electronic_energy: ExpectationValue

Energy of all electrons.

This is the total energy minus nuclear repulsion.

initial_active_electrons_energy: float

property initial_electronic_energy: ExpectationValue: Initial electronic energy of all electrons and nuclear repulsion.

property initial_total_energy: ExpectationValue: Initial total energy of all electrons and nuclear repulsion.

non_active_electrons_energy: float

nuclear_repulsion: float

second_order_correction: ExpectationValue

property total_energy: ExpectationValue: Total energy of all electrons and nuclear repulsion.

property total_energy_per_iteration: ListOfExpectationValues: Total energy at each TrimCI iteration.

property total_energy_per_iteration_with_initial_energy: ListOfExpectationValues: Total energy at each iteration, starting with the initial (HF) energy.

uncorrected_active_electrons_energy: ExpectationValue

class TrimCIOptions

Bases: DataclassPublicAPI

Options for Trimmed Configuration Interaction (TrimCI) calculations.

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

Parameters:

max_number_of_iterations – Maximum number of expand/trim iterations. (default=1_000_000)
initial_number_of_determinants – Size of the initial determinant set. (default=10)
determinant_increase_ratio – Multiplicative growth factor for the core each iteration. (default=1.02)
final_number_of_determinants – Maximum number of determinants retained after trimming. The algorithm stops when the core reaches this size. (default=1000)
pool_determinants_ratio – Maximum pool size as a multiple of the current core size. (default=20.0)
number_of_groups – Number of random groups for first-level trimming. (default=10)
local_trim_keep_ratio – Fraction of determinants kept per group in first-level trimming. (default=0.1)
seed – Random seed for reproducibility. (default=42)

__init__(*, max_number_of_iterations: int = 1000000, initial_number_of_determinants: int = 10, determinant_increase_ratio: float = 1.02, final_number_of_determinants: int = 1000, pool_determinants_ratio: float = 20.0, number_of_groups: int = 10, local_trim_keep_ratio: float = 0.1, seed: int = 42) → None

Parameters:

max_number_of_iterations (int)
initial_number_of_determinants (int)
determinant_increase_ratio (float)
final_number_of_determinants (int)
pool_determinants_ratio (float)
number_of_groups (int)
local_trim_keep_ratio (float)
seed (int)

Return type:

None

determinant_increase_ratio: float = 1.02

final_number_of_determinants: int = 1000

initial_number_of_determinants: int = 10

local_trim_keep_ratio: float = 0.1

max_number_of_iterations: int = 1000000

number_of_groups: int = 10

pool_determinants_ratio: float = 20.0

seed: int = 42