Function: mspolygon
Section: modular_symbols
C-Name: mspolygon
Prototype: GD0,L,
Help: mspolygon(M, {flag = 0}): M being a full modular symbol space, as given
 by msinit or an integer > 1, return an hyperbolic polygon (Farey symbol)
 attached to the group Gamma_0(N). Binary digits of flag mean: 1=normalized
 polygon, 2=also add graphical representations.
Doc: given an integer $N > 1$, return an hyperbolic polygon (Farey symbol)
 attached to the group $\Gamma_0(N)$. More precisely,

 \item its vertices are an ordered list in $\P^{1}(\Q)$, forming a system of
 representatives of cusps,

 \item its edges are hyperbolic arcs joining two consecutive vertices,

 \item given a path $(a,b)$ between two elements of $\P^{1}(\Q)$, let
 $\overline{(a,b)} = (b,a)$ be the opposite path. There is an involution $e
 \to e^*$ on the edges, where $e^*$ is $\Gamma_0(N)$ equivalent to
 $\overline{e}$, i.e. there exist $\gamma_e \in \Gamma_0(N)$ such that $e =
 \gamma_e \overline{e^*}$.

 The polygon is given by

 \item the list $E$ of its consecutive edges as matrices in $M_2(\Z)$;

 \item the permutation $A$ attached to the involution, such that
 \kbd{A[i]} is the index of $e^*$ in $E$ if $e = E[i]$ is the $i$-th edge;

 \item the list $G$ of pairing matrices between $e$ and
 $\overline{e^*}$, i.e. the matrices $\gamma_e\in \Gamma_0(N)$ such that $e =
 \gamma_e \overline{e^*}$. If $e = E[i]$, then $\gamma_e = G[i]$.
 Remark that $\gamma_{e^*}=\gamma_e^{-1}$ if $e \neq e^*$; modulo these
 trivial relations, the pairing matrices form a system of independant
 generators of $\Gamma_0(N)/\{1,-1\}$. Note that $\gamma_e$ is elliptic if and only if
 $e^* = e$.

 The above data yields a fundamental domain for $\Gamma_0(N)$ acting
 on Poincar\'e's half-plane: take the convex hull of the polygon defined by

 \item the edges in $E$ such that $e \neq e^*$ or $e^*=e$, where the pairing
 matrix $\gamma_e$ has order $2$;

 \item the edges $(r,t)$ and $(t,s)$ where the edge $e = (r,s) \in E$ is such
 that $e = e^*$ and $\gamma_e$ has order $3$ and the triangle $(r,t,s)$
 is the image of $(0,\exp(2i\pi/3), \infty)$ by some element of $PSL_2(\Q)$
 formed around the edge.

 Binary digits of flag mean:

 1: return a normalized hyperbolic polygon if set, else a polygon with
 unimodular edges (matrices of determinant $1$). A polygon is normalized
 in the sense of compact orientable surfaces if the distance $d(a,a^*)$ between
 an edge $a$ and its image by the involution $a^*$ is less than 2, with
 equality if and only if $a$ is \emph{linked} with another edge $b$
 ($a$, $b$, $a^*$ et $b^*$ appear consecutively in $E$ up to cyclic
 permutation). In particular, the vertices of all edges such that that
 $d(a,a^*) \neq 1$ (distance is 0 or 2) are all equivalent to $0$ modulo
 $\Gamma_0(N)$. The external vertices of $a a^*$ such that $d(a,a^*) = 1$ are
 also equivalent to $0$; the internal vertices $a\cap a^*$ (a single point),
 together with $0$, form a system of representatives of the cusps of
 $\Gamma_0(N)\bs \P^{1}(\Q)$. This is useful to compute the homology group
 $H_1(X_0(N),\Z)$ as it gives a symplectic basis for the intersection pairing.
 In this case, the number of parabolic matrices (trace 2) in the system of
 generators $G$ is $2(t-1)$, where $t$ is the number of non equivalent cusps
 for $\Gamma_0(N)$.

 2: add graphical representations (in LaTeX form) for the hyperbolic polygon
 in Poincar\'e's half-space and the involution $a\to a^*$ of the Farey symbol.
 The corresponding character strings can be written to file and included in a
 LaTeX document provided the preamble contains
 \kbd{\bs usepackage\obr tikz\cbr}.

 \bprog
 ? [V,A,G] = mspolygon(3);
 ? V
 %2 = [[-1, 1; -1, 0], [1, 0; 0, 1], [0, 1; -1, 1]]
 ? A
 %3 = Vecsmall([2, 1, 3])
 ? G
 %4 = [[-1, -1; 0, -1], [1, -1; 0, 1], [1, -1; 3, -2]]
 ? [V,A,G, D1,D2] = mspolygon(11,2); \\ D1 and D2 contains pictures
 ? {write("F.tex",
      "\\documentclass{article}\\usepackage{tikz}\\begin{document}"
      D1, "\n",
      D2,
      "\\end{document}");}

 ? [V1,A1] = mspolygon(6,1); \\ normalized
 ? V1
 %8 = [[-1, 1; -1, 0], [1, 0; 0, 1], [0, 1; -1, 3],
       [1, -2; 3, -5], [-2, 1; -5, 2], [1, -1; 2, -1]]
 ? A1
 %9 = Vecsmall([2, 1, 4, 3, 6, 5])

 ? [V0,A0] = mspolygon(6);  \\ not normalized V[3]^* = V[6], d(V[3],V[6]) = 3
 ? A0
 %11 = Vecsmall([2, 1, 6, 5, 4, 3])

 ? [V,A] = mspolygon(14, 1);
 ? A
 %13 = Vecsmall([2, 1, 4, 3, 6, 5, 9, 10, 7, 8])
 @eprog
 One can see from this last example that the (normalized) polygon has the form
 $$(a_1, a_1^*, a_2, a_2^*, a_3, a_3^*, a_4, a_5, a_4^*, a_5^*),$$
 that $X_0(14)$ is of genus 1 (in general the genus is the number of blocks
 of the form $aba^*b^*$), has no elliptic points ($A$ has no fixed point)
 and 4 cusps (number of blocks of the form $aa^*$ plus 1). The vertices
 of edges $a_4$ and $a_5$ all project to $0$ in $X_0(14)$: the paths $a_4$
 and $a_5$ project as loops in $X_0(14)$ and give a symplectic basis of the
 homology $H_1(X_0(14),\Z)$.
 \bprog
 ? [V,A] = mspolygon(15);
 ? apply(matdet, V) \\ all unimodular
 %2 = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
 ? [V,A] = mspolygon(15,1);
 ? apply(matdet, V) \\ normalized polygon but no longer unimodular edges
 %4 = [1, 1, 1, 1, 2, 2, 47, 11, 47, 11]
 @eprog