snappy 3.2__cp313-cp313-macosx_11_0_arm64.whl

snappy/doc/_sources/ptolemy_examples3.rst.txt

@@ -0,0 +1,301 @@
+Step-by-step examples: Part 3
+=============================
+
+.. _ptolemy-example-using-magma-sage:
+
+Computing solutions with magma or sage vs retrieving solutions
+--------------------------------------------------------------
+
+So far, we querried the database for solutions to a Ptolemy variety::
+
+    >>> p = Manifold("m011").ptolemy_variety(2)
+    >>> p.retrieve_solutions()
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/03_tetrahedra/m011__sl2_c0.magma_out ...
+    Parsing...
+    [PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0011_2': -1,
+          'c_0101_0': -1,
+          'c_0101_1': Mod(x^2 + x, x^3 + 2*x^2 + x + 1),
+	  ...
+          's_3_2': 1},
+         is_numerical = False, ...)]
+
+We can use ``compute_solutions`` instead of ``retrieve_solutions`` to actually compute the solutions ourselves (for example, for a non-census triangulation not in the database). Currently, we support two engines: 
+
+* `sage <http://www.sagemath.org/>`_ (which is free, but can only solve a fairly limited number of Ptolemy varieties)
+* `magma <http://magma.maths.usyd.edu.au/magma/>`_
+
+If you are inside sage::
+
+    >>> p = Manifold("m011").ptolemy_variety(2)
+    >>> p.compute_solutions(engine = 'sage')
+    [PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0011_2': -1,
+          'c_0101_0': -1,
+          'c_0101_1': Mod(x^2 + x, x^3 + 2*x^2 + x + 1),
+	  ...
+          's_3_2': 1},
+         is_numerical = False, ...)]
+
+If you have magma installed::
+
+    >>> p = Manifold("m011").ptolemy_variety(2)
+    >>> p.compute_solutions(engine = 'magma', verbose = True)
+    Writing to file: /tmp/tmppNSc8S/m011__sl2_c0.magma
+    Magma's output in: /tmp/tmppNSc8S/m011__sl2_c0.magma_out
+    Command: ulimit -m 732421; echo | magma "/tmp/tmppNSc8S/m011__sl2_c0.magma" > "/tmp/tmppNSc8S/m011__sl2_c0.magma_out"
+    Starting magma...
+    magma finished.
+    Parsing magma result...
+    [PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0011_2': -1,
+          'c_0101_0': -1,
+          'c_0101_1': Mod(x^2 + x, x^3 + 2*x^2 + x + 1),
+	  ...
+          's_3_2': 1},
+         is_numerical = False, ...)]
+
+To get an idea of what Ptolemy varieties magma can still handle, have a look at the `database <http://ptolemy.unhyperbolic.org/html/summary.html>`_: for *N* = 2, the computations up to 12 tetrahedra only took 
+
+**Remark:** The magma engine is not expected to work under windows. It will also fail if magma is not installed or the magma executable cannot be found. The ptolemy module creates a temporary file (``m011__sl2_c0`` here) and also gives the command it tried to run to process the file through magma. If you believe that magma is installed correctly on your system but encounter an error, you can try to run the command yourself to understand better what is going on. Feel free to report a bug (to enischte at gmail dot com) including the temporary files (``m011__sl2_c0`` and ``m011__sl2_c0.out`` here) and any other error messages.
+
+**Remark:** If no engine is specified, it is assumed to be sage when used inside sage and magma instead.
+
+.. _ptolemy-example-complex-volume:
+
+Computing the complex volume
+----------------------------
+
+Similar to ``volume_numerical``, we can compute the complex volume (volume + i Chern-Simons) for all representations (that are :ref:`generically decorated <ptolemy-generically-decorated>`).
+
+Here is an example computing the solutions to the Ptolemy variety ourselves::
+
+    >>> Manifold("m011").ptolemy_variety(2,'all').compute_solutions().complex_volume_numerical()
+    [[[-4.30211422042248 E-16 + 0.725471193740844*I,
+       -0.942707362776931 + 0.459731436553693*I,
+       0.942707362776931 + 0.459731436553693*I]],
+     [[4.64255370258293 E-15 + 0.680993020093457*I,
+       3.94215909915729 E-15 + 0.312682687518267*I,
+       -2.78183391239608 - 0.496837853805869*I,
+       2.78183391239608 - 0.496837853805869*I]]]
+
+And here the same example retrieving solutions from the database::
+
+    >>> Manifold("m011").ptolemy_variety(2,'all').retrieve_solutions().complex_volume_numerical()
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/03_tetrahedra/m011__sl2_c0.magma_out ...
+    Parsing...
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/03_tetrahedra/m011__sl2_c1.magma_out ...
+    Parsing...
+    [[[-4.30211422042248 E-16 + 0.725471193740844*I,
+    ...
+       2.78183391239608 - 0.496837853805869*I]]]
+
+.. _ptolemy-detailed-example-matrices:
+
+Computing the matrices for a different presentation
+---------------------------------------------------
+
+The :py:meth:`~snappy.Triangulation.fundamental_group` method of a SnapPy triangulation can yield different presentations by supplying  optional arguments such as ``simplify_presentation`` and ``minimize_number_of_generators``. If we have a word in one of these presentations and want to evaluate its image under the representation, we need to supply the presentation as follows::
+
+    >>> M=Manifold("m003")
+    >>> sol = M.ptolemy_variety(2).retrieve_solutions()[0]
+    >>> G = M.fundamental_group(simplify_presentation = False)
+    >>> sol.evaluate_word('a', G)
+
+Again, we can check that the representation actually assigns the identity to all relators:
+
+    >>> G
+    Generators:
+       a,b,c
+    Relators:
+       BCaC
+       AbCbA
+    >>> sol.evaluate_word('AbCbA', G)
+    [[Mod(1, x^2 - x - 1), 0], [0, Mod(1, x^2 - x - 1)]]
+    >>> for relator in G.relators():
+    ...     print(sol.evaluate_word(relator, G))
+    [[Mod(1, x^2 - x - 1), 0], [0, Mod(1, x^2 - x - 1)]]
+    [[Mod(1, x^2 - x - 1), 0], [0, Mod(1, x^2 - x - 1)]]
+  
+
+.. _ptolemy-example-boundary-holonomy:
+
+Computing the images of the peripheral curves for a representation
+------------------------------------------------------------------
+
+The object returned by :py:meth:`~snappy.Triangulation.fundamental_group` also contains words for the peripheral curves of a manifold. We can compute the corresponding matrices::
+
+    >>> M = Manifold("m003")
+    >>> G = M.fundamental_group()
+    >>> sol = M.ptolemy_variety(2,1).retrieve_solutions()[0]
+    >>> for i, cusp_curves in enumerate(G.peripheral_curves()):
+    ...     print("Cusp %d:" % i)
+    ...     for cusp_curve in cusp_curves:
+    ...         print(sol.evaluate_word(cusp_curve, G))
+    Cusp 0:
+    [[Mod(2*x - 3, x^2 + x + 1), Mod(2*x, x^2 + x + 1)], [Mod(6, x^2 + x + 1), Mod(-2*x + 1, x^2 + x + 1)]]
+    [[Mod(-2*x - 5, x^2 + x + 1), Mod(-2, x^2 + x + 1)], [Mod(6*x + 6, x^2 + x + 1), Mod(2*x + 3, x^2 + x + 1)]]    
+
+**Remark:** For each cusp, we can conjugate these matrices into *P* since the representation is :ref:`boundary-unipotent <ptolemy-boundary-unipotent>`. We might implement a method returning a matrix in *P* for the longitude and meridian of a cusp in the future (simply by finding loops corresponding to a longitude and meridian as path of short edges in the truncated simplex in Figure 17 of [GGZ2012]_).
+
+.. _ptolemy-example-find-witness:
+
+Finding a witness point for a positively dimensional component of the Ptolemy variety
+-------------------------------------------------------------------------------------
+
+We already saw an :ref:`example of a positively dimensional component <ptolemy-non-zero-dim-comp>`. By flattening, we obtain a list of all the components of the Ptolemy varieties for all obstruction classes::
+
+    >>> M=Manifold("m371")
+    >>> sols = M.ptolemy_variety(2,'all').retrieve_solutions().flatten()
+
+We can now just look at the positively dimensional ones::
+
+    >>> one_dim_sols = [ sol for sol in sols if sol.dimension > 0]
+    >>> len(one_dim_sols)
+    1
+    >>> one_dim_sols
+    [[ PtolemyCoordinates(
+           {'c_0011_0': 1,
+            'c_0011_1': -1,
+            'c_0011_2': -1,
+            'c_0011_3': Mod(-x - 1, x^2 + x + 2),
+	    ...,
+            's_3_4': 1},
+           is_numerical = False, ...) 
+       (witnesses for NonZeroDimensionalComponent(dimension = 1, free_variables = ['c_0110_2'])) ]]
+
+We see that we have one such component and that each component is actually itself a list of witness points.
+
+**Remark:** Witness points are a fairly new feature and not all files in the database have been updated yet to contain them. You might instead just see ``[NonZeroDimensionalComponent(dimension = 1)]``.
+
+**Remark:** The ptolemy module also reports the `free variables` for the positively dimensional components. We can set these variables to random values and generically will obtain a new witness point.
+
+We can access the witness point(s) for each component just by iteration::
+
+    >>> for component in one_dim_sols:
+    ...     print("Component:")
+    ...     for witness in component:
+    ...         print("    Witness:")
+    ...         print("        Volumes:", witness.volume_numerical())
+    Component:
+        Witness:
+            Volumes: [0.E-38, 0.E-38]
+
+The different volumes in a line correspond to different Galois conjugates of the same `algebraic` witness point. 
+
+.. _ptolemy-example-non-zero-dim-rep:
+
+Finding non-zero dimensional families of boundary-unipotent representations
+---------------------------------------------------------------------------
+
+We now revisit the :ref:`1-dimensional component of the Ptolemy variety<ptolemy-non-zero-dim-comp>` and answer the question whether this yields a 1-dimensional family of representations or not. We pick a :ref:`witness point <ptolemy-example-find-witness>` for the component and check the :ref:`matrices for the peripheral curves <ptolemy-example-boundary-holonomy>`::
+
+    >>> M = Manifold("m371")
+    >>> G = M.fundamental_group()
+    >>> sols = M.ptolemy_variety(2,'all').retrieve_solutions().flatten()
+    >>> components = [ sol for sol in sols if sol.dimension > 0]
+    >>> for component in components:
+    ...     print("Component of dimension %d" % component.dimension)
+    ...     for witness in component:
+    ...         for i, cusp_curves in enumerate(G.peripheral_curves()):
+    ...             print("    Cusp %d:" % i)
+    ...             for cusp_curve in cusp_curves:
+    ...                 print("        ", witness.evaluate_word(cusp_curve, G))
+    Component of dimension 1
+        Cusp 0:
+            [[Mod(1, x^2 + x + 2), 0], [0, Mod(1, x^2 + x + 2)]]
+            [[Mod(1, x^2 + x + 2), 0], [0, Mod(1, x^2 + x + 2)]]
+
+We see that the matrices are trivial, thus this 1-dimensional component corresponds to a 1-dimensional family of :ref:`decorations <ptolemy-generically-decorated>` of the same (up to Galois conjugacy) representation. The corresponding family of representation is 0-dimensional.
+
+Let us try another manifold, ``m410``:
+
+    >>> M = Manifold("m410")
+    >>> G = M.fundamental_group()
+    >>> sols = M.ptolemy_variety(2,'all').retrieve_solutions().flatten()
+    >>> components = [ sol for sol in sols if sol.dimension > 0]
+    >>> for component in components:
+    ...     print("Component of dimension %d" % component.dimension)
+    ...     for witness in component:
+    ...         for i, cusp_curves in enumerate(G.peripheral_curves()):
+    ...             print("    Cusp %d:" % i)
+    ...             for cusp_curve in cusp_curves:
+    ...                 print("       ", witness.evaluate_word(cusp_curve, G))
+    Component of dimension 1
+        Cusp 0:
+            [[Mod(1, x^2 + 2), 0], [0, Mod(1, x^2 + 2)]]
+            [[Mod(1, x^2 + 2), Mod(x, x^2 + 2)], [0, Mod(1, x^2 + 2)]]
+    Component of dimension 1
+        Cusp 0:
+            [[Mod(1, x^2 + 7), 0], [0, Mod(1, x^2 + 7)]]
+            [[Mod(1, x^2 + 7), 0], [0, Mod(1, x^2 + 7)]]
+
+It has two 1-dimensional components, and for the first one, we see that the matrices are non-trivial, so this corresponds indeed to a 1-dimensional family of representations.
+
+**Remark:** The witness points are chosen so that they are not at the intersection of two positively dimensional components. This is for the following reason: it could happen that there is a 1-dimensional family of representations which contains points where the boundary holonomy becomes trivial. This yields a representation where the above matrices are trivial yet it is part of a 1-dimensional family of boundary-unipotent representations. In the ptolemy variety, however, this means that two non-zero dimensional components (one corresponding to a family of decorations, the other to a family of representations) intersect.
+
+Representations that are the same as PSL(2, **C**)-representations
+------------------------------------------------------------------
+
+Let us compare the volumes of ``m009`` and ``m159``:
+
+    >>> Manifold("m009").ptolemy_variety(2,'all').retrieve_solutions().volume_numerical()
+    [[],
+     [],
+     [],
+     [[2.66674478344907, -2.66674478344907, 2.66674478344907, -2.66674478344907]]]
+    >>> Manifold("m159").ptolemy_variety(2,'all').retrieve_solutions().volume_numerical()
+    [[[0.E-38, 0.E-37, 0.E-37],
+     [-2.02988321281931, 2.02988321281931, -2.02988321281931, 2.02988321281931]],
+    [[0.698544082784440, -0.698544082784440, 3.82168758617998, -3.82168758617998],
+     [0.E-37, 0.E-37, 0.E-37, 0.E-37]]]
+
+In both cases, some volumes appear twice (2.66674... for ``m009`` and 2.02988... for ``m159``). In the case of ``m009``, these two volumes correspond to the same PSL(2, **C**)-representation and in case ``m159`` to two different boundary-unipotent SL(2, **C**)-representations that are the same as PSL(2, **C**)-representations (see :ref:`ptolemy-psl-multiplicity`). We can get the  multiplicity by calling ``degree_to_shapes``::
+
+    >>> Manifold("m009").ptolemy_variety(2).degree_to_shapes()
+    2
+    >>> Manifold("m159").ptolemy_variety(2).degree_to_shapes()
+    1
+
+When we convert the Ptolemy coordinates to shapes/cross ratios for ``m009``, we also see that we see the same shape assignment appears twice (at least numerically)::
+
+    >>> Manifold("m009").ptolemy_variety(2,'all').retrieve_solutions().numerical().cross_ratios()	
+    [[],
+     [],
+     [],
+     [[CrossRatios(
+           {'z_0000_0': 0.500000000000000 + 1.32287565553230*I,
+            'z_0000_1': 0.375000000000000 + 0.330718913883074*I,
+            'z_0000_2': 0.500000000000000 + 1.32287565553230*I,
+            'zp_0000_0': 0.250000000000000 + 0.661437827766148*I,
+    	    ...},
+           is_numerical = True, ...),
+       CrossRatios(
+           {'z_0000_0': 0.500000000000000 - 1.32287565553230*I,
+            'z_0000_1': 0.375000000000000 - 0.330718913883074*I,
+            'z_0000_2': 0.500000000000000 - 1.32287565553230*I,
+    	    ...}
+           is_numerical = True, ...),
+       CrossRatios(
+           {'z_0000_0': 0.500000000000000 + 1.32287565553230*I,
+            'z_0000_1': 0.375000000000000 + 0.330718913883074*I,
+            'z_0000_2': 0.500000000000000 + 1.32287565553230*I,
+            ...},
+           is_numerical = True, ...),
+       CrossRatios(
+           {'z_0000_0': 0.500000000000000 - 1.32287565553230*I,
+            'z_0000_1': 0.375000000000000 - 0.330718913883074*I,
+            'z_0000_2': 0.500000000000000 - 1.32287565553230*I,
+  	    ...},
+           is_numerical = True, ...)]]]
+    
+
+
+**Remark:** The tables at `ptolemy.unhyperbolic.org <http://ptolemy.unhyperbolic.org/html/summary.html>`_ use the cross ratios to list representations that are the same as PSL(2, **C**)-representation only once.
+

snappy/doc/_sources/ptolemy_examples4.rst.txt

@@ -0,0 +1,61 @@
+Step-by-step examples: Part 4
+=============================
+
+**Advanced topics. Still under construction.**
+
+.. _ptolemy-example-structure-of-solution:
+
+The structure of an exact solution
+----------------------------------
+
+A solution to the Ptolemy variety (here ``sol``) is an object of type ``PtolemyCoordinates`` which is a subclass of a python dictionary. It assigns a value to each Ptolemy coordinate c\ :sub:`...` (the s\ :sub:`...` are related to the obstruction class which is trivial here). We can get the value assigned to a particular Ptolemy coordinate as follows::
+
+    >>> sol = Manifold("m003").ptolemy_variety(2).retrieve_solutions()[0]
+    >>> sol['c_0101_1']
+    Mod(-x, x^2 - x - 1)
+
+This is a pari object of type `POLMOD`. It means that the solution is in the number field with defining polynomial *x*\ :sup:`2`\ - *x* - 1 and that it is equal to - *x* where *x* is a root in the defining polynomial.
+
+We can get to the parts of a pari `POLMOD` object by::
+
+    >>> sol['c_0101_1'].lift()
+    -x
+    >>> sol['c_0101_1'].mod()
+    x^2 - x - 1
+
+These objects also support the field operations, here we are computing a cross ratio::
+
+    >>> (sol['c_0101_0'] * sol['c_1010_0']) / (sol['c_1001_0'] * sol['c_0110_0'])
+    Mod(x, x^2 - x - 1)
+
+**Remark:** We would prefer to represent these using types that are better suited when using sage such as NumberField and NumberFieldElement. In the future, we might jettison support of the ptolemy module outside of sage and use sage's native types.
+
+Rational Univariate Representation
+----------------------------------
+
+We have some limited support for the `Rational Univariate Representation`, for example::
+
+    >>> sols = Manifold("m069").ptolemy_variety(3).retrieve_solutions()
+    >>> sols[4]
+    PtolemyCoordinates(
+        { 'c_0201_0': ( Mod(-426088934700737884313191344*x^24 + 4110489425474123899213651272*x^23 ...
+                                 - 67064980598091504185767190,
+                            x^25 ... - 196124*x^4 + 14010*x^3 - 1560*x^2 + 72*x - 1)
+                  ) / ( Mod(875895332415105303646551573*x^24 - 8450034810535061601312104296*x^23 ...
+                                 + 137871639973525691285247446, 
+                            x^25 ... - 196124*x^4 + 14010*x^3 - 1560*x^2 + 72*x - 1) ),
+          ...
+        },
+        is_numerical = False, ...)
+
+This means that ``c_0201_0`` is assigned the fraction of those two ``POLDMOD`` objects.
+
+**Remark:** This is still under development.
+
+TODO
+----
+
+* Give an overview of the classes and the methods.
+* Explain how the magma file are generated. Say that magma computes the RadicalDecomposition. Ptolemy module can process the lexicographic Groebner basis of a prime ideal.
+
+

snappy/doc/_sources/ptolemy_prelim.rst.txt

@@ -0,0 +1,105 @@
+Mathematical preliminaries
+==========================
+
+Given a triangulation, the ptolemy module will produce a system of equation that is equivalent to
+the reduced Ptolemy variety (see [GTZ2011]_, Section 5 of [GGZ2012]_, and Proposition 4.7 of [GGZ2014]_).
+
+A solution
+to this system of equations where no Ptolemy coordinate is zero yields a :ref:`boundary-unipotent <ptolemy-boundary-unipotent>`
+SL(*N*, **C**)-representation, respectively, PSL(*N*, **C**)-representation (see :ref:`obstruction-class`).
+
+Note that a solution where some Ptolemy coordinates are zero might not have enough information
+to recover the representation - thus the ptolemy module discards those and thus might miss some
+boundary-unipotent representations for the chosen triangulation (see :ref:`ptolemy-generically-decorated`).
+This is the same problem that the
+gluing equations for finding PGL(2, **C**)-representations suffer from where simplices in the developing
+map can be degenerate and yielding cross ratios that are 0, 1, or :math:`\infty`\ .
+
+.. _ptolemy-boundary-unipotent:
+
+Boundary-unipotent
+------------------
+
+We call a SL(*N*,  **C**)-representation *boundary-unipotent* if each peripheral subgroup is taken to
+a conjugate of the unipotent group *P* of upper unit-triangular matrices. Similarly, we call
+a PSL(*N*, **C**)-representation *boundary-unipotent* if each peripheral subgroup is taken to a conjugate
+of the unipotent group of PSL(*N*, **C**), i.e., the image of *P* under the projection SL(*N*, **C**)\ :math:`\rightarrow`\ PSL(*N*, **C**).
+
+Note that even when boundary-unipotent PSL(*N*, **C**)-representation can be lifted to an
+SL(*N*, **C**)-representation, the lift might no longer be boundary-unipotent, i.e., there might be
+a peripheral curve whose image now is conjugate to an upper triangular matrix with an *N*-th root
+of unity on the diagonal. For example, if the manifold is hyperbolic and has one cusp,
+any lift of the geometric representation will take the longitude
+to a matrix with trace -2 and is thus not boundary-unipotent as SL(2, **C**)-representation.
+
+.. _obstruction-class:
+
+Obstruction class
+-----------------
+
+Given a boundary-unipotent PSL(*N*, **C**)-representation, we obtain an *obstruction class* in H\ :sup:`2`\ (M,\ :math:`\partial`\ M; **Z**/*N*)
+that is trivial if and only if the representations lifts to a boundary-unipotent SL(*N*, **C**)-representation (see Section 9.1 of [GTZ2011]_ and Section 1.3 of [GGZ2014]_).
+Given a triangulation and an element in H\ :sup:`2`\ (M,\ :math:`\partial`\ M; **Z**/*N*), the Ptolemy variety can be modified to find
+the boundary-unipotent 
+PSL(*N*, **C**)-representations with that obstruction class (for *N* > 2 this is implemented here but has not been published yet).
+
+Note that two elements in H\ :sup:`2`\ (M,\ :math:`\partial`\ M; **Z**/*N*)
+related by multiplication by an element in (**Z**/*N*)\ :sup:`*` yield Ptolemy
+varieties corresponding to picking different Galois conjugates for the *N*-th root of unity. Thus, it is enough
+to consider a representative for each element in the quotient H\ :sup:`2`\ (M,\ :math:`\partial`\ M; **Z**/*N*)/(**Z**/*N*)\ :sup:`*`\ .
+
+.. _ptolemy-psl-multiplicity:
+
+SL(*N*, **C**) vs PSL(*N*, **C**)
+---------------------------------
+
+The reduced Ptolemy variety for the trivial obstruction class can have several points (say *d*) giving different SL(*N*, **C**)-representations that are the same as PSL(*N*, **C**)-representations. Similarly, for the non-trivial obstruction class we can have *d* points in the reduced Ptolemy variety yielding the same PSL(*N*, **C**)-representation.
+
+The degree *d* of this correspondence is the size of H\ :sup:`1`\ (\ :math:`\hat{M}`\ ; **Z**/*N*) where :math:`\hat{M}` is the cell complex obtained from collapsing each cusp to a point.
+
+.. _ptolemy-generically-decorated:
+
+Generically decorated representations
+-------------------------------------
+
+We want to point out two important facts when using the reduced Ptolemy variety to find boundary-unipotent representations:
+
+* We miss representations that are not generically decorated (as mentioned above). This happens but rarely.
+* A positively dimensional component in the reduced Ptolemy variety might mean two things (which we can distinguish by looking at the images of the peripheral groups):
+     *  a positively dimensional family of boundary-unipotent representations or
+     *  a family of decorations of the same representation.
+
+The reason for this is that the reduced Ptolmey variety does not parametrize representations but generically decorated representations (which can also be thought of as development maps). We just list the facts about decorations important to us here and refer the reader for details to Section 4 of [GTZ2011]_ and Section 8 of [GGZ2012]_ (where decoration would be called *B*-decoration or (SL(*N*), **C**), *B*)-decoration with *B* the Borel group of upper triangular matrices):
+
+* Every boundary-unipotent representation of a cusped manifold admits a decoration. The set of decorations of a representation is intrinsic to the representation and independent of the triangulation.
+* The representation determines the decoration uniquely if and only if the representation is boundary-non-degenerate (which most representations are).
+* Given a decorated representation and an ideal triangulation of a cusped manifold, we obtain Ptolemy coordinates.
+* If all the resulting Ptolemy coordinates are non-zero, we call the representation *generically decorated* - a notion that depends on the chosen triangulation.
+* The reduced Ptolemy variety parametrizes generically decorated and boundary-unipotent representations.
+
+  
+.. _ptolemy-reduced-variety:
+
+Reduced Ptolemy variety
+-----------------------
+
+We will actually always use the reduced Ptolemy variety, i.e., the system of equation that consists of the Ptolemy relations (always of the form
+:math:`\pm` c\ :sub:`...` c\ :sub:`...` :math:`\pm` c\ :sub:`...` c\ :sub:`...`  :math:`\pm` c\ :sub:`...` c\ :sub:`...`\) and extra equations fixing an appropriate set of (N-1) Ptolemy coordinates per cusp as described in Proposition 4.7 of [GGZ2014]_. This is because the Ptolemy relations alone admit an action by (**C**\ :sup:`*`\ )\ :sup:`(N-1)` for each cusp that does not change the representation it yields.
+
+In other words, the Ptolemy variety parametrizes *P*-decorations and the reduced Ptolemy variety parametrizes *B*-decorations.
+
+Future work
+-----------
+
+In unpublished work, we developed an algorithm that takes some triangulation of a manifold and constructs a set of triangulations and corresponding Ptolemy varieties (with extra edge relations) such that we can guarantee that all boundary-unipotent PSL(2,C)-representations are found - not just the ones that are generically decorated with respect to the chosen triangulation. This is inspired by [S2009]_. The ptolemy module might support this in the future.
+
+In [Z2014]_, the Ptolemy variety was extended to detect non boundary-unipotent representations as well. The ptolemy module might produce these varieties in the future. This might offer another way of computing A-polynomials - that when combined with the above algorithm is guaranteed to be the full A-polynomial and not just a factor of it.
+
+References
+----------
+
+.. [S2009] Henry Segerman: A generalisation of the deformation variety, http://arxiv.org/abs/0904.1893
+.. [GTZ2011] Stavros Garoufalidis, Dylan P. Thurston, and Christian K. Zickert: The Complex Volume of SL(n,C)-Representations of 3-Manifolds, http://arxiv.org/abs/1111.2828
+.. [GGZ2012] Stavros Garoufalidis, Matthias Goerner, and Christian K. Zickert: Gluing Equations for PGL(n,C)-Representations of 3-Manifolds, http://arxiv.org/abs/1207.6711
+.. [GGZ2014] Stavros Garoufalidis, Matthias Goerner, and Christian K. Zickert: The Ptolemy Field of 3-Manifold Representations, http://arxiv.org/abs/1401.5542
+.. [Z2014] Christian K. Zickert: Ptolemy coordinates, Dehn invariant, and the A-polynomial, http://arxiv.org/abs/1405.0025

snappy/doc/_sources/screenshots.rst.txt

@@ -0,0 +1,21 @@
+==============================
+Screenshots: SnapPy in action
+==============================
+
+Mac OS X
+---------
+
+.. image:: images/mac.png
+   :width: 717 px
+
+
+Linux (Ubuntu 13.10)
+------------------------
+
+.. image:: images/ubuntu.png
+
+
+Windows 7
+--------------------
+
+.. image:: images/win7.png

snappy/doc/_sources/snap.rst.txt

@@ -0,0 +1,87 @@
+.. Documentation of the Snap part of SnapPy
+..   automodule:: snappy.snap
+   
+Number theory of hyperbolic 3-manifolds
+=======================================
+
+SnapPy has support for arbitrary-precision computation and for
+identifying number fields associated to hyperbolic 3-manifolds.  While
+this functionality is less than that of `Snap
+<http://snap-pari.sf.net/>`_, it is already useful.  Except for the
+first example, one currently needs to use SnapPy inside of `Sage
+<http://sagemath.org>`_ to have access to these features.  Here's how
+to find the tetrahedra shapes to high-precision::
+
+       sage: import snappy
+       sage: M = snappy.Manifold('m004')
+       sage: M.tetrahedra_shapes('rect', bits_prec=100)
+       [0.50000000000000000000000000000 + 0.86602540378443864676372317075*I, 0.50000000000000000000000000000 + 0.86602540378443864676372317075*I]
+       sage: M.tetrahedra_shapes('rect', dec_prec=100)[0]
+       0.500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 +
+       0.866025403784438646763723170752936183471402626905190314027903489725966508454400018540573093378624288*I
+
+One can also compute the holonomy representation to any precision::
+
+    sage: G = M.polished_holonomy(bits_prec=100)
+    sage: G.SL2C('a')
+    [0.50000000000000000000000000000 + 0.86602540378443864676372317075*I                                   -1.0000000000000000000000000000*I]
+    [                                   1.0000000000000000000000000000*I   1.0000000000000000000000000000 - 1.7320508075688772935274463415*I]
+
+You can also try to guess the shapes exactly using an LLL-based
+algorithm of the type pioneered by Snap::
+
+          sage: T = M.tetrahedra_field_gens()
+	  sage: T.find_field(prec=100, degree=10, optimize=True)
+	  (Number Field in z with defining polynomial x^2 - x + 1, <ApproxAN: 0.5 + 0.866025403784*I>, [x, x])
+
+You can do the same for various other fields via the methods
+``trace_field_gens``, ``invariant_trace_field_gens``, and ``holonomy_matrix_entries``.
+	  
+In more complicated examples, one needs to use higher precision and/or
+degree to actually find the exact values::
+
+	  sage: N = snappy.Manifold('m004(1,3)')
+	  sage: K = N.trace_field_gens()
+	  sage: K.find_field(prec=100, degree=10, optimize=True)    # Fails, so no output 
+	  sage: K.find_field(prec=200, degree=20, optimize=True)[0]
+	  Number Field in z with defining polynomial x^11 - 2*x^10 - 8*x^9 + 16*x^8 + 22*x^7 - 44*x^6 - 25*x^5 + 50*x^4 + 11*x^3 - 22*x^2 - x + 1
+
+We can also compute various hyperbolicly-twisted Alexander
+polynomials, as described `here <http://dunfield.info/torsion>`_::
+
+	sage: M = snappy.Manifold('5_2')
+	sage: M.alexander_polynomial()
+	2*a^2 - 3*a + 2
+	sage: M.hyperbolic_torsion(bits_prec=100)
+	(2.3376410213776269870195455729 - 0.56227951206230124389918214504*I)*a^2 
+	- 4.0000000000000000000000000003*a 
+	+ 2.3376410213776269870195455731 - 0.56227951206230124389918214477*I
+	sage: M.hyperbolic_SLN_torsion(3, 100)   # Dubois-Yamagachi adjoint torsion
+	(0.40431358073618481197132660504 +
+	0.75939451500971650241038772223*I)*a^3 
+	+ (2.9032849613891083021420278850 -
+	4.1185388389935516999882632998*I)*a^2 
+	+ (-2.9032849613891083021420278809 +
+	4.1185388389935516999882633007*I)*a 
+	- 0.40431358073618481197132661847 - 0.75939451500971650241038771418*I
+	sage: M.hyperbolic_SLN_torsion(4, 100)   # Why not?
+	(2.5890988184099251088892745185 + 3.5126610817613336586374292713*I)*a^4
+	+ (10.357403823939297224437742077 - 13.378446302375451727042633120*I)*a^3
+	+ (-26.821802363180149782221451472 + 7.0253221635226673172748587283*I)*a^2
+	+ (10.357403823939297224437738856 - 13.378446302375451727042631346*I)*a 
+	+ 2.5890988184099251088892549440 + 3.5126610817613336586374448040*I
+
+You can find out more about each of these methods using
+introspection::
+
+  sage: M.hyperbolic_torsion?
+  Definition: M.hyperbolic_torsion(M, bits_prec=100, all_lifts=False, wada_conventions=False, phi=None)
+  Docstring:
+  Computes the hyperbolic torsion polynomial as defined in [DFJ].
+
+  >>> M = Manifold('K11n42')
+  >>> M.alexander_polynomial()
+  1
+  >>> tau = M.hyperbolic_torsion(bits_prec=200)
+  >>> tau.degree()
+  6

snappy/doc/_sources/snappy.rst.txt

@@ -0,0 +1,28 @@
+.. Documentation of the Python part of SnapPy
+
+The snappy module and its classes
+=======================================
+
+SnapPy is centered around a Python interface for SnapPea called
+"snappy", and this is what you're interacting with in the main "SnapPy
+command shell" window.  The main class is Manifold, which is an ideal
+triangulation of the interior of a compact 3-manifold with torus
+boundary, where each tetrahedron has been assigned the geometry of
+an ideal tetrahedron in hyperbolic 3-space.  A Dehn-filling can be
+specified for each boundary component, allowing the description of
+closed 3-manifolds and some orbifolds.  The class Manifold is derived
+from the simpler Triangulation class which lacks any geometric
+structure.  There are also some additional classes for things like
+fundamental groups, Dirichlet domains, etc.  Snappy comes with a large
+library of 3-manifolds, some of which are grouped together in censuses.  
+
+
+.. toctree::
+   :maxdepth: 2
+   
+   manifold
+   manifoldhp
+   triangulation
+   additional_classes
+   censuses 
+