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:
- $a$, the localization preference: how far the form concentrates on points or curves of the cut space;
- $w$, its Hodge weight;
- $o$, its pole order after the boundary is blown up;
- $|\mu|$, its total pole multiplicity.
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.
- Census.
censusreports, sector by sector, which Baikov representation the family admits, how many cut variables it leaves, and whether the sector is analyzable. Run it before any long reduction: a family whose heavy sectors have a smaller representation under a different routing of the loop momenta or a different numerator basis should be relabeled first. - Select.
selectruns the construction on every analyzable sector and writes the basis as the three lists of the table below. - Evaluate.
evaluateruns Kira on a workload of target integrals, once without a preferred list (the stock run) and once per candidate list. It rotates each table into the stock basis and compares every common rule modulo two primes at two random points. The smallest certified table wins. The stock table is one of the entrants, so a candidate larger than stock is never reported as best.
| List | What it holds |
|---|---|
<fam>.echelon.preferred | The single-integral pre-images of the leading forms, one per class that has one; Kira completes the rest |
<fam>.lc.preferred | The same, plus linear combinations with symbolic coefficients for the remaining classes: the class-pure basis |
<fam>.integrals.preferred | The 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:
- Sectors with three or more cut variables, and sectors that admit only a democratic Baikov representation (one Gram polynomial in all loop momenta at once), are not analyzed. They are reported as "other" and keep Kira's own masters.
- cutbasis chooses masters and writes the preferred-masters input. The reduction is Kira's.
- For sectors with two cut variables, the merge step of the paper (Algorithm 2) is replaced by the union of the candidates. The elimination over the whole cut then decides among them.
- The rotation to an ε-factorized differential equation, the second step of the paper, exists only as a prototype for one variable and two blocks (
geomorder/step2.py). It is not part of the command line. - The class-pure linear-combination basis is correct and certified, but its coefficients propagate into every entry of a reduction table. Use it for the differential equation and let
evaluatechoose the basis for the reduction. - With Kira 3.1, a run whose preferred-masters coefficient strings contained spaces did not get past "Generate equations". The writer strips the spaces and the self-test checks it. A Kira run that sits idle in "Generate equations" right after a sector with a linear-combination block has hit this stall.
- A list with more preferred objects than a sector has masters displaces masters in lower sectors inside Kira. cutbasis emits only the objects in the echelon of the integral span, but a hand-edited list can do it.
- The truncation $|\mu|\le M$ of the cut system is checked. A master at the truncation boundary, or a point with two even divisors and no residue candidate, triggers a retry with the other loop order and, failing that, a
NOT trustedflag insummary.json. Read the flags. Numeric kinematics modulo primes can hit accidental degeneracies; rerun a flagged sector with another--seed. - An
--Mtoo small for a sector leaves its cut system with no non-pivot column inside the truncation.selectnames the sector (dim H = 0 at M=... raise --M) and exits 1. A scaleless sector, with no column at the boundary, is not a failure. - For a sector with two cut variables the integers are computed at every column of the cut system, so such a sector is the slow part of a
selectrun. On the worked example it is the top sector.--M 4is a cheaper first pass, and--workersspreads the sectors. evaluateruns Kira without resource limits of its own. On a shared machine wrap it in yours.- A candidate list that names an integral Kira cannot reduce makes the shared target list fail in the stock run. The named line and the exit code 1 then point at the stock run, not at the candidate.
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.
- Four classes have single-integral pre-images: the corner integral
moeller[1,1,0,1,0,1,1,0,0], the same integral with a dot on one or the other of two massive lines (moeller[2,1,0,1,0,1,1,0,0]andmoeller[1,1,0,2,0,1,1,0,0]), and one integral with a numerator,moeller[1,1,0,1,0,1,1,0,-1]. - The other two classes are linear combinations. One is the paper's pattern of a dotted integral plus $t$ times a second dotted integral with a different numerator. The other has a coefficient that is a rational function of $d$, $t$ and $m^2$ with a numerator of degree 7 over a denominator of degree 6, correct but useless inside a reduction.
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:
| Run | Table size | Maximum degree, numerator and denominator | Denominator factors that mix $d$ with the kinematics | Certified equal to stock |
|---|---|---|---|---|
| Kira's own (stock) | 1.55 MB | 24 and 24 | 1 | the reference |
echelon | 0.51 MB | 21 and 18 | 0 | yes |
integrals | 2.88 MB | 20 and 19 | 0 | yes |
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.
| Command | What it does |
|---|---|
cutbasis.py census | Prints one line per sector, with the divisors of the representation; with --out, also writes <fam>.census.json |
cutbasis.py select | Writes the three lists, summary.json and resumable per-sector checkpoints under ckpt/ |
cutbasis.py evaluate | Writes the Kira tables under run_<name>/, and evaluate.json and evaluate_summary.json with the per-run metrics and the winner |
evaluate.py | The evaluate step as a stand-alone script, with the same arguments and exit codes |
tablecheck.py --a TABLE --b TABLE --symbols d,t | The 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 code | When |
|---|---|
| 0 | Every analyzed sector completed (select); every run finished and every candidate certified (evaluate); the tables are consistent (tablecheck.py) |
| 1 | A sector analysis failed (select); a Kira run failed or a candidate did not certify (evaluate); the tables are not consistent (tablecheck.py) |
| 2 | An option the tool cannot act on: an unknown family, a sector outside --top, a malformed --candidates entry, a missing file |
| 4 | evaluate 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/.
| Function | What 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
- Runs on: Python 3.9 or newer with sympy, python-flint and pyyaml.
- Self-test:
python3 selftest.pyin the package directory runs nine checks, listed at the top ofselftest.py, and ends with a line that beginsOVERALL PASS. One check reproduces 23 statements of the paper by script. Without a reducer the run takes a minute or two, most of it a check that reruns sector 42 of the worked example. With a reducer it adds three short Kira runs. - Optional: Kira with a Fermat executable, for
evaluateand the reducer check of the self-test only.KIRA=/path/to/kiraandFERMATPATH=/path/to/fer64name the executables. Without them the reducer check prints a named SKIP line and the self-test still exits 0. SetCUTBASIS_REQUIRE_REDUCER=1to make that skip exit 4 withREFUSED: <reason>as the last line. - Worked example: the full worked example takes much longer than the self-test. Its measured cost is in
examples/moeller_tower/README.md.
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.
| Reference | What 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.15381 | The 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.03646 | Intersection matrices for these bases. Related work: cutbasis does not compute intersection matrices |
| H. Frellesvig and C. G. Papadopoulos, JHEP 04 (2017) 083, arXiv:1701.07356 | The loop-by-loop Baikov representation |
| H. Frellesvig, JHEP 04 (2025) 111, arXiv:2412.01804 | The 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.20197 | Kira, 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.01463 | FireFly, Kira's finite-field back end |
| R. H. Lewis, Fermat | Kira's symbolic back end |
| S. Laporta, arXiv:hep-ph/0102033 | The 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.