Kira, FireFly and Fermat (external)
Kira is a public program for integration-by-parts (IBP) reduction by P. Maierhöfer, J. Usovitsch, P. Uwer, J. Klappert, F. Lange and Z. Wu. It writes each Feynman integral of a family as an exact linear combination of master integralsthe few integrals of the family that the linear relations cannot eliminate; every other integral is a rational-function combination of them, using Fermat (R. H. Lewis) or FireFly (J. Klappert, S. Y. Klein and F. Lange) for the arithmetic. BootLoops uses the three for the reductions on its Feynman-integral pages and adds a lightly patched Kira build and four Python scripts that split, shrink and diagnose large Kira jobs.
Where it comes from
Kira is by Maierhöfer, Usovitsch, Uwer, Klappert, Lange and Wu, FireFly by Klappert, Klein and Lange, and Fermat by Lewis. BootLoops runs FireFly and Fermat as released, and Kira 3.1 with two small patches. The scripts were written by Claude, part of them with Kira's and FireFly's source open. Two files are Python ports of Kira routines, and one of them also reads FireFly's saved-state files. Two scripts follow file formats and conventions read from Kira's source, and the rest is new code.
| Part of the stack | Source | Authors |
|---|---|---|
Kira 3.1 with two patches (kira, kira128) | Kira at commit 5760f42 | The Kira developers; the patches by Claude |
| FireFly, built unmodified | FireFly | Klappert, Klein and Lange |
| Fermat, installed from its own site | Fermat | Lewis |
Python ports: pyred_weight.py and ffsave_degree_census.py | src/pyred/integrals.cpp and src/kira/ReadYamlFiles.cpp in Kira; the state files that FireFly's RatReconst::save_state writes | The Kira developers; Klappert, Klein and Lange |
Code that follows Kira's source: top-emit and the equation-file reader in parallel_kira_gen.py, and parallel_kira_gen_uds.py | relations.h, relations.cpp, kira.cpp, reductionFF.cpp and integrals.cpp in Kira | The Kira developers |
| New code: sharding, merging, launching, restaging, the loader and the self-test | Written for BootLoops | Code by Claude |
Please cite the authors' papers, listed under Source and references, when you use the stack. The patched build and the scripts are not affiliated with or endorsed by the authors of Kira, FireFly or Fermat.
What it does
A multi-loop diagram defines a family of integrals that differ only in the integer powers $a_1,\dots,a_n$ on its propagators $D_i$, with negative powers standing for numerator factors. In dimensional regularization the integral of a total derivative vanishes,
$$\int d^dk\;\frac{\partial}{\partial k^\mu}\left[\frac{v^\mu}{D_1^{a_1}\cdots D_n^{a_n}}\right]=0,$$
and carrying out the derivative gives a linear relation among integrals of the family. Its coefficients are rational in the dimension $d$ and the kinematic invariants.
Kira generates these relations for every seed (an integral to which the identity is applied) in a range you choose, and solves the sparse linear system. Each requested integral then comes out in terms of the master integrals. Reducing the derivatives of the masters the same way gives their differential equations. All arithmetic is exact, so a finished reduction has no numerical error. If the seed range is too small to reach every target, Kira's log reports integrals left unreduced and the range must grow.
A Kira job is a directory with config/integralfamilies.yaml, config/kinematics.yaml and a jobs.yaml, run as kira jobs.yaml --parallel=N. Each reduce entry of jobs.yaml names a topology, a sector and the seed range.
- Sector. The subset of propagators with positive powers, written as an integer bit mask, so powers
[1,1,0,0]are sector 3. - Seed range. The bounds
r(sum of positive powers),s(sum of numerator powers) andd(extra powers beyond one per line). - Targets.
select_mandatory_listpoints at a file of target integrals written likefam[2,1,0,0,-1,0]. - Solve.
run_initiategenerates the equations.run_triangularandrun_back_substitutionsolve them through Fermat, orrun_fireflysolves them by finite-field reconstructionsolve the system many times with every symbol replaced by an integer modulo a large prime, then reconstruct the exact rational functions from those samples, avoiding the huge intermediate expressions of a symbolic solve. - Output. Results go to
results/<family>/, solver state toresults/kira.db.
BootLoops' Kira is Kira 3.1 with two small patches. One silences a harmless SQLite "cannot commit" line that otherwise fills long logs. The other lets each worker thread normalize coefficients through its own Fermat process instead of queueing on one. In side-by-side tests the reduction output is byte-identical to stock Kira's. A speedup is expected only on deep reductions and has not been demonstrated at moderate depth.
The scripts are for large families, a thousand sectors or more.
The stack has these limits:
- Equation generation has no checkpoint.
- Kira checkpoints its Fermat solve in
results/kira.db. After a crash, back upresults/and rerun the same command in the same directory. - A FireFly solve resumes only once
ff_save/shiftexists. - Agreement between primes inside one FireFly run does not show that a table is right. BootLoops checks tables with Trust, which certifies each table entry against the linear system it came from, or repeats the reduction with FIRE (A. V. Smirnov and F. S. Chukharev), a separate public IBP program.
Seedling treats seed-range choice in general. When a reconstruction in more than one symbolic variable stalls, see Numkin and the degree_alias module of Ratfit. That module says whether a reconstruction that keeps failing on the same entries needs a larger interpolation grid or more primes.
Examples
Restage a job whose generation runs out of memory or crawls. build_restage.py rewrites jobs.yaml with a smaller seed range for each sector. The self-test's fixture is a directory with a jobs.yaml and a target file de_targets for a family fam with four propagators and two numerator slots:
fam[1,1,0,0,0,0] fam[2,1,0,0,-1,0] fam[1,0,1,1,0,-2]
With the scripts in place (see Requirements), run from the root of the BootLoops repository; the package directory is tools/kira-stack/:
python3 tools/kira-stack/build_restage.py --dir DIR --fam fam --nprops 4
The old jobs.yaml is kept as jobs.yaml.pre_restage. The new one has one reduce entry per target sector, highest sector number first, each with the smallest seed range that covers its own targets:
- {topologies: [fam], sectors: [13], r: 3, s: 2, d: 0}
- {topologies: [fam], sectors: [3], r: 3, s: 1, d: 1}
These entries are followed by select_mandatory_list, integral_ordering: 5, run_initiate: true, and run_triangular and run_firefly set to false. A JSON record written in the same directory holds the target count, the number of sectors given their own entry, and the overall seed range, here [3, 2, 1].
--nprops (default 14) must equal the family's propagator count. A positive power in a numerator slot stops the script with an error, but too large a value silently assigns wrong sectors. --backup-suffix changes the suffix of the kept file, and --tail-file replaces the closing block.
Generate the equations of a large family in parallel. Kira's equation generation uses little more than one core whatever --parallel says. parallel_kira_gen.py spreads it over many Kira processes. Its usage summary:
setup REF OUT [--fam F --top T --r R --s S --tops S1,..] launch OUT [--parallel P --nice N --host HOST] status OUT top-emit OUT [--db RUNDIR --out-dir DIR] # option (c), engine-free merge OUT TARGET [--top-from DIR] [--dedupe] probe REF [--r R --s S --tops S1,..] # setup+launch+wait+verify, small
REF is a finished Kira directory for the family, whose config/ and sectormappings/ the shards reuse; OUT is new. setup requires --fam, --r and --s, and probe requires --fam. A shard is one directory with its own Kira process, covering part of the sector tree. setup reads the targets from REF/de_targets_m2 unless --targets names another file. merge writes the shard equations into TARGET/tmp/<family>/ for a single solve with run_initiate: false.
- Preferred masters. Pass
--no-pm(nopreferred_mastersat generation), and add--targets-mode own-sectorswhen the real targets all sit in the top sector (the sector with every propagator present). Do not mix shard output with tables from a run that used preferred masters, since the masters can differ. - Top sector. The top sector lies in no shard, and
mergewarns if it is missing. Supply it from a finished ordinary run through--top-from DIR, or runtop-emit OUTand thenmerge OUT TARGET --top-from OUT/top_emit. top-emit. It writesOUT/top_emit/tmp/<family>/SYSTEM_<family>_<top>.gzfrom the operator templates inREF/sectormappings/. It reads the weight bit widths andintegral_orderingfrom a finished shard'sresults/kira.db(or--db RUNDIR). It stops if the databases disagree or the ordering differs from the--iogiven atsetup.- Check. The
top-emitfile has no symmetry relations and no equation selection, so the merged system is larger than Kira's own and must be checked the same way. Before trusting a merged system, compare its equations as a set against an ordinary serial run of a smaller case.
Find which coefficients are blowing up in a stuck FireFly run.
python3 $BOOTLOOPS_KIRA_TOOLS/ffsave_degree_census.py <rundir> \
[--vars d,s2,s12] [--workers N] [--out census.json]
BOOTLOOPS_KIRA_TOOLS is the bootloops-tools/ folder of a checkout of the kira repository. <rundir> must contain ff_save/states/, de_targets, preferred, results/<family>/masters and results/kira.db. Name the family with --family, and copy ff_save/states/ first if Kira is still running, because the files rotate.
The script checks that its decoder for Kira's integer tags reproduces every integral name in those files, and stops if not. It then writes JSON, by default FF_DEGREE_CENSUS.json in the run directory.
Each item of entries gives target, master, the numerator and denominator degrees deg_num and deg_den that FireFly has already measured, and whether the entry was finished (done). The fields target_src and master_src record how each name was recovered: file, custom, or inverse for integrals that appear in no name file. --vars names Kira's symbols in order and adds per-variable degrees; --workers 16 reads the gzip files in parallel.
Routines
build_restage.py and ffsave_degree_census.py print their options with --help. The two generation scripts print them per command, for example parallel_kira_gen.py launch --help.
| Command | What it does |
|---|---|
kira, kira128 | Kira 3.1 with the two patches, used exactly like upstream; kira128 is the build with -Dweight_width=128 |
parallel_kira_gen.py setup REF OUT --fam F --r R --s S | Writes PGEN_META.json and one shard_<id>/ per sector one propagator below --top, per --tops entry, or per --manifest group |
parallel_kira_gen.py launch OUT | Starts one detached Kira process per shard; needs setsid, so Linux or a --host that has it |
parallel_kira_gen.py status OUT | DONE, RUN or DEAD per shard, with equation count and sector progress |
parallel_kira_gen.py top-emit OUT | Writes the top sector's equation file without running Kira, plus TOP_EMIT_META.json |
parallel_kira_gen.py merge OUT TARGET | Writes the union of shard equations and masters into TARGET |
parallel_kira_gen.py probe REF --fam F | Small sharded trial that checks equations agree across shards; prints a JSON verdict |
parallel_kira_gen_uds.py gen REF OUT --fam F --r R --s S | Builds the equations of chosen sectors from Kira's template files IBP and LI, as eq_<sector>.txt.gz plus UDS_META.json |
parallel_kira_gen_uds.py uds OUT --fam F | Writes jobs_uds.yaml, the reduce_user_defined_system job for those files |
build_restage.py --dir DIR --fam FAMILY | One reduce entry per target sector in one directory; writes RESTAGE_STAGING_RECEIPT.json into DIR |
build_restage.py --base DIR --fam FAMILY TOP [TOP ...] | The same for each DIR/shard_<TOP>/ |
ffsave_degree_census.py <rundir> | Degree table per target and master from saved FireFly state |
kira_gpl_tools.py | Prints the directory it searches and whether pyred_weight.py and ffsave_degree_census.py are present |
The module pyred_weight.py converts between an integral's index list and the integer weight Kira stores for it in results/kira.db. Importers load it with kira_gpl_tools.load('pyred_weight').
| Function | What it returns |
|---|---|
WeightCodec(np, bits, iord, topsectors=None) | A codec for integral_ordering 1 to 8 with methods encode(indices) and decode(weight); decode raises ValueError on a weight that fits no integral |
from_kiradb(path) | The weight bit widths and integral_ordering of a run, read from its results/kira.db |
sec_of(indices) | The sector bit mask of an index list |
Used on this site
- Non-planar hexa-box: integration-by-parts reduction to the master integrals, 98 in 62 sectors, and their differential equations along the path segments.
- Non-planar $q\bar q\to W^+W^-$: integration-by-parts reduction to the 76 master integrals, and the numerical reductions from which the exact connection matrix is reconstructed.
- Crossed light-by-light box: integration-by-parts reduction to the master integrals and their differential equations in $s$, $t$ and $m^2$.
Requirements
- Runs on: Kira needs a C++17 compiler, Meson and Ninja, GiNaC (with CLN), zlib, and GMP for FireFly. yaml-cpp, FireFly and FLINT are built as Meson subprojects if absent. Fermat must be installed to run Kira and is found through
FERMATPATH. The scripts need only Python 3 (standard library). - Install: clone the
kirarepository (itsmainbranch is the patched source) and build with the two commands below.
meson setup build --buildtype=release -Dfirefly=true -Dflint=true --prefix=<install> ninja -C build install
- Build options: add
-Djemalloc=true(recommended), whose allocator copes far better with long reductions. Add-Dweight_width=128to build the second binary,kira128, for the one case where the standard build stops withIntegral weight representation exceeds 64 bits. Keep the 64-bit build as the default and rerun only the failing job underkira128. - Scripts: the scripts are in
tools/kira-stack/of the BootLoops repository, exceptpyred_weight.pyandffsave_degree_census.py. Those two are in thekirarepository underbootloops-tools/, beside the source they follow.tools/kira-stack/kira_gpl_tools.pyfinds them throughBOOTLOOPS_KIRA_TOOLSor a side-by-side checkout (../kirabeside the BootLoops checkout). Without themtop-emitstops. - Self-test:
python3 selftest.pyintools/kira-stack/ends withkira-stack selftest: ALL PASS (7/7)when the two utilities are found. Otherwise the four parts that need them skip by name and the run still exits 0. - Running Kira: keep
--parallelat 8 or below, and cap Kira's memory so that it does not swap.
Source and references
The patched Kira is the kira repository. It is a snapshot of the upstream release Kira 3.1 at commit 5760f42 with the two patches applied, published as a single commit on main. PATCHES.md and PATCHES.diff there list every change against that upstream commit. The scripts are tools/kira-stack/ in the BootLoops repository.
| Reference | What it supplies |
|---|---|
| P. Maierhöfer, J. Usovitsch and P. Uwer, arXiv:1705.05610; code: gitlab.com/kira-pyred/kira | Kira, the reduction program |
| J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, arXiv:2008.06494 | Kira 2.0 |
| F. Lange, J. Usovitsch and Z. Wu, arXiv:2505.20197 | Kira 3, the version patched here |
| J. Klappert and F. Lange, arXiv:1904.00009; J. Klappert, S. Y. Klein and F. Lange, arXiv:2004.01463; code: gitlab.com/firefly-library/firefly | FireFly, the finite-field reconstruction |
| R. H. Lewis, Fermat, home.bway.net/lewis | The simplification of rational-function coefficients in a symbolic solve |
| A. V. Smirnov and F. S. Chukharev, arXiv:1901.07808; A. V. Smirnov and M. Zeng, arXiv:2311.02370; code: gitlab.com/feynmanIntegrals/fire | FIRE, the separate IBP program used to repeat a reduction |
| S. Laporta, arXiv:hep-ph/0102033 | The reduction method |