qrunch.chemistry.calculators.quantum_selected_configuration_interaction_calculator

Classes for calculating the ground state energy of a molecule using quantum selected configuration interaction (QSCI).

The module contains one class for using a custom quantum selected configuration interaction algorithm, CustomQuantumSelectedConfigurationInteractionGroundStateCalculator with a choice of subspace selection algorithms, and one class for the SqDRIFT algorithm, SqDRIFTGroundStateCalculator.

Classes

`QuantumSelectedConfigurationInteractionGroundStateCalculator`	Class for calculating the ground state energy using a quantum selected configuration interaction algorithm.
`SharpSqDriftGroundStateCalculator`	Ground state energy calculator using SHARP-qDRIFT.
`SqDriftGroundStateCalculator`	Class for calculating the ground state energy using an SqDRIFT algorithm.
`SqDriftOptions`	Options for SqDRIFT (SqDRIFT) calculations.

class QuantumSelectedConfigurationInteractionGroundStateCalculator

Bases: object

Class for calculating the ground state energy using a quantum selected configuration interaction algorithm.

__init__(generator: SubspaceStateGenerator, sampler: Sampler, *, shots_per_circuit: int, paired_electron_approximation: bool) → None

Initialize the QSCI ground state energy calculator.

Parameters:

generator (SubspaceStateGenerator) – Strategy producing the circuits whose samples define the diagonalization subspace.
sampler (Sampler) – Sampler used to draw computational-basis samples from each circuit.
shots_per_circuit (int) – Number of samples to draw from each circuit.
paired_electron_approximation (bool) – Whether to use the paired-electron approximation.

Return type:

None

calculate(problem: GeneralGroundStateProblem, initial_vqe_result: AdaptiveVqeGroundStateProblemCalculatorResult | None = None) → GroundStateProblemCalculatorResult

calculate(problem: ReactionPathProblem, initial_vqe_result: AdaptiveVqeReactionPathProblemCalculatorResult | None = None) → ReactionPathProblemCalculatorResult

Calculate the expectation value of the ground state energy of the given molecule/reaction.

Parameters:

problem (RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem | UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem | RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) – Ground state problem or reaction path problem to calculate energy for.
initial_vqe_result (AdaptiveVqeGroundStateProblemCalculatorResult | AdaptiveVqeReactionPathProblemCalculatorResult | None) – Optional VQE result to use as the starting point for the calculation. For a GeneralGroundStateProblem this must be an AdaptiveVqeGroundStateProblemCalculatorResult, and for a ReactionPathProblem an AdaptiveVqeReactionPathProblemCalculatorResult.

Return type:

GroundStateProblemCalculatorResult | ReactionPathProblemCalculatorResult

class SharpSqDriftGroundStateCalculator

Bases: object

Ground state energy calculator using SHARP-qDRIFT.

SHARP – subspace heat-bath adaptive reweighting of probabilities – is SqDriftGroundStateCalculator with the sampling strategy refreshed mid-run from the determinants discovered so far. The qDRIFT term-sampling distribution is rescored by an EpsteinNesbetReweighter, and the lowest eigenstate in the sampled subspace is optionally encoded as the reference state. Both share the SubspaceDiagonalizer performing the subspace diagonalization, which guarantees they are computed from the same integrals and conventions, avoids building the diagonalization machinery twice, and lets one update reuse a single cached diagonalization.

The circuit path is otherwise unchanged: the reweighting preserves the Hamiltonian one-norm and every coefficient sign, so the qDRIFT gate budget and rotation angle match the unweighted run and only the sampled terms differ.

__init__(sampler: Sampler, *, shots_per_circuit: int, update_frequency: int, iterations: int = 1, options: SqDriftOptions | None = None, maximum_blending: float = 1.0, minimum_determinant_weight: float = 0.0, state_preparation_options: FixedParticleNumberStatePrepBeamSearchOptions | None = None, time_step: float = 1.0, minimum_encoding_coefficient: float = 0.0) → None

Initialize the SHARP-qDRIFT ground state energy calculator.

Parameters:

sampler (Sampler) – Sampler used to draw computational-basis samples from each Krylov circuit.
shots_per_circuit (int) – Number of samples to draw from each circuit.
update_frequency (int) – Number of circuits sampled between successive updates of the sampling strategy.
iterations (int) – Number of passes over the Krylov sequence.
options (SqDriftOptions | None) – Optional SqDRIFT options; if not provided, defaults are used.
maximum_blending (float) – The largest weight \(\alpha \in [0, 1]\) the Epstein-Nesbet scores may be given; the weight itself is picked at every rescaling from the number of terms the circuits will draw before the next one. 0.0 reproduces SqDriftGroundStateCalculator, and 1.0 leaves the choice entirely to that criterion.
minimum_determinant_weight (float) – Determinants carrying a weight \(c_d^2\) below this are left out of the Epstein-Nesbet scores; 0.0 scores every determinant found so far.
state_preparation_options (FixedParticleNumberStatePrepBeamSearchOptions | None) – Options for the beam search re-preparing the Krylov reference state from the subspace wavefunction; None keeps the Hartree-Fock reference throughout.
time_step (float) – Reference time step \(\tau\); the evolution time for order \(k\) is \(k \tau\).
minimum_encoding_coefficient (float) – Determinants whose configuration-interaction coefficient \(|c_d|\) falls below this are left out of the state-preparation target.

Return type:

None

calculate(problem: GeneralGroundStateProblem) → GroundStateProblemCalculatorResult

calculate(problem: ReactionPathProblem) → ReactionPathProblemCalculatorResult

Calculate the expectation value of the ground state energy of the given molecule/reaction.

Parameters:: problem (RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem | UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem | RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) – Ground state problem or reaction path problem to calculate energy for.
Return type:: GroundStateProblemCalculatorResult | ReactionPathProblemCalculatorResult

class SqDriftGroundStateCalculator

Bases: object

Class for calculating the ground state energy using an SqDRIFT algorithm.

__init__(sampler: Sampler, *, shots_per_circuit: int, options: SqDriftOptions | None = None, time_step: float = 1.0, paired_electron_approximation: bool) → None

Initialize the SqDRIFT ground state energy calculator.

Parameters:

sampler (Sampler) – Sampler used to draw computational-basis samples from each Krylov circuit.
shots_per_circuit (int) – Number of samples to draw from each circuit.
options (SqDriftOptions | None) – Optional SqDRIFT options; if not provided, defaults are used.
time_step (float) – Time step \(\tau\) for the Krylov states. The evolution time for order.
paired_electron_approximation (bool) – Whether to use the paired-electron approximation.

Return type:

None

calculate(problem: GeneralGroundStateProblem) → GroundStateProblemCalculatorResult

calculate(problem: ReactionPathProblem) → ReactionPathProblemCalculatorResult

Calculate the expectation value of the ground state energy of the given molecule/reaction.

Parameters:: problem (RestrictedGroundStateProblem | LazyRestrictedGroundStateProblem | UnrestrictedGroundStateProblem | LazyUnrestrictedGroundStateProblem | RestrictedReactionPathProblem | UnrestrictedReactionPathProblem) – Ground state problem or reaction path problem to calculate energy for.
Return type:: GroundStateProblemCalculatorResult | ReactionPathProblemCalculatorResult

class SqDriftOptions

Bases: DataclassPublicAPI

Options for SqDRIFT (SqDRIFT) calculations.

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

Parameters:

subsequence_length – Number of Hamiltonian terms sampled into each qDRIFT time-evolution circuit, i.e. the length (gate count) of the qDRIFT subsequence. Larger means more precise.(default=10)
maximum_krylov_order – Largest Krylov order \(d\); circuits are generated for every order \(k = 1, \ldots, d\). Larger means more precise. (default=1)
number_of_randomizations – Number of qDRIFT circuits generated per Krylov order. More means a more precise estimate of the Krylov subspace, at the cost of more samples. (default=1)
seed – Optional seed for the qDRIFT randomized term sampling. (default = unseeded).

__init__(*, subsequence_length: int = 10, maximum_krylov_order: int = 1, number_of_randomizations: int = 1, seed: int | None = None) → None

Parameters:

subsequence_length (int)
maximum_krylov_order (int)
number_of_randomizations (int)
seed (int | None)

Return type:

None

maximum_krylov_order: int = 1

number_of_randomizations: int = 1

seed: int | None = None

subsequence_length: int = 10