Seedling

Seedling prepares, sizes and checks integration-by-parts reductionswriting every Feynman integral of a family as a linear combination of a few master integrals, by solving a large linear system of identities among them that are run with Kira, the reduction program of Maierhöfer, Usovitsch, Uwer and collaborators. From a family definition and a target list it finds the smallest range of seed integralsthe integrals from which the integration-by-parts identities are generated the targets need, writes the Kira job file, predicts the memory, and afterwards compares the results with reference values. Before a first reduction, audit searches for the family symmetries described in the Kira paper (arXiv:1705.05610), and identity tests whether a propagator list copied from a paper defines your family.

What it does

Integration-by-parts reduction in Laporta's form generates identities from a box of "seed" integrals and then eliminates the resulting linear system. Kira describes the box by three integers per sectorthe subset of propagators that appear with positive power. They are $r$, the sum of the positive propagator powers; $s$, the total power of numerator factors; and $d = r - t$, the extra powers ("dots") beyond the $t$ propagators of the sector.

A box that is too large runs out of memory during equation generation. A box that is too small can give a system that solves, with no error message, onto wrong values. Seedling measures the box that the targets need, runs Kira on it and checks the result:

seedling preflight predicts the size and memory of the system for one box before anything runs. For a sector with $t$ propagators in a family with $n$ scalar products, $m = n - t$ of them numerators, the box holds

$$N_\sigma(r,s,d) = \binom{\min(d,\,r-t)+t}{t}\binom{s+m}{m}$$

seeds. The equation count is the number of integration-by-parts operators times the sum over sectors. Memory in Kira's two generation phases is modeled as linear in that count. The constants were calibrated on one family, so read the prediction as an estimate good to about a factor of two. The binomial in $s$ grows like $s^m$, which is why numerator margins are the last thing to widen.

The family checks need no reduction. seedling audit computes the discrete symmetry group of a family. Each symmetry is a permutation of the external legs that preserves the kinematic invariants, optionally with every momentum reversed, followed by an integer change of loop momenta of determinant $\pm 1$ that permutes the denominators. These are the symmetries described in section 2 of the Kira paper of Maierhöfer, Usovitsch and Uwer (arXiv:1705.05610).

Kira 3.0 and 3.1 as released do not combine a loop-momentum map with a permutation of the external legs. With those versions, a family whose symmetry needs one keeps redundant masters unless you supply the relations. audit writes the relations in Kira's formats after checking each generator again by substitution.

seedling identity decides whether two propagator lists define the same family. It builds the second Symanzik polynomial (the $F$ polynomial of the Feynman-parameter representation) for both and solves for an affine map between scalar products that carries one onto the other. The usual error is a transcription onto a different momentum convention, which defines a different family that still reduces without complaint.

Seedling has these limits:

Trust checks the output of a finished reduction. Seedling writes the certificates of run with Winnow, an elimination library.

Examples

Write a restricted job file. With the package set up (see Requirements; the code is in tools/seedling/), give pin a Kira configuration directory and a target list. pin is a dry run by default, and bracketed parts are optional:

seedling pin --config CONFIGDIR --targets target --out RUNDIR \
             [--margin r:0,s:0,d:0] [--preferred preferred] \
             [--execute --cgroup NAME,12G,"400000 100000"]

The command reads the family name and top sectors from CONFIGDIR/integralfamilies.yaml. It prints one line with the measured support $(r,s,d)$ and the box chosen after the floor and margins, and writes RUNDIR/jobs.yaml. With --execute --cgroup it also runs Kira in a control group named NAME, created with sudo and capped here at 12 GB and four CPUs (the Linux cpu.max quota and period). The run is recorded in RUNDIR/ledger.jsonl.

Use a new RUNDIR for every box, because a changed jobs.yaml changes the keys of Kira's own result cache.

Predict the size of a box before running it. Equation count and memory for one candidate $(r,s,d)$ box:

seedling preflight --census sectormappings/<fam>/nonTrivialSector \
                   --top 255 --nsp 15 --nops 18 --cell 13,1,6

--census names Kira's list of the non-trivial sectors of the family, and --top keeps sectors with id at most 255. --nsp is the number of scalar products and --cell the $(r,s,d)$ box. --nops is the number of integration-by-parts operators, $L(L+E)$ for $L$ loops and $E$ independent external momenta, here $3 \times 6$. The output is a JSON object with the sectors counted, the predicted equations (bulk_eqns), the memory floor of the selection phase (select_floor_GB) and the predicted peak of the generation phase (generate_peak_GB).

Check a family before its first reduction.

seedling audit CONFIGDIR
seedling identity --ours fam.json --theirs Propagators.m --swap "l->k,k->p"

audit takes a Kira configuration directory or an AMFlow input JSON. It prints the group order and each generator's action on propagators and loop momenta, and writes <fam>_AUT.json beside the configuration (or under --out). When the group is non-trivial it also writes <fam>_aut_relations.kira and <fam>_magic_relations.yaml, and warns if the Kira configuration lacks magic_relations: true.

On the equal-mass sunrise included with the tests the group has order 6; on the included one-loop box with three different masses it is trivial. Results are cached by a hash of the family, beside the module or in the directory named by FAMILY_AUT_CACHE (--no-cache recomputes).

identity compares your family definition with a propagator list in Mathematica or JSON form. --swap renames the other list's momentum symbols first, all at once, so l->k,k->p does not cascade. The run ends with VERDICT: PASS (exit code 0) or VERDICT: FAIL (exit code 1) and the reason, for example the monomial at which no dictionary exists. --out F writes the verdict as JSON. With no arguments seedling identity runs a built-in regression example.

Routines

Every command is seedling <subcommand> or python3 -m seedling.cli <subcommand>.

CommandWhat it does
seedling pinMeasures the support of the targets and writes a restricted jobs.yaml; with --execute --cgroup it also runs Kira
seedling runAll steps in one command; with --execute --cgroup also the Kira run, the two checks, the certificates and the run log
seedling preflightPredicted equations and memory for one $(r,s,d)$ box, from Kira's list of sectors
seedling certifyThe two-slice comparison of reduced expressions given as JSON files; exit code 0 only on PASS
seedling censusThe differential-equation census, from a JSON list of masters and the positions of the mass-carrying propagators
seedling ledgerPrints the ledger.jsonl of a run directory
seedling auditThe discrete symmetry group of a family, and the relation files for Kira
seedling identityThe same-family check of two propagator lists
OptionWhat it does
--unsafe-s0 (pin, run)Drops the floor on $s$ and says so in the output
--kira-cmd (pin, run)The Kira command; without it, kira --parallel=4 jobs.yaml
--fresh, --ref, --fresh2, --ref2 (run, certify)The JSON files of the two-slice check: reduced and reference values at the first and second point
--slice-hook (run)A module of yours that supplies the files of the two-slice check
--receipt-hook (run)A module of yours that writes the certificates
--eta-props (run, census)The positions of the mass-carrying propagators
--gated (census)A JSON list of integrals already checked
--emit-minikira DIR with --config (census)Writes a Kira job for the integrals not yet covered

A malformed --cgroup spec is refused with exit code 2 before anything is written. Malformed means a name with a character outside [A-Za-z0-9_.-], a name made of dots, or a memory or CPU value that is empty or not a literal. GUIDE.md in the package gives the command line of each subcommand, including the options of audit and identity that are not shown here.

The functions below are imported from the package seedling. GUIDE.md names the modules.

FunctionWhat it returns
support.parse_targets, global_support, support_tableThe target list read from a file, and the largest $r$, $s$, $d$ overall and per sector
support.symmetry_closureThe target list closed under a Kira sector-map file, and a report of added, undecidable and mismatched images
pinner.chain_s_floor, pinned_cellThe minimum safe $s$, and the final box after floor and margins
pinner.emit_jobs_yaml, build_schedule, render_schedule_jobs_yamlThe Kira job text for one box or for a per-sector schedule
bulkmodel.seeds_per_sector, bulk, preflightThe seed count $N_\sigma$, the equation count and the memory prediction
margins.predict_marginsMargins per class of sectors (grouped by propagator count) in m2 or const mode, with the floors applied
certify.two_slice_certifyPASS, RERUN_SLICE, FAIL_PIN, or NEED_SECOND_SLICE when the first point failed and no second was supplied
runner.de_row_census, de_census_gate, minikira_specThe integrals a differential equation needs, those not yet covered, and a small Kira job for them
escalate.next_marginsThe next margins to try, with one of the actions ESCALATE, REFER, RUN_MINIKIRA, GIVE_UP
rankcheck.rank_reportThe basis verdict SHORT, LONG, OK or SUSPECT; OK needs a master count or a symmetry map from another source
receipts.emit_receiptsPer-target elimination certificates, written through Winnow
audit.load_family, audit.runA family read from a Kira directory or an AMFlow JSON, and the result of the symmetry search
audit.identity_check_general(argv)The identity subcommand as a function

Requirements

PYTHONPATH=tools python3 -m pytest tools/seedling/tests -q

Source and references

The code is in tools/seedling/ in the BootLoops repository. The staging model is described in the accompanying paper, Seedling: learning how much to stage in integration-by-parts reduction (PDF).

ReferenceWhat it supplies
P. Maierhöfer, J. Usovitsch and P. Uwer, Kira, arXiv:1705.05610The reduction program that Seedling prepares jobs for; section 2 describes the symmetries that audit searches for
J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, Kira 2.0, arXiv:2008.06494Kira with finite-field methods
F. Lange, J. Usovitsch and Z. Wu, Kira 3, arXiv:2505.20197Kira's own seeding and equation selection; Seedling sets Kira's $r$, $s$, $d$ inputs
S. Laporta, hep-ph/0102033The reduction algorithm whose seed integrals Seedling sizes
W.-J. He, R.-Y. Zhang, L. Han, Y. Jiang, Z. Li, X.-F. Wang, S.-X. Li, P.-F. Li and Q.-h. Wang, arXiv:2409.08879The propagator list of the built-in identity example

← back to the tools index