Surd

Surd integrates a three-fold parametric integral with a rational integrand exactly, on a one-parameter family of kinematics labeled by $t$, and returns a closed form in $t$. The closed form is a finite sum of hyperlogarithmsiterated integrals $G(a_1,\dots,a_n;z)=\int_0^z \frac{dx}{x-a_1}\,G(a_2,\dots,a_n;x)$, the functions produced by integrating rational functions one variable at a time; logarithms and polylogarithms are special cases of weight at most three whose arguments may be algebraic in $t$ (roots of quadratic and cubic polynomials included), with exact rational-function coefficients. It uses the hyperlogarithm integration method of F. Brown and E. Panzer; BootLoops wrote it for the leading-order collinear four-point energy correlator, and its drivers are organized around that integral.

What it does

Feynman-parameter integrals with rational integrands are often computed one variable at a time. Each integration gives hyperlogarithms again as long as the denominators stay linear in the next variable; an integral with that property throughout is linearly reducibleevery intermediate denominator factors into polynomials of degree one in the next integration variable, so each step is again a partial-fraction problem. Panzer's HyperInt and HyperFLINT by Giroux, Mizera and Salvatori (see the SubTropica page) handle that case.

Many integrals fail only at the last integration, where the remaining variable sits inside irreducible quadratic or cubic polynomials. The answer is still a hyperlogarithm, but some of its lettersthe arguments $a$ of the logarithmic forms $d\log a$ from which a polylogarithmic function is built; the full set, the alphabet, fixes where the function can have branch points are roots of those polynomials. HyperInt and HyperFLINT have options for square-root letters; neither handles the cube-root letters met here. Surd carries both kinds exactly through the last integration. A surd is the old word for an irreducible root such as $\sqrt{2}$ or $\sqrt[3]{5}$.

Surd handles that case with one symbolic parameter, in three stages.

The unit of work is a group of integrand terms sharing a denominator structure, with an elimination order for which the first two integrations are linear. The order, and the table of polynomials allowed in denominators at each stage, come from a linear-reducibility run and are given as input. Surd does not search for them. The strict engine stops with the error OffAlphabet at a denominator factor outside the table; the drivers extend the table and list every added letter in the run record.

Every group is compared twice, each time to at least 30 digits, with numerical evaluations that use none of the integrator's code. The stage-2 intermediate is compared with a residue-plus-quadrature evaluation in Arba ball-arithmetic library, in which every number carries a rigorous error radius, and the stage-3 closed form with an Arb evaluation in two charts (two choices of the variable set to 1). These comparisons support the result at that level; they are not a proof.

Each group leaves exact checkpoints and a JSON record under the output root named by SURD_WORK, and assemble.py sums groups into one .json.gz file per function in the format documented in FORMAT.md. Surd also evaluates the closed form to a requested precision and answers structure questions about it, such as which polynomials in $t$ appear as logarithmic singularities and how the function behaves near their roots.

Surd has these limits:

The largest cases Surd has been used on are the closed forms of the four-point energy correlator: 31,117 terms for the quark jet, 41,034 for the gluon jet and 21,348 for $\mathcal{N}=4$ super Yang–Mills.

Examples

Run the smoke test. With the package set up (see Requirements), run from the package directory tools/surd/:

bash tests/smoke_test.sh [TARGET]

TARGET is a fresh scratch directory outside the source tree (default ${TMPDIR:-/tmp}/surd_smoke.<stamp>); a target inside the tree, or one that already exists, is refused. The script sets SURD_WORK and SURD_DATA to the target itself, so nothing else needs to be set.

The script runs one group from the included cell files through the three stages and both comparisons, and writes only under the target. It prints the agreeing digits of the two comparisons, the closed-form values at $t=1/2$ and $4/5$ beside frozen reference strings, and finally [smoke] RESULT: PASS. Expect 3 to 5 minutes and about 0.2 GB.

Integrate one group by hand. SURD_WORK names the output root and should point at a scratch directory outside the package (default ./surd_work under the current directory; a root inside the package tree is refused).

export SURD_WORK=/path/to/scratch/surd_work
cd slice/scripts
python3 slice_run.py --channel q_qbpqpgq --sigma 1234 --pair 34
python3 slice_gate12.py --tag q_qbpqpgq_s1234_p34_g2
python3 stage3.py --tag q_qbpqpgq_s1234_p34_g2 --t 1/2,4/5

The first command does the two linear integrations and writes ckpt/<tag>/stage1.pkl, stage2.pkl and the record SLICE_S12_<tag>.json. The second writes SLICE_G12_<tag>.json with the minimum agreeing digits of the stage-2 comparison and a pass flag. The third does the function-level integration and writes the exact stage3.pkl and SLICE_S3_<tag>.json, with the closed-form values at the listed $t$ beside the reference values.

The package includes the cell inputs for this one channel only. The other channels of the built-in problem read external term lists from the directory named by SURD_TERMS and stop with an error that names the missing file if a list is not found.

Integrate many groups. List one channel sigma pair per line in a file and run the worker:

SURD_WORK=<scratch dir> bash slice/scripts/s13_worker.sh LIST NAME [t-list]

The worker runs the three commands above for each line, skips finished groups and logs under $SURD_WORK/logs/.

Evaluate a result file. With SURD_DATA naming a directory whose out/ holds files written by assemble.py (no assembled files come with the package):

python3 evaluate.py --file quark --t 3/5 [--dps 60] [--digits 30]

The JSON report carries value, digits_est, the attempts and a mode. The exact value is real, so the imaginary part of the numerical sum is the error monitor; if the estimate falls short of --digits the working precision is raised and the evaluation repeated. Expect roughly the working precision minus 10 digits, fewer near values of $t$ where single terms blow up while the sum stays finite.

At a rational $t$ where the representation divides by zero although the function is analytic (as here), mode reads symmetric limit (delta=...). The mean of the values at $t\pm\delta$ is then returned with its error.

Routines

The scripts are in slice/scripts/ unless a directory is given.

CommandWhat it does
slice_run.py --channel C --sigma S --pair PStages 1 and 2 for one group; a finished group is skipped on rerun unless --force is given
slice_gate12.py --tag TAGCompares the stage-2 intermediate with the residue-route evaluation
stage3.py --tag TAG --t LISTStage 3 and its comparison; --reuse re-evaluates an existing pickle, --no-po skips the comparison
s13_worker.sh LIST NAME [t-list]The three commands above for every line of a list file; run one worker per core on disjoint lists
slice_classes.pyThe exact relabeling symmetries of a channel and the class multiplicities that assemble.py needs
assemble.pySums groups into per-channel and per-jet files, collecting identical terms exactly
evaluate.py --file F --t p/qEvaluates a file, raising the precision as needed, with the symmetric limit where the representation is singular
slice_oracle.py --t LISTReference values to 30 digits per channel and per jet at rational $t$, by two integration routes; a rerun resumes
file_gate.pyCompares assembled files with every available reference value; --receipt writes the summary record
letters.pyRational and algebraic letters per function, discriminants factored over $\mathbb{Q}[t]$, cubic letters included
symtest.pyWhether the square-root letters survive in the symbol (SURVIVES or CANCELS), per weight and discriminant class
valtest.pyWhether $\log P(t)$ is a letter, per weight and symbol slot
tstar_local.py, near_root.pyBehavior near the real roots of each class on the principal sheet
landau_family.py, n4_alphabet.pyWhich denominator polynomials generate each algebraic letter; a function's prime support against an external alphabet file
gate/scripts/oracle.pyThe collinear four-point correlator to 30 digits at a rational complex shape
gate/scripts/onefold_arb.pyArb integrator for the last integration of a one-variable object with numeric kinematics

The modules are imported with slice/scripts on sys.path. oracle_cells and onefold_arb are in gate/scripts/, which import slice_prov adds to the path.

FunctionWhat it returns
assemble.evaluate_file(path, t, dps)The value of an assembled file at $t$
slice_common.build_group(channel, gauge, pair, sigma)The integrand of one group; with d_of_t and order_for, the code to copy for a new integral
oracle_cells.build_cells(channel, gauge)The exact cell integrands with symbolic kinematics
onefold_arb.fibre_residueThe residue-route evaluation used in the stage-2 comparison

The engine modules (fibr.py, fib3.py, int3.py, k3field.py, hpath.py, hlog_eval.py), the reference evaluators and the environment variables are described in MANUAL.md, sections 5 to 9.

Used on this site

Requirements

Source and references

The code is tools/surd/ in the BootLoops repository. MANUAL.md there is the manual, FORMAT.md specifies the output files and DATA.md describes the package data.

ReferenceWhat it supplies
F. Brown, Commun. Math. Phys. 287 (2009) 925, arXiv:0804.1660The method: hyperlogarithm fibration and the linear-reducibility criterion
E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385The algorithmic form of the method, as implemented for rational alphabets in HyperInt
M. Giroux, S. Mizera and G. Salvatori, SubTropica and HyperFLINT, arXiv:2604.20954The regularization conventions, which follow HyperFLINT; the program that hf_piece.py --run calls
J. Vollinga and S. Weinzierl, Comput. Phys. Commun. 167 (2005) 177, hep-ph/0410259The numerical evaluation of hyperlogarithms by the Hölder-convolution method of Borwein, Bradley, Broadhurst and Lisonek
A. B. Goncharov, math/0103059The total differential of iterated integrals, used in stage 3
D. Chicherin, I. Moult, E. Sokatchev, K. Yan and Y. Zhu, ancillary files of arXiv:2401.06463The data file N4_SLICE.json, adapted from their files (restricted to a one-parameter slice and re-factored)
V. Del Duca, C. Duhr, R. Haindl, A. Lazopoulos and M. Michel, JHEP 02 (2020) 189, arXiv:1912.06425; JHEP 10 (2020) 093, arXiv:2007.05345The tree-level quadruple-collinear splitting functions
The same authors, file P_qbp_qp_g_q.m on their supplementary-material pageThe quark splitting function in computer-readable form; the cell data under gate/cells/ are derived from that file

← back to the tools index