Wayfinder
Wayfinder integrates the differential equations of a family of Feynman integrals, carrying high-precision values from a point where they are known to the point where they are wanted. It then extracts the expansion in the regulator $\varepsilon$, and a second part, the connection sampler, reconstructs the constant matrices of the equation from numerical values of the integrals. The method is that of the series-expansion solvers of Hidding (DiffExp), Armadillo and co-authors (SeaSyde) and Liu and Ma (AMFlow); the table of boundary values is a Python port of AMFlow.cpp routines.
Where it comes from
Xiao Liu and Yan-Qing Ma wrote AMFlow (arXiv:2201.11669), the program of the auxiliary-mass-flow method, which adds a fictitious mass $\eta$ to chosen propagators. The AMFlow.cpp contributors wrote AMFlow.cpp, a reimplementation of AMFlow in C++. Wayfinder's five closed forms for single-mass vacuum integrals (integrals with no external momenta) and its prefactor are the AMFlow formulas of Liu and Ma, ported from AMFlow.cpp's source into Python. The paper states one of the five, the one-loop tadpole; the other four were taken from the C++ code.
The transport code is new code in an established class of method, transport by series expansion. It stands in the line of the solvers listed under Source and references. Computing at fixed numerical $\varepsilon$ and fitting the expansion afterwards is the design of AMFlow. The sampler runs amflow_cli, the command-line program of BootLoops' fork of AMFlow.cpp, as a separate process.
| Part of the package | Source | Authors |
|---|---|---|
Translated routines: the table of five single-mass vacuum integrals and its lookup (vacuum_known, singlemass_vacuum) | src/qft/vacuum.cpp in AMFlow.cpp | The AMFlow.cpp contributors; formulas of X. Liu and Y.-Q. Ma |
Translated routines: the Gamma-function prefactor (single_mass_prefactor) and the rule for the ending values in vacuum_ending_seed | src/pipeline/amfsystem.cpp in AMFlow.cpp | The same authors |
Code that follows theirs: the single-mass product in vacuum_ending_seed | src/pipeline/amfsystem.cpp in AMFlow.cpp | The same authors |
Code that follows theirs: the refinement loop inside quad_refine | QuadratureRule.summation in mpmath | F. Johansson and the mpmath contributors |
New code from the paper: tadpole and the auxiliary-mass power of the boundary constants | arXiv:2201.11669 | Code by Claude |
| New code: transport, Frobenius matching, the $\varepsilon$-expansion, the loaders, the sampler and every other module | Written for BootLoops | Code by Claude |
Please cite the authors' papers when you use it. Wayfinder is not affiliated with or endorsed by the authors of AMFlow, AMFlow.cpp or mpmath.
What it does
The master integralsthe finite basis to which every integral of the family reduces of a family obey a linear system $y'(x)=A(x,\varepsilon)\,y(x)$ in a kinematic variable $x$. Here $\varepsilon$ is the parameter of dimensional regularizationspace-time is continued to d = 4 − 2ε dimensions; results are Laurent series in ε and $A$ is a matrix of rational functions. If the integrals are known at one $x$, for instance in a limit where they reduce to vacuum integrals, integrating the system gives them at any other.
Wayfinder has four steps, used together or alone.
- Transport. At a fixed numerical $\varepsilon$ it advances by high-order Taylor steps, each sized by the distance to the nearest singular point of $A$. A step is accepted only when a bound on the neglected Taylor tail is below the requested precision. The worst bound over the path is returned as
trunc_worst. With complex waypoints the path goes around singular points on the real axis. - Landing. A Taylor march cannot end on a regular-singular pointa point where A has a simple pole; solutions there behave like powers (x−x₀)^λ times polynomials in log(x−x₀). There Wayfinder builds the local Frobenius basis (power-and-logarithm series, including exponents that differ by integers) and matches the transported vector onto it by least squares. It returns the residual and a condition-number estimate. Variants handle a scalar higher-order equation given as an exact recurrence, and apparent higher poles.
- Expansion in ε. The fixed-$\varepsilon$ computation is repeated at several $\varepsilon$, on a small circle around $\varepsilon=0$ or on a geometric grid of small real values with extra nodes kept back for checking. The Laurent coefficients (those of the powers of $\varepsilon$, negative powers included) are extracted twice, and the number of digits on which the two extractions agree is returned (
min_agree_digits,self_digits). Quote that number, not the working precision. - Comparison. The result is compared at two precisions with stored reference digits. A value passes only if it matches and does not move when the precision is raised.
The connection sampler (sampler.py) is for the case where the equation itself is missing. In a canonical basisa choice of master integrals in which ε factors out of the differential equation and only logarithmic one-forms appear the system reads
$$ dJ \;=\; \varepsilon \Big(\sum_a A_a\, d\log a\Big)\, J, $$
with constant rational matrices $A_a$, one per letter $a$ (the letters are the arguments of the logarithms). The sampler evaluates the integrals and their derivatives with AMFlow at a few exact rational kinematic points, by central finite differences or with AMFlow's exact derivative mode. It solves the linear equations these samples impose on the entries of the $A_a$ and rounds each entry to a fraction with PSLQ, an integer-relation algorithm. The result is checked at points not used in the fit.
The output connection.json holds the matrices in sparse form and the diagnostics of the fit: points used, condition number, residual digits, digits at the check points, and entries that failed to rationalize. Ansatzer reads it through --connection.
The epslimit module is for the case where the values already exist: another program, AMFlow, pySecDec or anything else, has evaluated an integral at a grid of $\varepsilon_i$ of its own choosing. It returns the coefficients $c_{k,j}$ of $f(\varepsilon)=\sum_{k\ge k_{\min}}\sum_{j\ge0}c_{k,j}\,\varepsilon^k\log^j\varepsilon$, usually the finite part $c_{0,0}$.
The pole order $k_{\min}$ is read from the slope of $\log|f|$ against $\log|\varepsilon|$. A power of $\log\varepsilon$ is accepted only when refitting with each sample left out in turn improves the fit decisively, which separates a genuine logarithm from round-off in the input. Up to four methods run, as the layout of the grid allows, and achieved_digits is the number of digits on which they agree.
The flintexport module belongs to the step before transport, when a differential equation or a large set of reduction rules is assembled symbolically and SymPy's cancel and together become the bottleneck. It walks each SymPy expression once and holds every intermediate value as a pair of exact multivariate polynomials over the rationals in FLINT (through python-flint). canonical_terms returns the result in a sorted form that can be compared byte for byte, the format load_monomial_json reads. Counterweight has the Julia counterpart, MpolyFeed.jl.
Wayfinder has these limits:
- It does not do integration-by-parts reduction or find a canonical basis; see Kira and Counterweight.
- Transport works at one $\varepsilon$ at a time by design. Plain transport accepts complex $\varepsilon$; Frobenius matching requires real $\varepsilon$.
- Transport along a straight path that runs into a singular point stops with an error asking for a detour.
- Both step kernels, the default and the optional python-flint one for systems with hundreds of masters (
backend="acb"), report a truncation bound, not interval enclosures. - The
kira_target.mloader covers a subset of Kira's grammar. An unsupported construct there, and an unsupported case anywhere in the package, raisesNotImplementedErrornaming what is missing. - In
epslimitthe grid, not the algorithm, limits what can be recovered. Three samples give six to eight digits of the finite part however they are processed. Thirty digits or more call for six to eight samples on a geometric ladder of ratio 2 to 4, computed at two to three times the target precision. epslimittakes its grid as given, while the expansion step chooses its own nodes. The two are separate code.flintexportallows any number of variables but only integer exponents. Mixing SymPy arithmetic into the middle of a walk loses the gain, which comes from staying in FLINT from the leaves to the export.- The number of digits is an explicit argument everywhere. The transport, Frobenius, boundary and $\varepsilon$-expansion routines never change the global
mpmathprecision.extrapolatesets it for the duration of the call and restores it. The sampler's routines set it to thedpsthey are given and leave it there.
Examples
Run the end-to-end control. With the package set up (see Requirements), run the two control scripts from the package directory tools/wayfinder/:
python3 tests/control_hypergeom.py # end-to-end positive control, ~6 min python3 tests/control_tadpole.py # boundary vs direct Gamma, seconds
The first script builds the $2\times2$ system of ${}_2F_1(\varepsilon,-2\varepsilon;1-3\varepsilon;x)$ inline and transports it at $\varepsilon=1/10$ from $x=1/2$ to $x=-1$, at 100 and at 140 digits. The path goes around the singular point at $0$ through the waypoint $-0.6i$. The result is compared with 90 stored digits of mpmath.hyp2f1 at $x=-1$, a value the transport never used. The script then extracts the $\varepsilon$-coefficients $k=-2\ldots6$ and compares them with a Taylor expansion computed by mpmath.taylor (the second-order one is exactly $\pi^2/6$).
Each stage prints its measured digits, and exit code 0 means every bar was met. The second script checks tadpole against the Gamma-function closed form at 150 digits.
Transport your own system from Python. Any object with .n, .var, .A(x, eps, dps) and .meta is accepted; this is the control's hypergeometric system with its singular points declared.
from mpmath import mp, mpc
from wayfinder import transport_fixed_eps
class Hyp2F1System:
n = 2
var = "x"
meta = {"source": "inline", "singular_points": [0, 1]}
def A(self, x, eps, dps):
with mp.workdps(dps):
xv, e = mpc(x), mpc(eps)
den = xv * (1 - xv)
return [[mpc(0), mpc(1)],
[-2 * e * e / den, ((1 - e) * xv - (1 - 3 * e)) / den]]
with mp.workdps(130): # boundary vector (w, w') at x = 1/2
a, b, c = mpc("0.1"), mpc("-0.2"), mpc("0.7")
y0 = [mp.hyp2f1(a, b, c, 0.5), a * b / c * mp.hyp2f1(a + 1, b + 1, c + 1, 0.5)]
y, diag = transport_fixed_eps(Hyp2F1System(), "0.1", "0.5", "-1", y0, 100,
path=[mpc(0, "-0.6")], return_diag=True)
y is $(w,w')$ at $x=-1$ as mpc numbers to the requested 100 digits. diag holds steps, trunc_worst, trunc_worst_log10 and min_hfrac, to be stored with the result. For a system loaded from disk, call desys.enable_fast_path(eps, wp=250) first: it attaches exact Taylor coefficients of $A$ and the singular points, and is recommended for large matrices.
Fit a canonical connection from samples. The one-loop massless box target comes with the package in targets/. The run needs an amflow-cpp build (AMFLOW_CLI) and the Gatekeeper and Counterweight packages as siblings under tools/.
python sampler.py targets/box1l_conn.json \
--n-fit 3 --n-heldout 2 --goal-digits 40 --eps-power 3 \
--parallel 6 --out out/box1l/connection.json
Three fit points and two verification points take 25 AMFlow calls, about two minutes at --parallel 6; a cached rerun takes a fraction of a second. In the basis $(\varepsilon(1-2\varepsilon)\,\mathrm{bub}_s,\ \varepsilon(1-2\varepsilon)\,\mathrm{bub}_t,\ \varepsilon^2 st\,\mathrm{box})$ the recovered matrices are
A[s] = [[-1,0,0],[0,0,0],[2,0,-1]] A[t] = [[0,0,0],[0,-1,0],[0,2,-1]] A[s+t] = [[0,0,0],[0,0,0],[-2,-2,1]]
with a 31-digit fit residual, 32 digits at the verification points, nothing that failed to rationalize, and $\sum_a A_a=-1$ as the scaling check.
Take the ε → 0 limit of values computed elsewhere. Three small files distributed with the tests each hold one sample of $f(\varepsilon)=7/2-3\varepsilon+11\varepsilon^2$, in the layout of an AMFlow result file. The samples are at $\varepsilon=1/1000$, $1/4000$ and $1/8000$.
from wayfinder.epslimit import extrapolate, load_amflow_grid
paths = [f"tests/fixtures_epslimit/series_quad_eps_1_{n}.json" for n in (1000, 4000, 8000)]
samples = load_amflow_grid(paths, part="re") # [(eps, value), ...], one integral
r = extrapolate(samples, max_log=0)
print(r.finite_part, r.c(1), r.c(2)) # 7/2, -3, 11
print(r.k_min, r.log_order, r.achieved_digits)
Because this $f$ is exactly quadratic, three samples are enough and the test requires $c_0$, $c_1$ and $c_2$ to 40, 35 and 30 digits; for a general function three samples would give six to eight. With max_log=0 no logarithms are tested for; the default of 3 lets the routine test for them.
Exact rational-function algebra with flintexport. This is the pattern from the module's self-test: SymPy symbols are mapped into the polynomial ring $\mathbb{Q}[\varepsilon,s_2,s_{12}]$, with $d$ sent to $4-2\varepsilon$, and an expression is evaluated there exactly (python-flint required).
import sympy as sp
from wayfinder.flintexport import mk_ctx, gen, poly, make_env, walk, canonical_terms
d, s2, s12 = sp.symbols("d s2 s12")
ctx = mk_ctx(("eps", "s2", "s12")) # variables of the ring, in order
env = make_env(ctx, {s2: gen(ctx, 1), s12: gen(ctx, 2),
d: poly(ctx, {(0, 0, 0): 4, (1, 0, 0): -2})}) # d -> 4 - 2*eps
fr = walk((d - 2) / (s2 * s12), env, {}, ctx) # exact numerator/denominator pair
num_terms, den_terms = canonical_terms(fr)
fr is a Frac holding the reduced numerator $2-2\varepsilon$ and denominator $s_2 s_{12}$, the identity the self-test checks. canonical_terms returns each as a list of [exponents, "coefficient"] entries with exponents in the order given to mk_ctx. The third argument of walk is a cache dictionary, one per expression tree, so shared subexpressions are evaluated once.
Routines
| Command | What it does |
|---|---|
python sampler.py TARGET.json [options] | Fits the connection of the target and writes connection.json |
python3 tools/wayfinder/epslimit.py FILE [FILE ...] | Prints the $\varepsilon\to0$ coefficients from AMFlow result files; the last line begins FINITE PART c_0 = |
python3 tools/wayfinder/flintexport.py | Runs the flintexport self-test (five exact identities); prints wayfinder.flintexport selftest: PASS and exits 0 |
sampler.py and epslimit.py print their options with --help. python3 -m wayfinder.epslimit from tools/ runs the same program as epslimit.py.
| Function | What it returns |
|---|---|
load_monomial_json, load_amatrix_json, load_kira_targets | A DESystem from exact rational monomials, from rational-function fits in $d$, or from AMFlow kira_target.m rules |
DESystem.enable_fast_path(eps, wp, backend) | Attaches exact Taylor coefficients of $A$ and the singular points; backend is "mpmath" or "acb" |
transport_fixed_eps(desys, eps0, x0, x1, y0, dps) | The vector at x1 by Taylor steps at fixed $\varepsilon$; path lists complex waypoints, return_diag=True adds the diagnostics |
frobenius_basis, land | The matrix Frobenius basis at a regular-singular point, and the transported vector matched onto it with residual and condition estimate |
frob_scalar.transport_value, two_sector_series, eval_two_sector | The scalar variant, for an equation given as an exact recurrence, and the two-branch series at apparent higher poles |
attach_fast_path, attach_acb_fast | The fast path and the backend="acb" kernel for one scalar equation; fixed at $\varepsilon=0$, and a dps above wp is refused |
boundary_branches | Wrapper around tools/frobenius-boundary for branch classification at $x=\infty$ |
cauchy_laurent, vandermonde_laurent | Laurent coefficients from a circle in $\varepsilon$, or from real nodes on a geometric grid, with the agreement digits of each order |
cauchy_laurent_certified, vandermonde_laurent_certified | The certified variants: the radius comes from the exact $\varepsilon$-singularities; EpsFanCertifyError when the bound cannot be met |
anchor_roundtrip | The coefficients resummed at a fresh $\varepsilon$ and compared with a direct evaluation, which isolates the extraction error |
tadpole, vacuum_known, singlemass_vacuum | The one-loop massive tadpole; the built-in single-mass vacuum integrals (1,1), (2,3), (3,4), (3,5), (4,5) and the test for them |
single_mass_prefactor, vacuum_ending_seed | The leading boundary constants for AMFlow's ending schemes |
gate_strings, feed_gate_table, write_gate_report | The two-precision comparison against stored strings, its table of verdicts and JSON writer; zero references are tested absolutely, one-digit ones refused |
sha256_file, write_manifest, check_manifest | Checksum manifests of input files, compared by content |
quad_refine | An integral accepted only when successive refinements agree to $10^{-(\mathrm{dps}+\mathrm{guard})}$; QuadNonConvergence at the depth cap |
tailcut.besselk_tail_bound, tailcut.choose_bessel_cutoff | A certified bound on $\int_X^\infty x^\sigma K_\nu(x)^m\,dx$, and a cutoff that puts it below tolerance |
conic_thirdkind.rows_from_connection, conic_thirdkind.build_row_system, conic_thirdkind.ExtSys | The exact rational $t$-system for one row of a connection over a conic $Y^2=q(x,t)$, as a DESystem; ConicScopeError unless $q$ is quadratic |
sampler.connection_once(target_json) | The sampler's fit as one call; writes connection.json |
The vacuum integrals, the prefactor and the ending rule are the port described under Where it comes from.
load_amatrix_json refuses an incomplete file. load_kira_targets keeps the order of the masters file, which is the order of AMFlow's boundary vectors. vandermonde_laurent refuses n_verify=0. frob_scalar.transport_value needs sympy and Annihilator.
ε → 0 limits from an existing grid (from wayfinder.epslimit import ..., or from wayfinder import epslimit)
| Function | What it returns |
|---|---|
extrapolate(samples) | An ExtrapResult from a sequence of (eps, value) pairs; max_log caps the power of $\log\varepsilon$ that is tested |
load_amflow_grid(json_paths, integral_index) | The samples of integral number integral_index from AMFlow result files, failed ones skipped; part is 're', 'im' or 'complex' |
richardson_boundary(partial_sums, Ms) | The sum of a series at its radius of convergence, from partial sums at truncation orders Ms |
vandermonde_fit, neville_zero, romberg_ladder, bulirsch_stoer_zero, eps_fft | The individual methods, for use on their own |
An ExtrapResult holds coeffs (a dictionary keyed by (k, j)), finite_part, c(k, j=0), k_min, log_order, achieved_digits, method, per_method and diagnostics. Samples may be numbers, decimal strings or Arb-style [mid +/- rad] strings. richardson_boundary needs the powers in the tail to be known; pass them as tail_exponents, half-integers by default (the square-root case). It returns a list of the values left after the eliminations, a single one with the default powers.
Exact rational-function algebra and export (from wayfinder.flintexport import ..., or from wayfinder import flintexport; needs python-flint and SymPy)
| Function | What it returns |
|---|---|
mk_ctx(names), gen(ctx, i), const(ctx, q), poly(ctx, monom_dict) | The polynomial ring in the named variables, its i-th variable, a rational constant, and a polynomial from {exponent_tuple: coefficient} |
make_env(ctx, subs_syms) | The map from each SymPy symbol to its value in the ring, such as $4-2\varepsilon$ for $d$ |
walk(e, env, cache, ctx) | The SymPy expression e evaluated once in exact FLINT arithmetic, as a Frac; ValueError on a non-integer exponent or an unsupported node |
canonical_terms(fr) | Numerator and denominator as sorted lists of [exponents, "coefficient"] with coprime integer coefficients; None for an exact zero |
Signatures and default values are in README.md in the package directory and in the docstrings. The lower-level names are in the module files (sampler.py, epslimit.py, epsfan.py, conic_thirdkind.py, tailcut.py).
Used on this site
- Kite: high-order Taylor transport of the differential equation along the negative real axis.
- gg → Zγ: transport of the 22-equation system in $s$ from the cusp $s=0$ to $s=-1/4$.
- Non-planar $q\bar q\to W^+W^-$: high-order Taylor transport of the differential equation along the line.
- Crossed light-by-light box: series transport of the differential equation along the curve from the exact boundary data.
- Light-by-light box with a kite insertion: series solution of the kite differential equation along the cut, giving the density used inside the dispersion integral.
- QED light-by-light graphs with a kite self-energy: power-series solution of the system along $w\gt m^2$, which gives the spectral density.
- Light-by-light box with a vacuum-polarization insertion: Taylor-series transport of the box kernel and of the density along $w'$ at fixed $\varepsilon$.
Requirements
- Runs on: Python 3 with
mpmath.epslimitneeds nothing more; mpmath's gmpy2 backend helps but is optional. - Install:
pip install mpmath. A clone of the repository is the installation; put itstools/directory onPYTHONPATHso thatfrom wayfinder import ...resolves. - Optional:
python-flintfor faster exact arithmetic,backend="acb"andattach_acb_fast;flintexportrequires it.numpyis only a fallback root finder.sympyis needed byfrob_scalar,boundary_branches,conic_thirdkind,flintexportand the sampler, and is imported only when those are used.frob_scalaralso needs Annihilator as a sibling undertools/. - Lazy modules: importing
wayfinderloads neitherepslimitnorflintexport;from wayfinder import epslimit, flintexportbrings them in. - Sampler: needs Gatekeeper, the
canonical_formmodule of Counterweight and, for targets defined by a graph, the Landau Alphabet package importable undertools/. It also needs anamflow_clibinary built from BootLoops'amflow-cppfork (see AMFlow);AMFLOW_CLInames it andAMFLOW_IBP_CACHEsets the reduction cache. - Threads: set
OPENBLAS_NUM_THREADSto 2 or less for large transports. - Self-test:
python3 -m pytest tests/ -qfrom the package directory runs the unit suite (ten to fifteen minutes); from the repository root usepython3 -m pytest tools/wayfinder -x -q. The first control script under Examples ends with a line beginningCONTROL VERDICT: PASS, the second withTADPOLE CONTROL VERDICT: PASS. - Module tests:
python3 tests/test_epslimit_synthetic.py,python3 tests/test_epslimit_fixtures.pyandpython tests/test_sampler.pyeach take a few seconds.python3 tests/test_flintexport.pytakes under a second and is skipped without python-flint. Pytest collects them all. - Longer tests:
WAYFINDER_RUN_AMFLOW=1adds the sampler's box tests that call AMFlow (ten to twenty minutes). Tests against large reference systems not distributed with the package are skipped unlessWAYFINDER_REFERENCE_FIXTURESpoints at a local copy.
Source and references
The code is tools/wayfinder/ in the BootLoops repository. GUIDE.md there has a CREDIT paragraph, and its bracketed keys resolve in REFERENCES.md at the repository root.
| Reference | What it supplies |
|---|---|
| X. Liu and Y.-Q. Ma, AMFlow, arXiv:2201.11669; code: AMFlow | The auxiliary-mass-flow method, the normalization and the boundary-value formulas |
| The AMFlow.cpp contributors, AMFlow.cpp; BootLoops' fork: amflow-cpp | src/qft/vacuum.cpp and src/pipeline/amfsystem.cpp, the source of the ported boundary routines; amflow_cli for the sampler |
| R. N. Lee, A. V. Smirnov and V. A. Smirnov, arXiv:1709.07525; F. Moriello, arXiv:1907.13234 | Transport by series expansion around singular points |
| M. Hidding, DiffExp, arXiv:2006.05510; T. Armadillo, R. Bonciani, S. Devoto, N. Rana and A. Vicini, SeaSyde, arXiv:2205.03345 | Public programs for the same transport |
| J. M. Henn, arXiv:1304.1806 | The canonical ($\varepsilon$-factorized) form of the differential equation, which the sampler fits |
| L. F. Richardson, Phil. Trans. R. Soc. A 210 (1911) 307 | Richardson extrapolation, used by epslimit |
| L. F. Richardson and J. A. Gaunt, Phil. Trans. R. Soc. A 226 (1927) 299 | The same |
| F. Johansson and the mpmath contributors, mpmath | The arithmetic; the quadrature nodes and the loop that quad_refine follows |
| W. Hart, F. Johansson, A. Ahlbäck and the FLINT team, FLINT; F. Johansson, O. Benjamin and contributors, python-flint | The exact polynomial arithmetic of flintexport and the optional step kernel |