End-to-End Method Pipelines

The methods subpackage provides complete pipelines combining NQS training, configuration sampling, and iterative diagonalisation with eigenvector feedback.

NQS + SQD

class qvartools.methods.nqs.nqs_sqd.NQSSQDConfig(n_samples=10000, nqs_train_epochs=200, nqs_lr=0.001, embed_dim=64, n_heads=4, n_layers=4, temperature=1.0, max_basis_size=10000, device='cpu')[source]

Bases: object

Configuration for the NQS+SQD pipeline.

Parameters:

  • n_samples (int) – Number of NQS samples to draw (default 10_000).

  • nqs_train_epochs (int) – Pre-training epochs for NQS (default 200).

  • nqs_lr (float) – NQS learning rate (default 1e-3).

  • embed_dim (int) – Transformer embedding dimension (default 64).

  • n_heads (int) – Attention heads (default 4).

  • n_layers (int) – Transformer layers per channel (default 4).

  • temperature (float) – Sampling temperature (default 1.0).

  • max_basis_size (int) – Maximum basis size for diagonalisation (default 10_000).

  • device (str) – Torch device (default "cpu").

n_samples: int = 10000
nqs_train_epochs: int = 200
nqs_lr: float = 0.001
embed_dim: int = 64
n_heads: int = 4
n_layers: int = 4
temperature: float = 1.0
max_basis_size: int = 10000
device: str = 'cpu'
qvartools.methods.nqs.nqs_sqd.run_nqs_sqd(hamiltonian, mol_info, config=None)[source]

Execute the NQS+SQD pipeline.

Stage 1 — Train an autoregressive transformer NQS using variational Monte Carlo (energy minimisation via REINFORCE).

Stage 2 — Sample configurations from the trained NQS, deduplicate, and diagonalise the projected Hamiltonian.

Parameters:

  • hamiltonian (Hamiltonian) – Molecular Hamiltonian.

  • mol_info (dict) – Molecular metadata. Required keys: "n_orbitals", "n_alpha", "n_beta", "n_qubits".

  • config (NQSSQDConfig or None) – Pipeline configuration.

Returns:

Energy, basis dimension, wall time, and metadata.

Return type:

SolverResult

NQS + SKQD

class qvartools.methods.nqs.nqs_skqd.NQSSKQDConfig(n_samples=10000, nqs_train_epochs=200, nqs_lr=0.001, embed_dim=64, n_heads=4, n_layers=4, temperature=1.0, krylov_max_new=500, krylov_n_ref=10, max_basis_size=10000, device='cpu')[source]

Bases: object

Configuration for the NQS+SKQD pipeline.

Parameters:

  • n_samples (int) – NQS samples to draw (default 10_000).

  • nqs_train_epochs (int) – VMC pre-training epochs (default 200).

  • nqs_lr (float) – NQS learning rate (default 1e-3).

  • embed_dim (int) – Transformer embedding dim (default 64).

  • n_heads (int) – Attention heads (default 4).

  • n_layers (int) – Transformer layers per channel (default 4).

  • temperature (float) – Sampling temperature (default 1.0).

  • krylov_max_new (int) – Max new configs from Krylov expansion (default 500).

  • krylov_n_ref (int) – Reference configs for expansion (default 10).

  • max_basis_size (int) – Max basis size for diag (default 10_000).

  • device (str) – Torch device (default "cpu").

n_samples: int = 10000
nqs_train_epochs: int = 200
nqs_lr: float = 0.001
embed_dim: int = 64
n_heads: int = 4
n_layers: int = 4
temperature: float = 1.0
krylov_max_new: int = 500
krylov_n_ref: int = 10
max_basis_size: int = 10000
device: str = 'cpu'
qvartools.methods.nqs.nqs_skqd.run_nqs_skqd(hamiltonian, mol_info, config=None)[source]

Execute the NQS+SKQD pipeline.

Stage 1 — Train an autoregressive transformer NQS via VMC.

Stage 2 — Sample, deduplicate, expand via Hamiltonian connections, and diagonalise.

Parameters:

  • hamiltonian (Hamiltonian) – Molecular Hamiltonian (must support diagonal_element and get_connections).

  • mol_info (dict) – Molecular metadata. Required keys: "n_orbitals", "n_alpha", "n_beta", "n_qubits".

  • config (NQSSKQDConfig or None) – Pipeline configuration.

Returns:

Energy, basis dimension, wall time, and metadata.

Return type:

SolverResult

HI + NQS + SQD (Iterative)

class qvartools.methods.nqs.hi_nqs_sqd.HINQSSQDConfig(n_iterations=10, n_samples_per_iter=10000, n_batches=5, max_configs_per_batch=5000, energy_tol=1e-05, nqs_lr=0.001, nqs_train_epochs=50, embed_dim=64, n_heads=4, n_layers=4, temperature=1.0, use_ibm_solver=False, device='cpu')[source]

Bases: object

Configuration for the HI+NQS+SQD pipeline.

Parameters:

  • n_iterations (int) – Number of outer self-consistent iterations (default 10).

  • n_samples_per_iter (int) – NQS samples drawn per iteration (default 10_000).

  • n_batches (int) – Configuration-recovery batches per iteration (default 5).

  • max_configs_per_batch (int) – Maximum configs retained per batch (default 5000).

  • energy_tol (float) – Convergence threshold in Hartree (default 1e-5).

  • nqs_lr (float) – NQS optimiser learning rate (default 1e-3).

  • nqs_train_epochs (int) – NQS training epochs per iteration (default 50).

  • embed_dim (int) – Transformer embedding dimension (default 64).

  • n_heads (int) – Number of attention heads (default 4).

  • n_layers (int) – Number of transformer layers per channel (default 4).

  • temperature (float) – NQS sampling temperature (default 1.0).

  • use_ibm_solver (bool) – Use IBM solve_fermion when available (default False). Set to True only if qiskit_addon_sqd is installed with a compatible API version.

  • device (str) – Torch device string (default "cpu").

n_iterations: int = 10
n_samples_per_iter: int = 10000
n_batches: int = 5
max_configs_per_batch: int = 5000
energy_tol: float = 1e-05
nqs_lr: float = 0.001
nqs_train_epochs: int = 50
embed_dim: int = 64
n_heads: int = 4
n_layers: int = 4
temperature: float = 1.0
use_ibm_solver: bool = False
device: str = 'cpu'
qvartools.methods.nqs.hi_nqs_sqd.run_hi_nqs_sqd(hamiltonian, mol_info, config=None, *, initial_basis=None)[source]

Execute the HI+NQS+SQD pipeline.

Parameters:

  • hamiltonian (Hamiltonian) – Molecular Hamiltonian.

  • mol_info (dict) – Molecular metadata. Required keys: "n_orbitals", "n_alpha", "n_beta", "n_qubits".

  • config (HINQSSQDConfig or None) – Pipeline configuration.

  • initial_basis (torch.Tensor or None, optional) – Pre-computed configurations to seed the cumulative basis (e.g., from NF+DCI Stage 1-2). Shape (n_configs, n_qubits). If None (default), starts from an empty basis.

Returns:

Energy, timing, convergence, and per-iteration metadata.

Return type:

SolverResult

Raises:

  • ValueError – If mol_info is missing required keys, or if initial_basis has wrong shape, non-binary values, or floating-point/complex dtype.

  • RuntimeError – If all diagonalisation batches produce non-finite energies.

HI + NQS + SKQD (Iterative)

class qvartools.methods.nqs.hi_nqs_skqd.HINQSSKQDConfig(n_iterations=10, n_samples_per_iter=10000, n_batches=5, max_configs_per_batch=5000, energy_tol=1e-05, nqs_lr=0.001, nqs_train_epochs=50, embed_dim=64, n_heads=4, n_layers=4, temperature=1.0, krylov_max_new=500, krylov_n_ref=10, use_ibm_solver=False, device='cpu')[source]

Bases: object

Configuration for the HI+NQS+SKQD pipeline.

Parameters:

  • n_iterations (int) – Outer self-consistent iterations (default 10).

  • n_samples_per_iter (int) – NQS samples per iteration (default 10_000).

  • n_batches (int) – Batches per iteration (default 5).

  • max_configs_per_batch (int) – Max configs per batch (default 5000).

  • energy_tol (float) – Convergence threshold in Hartree (default 1e-5).

  • nqs_lr (float) – NQS learning rate (default 1e-3).

  • nqs_train_epochs (int) – NQS epochs per iteration (default 50).

  • embed_dim (int) – Transformer embedding dim (default 64).

  • n_heads (int) – Attention heads (default 4).

  • n_layers (int) – Transformer layers per channel (default 4).

  • temperature (float) – NQS sampling temperature (default 1.0).

  • krylov_max_new (int) – Max new configs from Krylov expansion per iteration (default 500).

  • krylov_n_ref (int) – Number of reference configs for Krylov expansion (default 10).

  • use_ibm_solver (bool) – Use IBM solver when available (default False). Set to True only if qiskit_addon_sqd is installed with a compatible API version.

  • device (str) – Torch device (default "cpu").

n_iterations: int = 10
n_samples_per_iter: int = 10000
n_batches: int = 5
max_configs_per_batch: int = 5000
energy_tol: float = 1e-05
nqs_lr: float = 0.001
nqs_train_epochs: int = 50
embed_dim: int = 64
n_heads: int = 4
n_layers: int = 4
temperature: float = 1.0
krylov_max_new: int = 500
krylov_n_ref: int = 10
use_ibm_solver: bool = False
device: str = 'cpu'
qvartools.methods.nqs.hi_nqs_skqd.run_hi_nqs_skqd(hamiltonian, mol_info, config=None, *, initial_basis=None)[source]

Execute the HI+NQS+SKQD pipeline.

Parameters:

  • hamiltonian (Hamiltonian) – Molecular Hamiltonian (must support diagonal_element and get_connections for Krylov expansion).

  • mol_info (dict) – Molecular metadata. Required keys: "n_orbitals", "n_alpha", "n_beta", "n_qubits".

  • config (HINQSSKQDConfig or None) – Pipeline configuration.

  • initial_basis (torch.Tensor or None, optional) – Pre-computed configurations to seed the cumulative basis (e.g., from NF+DCI Stage 1-2). Shape (n_configs, n_qubits). If None (default), starts from an empty basis.

Returns:

Energy, timing, convergence, and iteration metadata.

Return type:

SolverResult

Raises:

  • ValueError – If mol_info is missing required keys, or if initial_basis has wrong shape, non-binary values, or floating-point/complex dtype.

  • RuntimeError – If all diagonalisation batches produce non-finite energies.