qrunch.quantum.algorithms.second_quantization.quantum_selected_configuration_interaction.quantum_selected_configuration_interaction

Quantum-selected configuration interaction (QSCI) algorithm.

Functions

get_initial_state_int(circuit)

Extract the computational basis state prepared by the leading X gates of a circuit.

Classes

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

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 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

get_initial_state_int(circuit: Circuit) → int

Extract the computational basis state prepared by the leading X gates of a circuit.

The X gates preceding the first non-X gate map \(\ket{0\dots0}\) to a single computational basis state. That state is returned as an integer whose bit i is set when qubit i is excited. Gates from the first non-X gate onwards are ignored.

Parameters:

circuit (Circuit) – Circuit with potential leading X gates.

Return type:

int