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 portSourceAuthors
Compiled programs redg1, fitrel, ssolve, recmod, dynamicrr: the authors' search, fit, solve and reconstruction programsBlade at commit c0a06cbGuan, Liu, Ma and Wu
Translated modules extension.py, ansatz.py, scheme.py, search.py, adaptive.py, semibl.pyBlade's Wolfram-language files, cited by line in each moduleGuan, Liu, Ma and Wu
Transcribed C wrappers in fflowC.cc and fflowC_stream.ccfflowmlink.cc in FiniteFlowT. Peraro
File layouts and order of calls that follow their code: formats.py, pipeline.py, dumppoints, parts of fflowcliBlade's C programs, SolveSemiBL.wl and Database.wl; FiniteFlow's sourceGuan, Liu, Ma and Wu; T. Peraro
probe.py, a Python counterpart of the block solve of ssolvesrc/ssolve/block.cGuan, 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-testWritten for BootLoopsCode 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:

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:

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

CommandWhat 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": [...]}.

FunctionWhat 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_pinA 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

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.

ReferenceWhat 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/bladeBlade: 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.09294The block-triangular search that Blade implements
T. Peraro, FiniteFlow, arXiv:1905.08019; code: github.com/peraro/finiteflowThe finite-field library that Blade runs on, linked unmodified and not bundled; fflowmlink.cc, the source of the transcribed C wrappers

← back to the tools index