cutbasis

cutbasis chooses the master integrals of a Feynman integral family from the geometry of each sector's maximal cut, following the construction of the ε-collaboration (arXiv:2511.15381, arXiv:2608.03646), and writes the choice as Kira preferred-masters files. It is for anyone whose integration-by-parts reduction produces tables larger than they should be, with denominators that mix the dimension $d$ and the kinematics, because of the basis the reducer picked on its own. The tool proposes a basis, runs Kira with each candidate list, checks every table against Kira's own and keeps the smallest certified table, with Kira's own table in the running. cutbasis only chooses the basis; the reduction itself is still Kira's.

What it does

A family of Feynman integrals is closed under the integration-by-parts relations. A reduction program such as Kira writes every integral of the family as a combination of a few master integralsthe integrals the linear relations cannot eliminate; every other integral of the family is a rational-function combination of them with coefficients rational in $d$ and the kinematic invariants. The number of masters is fixed by the family; which integrals play that role is a choice, and Kira makes it by an ordering of integrals that knows nothing about the geometry. A poor choice shows up as large tables, high polynomial degrees in the coefficients, and denominator factors that mix $d$ with the kinematics.

The ε-collaboration's construction makes the choice from the maximal cut. For a sector with $n$ propagators, set those 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, built loop by loop after Frellesvig and Papadopoulos. What remains is an integral over the uncut variables $z$ 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, the exponents $\gamma_i$ are linear in $d$, and $\varphi$ is a rational form that comes from the numerator and the dots 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, which says 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; and $|\mu|$, its total pole multiplicity. The order relation on these four integers ranks the forms, and the simplest forms under that order are the masters. The tool then has to go 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 reports, sector by sector, which Baikov representation the family admits, how many cut variables it leaves, and whether the sector is analyzable. It runs in seconds per sector and is worth running 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 runs the construction on every analyzable sector and writes the basis in three realizations. <fam>.echelon.preferred holds the single-integral pre-images of the leading forms, one per class that has one, and lets Kira complete the rest. <fam>.lc.preferred adds, for the remaining classes, the linear combinations with their symbolic coefficients; this is the class-pure basis. <fam>.integrals.preferred is the result of running the cut-space Laporta elimination with the Feynman integrals themselves as columns, so every master is a single integral, dotted where the corner integrand has no residue. evaluate runs Kira on a workload of target integrals once without a preferred list and once per candidate list. It rotates each resulting table into the stock basis and compares every common rule modulo two primes at two random points, and it reports for each run the table size, the maximum numerator and denominator degree, the coefficient bit length and the classes of denominator factors. The smallest certified table wins; the stock table is one of the entrants, so a candidate larger than stock is never reported as best.

The ordering integers come from local analysis modulo word-size primes at numeric kinematics: for sectors whose loop-by-loop representation has one cut variable, from one sample; with two cut variables, from two independent samples (prime and kinematic point), and a disagreement between the two samples is flagged in summary.json. Sectors with no cut variable have one master, the corner integral. Sectors with three or more cut variables, and sectors that admit only a democratic representation, are reported as "other" and keep Kira's own masters.

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, with nine propagators, top sector 107 and invariants $t$ and $m^2$ at $s=1$. It comes as Kira family files (input/integralfamilies.yaml, input/kinematics.yaml), a workload of 105 target integrals (input/targets) and a jobs template whose reduction runs on sector 107 with the line preferred_masters: PREFERRED, which evaluate fills in. From the package directory,

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 of them 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] and moeller[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 pre-image whose coefficient 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 is the all-single-integral realization, seventeen integrals. OUT/summary.json records per sector the representation, the basis with its four integers, the leading forms, the reconstructed coefficients, any flags and the sectors that did not complete, and OUT/ckpt/ holds per-sector checkpoints so an interrupted run resumes. The three lists are committed in examples/moeller_tower/expected/ and the run reproduces them byte for byte.

Letting Kira decide. With Kira and Fermat on the path, or named by KIRA and FERMATPATH,

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

runs the same reduction three times, once with Kira's own choice and once per candidate list, and writes OUT/eval/evaluate.json together with OUT/eval/evaluate_summary.json, the part without stamps, wall times or paths. On this family (13 masters, 105 targets) Kira's stock table is 1.55 MB, its coefficients reach degree 24 in numerator and denominator, and one denominator factor mixes $d$ with the kinematics. The echelon-singles basis gives a table of 0.51 MB, maximum degrees 21 and 18, and no mixed factor, and the table is certified equal to the stock table as a reduction. The integrals-mode basis gives 2.88 MB here, with degrees 20 and 19 and no mixed factor, certified as well but larger than stock, and best_certified_candidate in the summary reads echelon, as in examples/moeller_tower/expected/evaluate_summary.json. 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 realization wins depends on the family. The tool writes both single-integral realizations and lets evaluate measure them; there is no rule for which one wins. The stock table is always among the entrants, a tie goes to stock, and a candidate that certifies but comes out larger is reported as certified and nothing more. The self-test checks this on the paper's double box with two candidate lists, one of them built to give a larger table than Kira's own.

Routines

Command line (cutbasis.py)

• census --config CONFIG --family FAM --top SECTOR [--sectormappings DIR | --sectors a,b,c] [--out DIR] — per sector: the Baikov representation, the number of cut variables, whether the sector is analyzable, and the divisors; by default every subsector of --top; with --out, the same as <fam>.census.json.
• select --config CONFIG --family FAM --top SECTOR --out DIR [--sectormappings DIR | --sectors a,b,c] [--workers 8] [--M 5] [--dots 2 --sps 2] [--no-lc] [--no-integrals] [--seed 5] — the basis on every analyzable sector, written as <fam>.echelon.preferred, <fam>.lc.preferred and <fam>.integrals.preferred, with summary.json and resumable checkpoints under ckpt/; --M is the truncation of the pole multiplicity $|\mu|$ in the cut system, --dots and --sps bound the candidate integrals. Exit code 0 when every analyzed sector completed; 1 when a sector analysis failed, with a line [select] FAILED: ... naming the sectors, the lists written but incomplete for them, and failed_sectors in summary.json.
• evaluate --config CONFIG --family FAM --jobs jobs_template.yaml --targets TARGETS --out DIR --candidates name=FILE [name=FILE ...] --symbols d,t,m2 [--alphabet 't,m2,...'] [--kira PATH] [--fermat PATH] [--parallel 4] — Kira once per candidate list plus the stock run, in run_<name>/ under the output directory, certification of every table against stock, and evaluate.json and evaluate_summary.json with the per-run metrics and the winner. Exit code 0 when every run finished and every candidate certified; 1 when a Kira run failed or a candidate did not certify, named in the output and in evaluate.json; 4 when no Kira or no Fermat executable is found, one line [evaluate] REFUSED: <reason> and nothing written. --kira defaults to KIRA, then kira on the path; --fermat to FERMATPATH, then fer64 on the path.
• Every subcommand exits 2 on an option it cannot act on: an unknown --family (the families of the configuration are listed), a --top or --sectors entry that is not a sector of the family or not a subsector of --top, a missing nonTrivialSector file, or a missing candidate, jobs or targets file. For evaluate the same applies to a --candidates entry without =, a candidate named stock, and a candidate name with characters other than letters, digits, _, . and - (the name becomes the run directory run_<name>/). The check runs before the reducer lookup and writes nothing; the one line [cutbasis] usage error: <option>: <reason> goes to standard error.

Library (geomorder/)

• geomorder.lcbasis.SectorLC(spec, sector).base() and .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-mode basis of one sector (the cut Laporta with integral columns).
• geomorder.cutde.run_sector(spec, sector, ...) — tests, for one sector, whether the maximal-cut differential equation of the chosen basis is a Laurent polynomial in ε inside the filtration window (the paper's refined statement).

Reducer comparison

• evaluate.py — the evaluate subcommand as a stand-alone script, same arguments and exit codes (its usage-error line reads [evaluate] usage error: ...).
• tablecheck.py --a TABLE --b TABLE --symbols d,t [--lc-defs FILE] [--alphabet ...] [--json OUT] [--no-metrics] — rotates one basis into the other and compares every common rule modulo two primes at two random points; linear-combination masters are resolved through their definitions in --lc-defs; also the per-table metrics (size, degrees, bits, denominator-factor classes). Exit code 0 when the tables are consistent, 1 when they are not.

Self-test (selftest.py)

• python3 selftest.py — nine checks. paper_controls reproduces 23 statements of the paper by script (twists, images, integers, blow-ups). doublebox_select runs the paper's double-box top sector against a committed expected output. tablecheck_defect certifies two committed tables on rotated bases as equal and refuses the committed table with one wrong coefficient, exit 1 with the rule named. ratrec_defect reconstructs a known rational function of three variables from committed samples at two primes, verifies it at a third, and rejects the committed sample set with one corrupted value. coefficient_format checks that Kira coefficient strings are written without spaces. evaluate_refusal runs evaluate with no Kira executable and expects REFUSED and exit 4 before anything is written. cli_errors runs five bad options (a --sectors entry outside the family, an unknown --family, a --candidates entry without =, a candidate name with a path separator, a missing candidate file) and expects from each exit 2, one named line and nothing written. moeller_quick runs sector 42 of the worked example and compares the three lists with examples/moeller_tower/expected/quick/ byte for byte. reducer runs the evaluate step on the double box through Kira with two candidate lists: both certify, the three tables differ, and the larger candidate is never called best. The planted defects are committed fixtures built by fixtures/build_fixtures.py, which the self-test never runs. Exit code 0 when every check passes; 1 when a check fails. Without a kira executable, or without Fermat, the reducer check prints a named SKIP line and the run still exits 0; set CUTBASIS_REQUIRE_REDUCER=1 to make that skip exit 4 with REFUSED: <reason> as the last line. KIRA=/path/to/kira and FERMATPATH=/path/to/fer64 name the executables.

Limits

• Sectors with three or more cut variables, and sectors with only a democratic Baikov representation, are not analyzed; they keep the reducer's own masters.
• The tool chooses masters and writes the preferred-masters input; the reduction is Kira's.
• 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) and 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 evaluate choose 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.
• Supplying more preferred objects than a sector has masters displaces masters in lower sectors inside Kira; the tool 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 trusted flag in summary.json. Read the flags. Numeric kinematics modulo primes can hit accidental degeneracies; rerun a flagged sector with another --seed.
• An --M too small for a sector leaves its cut system with no non-pivot column inside the truncation; select names 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 sectors with two cut variables the integers are computed by local analysis at every column of the cut system, and such a sector is the slow part of a select run; on the worked example it is the top sector. --M 4 is a cheaper first pass, and --workers spreads the sectors.
• evaluate runs 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 point at the stock run rather than the candidate.

Requirements and source

Python 3.9 or newer with sympy, python-flint and pyyaml. Kira with a Fermat executable is needed for the evaluate step and the reducer check of the self-test only; census and select run without a reducer, and evaluate refuses with exit 4 if either program is missing. The self-test is python3 selftest.py in the package directory, a minute or two without a reducer (the quick check on sector 42 is most of it) plus three short Kira runs with one. The full worked example is a run to leave alone for a while; its measured cost is in examples/moeller_tower/README.md.

The code is tools/cutbasis/ in the BootLoops repository (release 1.0.1), released under the MIT license. It holds cutbasis.py (the command line), geo_master_select.py and imode.py (the two selection drivers), evaluate.py and tablecheck.py, the geomorder/ library and selftest.py. Beside them are fixtures/ (the paper's families, expected outputs, the planted-defect fixtures with their builder, and a Kira configuration for the self-test), examples/moeller_tower/ (input, expected output and a README with the run lines), and the manual GUIDE.md.

References

Credits. The method is the ε-collaboration’s: the geometric master integrals and ε-factorized differential equations of arXiv:2511.15381 and the intersection matrices of arXiv:2608.03646. The suggestion to build a tool that chooses Kira’s masters this way came from Marco Klann, who pointed us to these two papers 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