Trust

Trust is a Python package that checks 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 after a reduction program has produced it. It takes the system files that Kira generated and the table, and runs three checks that share no core code, so a mistake made once cannot confirm itself. The third check implements a published method, integration by parts in the Lee–Pomeransky representationa way of writing a Feynman integral with one polynomial G = U + F in the Feynman parameters, where U and F are the two Symanzik polynomials (Lee and Pomeransky; Bitoun, Bogner, Klausen and Panzer; Chen).

What it does

A reduction table 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 is to reduce at two primes and compare. That check cannot catch an error made the same way both times. It also cannot tell whether the chosen master integralsthe small set of integrals that every other integral in the family is expressed through satisfy further linear relations among themselves.

Trust runs three checks on one table. It returns a pass or an error for the whole table, a certificate for each row, and an exact coefficient-by-coefficient comparison with the reduction computed by the third check.

A certificate for a row that claims $I_t=\sum_m c_m I_m$ is a 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 $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.

Kira and the syzygy check both rest on the FLINT library. A separate pure-Python module therefore repeats a bounded, hash-seeded sample of the exact linear algebra in fractions.Fraction alone, so that a library-level bug 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. Winnow carries byte-identical copies of its checker, emitter and audit as ibplapper.receipt, so both packages read and write the same certificate files.

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. It holds the prime, the target column, the certified coefficients c and the nonzero multipliers lam. It can also hold a SHA-256 checksum of the evaluated system, so that a certificate presented against a different system fails.

The package also guards its inputs:

Trust has these limits:

Examples

Run the whole package's self-tests. With the dependencies in place (see Requirements), from the root of a checkout, where the package directory is tools/trust/:

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

The script writes only under the optional scratch directory, a temporary one by default. It 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$ and confirm the certificate of every pivot row with the separate checker. They then corrupt a multiplier, a coefficient and a recorded elimination factor in turn, and require exactly the affected certificates to fail.

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, 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 and a per-file results list whose failing entries carry a reason.

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

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. The stage 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)$.

Routines

The receipt module is run as python3 receipt/receipt.py with one of three subcommands. The other paths in the table are relative to tools/trust/.

CommandWhat it does
receipt.py verify --witness WChecks the certificates (files, globs or directories) against the system; --table adds the comparison with a claimed table
receipt.py emit --out DIRWrites certificates for an existing table, solving for the multipliers by a matrix-free Wiedemann iteration modulo $p$
receipt.py detectAudits the system and the declared master basis; reports one block for each of the alarms A1 to A4
sh selftest.sh [scratch]Runs the import guards and engine checksums, the receipt module's tests and the strata certificate tests
sh receipt/tests/run_tests.sh [OUT_DIR]Runs the receipt module's tests alone
python3 battery/battery.py <scratch>Runs the acceptance suite; each group of checks is paired with a deliberately broken copy that must fail
strata/corpus_bench.py --family F --staging DIR --workdir DIR --out DIR --ledger FILE --slices p:d:eta,...Runs the complete first check, from Kira's system files to the comparison; needs Kira; the first slice is the reference
lp_syz.py --stage {control,sec63,syz255}The first of the three syzygy reducers, for a three-loop family; reads the Kira table named by TRUST_LPSYZ_KTAB
lp_syz_431.py --stage {control,control452,probe,tower}The same method for a three-loop light-by-light sector: two controls, a probe stage and the full tower
lp_syz_prod.py --stage {screen,verify,build,cascade,lift2,exactfull} --tag TModular screen at several primes, Chinese-remainder lift of the violation rows, exact rank verification over the rationals
bessel_oracle2.py [result.json]High-precision Bessel-moment values of a four-line equal-mass banana, to test numerically whether reported violation rows vanish

The four engines in the last rows are in vendor/lpsyz/ and are run through load_vendored or run_vendored.

A receipt.py command reads the system in one of two ways:

Every command prints a JSON report. For verify and detect, --report FILE saves it; -q omits the per-file list of verify, and receipt.py <command> -h prints the remaining options. Except for emit from Kira, --table names a JSON object mapping each target column to its {column: value} row. With --table, verify also fails a row whose certificate holds but whose claimed coefficients differ.

A command exits 0 when everything passes, 1 when a row fails or an alarm fires, and 2 when an input cannot be read. emit gives each row one of the statuses CERTIFIED, CLAIM_MISMATCH (the system does not imply the claimed row; no certificate is written), SHELL_RESIDUAL and SOLVE_FAILED. The alarms of detect are:

The Python package is loaded with import trust after adding tools/trust to sys.path. The modules oracle_k2disp and witness_bridge are imported by name, as in from trust import oracle_k2disp.

FunctionWhat it returns
verify()A dictionary with vendor_ok, vendor_bad, linked_missing and linked_drift; raises VendorTamperError if a file under vendor/ changed
load_vendored(name), run_vendored(name, args)A bundled engine loaded in-process, or run as an isolated child process under TRUST_OUT_ROOT, after a checksum check
out_root()The validated TRUST_OUT_ROOT, or OutputRootError
strata.load(), strata.certify(), strata.fp_eliminate()The strata package and its certificate and eliminator modules, imported in place; TRUST_STRATA_ROOT selects an external copy
receipt.core(), receipt.winnow_core(), receipt.winnow(), receipt.byte_identity()The receipt checker (TRUST_RECEIPT_ROOT selects an external copy), Winnow's copy and Winnow itself (both need TRUST_IBPLAPPER_ROOT), and their byte-identity check
oracle_k2disp.parse_kira_table(path), oracle_k2disp.eval_coeff(ex, d0, eta0)The table parsed under the restricted grammar; the exact value of one coefficient, refused if a denominator vanishes at the point
oracle_k2disp.reduce_and_compare(table_path, d0, eta0)A dictionary with n_targets, n_violations, n_match, sigma and per-target details; raises on an empty table or an absent target
witness_bridge.emit_lpsyz_witness(path, rows_modp, target_col, c_modp, p, ...)Writes a version 1.0 certificate over the syzygy relation rows; raises ValueError if the claimed row does not follow
fraction_oracle.rref, reduce_column, verify_witness_combination, spot_check_rowsExact Fraction row reduction, single-column reduction, a multiplier check over the rationals and a hash-seeded row sample

In the result of reduce_and_compare, sigma is the sign convention under which every target matched, or None, and details lists any differing coefficients. The two reductions of fraction_oracle raise OracleBoundExceeded above their size bound.

The files of the receipt module can also be imported directly, after adding receipt/ to sys.path.

FunctionWhat it returns
core.py: load_witness, load_system_jsonl, verify_row, verify_manyCertificates and systems read from file; (passed, detail) for one certificate and (rc, report) for many
emitter.py: emit_for_target(record, lam, minpoly) with the status in record["status"]; needs NumPy
detector.py: detect(alarm, report) for the four alarms
shim.py: ReceiptSession, ReceiptSession.from_strataA session on generic rows or on staged Kira files, with methods .emit, .verify and .audit
adapters/strata.py: load_rowsA staged Kira system at one point and prime; needs the strata tree, ../strata or RECEIPT_STRATA_PATH

In core.py, detail["reason"] says why a row failed, and an unreadable or incomplete file raises MalformedInput. The LAYOUT section of MANUAL.md in the package lists the other files, those of strata/ included.

Requirements

Source and references

The code is tools/trust/ in the BootLoops repository: trust/ is the package, receipt/ the certificate module, strata/ the code of the first check, vendor/lpsyz/ the bundled syzygy engines and battery/ the acceptance suite. Related public programs that derive relations from syzygies in a parametric representation are CALICO by Bertolini, Fontana and Peraro (arXiv:2506.13653) and the file Magic-Test.m of Crisanti, Frellesvig, Pokraka and Smith (arXiv:2605.29789).

ReferenceWhat it supplies
R. N. Lee and A. A. Pomeransky, JHEP 11 (2013) 165, arXiv:1308.6676The Lee–Pomeransky representation used by the third check
T. Bitoun, C. Bogner, R. P. Klausen and E. Panzer, Lett. Math. Phys. 109 (2019) 497, arXiv:1712.09215Integration-by-parts identities from syzygies of the polynomial and its derivatives
Chen, arXiv:1902.10387; Chen and Wang, arXiv:2303.09864The boundary terms that send an identity to the subsectors
P. Maierhöfer, J. Usovitsch and P. Uwer, arXiv:1705.05610; J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, arXiv:2008.06494Kira, the reduction program whose system files and tables Trust checks
F. Lange, J. Usovitsch and Z. Wu, arXiv:2505.20197Kira 3
R. H. Lewis, FermatThe program Kira runs for back-substitution in the first check
J. Klappert and F. Lange, arXiv:1904.00009; J. Klappert, S. Y. Klein and F. Lange, arXiv:2004.01463FireFly, as released inside Kira
W. Decker, G.-M. Greuel, G. Pfister and H. Schönemann, SingularThe syzygy modules of the third check
W. Hart, F. Johansson, A. Ahlbäck and the FLINT developers, FLINT, through python-flint (F. Johansson, O. Benjamin and contributors)The exact linear algebra of the third check
K. G. Chetyrkin and F. V. Tkachov, Nucl. Phys. B 192 (1981) 159; F. V. Tkachov, Phys. Lett. B 100 (1981) 65The integration-by-parts identity of the identity generator in the first check
S. Laporta, Int. J. Mod. Phys. A 15 (2000) 5087, hep-ph/0102033The elimination order
A. von Manteuffel and R. M. Schabinger, Phys. Lett. B 744 (2015) 101, arXiv:1406.4513; T. Peraro, JHEP 12 (2016) 030, arXiv:1608.01902Reduction over finite fields, the kind of table the certificates are for
D. Wiedemann, IEEE Trans. Inf. Theory 32 (1986) 54; Berlekamp (1968) and Massey (1969); Kaltofen and Saunders (1991)The sparse solver of emit, with its minimal-polynomial step and its preconditioning
McConnell, Mehlhorn, Näher and Schweitzer, Comput. Sci. Rev. 5 (2011) 119Certifying algorithms, the idea behind a certificate for each row

← back to the tools index