Formglue
Formglue is the Python code BootLoops puts around FORM, the symbolic-manipulation program by Jos Vermaseren and the FORM developers, and around HyperFORM, the FORM integration library by Adam Kardos, Sven-Olaf Moch and Oliver Schnetz. Formglue reads FORM's output correctly, returns FORM 5's multiple zeta valuesnested sums over ordered positive integers; the formula is under What it does to Python as checked decimal strings, assigns loop momenta to the diagrams FORM 5 generates, and drives HyperFORM. A companion module, tornheim, evaluates the same kind of constants with mpmath alone, so a number from FORM can be compared with one computed a different way.
Where it comes from
FORM is by Jos Vermaseren and the FORM developers. HyperFORM is by Adam Kardos, Sven-Olaf Moch and Oliver Schnetz, and is a FORM port of the core of Erik Panzer's HyperInt. BootLoops downloads both from their authors and runs them unmodified, as separate programs. The code of Formglue was written by Claude, and two parts of the package follow the authors' material.
| Part of the package | Source | Authors |
|---|---|---|
The FORM job template in form_hyper.py | Follows, line for line, the example drivers that come with HyperFORM: examples/zigzags/zigzag3.frm and examples/multiscale/massless-box.frm | A. Kardos, S.-O. Moch and O. Schnetz |
The QCD model behind the routing test inputs and the examples/gg2qq/ example | The example model in the chapter "Diagram generation" of the FORM 5 reference manual | J. A. M. Vermaseren and the FORM developers |
Please cite the authors' papers when you use FORM or HyperFORM through Formglue. Formglue is not affiliated with or endorsed by the authors of either program.
What it does
FORM does the symbolic work (traces, color algebra, rewriting expressions too large for memory, diagram generation), and its own page covers that. Formglue lets a Python program use FORM's results without silent mistakes. It has five parts.
form_ioreads FORM output. FORM wraps long output lines in the middle of a token, with a trailing backslash or an indented continuation line, so code that reads the text line by line gets wrong numbers and wrong expressions.read_form_outputjoins the continuations back into logical lines. The rest of the package reads FORM output through it.form_oracleevaluates multiple zeta values $\zeta(a_1,\dots,a_k)$, the nested sums defined on the Galois page, and alternating Euler sums (the same with a sign $(-1)^{m}$ on chosen variables), using the float engine built into FORM 5. For a digit countdpsit runs a short FORM program atdps+10digits and checks that exactly one well-formed number came back. It returns a decimal string with at leastdpscorrect digits.form_routeadds what FORM 5's built-in diagram generator (diagrams_) leaves out. The generator gives every internal edge an independent label, and an integrand needs a momentum routingan assignment of a momentum to every internal line, built from the external momenta and one free momentum per loop, such that momentum is conserved at every vertex. The module builds each graph, picks a spanning tree, keeps one label per independent cycle as a loop momentum, and solves every other edge exactly. Vacuum diagrams and self-loops are handled.form_hyperis a bridge to HyperFORM, which integrates hyperlogarithmsiterated integrals of dx/(x - a) with fixed letters a; the Feynman-parameter integrals of many massless diagrams stay inside this class times rational functions one Feynman parameter at a time. The module writes a driver program, points FORM at your HyperFORM checkout and runs it. It parses the result into exact rational coefficients times named factors (z3for $\zeta(3)$,L(a1,...,an,x)for a hyperlogarithm in HyperInt's convention).tornheimandtornheim_w5need no FORM. They evaluate depth-two multiple zeta values, the Euler sum $\sum_k H_k/k^s$, and Mordell–Tornheim sums $T(a,b;c)=\sum_{m,n\ge1} m^{-a}n^{-b}(m+n)^{-c}$ with their triple and quadruple versions. From those they assemble the signed lattice sums $W_3$, $W_4$, $W_5$ that torus lattice sums and massless propagator integrals produce.
Every run of form_route verifies momentum conservation at each vertex, counts the loops in two ways, and checks that each external momentum enters once. A failure stops the run with RouteError and a nonzero exit code.
The sums $W_3$, $W_4$ and $W_5$ run over three to five nonzero integers adding to zero, weighted by powers of their absolute values and of the total length. The method is exact recursion plus a finite head sum and an asymptotic tail at the current mp.dps.
Formglue has these limits:
- Constants only: FORM 5.0.1 has no numerical polylogarithms.
form_oraclerefuses divergent index patterns, total weight above 22 and more than 1000 digits. A FORM failure, or a missing or unevaluated value, raises an exception.build_driverinform_hypercovers finite projective integrals. A divergent integral needs a hand-written driver passed torun_driver.tornheimresults carry no error bound. Repeat at higher precision to check.
Examples
Route a generated diagram set (no FORM needed). The package includes the 30 on-shell one-loop $gg\to q\bar q$ diagrams from the FORM page, as FORM 5.0.1's generator printed them. With Python 3 installed (see Requirements), run from the package directory tools/formglue/:
python3 form_route.py tests/fixtures/gen/enum_onshell_nodes.out --externals p1,p2,q1,q2 --table -
The table gives each edge's label, endpoints, kind (external, tree edge, or loop edge chord) and assigned momentum. The run ends with ROUTED 30 diagrams, all self-checks PASS (L values: [1]) and exit code 0. In the first diagram, for instance, the loop edge k3 keeps its own label and the tree edges come out as -q1-q2 and -q1-q2-k3.
Use --form route.h instead to write FORM id statements, one #procedure route<i>() per diagram, to #include into an integrand program. Use --json route.json for the full structure. In Python the same call is route_file(path, externals=["p1","p2","q1","q2"]).
A multiple zeta value from FORM, checked without FORM. This example needs a float-capable FORM 5 on PATH (or named in FORM5_BIN). --dps goes before -- when an index is negative:
python3 form_oracle.py --dps 40 euler -- -2,1
The command prints one number in mantissa-exponent form, $\zeta(3)/8$ to at least 40 digits. The outer index comes first (mzv((2,1), dps) is $\zeta(3)$), and a negative Euler index puts the sign on that variable.
From Python, the pattern in the package's tests and in Galois is to parse at an explicit precision and compare with tornheim. Run it with the repository's tools/ directory on the Python path:
import mpmath as mp
from formglue import form_oracle, tornheim
s = form_oracle.mzv((5, 3), 60) # runs FORM; string with at least 60 correct digits
x = form_oracle.to_mpf(s, 60) # parse at an explicit precision
with mp.workdps(85):
ref = tornheim.mzv2(5, 3) # the same zeta(5,3) from an mpmath series
print(mp.nstr(x - ref, 5))
The difference should be below $10^{-60}$. If FORM is missing or exits with an error, mzv raises FormRunError naming the binary it tried. It raises FormParseError if FORM ran but printed no number. probe_float_support() checks, without raising, whether the FORM on hand can evaluate floats.
Lattice sums without FORM. python3 tornheim.py prints the module's built-in checks: $W_3((1,1,1);1)$ beside $\pi^4/60$, MT3 and conv22 against brute-force sums, $W_4((1,1,1,1);1)$ against $30\zeta_5-12\zeta_2\zeta_3$, and $W_4((2,2,2,2);1)$ repeated at 60, 100 and 150 digits. python3 tornheim_w5.py evaluates $W_5((1,1,1,1,1);1)$ at 30 digits against a stored reference and exits nonzero if they differ by more than $10^{-25}$. In your own code set mp.mp.dps, then call for example tornheim.W3((1,1,1), 1).
Routines
| Command | What it does |
|---|---|
python3 form_route.py INPUT [options] | Routes every diagram in a diagrams_ dump; exit code 2 on failure |
python3 form_oracle.py FUNC INDICES --dps N | Prints one constant; FUNC is zeta, mzv or euler |
The options of form_route.py are --externals and --loops (comma-separated names), --table FILE (- prints to the screen), --form FILE, --json FILE and --quiet. --mutate-edge LABEL corrupts one momentum before the checks, only to demonstrate that they can fail.
| Function | What it returns |
|---|---|
form_io.read_form_output(path_or_str) | A file or string of FORM output with wrapped lines joined |
form_io.unwrap_form_text(text) | The joining rule alone, for text in memory |
form_oracle.zeta(n, dps), mzv(indices, dps), euler(indices, dps) | A string with at least dps correct digits; workdir= keeps FORM's files |
form_oracle.to_mpf(s, dps) | The string parsed into an mpmath number at that precision |
form_oracle.probe_float_support(binary=None) | (capable, detail): whether the FORM found can evaluate floats, and its version |
form_route.route_file(path, ...), route_text(text, externals=None, loops=None) | RoutedDiagram objects with .routing() and .to_json() |
form_route.routing_table(diagrams), form_block(diagrams), mom_str(v, order=()) | The readable table, the FORM #procedure block, one momentum as text |
form_hyper.run_driver(frm_text, ...) | {expression: printed body} from a HyperFORM program run through FORM 5, or tform with nthreads |
form_hyper.run_example(relpath) | The same for one of HyperFORM's examples, such as run_example('zigzags/zigzag3.frm') |
form_hyper.build_driver(name, integrand, nalpha, ...) | Driver text for a finite projective integral over al1..alN; integrand in FORM syntax with num() and den() |
form_hyper.hyper_integrate(name, integrand, nalpha, ...) | The body of name, after building and running the driver |
form_hyper.parse_terms(body) | A printed body as (rational coefficient, {factor: power}) pairs |
tornheim.mzv2(s, t), eulerH(s) | Depth-two $\zeta(s,t)$; $\sum_k H_k/k^s$ |
tornheim.T2(a, b, c), MT3(a, b, c, d), tornheim_w5.MT4(a, b, c, d, e) | Double, triple and quadruple Mordell–Tornheim sums |
tornheim.conv22(...), tornheim_w5.conv23(...) | The convolution sums for the sign sectors of $W_4$ and $W_5$ with two positive entries |
tornheim.W3(p, q), W4(p, q), tornheim_w5.W5(p, q) | Signed lattice sums with exponent tuple p and total-length exponent q |
form_hyper raises HyperFormError when HYPERFORM_SRC is unset, HyperFormRunError when FORM fails and HyperFormParseError when the output cannot be read.
Used on this site
- Modular graph functions (string theory): the
tornheimmodule evaluated the sector sums with three and four wound edges, in agreement with the exact coefficients to hundreds of digits.
Requirements
- Runs on: Python 3 with mpmath.
form_io,form_route,tornheimandtornheim_w5need no other program. - FORM:
form_oracleandform_hyperneed FORM 5 built from the FORM source repository with--enable-float, asformonPATHor named inFORM5_BIN. The FORM 4 packaged by distributions lacks float support. - HyperFORM:
form_hyperalso needs a HyperFORM clone, withHYPERFORM_SRCset to itssrc/directory. Nothing needs compiling. - Self-test: from the repository root,
python3 -m pytest tools/formglue -x -q -p no:cacheprovider(orpython3 run_selftests.py formglue). - Single tests: from
tools/formglue/,python3 tests/test_form_io.pyandpython3 tests/test_form_route.pyuse stored FORM output intests/fixtures/and need no FORM. Each ends with aTOTAL:line that reports0 failures. - Tests with FORM:
python3 tests/test_form_oracle.pyalways runs its validation and error-path tests. Its three float-engine tests run when a float-capable FORM 5 is present and are otherwise skipped, with a message saying which FORM was found and what it lacks. - HyperFORM bridge:
python3 form_hyper.pyneeds FORM 5 and HyperFORM. It replays HyperFORM'szigzag3example, requires exactly $6\zeta(3)$, and runs thebasic/productexample. It prints a line beginningform_hyper selftest: PASSand exits with code 0 on success, 1 on failure.
Source and references
The code is tools/formglue/ in the BootLoops repository. It is released under the MIT license, except form_hyper.py, which is distributed under GPL-3.0-only because its FORM job template follows HyperFORM's example drivers, as the package NOTICE states. FORM and HyperFORM are not part of the package.
| Reference | What it supplies |
|---|---|
| J. A. M. Vermaseren, "New features of FORM", arXiv:math-ph/0010025 | FORM |
| J. Kuipers, T. Ueda, J. A. M. Vermaseren and J. Vollinga, Comput. Phys. Commun. 184 (2013) 1453, arXiv:1203.6543 | FORM, version 4 |
| J. Davies, T. Kaneko, C. Marinissen, T. Ueda and J. A. M. Vermaseren, "FORM Version 5.0", arXiv:2601.19982; code: form-dev/form | The float engine behind form_oracle, and the diagram generator diagrams_ |
| T. Kaneko, Comput. Phys. Commun. 92 (1995) 127 | GRACE, on which FORM's diagram generator builds |
| A. Kardos, S.-O. Moch and O. Schnetz, HyperFORM, arXiv:2607.01163; code: HyperFORM, doi:10.5281/zenodo.17706909 | The integration library, and the example drivers that form_hyper.py follows |
| E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385 | The program whose core HyperFORM ports to FORM |
| F. Johansson and the mpmath contributors, mpmath | The arithmetic of tornheim and tornheim_w5 |