# The Upper Half Plane

The *upper half complex plane* is defined by ${\mathbb{H}}:= \{z\in {\mathbb{C}}\ \vert\ {\operatorname{Im}}(z) >0\}$. The group ${\operatorname{SL}}_2({\mathbb{Z}})$ acts on $H$ by fractional linear transformations. The space ${\mathbb{H}}/SL_2({\mathbb{Z}})$ is not compact; it is compactified by adding the cusps, which are points of ${\mathbb{Q}}$, together with $\infty$. Thus we define ${\mathbb{H}}^*$ to be the upper half plane union the cusps. Then ${\mathbb{H}}^*/{\operatorname{SL}}_2({\mathbb{Z}})$ is compact. Thus we define a function which will return the space of points in the upper half complex plane, together with the set of cusps.

In ${\mathbb{H}}^*$ we define two distinguished points, the elliptic points $\sqrt{-1}$ and $(1 + \sqrt{-3})/2$. In general, points constructed in ${\mathbb{H}}^*$ are allowed to come from at most quadratic extensions of ${\mathbb{Q}}$, since in this case there is a canonical embedding in ${\mathbb{C}}$.

## Creation

### `UpperHalfPlane() -> SpcHyp`

Creates a copy of the upper half complex plane, with the cusps included. As a set this consists of all complex numbers with positive imaginary part, together with all rational numbers, and the point at infinity.

### `H ! x: SpcHyp, . -> SpcHypElt`

Returns $x$ as a point in ${\mathbb{H}}$. Here $x$ can be a cusp, rational, integer, in a quadratic extension of ${\mathbb{Q}}$, or a complex number with positive imaginary part.

### `Example: Upper Half Plane Example (ex-e422b2)`

Example of creating some points in the upper half plane.

```magma
> H := UpperHalfPlaneWithCusps();
> // coerce a cusp into H:
> c := Cusps()!(1/2);
> H!c;
1/2
> // coerce an element of a quadratic extension of Q into H
> K := QuadraticField(-7);
> K<u> := QuadraticField(-7);
> H!(u+5);
5 + root(-7)
> // refer to the two distinguished elliptic points:
> H.1;
root(-1)
> H.2;
1/2 + (1/2)*root(-3)
> // Defining the names of the elliptic points when constructing H:
> H<i,rho> := UpperHalfPlaneWithCusps();
> i;
root(-1)
> rho;
1/2 + (1/2)*root(-3)

```

## Basic Attributes

### `Imaginary(z): SpcHypElt -> FldReElt`

Returns the imaginary part of the argument as an element of `RealField`.

### `Real(z): SpcHypElt -> FldReElt`

Returns the real part of the argument as an element of `RealField`.

### `IsReal(z): SpcHypElt -> BoolElt`

Returns `true` if and only if the element $z$ of the upper half plane lies on the real line (and is not the infinite cusp).

### `IsCusp(z): SpcHypElt -> BoolElt`

Returns `true` if and only if the element $z$ of the upper half plane is a cusp.

### `IsInfinite(z): SpcHypElt -> BoolElt`

Returns `true` if and only if the element $z$ of the upper half plane is the cusp at infinity.

### `IsExact(z): SpcHypElt -> BoolElt`

Returns `true` if and only if the element $z$ of the upper half plane is a cusp or has an exact value defined in a quadratic extension of the rationals.

### `ExactValue(z): SpcHypElt -> .`

For $x$ an element of the upper half plane, if $x$ is a cusp, returns the value of $x$ as an object of type `SetCspElt`; if $x$ has an exact value in a quadratic extension, returns this value, as an object of type `FldQuadElt`; otherwise returns a complex value of type `FldComElt`.

### `ComplexValue(x): SpcHypElt -> FldComElt`

```magma
Precision: RngIntElt                    Default: 
MaxValue : RngIntElt                    Default: 600
```

For $x$ an element of the upper half place, this returns $x$ as a complex number. When $x$ is the cusp at infinity, the value returned is `MaxValue + i*MaxValue`.

### `x eq y: SpcHypElt, SpcHypElt -> BoolElt`

Returns `true` if and only if the points $x$ and $y$ in the upper half plane are equal.