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:
- Pin.
seedling pinparses the target list (Kira'sselect_mandatory_listformat, onefamily[i1, i2, ...]per line) and takes the largest $r$, $s$, $d$ any target reaches (the support of the targets). It applies a floor on $s$ ($s \ge 1$ whenever a target carries numerator powers or lies below a top sector), adds any requested margins, and writesjobs.yaml. - Run.
seedling runchains the steps: support, a margin per class of sectors, a per-sector schedule, the job file, and the memory prediction. - Symmetry maps. With
--sector-mapsnaming Kira'ssectorSymmetriesorsectorRelationsfile,runfirst closes the target list under the family's symmetry maps. A sector that receives images of targets is sized from those images' own $r$, $s$, $d$, with no blanket margin. Images the map file cannot decide are reported in the run logledger.jsonl, never dropped. - Execute.
runlaunches Kira only when--executeand--cgroup NAME,MEM_MAX,CPU_MAXare both given, inside a new Linux control group with those memory and CPU caps. Each phase's peak memory and exit status go into the run log as one JSON line. - Two-slice check. The reduced targets, evaluated at one numerical point, are compared with reference values computed separately. If some differ, a second point decides between a seed box that is too small (
FAIL_PIN) and an artifact of the first evaluation (RERUN_SLICE). - Census. The differential-equation census lists the integrals that an auxiliary-massa fictitious mass added to chosen propagators, as in the auxiliary-mass-flow method differential equation will need: each master with one chosen propagator raised by a power. It reports those that are neither masters nor already compared, and writes a small Kira job for them.
- Failures. A step that raises an error ends the command with a nonzero exit code and a
phase=failedrecord. A check with no inputs is recorded asSKIPPEDwith the reason, and an executed run exits nonzero unless the two-slice check passed. When the box was too small, theescalatemodule proposes the next margins to try.
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:
- It does not choose targets or a master basis and does no symbolic reconstruction.
- A trivial group from
auditdoes not prove a basis minimal, since symmetries that cannot be realized as momentum maps are invisible to it. seedling run --margins m2(the default) reads its margins from a frozen model and a label file that are not part of the package (SEEDLING_ML_DIRandSEEDLING_LABELS, or--labels). Without them it stops with an error at the margins step.--margins constapplies a fixed margin of 6 with the same floors and needs no external files.pin,preflightand the checks need no model or label file.
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>.
| Command | What it does |
|---|---|
seedling pin | Measures the support of the targets and writes a restricted jobs.yaml; with --execute --cgroup it also runs Kira |
seedling run | All steps in one command; with --execute --cgroup also the Kira run, the two checks, the certificates and the run log |
seedling preflight | Predicted equations and memory for one $(r,s,d)$ box, from Kira's list of sectors |
seedling certify | The two-slice comparison of reduced expressions given as JSON files; exit code 0 only on PASS |
seedling census | The differential-equation census, from a JSON list of masters and the positions of the mass-carrying propagators |
seedling ledger | Prints the ledger.jsonl of a run directory |
seedling audit | The discrete symmetry group of a family, and the relation files for Kira |
seedling identity | The same-family check of two propagator lists |
| Option | What 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.
| Function | What it returns |
|---|---|
support.parse_targets, global_support, support_table | The target list read from a file, and the largest $r$, $s$, $d$ overall and per sector |
support.symmetry_closure | The target list closed under a Kira sector-map file, and a report of added, undecidable and mismatched images |
pinner.chain_s_floor, pinned_cell | The minimum safe $s$, and the final box after floor and margins |
pinner.emit_jobs_yaml, build_schedule, render_schedule_jobs_yaml | The Kira job text for one box or for a per-sector schedule |
bulkmodel.seeds_per_sector, bulk, preflight | The seed count $N_\sigma$, the equation count and the memory prediction |
margins.predict_margins | Margins per class of sectors (grouped by propagator count) in m2 or const mode, with the floors applied |
certify.two_slice_certify | PASS, 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_spec | The integrals a differential equation needs, those not yet covered, and a small Kira job for them |
escalate.next_margins | The next margins to try, with one of the actions ESCALATE, REFER, RUN_MINIKIRA, GIVE_UP |
rankcheck.rank_report | The basis verdict SHORT, LONG, OK or SUSPECT; OK needs a master count or a symmetry map from another source |
receipts.emit_receipts | Per-target elimination certificates, written through Winnow |
audit.load_family, audit.run | A 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
- Runs on: Python 3.10 or newer with
sympyandpyyaml. - Install: installing the package with pip provides the
seedlingconsole script. Otherwise put the directory that contains the package onPYTHONPATHand callpython3 -m seedling.cli. - Self-test: run the command below from the repository root. 52 tests need no external data. One of them makes a real control group under the test process's own and is skipped where the kernel refuses. Two more are skipped unless
SEEDLING_ML_DIRandSEEDLING_LABELSare set. Add-rsto see skipped tests by name.
PYTHONPATH=tools python3 -m pytest tools/seedling/tests -q
- Optional: Kira, for
--executeonly. Winnow (theibplapperlibrary), for the hook modules and certificates ofrunonly.
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).
| Reference | What it supplies |
|---|---|
| P. Maierhöfer, J. Usovitsch and P. Uwer, Kira, arXiv:1705.05610 | The 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.06494 | Kira with finite-field methods |
| F. Lange, J. Usovitsch and Z. Wu, Kira 3, arXiv:2505.20197 | Kira's own seeding and equation selection; Seedling sets Kira's $r$, $s$, $d$ inputs |
| S. Laporta, hep-ph/0102033 | The 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.08879 | The propagator list of the built-in identity example |