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.

The other four parts are separate modules.

Maxcut has these limits:

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.

CommandWhat it does
python3 -m maxcut.decisive SPEC.jsonClassifies from a JSON spec with key baikov, series or lp and prints the result
python3 -m maxcut.decisive_validateRuns the self-test suite of the first example
python3 -m maxcut.ut_rotationSmoke 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 --selftestFour 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_cascadeExactness 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.

FunctionWhat it returns
decisive.classify(spec)The result dictionary for a baikov, series or lp spec; lp needs Julia
decisive_helpers.gram_baikovThe Baikov polynomial of a family and its leftover variables
decisive_helpers.minimal_pf_orderThe smallest annihilating $\theta$-operator of a sequence
ut_rotation.T_of_epsThe rotation matrix at numerical $\varepsilon$
ut_rotation.kz_connection_3, ut_rotation.kz_connection_4The connection matrices of the canonical basis
de_transport.load_de24, de_transport.integrabilityThe assembled matrices; the result of the integrability test
de_transport.transport_steps_3_6The report and the per-master Laurent coefficients, after boundary, transport, extraction and comparison
deriv_m2.FamilyA 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_sparseThe 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_pThe 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

Requirements

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.

ReferenceWhat it supplies
P. A. Baikov, hep-ph/9611449The Baikov representation
H. Frellesvig and C. G. Papadopoulos, arXiv:1701.07356The 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.04255Maximal cuts in Baikov variables
A. Primo and L. Tancredi, arXiv:1610.08397, arXiv:1704.05465The 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.11497Genus drops
P. A. Griffiths, doi:10.2307/1970746; P. Lairez, arXiv:1404.5069Picard–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.1806Canonical rotations
J. Henn, B. Mistlberger, V. A. Smirnov and P. Wasser, arXiv:2002.09492Canonical rotations
R. N. Lee and A. A. Pomeransky, arXiv:1308.6676Master counting
V. Chestnov, G. Crisanti and M. Giroux, arXiv:2606.29612; G. Crisanti, L. Lippstreu, A. J. McLeod and M. Polackova, DiscKoskyThe 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.

← back to the tools index