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.
- Second solve. The
strata/part of the package re-solves the linear system Kira generated with its own modular eliminator and compares with Kira's full-table output. It does so at several chosen points $(p, d, \eta)$: a prime $p$ and numerical values of the dimension $d$ and of $\eta$, the two variables of the coefficients. It also reduces fresh identities from a separate IBP generator against the solved table, where every one must vanish, and confirms that deliberately corrupted rows are rejected. - Certificates. Each row gets a certificate, a sparse vector of multipliers that satisfies the identity below. The receipt module (
tools/trust/receipt/, described below) writes and verifies the certificates. Its checker uses only the Python standard library and imports no solver code. - Syzygy reduction. The third check builds the Lee–Pomeransky polynomial of each sector (a subset of the propagators of the family, the others removed) 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 check detects extra linear relations among the declared masters, which the first two cannot. Such relations make a table non-unique without making any single row look wrong.
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:
- Bundled engines. The engine scripts under
vendor/are checksummed, andtrust.verify()raisesVendorTamperErroron any change. A change in thereceipt/orstrata/trees is printed as an advisory and never raises. - Environment.
import trustraisesEnvPoisonErrorwhenPYTHONPATH,PYTHONSTARTUPorPYTHONHOMEis set (run Python with-Eor-I). It raisesStdlibShadowErrorwhen a standard-library module was loaded from outside the interpreter's own directories. - Output directory. Calls that write files need
TRUST_OUT_ROOTset to an absolute scratch directory of your choice, outside/homeand the package tree. By default it must lie under/tmpor/var/tmp;TRUST_ALLOWED_OUT_ROOTSandTRUST_DENY_ROOTSchange the allowed and denied prefixes. - Table text. Kira table text is parsed with a restricted rational-function grammar, never with
evalorsympify. Anything outside the grammar stops the parse with an error naming the line.
Trust has these 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 a question for
detectand for your knowledge of where the system came from. emitsolves one sparse linear system for every row and prime, so large tables are certified on a chosen sample of rows.- The syzygy check is for spot checks, because the Singular step is slow 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_comparetakes the path of your table, andlp_syz.pyreads its table path fromTRUST_LPSYZ_KTAB. - The receipt checker imports no solver code, but the
strataadapter parses rows with strata's own loader. For a check that has no code in common with the reduction, write the rows to JSONL with your own parser or reimplement the checker fromWITNESS_FORMAT.md.
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/.
| Command | What it does |
|---|---|
receipt.py verify --witness W | Checks the certificates (files, globs or directories) against the system; --table adds the comparison with a claimed table |
receipt.py emit --out DIR | Writes certificates for an existing table, solving for the multipliers by a matrix-free Wiedemann iteration modulo $p$ |
receipt.py detect | Audits 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 T | Modular 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:
- From any program:
--system-jsonl FILE, a JSONL file from your own parser with one sparse row per line, mapping an integer column id to its value mod $p$.emitanddetectalso take--p PRIME;verifyreads the prime from each certificate. Hereemitcertifies one--target-colgiven--pivots(a JSON column list), anddetecttakes--masters. - From Kira:
--adapter strata --system-dir DIR --staging DIR --family NAME.emitanddetecttake the primes and points in--slices p:d:eta,...(detectuses the first);verifyreads them from each certificate. Hereemitcertifies the rows of the Kira table file named by--table.
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:
- A1 (
A1_master_relations): relations among the declared masters. - A2 (
A2_pseudo_masters): undeclared columns that survive elimination as if they were masters. - A3 (
A3_uncovered_targets): requested targets that no chain of identities reaches. - A4 (
A4_foreign_support): table rows with coefficients outside the declared basis.
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.
| Function | What 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_rows | Exact 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.
| Function | What it returns |
|---|---|
core.py: load_witness, load_system_jsonl, verify_row, verify_many | Certificates 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_strata | A session on generic rows or on staged Kira files, with methods .emit, .verify and .audit |
adapters/strata.py: load_rows | A 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
- Runs on: Python 3 with sympy. The package itself runs from a checkout of the repository and needs no installation.
- Syzygy engines: python-flint and Singular; mpmath for the Bessel script.
- Receipt module: NumPy for
emit,shim.pyand the tests. The checker, the audit, andverifyanddetecton JSONL systems use only the standard library. - First check in full: Kira with the Fermat backend.
strata/certify.pyneeds NumPy, and the strata tests need pytest. - Self-test:
sh tools/trust/selftest.sh [scratch], from any directory, ends withTRUST SELFTEST: ALL LEGS PASS. Its third part is skipped, with a message saying so, when pytest or NumPy is missing. - Receipt tests alone:
sh tools/trust/receipt/tests/run_tests.sh [OUT_DIR]ends withRECEIPT TEST BATTERY: ALL PASS, in well under a minute on one core without the archived part. The part that replays archived tables prints a skip unlessRECEIPT_BANKED_ROOTpoints at them. - Acceptance suite:
python3 battery/battery.py <scratch>, run from a scratch directory with noPYTHON*variables set. A few of its checks read reference tables that are not in the repository and report a named skip.
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).
| Reference | What it supplies |
|---|---|
| R. N. Lee and A. A. Pomeransky, JHEP 11 (2013) 165, arXiv:1308.6676 | The 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.09215 | Integration-by-parts identities from syzygies of the polynomial and its derivatives |
| Chen, arXiv:1902.10387; Chen and Wang, arXiv:2303.09864 | The 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.06494 | Kira, the reduction program whose system files and tables Trust checks |
| F. Lange, J. Usovitsch and Z. Wu, arXiv:2505.20197 | Kira 3 |
| R. H. Lewis, Fermat | The 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.01463 | FireFly, as released inside Kira |
| W. Decker, G.-M. Greuel, G. Pfister and H. Schönemann, Singular | The 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) 65 | The integration-by-parts identity of the identity generator in the first check |
| S. Laporta, Int. J. Mod. Phys. A 15 (2000) 5087, hep-ph/0102033 | The 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.01902 | Reduction 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) 119 | Certifying algorithms, the idea behind a certificate for each row |