Trust

The content on this page was written by AI under human supervision.

Trust is a Python package for checking an integration-by-parts reduction table after a reduction program has produced it. It takes the system files Kira generated and the reduction table, plus a rational evaluation point for its exact route, and runs three checks that share no core code, so a mistake made once cannot confirm itself. It returns a pass or an error for the whole table, a certificate for each row (written and checked by its receipt module, which also runs on its own against a table from any program), and an exact coefficient-by-coefficient comparison against an independently computed reduction.

What it does

A reduction tablethe output of an integration-by-parts (IBP) reduction: each row writes one Feynman integral of a family as a linear combination of a few master integrals comes from solving a very large sparse linear system, usually numerically at a fixed kinematic point and modulo a large prime. The usual consistency check, reducing at two primes and comparing, cannot catch an error made the same way both times, and it says nothing about whether the chosen master integralsthe small set of integrals that every other integral in the family is expressed through are really independent. Trust runs three checks on one table instead.

The first check, the strata/ part of the package, re-solves the linear system Kira generated with its own modular eliminator at several chosen points $(p, d, \eta)$ and compares with Kira's full-table output. It also reduces fresh identities from an independent IBP generator against the solved table, where every one must vanish, and confirms that deliberately corrupted rows are rejected. The second check attaches a certificate to each row: a sparse vector of multipliers $\lambda$ over the rows $R_i$ of the generating system such that

$$\sum_i \lambda_i R_i = e_t - \sum_m c_m\, e_m \pmod p,$$

where the row claims $I_t=\sum_m c_m I_m$ and $e_j$ is the unit vector on column $j$. If the identity holds, the row is an exact linear consequence of that system at that point and prime, whichever program produced it; the check is a sparse multiply-and-add and an exact comparison with no tolerance. Certificates are written and verified by the receipt module (tools/trust/receipt/, described below), whose checker uses only the Python standard library and imports no solver code. The third check takes a different mathematical route. It builds the Lee–Pomeransky polynomial of each sector (the sum $U+F$ of the two Symanzik polynomials) and asks Singular for its syzygiespolynomial relations among the derivatives of the Lee–Pomeransky polynomial; each one gives an IBP identity directly in parametric form. It then descends through the subsector tower in exact rational arithmetic (python-flint) and reduces the same targets at one rational point $(d_0,\eta_0)$ for comparison with the table. This route sees what the first two cannot: extra linear relations among the declared masters, which make a table non-unique without making any single row look wrong.

Kira and the syzygy route both rest on the FLINT library, so a separate pure-Python module repeats a bounded, hash-seeded sample of the exact linear algebra in fractions.Fraction alone; a library-level bug then cannot make the two agree by accident.

The receipt module also runs on its own, from any directory, against a table from any reduction program. A certificate (the code calls it a witness) is one small JSON file per row and prime in the version 1.0 format of WITNESS_FORMAT.md: the prime, the target column, the certified coefficients c, the nonzero multipliers lam, and optionally a SHA-256 checksum of the evaluated system, so that a certificate presented against a different system fails. receipt.py verify checks such files against the system in about a millisecond per row, and with a claimed table also fails any row whose claimed coefficients differ from the certified ones. receipt.py emit produces certificates for an existing table by solving for the multipliers with a matrix-free Wiedemann iteration modulo $p$; a row the system does not imply gets status CLAIM_MISMATCH and no certificate. A solve costs a couple of seconds per row per prime on a system of about 7,000 equations and much more on larger ones, so large tables are certified on a chosen sample of rows. receipt.py detect audits the system itself: relations among the declared masters (alarm A1), undeclared columns that survive elimination as if they were masters (A2), requested targets that no chain of identities reaches (A3), and table rows with coefficients outside the declared basis (A4). The system is supplied either as a JSONL file from your own parser, one sparse row per line mapping an integer column id to its value mod $p$, or, for Kira-based pipelines, through the strata adapter at a prime and point written p:d:eta. Every command prints a JSON report and exits 0 when everything passes, 1 when a row fails or an alarm fires, and 2 when an input cannot be read. Winnow carries byte-identical copies of the checker, emitter and audit as ibplapper.receipt, so both packages read and write the same certificate files.

The package also guards its inputs. The bundled engine scripts under vendor/ are checksummed and trust.verify() raises VendorTamperError on any change. import trust refuses with EnvPoisonError when PYTHONPATH, PYTHONSTARTUP or PYTHONHOME is set (run Python with -E or -I), and with StdlibShadowError when a standard-library module was loaded from outside the interpreter's own directories. Calls that write files need TRUST_OUT_ROOT to name an absolute scratch directory outside /home and the package tree (under /tmp or /var/tmp by default). Kira table text goes through a restricted rational-function grammar, never eval or sympify, and anything outside it stops the parse with an error naming the line.

Limits. Every statement holds at the points and primes Trust ran at; it is not a symbolic proof about the table as a function of the kinematics. A verified certificate proves that a row lies in the row span of the given system and nothing more; whether that system is complete is what detect and your knowledge of where the system came from are for. The syzygy route is for spot checks, since the Singular step alone runs past twenty minutes on an eight-variable top sector. The included table adapter covers one two-loop, nine-propagator test family; another family needs a similar adapter (propagators, kinematics, masses). The reference Kira tables used by the package's own tests are not in the repository: reduce_and_compare takes the path of your table, and lp_syz.py reads its table path from TRUST_LPSYZ_KTAB. Running the first check in full needs Kira with the Fermat backend. Finally, the receipt checker imports no solver code, but the strata adapter parses rows with strata's own loader; for a check that shares no code with the reduction, write the rows to JSONL with your own parser or reimplement the checker from WITNESS_FORMAT.md.

Examples

Run the whole package's self-tests. From the root of a checkout (the script works from any directory and writes only under the optional scratch directory, a temporary one by default):

sh tools/trust/selftest.sh [scratch]
python3 -E -c "import trust; trust.verify()"      # the first part alone, from tools/trust

The first part imports the package with its guards active and re-hashes the four bundled engine files; verify() returns a dictionary with vendor_ok, vendor_bad, linked_missing and linked_drift, a changed file under vendor/ raises VendorTamperError naming it, and a change in the receipt/ or strata/ trees is printed as an advisory and never raises. The second part runs the receipt module's tests (RECEIPT TEST BATTERY: ALL PASS; the part that replays archived tables prints a skip unless RECEIPT_BANKED_ROOT points at them). The third part runs the strata certificate tests below and is skipped, with a message saying so, when pytest or NumPy is missing. The script ends with TRUST SELFTEST: ALL LEGS PASS and exit status 0.

Run the certificate tests of the strata eliminator. From tools/trust/strata:

python3 -m pytest tests/test_certify.py

Five tests build a small synthetic system modulo $p=1048573$, solve it while recording the elimination steps, extract the multiplier vector for every pivot row, and confirm each certificate with the independent checker. They then corrupt a multiplier, a coefficient and a recorded elimination factor in turn, require exactly the affected certificates to fail, and check that saving and reloading is exact.

Certify an existing Kira table with the receipt module, then check it. From the module's README, with $T the tools/trust/receipt directory, $ART the Kira staging output for a family myfam and $STG its staged configuration:

# 1. EMIT lambda-witnesses for an existing kira table (retrofit; both primes)
python3 $T/receipt.py emit --adapter strata \
  --system-dir $ART --staging $STG --family myfam \
  --table $STG/corpus/<id>/kira_target.m \
  --slices 2147483647:1234577:87654321,2147483629:1234577:87654321 \
  --out /path/to/witnesses

# 2. VERIFY witnesses (independent parse; ~1 ms/row after system load)
python3 $T/receipt.py verify --adapter strata \
  --system-dir $ART --staging $STG --family myfam \
  --witness '/path/to/witnesses/w_*.json'
# rc: 0 all pass | 1 any row fails | 2 malformed input

Step 1 writes one w_myfam_<p>_<target column>.json per certified row and prime into --out, plus EMIT_REPORT.json with each row's status (CERTIFIED, CLAIM_MISMATCH, SHELL_RESIDUAL or SOLVE_FAILED), and exits 1 if any row was not certified. Step 2 evaluates the system once per prime and point and prints n_pass, n_fail, verify_ms_per_row and a per-file results list whose failing entries carry a reason (-q omits the list, --report FILE saves it). Adding --table claimed_rows.json, a JSON object mapping each target column to its {column: value} row, makes it the wrong-table check: a row whose certificate holds but whose claimed coefficients differ fails. receipt.py detect with the same adapter flags and one --slices value reports one block per alarm (A1_master_relations, A2_pseudo_masters, A3_uncovered_targets, A4_foreign_support). For a system from another program, drop the adapter flags and pass --system-jsonl FILE --p PRIME (detect also takes --masters LIST.json; emit also --pivots and --target-col).

Run a bundled syzygy engine as a child process, then compare an exact reduction with a Kira table. Here table is the path of a Kira table file for the test family, d0 and eta0 are fractions.Fraction values, and TRUST_OUT_ROOT is set:

import sys; sys.path.insert(0, "<path-to>/tools/trust")
import trust
trust.verify()
trust.run_vendored("lp_syz_431", ["--stage","control452","--D0","6"])
from trust import oracle_k2disp as ok
r = ok.reduce_and_compare(table, d0, eta0)

run_vendored re-checks the engine's checksum, launches it as python3 -E -P -s -B in TRUST_OUT_ROOT, and returns a subprocess.CompletedProcess; control452 is that engine's clean negative control, expected to find zero violation rows, and writes control452.json there. reduce_and_compare builds one syzygy tower over the union of the targets' sectors and reduces every target in the table exactly at $(d_0,\eta_0)$. Its result dictionary carries n_targets, n_violations, n_match, sigma (the sign convention under which every target matched, or None), per-target details with any differing coefficients, and timings. An empty table or an absent requested target raises instead of returning an empty success.

Routines

Package (import trust)

trust.strata and trust.receipt (accessors to the two bundled sub-trees)

The receipt module (tools/trust/receipt/; also runs stand-alone)

trust.oracle_k2disp

trust.witness_bridge

trust.fraction_oracle

strata/

vendor/lpsyz/ (run through load_vendored or run_vendored)

Self-tests and environment

Requirements and source

Python 3 with sympy; python-flint and Singular for the syzygy engines; mpmath for the Bessel reference script; NumPy for strata/certify.py and for the receipt module's emit, shim.py and tests (its checker, its audit, and verify/detect on JSONL systems use only the standard library); Kira with the Fermat backend for the complete first check; pytest for the strata tests. The receipt module and the strata tree are included in the package, at tools/trust/receipt/ and tools/trust/strata/. Self-tests: sh tools/trust/selftest.sh [scratch] from any directory runs the import guards and engine checksums, the receipt module's tests and the strata tests, writing only under the scratch directory; python3 -E -c "import trust; trust.verify()" from tools/trust is the first part alone, and sh tools/trust/receipt/tests/run_tests.sh [OUT_DIR] the receipt module's tests alone (well under a minute on one core without the archived part). python3 battery/battery.py <scratch>, run from a scratch directory with a clean environment, is the full acceptance suite; a few of its checks read reference tables that are not included in the repository and report a named skip instead. The code lives in tools/trust/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license: trust/ is the package, receipt/ the certificate module, strata/ the cross-check engine, vendor/lpsyz/ the bundled syzygy engines, battery/ the acceptance suite.

← back to the tools index