Numkin
Numkin is for integration-by-parts reductionslarge sparse linear solves that write every Feynman integral of a family as a combination of a few "master" integrals with rational-function coefficients that stall because two symbolic scales are kept at once. Given the equation files that the reduction program Kira has already generated, it sets one kinematic invarianta squared mass or squared momentum on which the integrals depend to several rational values, reduces at each value, and reconstructs the exact dependence on it. Reducing at numerical values of a variable and reconstructing it afterwards is an established strategy: Belitsky, Smirnov and Yakovlev published it for FIRE (arXiv:2303.02511), and FireFlya library that rebuilds an exact rational function from many numerical evaluations over finite fields and Kira provide it too.
What it does
The coefficients of a reduction are rational functions of the dimension $d$ and the kinematic invariants. Kira delegates them to FireFly. With only $d$ symbolic the reconstruction is usually fast. With $d$ and one invariant both symbolic, a few high-degree entries can stall the same system. More memory does not help, because the time goes into the two-variable reconstruction.
Numkin is a set of driver scripts around Kira, FireFly and Fermat, and around AMFlow for the shift search. Its main route has three steps.
- Stage.
numkin_sweep.sh stagecopies a finished Kira generation directory and writes a rational value for the chosen invariant, say $m^2=101$, into everySYSTEM_*.gzfile by word-boundary text substitution, so equation generation is never repeated. It also removes the invariant from the copied configuration, because FireFly stays in two-variable mode if the symbol is left anywhere in it. - Run.
numkin_sweep.sh runruns Kira withrun_initiate: falseand FireFly on that directory. Each point gives coefficients that are exact rational functions of $d$ alone. - Reconstruct.
numkin_harvest.pyrebuilds each coefficient in both variables by exact rational (Padé) interpolation, first in the frozen variable and then in $d$.
The reconstructed coefficient is
$$c(d,x)=\frac{\sum_b N_b(d)\,x^b}{\sum_b D_b(d)\,x^b},$$
where $x$ is the frozen variable. The interpolation uses integer-matrix nullspaces from python-flint, so no floating-point number enters. The highest-numbered points (two by default) are kept out of the fit and every entry must reproduce them exactly. An entry that fails, or whose degrees cannot be fixed from the points (the code raises DGridInsufficient), is listed under failed_entries and left out; the remedy is more points. The output is a JSON file with $N_b$ and $D_b$ for each entry, plus optionally a .m file in Kira's kira2math format.
Three smaller parts cover related cases.
- Shift search.
shift_opt.pyis for the reductions behind AMFlow's differential equation in the auxiliary mass $\eta$. An affine loop-momentum shift with unit Jacobian leaves an integral without numerators unchanged but can shrink the reduction of a sectorthe integrals of a family that share the same set of propagators by a large factor. The script probes each shift and sector with a short capped AMFlow run and reports the smallest system. - Numeric-dimension rerun. The
etarerun/scripts take a stalled AMFlowtarget_reduce/directory whose equations contain only $d$ and $\eta$, substitute $d=4-2\epsilon$ at a rational $\epsilon$, and relaunch with one-variable FireFly. - Exact solve in a known basis.
basisland.pyhandles a function known to be a combination of given basis functions. It finds the rank and a pivot subset from sample rows, solves the overdetermined system exactly by modular elimination over many primes, and verifies every row. The number of samples needed scales with the dimension of the space and does not grow with the number of variables.
Numkin has these limits:
- The sweep needs a completed Kira generation pass and is pointless for a single kinematic point.
- Do not freeze $d$ with
numkin_sweep.sh; useetarerun/. - Avoid values where the system degenerates. At a degenerate point Kira returns a reduction that looks valid and is wrong.
shift_opt.pycovers only integrals without irreducible numerators.basisland.pyneeds a known spanning set and exact rational rows. Without a basis use the Padé route or Ratfit.
Examples
Run the self-test suite. The self-test needs only Python 3 with NumPy and SymPy, and no Kira (see Requirements). Run it from the root of the BootLoops repository; the package directory is tools/numkin/:
python3 tools/numkin/selftest.py
The script runs basisland.py on a synthetic 5-by-3 system with a known answer: solve must return exactly 2, -3/7, 5 with all 5 rows verified. Three [PASS] lines and a last line beginning OVERALL: PASS, in a few seconds, mean the install is good.
Freeze a mass and sweep. The usage text of numkin_sweep.sh stages point 0 of a sweep in $m^2$ for a family box3L, reducing two sectors, then runs it on 8 threads:
cat > reduce.yaml <<'EOF'
- {topologies: [box3L], sectors: [1023], r: 13, s: 1, d: 3}
- {topologies: [box3L], sectors: [170], r: 10, s: 1}
EOF
numkin_sweep.sh stage box3L /scratch/gen_pass_dir \
m2 101 /scratch/sec1023_numkin 0 \
preferred_masters de_targets_top30 reduce.yaml
numkin_sweep.sh run /scratch/sec1023_numkin 0 8
stage leaves a ready-to-run Kira job in /scratch/sec1023_numkin/pt_0: jobs.yaml, the substituted equation files, a config/ with m2 removed, a link to the source sectormappings/, and m2val with the value. run writes run.log and prints the name of the first result file under results/. Repeat with point identifiers 1, 2, ... at other values; p/q is accepted, and the identifiers must be numeric because numkin_harvest.py reads pt_<number> directories.
Then reconstruct:
python3 tools/numkin/numkin_harvest.py --family FAM --targets-file F \
--pts-dir DIR --var m2 --held-out 2 --out OUT.json \
[--out-m OUT.m] [--min-fit-pts N]
Here FAM is box3L, F is the target list de_targets_top30 and DIR is the sweep directory; bracketed arguments are optional. The log names the fit and verification points and ends with counts of entries reconstructed, failed and skipped. Called before any point has finished, it writes a JSON file with no entries and exits, so it is safe to run during the sweep.
Search loop-momentum shifts for a slow AMFlow sector. From the usage text of shift_opt.py: build one named shift for sector 510 of a template AMFlow input, or probe the standard catalog on sector 1022:
shift_opt.py build TEMPLATE.json --shift 'k2sh:k2=l+p1-k2' \
--sec 510:0,2,1,1,1,1,1,1,1,0 --out DIR
shift_opt.py probe TEMPLATE.json --sec 1022:0,1,2,1,1,1,1,1,1,1 \
--catalog --out DIR --amf /path/to/amflow_cli
build writes one AMFlow input in_<tag>_sec<sector>.json per shift and sector, with the physical propagators shifted and the auxiliary numerators chosen again to complete the set. probe also launches each input and stops any probe still running at the --cap limit (480 seconds by default). It writes SHIFT_PROBE.json, which gives for each shift and sector the number of $\eta$ masters, the equation count and the first Fermat item count. Use the shift with the smallest numbers for that sector; the best shift can differ from sector to sector.
Routines
| Command | What it does |
|---|---|
numkin_sweep.sh stage FAM SYS_DIR VAR VALUE OUT_DIR PT_ID PREFERRED_MASTERS TARGETS_FILE REDUCE_YAML | Stages one point of the sweep |
numkin_sweep.sh run OUT_DIR PT_ID NTHREADS [KIRA_BIN] [FERMATPATH] | Runs Kira with FireFly on a staged point |
numkin_harvest.py | Reconstructs every coefficient, verifies it on the held-out points, writes the JSON and the optional .m file |
shift_opt.py build TEMPLATE.json --sec ... [--shift tag:loop=expr] [--catalog] [--n-phys] [--out] | Writes one shifted AMFlow input per shift and sector |
shift_opt.py probe ... [--amf] [--wrap] [--cap] | Builds, launches capped probes, writes SHIFT_PROBE.json |
shift_opt.py harvest ... | Reads existing probe directories into SHIFT_PROBE.json without launching |
basisland.py rank IN.json OUT.json [nprimes=3] | Rank and pivot symbols of the sample rows, which must agree across primes |
basisland.py solve IN.json OUT.json [nprimes=96] | Exact solution vectors, several right-hand sides allowed, every row verified |
etarerun/etanumd_convert.sh SRC DST EPS_PQ [PARALLEL] [MEM_GB] [--nolaunch] | Substitutes $d=4-2\epsilon$ at $\epsilon=$P/Q in a copy of target_reduce/, rewrites jobs.yaml for FireFly, launches Kira detached |
etarerun/etanumd_2varff.sh SRC DST [PARALLEL] [MEM_GB] [--nolaunch] | The same relaunch with no substitution, both $d$ and $\eta$ symbolic |
etarerun/check_degd.py | Estimates the degree in $d$ from two or more finished reruns and prints how many a reconstruction needs |
etarerun/inject_ibpcache.sh KIRA_TARGET_M AMFLOW_LOG IN_JSON OUT_JSON | Places a reconstructed kira_target.m in AMFlow's reduction cache under the key the stalled run missed |
etarerun/inject/extract_shared_rows.py, rebase_invert.py | Reuse rows already reduced in one rerun inside another, after exactly inverting the change of master basis |
NUMKIN_STAGE_PAR sets how many files stage substitutes in parallel. basisland.py solve exits with code 2 on a rank deficit and names the columns, with 3 when more primes are needed, and with 4 on any verification miss. From Python, numkin.basisland has the same two commands as rank_verb and solve_verb.
Beside each probe log, probe writes <log>.memfence.json with the memory-limit settings that the launched AMFlow process received. If they differ from the requested settings, probe stops that process and exits with an error.
check_degd.py reads ETANUMD_DIR and ETANUMD_FAM, and inject_ibpcache.sh reads AMFLOW_IBP_CACHE_DIR. FARM_LAUNCHERS.sh and, in inject/, build_M1_injected.sh, merge_M1_injected.sh and FARM_M1_INJECTED.sh are launch, build and splice templates; their inputs come from ETANUMD_* variables with no defaults. GUIDE.md in the package lists the invocations, inputs, outputs and environment variables.
Used on this site
- Crossed light-by-light box: exact rational reconstruction of the two-variable differential-equation entries from reductions at numerical kinematic points.
Requirements
- Runs on: Bash and Python 3. The
etarerun/launch scripts need Linux. - Sweep and numeric-dimension rerun: Kira, FireFly and Fermat. The
etarerun/launch scripts preload jemalloc (library path fromJEMALLOC) and take the Fermat binary fromFERMATPATH, falling back to the usual Debian/Ubuntu install paths. - Reconstruction:
numkin_harvest.pyneeds python-flint and thekira_parsemodule fromtools/frobenius-boundary/in the same repository, found automatically when the packages sit side by side. - Shift search:
shift_opt.pyneeds SymPy and an AMFlow command-line build with its launch wrapper (--amf/--wraporAMFLOW_CLI/AMFLOW_WRAP). It importsamflow_kit.memfencefromtools/amflow-kit/in the same repository (see AMFlow); that module uses only the standard library and needs Linux, since it reads/procand cgroup v2. - Exact solve:
basisland.pyneeds NumPy and SymPy. - Self-test:
python3 tools/numkin/selftest.pyends with a line beginningOVERALL: PASS. It needs no Kira and coversbasisland.pyonly; the other parts are skipped because they need Kira, FireFly and Fermat.
Source and references
The code is tools/numkin/ in the BootLoops repository. tools/numkin_sweep.sh, tools/numkin_harvest.py and tools/shift_opt.py forward to it.
| Reference | What it supplies |
|---|---|
Belitsky, Smirnov and Yakovlev, arXiv:2303.02511, with Reconstruction.m in FIRE | The published strategy: reduce at numerical values of a variable, then reconstruct the variable |
| J. Klappert, F. Lange, P. Maierhöfer and J. Usovitsch, arXiv:2008.06494 | Kira, the reduction program Numkin runs and whose generated equation files it reuses |
| J. Klappert, S. Y. Klein and F. Lange, arXiv:2004.01463 | FireFly, which reconstructs the dependence on $d$ at each point |
| R. H. Lewis, Fermat | The computer algebra program that Kira runs |
| X. Liu and Y.-Q. Ma, arXiv:2201.11669 | AMFlow, whose auxiliary-mass reductions shift_opt.py and etarerun/ work on |
| P. S. Wang, SYMSAC '81, p. 212, doi:10.1145/800206.806398 | The rational reconstruction in basisland.py |