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 packageSourceAuthors
Translated routines: the table of five single-mass vacuum integrals and its lookup (vacuum_known, singlemass_vacuum)src/qft/vacuum.cpp in AMFlow.cppThe 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_seedsrc/pipeline/amfsystem.cpp in AMFlow.cppThe same authors
Code that follows theirs: the single-mass product in vacuum_ending_seedsrc/pipeline/amfsystem.cpp in AMFlow.cppThe same authors
Code that follows theirs: the refinement loop inside quad_refineQuadratureRule.summation in mpmathF. Johansson and the mpmath contributors
New code from the paper: tadpole and the auxiliary-mass power of the boundary constantsarXiv:2201.11669Code by Claude
New code: transport, Frobenius matching, the $\varepsilon$-expansion, the loaders, the sampler and every other moduleWritten for BootLoopsCode 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.

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:

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

CommandWhat 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.pyRuns 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.

FunctionWhat it returns
load_monomial_json, load_amatrix_json, load_kira_targetsA 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, landThe 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_sectorThe scalar variant, for an equation given as an exact recurrence, and the two-branch series at apparent higher poles
attach_fast_path, attach_acb_fastThe fast path and the backend="acb" kernel for one scalar equation; fixed at $\varepsilon=0$, and a dps above wp is refused
boundary_branchesWrapper around tools/frobenius-boundary for branch classification at $x=\infty$
cauchy_laurent, vandermonde_laurentLaurent 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_certifiedThe certified variants: the radius comes from the exact $\varepsilon$-singularities; EpsFanCertifyError when the bound cannot be met
anchor_roundtripThe coefficients resummed at a fresh $\varepsilon$ and compared with a direct evaluation, which isolates the extraction error
tadpole, vacuum_known, singlemass_vacuumThe 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_seedThe leading boundary constants for AMFlow's ending schemes
gate_strings, feed_gate_table, write_gate_reportThe 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_manifestChecksum manifests of input files, compared by content
quad_refineAn 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_cutoffA 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.ExtSysThe 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)

FunctionWhat 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_fftThe 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)

FunctionWhat 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

Requirements

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.

ReferenceWhat it supplies
X. Liu and Y.-Q. Ma, AMFlow, arXiv:2201.11669; code: AMFlowThe auxiliary-mass-flow method, the normalization and the boundary-value formulas
The AMFlow.cpp contributors, AMFlow.cpp; BootLoops' fork: amflow-cppsrc/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.13234Transport 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.03345Public programs for the same transport
J. M. Henn, arXiv:1304.1806The canonical ($\varepsilon$-factorized) form of the differential equation, which the sampler fits
L. F. Richardson, Phil. Trans. R. Soc. A 210 (1911) 307Richardson extrapolation, used by epslimit
L. F. Richardson and J. A. Gaunt, Phil. Trans. R. Soc. A 226 (1927) 299The same
F. Johansson and the mpmath contributors, mpmathThe 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-flintThe exact polynomial arithmetic of flintexport and the optional step kernel

← back to the tools index