qrunch.quantum.algorithms.second_quantization.quantum_selected_configuration_interaction

Quantum-selected configuration interaction (QSCI) algorithms for second quantization.

class AdaptiveQuantumSelectedConfigurationInteraction

Bases: object

Quantum-selected configuration interaction (QSCI) that steers sampling towards the determinants that matter.

Plain QSCI fixes both the Hamiltonian decomposition and the reference state for the whole run, so nothing learned from the sampled determinants feeds back into which circuits are compiled. This variant periodically updates the sampling strategy from the determinants found so far. One update currently covers two things, and further refinements – determinant pruning, orbital rotations – belong in the same step, which is why a single update_frequency governs all of them:

the Hamiltonian term weights, handed to a SecondQuantizedHamiltonianReweighter;
the reference state, re-prepared by a beam search approximating the subspace configuration-interaction wavefunction (see state_preparation_options).

Both are driven by the subspace configuration-interaction solution, so the subspace_diagonalizer given here should be the very same instance the reweighter holds: it caches its most recent solution, and one update then costs a single diagonalization rather than one per consumer.

Steering is safe: the circuits only generate determinants and the energy is an exact diagonalization in their span, so an update changes which subspace is diagonalized but can never bias the variational estimate.

__init__(generator: SubspaceStateGenerator, sampler: Sampler, subspace_diagonalizer: SubspaceDiagonalizer, reweighter: SecondQuantizedHamiltonianReweighter, *, shots_per_circuit: int, update_frequency: int, iterations: int = 1, state_preparation_options: FixedParticleNumberStatePrepBeamSearchOptions | None = None, minimum_encoding_coefficient: float = 0.0001) → None

Initialize the adaptive QSCI algorithm.

Parameters:

generator (SubspaceStateGenerator) – Strategy producing the states whose samples define the diagonalization subspace.
sampler (Sampler) – Sampler used to draw computational-basis samples from each circuit.
subspace_diagonalizer (SubspaceDiagonalizer) – Strategy diagonalizing the Hamiltonian in the sampled subspace. Pass the instance the reweighter was built on, so both share its cached solution.
reweighter (SecondQuantizedHamiltonianReweighter) – Strategy rescaling the Hamiltonian term coefficients from the determinants found so far.
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. Each update costs a subspace diagonalization and everything built on it, so a small value buys faster steering with more classical overhead.
iterations (int) – Number of iterations over the whole procedure. Each iteration exhausts the generator, so a small value is appropriate for a generator that produces many states.
state_preparation_options (FixedParticleNumberStatePrepBeamSearchOptions | None) – Options for the beam search re-preparing the reference state from the subspace wavefunction. None disables state preparation, i.e. keeps the original reference circuit for the whole run.
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

run(hamiltonian: FermionHermitianSum | PairedHardcoreBosonHermitianSum, reference_circuit: Circuit) → ExpectationValue

Sample the subspace determinants, updating the sampling strategy as they accumulate, and diagonalize.

Every update starts from the original decomposition rather than the previous one, so the reweighting does not compound over the run. An update takes effect on the very next circuit, since a state is handed the Hamiltonian and the reference circuit only when it is realized. The returned expectation value matches plain QSCI: a variational upper bound with a zero error estimate.

Parameters:

hamiltonian (FermionHermitianSum | PairedHardcoreBosonHermitianSum) – The second-quantized Hamiltonian whose ground state is targeted.
reference_circuit (Circuit) – Circuit preparing the reference state the generator builds upon.

Return type:

ExpectationValue

class IdentitySubspaceStateGenerator

Bases: SubspaceStateGenerator

Identity subspace state generator for quantum-selected configuration interaction.

This generator simply yields the reference state, whose circuit is assumed to prepare a useful state (e.g. a Hartree-Fock state or a VQE-optimized ansatz).

Note that QuantumSelectedConfigurationInteraction already samples the reference circuit for its determinants, so the state yielded here is sampled a second time; this is harmless and keeps the generator the correct way to run plain (reference-only) QSCI, including the VQE-seeded path.

__init__(*args, **kwargs)

generate() → Iterator[SubspaceState]

Yield the single state whose samples define the diagonalization subspace.

Return type:: Iterator[SubspaceState]

class KrylovSubspaceStateGenerator

Bases: SubspaceStateGenerator

Generate Krylov subspace states for quantum-selected configuration interaction.

For each Krylov order \(k = 1, \ldots, d\) (with \(d\) the maximum order) and each randomization, this generator produces a state preparing (an approximation of) the Krylov vector

\[\ket{\Psi_k} = e^{-iH k \tau} \ket{\Psi_\text{ref}} ,\]

where \(\tau\) is the time step and \(\ket{\Psi_\text{ref}}\) is prepared by the reference circuit. Each time-evolution operator \(e^{-iH k \tau}\) is compiled by the injected HamiltonianTimeEvolution strategy, once the caller realizes the state.

__init__(time_evolution: HamiltonianTimeEvolution, *, maximum_krylov_order: int = 3, time_step: float = 1.0, number_of_randomizations: int = 1) → None

Initialize the Krylov subspace state generator.

Parameters:

time_evolution (HamiltonianTimeEvolution) – Strategy compiling each time-evolution operator into a circuit.
maximum_krylov_order (int) – The largest Krylov order \(d\); states are generated for every order \(k = 1, \ldots, d\).
time_step (float) – The reference time step \(\tau\); the evolution time for order \(k\) is \(k \tau\).
number_of_randomizations (int) – Number of states generated per Krylov order.

Return type:

None

generate() → Iterator[SubspaceState]

Yield the Krylov subspace states.

Return type:: Iterator[SubspaceState]

class QuantumSelectedConfigurationInteraction

Bases: object

Quantum-selected configuration interaction (QSCI) algorithm.

QSCI approximates the ground state of a Hamiltonian by sampling computational-basis bitstrings (Slater determinants) from a set of quantum circuits and classically diagonalizing the Hamiltonian in the subspace spanned by the sampled determinants.

The states to sample are produced by a SubspaceStateGenerator and realized into circuits here; the subspace diagonalization is delegated to an injected SubspaceDiagonalizer, so alternative (e.g. more scalable) diagonalization strategies can be swapped in.

run() returns the diagonalized ground-state energy as an ExpectationValue. The energy is a variational upper bound; its error is reported as 0.0 because the classical diagonalization of the sampled subspace is deterministic.

__init__(generator: SubspaceStateGenerator, sampler: Sampler, subspace_diagonalizer: SubspaceDiagonalizer, *, shots_per_circuit: int) → None

Initialize the QSCI algorithm.

Parameters:

generator (SubspaceStateGenerator) – Strategy producing the states whose samples define the diagonalization subspace.
sampler (Sampler) – Sampler used to draw computational-basis samples from each circuit.
subspace_diagonalizer (SubspaceDiagonalizer) – Strategy diagonalizing the Hamiltonian in the sampled subspace.
shots_per_circuit (int) – Number of samples to draw from each circuit.

Return type:

None

run(hamiltonian: FermionHermitianSum | PairedHardcoreBosonHermitianSum, reference_circuit: Circuit) → ExpectationValue

Sample the subspace determinants and diagonalize the Hamiltonian in their span.

The reference determinants are always part of the diagonalization subspace. A reference circuit built only from X gates is evaluated classically rather than sampled; any other reference is sampled. The returned expectation value carries the estimated ground-state energy with a zero error estimate (see the class docstring).

The Hamiltonian is decomposed into its Hermitian terms once here, and each generated state is realized into a circuit under that decomposition. Realizing per state rather than once for the whole run is what lets adaptive variants refine the decomposition between circuits.

Parameters:

hamiltonian (FermionHermitianSum | PairedHardcoreBosonHermitianSum) – The second-quantized Hamiltonian whose ground state is targeted.
reference_circuit (Circuit) – Circuit preparing the reference state the generator builds upon.

Return type:

ExpectationValue

class SubspaceState

Bases: Protocol

Protocol for a state whose samples contribute determinants to a QSCI diagonalization subspace.

A subspace state describes which state to prepare without fixing the Hamiltonian it is prepared under or the reference state it builds upon. The caller realizes it into a circuit, so successive states of one run may be realized under different Hamiltonians and on top of different references – as adaptive strategies require, where both are refined from the determinants found so far.

__init__(*args, **kwargs)

create_circuit(hamiltonian: SecondQuantizedHamiltonian, reference_circuit: Circuit) → Circuit

Build the circuit preparing this state under the given Hamiltonian and reference.

Implementations may be randomized, in which case repeated calls return different circuits.

Parameters:

hamiltonian (SecondQuantizedHamiltonian) – The second-quantized Hamiltonian to prepare the state under.
reference_circuit (Circuit) – Circuit preparing the reference state this state builds upon.

Return type:

Circuit

class SubspaceStateGenerator

Bases: Protocol

Protocol for strategies generating the states whose samples define a diagonalization subspace.

In quantum-selected configuration interaction (QSCI), the Hamiltonian is diagonalized in the subspace spanned by Slater determinants sampled from a set of quantum circuits. A SubspaceStateGenerator decides which states are sampled; it does not compile them, so it never sees the Hamiltonian nor the reference state they build upon.

__init__(*args, **kwargs)

generate() → Iterator[SubspaceState]

Yield the states whose samples define the diagonalization subspace.

Return type:: Iterator[SubspaceState]

Modules

`creators`	Subspoace state generator sub-creator for quantum-selected configuration interaction.
`identity_subspace_generator`	Subspace state generator yielding the reference state itself, for quantum-selected configuration interaction.
`krylov_subspace_state_generator`	Krylov subspace state generator for quantum-selected configuration interaction.
`quantum_selected_configuration_interaction`	Quantum-selected configuration interaction (QSCI) algorithm.
`subspace_state_generator`	Protocols for the states defining a QSCI diagonalization subspace, and their generators.