Algebra of motivic multiple zeta values

This file contains an implementation of the algebra of motivic multiple zeta values.

The elements of this algebra are not the usual multiple zeta values as real numbers defined by concrete iterated integrals, but abstract symbols that satisfy all the linear relations between formal iterated integrals that come from algebraic geometry (motivic relations). Although this set of relations is not explicit, one can test the equality as explained in the article [Brown2012]. One can map these motivic multiple zeta values to the associated real numbers. Conjecturally, this period map should be injective.

The implementation follows closely all the conventions from [Brown2012].

As a convenient abbreviation, the elements will be called multizetas.

EXAMPLES:

One can input multizetas using compositions as arguments:

sage: Multizeta(3)
ζ(3)
sage: Multizeta(2,3,2)
ζ(2,3,2)

as well as linear combinations of them:

sage: Multizeta(5)+6*Multizeta(2,3)
6*ζ(2,3) + ζ(5)

This creates elements of the class Multizetas.

One can multiply such elements:

sage: Multizeta(2)*Multizeta(3)
6*ζ(1,4) + 3*ζ(2,3) + ζ(3,2)

and their linear combinations:

sage: (Multizeta(2)+Multizeta(1,2))*Multizeta(3)
9*ζ(1,1,4) + 5*ζ(1,2,3) + 2*ζ(1,3,2) + 6*ζ(1,4) + 2*ζ(2,1,3) + ζ(2,2,2)
+ 3*ζ(2,3) + ζ(3,1,2) + ζ(3,2)

The algebra is graded by the weight, which is the sum of the arguments. One can extract homogeneous components:

sage: z = Multizeta(6)+6*Multizeta(2,3)
sage: z.homogeneous_component(5)
6*ζ(2,3)

One can also use the ring of multiple zeta values as a base ring for other constructions:

sage: Z = Multizeta
sage: M = matrix(2,2,[Z(2),Z(3),Z(4),Z(5)])
sage: M.det()
-10*ζ(1,6) - 5*ζ(2,5) - ζ(3,4) + ζ(4,3) + ζ(5,2)

Auxiliary class for alternative notation

One can also use sequences of 0 and 1 as arguments:

sage: Multizeta(1,1,0)+3*Multizeta(1,0,0)
I(110) + 3*I(100)

This creates an element of the auxiliary class Multizetas_iterated. This class is used to represent multiple zeta values as iterated integrals.

One can also multiply such elements:

sage: Multizeta(1,0)*Multizeta(1,0)
4*I(1100) + 2*I(1010)

Back-and-forth conversion between the two classes can be done using the methods “composition” and “iterated”:

sage: (Multizeta(2)*Multizeta(3)).iterated()
6*I(11000) + 3*I(10100) + I(10010)

sage: (Multizeta(1,0)*Multizeta(1,0)).composition()
4*ζ(1,3) + 2*ζ(2,2)

Beware that the conversion between these two classes, besides exchanging the indexing by words in 0 and 1 and the indexing by compositions, also involves the sign \((-1)^w\) where \(w\) is the length of the composition and the number of \(1\) in the associated word in 0 and 1. For example, one has the equality

\[\zeta(2,3,4) = (-1)^3 I(1,0,1,0,0,1,0,0,0).\]

Approximate period map

The period map, or rather an approximation, is also available under the generic numerical approximation method:

sage: z = Multizeta(5)+6*Multizeta(2,3)
sage: z.n()
2.40979014076349
sage: z.n(prec=100)
2.4097901407634924849438423801

Behind the scene, all the numerical work is done by the PARI implementation of numerical multiple zeta values.

Searching for linear relations

All this can be used to find linear dependencies between any set of multiple zeta values. Let us illustrate this by an example.

Let us first build our sample set:

sage: Z = Multizeta
sage: L = [Z(*c) for c in [(1, 1, 4), (1, 2, 3), (1, 5), (6,)]]

Then one can compute the space of relations:

sage: M = matrix([Zc.phi_as_vector() for Zc in L])
sage: K = M.kernel(); K
Vector space of degree 4 and dimension 2 over Rational Field
Basis matrix:
[     1      0     -2   1/16]
[     0      1      6 -13/48]

and check that the first relation holds:

sage: relation = L[0]-2*L[2]+1/16*L[3]; relation
ζ(1,1,4) - 2*ζ(1,5) + 1/16*ζ(6)
sage: relation.phi()
0
sage: relation.is_zero()
True

Warning

Because this code uses an hardcoded multiplicative basis that is available up to weight 17 included, some parts will not work in larger weights, in particular the test of equality.

REFERENCES:

Brown2012(1,2,3,4,5,6,7,8,9)

Francis C. S. Brown, On the decomposition of motivic multiple zeta values, Advanced Studies in Pure Mathematics 63, 2012. Galois-Teichmuller Theory and Arithmetic Geometry.

Brown2019

Francis C. S. Brown, From the Deligne-Ihara conjecture to multiple modular values, arXiv 1904.00179

Deli2012

Pierre Deligne, Multizêtas, d’après Francis Brown, Séminaire Bourbaki, janvier 2012. http://www.bourbaki.ens.fr/TEXTES/1048.pdf

Stie2020

S. Stieberger, Periods and Superstring Amplitudes, Periods in Quantum Field Theory and Arithmetic, Springer Proceedings in Mathematics and Statistics 314, 2020

class sage.modular.multiple_zeta.All_iterated(R)

Bases: sage.combinat.free_module.CombinatorialFreeModule

Auxiliary class for multiple zeta value as generalized iterated integrals.

This is used to represent multiple zeta values as possibly divergent iterated integrals of the differential forms \(\omega_0 = dt/t\) and \(\omega_1 = dt/(t-1)\).

This means that the elements are symbols \(I(a_0 ; a_1,a_2,...a_n ; a_{n+1})\) where all arguments, including the starting and ending points can be 0 or 1.

This comes with a “regularise” method mapping to Multizetas_iterated.

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ); M
Space of motivic multiple zeta values as general iterated integrals
over Rational Field
sage: M((0,1,0,1))
I(0;10;1)
sage: x = M((1,1,0,0)); x
I(1;10;0)
sage: x.regularise()
-I(10)

class Element

Bases: sage.modules.with_basis.indexed_element.IndexedFreeModuleElement

conversion()

Conversion to the Multizetas_iterated.

This assumed that the element has been prepared.

Not to be used directly.

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,1,0,0,1))
sage: y = M(x).conversion(); y
I(100)
sage: y.parent()
Algebra of motivic multiple zeta values as convergent iterated
integrals over Rational Field

regularise()

Conversion to the Multizetas_iterated.

This is the regularisation procedure, done in several steps.

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,0,1,0,1))
sage: M(x).regularise()
-2*I(100)
sage: x = Word((0,1,1,0,1))
sage: M(x).regularise()
I(110)

sage: x = Word((1,0,1,0,0))
sage: M(x).regularise()
2*I(100)

dual()

Reverse words and exchange the letters 0 and 1.

This is the operation R4 in [Brown2012].

This should be used only when \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,0,1,1,1))
sage: y = Word((0,0,1,0,1))
sage: M.dual(M(x)+5*M(y))
5*I(0;010;1) - I(0;001;1)

dual_on_basis(w)

Reverse the word and exchange the letters 0 and 1.

This is the operation R4 in [Brown2012].

This should be used only when \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,0,1,0,1))
sage: M.dual_on_basis(x)
I(0;010;1)
sage: x = Word((0,1,0,1,1))
sage: M.dual_on_basis(x)
-I(0;010;1)

expand()

Perform an expansion as a linear combination.

This is the operation R2 in [Brown2012].

This should be used only when \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,0,1,0,1))
sage: y = Word((0,0,1,1,1))
sage: M.expand(M(x)+2*M(y))
-2*I(0;110;1) - 2*I(0;101;1) - 2*I(0;100;1)
sage: M.expand(M([0,1,1,0,1]))
I(0;110;1)
sage: M.expand(M([0,1,0,0,1]))
I(0;100;1)

expand_on_basis(w)

Perform an expansion as a linear combination.

This is the operation R2 in [Brown2012].

This should be used only when \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((0,0,1,0,1))
sage: M.expand_on_basis(x)
-2*I(0;100;1)

sage: x = Word((0,0,0,1,0,1,0,0,1))
sage: M.expand_on_basis(x)
6*I(0;1010000;1) + 6*I(0;1001000;1) + 3*I(0;1000100;1)

sage: x = Word((0,1,1,0,1))
sage: M.expand_on_basis(x)
I(0;110;1)

reversal()

Reverse words if necessary.

This is the operation R3 in [Brown2012].

This reverses the word only if \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((1,0,1,0,0))
sage: y = Word((0,0,1,1,1))
sage: M.reversal(M(x)+2*M(y))
2*I(0;011;1) - I(0;010;1)

reversal_on_basis(w)

Reverse the word if necessary.

This is the operation R3 in [Brown2012].

This reverses the word only if \(a_0 = 0\) and \(a_{n+1} = 1\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import All_iterated
sage: M = All_iterated(QQ)
sage: x = Word((1,0,1,0,0))
sage: M.reversal_on_basis(x)
-I(0;010;1)
sage: x = Word((0,0,1,1,1))
sage: M.reversal_on_basis(x)
I(0;011;1)

sage.modular.multiple_zeta.D_on_compo(k, compo)

Return the value of the operator \(D_k\) on a multiple zeta value.

This is now only used as a place to keep many doctests.

INPUT:

• k – an odd integer

• compo – a composition

EXAMPLES:

sage: from sage.modular.multiple_zeta import D_on_compo
sage: D_on_compo(3,(2,3))
3*I(100) # I(10)

sage: D_on_compo(3,(4,3))
I(100) # I(1000)
sage: D_on_compo(5,(4,3))
10*I(10000) # I(10)

sage: [D_on_compo(k, [3,5]) for k in (3,5,7)]
[0, -5*I(10000) # I(100), 0]

sage: [D_on_compo(k, [3,7]) for k in (3,5,7,9)]
[0, -6*I(10000) # I(10000), -14*I(1000000) # I(100), 0]

sage: D_on_compo(3,(4,3,3))
-I(100) # I(1000100)
sage: D_on_compo(5,(4,3,3))
-10*I(10000) # I(10100)
sage: D_on_compo(7,(4,3,3))
4*I(1001000) # I(100) + 2*I(1000100) # I(100)

sage: [D_on_compo(k,(1,3,1,3,1,3)) for k in range(3,10,2)]
[0, 0, 0, 0]

sage.modular.multiple_zeta.F_prod(a, b)

Return the associative and commutative product of a and b.

INPUT:

• a, b – two elements of the F ring

OUTPUT:

an element of the F ring

EXAMPLES:

sage: from sage.modular.multiple_zeta import F_ring_generator, F_prod
sage: f2 = F_ring_generator(2)
sage: f3 = F_ring_generator(3)
sage: F_prod(f2,f2)
f2^2*Z[]
sage: F_prod(f2,f3)
f2*Z[f3]
sage: F_prod(f3,f3)
2*Z[f3,f3]
sage: F_prod(3*f2+5*f3,6*f2+f3)
18*f2^2*Z[] + 33*f2*Z[f3] + 10*Z[f3,f3]

sage.modular.multiple_zeta.F_ring(basering, N=18)

Return the free Zinbiel algebra on many generators \(f_3,f_5,\dots\) over the polynomial ring with generator \(f_2\).

For the moment, only with a finite number of variables.

INPUT:

• N – an integer (default 18), upper bound for indices of generators

EXAMPLES:

sage: from sage.modular.multiple_zeta import F_ring
sage: F_ring(QQ)
Free Zinbiel algebra on generators (Z[f3], Z[f5], Z[f7], Z[f9], ...)
over Univariate Polynomial Ring in f2 over Rational Field

sage.modular.multiple_zeta.F_ring_generator(i)

Return the generator of the F ring over \(\QQ\).

INPUT:

• i – a nonnegative integer

If i is odd, this returns a single generator \(f_i\) of the free shuffle algebra.

Otherwise, it returns an appropriate multiple of a power of \(f_2\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import F_ring_generator
sage: [F_ring_generator(i) for i in range(2,8)]
[f2*Z[], Z[f3], 2/5*f2^2*Z[], Z[f5], 8/35*f2^3*Z[], Z[f7]]

sage.modular.multiple_zeta.Multizeta(*args)

Common entry point for multiple zeta values.

If the argument is a sequence of 0 and 1, an element of Multizetas_iterated will be returned.

Otherwise, an element of Multizetas will be returned.

The base ring is \(\QQ\).

EXAMPLES:

sage: Z = Multizeta
sage: Z(1,0,1,0)
I(1010)
sage: Z(3,2,2)
ζ(3,2,2)

class sage.modular.multiple_zeta.MultizetaValues

Bases: sage.structure.unique_representation.UniqueRepresentation

Custom cache for numerical values of multiple zetas.

Computations are performed using the PARI/GP pari:zetamultall (for the cache) and pari:zetamult (for indices/precision outside of the cache).

EXAMPLES:

sage: from sage.modular.multiple_zeta import MultizetaValues
sage: M = MultizetaValues()

sage: M((1,2))
1.202056903159594285399738161511449990764986292340...
sage: parent(M((2,3)))
Real Field with 1024 bits of precision

sage: M((2,3), prec=53)
0.228810397603354
sage: parent(M((2,3), prec=53))
Real Field with 53 bits of precision

sage: M((2,3), reverse=False) == M((3,2))
True

sage: M((2,3,4,5))
2.9182061974731261426525583710934944310404272413...e-6
sage: M((2,3,4,5), reverse=False)
0.0011829360522243605614404196778185433287651...

sage: parent(M((2,3,4,5)))
Real Field with 1024 bits of precision
sage: parent(M((2,3,4,5), prec=128))
Real Field with 128 bits of precision

pari_eval(index)

reset(max_weight=8, prec=1024)

Reset the cache to its default values or to given arguments.

update(max_weight, prec)

Compute and store more values if needed.

class sage.modular.multiple_zeta.Multizetas(R)

Bases: sage.combinat.free_module.CombinatorialFreeModule

Main class for the algebra of multiple zeta values.

The convention is chosen so that \(\zeta(1,2)\) is convergent.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = M((2,))
sage: y = M((4,3))
sage: x+5*y
ζ(2) + 5*ζ(4,3)
sage: x*y
6*ζ(1,4,4) + 8*ζ(1,5,3) + 3*ζ(2,3,4) + 4*ζ(2,4,3) + 3*ζ(3,2,4)
+ 2*ζ(3,3,3) + 6*ζ(4,1,4) + 3*ζ(4,2,3) + ζ(4,3,2)

class Element

Bases: sage.modules.with_basis.indexed_element.IndexedFreeModuleElement

is_zero()

Return whether this element is zero.

EXAMPLES:

sage: M = Multizeta

sage: (4*M(2,3) + 6*M(3,2) - 5*M(5)).is_zero()
True
sage: (3*M(4) - 4*M(2,2)).is_zero()
True
sage: (4*M(2,3) + 6*M(3,2) + 3*M(4) - 5*M(5) - 4*M(2,2)).is_zero()
True

sage: (4*M(2,3) + 6*M(3,2) - 4*M(5)).is_zero()
False
sage: (M(4) - M(2,2)).is_zero()
False
sage: (4*M(2,3) + 6*M(3,2) + 3*M(4) - 4*M(5) - 4*M(2,2)).is_zero()
False

iterated()

Convert to the algebra of iterated integrals.

Beware that this conversion involves signs.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = M((2,3,4))
sage: x.iterated()
-I(101001000)

numerical_approx(prec=None, digits=None, algorithm=None)

Return a numerical value for this element.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M(Word((3,2))).n()  # indirect doctest
0.711566197550572
sage: parent(M(Word((3,2))).n())
Real Field with 53 bits of precision

sage: (M((3,)) * M((2,))).n(prec=80)
1.9773043502972961181971
sage: M((1,2)).n(70)
1.2020569031595942854

sage: M((3,)).n(digits=10)
1.202056903

If you plan to use intensively numerical approximation at high precision, you might want to add more values and/or accuracy to the cache:

sage: from sage.modular.multiple_zeta import MultizetaValues
sage: M = MultizetaValues()
sage: M.update(max_weight=9, prec=2048)
sage: M
Cached multiple zeta values at precision 2048 up to weight 9
sage: M.reset()  # restore precision for the other doctests

phi()

Return the image of self by the morphism phi.

This sends multiple zeta values to the algebra F_ring().

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M((1,2)).phi()
Z[f3]

phi_as_vector()

Return the image of self by the morphism phi as a vector.

The morphism phi sends multiple zeta values to the algebra F_ring(). Then the image is expressed as a vector in a fixed basis of one graded component of this algebra.

This is only defined for homogeneous elements.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M((3,2)).phi_as_vector()
(9/2, -2)
sage: M(0).phi_as_vector()
()

simplify()

Gather terms using the duality relations.

This can help to lower the number of monomials.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: z = 3*M((3,)) + 5*M((1,2))
sage: z.simplify()
8*ζ(3)

simplify_full(basis=None)

Rewrite the term in a given basis.

INPUT:

• basis (optional) - either None or a function such that basis(d) is a basis of the weight d multiple zeta values. If None, the Hoffman basis is used.

EXAMPLES:

sage: z = Multizeta(5) + Multizeta(1,4) + Multizeta(3,2) - 5 * Multizeta(2,3)
sage: z.simplify_full()
-22/5*ζ(2,3) + 12/5*ζ(3,2)
sage: z.simplify_full(basis=z.parent().basis_filtration)
18*ζ(1,4) - ζ(5)

sage: z == z.simplify_full() == z.simplify_full(basis=z.parent().basis_filtration)
True

Be careful, that this does not optimize the number of terms:

sage: Multizeta(7).simplify_full()
352/151*ζ(2,2,3) + 672/151*ζ(2,3,2) + 528/151*ζ(3,2,2)

single_valued()

Return the single-valued version of self.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = M((2,))
sage: x.single_valued()
0
sage: x = M((3,))
sage: x.single_valued()
2*ζ(3)
sage: x = M((5,))
sage: x.single_valued()
2*ζ(5)
sage: x = M((2,3))
sage: x.single_valued()
-11*ζ(5)

sage: Z = Multizeta
sage: Z(3,5).single_valued() == -10*Z(3)*Z(5)
True
sage: Z(5,3).single_valued() == 14*Z(3)*Z(5)
True

algebra_generators(n)

Return a set of multiplicative generators in weight n.

This is obtained from hardcoded data, available only up to weight 17.

INPUT:

• n – an integer

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.algebra_generators(5)
[ζ(5)]
sage: M.algebra_generators(8)
[ζ(3,5)]

basis_brown(n)

Return a basis of the algebra of multiple zeta values in weight n.

It was proved by Francis Brown that this is a basis of motivic multiple zeta values.

This is made of all \(\zeta(n_1, ..., n_r)\) with parts in {2,3}.

INPUT:

• n – an integer

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.basis_brown(3)
[ζ(3)]
sage: M.basis_brown(4)
[ζ(2,2)]
sage: M.basis_brown(5)
[ζ(3,2), ζ(2,3)]
sage: M.basis_brown(6)
[ζ(3,3), ζ(2,2,2)]

basis_data(basering, n)

Return an iterator for a basis in weight n.

This is obtained from hardcoded data, available only up to weight 17.

INPUT:

• n – an integer

EXAMPLES:

sage: M = Multizetas(QQ)
sage: list(M.basis_data(QQ, 4))
[4*ζ(1,3) + 2*ζ(2,2)]

basis_filtration(d, reverse=False)

Return a module basis of the homogeneous components of weight d compatible with the length filtration.

INPUT:

• d – (non-negative integer) the weight

• reverse – (boolean, default False) change the ordering of compositions

EXAMPLES:

sage: M = Multizetas(QQ)

sage: M.basis_filtration(5)
[ζ(5), ζ(1,4)]
sage: M.basis_filtration(6)
[ζ(6), ζ(1,5)]
sage: M.basis_filtration(8)
[ζ(8), ζ(1,7), ζ(2,6), ζ(1,1,6)]
sage: M.basis_filtration(8, reverse=True)
[ζ(8), ζ(6,2), ζ(5,3), ζ(5,1,2)]

sage: M.basis_filtration(0)
[ζ()]
sage: M.basis_filtration(1)
[]

degree_on_basis(w)

Return the degree of the monomial w.

This is the sum of terms in w.

INPUT:

• w – a composition

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = (2,3)
sage: M.degree_on_basis(x)  # indirect doctest
5

half_product(w1, w2)

Compute half of the product of two elements.

This comes from half of the shuffle product.

Warning

This is not a motivic operation.

INPUT:

• w1, w2 – elements

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.half_product(M([2]),M([2]))
2*ζ(1,3) + ζ(2,2)

iterated()

Convert to the algebra of iterated integrals.

This is also available as a method of elements.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = M((3,2))
sage: M.iterated(3*x)
3*I(10010)
sage: x = M((2,3,2))
sage: M.iterated(4*x)
-4*I(1010010)

iterated_on_basis(w)

Convert to the algebra of iterated integrals.

Beware that this conversion involves signs in our chosen convention.

INPUT:

• w – a word

EXAMPLES:

sage: M = Multizetas(QQ)
sage: x = M.basis().keys()((3,2))
sage: M.iterated_on_basis(x)
I(10010)
sage: x = M.basis().keys()((2,3,2))
sage: M.iterated_on_basis(x)
-I(1010010)

one_basis()

Return the index of the unit for the algebra.

This is the empty word.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.one_basis()
word:

phi()

Return the morphism phi.

This sends multiple zeta values to the algebra F_ring(), which is a shuffle algebra in odd generators \(f_3,f_5,f_7,\dots\) over the polynomial ring in one variable \(f_2\).

This is a ring isomorphism, that depends on the choice of a multiplicative basis for the ring of motivic multiple zeta values. Here we use one specific hardcoded basis.

For the precise definition of phi by induction, see [Brown2012].

EXAMPLES:

sage: M = Multizetas(QQ)
sage: m = Multizeta(2,2) + 2*Multizeta(1,3); m
2*ζ(1,3) + ζ(2,2)
sage: M.phi(m)
1/2*f2^2*Z[]

sage: Z = Multizeta
sage: B5 = [3*Z(1,4) + 2*Z(2,3) + Z(3,2), 3*Z(1,4) + Z(2,3)]
sage: [M.phi(b) for b in B5]
[f2*Z[f3] - 1/2*Z[f5], 1/2*Z[f5]]

product_on_basis(w1, w2)

Compute the product of two monomials.

This is done by converting to iterated integrals and using the shuffle product.

INPUT:

• w1, w2 – compositions

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.product_on_basis([2],[2])
4*ζ(1,3) + 2*ζ(2,2)
sage: x = M((2,))
sage: x*x
4*ζ(1,3) + 2*ζ(2,2)

some_elements()

Return some elements of the algebra.

EXAMPLES:

sage: M = Multizetas(QQ)
sage: M.some_elements()
(ζ(), ζ(2), ζ(3), ζ(4), ζ(1,2))

class sage.modular.multiple_zeta.Multizetas_iterated(R)

Bases: sage.combinat.free_module.CombinatorialFreeModule

Secondary class for the algebra of multiple zeta values.

This is used to represent multiple zeta values as iterated integrals of the differential forms \(\omega_0 = dt/t\) and \(\omega_1 = dt/(t-1)\).

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ); M
Algebra of motivic multiple zeta values as convergent iterated
integrals over Rational Field
sage: M((1,0))
I(10)
sage: M((1,0))**2
4*I(1100) + 2*I(1010)
sage: M((1,0))*M((1,0,0))
6*I(11000) + 3*I(10100) + I(10010)

D_on_basis(k, w)

Return the action of the operator \(D_k\) on the monomial w.

This is one main tool in the procedure that allows to map the algebra of multiple zeta values to the F Ring.

INPUT:

• k – an odd integer, at least 3

• w – a word in 0 and 1

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M.D_on_basis(3,(1,1,1,0,0))
I(110) # I(10) + 2*I(100) # I(10)

sage: M.D_on_basis(3,(1,0,1,0,0))
3*I(100) # I(10)
sage: M.D_on_basis(5,(1,0,0,0,1,0,0,1,0,0))
10*I(10000) # I(10100)

class Element

Bases: sage.modules.with_basis.indexed_element.IndexedFreeModuleElement

composition()

Convert to the algebra of multiple zeta values of composition style.

This means the algebra Multizetas.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = M((1,0,1,0))
sage: x.composition()
ζ(2,2)
sage: x = M((1,0,1,0,0))
sage: x.composition()
ζ(2,3)
sage: x = M((1,0,1,0,0,1,0))
sage: x.composition()
-ζ(2,3,2)

coproduct()

Return the coproduct of self.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: a = 3*Multizeta(1,3) + Multizeta(2,3)
sage: a.iterated().coproduct()
3*I() # I(1100) + I() # I(10100) + I(10100) # I() + 3*I(100) # I(10)

is_zero()

Return whether this element is zero.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M(0).is_zero()
True
sage: M(1).is_zero()
False
sage: (M((1,1,0)) - -M((1,0,0))).is_zero()
True

numerical_approx(prec=None, digits=None, algorithm=None)

Return a numerical approximation as a sage real.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = M((1,0,1,0))
sage: y = M((1, 0, 0))
sage: (3*x+y).n()  # indirect doctest
1.23317037269047

phi()

Return the image of self by the morphism phi.

This sends multiple zeta values to the algebra F_ring().

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M((1,1,0)).phi()
Z[f3]

simplify()

Gather terms using the duality relations.

This can help to lower the number of monomials.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: z = 4*M((1,0,0)) + 3*M((1,1,0))
sage: z.simplify()
I(100)

composition()

Convert to the algebra of multiple zeta values of composition style.

This means the algebra Multizetas.

This is also available as a method of elements.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = M((1,0))
sage: M.composition(2*x)
-2*ζ(2)
sage: x = M((1,0,1,0,0))
sage: M.composition(x)
ζ(2,3)

composition_on_basis(w, basering=None)

Convert to the algebra of multiple zeta values of composition style.

INPUT:

• basering – optional choice of the coefficient ring

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = Word((1,0,1,0,0))
sage: M.composition_on_basis(x)
ζ(2,3)
sage: x = Word((1,0,1,0,0,1,0))
sage: M.composition_on_basis(x)
-ζ(2,3,2)

coproduct()

Return the motivic coproduct of an element.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: a = 3*Multizeta(1,4) + Multizeta(2,3)
sage: M.coproduct(a.iterated())
3*I() # I(11000) + I() # I(10100) + 3*I(11000) # I()
+ I(10100) # I()

coproduct_on_basis(w)

Return the motivic coproduct of a monomial.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M.coproduct_on_basis([1,0])
I() # I(10)

sage: M.coproduct_on_basis((1,0,1,0))
I() # I(1010)

degree_on_basis(w)

Return the degree of the monomial w.

This is the length of the word.

INPUT:

• w – a word in 0 and 1

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = Word((1,0,1,0,0))
sage: M.degree_on_basis(x)
5

dual_on_basis(w)

Return the order of the word and exchange letters 0 and 1.

This is an involution.

INPUT:

• w – a word in 0 and 1

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = Word((1,0,1,0,0))
sage: M.dual_on_basis(x)
-I(11010)

half_product()

Compute half of the product of two elements.

This is half of the shuffle product.

Warning

This is not a motivic operation.

INPUT:

• w1, w2 – elements

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = M(Word([1,0]))
sage: M.half_product(x,x)
2*I(1100) + I(1010)

half_product_on_basis(w1, w2)

Compute half of the product of two monomials.

This is half of the shuffle product.

Warning

This is not a motivic operation.

INPUT:

• w1, w2 – monomials

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = Word([1,0])
sage: M.half_product_on_basis(x,x)
2*I(1100) + I(1010)

one_basis()

Return the index of the unit for the algebra.

This is the empty word.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M.one_basis()
word:

phi()

Return the morphism phi.

This sends multiple zeta values to the algebra F_ring().

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: m = Multizeta(1,0,1,0) + 2*Multizeta(1,1,0,0); m
2*I(1100) + I(1010)
sage: M.phi(m)
1/2*f2^2*Z[]

sage: Z = Multizeta
sage: B5 = [3*Z(1,4) + 2*Z(2,3) + Z(3,2), 3*Z(1,4) + Z(2,3)]
sage: [M.phi(b.iterated()) for b in B5]
[f2*Z[f3] - 1/2*Z[f5], 1/2*Z[f5]]

sage: B6 = [6*Z(1,5) + 3*Z(2,4) + Z(3,3),
....:  6*Z(1,1,4) + 4*Z(1,2,3) + 2*Z(1,3,2) + 2*Z(2,1,3) + Z(2,2,2)]
sage: [M.phi(b.iterated()) for b in B6]
[Z[f3,f3], 1/6*f2^3*Z[]]

phi_extended(w)

Return the image of the monomial w by the morphism phi.

INPUT:

• w – a word in 0 and 1

OUTPUT:

an element in the algebra F_ring()

The coefficients are in the base ring.

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: M.phi_extended((1,0))
-f2*Z[]
sage: M.phi_extended((1,0,0))
-Z[f3]
sage: M.phi_extended((1,1,0))
Z[f3]
sage: M.phi_extended((1,0,1,0,0))
3*f2*Z[f3] - 11/2*Z[f5]

More complicated examples:

sage: from sage.modular.multiple_zeta import composition_to_iterated
sage: M.phi_extended(composition_to_iterated((4,3)))
2/5*f2^2*Z[f3] + 10*f2*Z[f5] - 18*Z[f7]

sage: M.phi_extended(composition_to_iterated((3,4)))
-10*f2*Z[f5] + 17*Z[f7]

sage: M.phi_extended(composition_to_iterated((4,2)))
10/21*f2^3*Z[] - 2*Z[f3,f3]
sage: M.phi_extended(composition_to_iterated((3,5)))
-5*Z[f5,f3]
sage: M.phi_extended(composition_to_iterated((3,7)))
-6*Z[f5,f5] - 14*Z[f7,f3]

sage: M.phi_extended(composition_to_iterated((3,3,2)))
-793/875*f2^4*Z[] - 4*f2*Z[f3,f3] + 9*Z[f3,f5] - 9/2*Z[f5,f3]

product_on_basis(w1, w2)

Compute the product of two monomials.

This is the shuffle product.

INPUT:

• w1, w2 – words in 0 and 1

EXAMPLES:

sage: from sage.modular.multiple_zeta import Multizetas_iterated
sage: M = Multizetas_iterated(QQ)
sage: x = Word([1,0])
sage: M.product_on_basis(x,x)
4*I(1100) + 2*I(1010)
sage: y = Word([1,1,0])
sage: M.product_on_basis(y,x)
I(10110) + 3*I(11010) + 6*I(11100)

sage.modular.multiple_zeta.Values = Cached multiple zeta values at precision 1024 up to weight 8

sage.modular.multiple_zeta.basis_f_iterator(n)

Return an iterator over decompositions of n using 2,3,5,7,9,....

The means that each term is made of a power of 2 and a composition of the remaining integer with parts in (3,5,7,...)

INPUT:

• n – an integer

Each term is returned as a pair (integer, word) where the integer is the exponent of 2.

EXAMPLES:

sage: from sage.modular.multiple_zeta import basis_f_iterator
sage: [list(basis_f_iterator(i)) for i in range(2,9)]
[[(1, word: )],
 [(0, word: f3)],
 [(2, word: )],
 [(0, word: f5), (1, word: f3)],
 [(0, word: f3,f3), (3, word: )],
 [(0, word: f7), (1, word: f5), (2, word: f3)],
 [(0, word: f5,f3), (0, word: f3,f5), (1, word: f3,f3), (4, word: )]]
sage: list(basis_f_iterator(11))
[(0, word: f11),
 (0, word: f5,f3,f3),
 (0, word: f3,f5,f3),
 (0, word: f3,f3,f5),
 (1, word: f9),
 (1, word: f3,f3,f3),
 (2, word: f7),
 (3, word: f5),
 (4, word: f3)]

sage.modular.multiple_zeta.basis_f_odd_iterator(n)

Return an iterator over compositions of n with parts in (3,5,7,...)

INPUT:

• n – an integer

EXAMPLES:

sage: from sage.modular.multiple_zeta import basis_f_odd_iterator
sage: [list(basis_f_odd_iterator(i)) for i in range(2,9)]
[[], [(3,)], [], [(5,)], [(3, 3)], [(7,)], [(5, 3), (3, 5)]]
sage: list(basis_f_odd_iterator(14))
[(11, 3),
 (5, 3, 3, 3),
 (3, 5, 3, 3),
 (3, 3, 5, 3),
 (9, 5),
 (3, 3, 3, 5),
 (7, 7),
 (5, 9),
 (3, 11)]

sage.modular.multiple_zeta.coeff_phi(w)

Return the coefficient of \(f_k\) in the image by phi.

INPUT:

• w – a word in 0 and 1 with \(k\) letters (where \(k\) is odd)

OUTPUT:

a rational number

EXAMPLES:

sage: from sage.modular.multiple_zeta import coeff_phi
sage: coeff_phi(Word([1,0,0]))
-1
sage: coeff_phi(Word([1,1,0]))
1
sage: coeff_phi(Word([1,1,0,1,0]))
11/2
sage: coeff_phi(Word([1,1,0,0,0,1,0]))
109/16

sage.modular.multiple_zeta.composition_to_iterated(w, reverse=False)

Convert a composition to a word in 0 and 1.

By default, the chosen convention maps (2,3) to (1,0,1,0,0), respecting the reading order from left to right.

The inverse map is given by iterated_to_composition().

EXAMPLES:

sage: from sage.modular.multiple_zeta import composition_to_iterated
sage: composition_to_iterated((1,2))
(1, 1, 0)
sage: composition_to_iterated((3,1,2))
(1, 0, 0, 1, 1, 0)
sage: composition_to_iterated((3,1,2,4))
(1, 0, 0, 1, 1, 0, 1, 0, 0, 0)

sage.modular.multiple_zeta.compute_u_on_basis(w)

Compute the value of u on a multiple zeta value.

INPUT:

• w – a word in 0,1

OUTPUT:

an element of F_ring() over \(\QQ\)

EXAMPLES:

sage: from sage.modular.multiple_zeta import compute_u_on_basis
sage: compute_u_on_basis((1,0,0,0,1,0))
-2*Z[f3,f3]

sage: compute_u_on_basis((1,1,1,0,0))
f2*Z[f3]

sage: compute_u_on_basis((1,0,0,1,0,0,0,0))
-5*Z[f5,f3]

sage: compute_u_on_basis((1,0,1,0,0,1,0))
11/2*f2*Z[f5]

sage: compute_u_on_basis((1,0,0,1,0,1,0,0,1,0))
11*f2*Z[f3,f5] - 75/4*Z[f3,f7] - 9*f2*Z[f5,f3] + 81/4*Z[f5,f5]
+ 75/8*Z[f7,f3]

sage.modular.multiple_zeta.compute_u_on_compo(compo)

Compute the value of the map u on a multiple zeta value.

INPUT:

• compo – a composition

OUTPUT:

an element of F_ring() over \(\QQ\)

EXAMPLES:

sage: from sage.modular.multiple_zeta import compute_u_on_compo
sage: compute_u_on_compo((2,4))
2*Z[f3,f3]
sage: compute_u_on_compo((2,3,2))
-11/2*f2*Z[f5]
sage: compute_u_on_compo((3,2,3,2))
11*f2*Z[f3,f5] - 75/4*Z[f3,f7] - 9*f2*Z[f5,f3] + 81/4*Z[f5,f5] + 75/8*Z[f7,f3]

sage.modular.multiple_zeta.coproduct_iterator(paire)

Return an iterator for terms in the coproduct.

This is an auxiliary function.

INPUT:

• paire – a pair (list of indices, end of word)

OUTPUT:

iterator for terms in the motivic coproduct

Each term is seen as a list of positions.

EXAMPLES:

sage: from sage.modular.multiple_zeta import coproduct_iterator
sage: list(coproduct_iterator(([0],[0,1,0,1])))
[[0, 1, 2, 3]]
sage: list(coproduct_iterator(([0],[0,1,0,1,1,0,1])))
[[0, 1, 2, 3, 4, 5, 6], [0, 1, 2, 6], [0, 1, 5, 6], [0, 4, 5, 6], [0, 6]]

sage.modular.multiple_zeta.dual_composition(c)

Return the dual composition of c.

This is an involution on compositions such that associated multizetas are equal.

INPUT:

• c – a composition

OUTPUT:

a composition

EXAMPLES:

sage: from sage.modular.multiple_zeta import dual_composition
sage: dual_composition([3])
(1, 2)
sage: dual_composition(dual_composition([3,4,5])) == (3,4,5)
True

sage.modular.multiple_zeta.extend_multiplicative_basis(B, n)

Extend a multiplicative basis into a basis.

This is an iterator.

INPUT:

• B – function mapping integer to list of tuples of compositions

• n – an integer

OUTPUT:

Each term is a tuple of tuples of compositions.

EXAMPLES:

sage: from sage.modular.multiple_zeta import extend_multiplicative_basis
sage: from sage.modular.multiple_zeta import B_data
sage: list(extend_multiplicative_basis(B_data,5))
[((5,),), ((3,), (2,))]
sage: list(extend_multiplicative_basis(B_data,6))
[((3,), (3,)), ((2,), (2,), (2,))]
sage: list(extend_multiplicative_basis(B_data,7))
[((7,),), ((5,), (2,)), ((3,), (2,), (2,))]

sage.modular.multiple_zeta.f_to_vector(elt)

Convert an element of F ring to a vector.

INPUT:

an homogeneous element of F_ring() over some base ring

OUTPUT:

a vector with coefficients in the base ring

See also

vector_to_f()

EXAMPLES:

sage: from sage.modular.multiple_zeta import F_ring, vector_to_f, f_to_vector
sage: F = F_ring(QQ)
sage: f2 = F.base_ring().gen()
sage: x = f2**4*F.monomial(Word([]))+f2*F.monomial(Word(['f3','f3']))
sage: f_to_vector(x)
(0, 0, 1, 1)
sage: vector_to_f(_,8)
f2^4*Z[] + f2*Z[f3,f3]

sage: x = F.monomial(Word(['f11'])); x
Z[f11]
sage: f_to_vector(x)
(1, 0, 0, 0, 0, 0, 0, 0, 0)

sage.modular.multiple_zeta.iterated_to_composition(w, reverse=False)

Convert a word in 0 and 1 to a composition.

By default, the chosen convention maps (1,0,1,0,0) to (2,3).

The inverse map is given by composition_to_iterated().

EXAMPLES:

sage: from sage.modular.multiple_zeta import iterated_to_composition
sage: iterated_to_composition([1,0,1,0,0])
(2, 3)
sage: iterated_to_composition(Word([1,1,0]))
(1, 2)
sage: iterated_to_composition(Word([1,1,0,1,1,0,0]))
(1, 2, 1, 3)

sage.modular.multiple_zeta.minimize_term(w, cf)

Return the largest among w and the dual word of w.

INPUT:

• w – a word in the letters 0 and 1

• cf – a coefficient

OUTPUT:

(word, coefficient)

The chosen order is lexicographic with 1 < 0.

If the dual word is chosen, the sign of the coefficient is changed, otherwise the coefficient is returned unchanged.

EXAMPLES:

sage: from sage.modular.multiple_zeta import minimize_term, Words10
sage: minimize_term(Words10((1,1,0)), 1)
(word: 100, -1)
sage: minimize_term(Words10((1,0,0)), 1)
(word: 100, 1)

sage.modular.multiple_zeta.phi_on_basis(L)

Compute the value of phi on the hardcoded basis.

INPUT:

a list of compositions, each composition in the hardcoded basis

This encodes a product of multiple zeta values.

OUTPUT:

an element in F_ring()

EXAMPLES:

sage: from sage.modular.multiple_zeta import phi_on_basis
sage: phi_on_basis([(3,),(3,)])
2*Z[f3,f3]
sage: phi_on_basis([(2,),(2,)])
f2^2*Z[]
sage: phi_on_basis([(2,),(3,),(3,)])
2*f2*Z[f3,f3]

sage.modular.multiple_zeta.phi_on_multiplicative_basis(compo)

Compute phi on one single multiple zeta value.

INPUT:

• compo – a composition (in the hardcoded multiplicative base)

OUTPUT:

an element in F_ring() with rational coefficients

EXAMPLES:

sage: from sage.modular.multiple_zeta import phi_on_multiplicative_basis
sage: phi_on_multiplicative_basis((2,))
f2*Z[]
sage: phi_on_multiplicative_basis((3,))
Z[f3]

sage.modular.multiple_zeta.rho_inverse(elt)

Return the image by the inverse of rho.

INPUT:

• elt – an homogeneous element of the F ring

OUTPUT:

a linear combination of multiple zeta values

EXAMPLES:

sage: from sage.modular.multiple_zeta import F_ring_generator, rho_inverse
sage: f = F_ring_generator
sage: rho_inverse(f(3))
ζ(3)
sage: rho_inverse(f(9))
ζ(9)
sage: rho_inverse(f(5)*f(3))
-1/5*ζ(3,5)

sage.modular.multiple_zeta.rho_matrix_inverse(n)

Return the matrix of the inverse of rho.

This is the matrix in the chosen bases, namely the hardcoded basis of multiple zeta values and the natural basis of the F ring.

INPUT:

• n – an integer

EXAMPLES:

sage: from sage.modular.multiple_zeta import rho_matrix_inverse
sage: rho_matrix_inverse(3)
[1]
sage: rho_matrix_inverse(8)
[-1/5    0    0    0]
[ 1/5    1    0    0]
[   0    0  1/2    0]
[   0    0    0    1]

sage.modular.multiple_zeta.vector_to_f(vec, N)

Convert back a vector to an element of the F ring.

INPUT:

a vector with coefficients in some base ring

OUTPUT:

an homogeneous element of F_ring() over this base ring

See also

f_to_vector()

EXAMPLES:

sage: from sage.modular.multiple_zeta import vector_to_f, f_to_vector
sage: vector_to_f((4,5),6)
5*f2^3*Z[] + 4*Z[f3,f3]
sage: f_to_vector(_)
(4, 5)