---
title: "The Upper Half Plane"
canonical: "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/CongruenceSubgroupsOfPSL2R/upper-plane.html"
source: "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/CongruenceSubgroupsOfPSL2R/upper-plane.md"
part: "Modular Arithmetic Geometry"
chapter: "Congruence Subgroups of ${\\operatorname{PSL}}_2({\\mathbb{R}})$"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Modular Arithmetic Geometry", "source": "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/index-modular-arithmetic-geometry.md"}
  - {"title": "Congruence Subgroups of ${\\operatorname{PSL}}_2({\\mathbb{R}})$", "source": "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/CongruenceSubgroupsOfPSL2R/index-congruence-subgroups-of-psl2-r.md"}
prev: {"title": "Elements of ${\\operatorname{PSL}}_2({\\mathbb{R}})$", "source": "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/CongruenceSubgroupsOfPSL2R/GrpPSL2Elt.md"}
next: {"title": "Action of ${\\operatorname{PSL}}_2({\\mathbb{R}})$ on the Upper Half Plane", "source": "https://docs.magma-maths.org/v2.30-1/ModularArithmeticGeometry/CongruenceSubgroupsOfPSL2R/group-action.md"}
intrinsics:
  - {"name": "UpperHalfPlane", "signature": "UpperHalfPlane() -> SpcHyp"}
  - {"name": "!", "signature": "H ! x: SpcHyp, . -> SpcHypElt"}
  - {"name": "Imaginary", "signature": "Imaginary(z): SpcHypElt -> FldReElt"}
  - {"name": "Real", "signature": "Real(z): SpcHypElt -> FldReElt"}
  - {"name": "IsReal", "signature": "IsReal(z): SpcHypElt -> BoolElt"}
  - {"name": "IsCusp", "signature": "IsCusp(z): SpcHypElt -> BoolElt"}
  - {"name": "IsInfinite", "signature": "IsInfinite(z): SpcHypElt -> BoolElt"}
  - {"name": "IsExact", "signature": "IsExact(z): SpcHypElt -> BoolElt"}
  - {"name": "ExactValue", "signature": "ExactValue(z): SpcHypElt -> ."}
  - {"name": "ComplexValue", "signature": "ComplexValue(x): SpcHypElt -> FldComElt"}
  - {"name": "eq", "signature": "x eq y: SpcHypElt, SpcHypElt -> BoolElt"}
examples:
  - "ex-e422b2"
---

# 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

<a id="function-upperhalfplane"></a>
### `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.

<a id="operation-op-spchyp"></a>
### `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.

<a id="example-ex-e422b2"></a>
### `Example: Points in the Upper Half Plane (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

<a id="function-imaginary-spchypelt"></a>
### `Imaginary(z): SpcHypElt -> FldReElt`

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

<a id="function-real-spchypelt"></a>
### `Real(z): SpcHypElt -> FldReElt`

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

<a id="function-isreal-spchypelt"></a>
### `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).

<a id="function-iscusp-spchypelt"></a>
### `IsCusp(z): SpcHypElt -> BoolElt`

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

<a id="function-isinfinite-spchypelt"></a>
### `IsInfinite(z): SpcHypElt -> BoolElt`

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

<a id="function-isexact-spchypelt"></a>
### `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.

<a id="function-exactvalue-spchypelt"></a>
### `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`.

<a id="function-complexvalue-spchypelt"></a>
### `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`.

<a id="operation-op-eq-spchypelt-spchypelt"></a>
### `x eq y: SpcHypElt, SpcHypElt -> BoolElt`

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