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

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().

For CAS molecules (mol_info["is_cas"] = True), the solver uses the active-space integrals directly instead of rebuilding the full molecule, and returns energy=None when the CAS Hilbert space exceeds 50 million configurations.

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 return energy=None 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
solve(hamiltonian, mol_info)[source]

Compute the FCI ground-state energy.

Parameters:

  • hamiltonian (Hamiltonian) – The molecular Hamiltonian.

  • mol_info (dict) – Molecular metadata. For the PySCF path (non-CAS molecules), must contain "geometry" (list of (atom, coord) tuples) and "basis" (str); optionally "charge" and "spin". For CAS molecules ("is_cas" is True), uses active-space integrals from the Hamiltonian directly. The "name" key is used only for logging.

Returns:

FCI energy result. energy is None when the computation was skipped (e.g. CAS too large, dense fallback exceeds max_configs).

Return type:

SolverResult

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

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

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

  1. Sample from the current NF distribution NF_k.

  2. Add unique, particle-number-valid configs to the cumulative basis.

  3. Diagonalize the projected Hamiltonian (Rayleigh–Ritz).

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

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:

  1. Trains a normalizing flow + NQS to generate configuration samples.

  2. Builds and diagonalises the projected Hamiltonian in the sampled basis (SQD).

  3. 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'
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'
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