Metadata-Version: 2.4
Name: twindex
Version: 0.8.0
Summary: Exact, replayable certificates that noisy data cannot tell two parameter sets apart, for ODE and PDE models.
Author: Arnav Mittal
License-Expression: MIT
Project-URL: Homepage, https://github.com/Arnav-M10/Twindex
Project-URL: Documentation, https://arnav-m10.github.io/Twindex/
Project-URL: Source, https://github.com/Arnav-M10/Twindex
Project-URL: Issues, https://github.com/Arnav-M10/Twindex/issues
Keywords: inverse problems,identifiability,certified computation,computer-assisted proof,exact arithmetic,PDE,ODE,PINN,set inversion,optimal recovery,parameter estimation,practical identifiability,epidemiology,pharmacokinetics,systems biology,chemical kinetics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: search
Requires-Dist: numpy>=1.24; extra == "search"
Provides-Extra: general
Requires-Dist: numpy>=1.24; extra == "general"
Requires-Dist: scipy>=1.10; extra == "general"
Provides-Extra: report
Requires-Dist: numpy>=1.24; extra == "report"
Requires-Dist: matplotlib>=3.7; extra == "report"
Provides-Extra: studies
Requires-Dist: numpy>=1.24; extra == "studies"
Requires-Dist: matplotlib>=3.7; extra == "studies"
Requires-Dist: scipy>=1.10; extra == "studies"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Requires-Dist: numpy>=1.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: scipy>=1.10; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Dynamic: license-file

# Twindex

**Your inverse solver returned a parameter. Twindex proves whether the data could have determined it.**

Least squares, Bayesian inference and physics-informed neural networks always
*return* a parameter. On their own, they do not give an independently checkable
proof of whether a very different parameter fits your measurements just as well.
Twindex finds such *twins* and proves it: it writes a JSON certificate that a
small exact checker (standard-library Python, no floating point, type-checked
with mypy --strict) replays and verifies. A VALID pair certificate proves that
**no method** can recover the parameter from those data with worst-case error
below half the certified gap.

Certified problem classes:

    ODE systems    u' = F(t, u; theta), u(0) = u0(theta), F and u0 any polynomials
                   (SIR/SEIR, pharmacokinetics, mass-action kinetics, Lotka-Volterra,
                    FitzHugh-Nagumo, ...)
    1-D BVP        -u'' + q(x; theta) f(u) = g on (0, 1)
    2-D elliptic   -Laplace(u) + q(x, y; theta) f(u) = g on (0, 1)^2
    heat equation  u_t - u_xx + q(x; theta) f(u) = g on (0, 1) x (0, 1]

Any other simulator you can call from Python gets a numerical audit, clearly
labelled as evidence rather than proof.

```console
$ pip install twindex                      # exact checker + CLI, zero dependencies
$ pip install "twindex[general,report]"    # + ODE workflow, audits and evidence reports

$ twindex example theta500_pair > pair.json
$ twindex check pair.json
pair.json: VALID: ... every estimator of theta_0 has worst-case error >= 500 on these data

$ twindex ode model.json data.csv --eps 1/100 --box k10=0,1 --box k12=0,1 --box k21=0,1 --target k10 --output out/
VALID: certified_pair; certified L = ... (about 0.287761); No U claimed. Wrote out/report.md

$ twindex report pair.json --output evidence/
```

* Certificates: witness and pair (twins) for every problem class; box and paving
  (two-sided bounds) for the 1-D problem.
* Headline result: early-epidemic SIR data at noise 1e-3 provably cannot
  determine R0 (certified twins with R0 = 2.5 and about 1.72).
* `twindex ode` / `identify_ode`: a model file and a CSV in, a certificate and a
  report out.
* `audit_model` / `certify_audit`: numerical audits of any simulator, with
  certified replay where an exact model exists.
* `twindex.fit`: check any callable (a PINN, scipy, FEM) as an exact candidate.
* Every step is proved: https://arnav-m10.github.io/Twindex/THEORY/

Documentation: https://arnav-m10.github.io/Twindex/ ·
Source: https://github.com/Arnav-M10/Twindex
