Blade (external)
Blade is public software by Xin Guan, Xiao Liu, Yan-Qing Ma and Wen-Hao Wu (Peking University) that reduces a family of Feynman integrals to master integralsthe finite basis to which every integral of the family reduces by the block-triangular method. It searches once per family for a small system of relations, and the reduction at each later kinematic point is a short solve of that system. BootLoops uses it for families that must be reduced at many points, through a fork that builds without Mathematica and a Python port of the authors' Wolfram-language code.
Where it comes from
Blade is the program of Guan, Liu, Ma and Wu. It runs on FiniteFlow, the library of Tiziano Peraro for finite-field arithmeticexact arithmetic with integers modulo a large prime; exact rational results are rebuilt afterwards from several primes, which the authors drive from Mathematica. BootLoops adds a fork in which two command-line programs, fflowcli and dumppoints, replace the Mathematica link, and a Python port of the code that runs the search. The fork changes nothing in Blade's algorithms. The programs added in the fork and the Python port were written by Claude with the authors' source open.
| Part of the port | Source | Authors |
|---|---|---|
Compiled programs redg1, fitrel, ssolve, recmod, dynamicrr: the authors' search, fit, solve and reconstruction programs | Blade at commit c0a06cb | Guan, Liu, Ma and Wu |
Translated modules extension.py, ansatz.py, scheme.py, search.py, adaptive.py, semibl.py | Blade's Wolfram-language files, cited by line in each module | Guan, Liu, Ma and Wu |
Transcribed C wrappers in fflowC.cc and fflowC_stream.cc | fflowmlink.cc in FiniteFlow | T. Peraro |
File layouts and order of calls that follow their code: formats.py, pipeline.py, dumppoints, parts of fflowcli | Blade's C programs, SolveSemiBL.wl and Database.wl; FiniteFlow's source | Guan, Liu, Ma and Wu; T. Peraro |
probe.py, a Python counterpart of the block solve of ssolve | src/ssolve/block.c | Guan, Liu, Ma and Wu |
New code: blade_family.py, the Kira-table and raw-system readers of search.py, the degree scan of ratrec.py, the streaming code of fflowcli_stream, the self-test | Written for BootLoops | Code by Claude |
Please cite the authors' papers when you use it. The fork and the port are not affiliated with or endorsed by the authors of Blade or FiniteFlow, and questions about them go to the BootLoops repositories.
What it does
The integrals of one family (one set of propagators raised to different integer powers) are related. Integration-by-parts identitieslinear relations among Feynman integrals that follow from the vanishing of total derivatives under the loop integration express each of them as a combination of the master integrals. The coefficients are rational functions of the kinematic variables and the dimensional regulator $\epsilon$, and finding them is called reduction.
Programs such as Kira eliminate a large sparse linear system and repeat most of that work at every new numerical value of the kinematics. Some methods need the same family at many points, as auxiliary mass flow does. Blade does the work once, in a search.
Working in finite-field arithmetic, Blade finds a small set of relations among the targets (the integrals to be reduced) and the masters whose coefficients are polynomials in the parameters. It fits those polynomials to numerical reduction data and arranges the relations in blocks that are solved one after another. Reducing at a new point then means evaluating the polynomials and solving a short sequence of small linear systems. Sampling over several primes and reconstructing the rational functions gives the full symbolic table.
The BootLoops driver takes a family specification in JSON. Its keys are family (the family name), search_params (the parameters, with eps last), targets (the target integrals as vectors of propagator powers) and optionally masters. The usage text at the top of blade_family.py lists every key. The specification also names one source of numerical reduction data:
- Kira table. A symbolic table named with
kira_table, or found in a Kira output directory withkira_config_dir, and evaluated modulo primes. - Stored samples. A directory of precomputed reduction samples,
database_dir. - Raw system. A sparse linear system in FiniteFlow's JSON format,
fflow_system, with anfflow_columnsmap from columns to integrals and the masters in the highest columns. It is solved numerically point by point, with no Kira.
The output is a family directory: btform.json (parameters, targets, masters, closed blocksthe blocks whose relations the search found, checksums), relations.json (the exact relations) and run_tree/ (the search tree, which the compiled back end of the reducer needs).
The compiled programs can exit with status 0 after a failure, so the library checks the files each program writes (dimensions, byte sizes, agreement across primes) and stops with an error that names the file. Exported relations are verified at a prime not used in the fit. With a Kira table, a final check compares them with that table at a prime never used in the search, and a deliberately wrong input must be rejected.
The port has these limits:
- The driver does not run Kira, and it refuses a specification that names no data source.
- With a raw system, the final check replays the input system's own numerical solve at a new prime. It tests the search and the export, not the input system, which you must validate separately.
- With
database_diralone the final check is skipped. Name akira_tableas well to enable it. - A system on the maximal cut (every propagator of the top-level integral put on shell) should also list
zero_sectors, the sectors (sets of integrals with the same propagators) that vanish under the cut. - If only some blocks close within the time limit, the directory is still written. Open blocks are listed with the reason the search stopped, and appear in a symbolic table as explicit
PENDINGmarkers, never as numbers. - The compiled solver cannot address ten or more parameters. The table builder accepts a Python evaluator callback for those, and
ratrec.reconstructstops at nine variables. - Several families at once is untested, and
preparerequires a fresh working directory.
For a single reduction at one point, run Kira directly.
Examples
Prepare a family, inspect it and reduce it at a few points. With the package set up (see Requirements), run the driver in tools/blade/ from the root of the bootloops checkout. The paths are placeholders.
python3 tools/blade/blade_family.py prepare spec.json --workdir runs/<p>/<tag>/fam
python3 tools/blade/blade_family.py status runs/<p>/<tag>/fam/family/<name>
python3 tools/blade/blade_family.py probe runs/<p>/<tag>/fam/family/<name> \
--points pts.json --prime 9223372036854775783
prepare runs the whole chain: integral-set extension, numerical database, block scheme, polynomial ansatz, the search, rational export and the final check. status prints each target as CLOSED or PENDING and any open blocks with their stop reasons, and probe prints the coefficient of every master in every closed target as an integer modulo the prime. To check the stored relations at a new prime, pass one that prepare did not use; the prime shown is the first entry of FiniteFlow's prime table, which prepare uses.
Call the per-point reducer from Python. From the package guide:
from blade.probe import BTOracle o = BTOracle(family_dir) o.reduce_point(kin, eps, prime)
Loading family_dir verifies the recorded checksums and refuses a modified directory. kin holds integer values of the kinematic parameters, eps the integer substituted for $\epsilon$ and prime any large prime. The result maps each target label to a dictionary {master_label: value}, with values in [0, prime) and zero coefficients omitted.
Reconstruct rational functions from a modular evaluator. Adapted from the package's self-test, which plants two known functions and recovers them exactly:
import sympy as sp
from fractions import Fraction
from blade import ratrec
x, y = sp.symbols("x1 x2")
f1_num = [(3, (2, 1)), (-7, (0, 1)), (Fraction(5, 2), (0, 0))]
f1_den = [(1, (1, 0)), (-2, (0, 1)), (1, (0, 0))]
f2_num = [(Fraction(1, 2), (1, 0)), (Fraction(-1, 3), (0, 0))]
f2_den = [(1, (1, 1)), (4, (0, 0))]
ev1 = ratrec.ratfun_evaluator(f1_num, f1_den)
ev2 = ratrec.ratfun_evaluator(f2_num, f2_den)
def evaluator(coords, prime):
return [ev1(coords, prime), ev2(coords, prime)]
wd, nthreads = "scratch/ratrec_plant", 6 # any empty scratch directory
funcs = ratrec.reconstruct(evaluator, nvars=2, maxdeg=4, nfuns=2,
primes=(0, 1), workdir=wd,
nthreads=nthreads, symbols=(x, y))
Term lists hold (coefficient, exponent_tuple) pairs, so f1_num is $3x_1^2x_2 - 7x_2 + 5/2$. The call returns sympy expressions, here $(3x_1^2x_2 - 7x_2 + \tfrac{5}{2})/(x_1 - 2x_2 + 1)$ and $(\tfrac{1}{2}x_1 - \tfrac{1}{3})/(x_1x_2 + 4)$. primes are consecutive indices into FiniteFlow's fixed prime table, at least two: one to fit and one to verify.
Routines
| Command | What it does |
|---|---|
blade_family.py prepare <spec.json> --workdir W [--max-round-seconds S] [--bank-dir DIR] [--bisect] [--nthreads N] | Builds the family directory from a specification |
blade_family.py probe <family_dir> --points FILE [--prime P] [--batch] [--out FILE] | Prints the master coefficients modulo P at the listed points, as JSON |
blade_family.py status <family_dir> | Verifies the checksums of a family directory and prints a summary |
prepare exits 0 when every block closed, 2 when a partial closure was saved, and 1 or 3 on failure, with ERROR.json naming the file that failed. --max-round-seconds is the limit for one round of the search. The file given to --points is a list [[x1, ..., eps], ...] in the parameter order of btform.json, or an object {"prime": P, "points": [...]}.
| Function | What it returns |
|---|---|
blade.probe.BTOracle(family_dir) | The per-point reducer of the second example |
o.reduce_many(points, prime) | The reductions at a list of (kin, eps) pairs |
o.reduce_many_ssolve(...) | The same from the compiled solver, only at the primes used in preparation, checked against the exact back end on every batch |
blade.probe.BTForm(family_dir) | The loaded and verified manifest |
blade.semibl.SemiBLJob(...) | A symbolic-table job: stage_prime(pid), run_recmod(pid), run_reconstruction(), then assemble_table(), which returns a SemiBLTable (write_text, write_json) |
blade.ratrec.reconstruct(evaluator, nvars, maxdeg, nfuns=1, primes=(0,1,2), ...) | Rational functions, as sympy expressions, from any callable that returns their values modulo a prime |
blade.search.nana_search, fit_at_pin | A search with some parameters pinned to numbers; its relations are marked valid only at the pins |
reconstruct first learns the exact numerator and denominator degrees from the evaluator (pass degrees= to skip this). It then generates the structured sample points that the compiled reconstructor requires.
The fork also builds fflowcli_stream, a version of fflowcli whose evalmany writes results as it goes and can --resume a partial run. The other modules (blade.pipeline, blade.search, blade.extension, blade.scheme, blade.ansatz, blade.adaptive, blade.formats) are described under "Modules" in tools/blade/README.md.
Requirements
- Runs on: Python 3 with
python-flintandsympy. The compiled programs need FiniteFlow, FLINT, GMP and MPFR. - Install: build FiniteFlow inside its own source directory (an out-of-source build misses a generated header). Then clone the fork, the
bladerepository, set the paths in itsinstall.in.txtand runcmake . && make install. - Connect: set
BLADE_BIN_DIRto the fork'sbin/directory. The default is../blade/binrelative to the root of thebootloopscheckout, that is, a sibling checkout of the fork. - Self-test:
cd tools; ulimit -v 32505856; python3 -m blade.selftestends with a line beginningn/n passed, with the two numbers equal. It checks that bad specifications are refused. With the compiled programs built, it also runsprepareon a small test system with known coefficients, probes the stored family at a new prime, and confirms that a deliberately wrong input is rejected. - Long form: add
--full. It replays reference files named byBLADE_PORT_ROOTor--root, which are not distributed with the repository. Without them the command prints a notice and runs only the part above. - Optional:
BLADE_PHASE0_DUMPPOINTSnames a separatedumppoints.
Source and references
The Python library is tools/blade/ in the BootLoops repository, with GUIDE.md, README.md (module notes, limits and known pitfalls) and NOTICE (the authors' notice). The compiled programs are the blade repository, a snapshot of upstream Blade at commit c0a06cb with the four BootLoops patches described in its PATCHES.md; its THIRD_PARTY.md holds T. Peraro's notice for the transcribed wrappers. It is published as a single commit, so the authors' own history is at gitee.com/multiloop-pku/blade.
| Reference | What it supplies |
|---|---|
| X. Guan, X. Liu, Y.-Q. Ma and W.-H. Wu, Comput. Phys. Commun. 310 (2025) 109538, arXiv:2405.14621; code: gitee.com/multiloop-pku/blade | Blade: the compiled programs and the Wolfram-language code that the port translates |
| X. Liu and Y.-Q. Ma, arXiv:1801.10523; X. Guan, X. Liu and Y.-Q. Ma, arXiv:1912.09294 | The block-triangular search that Blade implements |
| T. Peraro, FiniteFlow, arXiv:1905.08019; code: github.com/peraro/finiteflow | The finite-field library that Blade runs on, linked unmodified and not bundled; fflowmlink.cc, the source of the transcribed C wrappers |