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.

PartSourceAuthors
The solver as forkedAMFlow.cpp, a C++ port of AMFlowThe AMFlow.cpp contributors; AMFlow by X. Liu and Y.-Q. Ma
Derivative routines of the reduction interface, part of the solver as forkedLiteIBP, as carried in AMFlow's Kira interfaceT. Peraro
Patches that follow the authors' code: the count of boundary-matching conditions and the rationalization precisionDESolver.m of AMFlow 2.0R.-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 outLIBPDerivivative of LiteIBPT. Peraro; code by Claude
New code: the other patches and the validation suitePATCHES.md credits the papers behind the patches it listsCode by Claude
amflow-kit: new code; its key predictor is a Python port of the cache-key routine that BootLoops added to the forksrc/ibp/ibp_cache.cpp in the forkCode 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:

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:

The solver has these limits:

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:

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:

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 keyWhat 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_integralsFamily in, $\varepsilon$-series out
mode: black_box_amflowValues at the listed eps_samples
mode: amflowSolves a user-supplied differential system with boundaries
mode: diffeqReturns the differential equation itself
target_eps_powerThe wanted power of $\varepsilon$; sets eps_order
explicit_boundaryA boundary value supplied from outside, where the built-in large-$\eta$ recursion has no known ending
ibp_cache_dir, AMFLOW_IBP_CACHECaches reductions across jobs
symbolic_ibp, AMFLOW_SYMBOLIC_IBPReduces once with symbolic kinematics, so that new points reuse the reduction
eps_parallel, AMFLOW_EPS_PARALLELRuns the $\varepsilon$ samples in parallel
node_parallel, AMFLOW_NODE_PARALLELSolves the sub-systems at one node of the auxiliary-mass tree in parallel
AMFLOW_KIRA_FFSAVE=1Keeps reduction work directories across a relaunch, so that FireFly resumes
AMFLOW_KIRA_STALL_SECSSeconds 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)

CommandWhat 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.shWrite 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 FILEReference 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.shRecords 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 optionWhat it does
python3 -m amflow_kit.keypred key DIRPrints the 16-hexadecimal-digit cache key the solver will compute for the Kira input directory DIR
python3 -m amflow_kit.keypred predict DIRThe same, after repairing Windows line endings and a missing final newline in a hand-built directory
python3 -m amflow_kit.keypred --selftestThe 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/QAdds 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:

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 runsLimit 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:

Function or commandWhat 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.memfencePrints 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

Requirements

The solver

cmake -S . -B build -DAMFLOW_BUILD_DRIVER=ON
cmake --build build -j32
ctest --test-dir build --output-on-failure -j 4

amflow-kit

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/.

ReferenceWhat it supplies
X. Liu, Y.-Q. Ma and C.-Y. Wang, arXiv:1711.09572The auxiliary-mass-flow method
X. Liu and Y.-Q. Ma, AMFlow, arXiv:2201.11669; code: gitlab.com/multiloop-pku/amflowThe original Mathematica package
R.-J. Huang, X. Liu and Y.-Q. Ma, AMFlow 2.0, arXiv:2607.08477The version whose DESolver.m two patches follow
The AMFlow.cpp contributors, AMFlow.cpp, doi:10.5281/zenodo.20087172; code: github.com/chang18/amflow-cppThe C++ port that the fork starts from
T. Peraro, LiteIBP, in the finiteflow-mathtools packageThe derivative routines of the reduction interface
Z.-F. Liu and Y.-Q. Ma, arXiv:2201.11636The treatment of linear propagators
Kira, FireFly and Fermat: see the Kira pageThe reductions

← back to the tools index