Seedling

Seedling prepares, sizes and checks integration-by-parts reductions that are run with Kira. Given a Kira family definition and a list of target integrals, it works out the smallest range of seed integrals the targets need, writes the Kira job file for that range, and predicts the memory the run will take. After the run it compares the reduced integrals with independently computed values. Two further commands check a family before its first reduction: audit finds discrete symmetries that Kira's own search misses, and identity decides whether a propagator list copied from a paper defines the same family as yours.

What it does

Integration-by-parts reductionwriting 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 in Laporta's form generates identities from a box of "seed" integrals, then eliminates the resulting linear system. Kira describes the box by three integers per sectorthe subset of propagators that appear with positive power: $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. Too generous a box runs out of memory during equation generation; too tight a box can give a system that solves, with no error message, onto wrong values. seedling pin measures instead. It parses the target list (Kira's select_mandatory_list format, one family[i1, i2, ...] per line) and takes the largest $r$, $s$, $d$ any target reaches. It then applies a safety floor on $s$ ($s \ge 1$ whenever a target carries numerator powers or lies below a top sector), adds any requested margins, and writes jobs.yaml.

seedling preflight predicts the size and memory of the staged system 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, and 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.

seedling run chains the steps: support, a margin per class of sectors, a per-sector schedule, the job file, and the memory prediction. With --sector-maps naming Kira's sectorSymmetries or sectorRelations file, the target list is first closed under the family's symmetry maps, so a sector that the maps send targets into is staged from those images' own $r$, $s$, $d$ rather than a blanket margin. Images the map file cannot decide are reported in the ledger, never dropped. Only when --execute and --cgroup NAME,MEM_MAX,CPU_MAX are both given does it launch Kira, inside a fresh Linux control group with those memory and CPU caps, logging each phase's time, peak memory and exit status as one JSON line in ledger.jsonl. Two checks follow. The two-slice check compares the reduced targets, evaluated at one numerical point and supplied as JSON files or by a hook module, with independently computed reference values; if some differ, a second point decides whether the seed box is at fault (FAIL_PIN) or the first evaluation was an artifact of that run (RERUN_SLICE). The differential-equation census lists the integrals an auxiliary-mass differential equation will need (each master with one chosen propagator raised by a power), reports those that are neither masters nor already compared, and writes a small Kira job for them. Any stage that raises an error ends the command with a nonzero exit code and a phase=failed record; a check with no inputs is recorded as SKIPPED with the reason, and an executed run exits nonzero unless the two-slice check passed. When the box was too tight, the escalate module proposes the next margins to try.

The family checks need no reduction. seedling audit computes the full discrete symmetry group of a family: external-leg permutations that preserve the kinematic invariants, optionally composed with reversing every momentum, followed by an integer change of loop momenta of determinant $\pm 1$ that permutes the denominators. Kira's own finder never combines a loop-momentum map with a permutation of the external legs, so a family whose symmetry needs one keeps redundant masters unless you supply the relations. audit writes them in Kira's formats after re-verifying each generator 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 carrying one onto the other. The usual catch is a transcription onto a different momentum convention, which defines a different family that still reduces without complaint.

Limits. Seedling does not choose targets or a master basis and does no symbolic reconstruction. A trivial group from audit does not prove a basis minimal, since symmetries not realizable 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_DIR and SEEDLING_LABELS, or --labels), and without them it stops with an error at the margins step. --margins const applies a fixed margin of 6 with the same floors and needs no external files. pin, preflight and the checks need neither.

Examples

Write a restricted job file. From a Kira configuration directory and a target list (pin is a dry run by default; 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, prints one line with the measured support $(r,s,d)$ and the cell chosen after the floor and margins, and writes RUNDIR/jobs.yaml. With --execute --cgroup it also runs the staging command 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), and logs the phase to RUNDIR/ledger.jsonl. A malformed --cgroup spec (a name outside [A-Za-z0-9_.-], a dot-only name, or an empty or non-literal memory or CPU value) is refused with exit code 2 before anything is written. The command is kira --parallel=4 jobs.yaml unless --kira-cmd gives another. Use a fresh RUNDIR per cell, because a changed jobs.yaml changes the keys of Kira's own result cache.

Predict the size of a cell before staging 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

The census file is Kira's list of non-trivial sectors for the family. --top keeps sectors with id at most 255, --nsp is the number of scalar products, --nops the number of integration-by-parts operators ($L(L+E)$ for $L$ loops and $E$ independent external momenta, here $3 \times 6$), and --cell the $(r,s,d)$ box. 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 configuration 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 (simultaneously, so l->k,k->p does not cascade). It ends with VERDICT: PASS (exit code 0) or VERDICT: FAIL with the reason, for example the monomial at which no dictionary exists (exit code 1); --out F writes the verdict as JSON. With no arguments seedling identity runs a built-in regression example.

Routines

Command line (seedling <subcommand> or python3 -m seedling.cli <subcommand>)

• pin — measure target support and write a restricted jobs.yaml; with --execute --cgroup also stage it. --unsafe-s0 (also on run) drops the floor on $s$ and says so in the output.
• run — the full pipeline: support (--sector-maps closes it under the family symmetry maps), margins (--margins m2|const, --labels), schedule, job file, memory prediction, and with --execute --cgroup the Kira run (--kira-cmd), the two-slice check (--fresh/--ref/--fresh2/--ref2 or --slice-hook), the differential-equation census (--eta-props), certificate emission through a caller-supplied module (--receipt-hook) and the ledger.
• preflight — predicted equations and memory for one $(r,s,d)$ cell from a Kira sector census.
• certify — two-slice comparison of reduced expressions given as JSON files; exit 0 only on PASS.
• census — differential-equation census from a JSON list of masters and the mass-carrying propagator positions (--eta-props); --gated names a JSON list of integrals already checked, and --emit-minikira DIR (with --config) writes a Kira job for the uncovered integrals.
• ledger — print a run directory's ledger.jsonl.
• audit — discrete symmetry group of a family; options --out, --max-shift, --n-denom, --no-cache, --report-crossings.
• identity — same-family check; options --ours, --theirs, --theirs-format, --theirs-key, --swap, --masses, --x-perm, --out.

Support, job files, cost model (seedling.support, .pinner, .bulkmodel, .margins)

• parse_targets, global_support, support_table — read a target list; largest $r,s,d$ overall and per sector.
• symmetry_closure — add every image of the targets under a parsed Kira sector-map file, iterated to a fixed point; returns the closed list and a report of added, undecidable and sector-mismatched images.
• chain_s_floor, pinned_cell — the minimum safe $s$ and the final cell after floor and margins.
• render_jobs_yaml, emit_jobs_yaml, build_schedule, render_schedule_jobs_yaml — Kira job text for one cell or for a per-sector schedule.
• seeds_per_sector, bulk, preflight — the seed count $N_\sigma$, the equation count, and the memory prediction.
• predict_margins — margins per class of sectors (grouped by propagator count) in m2 or const mode, floors applied, model checksum attached.

Running and checking (seedling.runner, .certify, .escalate, .rankcheck, .receipts)

• run_phase — run one Kira phase inside a control group and append its record to the ledger.
• two_slice_certify, load_rows_json, split_kira_target_m — load reduced expressions (JSON or Kira's Mathematica output), drop zero coefficients, compare at one or two points; verdict PASS, NEED_SECOND_SLICE (first point failed and no second was supplied), RERUN_SLICE or FAIL_PIN.
• syzygy_certify — optional exact check through a syzygy solver passed in as a function; reports SKIPPED when none is supplied.
• de_row_census, de_census_gate, minikira_spec — the integrals a differential equation needs, which are uncovered, and a small Kira job for them.
• EscalationState, next_margins — the margin-widening state machine (ESCALATE, REFER, RUN_MINIKIRA, GIVE_UP).
• parse_kira_masters, parse_sector_maps, rank_report — read Kira's master list and sector symmetries and report the basis as SHORT, LONG, OK or SUSPECT (never OK without an independent count or map).
• receipts.emit_receipts, receipts.choose_backend — write per-target elimination certificates for a staged system through Winnow; the dense or CPU backend is chosen from a memory estimate against the budget and free address space, with one retry on CPU if a dense allocation fails.

Family checks (seedling.audit)

• load_family — read a family from a Kira configuration directory or an AMFlow JSON.
• run — the whole symmetry search; returns the result dictionary and writes the output files (find_autopermutations, emit_kira_relations, emit_magic_dropin are the separable steps).
• identity_check_general(argv) — the identity subcommand as a function; identity_check_wpair() is the built-in regression example.

Used on this site

• Non-planar $q\bar q\to W^+W^-$ — the identity check proved by matching graph polynomials that the corrected family is the paper's; propagators written for incoming momenta, transplanted onto outgoing kinematics, had first defined a different family with 98 master integrals instead of 76.

Requirements and source

Python 3.10 or newer with sympy and pyyaml. Installing the package with pip provides the seedling console script; otherwise put the directory containing the package on PYTHONPATH and call python3 -m seedling.cli. Kira is needed only for --execute, and Winnow (the ibplapper library) only for the hook modules and certificates of run. The self-tests run from the repository root with

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

(52 tests need no external data; one of them makes a real control group under the test process's own and skips where the kernel refuses, and two more skip unless SEEDLING_ML_DIR and SEEDLING_LABELS are set; add -rs to see skipped tests by name). The code is in tools/seedling/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license, and the staging model is described in the accompanying paper, Seedling: learning how much to stage in integration-by-parts reduction (PDF). Kira is by Maierhöfer, Usovitsch, Uwer and collaborators (arXiv:1705.05610, arXiv:2008.06494); the seeding problem is that of Laporta's algorithm (hep-ph/0102033). Related page: Trust, which checks a finished reduction's output.

← back to the tools index