Metadata-Version: 2.4
Name: qig-compute
Version: 0.9.7
Summary: Fast compute engine for QIG geometry — analytical QFI, GPU contractions, observable governance
Project-URL: Homepage, https://braden.com.au
Project-URL: Repository, https://github.com/GaryOcean428/qig-compute
Project-URL: Documentation, https://github.com/GaryOcean428/qig-compute#readme
Project-URL: Contact & Partnerships, https://braden.com.au
Author-email: Braden Lang <braden@garyocean.com>
License: MIT
Keywords: benchmarking,computational-physics,condensed-matter,cupy,dmrg,drug-discovery,eigensolve,fisher-information,gpu,hyperparameter-optimization,machine-learning,materials-science,matrix-product-state,molecular-dynamics,mps,physics,qfi,qig,quantum,quantum-computing,screening,sparse,tenpy,tensor-network,yukawa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.15.3
Requires-Dist: threadpoolctl>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: cupy-cuda12x; extra == 'full'
Requires-Dist: physics-tenpy>=1.0; extra == 'full'
Requires-Dist: scipy>=1.10; extra == 'full'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == 'gpu'
Provides-Extra: tenpy
Requires-Dist: physics-tenpy>=1.0; extra == 'tenpy'
Description-Content-Type: text/markdown

# 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

| Method | L=6 (36 sites) | Time | Speedup |
| ------ | --------------- | ---- | ------- |
| Finite-difference QFI (old) | 26 DMRG solves | >14,400s (timeout) | baseline |
| **Analytical QFI (qig-compute)** | **0 DMRG solves** | **287s** | **50×** |

### Physics-optimized DMRG (replaces TeNPy)

| Solver | L=4 (16 sites) | Time | χ | Sweeps |
| ------ | --------------- | ---- | - | ------ |
| Blind DMRG (χ=128) | Random init | >541s (3 sweeps, still running) | 128 | 5+ |
| **Physics DMRG (energy)** | **Field-polarized init** | **105s** | **16** | **4** |

**5× faster at L=4.** At L=5 (25 sites), the physics path uses 512× fewer FLOPs per contraction ((128/16)³) — projected **10–50× speedup** on production workloads.

How:
1. **Adaptive χ** — `recommended_chi` sizes bond dimension to the observable channel (energy needs χ=16; κ-channel needs 128). No wasted precision.
2. **Smart tolerance** — `dmrg_tolerance` propagates observable precision to energy convergence threshold. Stops earlier when the target doesn't need machine-epsilon energy.
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).

## 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

```bash
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

```python
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

```python
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

| Warning | What it detects | Auto-fillable? |
| ------- | --------------- | -------------- |
| AMPLITUDE_COLLAPSE | Observable amplitude varies >10× (wrong channel) | No — switch observable |
| REGIME_SINGLE | Only tested in one regime | No — test more regimes |
| RESOLUTION_FLOOR | Frequency at FFT limit | No — increase observation time |
| CHI_LIMIT | DMRG bond dimension maxed | Partially — compare χ vs χ/2 |
| GAP_UNKNOWN | Energy gap never measured | **Yes** — one extra eigenvalue |
| NONLINEARITY_UNTESTED | Constitutive law at one δh only | **Yes** — run second δh |
| OBSERVABLE_PROXY | Magnetisation on inhomogeneous lattice | No — use energy channel |

## 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](https://github.com/GaryOcean428/qig-bench) to validate qig-compute against frozen physics results:

```python
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](https://braden.com.au)
