cutbasis

cutbasis chooses the master integralsthe integrals the linear relations cannot eliminate; every other integral of the family is a rational-function combination of them of a family of Feynman integrals from the geometry of each sector's maximal cutwhat is left of the integral when every propagator of the sector is set to zero, and writes the choice as preferred-masters files for the reduction program Kira. The method is the construction of the ε-collaboration (Bree, Gasparotto, Matijašić, Mazloumi, Melnichenko, Pögel, Teschke, Wang, Weinzierl, Wu and Xu, arXiv:2511.15381), and cutbasis is a Python implementation of it written from their paper. It is for anyone whose integration-by-parts reduction produces tables larger than they should be because of the basis the reducer picked on its own.

What it does

A reduction program such as Kira writes every integral of a family as a combination of a few master integrals, with coefficients rational in the dimension $d$ and the kinematic invariants. The number of masters is fixed by the family, but which integrals play that role is a choice. Kira makes it from an ordering of the integrals that does not use the geometry. A poor choice gives large tables, high polynomial degrees in the coefficients, and denominator factors that mix $d$ with the kinematics.

In the construction of the ε-collaboration the choice is made on the maximal cut. For a sector (a subset of the propagators of the family), set its propagators to zero in a Baikov representationa change of integration variables in which the propagator denominators themselves, plus a few extra scalar products, become the variables. The representation is built loop by loop after Frellesvig and Papadopoulos (arXiv:1701.07356) and Frellesvig (arXiv:2412.01804). What remains is an integral over the variables $z$ left on the cut (the cut variables) of a twisted differential form,

$$\int u(z)\,\varphi(z),\qquad u(z)=\prod_i P_i(z)^{\gamma_i},$$

where the $P_i$ are the Gram-determinant polynomials of the representation and the exponents $\gamma_i$ are linear in $d$. The rational form $\varphi$ comes from the numerator and the dots (raised propagator powers) of the integral. On the cut, the integrals of the sector are classes in the twisted cohomology of $u$, and a basis of that cohomology is a basis of masters. Every form gets four integers:

The forms are ranked by these four integers, and the simplest forms under that order are the masters. cutbasis then goes back from forms to Feynman integrals. For each leading form it looks for a single integral of the family, possibly with dots or numerators, that maps to it. Where no single integral does, it looks for a linear combination with symbolic coefficients, reconstructed from samples at two 61-bit primes and verified at a third.

The command line has three steps.

ListWhat it holds
<fam>.echelon.preferredThe single-integral pre-images of the leading forms, one per class that has one; Kira completes the rest
<fam>.lc.preferredThe same, plus linear combinations with symbolic coefficients for the remaining classes: the class-pure basis
<fam>.integrals.preferredThe cut-space Laporta elimination with the Feynman integrals themselves as columns: single integrals, dotted where the corner integrand has no residue

The four integers are computed by local analysis modulo word-size primes at numeric kinematics. A sector with one cut variable uses one sample. A sector with two cut variables uses two independent samples (prime and kinematic point), and a disagreement between the two is flagged in summary.json. A sector with no cut variable has one master, the corner integral (every propagator of the sector to the first power, no numerator).

cutbasis has these limits:

Examples

Census and selection on the Møller tower. The package includes examples/moeller_tower/: the two-loop Møller double box with a massive loop, the elliptic example of the paper. The family has nine propagators, top sector 107 and invariants $t$ and $m^2$ at $s=1$. The input is the Kira family files (input/integralfamilies.yaml, input/kinematics.yaml), a workload of 105 target integrals (input/targets) and a jobs template. With Python set up (see Requirements), run from the package directory tools/cutbasis/:

python3 cutbasis.py census --config examples/moeller_tower/input --family moeller --top 107
python3 cutbasis.py select --config examples/moeller_tower/input --family moeller --top 107 \
    --out OUT --workers 8

By default every subsector of --top is analyzed; --sectormappings DIR restricts the list to the nonTrivialSector file of a finished Kira run on the family, and --sectors 107,... names the sectors by hand. On sector 107 the selection finds six classes, with $a=(-4,-4,-4,-3,-3,-2)$, the basis the paper gives.

Over the whole tower, OUT/moeller.echelon.preferred lists twelve single integrals: the four above, one from each of five lower sectors, and the corner integrals of the three sectors with no cut variable. OUT/moeller.lc.preferred adds five linear-combination blocks, and OUT/moeller.integrals.preferred has seventeen integrals. The three lists are committed in examples/moeller_tower/expected/, and the run reproduces them byte for byte.

Letting Kira decide. The jobs template runs the reduction on sector 107 and carries the line preferred_masters: PREFERRED, which evaluate fills in. With Kira and Fermat on the path, or named by KIRA and FERMATPATH, run:

python3 cutbasis.py evaluate --config examples/moeller_tower/input --family moeller \
        --jobs examples/moeller_tower/input/jobs_template.yaml \
        --targets examples/moeller_tower/input/targets \
        --out OUT/eval --candidates echelon=OUT/moeller.echelon.preferred \
        integrals=OUT/moeller.integrals.preferred \
        --symbols d,t,m2

The command writes OUT/eval/evaluate.json and OUT/eval/evaluate_summary.json, the part without stamps or paths. On this family (13 masters, 105 targets) the three tables are:

RunTable sizeMaximum degree, numerator and denominatorDenominator factors that mix $d$ with the kinematicsCertified equal to stock
Kira's own (stock)1.55 MB24 and 241the reference
echelon0.51 MB21 and 180yes
integrals2.88 MB20 and 190yes

best_certified_candidate in the summary reads echelon, as in examples/moeller_tower/expected/evaluate_summary.json. The integrals list certifies but gives a table larger than stock, so it is reported as certified and nothing more. The byte counts are those of Kira 3.1 tables. Another Kira version can format its tables differently, in which case the certified flags, the master lists and the degree and factor columns are the comparison.

Which list wins depends on the family, so cutbasis writes both single-integral lists and evaluate measures them. A tie goes to stock.

Routines

The three steps are subcommands of cutbasis.py. Their required arguments are those of the examples above; --workers is optional.

CommandWhat it does
cutbasis.py censusPrints one line per sector, with the divisors of the representation; with --out, also writes <fam>.census.json
cutbasis.py selectWrites the three lists, summary.json and resumable per-sector checkpoints under ckpt/
cutbasis.py evaluateWrites the Kira tables under run_<name>/, and evaluate.json and evaluate_summary.json with the per-run metrics and the winner
evaluate.pyThe evaluate step as a stand-alone script, with the same arguments and exit codes
tablecheck.py --a TABLE --b TABLE --symbols d,tThe certification alone, on two tables, with the per-table metrics; --lc-defs FILE supplies the definitions of linear-combination masters

summary.json records per sector the representation, the basis with its four integers, the leading forms, the reconstructed coefficients and any flags, and lists the sectors that did not complete. The metrics are the table size, the maximum degrees, the coefficient bit length and the classes of denominator factors. The options of the three subcommands are listed in GUIDE.md in the package.

Exit codeWhen
0Every analyzed sector completed (select); every run finished and every candidate certified (evaluate); the tables are consistent (tablecheck.py)
1A sector analysis failed (select); a Kira run failed or a candidate did not certify (evaluate); the tables are not consistent (tablecheck.py)
2An option the tool cannot act on: an unknown family, a sector outside --top, a malformed --candidates entry, a missing file
4evaluate found no Kira or no Fermat executable

After a failed sector, select prints a line [select] FAILED: ... that names the sectors. The lists are written but incomplete for them, and summary.json names them under failed_sectors. Exits 2 and 4 write nothing and print one line, [cutbasis] usage error: <option>: <reason> or [evaluate] REFUSED: <reason>.

The Python library is the directory geomorder/.

FunctionWhat it returns
geomorder.lcbasis.SectorLC(spec, sector).base(), .structure()The maximal-cut cohomology basis of one sector with its integers, then its structure (leading forms, integral span, supports)
geomorder.lcbasis.reconstruct_sector(sl, ...)The symbolic coefficients of the linear-combination pre-images, from samples at two primes with verification at a third
geomorder.masters.sector_masters(spec, sector, ...)The integrals list of one sector
geomorder.cutde.run_sector(spec, sector, ...)Whether the maximal-cut differential equation of the basis is a Laurent polynomial in ε inside the filtration window (the paper's refined statement)

Requirements

Source and references

The code is tools/cutbasis/ in the BootLoops repository (release 1.0.1), released under the MIT license. GUIDE.md in that directory is the manual.

ReferenceWhat it supplies
I. Bree, F. Gasparotto, A. Matijašić, P. Mazloumi, D. Melnichenko, S. Pögel, T. Teschke, X. Wang, S. Weinzierl, K. Wu and X. Xu (the ε-collaboration), "New algorithms for Feynman integral reduction and ε-factorised differential equations", arXiv:2511.15381The construction: geometric master integrals on the maximal cut and the ε-factorized differential equation (Algorithms 1 to 3)
I. Bree, F. Gasparotto, S. Pögel, X. Wang, S. Weinzierl and X. Xu, "Intersection matrices associated to geometric-ordered bases of Feynman integrals", arXiv:2608.03646Intersection matrices for these bases. Related work: cutbasis does not compute intersection matrices
H. Frellesvig and C. G. Papadopoulos, JHEP 04 (2017) 083, arXiv:1701.07356The loop-by-loop Baikov representation
H. Frellesvig, JHEP 04 (2025) 111, arXiv:2412.01804The treatment of numerators outside the representation, the step for which the paper of the ε-collaboration cites it
P. Maierhöfer, J. Usovitsch and P. Uwer, arXiv:1705.05610; J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, arXiv:2008.06494; F. Lange, J. Usovitsch and Z. Wu, arXiv:2505.20197Kira, the reduction program the tool writes for
J. Klappert and F. Lange, arXiv:1904.00009; J. Klappert, S. Y. Klein and F. Lange, arXiv:2004.01463FireFly, Kira's finite-field back end
R. H. Lewis, FermatKira's symbolic back end
S. Laporta, arXiv:hep-ph/0102033The reduction method

Credits. The method is that of the ε-collaboration. The suggestion to build a tool that chooses Kira's masters this way came from Marco Klann. He pointed us to the first two papers of the table, and noted that such bases could lead to more efficient reductions and to differential equations that are easier to integrate.

← back to the tools index