Metadata-Version: 2.5
Name: qig-warp
Version: 0.6.10
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.11
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.12.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)

## Security gate

`security-scan` runs on pull requests and development/main pushes. It uses Bandit 1.9.4 for common Python
security hazards in all shipped `src/` code, and pip-audit 2.10.1 for known vulnerabilities in the complete
installed dependency set, including runtime, development, optional QIG and scanner dependencies.
CI records and upgrades the runner packaging tools before scanning (setuptools 84.0.0, wheel 0.48.0);
those tools remain in the audited dependency inventory. Failure summaries name the package, version,
advisory IDs and fixed versions without dumping advisory descriptions.
Only the local unpublished qig-warp root is omitted from the advisory lookup; its source is scanned.
No Bandit finding severities are excluded, and `nosec` annotations cannot bypass the gate.

Both tools must first detect deliberately unsafe fixtures: dynamic evaluation and an old vulnerable
Requests version. These fixtures live only in a temporary directory, are never executed or installed,
and are removed automatically. Missing reports, scanner failures, unauditable dependencies and unavailable
advisory services fail the check. Returned file metrics must cover every enumerated source Python file;
returned dependency names and versions must exactly match the installed dependency inventory. Bandit
failure output excludes source snippets and issue text that could contain credentials.
Run locally after installing the same extras and pinned scanners:
`python scripts/security_gate.py`.

This replaces unavailable hosted CodeQL scanning for this private repository with an actual check named
`security-scan`. It does **not** claim CodeQL equivalence: Bandit is a Python AST pattern scanner, without
CodeQL's interprocedural data-flow analysis. Dependency checks cover known advisories, not unknown defects,
malicious-package detection or every possible dependency resolution. Tests, code review and required branch
checks remain necessary; this gate provides no blanket claim that code is safe.

Scanner references: [Bandit](https://bandit.readthedocs.io/en/latest/man/bandit.html) and
[pip-audit](https://github.com/pypa/pip-audit). Failed black-box evaluations now log their exception class
without revealing user parameters or exception text. Existing numerical fallbacks and results are preserved.
