AMFlow (external)
AMFlow is public software by Xiao Liu and Yan-Qing Ma (version 2.0 with Rui-Jun Huang) that evaluates Feynman integrals numerically to as many digits as you ask for. BootLoops runs AMFlow.cpp, the C++ port of AMFlow by the AMFlow.cpp contributors, from a patched fork, and checks its proposed closed forms against the numbers. Given an integral family, numerical kinematics and a precision goal, the solver returns each requested integral as a series in $\varepsilon=(4-d)/2$, where $d$ is the spacetime dimension.
Where it comes from
The auxiliary-mass-flow method (an integral is obtained from a differential equation in an added mass) originates with Xiao Liu, Yan-Qing Ma and Chen-Yu Wang, and AMFlow is Liu and Ma's Mathematica package for it. AMFlow.cpp is a C++ port of AMFlow by the AMFlow.cpp contributors (maintainer: GitHub user chang18). The derivative routines in AMFlow's interface to the reduction program Kira come from T. Peraro's LiteIBP, and AMFlow.cpp ported them with the rest.
The BootLoops fork is AMFlow.cpp at commit 006a275 (version 1.1.0 plus the unreleased changes in its changelog) with patches. Claude wrote the patches with the Mathematica source of AMFlow 2.0 open.
| Part | Source | Authors |
|---|---|---|
| The solver as forked | AMFlow.cpp, a C++ port of AMFlow | The AMFlow.cpp contributors; AMFlow by X. Liu and Y.-Q. Ma |
| Derivative routines of the reduction interface, part of the solver as forked | LiteIBP, as carried in AMFlow's Kira interface | T. Peraro |
| Patches that follow the authors' code: the count of boundary-matching conditions and the rationalization precision | DESolver.m of AMFlow 2.0 | R.-J. Huang, X. Liu and Y.-Q. Ma |
| Patch in the place of one of the authors' routines: the momentum-derivative chain rule, which AMFlow.cpp had left out | LIBPDerivivative of LiteIBP | T. Peraro; code by Claude |
| New code: the other patches and the validation suite | PATCHES.md credits the papers behind the patches it lists | Code by Claude |
| amflow-kit: new code; its key predictor is a Python port of the cache-key routine that BootLoops added to the fork | src/ibp/ibp_cache.cpp in the fork | Code by Claude |
Work that uses the solver should cite Liu and Ma (arXiv:2201.11669) and Liu, Ma and Wang (arXiv:1711.09572), together with AMFlow.cpp. The fork is not affiliated with or endorsed by the authors of AMFlow, AMFlow.cpp or LiteIBP.
What it does
The auxiliary-mass-flow method adds a fictitious mass $\eta$ to chosen propagators, $1/(q^2-m^2)\to 1/(q^2-m^2-\eta)$. At very large $\eta$ the integral reduces to vacuum integrals (integrals with no external momenta) whose values are known exactly.
The solver sets up the differential equation in $\eta$ obeyed by the master integralsthe small set of basis integrals in terms of which every integral of the family can be written. It solves that equation numerically, as a chain of power-series expansions from large $\eta$ down to $\eta=0$, and reads off the physical value there. Building the equation requires an IBP reductionintegration-by-parts reduction: the linear-algebra step that rewrites every integral of a family as a combination of the master integrals, which the solver delegates to the external programs Kira and Fermat.
The input is a JSON job file. It names the family (momenta, propagators, kinematic replacement rules), the target integrals by their propagator powers, a value for every kinematic symbol, goal_digits and eps_order. The output JSON has a result array with one entry per target. Its coefficients give each power of $\varepsilon$, with real and imaginary parts printed as balls [midpoint +/- radius]. The radius is the solver's own error estimate.
One convention needs care. For an $L$-loop integral, eps_order = K + 2L returns the series through $\varepsilon^K$, so the finite part needs eps_order of at least $2L$. In the stock code, asking for too little could return a lone zero that looks like a vanishing finite part. The patched solver prints the range of powers it fitted, raises a too-small eps_order to $2L$ with a warning, and stops with an error rather than return such a zero. The preferred key target_eps_power states the wanted power $K$ directly.
On the default path the BootLoops patches leave the algorithm unchanged. PATCHES.md in the fork lists the main ones. They fall into four groups:
- Precision. The main fix is in the step that matches solutions at $\eta\to 0$. At very fine $\varepsilon$ grids the stock code could merge two distinct power behaviors and return wrong coefficients with no error.
- Reduction. The embedded Kira reduction recovers from crashes and stalls and resumes after a kill.
- Long runs. The $\eta$-flow solves have checkpoint and resume, the $\varepsilon$ grid runs in parallel, and reductions are cached across jobs.
- Boundaries. The fork adds boundary and vacuum cases, some of them experimental. Among them are integrals with linear propagators, whose auxiliary-mass-flow treatment is due to Z.-F. Liu and Y.-Q. Ma (arXiv:2201.11636).
Everything BootLoops runs around the solver is collected in the package amflow-kit (tools/amflow-kit/, Python import name amflow_kit). The package builds nothing and its tests need no solver binary. It has three parts, described under Routines:
- Output checks. Three scripts check
solve_integralsoutput: a per-file check, a smoke test (a short run with known answers) for a freshly built binary, and a digit-by-digit comparison of two outputs of the same job. - Key predictor. The module
amflow_kit.keypredpredicts the key under which the solver's reduction cache will store a reduction. - Memory limit. The module
amflow_kit.memfencesets the memory limit of every solver process that PMflow and theshift_opt.pyscript of Numkin start.
The solver has these limits:
- The result is a numerical value with an error estimate, not a proof. In practice BootLoops runs the same point at two precision goals and trusts the digits on which the two runs agree.
- It does not accept complex-valued kinematics.
- On large families at high digit counts the practical limit is the memory and time of the Kira reduction.
For a second opinion on an AMFlow number BootLoops uses pySecDec and FIESTA. Closed forms are compared against AMFlow's digits with the PSLQ and LLL tools. The reduction programs have their own Kira page.
Examples
Evaluate the one-loop massive bubble. The fork includes this job as examples/bubble_solve_integrals.json:
{
"mode": "solve_integrals",
"options": {
"chop_pre": 20,
"silent_mode": true
},
"family": {
"name": "bubblefam",
"loops": ["l"],
"legs": ["p"],
"replacement": {
"p^2": "s"
},
"propagators": [
"l^2 - msq",
"(l - p)^2 - msq"
]
},
"integrals": [
{ "indices": [1, 1] }
],
"goal_digits": 25,
"eps_order": 2,
"work_dir": "/tmp/desolver_example_bubble",
"amf_options": {
"blackbox": {
"numeric_values": {
"s": "5",
"msq": "1"
}
}
}
}
With the solver built (see Requirements) and Kira and Fermat installed, run it from the root of the amflow-cpp repository:
./build/src/cli/amflow_cli examples/bubble_solve_integrals.json
Kira's intermediate files go under work_dir. In the printed JSON, result[0].integral echoes the family and indices and result[0].coefficients holds one {order, value} pair per power of $\varepsilon$. With eps_order 2 and $L=1$ the series runs through $\varepsilon^0$, that is the $1/\varepsilon$ pole and the finite part, each good to about 25 digits.
Check output files before using them. Run amflow_output_lint.py from tools/amflow-kit/:
python3 amflow_output_lint.py out_*.json [--class vacuum|kinematic] [--allow-shallow] [--min-nonzero-frac F] [--in job.json] [-q]
The script stops with a nonzero exit code in these cases:
- the file is all zeros;
- fewer than half of the integrals are nonzero (
--min-nonzero-fracsets the fraction); - a nonzero integral carries fewer than two nonzero orders;
- a value does not parse as a ball with a finite midpoint;
- with
--class vacuum, no integral has a pole (any multi-loop vacuum family must have one).
An integral that comes out exactly zero among nonzero ones only produces a warning.
Compare two outputs of the same job, for example one point at two precision goals:
python3 compare_amflow_json.py REF.json TEST.json [--min-digits 25] [--n-integrals N] [--goal G|GREF,GTEST | --goal-from-config REF_CFG[,TEST_CFG] | --radii-only] [--strict-window]
The comparator needs the precision goal $G$ of the runs to decide what counts as zero:
- Numerical zero. A pair of coefficients that are both smaller than $T=\max(\text{radii},\,10^{-(G-2)})$, with $G$ the lower of the two goals, is reported as a numerical zero and left out of the digit count. A zero against a value above $T$ fails.
- The goal. Give it with
--goal(one value, orGREF,GTEST) or with--goal-from-confignaming the job file or files, whosegoal_digitsis read. With neither flag the job file is looked up by name: an output atout/<name>.jsonpairs withconfigs/<name>.jsonunder the same parent directory. - No goal. With no goal from any of these the script refuses and compares nothing (exit code 2). With
--radii-onlyit takes the threshold from the two error radii alone. - Missing orders. An $\varepsilon$ order present in only one file is reported as not compared, not as failed, unless
--strict-windowis given.
The script prints the matched decimal digits for every coefficient and marks each PASS or FAIL against --min-digits. It ends with a line such as OVERALL: PASS (10 compared, 4 numerical zeros excluded, 2 orders not compared), exit code 0 or 1.
Smoke-test a freshly built binary.
amflow_smoke.sh BINARY_PATH [JOB_TIMEOUT_SECONDS]
The script runs two fixture jobs with known answers through the binary: a two-loop vacuum probe with five integrals and a one-loop triangle job restricted to its first two integrals. Both outputs go through amflow_output_lint.py and must match the reference outputs to at least 20 significant digits. When both pass, the last line is RESULT: PASS and the exit code is 0.
Routines
The solver (patched AMFlow.cpp, the amflow-cpp repository)
| Command or key | What it does |
|---|---|
amflow_cli input.json [output.json] | Runs one job, in the mode given by the mode key of the job file |
mode: solve_integrals | Family in, $\varepsilon$-series out |
mode: black_box_amflow | Values at the listed eps_samples |
mode: amflow | Solves a user-supplied differential system with boundaries |
mode: diffeq | Returns the differential equation itself |
target_eps_power | The wanted power of $\varepsilon$; sets eps_order |
explicit_boundary | A boundary value supplied from outside, where the built-in large-$\eta$ recursion has no known ending |
ibp_cache_dir, AMFLOW_IBP_CACHE | Caches reductions across jobs |
symbolic_ibp, AMFLOW_SYMBOLIC_IBP | Reduces once with symbolic kinematics, so that new points reuse the reduction |
eps_parallel, AMFLOW_EPS_PARALLEL | Runs the $\varepsilon$ samples in parallel |
node_parallel, AMFLOW_NODE_PARALLEL | Solves the sub-systems at one node of the auxiliary-mass tree in parallel |
AMFLOW_KIRA_FFSAVE=1 | Keeps reduction work directories across a relaunch, so that FireFly resumes |
AMFLOW_KIRA_STALL_SECS | Seconds of zero CPU progress before a reduction is declared stalled and restaged |
Of two names in a row, the first is a job-file key and the second an environment variable. FireFly is the finite-field reconstruction library that Kira uses.
Validation suite (bootloops-wrappers/ in the amflow-cpp repository)
| Command | What it does |
|---|---|
run_tier1.sh [jobs] | Runs all 228 benchmark cases under the fork's tools/bench/ against the committed Mathematica reference values, jobs at a time |
gen_tier23_configs.py, run_tier23.sh | Write and run the closed-form test jobs at 30, 100 and 300 goal digits |
ref_closed_forms.py --out refs.json, ref_sunrise_bessel.py --out FILE | Reference values computed with mpmath, from closed forms (bubble, box) and Bessel moments (sunrise) |
compare_orders.py engine_out.json reference.json [CASE_KEY] | Compares a solver output with a reference file, order by order; CASE_KEY selects the case in a ref_closed_forms.py file |
run_tier5.sh | Records run time and memory against the requested digits and against eps_order, and fits how the run time grows |
The closed-form test jobs are the massless bubble and box, the massive bubble (including above threshold) and the equal-mass sunrise.
Output checks (tools/amflow-kit/)
The three scripts amflow_output_lint.py, compare_amflow_json.py and amflow_smoke.sh are shown under Examples. selftest.py is the package's quick self-test of the three scripts and the two modules.
Reduction-cache key predictor (amflow_kit.keypred, in tools/amflow-kit/)
| Command or option | What it does |
|---|---|
python3 -m amflow_kit.keypred key DIR | Prints the 16-hexadecimal-digit cache key the solver will compute for the Kira input directory DIR |
python3 -m amflow_kit.keypred predict DIR | The same, after repairing Windows line endings and a missing final newline in a hand-built directory |
python3 -m amflow_kit.keypred --selftest | The predictor's tests, on the synthetic directories in tests/fixtures/keypred/ |
--raw (with key) | Prints the uncorrected byte-level key, for diagnosing a cache miss only, never for placing a cache entry |
--numd=P/Q | Adds the extra string the solver hashes at a numeric dimension (AMFLOW_DIFFEQ_NUMD=P/Q); a bare --numd reads that variable |
The predictor runs nothing. With the key in hand, a reduction computed elsewhere can be placed where the run will look for it. Run the commands from tools/amflow-kit/. From Python, keypred.ibp_cache_key(dirpath) returns the key of a directory, and KEYPRED.md in the package names the other options and functions and the files that are hashed. Two points need care:
- A directory whose content differs from what the solver writes, with other sectors, another reduction mode or other targets, gets a different key. In that case read the key the run logs.
- Rerun the self-test whenever the solver's cache code changes, since the predictor must track that code byte for byte.
Memory limit for launch scripts (amflow_kit.memfence, in tools/amflow-kit/)
The memory budget is the variable AMFLOW_KIRA_MEM_CAP_GB, in GiB. How it is enforced depends on the launcher's cgroupa Linux control group: a set of processes on which the kernel enforces resource limits, here a memory ceiling:
| Where the launcher runs | Limit applied |
|---|---|
Inside a cgroup with a finite memory ceiling (mode leaf) | The ceiling alone: no ulimit -v is set and the variable is exported as 0, which the solver reads as no cap |
Without such a ceiling (mode fuse) | An address-space limit of 2.5 times the budget, logged in those words (a 48 GiB budget gives a 120 GiB limit) |
With neither a ceiling nor a budget (mode unfenced) | None |
The policy has these rules:
- Only the launcher's own cgroup counts, never an enclosing one, so a job meant to be held by a cgroup must be launched from inside it.
- The budget is never applied as an address-space limit (
ulimit -v) of the same size. Under the jemalloc allocator a Kira reduction reserves two to five times more address space than the memory it uses, and would die at about a third of its intended memory. - After the launch the module reads back from
/procthe environment of the started process, and of every process it started in turn, and compares it with what the launcher intended. - On a mismatch the launcher kills exactly the process it started, identified by process id and command line and never by a name pattern, and stops with an error. An environment that can no longer be read counts as unverified, not as a mismatch.
| Function or command | What it returns |
|---|---|
memfence.fuse_policy(env_cap_gb, budget_bytes, leaf) | The policy for one launch: the mode, the numbers, the exports and a sentence for the launch log |
memfence.apply_policy_to_env(env, policy), memfence.ulimit_prefix(policy) | The child's environment with the exports written in, and the ulimit -v prefix for the launch line |
memfence.env_readback_tree(pid, intended) | match and verified from reading the environment of the launched process and of every descendant |
memfence.abort_tree_by_pid(pid, argv, reason) | Kills the launched process and its descendants, deepest first, after checking its command line |
python3 -m amflow_kit.memfence | Prints the calling shell's own cgroup record and the policy it would get, as JSON |
The other functions are listed in __all__ at the top of amflow_kit/memfence.py. A launch script of your own in the repository's tools/ tree imports the module as PMflow and Numkin do, with sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "amflow-kit")); from amflow_kit import memfence.
Used on this site
- Crossed light-by-light box: the numerical evaluations of the master integral at the two points of the Checks table, used neither in a fit nor to fix a boundary value.
- Ice-cream cone: the numerical evaluations at the points of the Checks table, used neither in a fit nor to fix a boundary value.
- Kite: high-precision values of the top-sector master for the coefficient fit, and the evaluations in the Checks table. Two of the six points were used in the fit and four were not.
Requirements
The solver
- Runs on: a C++17 compiler, CMake 3.16 or newer, FLINT/Arb, GoogleTest and nlohmann/json. Kira and Fermat must be installed at run time for any job with a reduction;
BUILD.mdin the fork explains why Kira should be built against jemalloc. - Validation suite: also needs
kiraonPATHand GNU parallel;AMFLOW_REPOpoints it at a build. - Install and self-test: build the solver and run its tests from the root of the
amflow-cpprepository with the three commands below.
cmake -S . -B build -DAMFLOW_BUILD_DRIVER=ON cmake --build build -j32 ctest --test-dir build --output-on-failure -j 4
amflow-kit
- Runs on: Python 3, and bash 4 or newer for the smoke script. The comparator needs mpmath. The two modules use only the standard library; the memory-limit module needs Linux with cgroup v2.
- Install: nothing is built. Keep the repository's
tools/tree together, since PMflow, Numkin and Holonomic find the package as a sibling directory. - Key predictor alone:
python3 -m amflow_kit.keypred --selftest. - Smoke test: needs a built
amflow_cli,FERMATPATHpointing at afer64binary, and a reference binary inAMFLOW_SMOKE_VENDOR_BINthe first time the triangle reference is generated. - Optional:
AMFLOW_SMOKE_FIX,AMFLOW_SMOKE_ROOTandAMFLOW_SMOKE_WRAPmove the smoke test's fixtures, scratch directory and launch wrapper. - Self-test: the command below, run from
tools/amflow-kit/, tests the whole package with no built solver. It needs mpmath, and its second part needs pytest.selftest.pyends with a line beginningOVERALL: PASS. Two tests that create a cgroup of their own are skipped, with the reason printed, where the kernel refuses; the exit status stays 0.
python3 selftest.py && python3 -m pytest tests -q -rs -p no:cacheprovider
Source and references
The patched solver and its validation suite (bootloops-wrappers/) are the amflow-cpp repository. PATCHES.md there lists the main changes against commit 006a275 and the papers behind them. amflow-kit is tools/amflow-kit/ in the BootLoops repository, with the smoke fixtures in tools/fixtures/amflow_smoke/.
| Reference | What it supplies |
|---|---|
| X. Liu, Y.-Q. Ma and C.-Y. Wang, arXiv:1711.09572 | The auxiliary-mass-flow method |
| X. Liu and Y.-Q. Ma, AMFlow, arXiv:2201.11669; code: gitlab.com/multiloop-pku/amflow | The original Mathematica package |
| R.-J. Huang, X. Liu and Y.-Q. Ma, AMFlow 2.0, arXiv:2607.08477 | The version whose DESolver.m two patches follow |
| The AMFlow.cpp contributors, AMFlow.cpp, doi:10.5281/zenodo.20087172; code: github.com/chang18/amflow-cpp | The C++ port that the fork starts from |
| T. Peraro, LiteIBP, in the finiteflow-mathtools package | The derivative routines of the reduction interface |
| Z.-F. Liu and Y.-Q. Ma, arXiv:2201.11636 | The treatment of linear propagators |
| Kira, FireFly and Fermat: see the Kira page | The reductions |