Solvers

The solvers subpackage provides high-level solver interfaces that accept a Hamiltonian and return a standardized SolverResult.

Base Classes

class qvartools.solvers.solver.SolverResult(diag_dim, wall_time, method, converged, energy=None, metadata=<factory>)[source]

Bases: object

Immutable container for solver output.

Parameters:

energy (float or None) – Ground-state energy estimate in Hartree, or None when the solver fails or skips the computation.
diag_dim (int) – Dimension of the diagonalisation subspace (number of basis configurations used).
wall_time (float) – Wall-clock time in seconds for the full solve.
method (str) – Human-readable solver method name (e.g. "FCI", "SQD").
converged (bool) – Whether the solver converged to the requested tolerance.
metadata (dict) – Additional method-specific information (e.g. iteration history, basis size per step, training metrics).

energy

Type:: float or None

diag_dim

Type:: int

wall_time

Type:: float

method

Type:: str

converged

Type:: bool

metadata

Type:: dict

Examples

>>> result = SolverResult(
...     diag_dim=100, wall_time=1.5, method="SQD", converged=True,
...     energy=-1.137,
... )
>>> result.energy
-1.137

Attributes:

energy

Parameters:

diag_dim (int)
wall_time (float)
method (str)
converged (bool)
energy (float | None)
metadata (Dict[str, Any])

diag_dim: int

wall_time: float

method: str

converged: bool

energy: float | None = None

metadata: Dict[str, Any]

class qvartools.solvers.solver.Solver[source]

Bases: ABC

Abstract base class for all quantum chemistry solvers.

Every subclass must implement solve(), which takes a Hamiltonian and a molecular information dictionary and returns a SolverResult.

The mol_info dictionary is expected to contain at least:

"name" : str – molecule name.
"n_qubits" : int – number of qubits (spin-orbitals).
"basis" : str – Gaussian basis set.
"geometry" : list – atomic geometry.
"charge" : int – net molecular charge.
"spin" : int – spin multiplicity minus one (2S).

Methods

solve(hamiltonian, mol_info)

Compute the ground-state energy.

abstractmethod solve(hamiltonian, mol_info)[source]

Compute the ground-state energy.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian to diagonalise.
mol_info (dict) – Molecular metadata dictionary with keys name, n_qubits, basis, geometry, charge, spin.

Returns:

Result containing energy, timing, and convergence information.

Return type:

SolverResult

Reference Solvers

class qvartools.solvers.reference.fci.FCISolver(max_configs=500000)[source]

Bases: Solver

Full configuration interaction solver.

Attempts to use PySCF’s FCI module for molecular Hamiltonians. When PySCF is unavailable or the Hamiltonian is not molecular, falls back to dense exact diagonalisation via exact_ground_state().

Parameters:: max_configs (int, optional) – Maximum number of configurations (Hilbert-space dimension) for which dense diagonalisation is attempted (default 500_000). Systems exceeding this limit raise a RuntimeError when PySCF is unavailable.

max_configs

Configuration limit for dense fallback.

Type:: int

Examples

>>> solver = FCISolver()
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.energy
-1.1373060356

Methods

solve(hamiltonian, mol_info)

Compute the FCI ground-state energy.

solve(hamiltonian, mol_info)[source]

Compute the FCI ground-state energy.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian.
mol_info (dict) – Molecular metadata (must contain "name").

Returns:

FCI energy result.

Return type:

SolverResult

Raises:

RuntimeError – If the Hilbert-space dimension exceeds max_configs and PySCF is not available.

class qvartools.solvers.reference.ccsd.CCSDSolver[source]

Bases: Solver

Coupled cluster singles and doubles solver via PySCF.

Requires PySCF to be installed. The solver runs RHF followed by CCSD on the molecular geometry specified in mol_info.

Examples

>>> solver = CCSDSolver()
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.method
'CCSD'

Methods

solve(hamiltonian, mol_info)

Compute the CCSD ground-state energy.

solve(hamiltonian, mol_info)[source]

Compute the CCSD ground-state energy.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian (used for metadata; PySCF recomputes integrals internally).
mol_info (dict) – Molecular metadata. Must contain "geometry" and "basis".

Returns:

CCSD energy result.

Return type:

SolverResult

Raises:

ImportError – If PySCF is not installed.
RuntimeError – If the RHF or CCSD calculation does not converge.

Subspace Solvers

class qvartools.solvers.subspace.sqd.SQDSolver(n_samples=5000, flow_type='particle_conserving', training_config=None, device='cpu')[source]

Bases: Solver

Sample-based quantum diagonalization solver.

Trains a normalizing flow to generate computational-basis configurations, builds a projected Hamiltonian in the sampled basis, and diagonalises it.

Parameters:

n_samples (int, optional) – Number of configuration samples to draw after training (default 5000).
flow_type (str, optional) – Type of normalizing flow: "particle_conserving" or "discrete" (default "particle_conserving").
training_config (dict or None, optional) – Override training hyperparameters. Keys are forwarded to PhysicsGuidedConfig. If None, sensible defaults are used.
device (str, optional) – Torch device for computation (default "cpu").

n_samples

Number of post-training samples.

Type:: int

flow_type

Flow architecture identifier.

Type:: str

training_config

Merged training hyperparameters.

Type:: dict

device

Torch device string.

Type:: str

Examples

>>> solver = SQDSolver(n_samples=3000)
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.method
'SQD'

Methods

solve(hamiltonian, mol_info)

Run the SQD pipeline.

solve(hamiltonian, mol_info)[source]

Run the SQD pipeline.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian.
mol_info (dict) – Molecular metadata. Must contain "n_qubits".

Returns:

SQD energy result with training history in metadata.

Return type:

SolverResult

class qvartools.solvers.subspace.cipsi.CIPSISolver(max_iterations=30, max_basis_size=10000, convergence_threshold=1e-05, expansion_size=500)[source]

Bases: Solver

Selected CI solver using the CIPSI perturbative selection scheme.

Parameters:

max_iterations (int) – Maximum number of expansion iterations.
max_basis_size (int) – Hard cap on basis dimension.
convergence_threshold (float) – Energy change threshold (Ha) for early stopping.
expansion_size (int) – Number of candidates added per iteration.

Methods

solve(hamiltonian, mol_info)

Run the CIPSI selected-CI algorithm.

solve(hamiltonian, mol_info)[source]

Run the CIPSI selected-CI algorithm.

Parameters:

hamiltonian (MolecularHamiltonian) – Hamiltonian exposing get_hf_state(), matrix_elements_fast(), get_connections(), diagonal_element(), and diagonal_elements_batch().
mol_info (dict) – Molecular metadata (unused, kept for API compatibility).

Return type:

SolverResult

Krylov Solvers

class qvartools.solvers.krylov.skqd.SKQDSolver(n_samples=5000, skqd_config=None, training_config=None, device='cpu')[source]

Bases: Solver

Sample-based Krylov quantum diagonalization solver.

Trains a normalizing flow, samples an initial basis, and runs Krylov-based diagonalisation to obtain the ground-state energy.

Parameters:

n_samples (int, optional) – Number of configuration samples from the trained flow (default 5000).
skqd_config (dict or None, optional) – Override SKQD hyperparameters forwarded to SKQDConfig.
training_config (dict or None, optional) – Override training hyperparameters forwarded to PhysicsGuidedConfig.
device (str, optional) – Torch device (default "cpu").

n_samples

Post-training sample count.

Type:: int

skqd_config

Merged SKQD hyperparameters.

Type:: dict

training_config

Merged training hyperparameters.

Type:: dict

device

Torch device string.

Type:: str

Examples

>>> solver = SKQDSolver(n_samples=3000)
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.method
'SKQD'

Methods

solve(hamiltonian, mol_info)

Run the SKQD pipeline.

solve(hamiltonian, mol_info)[source]

Run the SKQD pipeline.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian.
mol_info (dict) – Molecular metadata. Must contain "n_qubits".

Returns:

SKQD energy result with Krylov history in metadata.

Return type:

SolverResult

class qvartools.solvers.krylov.nf_skqd.NFSKQDSolver(flow_model, config=None)[source]

Bases: Solver

NF-SKQD: faithful NF analog of quantum SKQD with cumulative basis.

Each Krylov power k:

Sample from the current NF distribution NF_k.
Add unique, particle-number-valid configs to the cumulative basis.
Diagonalize the projected Hamiltonian (Rayleigh–Ritz).
Partially update the NF toward the ground-state eigenvector.

Parameters:

flow_model (object) – A normalizing-flow model exposing sample(), log_prob(), and parameters() methods.
config (NFSKQDConfig, optional) – Solver hyper-parameters. Uses defaults when omitted.

Methods

solve(hamiltonian, mol_info)

Run NF-SKQD and return the ground-state energy estimate.

solve(hamiltonian, mol_info)[source]

Run NF-SKQD and return the ground-state energy estimate.

Parameters:

hamiltonian (MolecularHamiltonian) – Hamiltonian with get_hf_state, matrix_elements_fast, diagonal_element, and diagonal_elements_batch methods.
mol_info (dict) – Molecular metadata (unused by this solver, kept for API compat).

Return type:

SolverResult

Iterative Solvers

class qvartools.solvers.iterative.iterative_sqd.IterativeNFSQDSolver(n_iterations=5, n_samples=2000, training_config=None, convergence_tol=1e-06, device='cpu')[source]

Bases: Solver

Iterative normalizing-flow SQD with eigenvector feedback.

At each iteration the solver:

Trains a normalizing flow + NQS to generate configuration samples.
Builds and diagonalises the projected Hamiltonian in the sampled basis (SQD).
Uses the ground-state eigenvector coefficients to bias the NQS log-amplitudes for the next iteration.

The feedback loop progressively focuses sampling on the most important configurations for the ground state.

Parameters:

n_iterations (int, optional) – Number of outer SQD iterations (default 5).
n_samples (int, optional) – Samples per iteration from the trained flow (default 2000).
training_config (dict or None, optional) – Override training hyperparameters forwarded to PhysicsGuidedConfig.
convergence_tol (float, optional) – Stop iterating when the energy change between consecutive iterations is below this threshold (default 1e-6).
device (str, optional) – Torch device (default "cpu").

n_iterations

Type:: int

n_samples

Type:: int

training_config

Type:: dict

convergence_tol

Type:: float

device

Type:: str

Examples

>>> solver = IterativeNFSQDSolver(n_iterations=3)
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.method
'IterativeNFSQD'

Methods

solve(hamiltonian, mol_info)

Run the iterative NF-SQD pipeline.

solve(hamiltonian, mol_info)[source]

Run the iterative NF-SQD pipeline.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian.
mol_info (dict) – Molecular metadata. Must contain "n_qubits".

Returns:

Best energy across iterations with full history in metadata.

Return type:

SolverResult

class qvartools.solvers.iterative.iterative_skqd.IterativeNFSKQDSolver(n_iterations=5, n_samples=2000, training_config=None, skqd_config=None, convergence_tol=1e-06, device='cpu')[source]

Bases: Solver

Iterative normalizing-flow SKQD with eigenvector feedback.

Same iterative feedback loop as IterativeNFSQDSolver, but uses Krylov subspace expansion (SKQD) instead of direct projected diagonalisation at each iteration.

Parameters:

n_iterations (int, optional) – Number of outer iterations (default 5).
n_samples (int, optional) – Samples per iteration (default 2000).
training_config (dict or None, optional) – Override training hyperparameters.
skqd_config (dict or None, optional) – Override SKQD hyperparameters forwarded to SKQDConfig.
convergence_tol (float, optional) – Energy convergence threshold (default 1e-6).
device (str, optional) – Torch device (default "cpu").

n_iterations

Type:: int

n_samples

Type:: int

training_config

Type:: dict

skqd_config

Type:: dict

convergence_tol

Type:: float

device

Type:: str

Examples

>>> solver = IterativeNFSKQDSolver(n_iterations=3)
>>> result = solver.solve(hamiltonian, mol_info)
>>> result.method
'IterativeNFSKQD'

Methods

solve(hamiltonian, mol_info)

Run the iterative NF-SKQD pipeline.

solve(hamiltonian, mol_info)[source]

Run the iterative NF-SKQD pipeline.

Parameters:

hamiltonian (Hamiltonian) – The molecular Hamiltonian.
mol_info (dict) – Molecular metadata. Must contain "n_qubits".

Returns:

Best energy across iterations with full history in metadata.

Return type:

SolverResult