Metadata-Version: 2.4
Name: qig-warp
Version: 0.4.3
Summary: Physics-based navigation for expensive computation — screening, cost prediction, convergence stopping
Project-URL: Homepage, https://braden.com.au
Project-URL: Repository, https://github.com/GaryOcean428/qig-warp
Project-URL: Documentation, https://github.com/GaryOcean428/qig-warp#readme
Project-URL: Contact & Partnerships, https://braden.com.au
Author-email: Braden Lang <braden@garyocean.com>
License: MIT
Keywords: auto-discovery,bayesian-optimization,budget,climate-modeling,computational-budget,convergence,cost-prediction,drug-discovery,early-stopping,ensemble-forecasting,expensive-computation,hyperparameter-optimization,locality,machine-learning,materials-science,molecular-dynamics,navigation,physics,pruning,qig,regime-aware,screening,self-calibrating,warp-bubble,yukawa
Classifier: Development Status :: 4 - Beta
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'
Requires-Dist: scipy>=1.10; extra == 'dev'
Provides-Extra: qig
Requires-Dist: qig-core>=2.6.0; extra == 'qig'
Description-Content-Type: text/markdown

# qig-warp

**Physics-based navigation for expensive computation** — screening, cost prediction, convergence stopping.

Any expensive computation has three questions: What can I skip? What will it cost? When should I stop? qig-warp answers all three from a small pilot, before the main computation runs.

## The problem

You have an expensive function to evaluate across many parameters. Running everything takes hours. But most of the computation doesn't contribute to your answer — perturbations decay exponentially, cost scales predictably, and estimates converge long before you finish.

## The solution

```python
from qig_warp import WarpBubble

# Self-calibrating: discovers structure from 5 pilot probes
bubble = WarpBubble.auto()
result = bubble.navigate(fn=my_expensive_function, params=param_list, budget_s=3600)

# Result: computed 12/20 params in 30 min instead of 60 min
# Skipped the expensive ones that wouldn't change the answer
# Predicted values for skipped sites from decay profile
```

## Three operations

| Operation | Question | How it works |
|---|---|---|
| **Screening** | What can I skip? | Perturbation response decays exponentially. Sites beyond the decay length don't matter. |
| **Bridge** | What will it cost? | Cost scales as a power law with the control parameter. Knowing the exponent predicts runtime. |
| **Convergence** | When should I stop? | Successive estimates converge exponentially. The decay rate tells you when more computation is waste. |

## Four modes

```python
bubble = WarpBubble.auto()                      # discovers constants from pilot probes
bubble = WarpBubble.qig_regime(h=3.0, J=1.0)    # regime-aware (physics calibrated)
bubble = WarpBubble.qig_frozen()                 # single calibration (v0.3 compatible)
bubble = WarpBubble.general(screening_length=0.5, bridge_exponent=0.8)  # user-specified
```

## Use cases

**Molecular simulation:** Interatomic potentials decay with distance (screening). System-size cost scales as N² or N·log(N) (bridge). Energy minimization converges (convergence).

**Drug discovery:** Binding sites are local — only nearby residues matter (screening). Conformational search cost scales with flexibility (bridge). Docking scores stabilize (convergence).

**ML hyperparameter search:** Learning rate perturbations have limited range (screening). Training cost scales with model/data size (bridge). Loss curves flatten (convergence).

**Climate ensemble forecasting:** Weather patterns have finite spatial correlation (screening). Resolution scaling is predictable (bridge). Ensemble convergence tells you when to stop adding members (convergence).

**Materials science:** Grain boundary physics concentrates at the interface (screening). Simulation cost scales with supercell size (bridge). Elastic constants converge (convergence).

## Performance

Validated on quantum physics lattice experiments (L=3 through L=6):
- Screening: 36% site reduction with <2.1% error
- Cost prediction: matched actual runtime to R²=0.999
- Bridge: predicted J-sweep cost within 5% across 7 coupling values

On a molecular dynamics benchmark:
- Auto-discovery found cost exponent within 0.5% of truth from 5 probes
- Budget-constrained: 12/15 evaluations, 29% time savings

## Install

```bash
pip install qig-warp
```

## Contact

Built by Braden Lang. For partnerships and research collaboration: [braden.com.au](https://braden.com.au)
