GeoTriage
GeoTriage reads a Feynman graph and reports the geometry of its maximal cutthe integral with every propagator put on shell; what remains is a polynomial in a few leftover variables, and the curve or surface where it vanishes controls how hard the full integral is: a rational curve, an elliptic curve (and which one), a K3 surface, a Calabi–Yau space, or a curve of higher genus. From that it recommends how the integral should be computed, as a one-letter class A through E, and lists every assumption behind the verdict. It names an elliptic family from Beauville's list of modular elliptic surfaces and tests a K3 surface for complex multiplicationan extra arithmetic symmetry of an elliptic curve or K3 surface present only at special parameter values (CM) with Livné's criterion.
What it does
The cut polynomial defines a curve or surface. The functions and constants that can appear in the integral depend on the type of that variety. GeoTriage reads that type for one graph, before any numerical work. It does not evaluate or reduce any integral.
A short JSON description of the graph goes in and a JSON report comes out. The input lists the edges with their masses, the external legs at each vertex, and the kinematic invariants, in the schema the Landau Alphabet package uses. Two blocks are optional:
"maxcut": the known cut polynomial as a SymPy string (poly), its residual variables (vars), and the kinematic variable that parametrizes the family (modulus). Without it GeoTriage builds the second Symanzik polynomial from the graph itself."fiber_point": numerical values of the invariants for the arithmetic tests.
The classification goes by the number of residual variables, and then by the type found.
- One variable. The cut is a curve $y^2=P(z)$ and the genus is exact: 0 if the square-free degree $d$ of $P$ is at most 2, otherwise $\lfloor (d-1)/2\rfloor$.
- Two variables. The cut is reduced to a curve when a degree-two fibration or a plane cubic allows it, and is otherwise treated as K3.
- Three or more. The cut is classed as Calabi–Yau.
- Elliptic curve. GeoTriage computes the j-invariantthe number that labels an elliptic curve up to isomorphism; for a family depending on a kinematic variable t it is a rational function j(t) whose poles mark the singular fibers and reads the singular fibers off the poles of $j(t)$. It matches the sorted pole orders against Beauville's list to name the congruence subgroup and its level $N$.
- Complex multiplication (CM). The curve is flagged CM when $j$, at the fiber point if given, is one of the thirteen rational CM values. Point counts on the curve modulo small primes corroborate the verdict.
- K3 surface. Livné's criterion is applied to the integers $a_p$ that encode the number of solutions of the cut equation modulo each small prime $p$. If $a_p=0$ exactly at the primes where a quadratic character has $\chi_D(p)=-1$, the surface has CM by $\mathbb{Q}(\sqrt{D})$.
The K3 test is a proof only for the equal-mass three-loop banana, where the $a_p$ come from a known modular form. For any other K3 GeoTriage counts points on a banana-shaped model, subtracts a polynomial background fixed by exact arithmetic, and scans a short list of candidate discriminants $D$. A unique match is reported as a probe verdict with certified: false. When no background fits the counts, is_cm is left null.
The route field of the report is the recommendation.
| Route | Geometry | How to compute the integral |
|---|---|---|
| A | Genus 0, or CM elliptic | Fit a high-precision numerical evaluation against known constants such as multiple zeta values |
| B | Elliptic on $X_1(N)$ with $N\le 10$ or $N=12$, or K3 with CM | The same fit with one boundary constant added, an $L$-value named in ring_conductors (a Dirichlet $L$-value in the elliptic case) |
| C | Elliptic on none of those curves, or K3 whose CM status is open | A fit alone cannot succeed; solve the differential equations from a known boundary |
| D | Calabi–Yau, or K3 found to be non-CM | Transport the periods along the differential equation; no fit is attempted |
| E | Genus two or more | Beyond the routes the toolkit offers |
The criterion is proved in one direction only: a C verdict is firm, and an A or B verdict is a hypothesis that the later fit confirms or refutes.
Read the honesty field of the report first. GeoTriage has these limits:
genus_methodis"exact"or"degree-bound". A degree bound can over-report the genus, never under-report it.pf_order_certifiedis alwaysfalse. The Picard–Fuchs orderthe order of the differential equation in a kinematic variable that the cut integral satisfies: 2 for an elliptic curve, 3 for K3, 4 for a Calabi–Yau threefold is inferred from the genus or the number of residual variables, never from an operator actually constructed. Use Dipstick or Annihilator when it matters.caveatslists the remaining assumptions. A K3 CM verdict from the point-count probe always comes with a caveat saying it is not a theorem.- A "not modular" verdict rests on the fiber configuration and the degree of $j$, with no search at higher level.
- The automatic Symanzik model matches the true maximal cut only for banana- and vertex-type graphs, the sunrise included. For any other topology, supply
"maxcut".
To classify a cut polynomial by discriminant chains without a graph description, see Maxcut. GeoTriage is also the reference implementation behind the $p$-adic Frobenius boundary-constant method, which reads a boundary constant off the Picard–Fuchs operator reduced modulo primes. The Frobenius package is a different tool, for solutions at infinite mass.
Examples
Classify one graph from the command line. The ice-cream-cone fixture supplies its cut polynomial directly, $P=z(z-4)\,((z-w)^2-4tw)$ with residual variable $z$ and modulus $w$, and a fiber point {"w": 5, "t": 3}. With the package set up (see Requirements), run from the package directory tools/geotriage/:
python geotriage.py graph_specs/icc.json --out icc_classify.json
Without --out the report is printed instead of written. In the report variety.type is elliptic, and the fiber signature matches nothing in Beauville's list, so elliptic.level_N is null. cm.is_cm is false because $j$ at the fiber point is a non-integer rational, and route is C. honesty.caveats records that the polynomial was taken from the spec and that no higher-level modular curve was searched.
Call it from Python. The sunrise fixture has no "maxcut" block, so the polynomial is derived from the graph:
from geotriage import classify
rep = classify("graph_specs/sunrise_eq.json")
rep['route'] # 'B'
rep['elliptic'] # {j, kodaira, level_N, on_X1N, congruence_group, ...}
rep['honesty'] # {genus_method, cm_evidence, pf_order_certified, caveats}
rep['elliptic'] gives fiber_signature [1, 2, 3, 6], level_N 6 and congruence_group Gamma_1(6). rep['ring_conductors'] names $\chi_{-3}$, whose $L$-value is the boundary constant. classify also accepts a dict.
Run the self-test suite, from inside the package directory:
python test_geotriage.py
After its unit checks the script classifies six known cases: five fixtures from graph_specs/ and an unequal-mass four-edge banana defined inline. The expected verdicts are:
| Case | Geometry | Route |
|---|---|---|
| One-loop massless box | Genus 0 | A |
| Equal-mass sunrise | Elliptic with fiber signature (1, 2, 3, 6) on $\Gamma_1(6)$ | B |
| Ice-cream cone | Elliptic on no small $X_1(N)$ | C |
| Equal-mass three-loop banana | K3 with CM by $\mathbb{Q}(\sqrt{-15})$ | B |
| Three-loop crossed box | Genus 0 | A |
| Banana with masses (1, 1, 1, 2) | K3 with CM by $\mathbb{Q}(\sqrt{-3})$ from the probe | B with a not-certified caveat |
Routines
| Command | What it does |
|---|---|
python geotriage.py <spec.json> [--out FILE] [-v] | Classifies one graph and writes the report to FILE or prints it; -v prints it in either case |
python test_geotriage.py | Runs the self-test suite |
The Python functions are loaded with from geotriage import ....
| Function | What it returns |
|---|---|
classify(spec_or_path, verbose) | The report dict, after running every step |
baikov_maxcut(spec) | The cut polynomial of the top sector, from spec["maxcut"] or the second Symanzik polynomial |
classify_variety(mc) | Dimension, genus, type (polylog, elliptic, hyperelliptic, K3, CY3, ...), estimated Picard–Fuchs order, genus_method |
elliptic_invariants(P, var, modulus) | $j$, discriminant, Kodaira fibers, fiber_signature, level_N, on_X1N, congruence_group |
cm_check_elliptic(j_expr, modulus, fiber_point, pmax) | is_cm, discriminant_D, certified and the evidence, with point counts at primes up to pmax |
cm_check_K3(spec, mc, pmax, D_candidates) | is_cm, discriminant_D and the evidence, from Livné's test or the point-count probe |
k3_ap_probe(raw, D_candidates) | locked, background, resid, zero_density, matches, from raw K3 point counts keyed by prime |
closure_route(cls) | Route A to E with reason, ring_conductors, honesty |
Two helper modules check single fibers of a Legendre-form elliptic family $y^2=u(u-1)(u-\lambda)$ by exact arithmetic. Their functions are listed under MEMBERS in GUIDE.md.
exactj.py:exact_j_resultant(minpoly_coeffs)takes the integer minimal polynomial of $x_0$ as ascending coefficients and returns the minimal polynomial over $\mathbb{Q}$ of $j$ at the algebraic fiber $\lambda=x_0^2$, by two different methods that must agree. A leading coefficient other than 1 proves the fiber is not CM, because a CM j-invariant is an algebraic integer. A leading coefficient of 1 proves nothing. The function raises when $\lambda\in\{0,1\}$, and a reducible input returns the statusAMBIGUOUS-REDUCIBLE-MINPOLY.fiberstack.py:legendre_ap_fast(lam, p, chi)counts points over $\mathbb{F}_p$, withchithe character table fromchi_table(p).ap2_charsum(lam, p, chi)counts over $\mathbb{F}_{p^2}$, for primes where the minimal polynomial of the fiber has no root modulo $p$. Use it at small primes only, and exclude $\lambda\equiv 0,1 \pmod p$.
Used on this site
- Equal-mass sunrise: identified the $\Gamma_1(6)$ curve from its singular fibers $I_1$, $I_2$, $I_3$, $I_6$.
- Light-by-light box with a sunrise insertion: classified each sector's geometry as the sunrise curve or polylogarithmic.
- Non-planar $q\bar q\to W^+W^-$: identified the fibered elliptic curve on the maximal cut of the five-propagator sector.
Requirements
- Runs on: Python 3 with SymPy.
- Install: keep
tools/geotriage/andtools/landau-alphabet/side by side as in the repository. The automatic mode importsGraphSpecandsymanzik_subgraphfrom the second. Specs with a"maxcut"block work without it. - Self-test:
python test_geotriage.pyinsidetools/geotriage/prints a PASS or FAIL line per check and passes when itsSUMMARY:line reports0 failed. The exit code is nonzero on any failure. Reports go totest_output.jsonbeside the script, or to the file named in theGEOTRIAGE_TEST_OUTenvironment variable. - Optional: python-flint, which
exactj.pyneeds. The self-test skips theexactjchecks with a message when it is missing.
Source and references
The code is tools/geotriage/ in the BootLoops repository, released under the MIT license. README.md there has the decision table and separates what is certified from what is a probe.
| Reference | What it supplies |
|---|---|
| P. A. Baikov, Phys. Lett. B 385 (1996) 404 | Maximal cuts in the Baikov representation |
| Frellesvig and Papadopoulos, JHEP 04 (2017) 083, arXiv:1701.07356 | The loop-by-loop form of the Baikov representation |
| Kodaira | The types of the singular fibers of an elliptic family |
| A. Beauville, C. R. Acad. Sci. Paris Sér. I 294 (1982) 657 | The list of four-cusp rational elliptic surfaces |
| A. Sebbar, Duke Math. J. 110 (2001) 377 | The index data, from the classification of torsion-free genus-zero congruence subgroups |
| R. Livné, Israel J. Math. 92 (1995) 149 | The CM test for rank-2 K3 motives |
| Bloch and Vanhove, arXiv:1309.5865; Bloch, Kerr and Vanhove, arXiv:1406.2664, arXiv:1601.08181 | The elliptic and K3 identifications of the sunrise and banana graphs |
| FLINT, through python-flint | The exact arithmetic of exactj.py |