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 packageSourceAuthors
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.jlC. 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.pysrc/QuadForm/Enumeration.jlThe same authors
New code: the rest of both files and the other modules of the packageWritten for BootLoopsCode 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.

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.

Census (census/) counts how many distinct vacua a flux sector contains once symmetries are divided out.

The shared library common/ holds the result records, the control entries, the registry of conventions and the ball comparisons.

The package has these limits:

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.

CommandWhat 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.pyRebuilds 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.

FunctionWhat 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_choiceThe route: matrix transport for point values; raises ScalarEliminationRefusal for a scalar elimination that was not probed or is over budget
opderive.find_operatorThe 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

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.

ReferenceWhat it supplies
C. Fieker, W. Hart, T. Hofmann and F. Johansson, ISSAC 2017, 157, arXiv:1705.06134; code: Hecke.jlThe 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-7The computer algebra system the Julia scripts run on
The PARI Group, PARI/GPThe 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.5The short-vector enumeration of lp_kill_rank_agnostic.py
Hosono, Klemm, Theisen and Yau, hep-th/9406055The method of Gopakumar–Vafa extraction
M. Demirtas, M. Kim, L. McAllister, J. Moritz and A. Rios-Tascon, arXiv:2107.09064The KKLT vacuum of the example card
I. Bena, J. Blåbäck, M. Graña and S. Lüst, arXiv:2010.10519The K3×K3 flux matrix used as a control
T. W. Grimm and D. van de Heisteeg, arXiv:2404.12422The Hulek–Verrill fourfold operators
M. Demirtas, M. Kim, L. McAllister and J. Moritz, arXiv:1912.10047The two-modulus example
The LMFDB Collaboration, LMFDBNewform coefficients

← back to the tools index