qvartools: Quantum Variational Toolkit

qvartools is a unified Python package for quantum variational methods applied to molecular ground-state energy estimation. It consolidates normalizing-flow-guided neural quantum states (NF-NQS), sample-based quantum diagonalization (SQD), and sample-based Krylov quantum diagonalization (SKQD) into reusable, well-scoped modules.

Key capabilities:

• Molecular and spin Hamiltonians with efficient matrix-element computation

• Neural quantum state architectures (dense, complex, RBM, transformer)

• Normalizing flows with particle-number conservation

• Physics-guided mixed-objective training

• Sample-based Krylov diagonalization (SKQD) with residual expansion

• Unified solver interface (FCI, CCSD, SQD, SKQD, iterative variants)

• YAML-based experiment configuration with CLI overrides

Getting Started

• Installation
  • Requirements
  • Basic Installation
  • Optional Dependencies
  • Using uv
  • Docker (GPU)
  • Verifying the Installation
• Quickstart
  • One-Line Pipeline
  • Configurable Pipeline
  • Stage-by-Stage Execution
  • Using Individual Solvers
  • Spin Hamiltonians
  • Next Steps

User Guide

• Package Overview
  • Architecture
  • Subpackages
  • Design Principles
• Pipeline Methods
  • Pipeline Overview
  • The FlowGuidedKrylovPipeline
  • Iterative Pipelines
  • Running Experiment Scripts
• YAML Configuration System
  • Using Config Files
  • CLI Overrides
  • Available Config Files
  • Config File Structure
  • Parameter Reference
  • Auto-Scaling

API Reference

• API Reference
  • Hamiltonians
  • Neural Quantum States
  • Normalizing Flows
  • Krylov Methods
  • Diagonalization
  • Solvers
  • Samplers
  • Molecules
  • End-to-End Method Pipelines
  • GPU Extensions (Experimental)
  • Pipeline

Tutorials

• Tutorial: H2 Ground-State Energy
  • Setup
  • Step 1: Load the Molecule
  • Step 2: Compute the Exact Reference
  • Step 3: Configure the Pipeline
  • Step 4: Train the NF-NQS Model
  • Step 5: Extract and Select Basis
  • Step 6: SKQD Diagonalization
  • Running from the Command Line
• Tutorial: BeH2 Ground-State Energy
  • Setup and Configuration
  • Running the Full Pipeline
  • Comparing Methods
  • Using YAML Configs
  • Interpreting Results
• Tutorial: Writing a Custom Solver
  • The Solver Interface
  • Example: Random Sampling Solver
  • Using the Custom Solver
  • Design Guidelines

Developer Guide

• Developer Guide
  • Extending Solvers
  • Extending Samplers

About

• About

Indices and tables

• Index

• Module Index

• Search Page