Landau Alphabet
Landau Alphabet takes a Feynman graph (edges, internal masses, external kinematics) and returns the Landau singularities of its integral: the polynomials in the kinematic invariants on whose zeros the integral can be singular. It sorts them into the letter classesa letter is one of the polynomials whose logarithms the answer is built from; its class says where in the answer it may appear of the Landau bootstrap of Hannesdottir, McLeod, Schwartz and Vergu (arXiv:2410.02424) and states whether the list is proven complete. The face-by-face computation follows the principal Landau determinantthe discriminants in the kinematic variables obtained by eliminating the Feynman parameters face by face on a polytope attached to the graph polynomials; their irreducible factors are the candidate letters of Fevola, Mizera and Telen, whose program PLD.jl the package can run on the same input.
Where it comes from
The principal Landau determinant and the program PLD.jl are by C. Fevola, S. Mizera and S. Telen, and the Landau discriminant is by S. Mizera and S. Telen. The Gröbner backend and the numerical check implement steps of both papers: saturation (the removal of solutions with a vanishing parameter) followed by elimination, and the critical-point equations on a line. The code of the package was written by Claude. The bridge and the numerical check were written with the PLD.jl source open.
| Part of the package | Source | Authors |
|---|---|---|
The bridge pld_bridge.jl, which calls getPLD of PLD.jl at run time (PLD.jl is not included) | PLD.jl | C. Fevola, S. Mizera and S. Telen |
| Lines of the numerical check that follow their code: the tolerance value for merging duplicate solutions (about four lines) | PLD.jl | C. Fevola, S. Mizera and S. Telen |
| New code for the method of their papers: the numerical check and the Gröbner backend | arXiv:2311.16219, arXiv:2109.08036 | Method by Fevola, Mizera and Telen and by Mizera and Telen; code by Claude |
New code for published methods: the fitting library LandauAlphabet.jl | arXiv:2507.17815 for the fits, arXiv:1704.08895 for the modular kernels | Methods by Barrera, Dersy, Husain, Schwartz and Zhang and by Adams and Weinzierl; code by Claude |
| New code: the face engine, the auditor and the linear-propagator engine | arXiv:2311.16219 for the face-by-face determinant, arXiv:2410.02424 for the letter classes | Method by Fevola, Mizera and Telen; letter classes by Hannesdottir, McLeod, Schwartz and Vergu; code by Claude |
Please cite the authors' papers when you use the package. Landau Alphabet is not affiliated with or endorsed by the authors of PLD.jl.
What it does
A Feynman integral can have a branch point only where the Landau equations hold, that is, where the integration contour is trapped between singularities of the integrand. In Feynman parameters this is a polynomial condition. For every sub-graph, or facea subset of the graph's edges; the integral's singularities are the union of those associated with each subset, so the analysis runs over all of them, the Symanzik polynomialone of the two graph polynomials U and F of the Feynman-parameter integrand, fixed by the graph's spanning trees, masses and invariants $F$ and all its derivatives with respect to the parameters must vanish together. Singularities of the second type come from $U$ in the same way.
Eliminating the parameters leaves polynomials in the invariants alone. Their irreducible factors, collected over all faces, are the Landau letters. For a polylogarithmic integral this set is the symbol alphabetthe finite list of functions of the kinematics whose logarithms the answer is built from; knowing it in advance turns the calculation into finite linear algebra. The output file is read directly by Ansatzer, which counts how many unknowns an ansatz (a trial sum of functions with unknown coefficients) over it leaves.
The package has seven parts.
- Face engine.
landau_alphabet.pyreads a small JSON graph specification, enumerates the faces, builds $U$ and $F$ for each, and eliminates the parameters with a chain of resultants under a hard per-face time limit. All algebra is exact (sympy). The output file is rewritten after every face, so an interrupted run keeps what it has. - Auditor.
audit_faces.pyre-checks any output file against a face count that it computes itself from the graph. - Gröbner backend. Resultant chains grow uncontrollably on high-degree faces. When msolve or Singular is installed, a face that times out or comes back partial goes to
pld_groebner_backend.py. It removes solutions with a vanishing parameter (saturation), eliminates the parameters with a Gröbner basis (msolve, then Singular, then sympy) and factors what remains. - PLD.jl bridge.
pld_bridge.jlruns PLD.jl on the same specification and writes the same output format, so the two computations can be compared. - Numerical check. When PLD.jl and Oscar cannot be loaded (or with
--fallback), the bridge runs a check that needs only HomotopyContinuation.jl. For each face it restricts the polynomial $U+F$ to a randomly seeded straight line through the space of invariants and solves the critical-point equations by homotopy continuation. The solutions are numerical witness points of the singular surfaces. - Linear-propagator engine.
linear_landau.pycovers families in which some propagators are linear in the loop momenta, $2u\cdot k$, as in the post-Minkowskian expansion of gravitational scattering, heavy-quark effective theory and eikonal limits. Such propagators have no graph edge, so $U$ and $F$ are built by completing the square in the loop momenta. - Fitting library.
LandauAlphabet.jlbuilds candidate functions as weight-graded iterated integrals (words) over the letters and assembles exact linear constraints on their rational coefficients. It evaluates the basis in high-precision ball arithmetic (every number carries a proven error radius) and fixes the coefficients by lattice reduction. A fit is accepted only if the coefficients are small rationals and the residual vanishes at full precision, also at points not used in the fit. Kernels are either dlog forms (multiple polylogarithms) or the $\Gamma_1(6)$ modular forms of the equal-mass sunrise.
The output of the face engine lists alphabet, first_entry, last_entry, spurious (dropped factors), one record per face, and an honesty block. First-entry letters come from codimension-one solutions of $F$ and the bare invariants: they are the physical thresholds, the only letters allowed in a symbol's first slot. Last-entry letters arise only from $U$.
The top-level complete flag is true only if every face was attempted, none timed out or was resolved only partly, and the deadline was not reached. Otherwise honesty.unresolved_faces lists the sub-graphs that need a longer timeout or a heavier backend.
The package has these limits:
- Faces are enumerated as connected sub-graphs. On graphs with more than four vertices a two-particle cut can be a disconnected sub-graph, which is skipped, so letters of the $s-4m^2$ type can be missed there. Four-vertex graphs such as the three-loop $K_4$ box are unaffected.
- A comparison with PLD.jl may need relabeling, because PLD.jl names the Mandelstam invariants itself. Its faces are those of the Newton polytopethe convex hull of the exponent vectors of the monomials of a polynomial of $U+F$, not the sub-graphs used here.
- The alphabet is pruned of second-type letters, so it can be shorter than the output of PLD.jl. For the one-loop massless box the face engine returns $s$ and $t$, and the database of PLD.jl lists $s$, $s+t$ and $t$.
- The numerical check confirms letters and cannot certify completeness, so it always writes
complete: false. Its witnesses are interior pinches. They include second-type surfaces the pruned alphabet omits (on the massless box, $s+t$) and never include letters such as $s$ and $t$ that multiply a whole face polynomial. - The Gröbner backend returns a face's complete Landau variety, non-physical branches included. Classification and pruning are done by
landau_alphabet.py. - The elimination in
linear_landau.pyover-generates candidates.verify_lettertests each against a saturated Gröbner elimination ideal, and only verified letters belong in the alphabet.
Leviathan finds the same singularities by a different method, a count of master integrals, and serves as a cross-check. The series evaluator of the fitting library underlies GPLEval.
Examples
Compute and audit the alphabet of the three-loop crossed light-by-light box. The specification graph_specs/k4box3l.json comes with the package: four massive perimeter lines, two massless diagonals, four massless legs, invariants s, t, m2. It is the crossed massive box of the three-loop light-by-light family and the hardest regression test of the face engine. With the package set up (see Requirements), run from the package directory tools/landau-alphabet/:
# sympy backend python landau_alphabet.py graph_specs/k4box3l.json --out k4box3l_alphabet.json --face-timeout 45 # audit any output for silently-dropped faces (exit 2 on a silent drop) python audit_faces.py k4box3l_alphabet.json
The first command prints the alphabet, the first_entry, last_entry and spurious lists, and a tally of resolved, partial and timed-out faces. It ends with COMPLETE: True or COMPLETE: False ** alphabet NOT proven complete ** followed by the unresolved faces; the JSON holds the same data.
This graph has 54 faces and the known alphabet $\{s,\ t,\ s+t,\ s-4m^2,\ t-4m^2,\ st-4m^2(s+t)\}$. Four faces are hard (the whole graph and three five-edge sub-boxes). With msolve or Singular installed the Gröbner backend resolves them; without, a 45-second timeout leaves them unresolved and the run correctly reports complete: false. The faces that time out are generally where the missing letters are, so dropping them is not a fix.
The same from Python. The included two-loop non-planar topbox graph is a ring of four massive lines and a chain of three massless ones, from the $gg\to Z\gamma$ family. Run from landau_alphabet import load_spec, run, then gs = load_spec("graph_specs/topbox.json") and log = run(gs, out_path="topbox_alphabet.json", face_timeout=45). Then read log["alphabet"], log["first_entry"] and log["honesty"].
Check an alphabet numerically. First make the candidate file with python landau_alphabet.py graph_specs/box1l.json --out box1l_alphabet.json. The command julia pld_bridge.jl graph_specs/box1l.json box1l_hc.json --fallback --check box1l_alphabet.json --seed 0 runs the numerical check on the one-loop massless box. Every witness must lie on a candidate letter taken from the --check file. The exit code is 0 if every witness matches and 2 if one matches no candidate. With the output of the face engine as the --check file, the witness on $s+t$ matches no candidate. With s + t added to the candidates, every witness matches.
Letters of a family with worldline propagators. The one-loop integral with propagators $k^2$, $(k-q)^2$, $2u_1\cdot k$, $2u_2\cdot k$ and $u_1^2=u_2^2=1$, $u_1\cdot u_2=y$, $u_i\cdot q=0$ is the preset family_2PM_box:
import linear_landau as LL res = LL.landau_locus_mixed(*LL.family_2PM_box()) ax = LL.pm_alphabet_x(res["alphabet"])
res["U"] and res["F"] are $a_1+a_2$ and $a_1a_2q^2-a_3^2-2y\,a_3a_4-a_4^2$, and res["alphabet"] is {q2, y - 1, y + 1}. ax is the alphabet in $x$, where $y=(1+x^2)/(2x)$: {x, x - 1, x + 1}. python linear_landau.py 2PM_box prints the same.
The preset apery prints the discriminant factors in $x$ of the Apéry K3 leading-singularity surface: $x$, $x\pm1$ and $x^2\mp6x+1$. The surface is the polynomial $Q_6$ of D. Brammer, H. Frellesvig, R. Morales and M. Wilhelm (arXiv:2505.10274). The product of the two quadratics, $x^4-34x^2+1$, has the physical root $x=3-2\sqrt2$, which is $y=\gamma=3$. The black-hole scattering page gives the same discriminant.
Routines
| Command | What it does |
|---|---|
python landau_alphabet.py SPEC.json [--out OUT.json] [--face-timeout S] [--global-minutes M] [--min-face-edges N] [-v] | Alphabet of a graph specification |
python audit_faces.py FILE... [--spec SPEC.json] [--glob PATTERN] [--strict] | Recounts the expected faces and checks every completeness claim |
python pld_groebner_backend.py FACE_UF.json [--field s,t,m2] [--backend NAME] [--threads 8] [--timeout 900] [--out OUT.json] | Letters of every face in a face file, by saturated Gröbner elimination |
julia pld_bridge.jl SPEC.json OUT.json [--method METHOD] | Runs getPLD of PLD.jl and writes the output format of the face engine |
julia pld_bridge.jl SPEC.json OUT.json --fallback [--check CANDIDATES.json] [--seed N] [--tol X] | The numerical check: witness points per face, matched against the candidate letters |
python linear_landau.py [PRESET] [--json-out FILE] | Runs a preset family and prints $U$, $F$ and the alphabet in $y$ and $x$ |
NAME is auto, msolve, singular or sympy; METHOD is sym or num; PRESET is 2PM_tri, 2PM_box, 3PM_H, 3PM_IY, 4PM_K3 or apery. audit_faces.py exits with code 0 if every file is consistent, 2 if faces are missing or unresolved while a file claims to be complete, and 3 if a claim cannot be verified (only with --strict).
The bridge writes complete: false if PLD.jl errors part-way. --codim_start, --face_start, --load_output and --save_output pass through PLD.jl's resume options. In the numerical check, --seed fixes the line and --tol the matching tolerance. The --check file is an output of landau_alphabet.py or any JSON with an alphabet list; its alphabet, spurious and per-face lists are pooled. The output of the check carries t_witnesses per face and honesty.unmatched_witnesses.
The Python functions are in landau_alphabet.py, pld_groebner_backend.py and linear_landau.py. In a signature, the arguments after * are optional and are passed by keyword, as in run(gs, face_timeout=45). The lower-level functions of the face engine are listed in the package README.md.
| Function | What it returns |
|---|---|
load_spec(path_or_dict), run(gs, *, out_path, face_timeout, global_minutes, min_face_edges) | The graph specification; the output dictionary of a full run |
face_letters(F, fvars, kinvars, *, backend, threads, timeout) | letters, status, backend and elim_gens for one face polynomial, by saturated Gröbner elimination |
symanzik_mixed(quad, lin, loops, ext, repl), landau_locus_mixed(quad, lin, loops, ext, repl) | $U$, $F$, the parameter symbols and an auxiliary record; the face-by-face result U, F, alphabet, faces |
pm_alphabet_x(letters_y) | The letters rewritten from $y$ to $x$ |
verify_letter(F, alphas_face, letter, kinsyms) | True, False (a spurious factor produced by the elimination) or None (undecided in the time limit) |
apery_K3_landau_locus() | The discriminant factors in $x$ of the Apéry K3 leading-singularity surface |
family_2PM_tri, family_2PM_box, family_3PM_H, family_3PM_IY, family_4PM_K3 | The preset worldline families |
The fitting library is the module LandauAlphabet in LandauAlphabet.jl/src/.
| Function | What it provides |
|---|---|
words_of_weight, lyndon_words, shuffle_product | Word combinatorics for weight-graded ansätze |
ItIntEvaluator, DlogKernel, SeriesKernel, eval_word; GPLContext, gpl, basis_tower | Iterated-integral series evaluator, multiple polylogarithms in ball arithmetic, weight-graded bases of them |
eisenstein_E, eta_quotient_q2, B2K and the qs_* routines; sunrise_data, level6_basis, landau_weight2_candidates (also 3, 4), modular_context | Exact $q$-series and the $\Gamma_1(6)$ kernels of the sunrise family |
cusp_value_E, cusp_value_B2K, cusp_values_level6 | Exact Eisenstein cusp values over $\mathbb{Q}(\sqrt{-3})$ |
symbol_alphabet, integrable_symbols | Integrable symbols of given weight over a multivariate dlog alphabet |
ConstraintSystem, add_constraint!, reduce_space, solution_dim | Exact linear constraints and their solution space |
lattice_fit, fit_residual, integer_relation | LLL coefficient fit with a height bound, full-precision residual check, single-point integer relations |
AmflowFamily, amflow_run, amflow_sample | High-precision samples from amflow_cli, keeping only digits on which two precision goals agree |
cauchy_coeffs, sunrise_boundary_constants | Taylor coefficients by Cauchy integrals; the sunrise boundary constants at $t=0$ |
The package README.md also gives the input and output formats in full.
Used on this site
- Massless planar double box: fixed the two-letter alphabet $\{x,\,1+x\}$ from the Landau singularities of the graph.
- Three-loop ladder: fixed the two-letter alphabet $\{x,\,1+x\}$ from the singularities of the graph.
- One-loop massless pentagon: gave the 21 letters of the pentagon family from its Landau singularities.
Requirements
- Runs on: Python 3 with sympy, which is enough for the face engine, the auditor and the linear-propagator engine.
- Gröbner backend: msolve and/or Singular. msolve is always run through the memory-capped wrapper of Dipstick,
tools/dipstick/. The face engine calls the backend only when one of the two is installed. Run directly with neither, the backend falls back to sympy. - PLD.jl bridge: Julia with HomotopyContinuation.jl and JSON.jl. The full PLD.jl run also needs Julia 1.10 with PLD.jl and Oscar. PLD.jl comes from its authors, mathrepo.mis.mpg.de/PLD; see PLD and SOFIA. Without them, as on Julia 1.11 or newer, the bridge runs the numerical check.
- Fitting library: Julia 1.11 or newer with Nemo, Arblib and JSON3. Its sampling routines call
amflow_clibuilt from BootLoops'amflow-cppfork (onPATH, or named byAMFLOW_CLI; see AMFlow). - Install:
julia --project=LandauAlphabet.jl -e 'using Pkg; Pkg.instantiate()'installs the Julia packages of the fitting library. On a newer Julia minor version runPkg.resolve()first. - Optional: the environment variables
PLD_ENV(the Julia environment holding PLD.jl's dependencies) andPLD_SRC(a PLD.jl source checkout).PLD_GROEBNER(auto,offorforce) controls the hand-over from the face engine to the Gröbner backend, andMSOLVE_CAP_GBis the memory cap of the msolve wrapper. - Self-test: run the two commands below from the package directory.
python3 selftest.py python3 selftest.py --full
The first command takes seconds and ends with a line beginning fast battery PASS. Each check prints PASS or FAIL, and the exit code is nonzero on failure. The second command takes minutes and ends with a line beginning full battery PASS. It runs test_landau_alphabet.py, PYTHONHASHSEED=1 python test_linear_landau.py, the numerical check on box1l.json and the two Julia suites in LandauAlphabet.jl/test/. Missing msolve, Singular or Julia are reported as named skips, since they are external programs the Python face engine does not require.
Source and references
The code and its guide are tools/landau-alphabet/ in the BootLoops repository.
| Reference | What it supplies |
|---|---|
| H. S. Hannesdottir, A. J. McLeod, M. D. Schwartz and C. Vergu, arXiv:2410.02424 | The Landau bootstrap and its letter classes |
| C. Fevola, S. Mizera and S. Telen, "Principal Landau determinants", arXiv:2311.16219, and arXiv:2311.14669; code: PLD.jl | The principal Landau determinant, the method of the numerical check and of the Gröbner backend, and the program the bridge runs |
| S. Mizera and S. Telen, "Landau discriminants", arXiv:2109.08036 | The Landau discriminant, on which the numerical check and the Gröbner backend also draw |
| O. Barrera, A. Dersy, R. Husain, M. D. Schwartz and X. Zhang, arXiv:2507.17815 | Analytic regression, the method of the fits in LandauAlphabet.jl |
| L. Adams and S. Weinzierl, arXiv:1704.08895 | The conventions for the $\Gamma_1(6)$ modular kernels and the iterated integrals |
| D. Brammer, H. Frellesvig, R. Morales and M. Wilhelm, arXiv:2505.10274 | The polynomial $Q_6$ of the preset apery |
| T. Ahmed, E. Chaubey, M. Kaur and S. Maggio, arXiv:2402.07311 | The momentum routing of the topbox specification |
| P. Breiding and S. Timme, HomotopyContinuation.jl, arXiv:1711.10911 | The solver of the numerical check |
| J. Berthomieu, C. Eder and M. Safey El Din, msolve, arXiv:2104.03572; the Singular team, Singular | The Gröbner bases of the backend |