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.

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.

Numkin has these limits:

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

CommandWhat it does
numkin_sweep.sh stage FAM SYS_DIR VAR VALUE OUT_DIR PT_ID PREFERRED_MASTERS TARGETS_FILE REDUCE_YAMLStages 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.pyReconstructs 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.pyEstimates 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_JSONPlaces 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.pyReuse 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

Requirements

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.

ReferenceWhat it supplies
Belitsky, Smirnov and Yakovlev, arXiv:2303.02511, with Reconstruction.m in FIREThe 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.06494Kira, the reduction program Numkin runs and whose generated equation files it reuses
J. Klappert, S. Y. Klein and F. Lange, arXiv:2004.01463FireFly, which reconstructs the dependence on $d$ at each point
R. H. Lewis, FermatThe computer algebra program that Kira runs
X. Liu and Y.-Q. Ma, arXiv:2201.11669AMFlow, whose auxiliary-mass reductions shift_opt.py and etarerun/ work on
P. S. Wang, SYMSAC '81, p. 212, doi:10.1145/800206.806398The rational reconstruction in basisland.py

← back to the tools index