Certify your own twins in five minutes

Twindex answers a specific question: can two coefficients of this PDE match the same noisy measurements while having different target parameters? A certified pair proves ambiguity. It does not prove either parameter is the true one. This tutorial uses the cubic model and four Bernstein coefficients of v0.1. Install the search dependencies with pip install 'twindex[search]'.

Start with your measured sensor values, exact decimal strings, a noise bound, and a prior. Here we create reproducible synthetic measurements instead. The seed parameter is checked against the rounded data using the exact checker.

from fractions import Fraction
from twindex.search import make_problem, find_pair, sivia
from twindex.model import Problem
from twindex.checker import check_certificate, Verdict
from twindex.certificate import dump_certificate, load_certificate

synthetic = make_problem(
    [500, 500, 500, 500],
    ["1/6", "1/3", "1/2", "2/3", "5/6"],
    "1/1000", [[0, 1000]] * 4, n=24,
)
# Replace synthetic.data with your own rational/decimal measurement strings.
problem = Problem.build(
    sensors=synthetic.sensors, data=synthetic.data, epsilon="1/1000",
    box=[[0, 1000]] * 4, target=0,
)

Search from a plausible feasible estimate. With real data, supply your own seed; a failed search means the heuristic failed, not that the parameter is recoverable. The numerical search is untrusted; only the exact replay establishes the claim.

pair = find_pair(problem, seed=[500] * 4, n=24, rounds=2, depth=4)
report = check_certificate(pair, depth=4)
assert report.verdict is Verdict.VALID
lower = Fraction(pair["claim"]["gap"])
assert lower > 0
print("Certified target diameter lower bound:", lower)
for witness in report.details["witnesses"]:
    assert Fraction(witness["details"]["rho"]) / 8 <= problem.epsilon / 10

dump_certificate(pair, "my_twins.json")
assert check_certificate(load_certificate("my_twins.json")).verdict is Verdict.VALID

If the target gap is L, no estimator using only these data and assumptions can guarantee absolute error strictly below L/2 for every compatible parameter. This is a worst-case statement; it says nothing about average error under a prior distribution. Inspect report.details for the individual sensor slacks and residual bounds. All certificate numbers are exact rationals.

A paving covers the entire prior, including unresolved boxes. It supplies an upper bound on the compatible target diameter, but may need far more than this small budget to improve on the prior width of 1000.

paving = sivia(problem, max_leaves=4, n=24, depth=4)
paving_report = check_certificate(paving, depth=4)
assert paving_report.verdict is Verdict.VALID
upper = Fraction(paving["claim"]["upper"])
assert lower <= upper <= 1000
print("Certified diameter interval:", lower, upper)
print("Paving leaves:", paving_report.details["leaves"])
dump_certificate(paving, "my_paving.json")

VALID for a paving verifies its bounds and coverage; unresolved leaves are allowed. An upper bound of 1000 proves no improvement over the prior. To prove recoverability to tolerance t, a nonempty compatible set and a certified diameter at most 2t suffice for a midpoint estimate of the compatible target range. A large pair gap instead rules out small worst-case errors. Never replace the full prior with a small neighborhood and describe its bound as global.

See the sensor/noise study for measured costs and bounds. Replay a saved certificate with twindex check my_twins.json. Replay needs no NumPy; generation does. Noise is a deterministic uniform bound at all listed sensors, not a standard deviation or a confidence interval.