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:
- Relation tables.
galois.mzvringgenerates, weight by weight, the stuffle and shuffle relations (the product of two MZVs written as sums and as iterated integrals) and Hoffman's relation. It solves them by exact Gaussian elimination over the rationals. - Derivations through weight 8.
corecomputes $D_3,D_5,D_7$ exactly on MZVs through weight 8, on harmonic polylogarithmsiterated integrals H_u(z) of dz/z and dz/(1-z), labeled by a binary word u $H_u(z)$, and on Brown's single-valued combinations of them. - Derivations at odd weights 11 to 21.
sector21extends $D_m$ ($m=3,\dots,19$) to odd-index double and triple zeta values at odd weights 11 through 21, reducing with the relation tables. - Single-valued map.
svmap21computes Brown's map $\zeta(a,b,c)\mapsto\zeta_{\rm sv}(a,b,c)$ (arXiv:1309.5309, eq. 7.3) as an exact formula in ordinary MZVs by a linear solve over the basis, with no numerical input. Its orientation convention (orient='B') was fixed by reproducing 61 reference formulas and should not be changed. - Allowed space.
vspacereads the already-solved integrals of a family from published ancillary files and closes their span under $D_3,D_5,D_7$. It splits the span by weight and by parity under $z\leftrightarrow\bar z$, and returns the exact linear functionals vanishing on each piece.
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:
- The principle is a conjecture, so a result obtained with these equations still needs a separate exact solve and a check against values not used in the fit.
- The allowed space is only as large as its solved input. If a known-correct function fails, add more solved integrals to the input; do not edit the space by hand.
Galois has these limits:
- It is exact only, with no numerical evaluation (see Formglue).
- Depth four or more raises an error.
- Alternating sums and elliptic functions are out of scope.
corestops at weight 8.- The
vspaceparser expects the ancillary files of arXiv:2607.11645 and skips entries with letters beyond $\{0,1\}$.
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/.
| Command | What it does |
|---|---|
mzvring/build_ring.py --wmax N --out X.pkl | Builds 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 selftest | Runs four groups of checks and writes its JSON record only on a full pass |
sector21.py selftest | Checks values and images against core, literature values and 200-digit FORM evaluations |
sector21.py gates, sector21.py oracle | Run the longer identity, parity and numeric checks |
sector21.py sector, sector21.py sv | Regenerate the sector tables, at the path given by --tables JSON |
The options are:
- Table builder:
--checkpointrewritesX.pkl.partialafter every weight.--resume PKLcontinues a table from its top weight. - Both scripts:
--ring PKLnames the relation tables thatsector21.pyorsvmap21.pyuses. - Derive:
--dps Nalso checks each formula numerically at $N$ digits against high-precision values read from the--svaligndirectory. These values are not distributed, and the check needs Formglue.--out Jwrites JSON with each formula in both index orders. - Self-tests:
--receipt Jwrites the JSON record of the self-test. - Sector tables:
--tables JSONnames the sector-table file forsector21.py sectorandsector21.py sv.
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).
| Function | What 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.cvec | The 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
- Modular graph functions (string theory): the depth-three single-valued zeta values at weights 11 through 21 as exact formulas in ordinary MZVs. Their images under the $D_m$ are used in that page's test of closure under the cosmic Galois group.
Requirements
- Runs on: Python 3 with
sympyandmpmath; single core, under 1 GB of memory. - Install: no build step. Put the repository's
tools/onsys.path, ahead of any PyPIgalois. The finite-fieldgaloislibrary on PyPI is unrelated. - Reference data: not distributed. An entry point that needs it stops with a message naming the environment variable to set, or takes an explicit path.
GALOIS_RING_BANK: the relation tables, built as in the first example.GALOIS_T0DEEP: the weight-8 tables imported bycore; not included in the repository.GALOIS_CAMPAIGN_BANK: the sector and single-valued tables.GALOIS_ANC_DIR: the ancillary files of arXiv:2607.11645, from the arXiv.- From a fresh clone: the table builder runs as is. The
sector21andsvmap21routines (includingderive) run once a table is built. Their self-tests,coreandvspaceneed the remaining directories. - Self-test:
python3 tools/galois/svmap21.py selftest(the package's default self-test) andpython3 tools/galois/sector21.py selftest, each with--ring PKL. On success the first prints four lines that begingate pin PASS,gate depth2 PASS,gate regress61 PASSandgate extcheck PASS. The second prints three lines that begingate a PASS,gate c PASSandgate e-spot PASS. The numerical checks in both need Formglue.
Source and references
The code is tools/galois/ in the BootLoops repository. README.md there lists the checks the package was validated against.
| Reference | What it supplies |
|---|---|
| A. B. Goncharov, math/0103059; C. Duhr, arXiv:1203.0454 | The coproduct from which the $D_m$ are computed, in Duhr's formulation |
| F. Brown, arXiv:1102.1310 and arXiv:1102.1312 | The decomposition of MZVs used by the single-valued map; values for the checks |
| F. Brown, arXiv:1309.5309 | Single-valued MZVs and the single-valued map (section 7.2, eq. 7.3) |
| F. Brown, arXiv:1512.06409 | The coaction principle, as proposed |
| E. Panzer and O. Schnetz, arXiv:1603.04289 | Its form in $\phi^4$ theory |
| S. Caron-Huot, L. J. Dixon, F. Dulat, M. von Hippel, A. J. McLeod and G. Papathanasiou, arXiv:1906.07116 | Its form for amplitudes |
| K. Ihara, M. Kaneko and D. Zagier, Compos. Math. 142 (2006) 307; M. E. Hoffman, J. Algebra 194 (1997) 477 | The regularized double-shuffle relations and Hoffman's relation |
| D. J. Broadhurst and D. Kreimer, hep-th/9609128 | The 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.2557 | The method and the basis conventions that the relation tables follow |
| O. Schlotterer, Y. Sohnle and Y.-X. Tao, arXiv:2511.15883 | The normalization of the decomposition; values for the checks |
| X. Jiang, arXiv:2607.11645 | The solved integrals that vspace reads, and their conventions |
| O. Schnetz, HyperlogProcedures | The program that produced solved results in those files and defines their notation |
F. Chapoton, the multiple_zeta module of SageMath | A public program for the same mathematics |
| J. Kuipers, T. Ueda, J. A. M. Vermaseren and J. Vollinga, FORM, arXiv:1203.6543 | The 200-digit numerical checks, run through Formglue |