GeoTriage

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

GeoTriage reads a Feynman graph and reports what geometric object sits on its maximal cut: 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. A short JSON description of the graph goes in; a JSON report comes out.

What it does

The kind of function a multi-loop Feynman integral evaluates to is decided by 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: the cut polynomial defines a curve or surface, and the type of that variety fixes which functions and constants can appear. GeoTriage reads that type for one graph, before any numerical work; it does not evaluate or reduce any integral.

The input JSON lists the edges with their masses, the external legs at each vertex, and the kinematic invariants, in the schema the Landau Alphabet package uses. Without a "maxcut" block GeoTriage builds the second Symanzik polynomial from the graph itself, the right model for sunrise- and banana-type graphs. For any other graph you add a "maxcut" block with the known cut polynomial as a SymPy string, its residual variables, and the kinematic variable that parametrizes the family. An optional "fiber_point" fixes numerical values of the invariants for the arithmetic tests.

With one residual 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 are reduced to a curve when a degree-two fibration or a plane cubic allows it, and otherwise treated as K3; three or more are classed as Calabi–Yau. For an 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, reads the singular fibers off the poles of $j(t)$, and matches the sorted pole orders against Beauville's list of modular elliptic surfaces to name the congruence subgroup and its level $N$. It flags complex multiplication (CM) when $j$, at the fiber point if given, is one of the thirteen rational CM values, and corroborates the verdict by counting points on the curve modulo small primes. For a K3 surface it applies Livné's criterion to the integers $a_p$ that encode the number of solutions of the cut equation modulo each small prime $p$: $a_p=0$ exactly at the primes where a quadratic character $\chi_D(p)=-1$ means CM by $\mathbb{Q}(\sqrt{D})$. That 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 is the recommendation. A (genus 0, or CM elliptic): the value can be recovered by fitting 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 fit works once one boundary constant, an $L$-value named in ring_conductors (a Dirichlet $L$-value in the elliptic case), is added. C (elliptic on none of those curves, or K3 whose CM status is open): a fit alone cannot succeed; the differential equations must be solved from a known boundary. D (Calabi–Yau, or K3 found to be non-CM): the periods are transported 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, an A or B verdict is a hypothesis the later fit confirms or refutes.

Read the honesty field first. genus_method is "exact" or "degree-bound"; a degree bound can over-report the genus, never under-report it. pf_order_certified is always false, because 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. caveats lists the remaining assumptions; a K3 CM verdict that came from the point-count probe always adds one saying it is not a theorem. Two others recur: a "not modular" verdict rests on the fiber configuration and the degree of $j$, with no search at higher level; and the automatic Symanzik model matches the true maximal cut only for banana- and vertex-type graphs, so other topologies should supply "maxcut". To classify a cut polynomial by discriminant chains without a graph description, see Maxcut.

Two helper modules check single fibers of a Legendre-form elliptic family $y^2=u(u-1)(u-\lambda)$ by exact arithmetic. exactj.py computes the minimal polynomial over $\mathbb{Q}$ of the j-invariant at an algebraic fiber $\lambda=x_0^2$ by two independent methods that must agree; a leading coefficient other than 1 proves the fiber is not CM (a CM j-invariant is an algebraic integer), while 1 proves nothing. fiberstack.py counts points modulo $p$, and modulo $p^2$ at primes where the fiber has no reduction modulo $p$.

Examples

Run the self-test suite, from inside the package directory:

python test_geotriage.py

The script first runs unit checks: the j-invariant routine on $y^2=x^4-1$ (expect 1728) and $y^2=x^3-1$ (expect 0), and the point counter's CM pattern for $j=1728$ and $j=0$ with a wrong-discriminant input that must fail. It checks the K3 background probe on synthetic counts, where a one-count mutation must destroy the match, and the exactj and fiberstack modules; the exactj checks are skipped with a message when python-flint is missing. It then classifies six known cases, five fixtures from graph_specs/ and an unequal-mass four-edge banana defined inline, printing a PASS or FAIL line per check, a summary, and a route table. Expected: 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. Reports go to test_output.json beside the script, or to the file named in the GEOTRIAGE_TEST_OUT environment variable; the exit code is nonzero on any failure.

Classify one graph from the command line. The ice-cream-cone fixture supplies its cut polynomial directly ("poly": "z(z-4)((z-w)**2 - 4tw)", "vars": ["z"], "modulus": "w") and a fiber point {"w": 5, "t": 3}.

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

Routines

Command line

Python functions (from geotriage import ...)

Helper modules

Tables and fixtures

Used on this site

Requirements and source

Python 3 with SymPy; exactj.py also needs python-flint, and the self-tests skip its checks when it is absent. The automatic mode imports GraphSpec and symanzik_subgraph from the sibling tools/landau-alphabet/ package, so keep the two directories side by side as in the repository; specs with a "maxcut" block work without it. Self-tests: python test_geotriage.py inside tools/geotriage/ (set GEOTRIAGE_TEST_OUT to a path to keep the log out of the package directory). The code is tools/geotriage/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license, and it is the reference implementation behind the p-adic Frobenius boundary-constant method.

← back to the tools index