Package Overview

qvartools is organized as a collection of loosely coupled subpackages, each handling one stage of the quantum variational pipeline. This design allows researchers to use individual components independently or combine them into end-to-end workflows.

Architecture

The package follows a bottom-up dependency structure:

               pipeline.py
              /    |    \    \
             /     |     \    \
       flows/   krylov/   \    molecules/
      /  |  \     |   \    \       |
     /   |   \    |    \    \      hamiltonians/
nqs/  hamiltonians/ diag/
     \           |       /
      \          |      /
       \    _utils/    /
        \      |     /
         [torch, numpy, scipy]

Key rules:

  • hamiltonians/ depends only on torch, numpy, scipy

  • nqs/ depends only on torch

  • flows/ depends on hamiltonians/ and nqs/

  • krylov/ depends on hamiltonians/ and diag/

  • solvers/ is a leaf consumer – nothing depends on it

  • pipeline.py ties everything together at the top

Subpackages

hamiltonians

Hamiltonian operators for molecular and spin systems. Provides the abstract Hamiltonian base class and concrete implementations:

  • MolecularHamiltonian – second-quantized molecular Hamiltonian via Jordan-Wigner mapping with Slater-Condon rules for matrix elements

  • HeisenbergHamiltonian – anisotropic Heisenberg (XYZ) model

  • TransverseFieldIsing – transverse-field Ising model

  • PauliString – individual Pauli operator strings

nqs

Neural quantum state architectures that parameterize the many-body wavefunction:

  • DenseNQS – fully connected feedforward network

  • SignedDenseNQS – amplitude + sign network with explicit sign structure

  • ComplexNQS – shared feature extractor for amplitude and phase

  • RBMQuantumState – restricted Boltzmann machine (Carleo & Troyer, 2017)

  • AutoregressiveTransformer – autoregressive transformer with alpha/beta spin channels

flows

Normalizing flows for configuration sampling:

  • DiscreteFlowSampler – RealNVP flow mapping continuous latent variables to discrete binary configurations

  • ParticleConservingFlowSampler – flow with exact particle-number conservation via differentiable top-k (Gumbel-Softmax)

  • PhysicsGuidedFlowTrainer – joint flow + NQS training with mixed objectives (teacher KL, variational energy, entropy regularization)

krylov

Krylov subspace methods:

  • ClassicalKrylovDiagonalization – core SKQD solver constructing Krylov states via time evolution

  • FlowGuidedKrylovDiag – SKQD seeded with normalizing-flow basis

  • ResidualBasedExpander – iterative basis expansion via residual analysis

  • SelectedCIExpander – CIPSI-style perturbative basis enrichment

diag

Subspace diagonalization utilities:

  • DiversitySelector – excitation-rank-aware diversity selection

  • ProjectedHamiltonianBuilder – hash-based projected Hamiltonian construction

  • DavidsonSolver – iterative Davidson eigensolver

  • Generalized eigenvalue solvers with GPU acceleration

solvers

High-level solver interfaces returning a common SolverResult:

  • FCISolver – full configuration interaction (exact)

  • CCSDSolver – coupled cluster singles and doubles (PySCF)

  • SQDSolver – sample-based quantum diagonalization

  • SKQDSolver – sample-based Krylov quantum diagonalization

  • IterativeNFSQDSolver – iterative NF-SQD with eigenvector feedback

  • IterativeNFSKQDSolver – iterative NF-SKQD with eigenvector feedback

molecules

Molecular system registry with pre-configured benchmarks:

  • 8 molecules from H2 (4 qubits) to C2H4 (28 qubits)

  • Automatic integral computation via PySCF

  • Factory function get_molecule() for easy access

Design Principles

  1. Immutable configuration. All config dataclasses are frozen. Adapted copies are created via dataclasses.replace().

  2. Abstract base classes. Hamiltonian, NeuralQuantumState, Solver, and Sampler define the contracts that concrete implementations must satisfy.

  3. Consistent return types. Solvers return SolverResult, samplers return SamplerResult, and the pipeline returns a dictionary with documented keys.

  4. No upward dependencies. Lower-level modules never import from higher-level ones.