qrunch.chemistry.calculators.trim_configuration_interaction_calculator

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

Classes

`TrimCIOptions`	Options for Trimmed Configuration Interaction (TrimCI) calculations.
`TrimConfigurationInteractionGroundStateCalculator`	Ground state calculator using Trimmed Configuration Interaction (TrimCI).

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

class TrimConfigurationInteractionGroundStateCalculator

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(problem: GeneralGroundStateProblem) → TrimCIGroundStateProblemCalculatorResult

calculate(problem: ReactionPathProblem) → ReactionPathProblemCalculatorResult

Solve the trimmed configuration interaction (TrimCI) calculation.

Note that the problem may restrict the orbital space.

The Hamiltonian for all geometries is assumed to be real.

Parameters:: problem (RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem | UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem | RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) – The problem to calculate the ground state energy / energies for.
Return type:: TrimCIGroundStateProblemCalculatorResult | ReactionPathProblemCalculatorResult