Galois

Galois is a Python package for exact arithmetic with multiple zeta valuesnested sums over integers m1 > m2 > ... > mk of 1/(m1^a1 ... mk^ak); the depth is the number of indices k and the weight is their sum (MZVs), which appear as constants in Feynman integrals and string amplitudes. It reduces any expression in single, double and triple zeta values, up to weight 23, to a canonical basis with exact rational coefficients, using the proved double-shuffle relationsthe linear relations found by writing a product of two MZVs both as nested sums and as iterated integrals of Ihara, Kaneko and Zagier. It also computes Brown's single-valued mapthe map from MZVs to the single-valued MZVs, a subalgebra named after the single-valued versions of the polylogarithms, of which these numbers are special values and the Galois derivationsoperations D_m, one for each odd m of 3 or more, that lower the weight by m $D_3, D_5, D_7,\dots$, after Goncharov, and turns them into exact linear constraints on the coefficients of an ansatza trial combination of known functions with unknown rational coefficients.

What it does

An MZV of depth $k$ and weight $a_1+\dots+a_k$ is, with the outer index written first as everywhere in the package,

$$\zeta(a_1,\dots,a_k)=\sum_{m_1\gt m_2\gt\cdots\gt m_k\ge 1}\frac{1}{m_1^{a_1}\cdots m_k^{a_k}},\qquad a_1\ge 2.$$

MZVs satisfy many rational linear relations (the regularized double-shuffle relations), so two exact answers can be compared only after both are reduced to a common basis.

MZVs also carry operations $D_m$ (odd $m\ge 3$) that lower the weight by $m$: $D_m$ sends $\zeta_m$ to 1, every other single zeta value and $\pi^2$ to 0, and obeys the product rule. On deeper values it follows from Goncharov's coproducta formula that splits an iterated integral into pairs of simpler iterated integrals; for example $D_5\,\zeta(5,3)=-5\,\zeta_3$.

The package has five modules:

In the relation tables, products, odd single zeta values and powers of $\pi^2$ stay as basis elements. As many double and triple values as possible are eliminated, and those that survive (e.g. $\zeta(5,3)$ at weight 8, $\zeta(5,3,3)$ at weight 11) complete the basis. Their count at each weight reproduces the dimensions of Broadhurst and Kreimer through weight 23. A reduction is a proved identity; no numerical fitting is involved.

The main application is narrowing an ansatz. The coaction principle (Brown; Panzer and Schnetz in $\phi^4$ theory) states that the functions a family of integrals produces should be closed under the $D_m$. Applied to $D_m$ of a candidate ansatz, the functionals from vspace give homogeneous rational linear equations on its coefficients without any new boundary data. Two cautions apply:

Galois has these limits:

Public programs cover the same mathematics: F. Chapoton's multiple_zeta module in SageMath, O. Schnetz's HyperlogProcedures, and the MZV Data Mine of J. Blümlein, D. J. Broadhurst and J. A. M. Vermaseren (arXiv:0907.2557). The released package is new code for the objects defined in the papers listed under Source and references. The relation tables follow the method and the basis conventions of the Data Mine. O. Schnetz's HyperlogProcedures produced solved results that vspace reads, and it defines the notation of those files.

Related pages: Lockpick (integer-relation fitting, which the tables replace at depth three or less), Rankscreen (consumes the constraint equations), Eichler (the elliptic case).

Examples

Build the relation tables, which the other modules need and a fresh clone can produce. With Python set up (see Requirements), run from the root of the repository; the package directory is tools/galois/:

python3 tools/galois/mzvring/build_ring.py --wmax N --out X.pkl [--resume PKL] [--checkpoint]

One line per weight reports the time and the survivors, e.g. w=8: 0.0s survivors [('m2', 5, 3)], then a DONE line with total time and peak memory; the tables are pickled to X.pkl. --wmax 21 takes about 30 minutes and --wmax 23 about two hours on one core, using under 100 MB of memory. The other modules look for ring21.pkl in the directory named by GALOIS_RING_BANK.

Reduce an MZV to the basis (the package README's example, with tools/ on sys.path):

from galois import mzvring
R = mzvring.load_ring(path)   # or set GALOIS_RING_BANK
v = R.csym(('m2', 5, 3))      # canonical form of mzv(5,3)
R.survivors[8]                # the depth<=3 basis at weight 8

Here v is {(('m2', 5, 3),): Fraction(1, 1)} and R.survivors[8] is [('m2', 5, 3)]: $\zeta(5,3)$ is the one double or triple value kept in the basis at weight 8. A reducible value comes back rewritten: R.csym(('m2', 3, 5)) has coefficient 1 on (('z',3),('z',5)), $-1/9450$ on four copies of ('pi2',) and $-1$ on (('m2',5,3),), i.e. $\zeta(3,5)=\zeta_3\zeta_5-\pi^8/9450-\zeta(5,3)$.

Single-valued MZVs as formulas, from tools/galois/, compositionsthe index lists a,b,c of the zeta values outer-first and separated by semicolons:

python3 svmap21.py derive --comps "5,7,7;3,9,7" [--svalign DIR] [--dps N] [--out J]

Each composition prints on one line as $2\,\zeta(a,b,c)$ plus an exact rational combination of basis monomials (products of $\zeta_2$, odd zeta values and surviving double or triple values). For 3,5,3 the output is Brown's $\zeta_{\rm sv}(3,5,3)=2\zeta(3,5,3)-2\zeta_3\,\zeta(5,3)-10\,\zeta_3^2\zeta_5$.

The derive command takes depth-three compositions; for depth two call svmap21.sv_reduce_many from Python, which gives for example $\zeta_{\rm sv}(5,3)=-10\,\zeta_3\zeta_5$. The table bound with --ring PKL must reach the highest weight requested, otherwise the run stops with a KeyError naming the missing symbol. A composition whose image needs depth-four MZVs stops with an error.

Routines

The scripts are in tools/galois/.

CommandWhat it does
mzvring/build_ring.py --wmax N --out X.pklBuilds the relation tables through weight N and pickles them to X.pkl
svmap21.py derive --comps "5,7,7;3,9,7"Prints $\zeta_{\rm sv}$ of each listed composition as a formula in ordinary MZVs
svmap21.py selftestRuns four groups of checks and writes its JSON record only on a full pass
sector21.py selftestChecks values and images against core, literature values and 200-digit FORM evaluations
sector21.py gates, sector21.py oracleRun the longer identity, parity and numeric checks
sector21.py sector, sector21.py svRegenerate the sector tables, at the path given by --tables JSON

The options are:

The modules are imported with from galois import core, vspace, sector21, svmap21, mzvring. Without GALOIS_T0DEEP set, leave out core and vspace: both stop at import (see Requirements).

FunctionWhat it returns
mzvring.load_ring(path=None)A Ring, called R below, with the pickled tables; the default is ring21.pkl in the table directory
R.csym, R.cmono, R.cvecThe canonical form of a symbol, a monomial, an expression; R.cvec(a) == R.cvec(b) is an exact equality test
R.survivors[w]The double and triple values kept as basis elements at weight w
mzvring.dsum, mzvring.dscale, mzvring.dmul, mzvring.znorm(n)The sum, a multiple and the product of expressions; $\zeta(n)$, with even $n$ converted to a rational times $\pi^n$
core.Dm_zpoly, core.Dm_hword, core.Dm_calL$D_m$ of a polynomial in $i\pi,\zeta_3,\zeta_5,\zeta_7,\zeta(5,3)$, of $H_u(z)$, of Brown's single-valued $\mathcal{L}_w$
core.Dm_vector, core.conj_vector$D_m$ and the complex conjugate of a vector in the single-valued space of one weight
vspace.collect_feed(include_i173)Vectors of the solved integrals in GALOIS_ANC_DIR, with counts of parsed and skipped entries; the flag adds fourloopI173.txt
vspace.saturate(vecs)The span closed under $D_3,D_5,D_7$, split by weight and parity
vspace.fiber_annihilator(fibers, wt, par)The exact functionals vanishing on one piece, with dimensions
sector21.Dm_comp, sector21.Dm_word, sector21.Dm_vec$D_m$ of $\zeta(c)$, of a binary word, of an expression
svmap21.init_ring(path=None)Binds the tables and clears the caches; use it, not sector21.init_ring, when switching tables
svmap21.sv_reduce_many(comps, orient='B')$\zeta_{\rm sv}$ of the compositions, as expressions
svmap21.derive_formulas(comps, dps=None, svalign_dir=None)The same as formulas in both index orders, with an optional numeric check

An expression is a dictionary that maps a monomial to a Fraction. A monomial is a sorted tuple of the symbols ('pi2',), ('z', n), ('m2', a, b) and ('m3', a, b, c). Ring(wmax) rebuilds the tables in full. The lower-level names (the ansatz parser core.element_vector, word conversions, table loaders and the steps of the single-valued map) are listed under INVOKE in GUIDE.md.

Used on this site

Requirements

Source and references

The code is tools/galois/ in the BootLoops repository. README.md there lists the checks the package was validated against.

ReferenceWhat it supplies
A. B. Goncharov, math/0103059; C. Duhr, arXiv:1203.0454The coproduct from which the $D_m$ are computed, in Duhr's formulation
F. Brown, arXiv:1102.1310 and arXiv:1102.1312The decomposition of MZVs used by the single-valued map; values for the checks
F. Brown, arXiv:1309.5309Single-valued MZVs and the single-valued map (section 7.2, eq. 7.3)
F. Brown, arXiv:1512.06409The coaction principle, as proposed
E. Panzer and O. Schnetz, arXiv:1603.04289Its form in $\phi^4$ theory
S. Caron-Huot, L. J. Dixon, F. Dulat, M. von Hippel, A. J. McLeod and G. Papathanasiou, arXiv:1906.07116Its form for amplitudes
K. Ihara, M. Kaneko and D. Zagier, Compos. Math. 142 (2006) 307; M. E. Hoffman, J. Algebra 194 (1997) 477The regularized double-shuffle relations and Hoffman's relation
D. J. Broadhurst and D. Kreimer, hep-th/9609128The dimensions that the basis counts reproduce
J. Blümlein, D. J. Broadhurst and J. A. M. Vermaseren, "The Multiple Zeta Value Data Mine", arXiv:0907.2557The method and the basis conventions that the relation tables follow
O. Schlotterer, Y. Sohnle and Y.-X. Tao, arXiv:2511.15883The normalization of the decomposition; values for the checks
X. Jiang, arXiv:2607.11645The solved integrals that vspace reads, and their conventions
O. Schnetz, HyperlogProceduresThe program that produced solved results in those files and defines their notation
F. Chapoton, the multiple_zeta module of SageMathA public program for the same mathematics
J. Kuipers, T. Ueda, J. A. M. Vermaseren and J. Vollinga, FORM, arXiv:1203.6543The 200-digit numerical checks, run through Formglue

← back to the tools index