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 stackSourceAuthors
Kira 3.1 with two patches (kira, kira128)Kira at commit 5760f42The Kira developers; the patches by Claude
FireFly, built unmodifiedFireFlyKlappert, Klein and Lange
Fermat, installed from its own siteFermatLewis
Python ports: pyred_weight.py and ffsave_degree_census.pysrc/pyred/integrals.cpp and src/kira/ReadYamlFiles.cpp in Kira; the state files that FireFly's RatReconst::save_state writesThe 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.pyrelations.h, relations.cpp, kira.cpp, reductionFF.cpp and integrals.cpp in KiraThe Kira developers
New code: sharding, merging, launching, restaging, the loader and the self-testWritten for BootLoopsCode 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.

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:

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.

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.

CommandWhat it does
kira, kira128Kira 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 SWrites 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 OUTStarts one detached Kira process per shard; needs setsid, so Linux or a --host that has it
parallel_kira_gen.py status OUTDONE, RUN or DEAD per shard, with equation count and sector progress
parallel_kira_gen.py top-emit OUTWrites the top sector's equation file without running Kira, plus TOP_EMIT_META.json
parallel_kira_gen.py merge OUT TARGETWrites the union of shard equations and masters into TARGET
parallel_kira_gen.py probe REF --fam FSmall 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 SBuilds 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 FWrites jobs_uds.yaml, the reduce_user_defined_system job for those files
build_restage.py --dir DIR --fam FAMILYOne 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.pyPrints 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').

FunctionWhat 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

Requirements

meson setup build --buildtype=release -Dfirefly=true -Dflint=true --prefix=<install>
ninja -C build install

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.

ReferenceWhat it supplies
P. Maierhöfer, J. Usovitsch and P. Uwer, arXiv:1705.05610; code: gitlab.com/kira-pyred/kiraKira, the reduction program
J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, arXiv:2008.06494Kira 2.0
F. Lange, J. Usovitsch and Z. Wu, arXiv:2505.20197Kira 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/fireflyFireFly, the finite-field reconstruction
R. H. Lewis, Fermat, home.bway.net/lewisThe 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/fireFIRE, the separate IBP program used to repeat a reduction
S. Laporta, arXiv:hep-ph/0102033The reduction method

← back to the tools index