Pipeline Methods

qvartools provides 24 pipeline methods organized in 8 groups. Each group combines a basis generation strategy (rows) with one of three diagonalization modes (columns): Classical Krylov, Quantum Circuit Krylov, or SQD.

Pipeline Overview

Group	NF Training	Diag Modes	Description
01 DCI	No	C / Q / SQD	Deterministic HF + singles + doubles
02 NF+DCI	Yes	C / Q / SQD	NF training + DCI merge
03 NF+DCI+PT2	Yes	C / Q / SQD	NF + DCI + perturbative expansion
04 NF-Only	Yes	C / Q / SQD	NF-only basis (ablation, no DCI)
05 HF-Only	No	C / Q / SQD	Single HF reference state (baseline)
06 Iterative NQS	Iterative	C / Q / SQD	Autoregressive NQS with eigenvector feedback
07 NF+DCI -> Iter NQS	Yes + Iterative	C / Q / SQD	NF+DCI merge then iterative NQS refinement
08 NF+DCI+PT2 -> Iter NQS	Yes + Iterative	C / Q / SQD	NF+DCI+PT2 then iterative NQS refinement

Diag mode key: C = Classical Krylov (SKQD), Q = Quantum Circuit Krylov (Trotterized), SQD = batch diag with noise + S-CORE.

The FlowGuidedKrylovPipeline

The main pipeline class orchestrates up to four stages:

Stage 1: Train — Joint physics-guided training of the normalizing flow and NQS using a mixed objective (teacher KL-divergence + variational energy + entropy regularization).

Stage 2: Select — Extract accumulated basis configurations from the trained flow and apply diversity-aware selection to ensure representation across excitation ranks.

Stage 2.5: Expand (Groups 03, 08 only) — Enlarge the basis via CIPSI-style perturbative selection using Hamiltonian connections.

Stage 3: Diagonalize — Run Classical Krylov (SKQD), Quantum Circuit Krylov, or SQD (batch diag) to compute the ground-state energy.

from qvartools import PipelineConfig, FlowGuidedKrylovPipeline
from qvartools.molecules import get_molecule

hamiltonian, mol_info = get_molecule("BeH2")

config = PipelineConfig(
    skip_nf_training=False,
    subspace_mode="classical_krylov",   # "classical_krylov", "skqd", or "sqd"
    teacher_weight=0.5,
    physics_weight=0.4,
    entropy_weight=0.1,
)

pipeline = FlowGuidedKrylovPipeline(
    hamiltonian=hamiltonian,
    config=config,
    auto_adapt=True,  # auto-scale parameters to system size
)

results = pipeline.run()

Iterative Pipelines

Groups 06-08 use an iterative loop where the ground-state eigenvector from each diagonalization is fed back as a training target for the next NQS iteration:

from qvartools.methods.nqs.hi_nqs_skqd import HINQSSKQDConfig, run_hi_nqs_skqd
from qvartools.molecules import get_molecule

hamiltonian, mol_info = get_molecule("H2")
mol_info["n_orbitals"] = hamiltonian.integrals.n_orbitals
mol_info["n_alpha"] = hamiltonian.integrals.n_alpha
mol_info["n_beta"] = hamiltonian.integrals.n_beta

config = HINQSSKQDConfig(
    n_iterations=10,
    n_samples_per_iter=5000,
    device="cuda",
)

result = run_hi_nqs_skqd(hamiltonian, mol_info, config=config)
print(f"Energy: {result.energy:.10f} Ha")
print(f"Converged: {result.converged}")

Running Experiment Scripts

All 24 pipelines live in experiments/pipelines/:

# Run a single pipeline
python experiments/pipelines/01_dci/dci_krylov_classical.py h2 --device cuda

# Run all 24 pipelines and compare
python experiments/pipelines/run_all_pipelines.py h2 --device cuda

# Run with a YAML config
python experiments/pipelines/02_nf_dci/nf_dci_krylov_classical.py lih \
    --config experiments/pipelines/configs/02_nf_dci.yaml --max-epochs 200

See YAML Configuration System for details on the configuration system.