# 41.2 Generic spaces of modular forms

Module: sage.modular.modform.space

Generic spaces of modular forms

EXAMPLES (computation of base ring): Return the base ring of this space of modular forms.

For spaces of modular forms for or , the default base ring is :

sage: ModularForms(11,2).base_ring()
Rational Field
sage: ModularForms(1,12).base_ring()
Rational Field
sage: CuspForms(Gamma1(13),3).base_ring()
Rational Field


The base ring can be explicitly specified in the constructor function.

sage: ModularForms(11,2,base_ring=GF(13)).base_ring()
Finite Field of size 13


For modular forms with character the default base ring is the field generated by the image of the character.

sage: ModularForms(DirichletGroup(13).0,3).base_ring()
Cyclotomic Field of order 12 and degree 4


For example, if the character is quadratic then the field is (if the characteristic is 0).

sage: ModularForms(DirichletGroup(13).0^6,3).base_ring()
Rational Field


An example in characteristic :

sage: ModularForms(13,3,base_ring=GF(7)).base_ring()
Finite Field of size 7


Module-level Functions

 contains_each( V, B)

Class: ModularFormsSpace

class ModularFormsSpace
A generic space of modular forms.
 ModularFormsSpace( self, group, weight, character, base_ring)

Functions: basis, change_ring, character, cuspidal_submodule, cuspidal_subspace, decomposition, echelon_basis, echelon_form, eisenstein_series, eisenstein_submodule, eisenstein_subspace, embedded_submodule, find_in_space, gen, gens, group, has_character, integral_basis, intersect, is_ambient, key, level, modular_symbols, new_submodule, new_subspace, newspaces, prec, q_echelon_basis, q_expansion_basis, q_integral_basis, set_precision, span, span_of_basis, sturm_bound, weight

 change_ring( self, R)
Change the base ring of this space of modular forms.

 character( self)
Return the Dirichlet character of this space.

sage: M = ModularForms(DirichletGroup(11).0, 3)
sage: M.character()
[zeta10]
sage: s = M.cuspidal_submodule()
sage: s.character()
[zeta10]
sage: CuspForms(DirichletGroup(11).0,3).character()
[zeta10]


 cuspidal_subspace( self)
Synonym for cuspidal_submodule.

 decomposition( self)
This function returns a list of submodules corresponding to newforms of some level dividing the level of self, such that the direct sum of the submodules equals self, if possible. The space is the image under maps to of the intersection with of the space spanned by the conjugates of , where is the base ring of self.

 echelon_basis( self)
Return a basis for self in reduced echelon form. This means that if we view the -expansions of the basis as defining rows of a matrix (with infinitely many columns), then this matrix is in reduced echelon form.

sage: M = ModularForms(Gamma0(11),4)
sage: M.echelon_basis()
[
1 + O(q^6),
q - 9*q^4 - 10*q^5 + O(q^6),
q^2 + 6*q^4 + 12*q^5 + O(q^6),
q^3 + q^4 + q^5 + O(q^6)
]
sage: M.cuspidal_subspace().echelon_basis()
[
q + 3*q^3 - 6*q^4 - 7*q^5 + O(q^6),
q^2 - 4*q^3 + 2*q^4 + 8*q^5 + O(q^6)
]


sage: M = ModularForms(SL2Z(), 12)
sage: M.echelon_basis()
[
1 + 196560*q^2 + 16773120*q^3 + 398034000*q^4 + 4629381120*q^5 + O(q^6),
q - 24*q^2 + 252*q^3 - 1472*q^4 + 4830*q^5 + O(q^6)
]


sage: M = CuspForms(Gamma0(17),4, prec=10)
sage: M.echelon_basis()
[
q + 2*q^5 - 8*q^7 - 8*q^8 + 7*q^9 + O(q^10),
q^2 - 3/2*q^5 - 7/2*q^6 + 9/2*q^7 + q^8 - 4*q^9 + O(q^10),
q^3 - 2*q^6 + q^7 - 4*q^8 - 2*q^9 + O(q^10),
q^4 - 1/2*q^5 - 5/2*q^6 + 3/2*q^7 + 2*q^9 + O(q^10)
]


 echelon_form( self)
Return a space of modular forms isomorphic to self but with basis of -expansions in reduced echelon form.

This is useful, e.g., the default basis for spaces of modular forms is rarely in echelon form, but echelon form is useful for quickly recognizing whether a -expansion is in the space.

We first illustrate two ambient spaces and their echelon forms.

sage: M = ModularForms(11)
sage: M.basis()
[
q - 2*q^2 - q^3 + 2*q^4 + q^5 + O(q^6),
1 + 12/5*q + 36/5*q^2 + 48/5*q^3 + 84/5*q^4 + 72/5*q^5 + O(q^6)
]
sage: M.echelon_form().basis()
[
1 + 12*q^2 + 12*q^3 + 12*q^4 + 12*q^5 + O(q^6),
q - 2*q^2 - q^3 + 2*q^4 + q^5 + O(q^6)
]


sage: M = ModularForms(Gamma1(6),4)
sage: M.basis()
[
q - 2*q^2 - 3*q^3 + 4*q^4 + 6*q^5 + O(q^6),
1 + O(q^6),
q - 8*q^4 + 126*q^5 + O(q^6),
q^2 + 9*q^4 + O(q^6),
q^3 + O(q^6)
]
sage: M.echelon_form().basis()
[
1 + O(q^6),
q + 94*q^5 + O(q^6),
q^2 + 36*q^5 + O(q^6),
q^3 + O(q^6),
q^4 - 4*q^5 + O(q^6)
]


We create a space with a funny basis then compute the corresponding echelon form.

sage: M = ModularForms(11,4)
sage: M.basis()
[
q + 3*q^3 - 6*q^4 - 7*q^5 + O(q^6),
q^2 - 4*q^3 + 2*q^4 + 8*q^5 + O(q^6),
1 + O(q^6),
q + 9*q^2 + 28*q^3 + 73*q^4 + 126*q^5 + O(q^6)
]
sage: F = M.span_of_basis([M.0 + 1/3*M.1, M.2 + M.3]); F.basis()
[
q + 1/3*q^2 + 5/3*q^3 - 16/3*q^4 - 13/3*q^5 + O(q^6),
1 + q + 9*q^2 + 28*q^3 + 73*q^4 + 126*q^5 + O(q^6)
]
sage: E = F.echelon_form(); E.basis()
[
1 + 26/3*q^2 + 79/3*q^3 + 235/3*q^4 + 391/3*q^5 + O(q^6),
q + 1/3*q^2 + 5/3*q^3 - 16/3*q^4 - 13/3*q^5 + O(q^6)
]


 eisenstein_subspace( self)
Synonym for eisenstein_submodule.

 find_in_space( self, f, [forms=None], [prec=None], [indep=True])
INPUT:
f -- a modular form or power series
forms -- (default: None) a specific list of modular
forms or q-expansions.
prec  -- if forms are given, compute with them to
the given precision
indep -- (default: True) whether the given list of
forms are assumed to form a basis.

OUTPUT:
A list of numbers that give f as a linear
combination of the basis for this space or
of the given forms if independent=True.


NOTE: If the list of forms is given, they do *not* have to be in self.

 group( self)
Return the congruence subgroup associated to this space of modular forms.

sage: ModularForms(Gamma0(12),4).group()
Congruence Subgroup Gamma0(12)


sage: CuspForms(Gamma1(113),2).group()
Congruence Subgroup Gamma1(113)


Note that and are replaced by .

sage: CuspForms(Gamma1(1),12).group()
Congruence Subgroup Gamma0(1)
sage: CuspForms(SL2Z(),12).group()
Congruence Subgroup Gamma0(1)


 has_character( self)
Return True if this space of modular forms has a specific character.

This is True exactly when the character() function does not return None.

A space for has trivial character, hence has a character.

sage: CuspForms(Gamma0(11),2).has_character()
True


A space for (for ) never has a specific character.

sage: CuspForms(Gamma1(11),2).has_character()
False
sage: CuspForms(DirichletGroup(11).0,3).has_character()
True


 integral_basis( self)
Return an integral basis for this space of modular forms.

In this example the integral and echelon bases are different.

sage: m = ModularForms(97,2,prec=10)
sage: s = m.cuspidal_subspace()
sage: s.integral_basis()
[
q + 2*q^7 + 4*q^8 - 2*q^9 + O(q^10),
q^2 + q^4 + q^7 + 3*q^8 - 3*q^9 + O(q^10),
q^3 + q^4 - 3*q^8 + q^9 + O(q^10),
2*q^4 - 2*q^8 + O(q^10),
q^5 - 2*q^8 + 2*q^9 + O(q^10),
q^6 + 2*q^7 + 5*q^8 - 5*q^9 + O(q^10),
3*q^7 + 6*q^8 - 4*q^9 + O(q^10)
]
sage: s.echelon_basis()
[
q + 2/3*q^9 + O(q^10),
q^2 + 2*q^8 - 5/3*q^9 + O(q^10),
q^3 - 2*q^8 + q^9 + O(q^10),
q^4 - q^8 + O(q^10),
q^5 - 2*q^8 + 2*q^9 + O(q^10),
q^6 + q^8 - 7/3*q^9 + O(q^10),
q^7 + 2*q^8 - 4/3*q^9 + O(q^10)
]


Here's another example where there is a big gap in the valuations:

sage: m = CuspForms(64,2)
sage: m.integral_basis()
[
q + O(q^6),
q^2 + O(q^6),
q^5 + O(q^6)
]


TESTS:

sage: m = CuspForms(11*2^4,2, prec=13); m
Cuspidal subspace of dimension 19 of Modular Forms space of dimension 30
for Congruence Subgroup Gamma0(176) of weight 2 over Rational Field
sage: m.integral_basis()          # takes a long time (3 or 4 seconds)
[
q + O(q^13),
q^2 + O(q^13),
q^3 + O(q^13),
q^4 + O(q^13),
q^5 + O(q^13),
q^6 + O(q^13),
q^7 + O(q^13),
q^8 + O(q^13),
q^9 + O(q^13),
q^10 + O(q^13),
q^11 + O(q^13),
q^12 + O(q^13),
O(q^13),
O(q^13),
O(q^13),
O(q^13),
O(q^13),
O(q^13),
O(q^13)
]


 is_ambient( self)
Return True if this an ambient space of modular forms.

sage: M = ModularForms(Gamma1(4),4)
sage: M.is_ambient()
True


sage: E = M.eisenstein_subspace()
sage: E.is_ambient()
False


 new_submodule( self, [p=None])
Return the new submodule of self. If p is specified, return the p-new submodule of self.

NOTE: This function should be overridden by all derived classes.

sage: M = sage.modular.modform.space.ModularFormsSpace(Gamma0(11),2,DirichletGroup(1).0,base_ring=QQ) ; M.new_submodule()
Traceback (most recent call last):
...
NotImplementedError: computation of new submodule not yet implemented


 new_subspace( self, [p=None])
Synonym for new_submodule.

 newspaces( self)
This function returns a list of submodules and , corresponding to levels dividing and integers dividing , such that self is the direct sum of these spaces, if possible. Here is by definition the image under of the new submodule of cusp forms of level , and similarly is the image of Eisenstein series.

Notes: (1) the submodules need not be stable under Hecke operators of index dividing . (2) Since self can be an arbitrary submodule, there's no guarantee any or is in self, so the return list could be empty.

 prec( self, [new_prec=None])
Return or set the default precision used for displaying -expansions of elements of this space.

INPUT:
new_prec -- positive integer (default: None)

OUTPUT:
if new_prec is None, returns the current precision.


sage: M = ModularForms(1,12)
sage: S = M.cuspidal_subspace()
sage: S.prec()
6
sage: S.basis()
[
q - 24*q^2 + 252*q^3 - 1472*q^4 + 4830*q^5 + O(q^6)
]
sage: S.prec(8)
8
sage: S.basis()
[
q - 24*q^2 + 252*q^3 - 1472*q^4 + 4830*q^5 - 6048*q^6 - 16744*q^7 + O(q^8)
]


 q_echelon_basis( self, [prec=None])
Return the echelon form of the basis of -expansions of self up to precision prec.

The -expansions are power series (not actual modular forms). The number of -expansions returned equals the dimension.

 q_expansion_basis( self, [prec=None])
Return a sequence of q-expansions for the basis of this space computed to the given input precision.

INPUT:
prec -- integer (>=0) or None


If prec is None, the prec is computed to be *at least* large enough so that each q-expansion determines the form as an element of this space.

sage: S = ModularForms(11,2).cuspidal_submodule()
sage: S.q_expansion_basis(5)
[
q - 2*q^2 - q^3 + 2*q^4 + O(q^5)
]
sage: S = ModularForms(1,24).cuspidal_submodule()
sage: S.q_expansion_basis(5)
[
q + 195660*q^3 + 12080128*q^4 + O(q^5),
q^2 - 48*q^3 + 1080*q^4 + O(q^5)
]


 q_integral_basis( self, [prec=None])
Return a -reduced echelon basis of -expansions for self.

The -expansions are power series with coefficients in ; they are not actual modular forms.

The base ring of self must be . The number of -expansions returned equals the dimension.

sage: S = CuspForms(11,2)
sage: S.q_integral_basis(5)
[
q - 2*q^2 - q^3 + 2*q^4 + O(q^5)
]


 set_precision( self, new_prec)
Set the default precision used for displaying -expansions.

INPUT:
new_prec -- positive integer


sage: M = ModularForms(Gamma0(37),2)
sage: M.set_precision(10)
sage: S = M.cuspidal_subspace()
sage: S.basis()
[
q + q^3 - 2*q^4 - q^7 - 2*q^9 + O(q^10),
q^2 + 2*q^3 - 2*q^4 + q^5 - 3*q^6 - 4*q^9 + O(q^10)
]


sage: S.set_precision(0)
sage: S.basis()
[
O(q^0),
O(q^0)
]


The precision of subspaces is the same as the precision of the ambient space.

sage: S.set_precision(2)
sage: M.basis()
[
q + O(q^2),
O(q^2),
1 + 2/3*q + O(q^2)
]


The precision must be nonnegative:

sage: S.set_precision(-1)
Traceback (most recent call last):
...
ValueError: n (=-1) must be >= 0


We do another example with nontrivial character.

sage: M = ModularForms(DirichletGroup(13).0^2)
sage: M.set_precision(10)
sage: M.cuspidal_subspace().0
q + (-zeta6 - 1)*q^2 + (2*zeta6 - 2)*q^3 + zeta6*q^4 + (-2*zeta6 + 1)*q^5 +
(-2*zeta6 + 4)*q^6 + (2*zeta6 - 1)*q^8 - zeta6*q^9 + O(q^10)


 sturm_bound( self, [M=None])
For a space M of modular forms, this function returns an integer B such that two modular forms in either self or M are equal if and only if their q-expansions are equal to precision B. If M is none, then M is set equal to self.

NOTES: Reference for the Sturm bound that we use in the definition of of this function:

J. Sturm, On the congruence of modular forms, Number theory (New York, 1984-1985), Springer, Berlin, 1987, pp. 275-280.

Useful Remark:

Kevin Buzzard pointed out to me (William Stein) in Fall 2002 that the above bound is fine for Gamma1 with character, as one sees by taking a power of . More precisely, if for first coefficients, then for first coefficents. Since the weight of is    weight, it follows that if the sturm bound for at weight(f), then has valuation large enough to be forced to be 0 at weight(f) by Sturm bound (which is valid if we choose right). Thus . Conclusion: For with fixed character, the Sturm bound is exactly the same as for . A key point is that we are finding generators for the Hecke algebra here, not -generators. So if one wants generators for the Hecke algebra over , this bound is wrong.

This bound works over any base, even a finite field. There might be much better bounds over , or for comparing two eigenforms.

 weight( self)
Return the weight of this space of modular forms.

sage: M = ModularForms(Gamma1(13),11)
sage: M.weight()
11


sage: M = ModularForms(Gamma0(997),100)
sage: M.weight()
100


sage: M = ModularForms(Gamma0(97),4)
sage: M.weight()
4
sage: M.eisenstein_submodule().weight()
4


Special Functions: __add__, __and__, __call__, __cmp__, __contains__, _compute_hecke_matrix, _compute_hecke_matrix_prime, _compute_q_expansion_basis, _has_natural_inclusion_map_to, _ModularFormsSpace__create_newspace, _ModularFormsSpace__newspace_bases, _ModularFormsSpace__normalize_prec, _ModularFormsSpace__submodule_from_subset_of_basis, _q_expansion, _q_expansion_module, _q_expansion_ring, _q_expansion_zero

 __contains__( self, x)
True if x is an element or submodule of self.

 _compute_hecke_matrix_prime( self, p, [prec=None])

sage: M = ModularForms(11,2)
sage: M._compute_hecke_matrix_prime(2)
[-2  0]
[ 0  3]


sage: M = ModularForms(11,2)
sage: M2 = M.span([M.0 + M.1])
sage: M2.hecke_matrix(2)
Traceback (most recent call last):
...
ArithmeticError: vector is not in free module


 _has_natural_inclusion_map_to( self, right)
Return true if there is a natural inclusion map from modular forms in self to modular forms in right.

INPUT:
self, right -- spaces of modular forms


 _q_expansion_module( self)
Return module spanned by coefficients of q-expansions to sufficient precision to determine elements of this space.