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 packageSourceAuthors
The FORM job template in form_hyper.pyFollows, line for line, the example drivers that come with HyperFORM: examples/zigzags/zigzag3.frm and examples/multiscale/massless-box.frmA. Kardos, S.-O. Moch and O. Schnetz
The QCD model behind the routing test inputs and the examples/gg2qq/ exampleThe example model in the chapter "Diagram generation" of the FORM 5 reference manualJ. 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.

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:

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

CommandWhat 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 NPrints 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.

FunctionWhat 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

Requirements

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.

ReferenceWhat it supplies
J. A. M. Vermaseren, "New features of FORM", arXiv:math-ph/0010025FORM
J. Kuipers, T. Ueda, J. A. M. Vermaseren and J. Vollinga, Comput. Phys. Commun. 184 (2013) 1453, arXiv:1203.6543FORM, 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/formThe float engine behind form_oracle, and the diagram generator diagrams_
T. Kaneko, Comput. Phys. Commun. 92 (1995) 127GRACE, 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.17706909The integration library, and the example drivers that form_hyper.py follows
E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385The program whose core HyperFORM ports to FORM
F. Johansson and the mpmath contributors, mpmathThe arithmetic of tornheim and tornheim_w5

← back to the tools index