qig-compute

Fast compute engine for quantum geometry — analytical QFI, GPU tensor contractions, observable governance.

Replaces expensive iterative methods (26 DMRG solves → 0) with direct analytical computation. Built-in blindspot detection warns when your measurements might be unreliable.

Performance

Physics-optimized DMRG (replaces TeNPy)

These timings use different bond dimensions and do not establish a matched-accuracy speedup. The nominal contraction-cost ratio ((128/16)³) is not an end-to-end speedup guarantee; check the target observable at increasing χ before using a cheaper result.

How:

1. Heuristic χ sizing — recommended_chi applies channel floors (energy: exploratory χ=16; κ-channel: 128). These are starting policies, not guarantees of a requested absolute error.
2. Sweep tolerance — dmrg_tolerance converts the requested precision to a successive-sweep energy-change threshold. It does not bound finite-χ bias or absolute error against the exact ground state.
3. Warm-start — parameter sweeps pass the previous converged MPS as initial guess. Anderson orthogonality (0.089/site) means small steps need 2–3 sweeps instead of 5+.
4. Field-polarized init — deep in the gapped phase (dist > 0.5 from critical point), starts from the +X product state instead of random. Already close to the ground state → fewer sweeps.
5. Observable early-stop — check_ci_stabilized monitors the target observable each sweep. Stops when it plateaus, even if energy hasn't fully converged.

Validated: matches exact diagonalisation to 1.78e-15 (L=2), 3.55e-15 (L=3), 1.55e-10 at χ=128 (L=4).

Sweep convergence is not an accuracy certificate

result.converged means successive sweep energies changed by less than energy_tol at the selected bond dimension. It does not certify χ convergence, ground-state accuracy, or the accuracy of another observable. required_precision in dmrg_2d_physics controls the sweep tolerance and SVD cutoff; it does not currently feed the χ-sizing heuristic. Increasing max_chi only changes a sizing ceiling, not the requested or necessarily selected χ. A channel floor can override that ceiling when the supplied ceiling is below the floor.

For example, an independent open-boundary L=4, J=h=1 energy check with required_precision=1e-9, max_chi=64 selected χ=16 and reported sweep convergence, but differed from exact diagonalisation by 6.148572e-6 in total energy. This is not 1e-9 absolute accuracy. The same check's reference eigenpair residual was 6.63e-12. Frozen experiment results retain their original convergence evidence.

To control the bond limit explicitly, use dmrg_2d_tfim(chi_max=...) and compare a declared χ ladder on the same Hamiltonian, boundaries and observable. For example:

from qig_compute import dmrg_2d_tfim

previous = None
energies = []
for chi in (16, 24, 32):
    result = dmrg_2d_tfim(
        L=4, J=1.0, h=1.0, pbc=False, chi_max=chi,
        energy_tol=1e-10, max_sweeps=30, mps_init=previous, verbose=False,
    )
    if not result.converged:
        raise RuntimeError(f"Sweep convergence not reached at chi={chi}")
    energies.append((chi, result.chi_effective, result.energy))
    previous = result.mps

Choose the ladder and acceptance criterion for the target observable. A small change across two χ values is evidence of stability, not a rigorous absolute-error bound; check further χ values or an independent reference where feasible. Report sweep convergence, χ stability and independently measured error separately.

What it does

1. Analytical QFI — Compute Quantum Fisher Information from a single MPS ground state. No finite differences, no iterative DMRG loops. One-shot computation via MPS transfer matrix overlaps.

2. GPU contractions — CuPy-accelerated tensor network contractions. Custom transfer matrix code for when TeNPy's CPU overlaps are the bottleneck.

3. Screening pipeline — Push spatial pruning INSIDE the QFI computation. Only compute at sites that matter (from warp bubble). Unmeasured sites get Yukawa-predicted values from the decay profile.

4. Observable governance — 10 built-in blindspot detectors that warn when your measurements might be wrong. Amplitude collapse, regime blindness, resolution floor, chi limits, and more. Auto-fills cheap missing measurements when budget allows.

5. Prediction tracking — Every shortcut produces a prediction. Every prediction is logged. When you later measure the skipped site, compare predicted vs actual.

Install

pip install qig-compute                # numpy only
pip install qig-compute[tenpy]         # + TeNPy for MPS-QFI
pip install qig-compute[gpu]           # + CuPy for GPU acceleration
pip install qig-compute[full]          # everything

Usage

from qig_compute import qfi_analytical, screening_aware_qfi, GovernanceReport

# Analytical QFI from a single MPS (zero DMRG loops)
F = qfi_analytical(psi_mps, L=6, sites=pruned_sites)

# Screening-aware: pruning + Yukawa fill + prediction tracking
F_full, sites, metadata = screening_aware_qfi(
    psi_mps, L=6, center=(3, 3), screening_length=0.618
)
# metadata["prediction_report"] shows measured vs predicted at every site

# Observable governance
from qig_compute import check_amplitude, check_regime_coverage
warning = check_amplitude(my_observable_values)  # detects proxy failure
warning = check_regime_coverage([1.0], J=1.0)     # flags single-regime blindspot

Physics-optimized DMRG

from qig_compute import dmrg_2d_physics, dmrg_2d_sweep

# Single solve — physics auto-selects χ, tolerance, and initialization
result = dmrg_2d_physics(L=5, J=1.0, h=1.0, observable_channel='kappa_defect')
# result.mps is a NativeMPS compatible with qfi_analytical

# Parameter sweep — automatic warm-starting between points
import numpy as np
results = dmrg_2d_sweep(
    L=4, J=1.0,
    h_values=np.linspace(0.5, 3.0, 20),
    observable_channel='energy',
)
# Each point warm-starts from the previous converged MPS

# Warm-start a perturbed solve (for finite-difference QFI)
from qig_compute import dmrg_2d_tfim_perturbed
r_pert = dmrg_2d_tfim_perturbed(
    L=4, J=1.0, h=1.0, site=8, eps=0.01,
    psi_init=result.mps,  # unperturbed GS as warm-start
)

Observable governance warnings

Use cases

Any computation where perturbations have finite range. The screening pipeline skips sites beyond the decay length. The governance module catches when your measurement observable is unreliable.

Molecular simulation: QFI measures how distinguishable quantum states are. The screening length IS the interatomic potential range. Analytical QFI avoids recomputing ground states for each perturbation.

Materials science: Grain boundaries concentrate the physics at the interface. The screening pipeline measures the boundary densely and predicts the bulk from the decay profile.

Drug discovery: Binding site QFI measures how sensitive the energy landscape is to ligand perturbations. Analytical computation makes it feasible for large binding pockets.

Benchmarking

Use qig-bench to validate qig-compute against frozen physics results:

from qig_bench import run_suite
results = run_suite(backend="qig-compute")
# 5/5 benchmarks must pass before promoting any compute upgrade

Contact

Built by Braden Lang. For partnerships and research collaboration: braden.com.au