Maxcut

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

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. The main part, the classifier, decides from polynomial algebra alone what geometry the cut defines (a rational curve, an elliptic curve, a K3 surface or a Calabi–Yau threefold), which fixes the class of functions the full integral evaluates to. Two more build a canonical-basis rotation for one common type of cut and assemble, test and transport the cut differential equations of an on-shell four-point family. The last two construct the mass derivative for a family with one massive external leg and supply sparse finite-field linear algebra for large symbol-constraint systems.

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 cutthe integral with every propagator of a sector put on shell; the geometry of what remains controls which functions the full integral needs 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; they survive the cut as integration variables. The curve or surface $B=0$ fixes the function class: polylogarithms, elliptic functions, or periods of a higher-dimensional variety. maxcut.decisive reads that type and returns a dictionary whose type field is the classification, with its genus or Picard–Fuchs order pf_order, supporting fields such as j_distinct and reducible, and caveats, usually in well under 30 seconds. The classification is for the cut of one sector, not the whole integral; GeoTriage gives the graph-level survey.

The classifier has two independent routes, which the code and its output call Track A and Track B. Track A takes the loop momenta, the propagators with their masses, the external kinematics and a numerical kinematic point, and builds $B$ as a Gram determinant. An iterated discriminant then eliminates the degree-two variables one at a time. If at most one variable is left, the genus is read from the square-free degree of the remaining one-variable polynomial: 2 or less is polylog, 3 or 4 elliptic, more is hyperelliptic. In parallel the highest-degree variable is kept symbolic while the others are set to random rationals on four slices. That slice computation gives the genus when the chain stops with several variables left and one of them has degree three or more; for an elliptic curve it also gives the $j$-invariant on each slice, where distinct values mean the curve varies with the kinematics. If the chain stops with several variables left and none of degree three or more, the answer is higher, a K3 or Calabi–Yau candidate to confirm by Track B. Track A can over-report the genus but never under-reports it, so confirm any higher answer with Track B before acting on it. Track B takes a list of exact Taylor coefficients of the cut's holomorphic period (the self-tests use 70 to 80 terms) and 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). An lp input instead hands a Lee–Pomeransky polynomial to the Julia script tools/pf_rank.jl.

maxcut.ut_rotation serves 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, and the module returns the $3\times3$ matrix $T(\varepsilon)$ rotating the raw cut masters into it, with the matching connection matrices. Root labels depend on the kinematic region, so keep all points used with one rotation in one region.

maxcut.de_transport assembles the $24\times24$ cut differential equation of a three-loop four-point top sector with all four external legs massless (on shell) from a derivative recipe and a Kira reduction, and tests integrability, $\partial_tA_s-\partial_sA_t+[A_s,A_t]=0$, at three points to high precision. That 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$. When the test passes the script runs the remaining steps. It builds the boundary vector at a base point from a JSON corner file and transports it at several complex $\varepsilon$ on a small circle, along $s$ and then $t$. A discrete Fourier transform then gives the Laurent coefficients in $\varepsilon$, which are compared with independently derived values from a JSON basis file, reporting the fewest matching digits at each order. The exit status is 0 when the comparison passes, 2 when integrability fails (the later steps are skipped) and 3 when the comparison fails. The reference family's input files are not in the repository, so a production run stops with an error unless the MAXCUT_DE_* variables or --corner and --basis name your own (formats in the module docstring); --selftest runs the same machinery on a built-in toy system with a closed-form solution and needs no inputs.

maxcut.deriv_m2 serves families with one massive external leg, $p_1^2=m^2$. It solves for $D=\sum_{ij}c_{ij}\,p_i\cdot\partial/\partial p_j$ equal to $d/dm^2$ at fixed Mandelstam invariants, asserting $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)$ for any integral of the family as the finite sum $\sum_a(-\nu_a)\,G(\nu+e_a)\,D[D_a]$ of index-shifted integrals of the same family, so an existing reduction gives the $m^2$ differential equation. Its audit method confirms that every $p_1$-dependent slot, numerators included, gets its chain-rule term; omitting them gives wrong diagonal entries that other checks miss. The code is generic through the Family class; the bundled reference family reads a definition file that is not in the repository (DERIV_M2_FAMDEF).

maxcut.sparse_cascade is the linear algebra for building an integral's allowed symbols weight by weight, where a word of weight $w$ over $A$ letters indexes one of $A^w$ columns and dense Kronecker products exhaust memory near weight five. SparseWord keeps a basis only on the nonzero word columns, appends a letter without forming the Kronecker product, and imposes constraints through an incremental null space that processes rows in batches. Arithmetic is modulo a prime $p$ with float64 matrix products, the inner dimension split into 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$ raises ValueError. The sparse computation reproduces the dense one exactly where both fit.

Examples

Run the classifier's self-test suite, 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, whose cut is an elliptic curve with four distinct $j$ values on four slices. 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. The run takes about 40 seconds, overwrites maxcut/decisive_validate.json with the full results, and exits nonzero if any executed case fails (the skipped case does not count as a failure).

Classify a cut from its propagators (Track A). The top box as the self-test writes it: two loop momenta, 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$, seven propagators with the last four of mass $m^2$, 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 in under a second with 'type': 'elliptic', 'genus': 1, 'pf_order': 2, 'carrier': 'k2p3', 'j_distinct': 4, 'caveats': [] and a disc_chain entry showing 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

Geometry classifier (maxcut.decisive, maxcut.decisive_helpers)

Canonical rotation (maxcut.ut_rotation)

Cut differential equation (maxcut.de_transport)

Mass derivative (maxcut.deriv_m2)

Sparse finite-field cascade (maxcut.sparse_cascade)

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

Requirements and source

Python 3 with SymPy, mpmath and NumPy. The lp route calls Julia as julia +1.10 (the juliaup form) on tools/pf_rank.jl, which must stay in tools/ beside the package (PLD_ENV names a Julia project with its dependencies); de_transport imports the Kira parser from the sibling tools/frobenius-boundary/ package. Run from tools/ so import maxcut finds the package, and keep any directory holding an unrelated maxcut.py off the front of the Python path, or the import fails with "'maxcut' is not a package". Self-tests: python3 -m maxcut.decisive_validate (about 40 seconds; the fifth case only with MAXCUT_R3C set), python3 -m maxcut.de_transport --selftest (seconds, no inputs), python3 -m maxcut.sparse_cascade, and the python3 -m maxcut.ut_rotation smoke test. Source: tools/maxcut/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license.

← back to the tools index