Terrier

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

Terrier is the BootLoops package for exact and certified computations about string-theory flux vacua. Its inputs are the defining data of a Calabi–Yau family (a JSON "card" of exact rationals), integer flux vectors, lattice Gram matrices and lists of flux configurations. Its outputs are period values as intervals 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.

What it does

In a flux compactification the shape parameters (moduli) of the compact space are fixed by a superpotential $W$, an integer combination, chosen by the fluxes, 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 of the space; a vacuum is a critical point of $W$. Terrier answers three kinds of question, one per part of the package. The periods part decides whether a given flux has a critical point, where it is, and what $|W_0|$ is there. The lattice part decides which integer fluxes inside a charge budget the lattice structure allows at all. The census part counts how many distinct vacua a flux sector contains once symmetries are divided out. Everything that decides a result is exact integer or rational arithmetic, or interval (ball) arithmetic with an explicit radius.

Periods (periods/). From a card the code builds the Frobenius basis of series solutions at the large-complex-structure point (extracting Gopakumar–Vafa invariants as it goes), restricts it to the one-parameter curve a flux selects, and transports the solution vector along that curve in steps. Each step sums a truncated series and adds a proven bound on the discarded tail (the lemma in periods/PROVEN_MAJORANT.md), so every value is a ball whose radius provably contains the truth. 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; and the computation is repeated at two precisions and along two routes, which must agree. For harder families there is matrix transport of $v' = A(s)\,v$ from a connection reconstructed modulo primes, which refuses to eliminate to one high-order scalar equation unless a mod-$p$ probe shows that is affordable. There is also direct summation of the multivariate series at the target point, allowed only inside its proven convergence region. Conifold charts, finite-field period fingerprints for locating attractor points, and S-integrality candidate nets are separate modules.

Lattices (lattice/). For K3×K3 the admissible fluxes are governed by even integer lattices. 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, then proves the list complete by checking that $\sum 1/|\mathrm{Aut}|$ over the classes found equals the mass formula exactly. It decides root-freeness (no vectors of norm 2) by a linear program whose infeasibility comes back as an exact rational Farkas vector, and certifies primitive embeddings into the K3 lattice by Nikulin's discriminant-form criteria. It also reduces definite binary quadratic forms under SL(2,ℤ) exactly and runs the K3×K3 flux sweep as an exact predicate chain, with known-answer control entries inserted at hash-determined positions that the sweep must catch. Two further modules work with finite quadratic modules (discriminant forms) exactly at large group order, and evaluate floating-point theta series of standard lattices.

Census (census/). Raw flux pairs are grouped into SL(2,ℤ) orbits by a complete key (Hermite normal form plus a determinant sign), then deduplicated under monodromy by two independently written engines. Every merge carries 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. Later stages give exact rational distance certificates from certified vacuum positions to a fixed catalog of special loci, and control samples drawn by exact-rational rejection sampling with Clopper–Pearson brackets. The finiteness cutoff is fixed before any count is made, and continuous regions are excluded tile by tile, a tile with any missing certificate staying open.

Limits. sunit.py gives a bounded candidate net, not a finiteness proof, and says so in its output. ffp.py refuses primes $\ge 2^{31}$ because its 64-bit integer arithmetic would overflow. nikulin.jl certifies uniqueness at the glue level only. Gopakumar–Vafa completeness is certified through a stated degree, and the allowance beyond it is a labeled estimate, never part of a certified radius. The criterion constants in census/dist_cert, control_sampler and tile_engine were tuned to one specific ten-sector census and should not be reused elsewhere without independent validation. For Feynman-integral differential equations at fixed $\epsilon$ use Wayfinder, not this.

Examples

Run the test suite. From the package root:

python3 selftest.py                               # full run
python3 selftest.py --only cards,receipts,certs   # a subset of the tests (sections M and X always run)

The suite first recomputes the SHA-256 of every stored fixture in regression_manifest.json and names any missing or changed file; in that case no test runs and the exit status is 1. It then runs each registered test in its own process under a memory cap, and checks that every selftest_* file on disk is registered. Each test prints PASS, FAIL or SKIP (named); a named skip means its reference data are not included in the package, and the line names the environment variable that supplies them. The Julia tests are named skips until TERRIER_JULIA_PROJECT points at a Julia project with Oscar/Hecke installed. As distributed, the full run finishes in well under a minute and exits 0.

A proven tail bound for a Frobenius series. Adapted from periods/selftest_envelope.py, the lines below 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: ok says whether an admissible majorant parameter t with $t x \lt 1$ exists at truncation order N, and tail is then a proven upper bound, as an exact fraction, on $\sum_{m \gt N} \lVert b_m \rVert x^m$. Otherwise ok is False and reason says to raise N or shrink x. deriv_tail(cert, d) bounds the tail of the $d$-th derivative.

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, finds the norm-2 vectors and dual-lattice shells exactly, and sets up the linear program that a Niemeier embedding with Coxeter number $h = 2$ would have to satisfy. It 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). lattice/selftest_lpkill_a1n_mustfail.py compares this line byte for byte with a stored reference copy (supplied through STRINGVAC_R18_DIR). Production use is lp_kill_rank_agnostic.py <key> <hecke_out> <dst>: complement classes of a genus in, one JSON record of kills and certificates out.

Routines

Suite

Periods (Python modules in periods/; the underlying code they call is in periods/pipeline/)

Lattices (Julia with Oscar/Hecke, plus Python)

Census (Python)

Shared library (common/)

Used on this site

Requirements and source

Python 3 with mpmath, sympy, numpy, scipy and python-flint; Julia with an Oscar/Hecke project named in TERRIER_JULIA_PROJECT for lattice/*.jl; PARI/GP for genus_enum.jl. annihilator_v2.py uses the Annihilator package from the same repository (tools/annihilator/). No installation step: run from the package root; python3 selftest.py runs the tests. Modules that compare against large reference data read its location from environment variables listed in selftest.py; the checksummed copies under periods/pipeline/, census/ and lattice/ must not be edited in place or the fixture hashes fail. The code is in tools/terrier/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license. The archive posted with the flux-vacua paper also includes the KKLT reference data, and omits the job-launch wrapper common/launch.py, the lattice/fqm/ module and the experimental OPTION_D/ folder.

← back to the tools index