# Introduction

This chapter is the reference for the modular abelian varieties package in Magma. A *modular abelian variety* is an abelian variety that is a quotient of the modular Jacobian $J_1(N)$, for some integer $N$. This package provides extensive functionality for computing with such abelian varieties, including functions for enumerating and decomposing modular abelian varieties, isomorphism testing, computing exact endomorphism and homomorphism rings, doing arithmetic with finite subgroups and computing information about torsion subgroups, special values of $L$-functions and Tamagawa numbers.

Essentially none of the algorithms in this package use explicit defining equations for varieties, and as such work in a great degree of generality. For example, many even make sense for Grothendieck motives attached to modular forms, and we have included the corresponding functionality, when it makes sense.

Magma V2.11 was the first release of the modular abelian varieties package. The major drawback of the current version is that complete decomposition into simples is only implemented over the rational numbers. Thus the interesting behavior over number fields, involving extra inner twists, which leads to ${\mathbb{Q}}$-curves and associated questions, is not available (much of it is implemented, but there are some fundamental theoretical obstructions to overcome).

Our philosophy for representing modular abelian varieties is perhaps different than what you might expect, so we describe how we view an abelian subvariety $A$ over ${\mathbb{Q}}$ contained in the modular Jacobian $J_0(N)$. By the Abel-Jacobi theorem we may view $J_0(N)$ over the complex numbers as a complex vector space $V$ modulo the lattice $H_1(J_0(N),{\mathbb{Z}})=H_1(X_0(N),{\mathbb{Z}})$. An abelian subvariety $A\subset J_0(N)$ and the map $i:A\to J_0(N)$ is completely determined by giving the image of $H_1(A,{\mathbb{Q}})$ in the vector space $H_1(X_0(N),{\mathbb{Q}})$. At this point, it might appear that we have to compute lots of floating point numbers and approximate lattices in the complex numbers, but this is not the case. Instead, we use modular symbols to compute $H_1(X_0(N),{\mathbb{Z}})$ as an abstract abelian group, and use everything we can from the extensive theory of modular forms to compute things about the abelian varieties determined by subgroups of $H_1(X_0(N),{\mathbb{Z}})$ and other related abelian varieties. Note that even though we work with homology, which is associated to complex tori, the abelian variety $A$ over ${\mathbb{Q}}$ is still determined by our defining data (a certain subgroup of $H_1(X_0(N),{\mathbb{Z}})$), and our algorithms can often take advantage of this.

## Categories

Modular abelian varieties belong to the category `ModAbVar`, and the elements of modular abelian varieties belong to `ModAbVarElt`. The category `MapModAbVar` consists of homomorphisms between modular abelian varieties (sometimes only up to isogeny, i.e., with a denominator). Spaces of homomorphisms between modular abelian varieties form the category `HomModAbVar`. Finitely generated subgroups of modular abelian varieties form the category `ModAbVarSubGrp`. Homology of a modular abelian variety is in the category `ModAbVarHomol`. The $L$-series of modular abelian varieties are in `ModAbVarLSer`.

### `Example: Categories (ex-18bf29)`

We create an object of each category.

```magma
> A := JZero(11);
> Type(A);
ModAbVar
> Type(A!0);
ModAbVarElt
> Type(nIsogeny(A,2));
MapModAbVar
> Type(nTorsionSubgroup(A,2));
ModAbVarSubGrp
> Type(End(A));
HomModAbVar
> Type(Homology(A));
ModAbVarHomol
> Type(LSeries(A));
ModAbVarLSer

```

## Verbose Output

The verbosity level is set using the command `SetVerbose("ModAbVar",n)`, where `n` is $0$ (silent), $1$ (verbose), or $2$ (very verbose). The default verbose level is $0$.

Two additional verbose levels are included in this package. Level $3$ is exactly like level $1$, except instead of displaying to the screen, verbose output is appended to the file `ModAbVar-verbose.log` in the directory that Magma was run from. Verbose level $4$ is exactly like level $2$, except verbose output is appended to `ModAbVar-verbose.log`. On a UNIX-like system, use the shell command `tail -f ModAbVar-verbose.log` to watch the verbose log in another terminal.

### `Example: Verbosity (ex-d23497)`

Using `SetVerbose`, we get some information about what is happening during computations.

```magma
> SetVerbose("ModAbVar",1);   // some verbose output
> SetVerbose("ModAbVar",2);   // tons of verbose output
> SetVerbose("ModAbVar",3);   // some verbose output to ModAbVar-verbose.log
> SetVerbose("ModAbVar",4);   // tons of verbose output to ModAbVar-verbose.log

```