# The ptolemy module

## What is the ptolemy module?

This module provides tools to find boundary-unipotent representations of an oriented 3-manifold into PSL(N, C). It was used, for example, to generate the tables of representations at ptolemy.unhyperbolic.org.

The ptolemy module can use magma for the computations necessary to find the representations or it can automatically retrieve the necessary computations from a database we provide that contains the computations for all manifolds and N at ptolemy.unhyperbolic.org. In particular, the database includes the computations for all orientable census manifolds for PSL(2, C) and the examples below work without magma for these manifolds. This makes it useful for people who do not have magma (see here).

The ptolemy module is still under development. Please report bugs or email suggestions to: enischte at gmail dot com.

Examples of what the Ptolemy module can do:

- Give the equations for the reduced Ptolemy varieties to find all generically decorated and boundary-unipotent representations into SL(N, C).

- Same for representations into PSL(N, C) using Obstruction classes.

- Retrieve the exact and numerical solutions for these varieties.

- Compute the matrices for these representations exactly or numerically given a generator of or word in the fundamental group.

- Compute the traces for these matrices.

- Compute the trace field of the representation.

- Compute the boundary holonomy.

- Compute the corresponding shape parameters/cross ratios for a representation.

- Compute the volume and complex volume (volume + i Chern-Simons) for a representation.

- Compute solutions to the Ptolemy varieties using magma or sage.

- Find positively dimensional components of the Ptolemy variety.

- Find positively dimensional families of boundary-unipotent representations.

The ptolemy module tries to have powerful and flexible functionality but at the same time be easy to use. For example, we can get the volumes of boundary-unipotent PSL(2, C)-representations of `m011` in just one line:

    >>> Manifold("m011").ptolemy_variety(2,'all').retrieve_solutions().volume_numerical()
    [[[-4.30211422042248 E-16, -0.942707362776931, 0.942707362776931]],
     [[4.64255370258293 E-15, 3.94215909915729 E-15, -2.78183391239608, 2.78183391239608]]]

Here, we see that `m011` has a representation that is not Galois-conjugate to the geometric representation and that has the volume 0.9427… of the Weeks manifold.

Remark: Please check your Internet connection if the above example does not work.

## Documentation

- Mathematical preliminaries
  - Boundary-unipotent
  - Obstruction class
  - SL(N, C) vs PSL(N, C)
  - Generically decorated representations
  - Reduced Ptolemy variety
  - Future work
  - References
- Step-by-step examples: Part 1
  - The Ptolemy variety for SL(N, C)
  - Using auto-completion
  - Retrieving exact solutions from the database
  - Compute the matrices for a representation
  - Compute the traces
  - Compute the trace field for a PSL(2, C)-representation
  - Compute the volume
  - Increase precision
  - Ptolemy varieties for PSL(N, C)-representations
  - A short cut for a PSL(N, C) Ptolemy variety
- Step-by-step examples: Part 2
  - The Ptolemy list type
  - Using the Ptolemy list type recursively
  - A comparison of `m003` and `m004`
  - A non-hyperbolic example
  - Flattening nested structures
  - Lack of tab-autocompletion for nested structures
  - Converting exact solutions into numerical solutions
  - Working with exact vs numerical solutions
  - Computing numerical solutions directly
  - Computing cross ratios from Ptolemy coordinates
  - The dimension of a component
- Step-by-step examples: Part 3
  - Computing solutions with magma or sage vs retrieving solutions
  - Computing the complex volume
  - Computing the matrices for a different presentation
  - Computing the images of the peripheral curves for a representation
  - Finding a witness point for a positively dimensional component of the Ptolemy variety
  - Finding non-zero dimensional families of boundary-unipotent representations
  - Representations that are the same as PSL(2, C)-representations
- Step-by-step examples: Part 4
  - The structure of an exact solution
  - Rational Univariate Representation
  - TODO
- Classes
  - PtolemyVariety
  - PtolemyCoordinates
  - CrossRatios
  - Flattenings
  - NonZeroDimensionalComponent
  - Other functions