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.
- Input. The input is a propagator list or a "UF-spec" JSON file. The front end of pySecDec turns a propagator list into $U$ and $F$ in pySecDec's normalization, so that values compare digit for digit with pySecDec's. A UF-spec writes any finite projective integrand as polynomials with exact rational coefficients plus numerator terms, and needs no pySecDec.
- Reduce. Before any numerics, every Feynman parameter that enters $F$ linearly is integrated out in closed form. The first step is $\int_0^\infty dx/(Ax+B)^2 = 1/(AB)$ and the second is partial fractions on the two surviving factors, which leaves a logarithm. Both are valid because the coefficient polynomials are positive in this region. Each removes one dimension exactly: the three-loop self-energy benchmark goes from seven dimensions to six this way.
- Quadratic parameters. A parameter in which $F$ is a positive quadratic is integrated out by a second closed form, $\int_0^\infty dx/(Px^2+Qx+R)^2$ (
reduce_one_quadratic). In the one-loop massive box $F$ is such a quadratic in every parameter, and the box drops to two dimensions. - Integrate. The remainder goes to one of the three arbitrary-precision engines in the table. The third is a quasi-Monte Carlo lattice rule.
| Engine | Effective dimension | What it gives |
|---|---|---|
| Fixed tensor-product Gauss–Legendre rule | Up to 3 | Spectral convergence; about 46 digits on the one-loop massive box |
| Nested tanh-sinh quadrature | Up to 2 | Roughly 17 digits |
| Randomly shifted rank-1 lattice rule, parallel over the shifts | Irreducible, 4 to 12 | A 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.
- Stage A. A coarse lattice ($10^4$ points).
- Stage B. A fine lattice ($10^5$ points, relative target $10^{-7}$).
- Stage C. disteval's median-lattice rule at the stage-B targets, so that B and C are two different lattice constructions applied to the same integrand library.
- Compare. The three results are lined up order by order in $\varepsilon$.
- Check. The acceptance check fails if B and C differ by more than three standard deviations at any order. Otherwise it reports for each order the smaller of the B–C agreement and what the two error bars allow. The minimum over orders is the digit count of the whole result.
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:
- Route A's Gauss–Legendre values are as precise as a two-precision test says: run at
dpsand atdps+15and keep the digits on which the two runs agree. - Route A's lattice values are estimates with a statistical bar. Quote them only within the bar. At high dimension raise the point count and compare with another route, because with few points the bar can be too small.
- Route B's digit count is a measured agreement between two double-precision integrations, about 8 to 9 digits at best, with no proven bound.
- Neither route handles thresholds or physical-region kinematics. Route A has no contour deformation, and route B has so far been established only on libraries compiled without it.
- Route A does not handle poles in $\varepsilon$.
- The closed-form reduction applies when the exponents of $U$ and $F$ are 0 and 2. For other exponents the integrand $U^a/F^b$ is passed on unreduced, and finiteness is then the caller's responsibility.
- A kinematic constant rounded at low precision, such as
mpf(-1)/3at mpmath's default setting, is a slightly different rational number. Every engine then converges to the integral of that number, so pass integers,Fractions or decimal strings.
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:
--max-chunks 1: evaluates a single chunk and stops, so that one chunk can be tried before the whole stage;--resumethen continues the stage.--resume: continues an interrupted stage.--dry: rehearses the whole chain, with the disteval call replaced by a library-presence check and a canned result.--leaf-stamp: hands the check an end-of-runkey=valuereadback of the memory-limited process group you ran the stages in. A nonzerooom_killthere fails the check.
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/.
| Command | What it does |
|---|---|
selftest.py [--full] [--route ROUTE] | The self-tests of both routes; ROUTE is parametric, disteval or all |
selftest_parametric.py | The 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 FILE | The 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 DIR | One evaluation stage; B and C likewise |
pysecdec_point.py --stage compare --results NAME=RESULT.json ... --out FILE | The pairwise per-order comparison |
pysecdec_point.py --stage check | The acceptance check over --work DIR, or over the worked example's records with --example |
pysecdec_point.py --check-package | Verifies a library against its checksums |
pysecdec_point.py --emit-pins OUT | Writes the checksums of another family's library |
pysecdec_point.py --planted-fail-control | Prints the shifted-result self-check |
pysecdec_point.py --basis W | Prints 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.py | The 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.
| Function | What 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
- Runs on: Python 3 with
mpmath,sympy,numpyandgmpy2, andpytestfor route B's tests. - Install:
pip install gmpy2. Route A imports gmpy2 at load and stops with a message naming it if it is missing. - Route B stages: GNU time as
/usr/bin/time -v, which makes the stages Linux-only as distributed. The compare, the check and the example replay are not. - Optional: pySecDec, installed by you with
pip install pySecDec; it is not bundled. The example's records were made with version 1.6.6. Route A needs it only forbuild_UF, route B for the evaluation stages and for--dry. - macOS: worker pools start only under
if __name__ == '__main__', so route A also runs where the multiprocessing start method is spawn (the macOS default). - Self-test: run the first command below from
tools/longhand/. It ends with a line beginninglonghand battery PASSand exits nonzero on any failure.
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'.
| Reference | What it supplies |
|---|---|
| T. Binoth and G. Heinrich, hep-ph/0004013 | Sector decomposition |
| S. Borowka, G. Heinrich, S. Jahn, S. P. Jones, M. Kerner, J. Schlenk and T. Zirke, pySecDec, arXiv:1703.09692; code: secdec | The 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.11720 | pySecDec'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.19768 | The disteval evaluator |
| Z. Li, J. Wang, Q.-S. Yan and X. Zhao, arXiv:1508.02512 | Rank-1 lattice rules for Feynman integrals, the method of route A's lattice engine |
| D. Nuyens and R. Cools, Math. Comp. 75 (2006) 903 | The fast component-by-component construction of generating vectors; Longhand runs the plain component-by-component search |
| T. Goda and P. L'Ecuyer, arXiv:2201.09413 | The median-lattice rule of stage C |