Metadata-Version: 2.4
Name: qig-compute
Version: 0.2.3
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
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×** |

Validated: 0.00% difference vs exact diagonalisation at L=3. Identical overlaps to TeNPy at all sizes tested.

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

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