Longhand

Longhand produces a second numerical value for a Feynman integral, with a measured digit count, by a slow route that shares no machinery with the method behind the first. Route A, written by BootLoops, evaluates the Feynman-parameter formthe representation that trades the product of propagators for one integration variable per propagator, over a simplex, with two polynomials U and F built from the graph and the kinematics of a finite integralthe ε⁰ term of an integral with no poles in ε in arbitrary precision, with lattice rulesquasi-Monte Carlo integration on a deterministic, evenly spread point set; random shifts of the whole set give estimates whose spread is the error bar after Li, Wang, Yan and Zhao and Borowka et al. Route B drives pySecDec, the program of Borowka, Heinrich, Jahn, Jones, Kerner, Schlenk and Zirke, over a compiled library in resumable stages, and reports the digits on which two integration rules agree.

What it does

A value obtained from differential equations, from AMFlow's auxiliary-mass method or from a fitted formula can be built on only after a computation by another method agrees with it. Both routes of Longhand start from the Feynman-parameter form of the integral with $N$ propagators and $L$ loops in $d$ dimensions,

$$ I \;=\; \Gamma\!\left(N - \tfrac{L d}{2}\right) \int d^N x \;\delta\!\Big(1-\sum_i x_i\Big)\, \frac{U^{\,N-(L+1)d/2}}{F^{\,N-L d/2}} , $$

and integrate it numerically, with no reduction to master integralsthe finite basis to which every integral of the family reduces anywhere.

Route A handles finite integrals in the deep-Euclidean regions and t negative and internal masses positive, so F is positive on the whole simplex and the integrand is smooth and real; no contour deformation, no thresholds. Kinematics go in as exact numbers and the working precision dps is set per call. Route A works in these steps.

EngineEffective dimensionWhat it gives
Fixed tensor-product Gauss–Legendre ruleUp to 3Spectral convergence; about 46 digits on the one-loop massive box
Nested tanh-sinh quadratureUp to 2Roughly 17 digits
Randomly shifted rank-1 lattice rule, parallel over the shiftsIrreducible, 4 to 12A value with a statistical error bar, typically a few digits

On the one-loop massive box two reductions that share no algebra beyond $U$ and $F$ agree to about 46 digits, and the package stores 40-digit reference values.

Route B stays in double precision and uses pySecDec's numerics; Longhand adds the staging and the checks. The input is one kinematic point and the disteval directory of a library compiled with pySecDec (loop_package, then make disteval). The compiled library belongs to the machine that built it and is not part of BootLoops. The driver runs pySecDec's disteval evaluator three times, then compares and checks the results.

The check also runs two self-checks. A copy of the stage-B result shifted by one part in a thousand must be caught; if the compare misses it, the check fails. Separate coarse evaluations of the same library ("smokes") must agree with stage A.

Stages B and C run in chunks of sectors (the pieces into which sector decomposition splits the integral). Each chunk is written to disk when it finishes, so an interrupted stage resumes where it stopped, and no stage has a time limit. Every result covers all the $\varepsilon$ orders the library carries.

Longhand has these limits:

AMFlow gives the value Longhand most often checks. Nestor is a singularity-subtracted dispersion quadrature for cases where a lattice rule cannot reach the digits, and SubTropica does exact parametric integration. The engine that route B drives has its own page, pySecDec and FIESTA.

Examples

A 35-digit value for the one-loop massive box (route A). With the package set up (see Requirements) and the repository's tools/ directory on sys.path, run from the package directory tools/longhand/, as the README shows it:

from fractions import Fraction
from longhand import box, integrate_spec
box(-1, Fraction(-1, 3), 1, 2, dps=35)
integrate_spec('toy_qmc_spec.json', N=8009, n_shifts=8, dps=25, nproc=8)

The first call evaluates the finite box with three internal lines of mass $m^2=1$ and a fourth of mass $M_5^2=2$ at $s=-1$, $t=-1/3$, by one closed-form integration followed by a two-dimensional Gauss–Legendre rule. It returns an mpmath number beginning 0.1245570572 that agrees with the stored 40-digit reference to the working precision. The kinematics are exact on purpose: -1/3 as a float would cap the agreement near 16 digits.

The second call sends the six-dimensional UF-spec fixture toy_qmc_spec.json through the lattice engine on 8 worker processes. It returns a dictionary with value, error (the standard error over the random shifts), digits and the per-shift estimates. The value should sit within a few error bars of $13/1080$.

One pySecDec evaluation in checked stages (route B). With a compiled library under PKG/disteval and a scratch directory WORK, as DISTEVAL.md shows it:

cd tools/longhand/disteval
python3 pysecdec_point.py --disteval-dir PKG/disteval --stage A --workers 8 --work WORK
python3 pysecdec_point.py --disteval-dir PKG/disteval --stage B --workers 8 --work WORK
python3 pysecdec_point.py --disteval-dir PKG/disteval --stage C --workers 8 --work WORK
python3 pysecdec_point.py --stage compare \
    --results A=WORK/stage_A/RESULT_A.json \
    B=WORK/stage_B/RESULT_B.json \
    C=WORK/stage_C/RESULT_C.json \
    --out WORK/COMPARE.json
python3 pysecdec_point.py --stage check --work WORK --compare WORK/COMPARE.json \
    --leaf-stamp LEAF.stamp --out WORK/GATE.json
python3 pysecdec_point.py --stage check --example

Each stage leaves WORK/stage_<S>/RESULT_<S>.json. For B and C every chunk directory under WORK/stage_<S>/chunks/ holds its own result.json, log and DONE marker, and one line per finished chunk goes to WORK/progress.jsonl. The check writes the per-order digit table, the two self-checks and a PASS or FAIL verdict to the --out file and exits 0 or 1.

These options change how a stage or the check runs:

The last line runs the check over the records of the package's worked example and must reproduce them. That example is the eight-propagator double pentagon of a five-point family with generic masses (332 sectors) at a Euclidean point. Stage B gives $\varepsilon^0 = 0.8246341249 \pm 7.3\times10^{-8}$, and the check reports 9 digits at the leading pole $\varepsilon^{-4}$ and 7 at each order from $\varepsilon^{-3}$ to $\varepsilon^0$.

By default --disteval-dir must match the checksums of that example's library in PACKAGE_PINS.json. For your own library, write its checksums once with --emit-pins PINS.json --disteval-dir PKG/disteval --family NAME. Then pass --family NAME --pins PINS.json on every line, and give the check line --smoke NAME=smoke.json files from coarse runs of your library. The alternative is --unpinned-package, which runs anyway and labels every result unverified.

Routines

The self-tests and benchmarks run inside tools/longhand/, and pysecdec_point.py and its helper scripts are in tools/longhand/disteval/.

CommandWhat it does
selftest.py [--full] [--route ROUTE]The self-tests of both routes; ROUTE is parametric, disteval or all
selftest_parametric.pyThe UF-spec check on 8 processes: the box written as a spec, against the reference
bench_box.py [dps]The one-loop massive box at three values of M5 beside the stored references, with the digits of agreement
bench_se3l.py --N --shifts --p --dps --nproc --out FILEThe finite three-loop, eight-propagator self-energy on the lattice engine, six-dimensional after one elimination; --out writes a JSON record
pysecdec_point.py --stage A --disteval-dir D --work DIROne evaluation stage; B and C likewise
pysecdec_point.py --stage compare --results NAME=RESULT.json ... --out FILEThe pairwise per-order comparison
pysecdec_point.py --stage checkThe acceptance check over --work DIR, or over the worked example's records with --example
pysecdec_point.py --check-packageVerifies a library against its checksums
pysecdec_point.py --emit-pins OUTWrites the checksums of another family's library
pysecdec_point.py --planted-fail-controlPrints the shifted-result self-check
pysecdec_point.py --basis WPrints the memory limit to give a run with W workers, from the measured memory of the example run
stage_chunks.py, assemble_compare.py, gate.py, memory_basis.pyThe chunk splitter, the per-order assembly and comparison, the acceptance check and the memory formula as standalone scripts (--help on each)

A stage line also takes --workers W, --chunk-sectors N and --point 'name=value ...', which must name every parameter of the library exactly once. The options --points, --shifts, --epsrel, --epsabs, --epsabs-from and --lattice-candidates override a stage's defaults.

Exit codes: 0 pass; 1 a failed check, an incomplete stage or the example not reproduced; 2 a usage error or a refused input; 3 a checksum mismatch; 4 a required file missing.

bench_se3l.py needs pySecDec and sympy once for the symbolic reduction, which it caches in se3l_reduced.json beside the script.

Route A is imported with the repository's tools/ directory on sys.path. build_UF, reduce_linear_full, reduce_one_quadratic, build_integrand_expr and make_factory come from longhand.feynman, which needs sympy. Everything else comes from longhand. The tables omit default values and some optional arguments, so pass every optional argument by keyword.

FunctionWhat it returns
box(s, t, m2, M5, dps)The finite one-loop massive box at a deep-Euclidean point, from exact kinematics (int, Fraction, decimal string); ValueError outside the supported region
box_crosschart(s, t, m2, M5, dps)The same box by a different reduction; agreement with box checks reduction and quadrature together
integrate_gauss_product(f, dim, dps, nodes, limits)The Gauss–Legendre product rule over $[0,\infty)^{dim}$; the per-axis limits may depend on the outer variables
integrate_tanhsinh(f, dim, dps, intervals)Nested mpmath.quad, for low dimension
integrate_qmc(integrand_factory, fac_arg, dim, N, n_shifts, korobov_p, dps, nproc, seed)The lattice rule with N prime: a dictionary with value, error, digits, shifts, N, n_shifts, gvec
build_UF(propagators, loop_momenta, external_momenta, replacement_rules)$U$, $F$, the Feynman parameters, the loop count and the propagator count, through pySecDec's LoopIntegralFromPropagators
reduce_linear_full(F, xs)The integrand with the parameters linear in $F$ integrated out by both closed-form steps, and the surviving variables
reduce_one_quadratic(F, xs, var)The integrand with one parameter quadratic in $F$ integrated out in closed form, and the remaining variables
build_integrand_expr(propagators, loop_momenta, external_momenta, replacement_rules, param_values)The numeric integrand from a propagator list in one call
make_factory(expr, remaining_vars)(factory, dim): a sympy expression wrapped as an integrand factory for integrate_qmc
check_spec(spec)Passes if every polynomial is homogeneous and every numerator term has the right projective degree; otherwise AssertionError naming the offender
integrate_spec(json_path, family, chart, N, n_shifts, korobov_p, dps, nproc, seed)A lattice-rule result straight from a spec file
box_spec(s, t, m2, M5)The one-loop box as a spec: a test case with a known answer and, with toy_qmc_spec.json, a worked example of the schema

The lattice generating vectors that the benchmarks and tests need are included in cbc_cache.json. Newly built ones go to a user cache ($LONGHAND_CBC_CACHE, default ~/.cache/longhand/cbc_cache.json).

Route B from Python is from longhand.disteval import check, stage_chunks, assemble_compare, memory_basis. The lower-level functions (reduce_linear, assemble_integrand_expr, make_eval, load_spec) are listed in GUIDE.md in the package, and the remaining options of route B in DISTEVAL.md.

Requirements

python3 selftest.py
python3 selftest.py --full
python3 selftest.py --route parametric

The default run takes about a minute with pySecDec installed and well under that without it, when the checks that need pySecDec are skipped by name. Route A's checks compare every code path with known answers, and route B's checks (pytest, under tests/) replay the worked example's records and need no compiled library. --full swaps in route A's heavier multi-process checks, and --route runs one route alone.

Source and references

The code is tools/longhand/ in the BootLoops repository, released under the MIT license. The methods are others'; the code of route A and of route B's staging and checks is BootLoops'.

ReferenceWhat it supplies
T. Binoth and G. Heinrich, hep-ph/0004013Sector decomposition
S. Borowka, G. Heinrich, S. Jahn, S. P. Jones, M. Kerner, J. Schlenk and T. Zirke, pySecDec, arXiv:1703.09692; code: secdecThe program route B drives; $U$ and $F$ from a propagator list in route A
S. Borowka, G. Heinrich, S. Jahn, S. P. Jones, M. Kerner and J. Schlenk, arXiv:1811.11720pySecDec's lattice rules; the Korobov periodization of route A's lattice engine
G. Heinrich, S. P. Jones, M. Kerner, V. Magerya, A. Olsson and J. Schlenk, arXiv:2305.19768The disteval evaluator
Z. Li, J. Wang, Q.-S. Yan and X. Zhao, arXiv:1508.02512Rank-1 lattice rules for Feynman integrals, the method of route A's lattice engine
D. Nuyens and R. Cools, Math. Comp. 75 (2006) 903The fast component-by-component construction of generating vectors; Longhand runs the plain component-by-component search
T. Goda and P. L'Ecuyer, arXiv:2201.09413The median-lattice rule of stage C

← back to the tools index