Galois

The content on this page was written by AI under human supervision.

Galois is a Python package for exact arithmetic with multiple zeta values, the nested sums that appear as constants in Feynman integrals and string amplitudes. One half reduces any expression in single, double and triple zeta values, up to weight 23, to a canonical basis using proved relations, with exact rational coefficients. The other half computes the Galois derivations $D_3, D_5, D_7,\dots$ and Brown's single-valued map on these numbers and on polylogarithms, and turns them into exact linear constraints on the coefficients of an ansatz. It is unrelated to the finite-field galois library on PyPI.

What it does

A multiple zeta valuea nested sum 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 (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. The subpackage galois.mzvring generates the stuffle, shuffle and Hoffman relations weight by weight and solves them by exact Gaussian elimination over the rationals. 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 Broadhurst–Kreimer dimensions through weight 23. A reduction is a proved identity; no numerical fitting is involved. Expressions are dictionaries mapping a monomial, a sorted tuple of the symbols ('pi2',), ('z', n), ('m2', a, b), ('m3', a, b, c), to a Fraction.

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 coproduct; for example $D_5\,\zeta(5,3)=-5\,\zeta_3$. The module core computes $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. sector21 extends $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. svmap21 computes Brown's single-valued 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 independently obtained formulas and should not be changed.

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$. The module vspace reads the already-solved integrals of a family from published ancillary files, closes their span under $D_3,D_5,D_7$, splits it by weight and by parity under $z\leftrightarrow\bar z$, and returns the exact linear functionals vanishing on each piece. Applied to $D_m$ of a candidate ansatz, these 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 an independent exact solve and a check against values not used in the fit. And the allowed space is only as large as its solved input: if a known-correct function fails, add more solved integrals to the input rather than editing the space by hand.

Limits: exact only, no numerical evaluation (see Formglue); depth four or more raises an error; alternating sums and elliptic functions are out of scope; core stops at weight 8; the vspace parser expects the ancillary files of arXiv:2607.11645 and skips entries with letters beyond $\{0,1\}$.

Examples

Build the relation tables, which the other modules need and a fresh clone can produce:

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. --checkpoint rewrites X.pkl.partial after every weight; --resume PKL continues a table from its top weight. 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)$. R.cvec reduces a whole expression, so an exact equality test is R.cvec(a) == R.cvec(b).

Single-valued MZVs as formulas, from tools/galois/, compositions 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 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. --dps N also checks each formula numerically at $N$ digits against independent high-precision values read from the --svalign directory (not distributed; the check needs Formglue); --out J writes JSON with each formula in both index orders. A composition whose image needs depth-four MZVs stops with an error.

Routines

Relation tables (galois.mzvring)

mzvring/build_ring.py — command-line table builder (above).
load_ring(path=None) — load pickled tables into a Ring (default ring21.pkl in the table directory).
Ring — .csym, .cmono, .cvec canonicalize a symbol, monomial, expression; .survivors[w] lists the double and triple values kept as basis elements at weight w; Ring(wmax) rebuilds from scratch.
dsum, dscale, dmul — add, scale, multiply expressions.
znorm(n) — $\zeta(n)$, with even $n$ converted to a rational times $\pi^n$.
comp_word, word_comp, shuffle, mweight — index tuple to binary word and back; shuffle product; weight of a monomial.

Derivations through weight 8 (galois.core)

Dm_zpoly(zp, m) — $D_m$ on a polynomial in the weight-8 generators $i\pi,\zeta_3,\zeta_5,\zeta_7,\zeta(5,3)$.
Dm_hword(u, m), Dm_calL(w, m) — $D_m$ on $H_u(z)$ and on Brown's single-valued $\mathcal{L}_w$.
Dm_vector(vec, wt, m), conj_vector(vec) — $D_m$ and complex conjugation on a vector in the weight-wt single-valued space.
element_vector(el), sv_basis(wt), SVDecomposer — parsed ansatz element to vector; the single-valued basis and exact decomposition into it.

Allowed space (galois.vspace)

collect_feed(include_i173) — parse the solved ancillary files in the GALOIS_ANC_DIR directory (via load_entries, parse_entry; the flag adds the standalone fourloopI173.txt); returns vectors and counts of parsed and skipped entries.
saturate(vecs) — close under $D_3,D_5,D_7$ into (weight, parity) fibers.
fiber_annihilator(fibers, wt, par) — the exact functionals vanishing on one fiber, with dimensions.

Odd weights 11 to 21 (galois.sector21)

init_ring(path=None) — bind the relation tables.
Dm_comp(c, m), Dm_word(u, m), Dm_vec(vec, m) — $D_m$ of $\zeta(c)$, of a binary word, of an expression.
sv_proj(vec) — drop every term containing $\pi^2$.
zsh(u), sym_vec(s) — regularized zeta of a word, canonical form of a symbol; KeyError if the tables do not cover it.
sector_words(w), ms_for(w), load_tables(path=None) — compositions and $m$ values at a weight; read a tables JSON.
python3 sector21.py selftest|gates|oracle|sector|sv [--ring PKL --tables JSON --svalign DIR --receipt J] — selftest checks 255 values and 765 images against core, six literature values and six 200-digit FORM evaluations, and can write a JSON record; gates/oracle run the longer identity, parity and numeric checks; sector/sv regenerate the tables.

Single-valued map (galois.svmap21)

init_ring(path=None) — bind tables and clear caches (use this, not sector21.init_ring, when switching tables).
phi_sym(s), phi_vec(vec), sv_f(fv, orient='B') — $f$-alphabet decomposition and the single-valued map on it.
sv_reduce_many(comps, orient='B'), derive_formulas(comps, dps=None, svalign_dir=None) — $\zeta_{\rm sv}$ of compositions as expressions, or as formulas in both index orders (via coeffs_brown, formula_strings) with an optional numeric check.
python3 svmap21.py selftest|derive [--ring PKL --svalign DIR --dps N --comps ... --receipt J --out J] — the self-test runs four groups of checks (literature values, 27 depth-two pairs, the 61-formula regression, 22 re-derivations) and writes its JSON record only on a full pass.

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, and their images under the $D_m$ for that page's test of closure under the cosmic Galois group.

Requirements and source

Python 3 with sympy and mpmath (plus gmpy2 for the table eliminations); single core, under 1 GB of memory. Put the repository's tools/ on sys.path (ahead of any PyPI galois). Reference data is not distributed; an entry point that needs it stops with a message naming the environment variable to set, or takes an explicit path. The four variables are GALOIS_RING_BANK (relation tables, built as above), GALOIS_T0DEEP (weight-8 tables imported by core; not included in the repository), GALOIS_CAMPAIGN_BANK (sector and single-valued tables) and GALOIS_ANC_DIR (ancillary files of arXiv:2607.11645, from the arXiv). From a fresh clone the table builder runs as is; the sector21 and svmap21 routines (including derive) run once a table is built; their self-tests, core and vspace need the remaining directories. Self-tests: python3 tools/galois/svmap21.py selftest (the package's default self-test) and python3 tools/galois/sector21.py selftest, each with --ring PKL; the numerical checks in both need Formglue.

Code: tools/galois/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license. Related pages: Lockpick (integer-relation fitting, which the tables replace at depth three or less), Rankscreen (consumes the constraint equations), Eichler (the elliptic case). Background: Goncharov's coproduct; Brown, arXiv:1309.5309, for single-valued MZVs; Ihara–Kaneko–Zagier for double shuffle; Broadhurst–Kreimer for the dimensions.

← back to the tools index