Maxcut
Maxcut is a Python package with five parts for the maximal cut of a Feynman integral, the version of the integral with every propagator put on its mass shell. Its classifier decides from polynomial algebra alone whether the cut defines a rational curve, an elliptic curve, a K3 surface or a Calabi–Yau threefold, a use of the cut that follows Primo and Tancredi. The other four parts build a canonical-basis rotation, assemble and transport cut differential equations, construct a mass derivative and supply sparse finite-field linear algebra.
What it does
In the Baikov representationa rewriting of the loop integral with the propagators themselves as integration variables; cutting a propagator sets that variable to zero the maximal cut leaves a polynomial $B$ in a few leftover variables, the irreducible scalar productsdot products of loop and external momenta that cannot be written in terms of the propagators. The function class of the full integral follows from the curve or surface $B=0$: polylogarithms, elliptic functions, or periods of a higher-dimensional variety.
maxcut.decisive returns a dictionary with the classification type, its genus or Picard–Fuchs orderthe order of the lowest-order differential operator that annihilates the period of the cut pf_order, and caveats. It has two routes, called Track A and Track B in the code and its output, and a third input type, lp.
- Track A, discriminant chain. The code builds $B$ as a Gram determinant from the propagators and the kinematics at a numerical point. An iterated discriminant eliminates the degree-two variables one at a time. If at most one variable is left, the square-free degree of the remaining polynomial gives the genus: 2 or less is
polylog, 3 or 4elliptic, more is hyperelliptic. - Track A, slices. In parallel the highest-degree variable is kept symbolic while the others are set to random rationals on four slices. The slices give the genus when the chain stops with several variables left and one of them has degree three or more. If none has, the answer is
higher, a K3 or Calabi–Yau candidate. For an elliptic curve the slices also give the $j$-invariant (the modulus of the curve), and distinct values mean the curve varies with the kinematics. - Track B. From exact Taylor coefficients of the cut's holomorphic period (the self-tests use 70 to 80 terms), the code finds the smallest order of a differential operator in $\theta=z\,d/dz$ annihilating them. Order 1 is polylogarithmic, 2 elliptic, 3 K3, 4 a Calabi–Yau threefold. A factorization test reports a split order 4 as
2×elliptic (reducible). lpinput. A Lee–Pomeransky polynomial (the single polynomial of the Feynman-parameter form) goes to the Julia scripttools/pf_rank.jlof Dipstick, which finds the order by Griffiths–Dwork reduction modulo primes. For theholonomic_rankfield the script callschi_regulatedof Leviathan, the partial Julia port of the program of Chestnov, Crisanti and Giroux.
The other four parts are separate modules.
- Canonical rotation (
maxcut.ut_rotation). This module is for a two-loop cut that reduces to $\int R_k(u)\,P_4(u)^{-1-\varepsilon}du$ over a quartic with two roots rational in the kinematics and two exchanged by a square root. Partial fractions in the roots give integrals whose differential equation is proportional to $\varepsilon$, a canonical basis. The module returns the $3\times3$ matrix $T(\varepsilon)$ rotating the raw cut master integralsthe finite basis to which every integral of the family reduces into it, with the matching Aomoto/Knizhnik–Zamolodchikov connection matrices. - Cut differential equation (
maxcut.de_transport). This module assembles the $24\times24$ cut differential equation of a three-loop four-point top sector (the sector, or subset of propagators, with every propagator present) with all four external legs massless. It builds the equation from a derivative recipe and a Kira reduction. It tests integrability, $\partial_tA_s-\partial_sA_t+[A_s,A_t]=0$, at three points to high precision. The test catches on-shell derivative operators which keep $p_1^2=p_2^2=p_3^2=0$ but break $p_4^2=(p_1+p_2+p_3)^2=0$; the correct pair is built from $O_k=p_k\cdot\partial/\partial p_k$. - Cut differential equation, transport. When the test passes,
de_transportbuilds the boundary vector from a JSON corner file. It transports the vector at several complex $\varepsilon$ on a small circle, along $s$ and then $t$, with a Bulirsch–Stoer stepper. A discrete Fourier transform gives the Laurent coefficients in $\varepsilon$, which are compared with the reference values of a JSON basis file. - Mass derivative (
maxcut.deriv_m2). For a family with one massive external leg, $p_1^2=m^2$, this module solves for $D=\sum_{ij}c_{ij}\,p_i\cdot\partial/\partial p_j$ equal to $d/dm^2$ at fixed Mandelstam invariants. It asserts $D[p_1^2]=1$ and $D[p_i^2]=0$ for every other leg including the momentum-conserving one. It then writes $\partial_{m^2}G(\nu)$ as the finite sum $\sum_a(-\nu_a)\,G(\nu+e_a)\,D[D_a]$ of index-shifted integrals of the same family, so the $m^2$ differential equation follows from an existing reduction. - Sparse cascade (
maxcut.sparse_cascade). This module is the linear algebra for building an integral's allowed symbolsa symbol is a sum of words in the letters, the arguments of the logarithms in the answer weight by weight. A word of weight $w$ over $A$ letters indexes one of $A^w$ columns, and dense Kronecker products exhaust memory near weight five.SparseWordkeeps a basis only on the nonzero word columns and imposes constraints through a null space computed in batches of rows. The sparse computation reproduces the dense one exactly where both fit.
Maxcut has these limits:
- The classification is for the cut of one sector, not the whole integral. GeoTriage gives the graph-level survey.
- Track A can over-report the genus but never under-reports it, so confirm any
higheranswer with Track B before acting on it. - Root labels in
ut_rotationdepend on the kinematic region, so keep all points used with one rotation in one region. - The input files of the reference families of
de_transportandderiv_m2are not in the repository. A production run ofde_transportstops with an error unless theMAXCUT_DE_*variables or--cornerand--basisname your own files.deriv_m2is generic through itsFamilyclass, and its reference family reads the file named byDERIV_M2_FAMDEF. - In
deriv_m2every $p_1$-dependent slot, numerators included, needs its chain-rule term, which theauditmethod confirms. Omitting those terms gives wrong diagonal entries that other checks miss. sparse_cascadeuses float64 matrix products modulo a prime $p$, in chunks short enough that every partial sum stays below $2^{53}$. The result is exact for any $p$ up to 94 906 266, and a larger $p$ raisesValueError.
Examples
Run the classifier's self-test suite. With the package set up (see Requirements), run from the repository's tools/ directory:
python3 -m maxcut.decisive_validate
[gfp-matmul ] expect=exact-at-boundary got=exact PASS 0.0s [topbox-cal ] expect=elliptic got=elliptic PASS 0.6s j_distinct=4 [g0-3loop ] expect=polylog got=polylog PASS 19.6s [ell-3loop ] expect=elliptic got=elliptic PASS 20.2s j_distinct=4 SKIP pent5: external data dir not present (set MAXCUT_R3C to a dir containing baikov_ls.py) [K3-ord3 ] expect=K3 got=K3 PASS 0.1s [sunpair-red ] expect=2×elliptic got=2×elliptic (reducible) PASS 0.0s SUMMARY: 4/5 validation targets PASS (calibration topbox: PASS; gfp-matmul probe: PASS)
The first line is the exactness probe of the finite-field matrix product in sparse_cascade, run as an extra check outside the five-case count. The calibration case is the two-loop top box with four massive propagators. Two three-loop ten-propagator families follow through Track A, then two Track B cases from period series (a K3 of order 3, and a reducible order 4 from the sunrise period with its reciprocal-argument partner). The five-point case needs data not in the repository and is skipped unless MAXCUT_R3C points at it, hence 4/5.
Classify a cut from its propagators (Track A). The top box as the self-test writes it has two loop momenta and three massless external momenta with $p_1\cdot p_2=s/2$, $p_2\cdot p_3=t/2$, $p_1\cdot p_3=-(s+t)/2$. Its seven propagators, the last four of mass $m^2$, are taken at $s=7$, $t=-3/2$, $m^2=1$.
import sympy as sp
from maxcut.decisive import classify
s,t,m2=sp.symbols('s t m2',real=True)
PP4={('p1','p1'):0,('p2','p2'):0,('p3','p3'):0,
('p1','p2'):s/2,('p2','p3'):t/2,('p1','p3'):-(s+t)/2}
KIN={s:7,t:sp.Rational(-3,2),m2:1}
def cf(*tm):
d={}
for c,v in tm: d[v]=d.get(v,0)+c
return d
tb=[cf((1,'k1')),cf((1,'k1'),(-1,'p1')),cf((1,'k1'),(-1,'p1'),(-1,'p2')),
cf((1,'k2')),cf((1,'k2'),(-1,'p1'),(-1,'p2'),(-1,'p3')),
cf((1,'k1'),(-1,'k2')),cf((1,'k1'),(-1,'k2'),(1,'p3'))]
classify({'baikov':dict(
gram=dict(loops=['k1','k2'],ext=['p1','p2','p3'],ext_gram=PP4,
props=list(zip(tb,[0,0,0,m2,m2,m2,m2])),kin_syms=(s,t,m2)),
kin=KIN)})
Each propagator is a dictionary from momentum name to coefficient, paired with its squared mass. The call returns 'type': 'elliptic', 'genus': 1, 'pf_order': 2, 'carrier': 'k2p3', 'j_distinct': 4, 'caveats': []. Its disc_chain entry shows that of the two scalar products surviving the cut, k2p2 was eliminated and k2p3 remains with square-free degree 4, hence genus 1. An empty caveats list means Track A decided on its own.
Classify from a period series on the command line (Track B). The equal-mass sunrise period has coefficients $a_n=\sum_{i+j+k=n}(n!/i!j!k!)^2=1,3,15,93,639,\dots$. Put the first 81 in a file as {"series": [1, 3, 15, 93, 639, ...]} and run
python3 -m maxcut.decisive sunrise.json
{
"track": "B",
"pf_order": 2,
"pf_parts": [
2
],
"reducible": null,
"type": "elliptic",
"leading_symbol": "(z - 1)*(9*z - 1)",
"method": "series-krylov",
"wall_s": 0.04
}
Order 2 means an elliptic curve; the operator's leading coefficient vanishes at the sunrise's singular points $z=1$ and $z=1/9$. reducible is null because a single order-2 series is not tested for factoring. From Python the same call is classify({'series': [...]}), with an optional 'series_aux' list.
Routines
Every command is run from the repository's tools/ directory.
| Command | What it does |
|---|---|
python3 -m maxcut.decisive SPEC.json | Classifies from a JSON spec with key baikov, series or lp and prints the result |
python3 -m maxcut.decisive_validate | Runs the self-test suite of the first example |
python3 -m maxcut.ut_rotation | Smoke test on a toy quartic: prints the sum of the basis integrals and the connection's error against finite differences |
python3 -m maxcut.de_transport [--corner FILE] [--basis FILE] | Assembles, tests, then transports and compares |
python3 -m maxcut.de_transport --selftest | Four checks on a built-in toy system with a closed-form solution |
python3 -m maxcut.deriv_m2 [--symbolic] [--out FILE] | Builds the operator for the reference family, runs the audits and writes DERIV_M2_AUDIT.json |
python3 -m maxcut.sparse_cascade | Exactness probe of matmul_mod at the edge of its range, including the refusal of an over-large $p$ |
de_transport exits with 0 when the comparison passes, 2 when integrability fails (the later steps are skipped) and 3 when the comparison fails. The MAXCUT_DE_* environment variables (SRC, KIRA_RED, MASTERS, CORNER, BASIS, OUT, FAMILY, PARSER_DIR) name its inputs; the file formats are in the module docstring. Its other options are --dps, --neps, --eps-radius, --prec, --n-neg, --n-pos, --gate-digits and --out.
From Python, each function is imported from its module, as in from maxcut.decisive import classify.
| Function | What it returns |
|---|---|
decisive.classify(spec) | The result dictionary for a baikov, series or lp spec; lp needs Julia |
decisive_helpers.gram_baikov | The Baikov polynomial of a family and its leftover variables |
decisive_helpers.minimal_pf_order | The smallest annihilating $\theta$-operator of a sequence |
ut_rotation.T_of_eps | The rotation matrix at numerical $\varepsilon$ |
ut_rotation.kz_connection_3, ut_rotation.kz_connection_4 | The connection matrices of the canonical basis |
de_transport.load_de24, de_transport.integrability | The assembled matrices; the result of the integrability test |
de_transport.transport_steps_3_6 | The report and the per-master Laurent coefficients, after boundary, transport, extraction and comparison |
deriv_m2.Family | A family, with propagators as strings such as "(k1-p1-p2)^2" |
deriv_m2.MassDerivOperator(fam) | The operator $D$; .deriv_terms(nu) gives {shifted indices: coefficient} and .audit() the per-slot report |
sparse_cascade.SparseWord(mat, cols, p) | A basis on a sparse set of word columns, extended by .extend(Bw, A) |
sparse_cascade.incremental_nullspace, sparse_cascade.project_sparse | The null space modulo $p$ of a tall constraint matrix, in batches; the basis after constraints are imposed |
sparse_cascade.matmul_mod, sparse_cascade.matmul_max_p | The matrix product modulo $p$; the largest admissible $p$ |
The argument lists and the lower-level functions are in the module files of tools/maxcut/. The flat files tools/maxcut_decisive.py (with maxcut_decisive_helpers.py and maxcut_decisive_validate.py), maxcut_ut_rotation.py, maxcut_de_transport.py, sparse_cascade.py and deriv_m2.py are shims forwarding imports and command-line use to the package.
Used on this site
- The BootLoops integral class: names Maxcut as the diagnostic for cut geometry and basis rotation.
Requirements
- Runs on: Python 3 with SymPy, mpmath and NumPy.
- Install: run from
tools/so thatimport maxcutfinds the package. Keep any directory holding an unrelatedmaxcut.pyoff the front of the Python path, or the import fails with "'maxcut' is not a package". - Self-test:
python3 -m maxcut.decisive_validatetakes about 40 seconds and ends with theSUMMARY:line of the first example. It overwritesmaxcut/decisive_validate.jsonwith the full results and exits nonzero if any executed case fails; the skipped case does not count as a failure. - Other self-tests:
python3 -m maxcut.de_transport --selftestneeds no inputs and ends withselftest: PASS (4 legs).python3 -m maxcut.sparse_cascadeends with a line beginningmatmul_mod boundary probe: PASS.python3 -m maxcut.ut_rotationprints the sum of the basis integrals, which is zero to working precision. de_transport: imports the Kira parser from the siblingtools/frobenius-boundary/package.- Optional, the
lproute: Julia, called asjulia +1.10(the juliaup form) ontools/pf_rank.jl, which must stay intools/beside the package.PLD_ENVnames a Julia project with its dependencies. The script loadstools/dipstick/pf_rank.jland Leviathan fromupgrades/leviathan/.
Source and references
The code is tools/maxcut/ in the BootLoops repository. The journal citations of the method papers are in REFERENCES.md at the repository root.
| Reference | What it supplies |
|---|---|
| P. A. Baikov, hep-ph/9611449 | The Baikov representation |
| H. Frellesvig and C. G. Papadopoulos, arXiv:1701.07356 | The loop-by-loop form of the Baikov representation |
| M. Harley, F. Moriello and R. M. Schabinger, arXiv:1705.03478; J. Bosma, M. Sogaard and Y. Zhang, arXiv:1704.04255 | Maximal cuts in Baikov variables |
| A. Primo and L. Tancredi, arXiv:1610.08397, arXiv:1704.05465 | The use of maximal cuts to read off the geometry and the homogeneous differential equations |
| R. Marzucca, A. J. McLeod, B. Page, S. Pögel and S. Weinzierl, arXiv:2307.11497 | Genus drops |
| P. A. Griffiths, doi:10.2307/1970746; P. Lairez, arXiv:1404.5069 | Picard–Fuchs operators by Griffiths–Dwork reduction |
| N. Arkani-Hamed, J. L. Bourjaily, F. Cachazo and J. Trnka, arXiv:1012.6032; J. M. Henn, arXiv:1304.1806 | Canonical rotations |
| J. Henn, B. Mistlberger, V. A. Smirnov and P. Wasser, arXiv:2002.09492 | Canonical rotations |
| R. N. Lee and A. A. Pomeransky, arXiv:1308.6676 | Master counting |
| V. Chestnov, G. Crisanti and M. Giroux, arXiv:2606.29612; G. Crisanti, L. Lippstreu, A. J. McLeod and M. Polackova, DiscKosky | The programs that Leviathan ports in part; the lp route runs Leviathan |
Public programs exist for two of the tasks: SymBuild by V. Mitev and Y. Zhang (arXiv:1809.05101) for integrable symbols, and BaikovPackage by H. Frellesvig (arXiv:2412.01804) for Baikov polynomials.