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.
- Stages 1 and 2. The first two integrations are exact polynomial arithmetic over the Gaussian rationals $\mathbb{Q}(i)$ (the rational numbers with $i$ adjoined) in the integration variables and $t$. Denominators are kept as exponent vectors over a table of irreducible polynomials, not multiplied out.
- Stage 3. The third integration is done at function level: the roots of the last-variable polynomials are adjoined as exact algebraic quantities over $\mathbb{Q}(i)(t)$ and partial fractions are taken in that extension.
- Result. Each term is a coefficient in $\mathbb{Q}(i)(t)$ times powers of roots times hyperlogarithms whose arguments are rational points or roots. An argument lying exactly on the positive real integration path is taken as "argument $-\,i0$". No fit, tolerance or integer-relation search enters the construction.
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:
- One symbolic parameter and exactly three integrations, the first two linear.
- Evaluation is on the principal sheet (the branch on which the integral is defined). The package can bound the exponent of a possible singularity at a root of $P(t)$ but cannot extract the coefficient of a singularity on another sheet.
- The symbola sum of "words", ordered strings of letters drawn from a finite alphabet of functions of the kinematics, encoding the branch cuts test treats square-root letters only.
- The drivers address integrands by the names of the energy-correlator problem (
--channel,--sigma,--pair). A different integral needs its own constructor on the pattern ofslice_common.build_group.
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.
| Command | What it does |
|---|---|
slice_run.py --channel C --sigma S --pair P | Stages 1 and 2 for one group; a finished group is skipped on rerun unless --force is given |
slice_gate12.py --tag TAG | Compares the stage-2 intermediate with the residue-route evaluation |
stage3.py --tag TAG --t LIST | Stage 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.py | The exact relabeling symmetries of a channel and the class multiplicities that assemble.py needs |
assemble.py | Sums groups into per-channel and per-jet files, collecting identical terms exactly |
evaluate.py --file F --t p/q | Evaluates a file, raising the precision as needed, with the symmetric limit where the representation is singular |
slice_oracle.py --t LIST | Reference values to 30 digits per channel and per jet at rational $t$, by two integration routes; a rerun resumes |
file_gate.py | Compares assembled files with every available reference value; --receipt writes the summary record |
letters.py | Rational and algebraic letters per function, discriminants factored over $\mathbb{Q}[t]$, cubic letters included |
symtest.py | Whether the square-root letters survive in the symbol (SURVIVES or CANCELS), per weight and discriminant class |
valtest.py | Whether $\log P(t)$ is a letter, per weight and symbol slot |
tstar_local.py, near_root.py | Behavior near the real roots of each class on the principal sheet |
landau_family.py, n4_alphabet.py | Which denominator polynomials generate each algebraic letter; a function's prime support against an external alphabet file |
gate/scripts/oracle.py | The collinear four-point correlator to 30 digits at a rational complex shape |
gate/scripts/onefold_arb.py | Arb 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.
| Function | What 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_residue | The 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
- The four-point energy correlator: computed the leading-order collinear correlator in closed form on the one-parameter family of dipole shapes for quark jets, gluon jets and $\mathcal{N}=4$ super Yang–Mills, and compared their letters.
Requirements
- Runs on: Python 3.10 or newer with python-flint, sympy and mpmath; bash and GNU coreutils for the shell drivers. Everything is single-threaded and fits in an 8 GB memory cap; groups can run side by side.
- Install:
pip install python-flint sympy mpmath. There is nothing to build. - SubTropica: the hyperlogarithm evaluator imports
zip_numfrom the SubTropica package (tools/subtropica/scripts/fibrate/), found automatically in the repository layout or throughSURD_FIBRATE. - Directories: set
SURD_WORKto a scratch directory before running anything, andSURD_DATAto the directory holding assembledout/*.json.gzfiles for the structure tools and tests (default: the work directory). - Self-test:
bash tests/smoke_test.sh [TARGET]ends with[smoke] RESULT: PASS. - Regression suite:
python3 tests/run_tests.py [--only h,p,g,n,a,b,c,d2,e,s12] [--data <dir>] [--quick] [--dps 60]runs four hermetic tests in a few seconds without data;--only s12adds stages 1–2 of one group, about 50 s. Exit code 0 means every selected test that ran passed. - Data tests: the five tests
a,b,c,d2,eneed the assembled result files (--dataorSURD_DATA), which are not part of the package, and are skipped by name otherwise. Testsbandd2take about 8 minutes together and all five about an hour and 2.1 GiB. - Optional: the HyperFLINT program, needed only for
gate/scripts/hf_piece.py --runand for the piece files thatonefold_arb.pyreads; setSUBTROPICA_HF_BINandSUBTROPICA_MZV_DATA.
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.
| Reference | What it supplies |
|---|---|
| F. Brown, Commun. Math. Phys. 287 (2009) 925, arXiv:0804.1660 | The method: hyperlogarithm fibration and the linear-reducibility criterion |
| E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385 | The algorithmic form of the method, as implemented for rational alphabets in HyperInt |
| M. Giroux, S. Mizera and G. Salvatori, SubTropica and HyperFLINT, arXiv:2604.20954 | The 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/0410259 | The numerical evaluation of hyperlogarithms by the Hölder-convolution method of Borwein, Bradley, Broadhurst and Lisonek |
| A. B. Goncharov, math/0103059 | The 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.06463 | The 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.05345 | The tree-level quadruple-collinear splitting functions |
The same authors, file P_qbp_qp_g_q.m on their supplementary-material page | The quark splitting function in computer-readable form; the cell data under gate/cells/ are derived from that file |