twindex 0.2.0__py3-none-any.whl

twindex/__init__.py

@@ -0,0 +1,3 @@
+"""Exact, replayable certificates of data-compatible ambiguity for a PDE inverse problem."""
+
+__version__ = "0.2.0"

twindex/affine.py

@@ -0,0 +1,135 @@
+"""Affine candidate families over a parameter box (trusted core; exact arithmetic only).
+
+On a box B = c +- h a certificate may use, instead of one candidate p, the family
+
+    p_D(x) = p0(x) + sum_j D_j s_j(x),    D in prod_j [-h_j, h_j],   theta = c + D,
+
+with every s_j vanishing at 0 and 1. Expanding the residual exactly,
+
+    r(x; D) = -p_D'' + q(x; c + D) f(p_D) - g = sum_alpha D^alpha R_alpha(x),
+
+gives the uniform bound sup_{x, D} |r| <= sum_alpha h^alpha sup_x |R_alpha|
+(docs/THEORY.md, Theorem 3'). The polynomial p_D(x_i) at a sensor is affine in D,
+so its exact range over the box is a_i +- sum_j h_j |s_j(x_i)|.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from fractions import Fraction
+
+from .model import Model
+from .poly import Poly, sup_abs_bound
+
+__all__ = ["MAX_EXPANSION_TERMS", "ExpansionTooLarge", "affine_residual_bound", "sensor_range"]
+
+#: Largest number of D-monomials an exact residual expansion may have.
+MAX_EXPANSION_TERMS = 20_000
+
+Exponent = tuple[int, ...]
+MPoly = dict[Exponent, Poly]  # sum over exponents alpha of D^alpha * coefficient(x)
+
+
+class ExpansionTooLarge(ValueError):
+    """The exact expansion would exceed MAX_EXPANSION_TERMS monomials."""
+
+
+def _add_into(acc: MPoly, other: MPoly) -> None:
+    for k, v in other.items():
+        s = acc[k] + v if k in acc else v
+        if s.coeffs:
+            acc[k] = s
+        elif k in acc:
+            del acc[k]
+
+
+def _mul(a: MPoly, b: MPoly) -> MPoly:
+    out: MPoly = {}
+    for ka, va in a.items():
+        for kb, vb in b.items():
+            k = tuple(i + j for i, j in zip(ka, kb, strict=True))
+            prod = va * vb
+            s = out[k] + prod if k in out else prod
+            if s.coeffs:
+                out[k] = s
+            elif k in out:
+                del out[k]
+            if len(out) > MAX_EXPANSION_TERMS:
+                raise ExpansionTooLarge(f"expansion exceeds {MAX_EXPANSION_TERMS} terms")
+    return out
+
+
+def _pow(a: MPoly, m: int, n: int) -> MPoly:
+    result: MPoly = {(0,) * n: Poly([1])}
+    base = a
+    while m:
+        if m & 1:
+            result = _mul(result, base)
+        m >>= 1
+        if m:
+            base = _mul(base, base)
+    return result
+
+
+def _unit(n: int, j: int) -> Exponent:
+    return tuple(1 if i == j else 0 for i in range(n))
+
+
+def residual_expansion(model: Model, center: Sequence[Fraction], p0: Poly,
+                       sens: Sequence[Poly]) -> MPoly:
+    """Exact coefficients R_alpha(x) of r(x; D) = sum_alpha D^alpha R_alpha(x)."""
+    n = model.num_params
+    zero: Exponent = (0,) * n
+    p_family: MPoly = {zero: p0}
+    for j, s in enumerate(sens):
+        if s.coeffs:
+            p_family[_unit(n, j)] = s
+    f_family: MPoly = {}
+    for m, a in model.nonlinearity:
+        term = _pow(p_family, m, n)
+        _add_into(f_family, {k: v.scale(a) for k, v in term.items()})
+    q_family: MPoly = {zero: model.q(center)}
+    for j, bj in enumerate(model.basis):
+        q_family[_unit(n, j)] = bj
+    out = _mul(q_family, f_family) if f_family else {}
+    lin: MPoly = {k: -v.deriv(2) for k, v in p_family.items()}
+    lin[zero] = lin.get(zero, Poly()) - model.source
+    _add_into(out, {k: v for k, v in lin.items() if v.coeffs})
+    return out
+
+
+def affine_residual_bound(
+    model: Model,
+    center: Sequence[Fraction],
+    half_width: Sequence[Fraction],
+    p0: Poly,
+    sens: Sequence[Poly],
+    depth: int,
+    high_order_depth: int = 2,
+) -> Fraction:
+    """Certified bound of sup over x in [0,1] and D in the box of |r(x; D)|.
+
+    Terms of total degree <= 1 in D use ``depth`` subdivision levels, higher-order
+    terms use ``min(depth, high_order_depth)``; every choice is sound.
+    """
+    expansion = residual_expansion(model, center, p0, sens)
+    rho = Fraction(0)
+    for alpha, coeff in expansion.items():
+        weight = Fraction(1)
+        for hj, aj in zip(half_width, alpha, strict=True):
+            if aj:
+                weight *= hj**aj
+        if weight == 0:
+            continue
+        d = depth if sum(alpha) <= 1 else min(depth, high_order_depth)
+        rho += weight * sup_abs_bound(coeff, d)
+    return rho
+
+
+def sensor_range(
+    p0: Poly, sens: Sequence[Poly], half_width: Sequence[Fraction], x: Fraction
+) -> tuple[Fraction, Fraction]:
+    """Exact range [lo, hi] of p_D(x) = p0(x) + sum_j D_j s_j(x) over |D_j| <= h_j."""
+    a = p0(x)
+    spread = sum((h * abs(s(x)) for h, s in zip(half_width, sens, strict=True)), Fraction(0))
+    return a - spread, a + spread

twindex/audit.py

@@ -0,0 +1,103 @@
+"""Untrusted measured-data workflow; only exact replay accepts evidence."""
+import csv
+from fractions import Fraction
+from pathlib import Path
+
+import numpy as np
+from numpy.polynomial.chebyshev import chebval
+
+from .candidate import to_candidate
+from .certificate import dump_certificate, make_witness_certificate
+from .checker import Verdict, check_certificate, check_witness
+from .model import Problem
+from .poly import Poly
+from .rational import format_rational, parse_rational
+from .search import find_pair
+from .solver import solve_bvp
+
+
+def read_data(path):
+    """Read exact x,y columns without a floating-point round trip."""
+    with open(path, newline='', encoding='utf-8-sig') as stream:
+        reader = csv.DictReader(stream)
+        if (reader.fieldnames is None or len(reader.fieldnames) != 2
+                or set(reader.fieldnames) != {'x', 'y'}):
+            raise ValueError('CSV must have exactly the columns x,y')
+        rows = list(reader)
+    if not rows or any(None in row or None in row.values() for row in rows):
+        raise ValueError('CSV must contain complete x,y rows')
+    return tuple(parse_rational(row['x']) for row in rows), tuple(
+        parse_rational(row['y']) for row in rows)
+
+
+def fit_seed(problem, *, n=32, iterations=30):
+    """Bounded damped least squares, a heuristic with no feasibility guarantee."""
+    lo, hi = np.array(problem.box, dtype=float).T
+    theta = (lo + hi) / 2
+    xs, y = np.array(problem.sensors, dtype=float), np.array(problem.data, dtype=float)
+
+    def values(t):
+        return chebval(2 * xs - 1, solve_bvp(t, n=n, model=problem.model))
+
+    for _ in range(iterations):
+        base = values(theta)
+        error = base - y
+        if np.max(np.abs(error)) < float(problem.epsilon) / 2:
+            break
+        jac = np.zeros((len(xs), len(theta)))
+        for j in range(len(theta)):
+            if hi[j] == lo[j]:
+                continue
+            probe = theta.copy()
+            h = max(1e-4, abs(theta[j]) * 1e-4)
+            probe[j] = min(hi[j], theta[j] + h)
+            if probe[j] == theta[j]:
+                probe[j] = max(lo[j], theta[j] - h)
+            jac[:, j] = (values(probe) - base) / (probe[j] - theta[j])
+        step = np.linalg.lstsq(jac, -error, rcond=None)[0]
+        for backtrack in range(20):
+            trial = np.clip(theta + 2.0**(-backtrack) * step, lo, hi)
+            if np.linalg.norm(values(trial) - y) < np.linalg.norm(error):
+                theta = trial
+                break
+        else:
+            break
+    return tuple(Fraction(f'{v:.12f}') for v in theta)
+
+
+def audit(problem: Problem, output, *, estimate=None, n=32, rounds=3, depth=6):
+    """Return an honest summary and paths; never infer uniqueness from failure."""
+    seed = None
+    # An estimate is accepted only after an exact check. If it fails, try a fit.
+    attempts = [estimate, None] if estimate is not None else [None]
+    for attempt in attempts:
+        try:
+            theta = (tuple(parse_rational(v) for v in attempt) if attempt is not None
+                     else fit_seed(problem, n=n))
+            p = Poly(to_candidate(solve_bvp(theta, n=n, model=problem.model)))
+            if check_witness(problem, theta, p, depth).verdict is Verdict.VALID:
+                seed = (theta, p)
+                break
+        except (ValueError, RuntimeError, ArithmeticError, np.linalg.LinAlgError):
+            continue
+    if seed is None:
+        return 2, 'No compatible seed certified; recoverability remains undecided.'
+    output = Path(output)
+    output.mkdir(parents=True, exist_ok=True)
+    witness = make_witness_certificate(problem, *seed)
+    if check_certificate(witness, depth).verdict is not Verdict.VALID:
+        raise RuntimeError('seed certificate failed replay')
+    witness_path = output / 'seed.json'
+    dump_certificate(witness, witness_path)
+    try:
+        pair = find_pair(problem, seed=seed[0], n=n, rounds=rounds, depth=depth)
+    except (ValueError, RuntimeError, ArithmeticError, np.linalg.LinAlgError):
+        return 2, (f'Compatible seed certified: {witness_path}. No positive pair gap certified; '
+                   'recoverability remains undecided.')
+    pair_path = output / 'pair.json'
+    dump_certificate(pair, pair_path)
+    radius = format_rational(parse_rational(pair['claim']['gap']) / 2)
+    return 0, (f'theta_{problem.target} cannot have a uniform absolute-error guarantee '
+               f'better than +/-{radius} from these data (certified). '
+               f'Certificates: {witness_path}, {pair_path}. '
+               'This is a lower bound on worst-case uncertainty, not an upper bound.')

twindex/candidate.py

@@ -0,0 +1,66 @@
+"""Untrusted conversion to exact monomial candidates with exact zero BCs."""
+
+import operator
+from fractions import Fraction
+
+import numpy as np
+from numpy.polynomial import chebyshev as cheb
+
+
+def _add(a, b):
+    out = [Fraction(0)] * max(len(a), len(b))
+    for i, c in enumerate(a):
+        out[i] += c
+    for i, c in enumerate(b):
+        out[i] += c
+    return out
+
+
+def _shifted_t_times(a):
+    """Multiply by t=2x-1 in exact monomial arithmetic."""
+    out = [Fraction(0)] * (len(a) + 1)
+    for i, c in enumerate(a):
+        out[i] -= c
+        out[i + 1] += 2 * c
+    return out
+
+
+def to_candidate(coeffs, bits=60, degree=None):
+    """Return exact monomial coefficients, constant first.
+
+    Divide the floating Chebyshev polynomial by x(1-x), discard its boundary
+    remainder, and round the quotient's Chebyshev coefficients to dyadics.
+    Convert the quotient EXACTLY using T_(k+1)=2(2x-1)T_k-T_(k-1), then
+    multiply by x(1-x). No floating monomial conversion is performed.
+    ``degree`` optionally truncates the quotient before exact conversion.
+    """
+    bits = operator.index(bits)
+    if bits < 0 or bits > 1024:
+        raise ValueError("bits must lie between 0 and 1024")
+    c = np.asarray(coeffs, dtype=float)
+    if c.ndim != 1 or c.size == 0 or not np.all(np.isfinite(c)):
+        raise ValueError("coeffs must be a nonempty finite one-dimensional array")
+    quotient, _ = cheb.chebdiv(c, [1 / 8, 0, -1 / 8])
+    if degree is not None:
+        degree = operator.index(degree)
+        if degree < 0:
+            raise ValueError("degree must be nonnegative")
+        quotient = quotient[:degree + 1]
+    scale = 1 << bits
+    # Fraction(float) is intentional here, outside the trusted core. Integer
+    # rounding avoids overflow even when bits is larger than the float range.
+    rounded = [Fraction(round(Fraction(float(a)) * scale), scale) for a in quotient]
+    previous, current = [Fraction(1)], [Fraction(-1), Fraction(2)]
+    s = [rounded[0]]
+    for k in range(1, len(rounded)):
+        s = _add(s, [rounded[k] * a for a in current])
+        previous, current = current, _add(
+            [2 * a for a in _shifted_t_times(current)], [-a for a in previous]
+        )
+    out = [Fraction(0)] * (len(s) + 2)
+    for i, a in enumerate(s):
+        out[i + 1] += a
+        out[i + 2] -= a
+    while len(out) > 1 and out[-1] == 0:
+        out.pop()
+    return out