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 packageSourceAuthors
The bridge pld_bridge.jl, which calls getPLD of PLD.jl at run time (PLD.jl is not included)PLD.jlC. 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.jlC. Fevola, S. Mizera and S. Telen
New code for the method of their papers: the numerical check and the Gröbner backendarXiv:2311.16219, arXiv:2109.08036Method by Fevola, Mizera and Telen and by Mizera and Telen; code by Claude
New code for published methods: the fitting library LandauAlphabet.jlarXiv:2507.17815 for the fits, arXiv:1704.08895 for the modular kernelsMethods 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 enginearXiv:2311.16219 for the face-by-face determinant, arXiv:2410.02424 for the letter classesMethod 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.

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:

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

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

FunctionWhat 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_K3The preset worldline families

The fitting library is the module LandauAlphabet in LandauAlphabet.jl/src/.

FunctionWhat it provides
words_of_weight, lyndon_words, shuffle_productWord combinatorics for weight-graded ansätze
ItIntEvaluator, DlogKernel, SeriesKernel, eval_word; GPLContext, gpl, basis_towerIterated-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_contextExact $q$-series and the $\Gamma_1(6)$ kernels of the sunrise family
cusp_value_E, cusp_value_B2K, cusp_values_level6Exact Eisenstein cusp values over $\mathbb{Q}(\sqrt{-3})$
symbol_alphabet, integrable_symbolsIntegrable symbols of given weight over a multivariate dlog alphabet
ConstraintSystem, add_constraint!, reduce_space, solution_dimExact linear constraints and their solution space
lattice_fit, fit_residual, integer_relationLLL coefficient fit with a height bound, full-precision residual check, single-point integer relations
AmflowFamily, amflow_run, amflow_sampleHigh-precision samples from amflow_cli, keeping only digits on which two precision goals agree
cauchy_coeffs, sunrise_boundary_constantsTaylor 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

Requirements

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.

ReferenceWhat it supplies
H. S. Hannesdottir, A. J. McLeod, M. D. Schwartz and C. Vergu, arXiv:2410.02424The 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.jlThe 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.08036The 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.17815Analytic regression, the method of the fits in LandauAlphabet.jl
L. Adams and S. Weinzierl, arXiv:1704.08895The conventions for the $\Gamma_1(6)$ modular kernels and the iterated integrals
D. Brammer, H. Frellesvig, R. Morales and M. Wilhelm, arXiv:2505.10274The polynomial $Q_6$ of the preset apery
T. Ahmed, E. Chaubey, M. Kaur and S. Maggio, arXiv:2402.07311The momentum routing of the topbox specification
P. Breiding and S. Timme, HomotopyContinuation.jl, arXiv:1711.10911The solver of the numerical check
J. Berthomieu, C. Eder and M. Safey El Din, msolve, arXiv:2104.03572; the Singular team, SingularThe Gröbner bases of the backend

← back to the tools index