Terrier
Terrier is the BootLoops package for exact and certified computations about string-theory flux vacua, the solutions in which integer fluxes fix the shape of the compact space. It computes values of the periodsintegrals of the holomorphic top form over a basis of cycles; as functions of the moduli they satisfy a linear differential equation with polynomial coefficients, the Picard–Fuchs equation with proven radii, certified critical points of the flux superpotential, complete lists of lattice classes with exact certificates, and deduplicated counts of vacua. A computation the code cannot certify stops with a message instead of returning an approximation.
Where it comes from
Claus Fieker, Tommy Hofmann and the Hecke contributors wrote Hecke.jl, the Julia library that the lattice part of Terrier runs on. Parts of two files follow Hecke's code. The genus enumeration in lattice/genus_enum.jl is Hecke's traversal with the invariant and the isometry test replaced, and with the mass check done afterwards in PARI/GP. It calls Hecke's neighbor, theta-series and isometry routines when it runs. The short-vector search in lattice/lp_kill_rank_agnostic.py follows two of Hecke's conventions. Claude wrote both files with the Hecke source open.
| Part of the package | Source | Authors |
|---|---|---|
Adapted copy of their routine: the closures, the spinor-genus seeding and the neighbor loop of enumerate_aut_free in genus_enum.jl | _enumerate_definite_genus! in src/QuadForm/Quad/ZGenusRep.jl | C. Fieker, T. Hofmann and the Hecke contributors |
Conventions that follow their code: the search window and the output contract of short_vectors in lp_kill_rank_agnostic.py | src/QuadForm/Enumeration.jl | The same authors |
| New code: the rest of both files and the other modules of the package | Written for BootLoops | Code by Claude |
Please cite the Hecke paper when you use the lattice part. Terrier is not affiliated with or endorsed by the Hecke authors.
What it does
In a flux compactification the shape parameters (moduli) of the compact space are fixed by a superpotential $W$. It is an integer combination, chosen by the fluxes, of the periods of the space, and a vacuum is a critical point of $W$. Terrier has three parts, one for each kind of question. Everything that decides a result is exact integer or rational arithmetic, or interval (ball) arithmetic with an explicit radius.
Periods (periods/) decides whether a given flux has a critical point, where it is, and what $|W_0|$ is there. Its input is a card, a JSON file of exact rationals that defines a Calabi–Yau family.
- Series (
geffseries,gvderive). The code builds the Frobenius basis of series solutions at the large-complex-structure point. It extracts the Gopakumar–Vafa invariants (integer curve counts) by the method of Hosono, Klemm, Theisen and Yau. - Transport (
fluxcurves,transport). It restricts the basis to the one-parameter curve a flux selects and transports the solution vector along it in steps. Each step sums a truncated series and adds a proven bound on the discarded tail (the lemma inperiods/PROVEN_MAJORANT.md), so every value is a ball that contains the true value. - Critical point. Contracting with the flux in the integral symplectic frame gives $W$. The critical point is certified by the Krawczyk testan interval version of Newton's method: if the Krawczyk operator maps a box into its own interior, the box provably contains exactly one zero. The computation is repeated at two precisions and along two routes, which must agree.
- Harder families (
pfaffian,summation/). Matrix transport of $v' = A(s)\,v$ uses a connection reconstructed modulo primes. It refuses to eliminate to one high-order scalar equation unless a mod-$p$ probe shows that is affordable. Direct summation of the multivariate series at the target point is allowed only inside its proven convergence region. - Separate modules. Conifold charts (
conifold), finite-field period fingerprints for locating attractor points (ffp) and S-integrality candidate nets (sunit).
Lattices (lattice/) decides which integer fluxes inside a charge budget the lattice structure allows. For K3×K3 the admissible fluxes are governed by even integer lattices.
- Genus enumeration (
genus_enum.jl). The code enumerates every class in a genusthe set of lattices equivalent over the reals and modulo every prime power; it splits into finitely many integer isometry classes by Kneser's neighbor method, using Hecke.jl's traversal. It then proves the list complete by checking that $\sum 1/|\mathrm{Aut}|$ over the classes found equals the value of the mass formulaa formula that fixes the weighted count of the classes of a genus in advance exactly. - Root-freeness (
lp_kill_rank_agnostic.py). It decides root-freeness (no vectors of norm 2) by a linear program whose infeasibility comes back as an exact rational Farkas vector. - Embeddings (
nikulin.jl). It certifies primitive embeddings into the K3 lattice by Nikulin's discriminant-form criteria. - Forms and sweep (
lattice.jl,emit/). It reduces definite binary quadratic forms under SL(2,ℤ) exactly and runs the K3×K3 flux sweep as an exact predicate chain. Known-answer control entries are inserted at hash-determined positions, and the sweep must catch them. - Theta series (
lattice_theta.py). A standalone NumPy module evaluates floating-point theta series of $\mathbb{Z}^n$, $D_n$, $D_n^+$, $E_8$ and the Leech lattice, without certificates and without the K3 conventions of the rest oflattice/. It also has the Jacobi theta functions, a flatness factor and vectorized closest-vector routines.
Census (census/) counts how many distinct vacua a flux sector contains once symmetries are divided out.
- Orbits (
fold_hnf/). Raw flux pairs are grouped into SL(2,ℤ) orbits by a complete key (Hermite normal form plus a determinant sign). - Deduplication (
dedup/). Two separately written engines deduplicate the orbits under monodromy. Every merge comes with a word in the generators that a third, referee script verifies exactly, so a bounded search can under-merge but never over-merge. A disagreement between the engines is an error to be resolved with those witnesses, never a number to quote. - Distances and controls (
dist_cert/,control_sampler/). Later stages give exact rational distance certificates from certified vacuum positions to a fixed catalog of special loci. Control samples are drawn by exact-rational rejection sampling with Clopper–Pearson brackets. - Finiteness (
isd_cutoff/,tile_engine/). The finiteness cutoff is fixed before any count is made. Continuous regions are excluded tile by tile, and a tile with any missing certificate stays open.
The shared library common/ holds the result records, the control entries, the registry of conventions and the ball comparisons.
The package has these limits:
sunit.pygives a bounded candidate net, not a finiteness proof, and says so in the machine-readable truncation statement of every run.ffp.pyrefuses primes $\ge 2^{31}$ (BigPrimeRefusal) because its 64-bit integer arithmetic would overflow.nikulin.jlcertifies uniqueness at the glue level only.- Gopakumar–Vafa completeness is certified through a stated degree. The allowance beyond it is a labeled estimate, never part of a certified radius.
- The criterion constants in
census/dist_cert,control_samplerandtile_enginewere tuned to one specific ten-sector census. Do not reuse them elsewhere without validating them again. - For Feynman-integral differential equations at fixed $\epsilon$ use Wayfinder, not Terrier.
Examples
Run the tests. With the programs listed under Requirements installed, run from the package directory tools/terrier/:
python3 selftest.py # full run python3 selftest.py --only cards,receipts,certs # a subset of the tests (sections M and X always run)
The script first recomputes the SHA-256 of every stored fixture in regression_manifest.json; if a file is missing or changed it names the file, runs no test and exits with status 1. Otherwise it runs each registered test in its own process under a memory cap and prints PASS, FAIL or SKIP (named) for each. A named skip is a test whose reference data are not in the package.
A proven tail bound for a Frobenius series. The lines below are adapted from periods/selftest_envelope.py. They take the Picard–Fuchs operator of the two-loop sunrise integral, as coefficient lists of its polynomials, and bound the tail of its series solutions (run inside periods/):
from fractions import Fraction as Fr
from envelope_certified import theta_form, mum_jets, rational_roots, certify
R_sun, _ = theta_form([[-3, 1], [9, -20, 3], [0, 9, -10, 1]]) # coeffs[i][j] = [z^j] p_i(z)
b = mum_jets(R_sun, 0, 2, 160) # exact jets b_m, m = 0..160, log depth J = 2
lc, roots = rational_roots(R_sun[0]) # indicial polynomial: leading coeff, {root: multiplicity}
cert = certify(R_sun, 0, 2, b, 64, Fr(1, 2))
theta_form rewrites the operator in $\theta = z\,d/dz$ and mum_jets generates the coefficients as exact fractions. certify(R, e, J, jets, N, x) returns a dictionary in which ok says whether an admissible majorant parameter t with $t x \lt 1$ exists at truncation order N. If it does, tail is a proven upper bound, as an exact fraction, on $\sum_{m \gt N} \lVert b_m \rVert x^m$; if not, reason says why, for instance to raise N or shrink x.
An exclusion that must fail in the right way. The Venkov linear program is run on the control lattice $A_1^6$, where the correct answer is known:
python3 lattice/lp_kill_rank_agnostic.py control
The script reads the rank from the Gram matrix and finds the norm-2 vectors and dual-lattice shells exactly. It then sets up the linear program that a Niemeier embedding with Coxeter number $h = 2$ would have to satisfy, and prints one line. The strict program is KILLED, with an exact rational Farkas certificate obtained by rounding the dual solution and rechecking in Fraction arithmetic. The relaxed program without shell caps is FEASIBLE with its zero-projection variable equal to 36, and the line ends (expect 36).
Routines
The Python parts are modules to import, and the selftest_*.py script beside each module shows complete calls. The .jl scripts of the lattice part run in the Julia project named in TERRIER_JULIA_PROJECT; its .py files are Python.
| Command | What it does |
|---|---|
selftest.py [--only ID,...] | Checks the fixture hashes, runs the registered tests and checks that every test file is registered; nonzero exit on failure |
build_manifest.py | Rebuilds the fixture hashes; run it only after a full passing run of a tree you changed on purpose |
periods/pipeline/run_pipe.py <stage> | One stage of the KKLT benchmark replay; battery_dkmm.sh runs the stages in order |
lattice/nikulin.jl <mode> | Discriminant-form embedding certificates; modes pins, validate03, cert:<D>, certfile:<f> |
lattice/genus_enum.jl <det> <key16> [stop_after] | Kneser genus enumeration using Hecke.jl's traversal, with PARI mass and isometry checks |
lattice/genus_enum.jl --control <det> <key16> <reference_out.txt> | The same on a control genus, which must reproduce a stored enumeration class by class |
lattice/lp_kill_rank_agnostic.py <key> <hecke_out> <dst> | Venkov LP exclusion: complement classes of a genus in, one JSON record of kills and certificates out |
lattice/emit/harness.jl [mode] | The K3×K3 sweep engine; modes emit, controls, all (the default) |
lattice/emit/s11.jl [mode] | The second sweep engine; modes v1, v2, v3, mut, all (the default) |
common/dedup.py check <op> <spec>, common/dedup.py newform <label> | Known-point orbit deduplication; exit code 10 means a rediscovery, 0 no match |
The stages of run_pipe.py are listed at the top of that file.
| Function | What it returns |
|---|---|
cards.validate_card(path) | The parsed card, after the schema and exactness check; raises on any violation |
envelope_certified.certify, deriv_tail(cert, d) | The tail bound of the second example, and the bound for the $d$-th derivative |
pfaffian.route_choice | The route: matrix transport for point values; raises ScalarEliminationRefusal for a scalar elimination that was not probed or is over budget |
opderive.find_operator | The derived operator, after an exact annihilation check; the engine is Annihilator |
sweepchassis.Chassis (run, replay, clear_halt) | Generic sweep driver; returns 8 for a missed control entry or a failed integrity check, 9 while a halt is pending |
MODULE_MAP.md lists every module with its test. lattice/validate.jl runs the 18 checks of lattice.jl, and PFAFFIAN.md describes the stages of matrix transport.
Requirements
- Runs on: Python 3 with mpmath, sympy, numpy, scipy and python-flint.
- Lattice part: Julia 1.10 with an Oscar/Hecke project named in
TERRIER_JULIA_PROJECT, forlattice/*.jl, and PARI/GP forgenus_enum.jl. Until the variable is set, the Julia tests are named skips. - Install: no installation step. Run from the package root, inside a checkout of the repository:
periods/opderive.pyuses the Annihilator package intools/annihilator/. - Self-test:
python3 selftest.pyexits 0 when every test printedPASSorSKIP (named). As distributed, the full run finishes in well under a minute. - Reference data: large reference data are not in the package.
run_pipe.py, thevalidate03andcert:modes ofnikulin.jl, andtile_engine.pyneed them. Each test or script reads the location from an environment variable; without it a test prints a named skip and a script stops with a message. The README lists the variables under "Environment". - Fixtures: do not edit the checksummed copies under
periods/pipeline/,census/andlattice/in place, or the fixture hashes fail.
Source and references
The code is tools/terrier/ in the BootLoops repository. The example cards and controls transcribe published values, each cited in the file that holds it.
| Reference | What it supplies |
|---|---|
| C. Fieker, W. Hart, T. Hofmann and F. Johansson, ISSAC 2017, 157, arXiv:1705.06134; code: Hecke.jl | The traversal of the genus enumeration, two conventions of the short-vector search, and the lattice routines the Julia scripts call |
| The OSCAR team, OSCAR, doi:10.1007/978-3-031-62127-7 | The computer algebra system the Julia scripts run on |
| The PARI Group, PARI/GP | The automorphism counts, isometry tests and minimal norms of genus_enum.jl |
| U. Fincke and M. Pohst, Math. Comp. 44 (1985) 463; H. Cohen, A Course in Computational Algebraic Number Theory, Algorithm 2.7.5 | The short-vector enumeration of lp_kill_rank_agnostic.py |
| Hosono, Klemm, Theisen and Yau, hep-th/9406055 | The method of Gopakumar–Vafa extraction |
| M. Demirtas, M. Kim, L. McAllister, J. Moritz and A. Rios-Tascon, arXiv:2107.09064 | The KKLT vacuum of the example card |
| I. Bena, J. Blåbäck, M. Graña and S. Lüst, arXiv:2010.10519 | The K3×K3 flux matrix used as a control |
| T. W. Grimm and D. van de Heisteeg, arXiv:2404.12422 | The Hulek–Verrill fourfold operators |
| M. Demirtas, M. Kim, L. McAllister and J. Moritz, arXiv:1912.10047 | The two-modulus example |
| The LMFDB Collaboration, LMFDB | Newform coefficients |