snappy 3.1.1__cp312-cp312-win_amd64.whl → 3.2__cp312-cp312-win_amd64.whl

snappy/doc/_sources/ptolemy_examples4.rst.txt

@@ -1,61 +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.
-
-
+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

@@ -1,105 +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
+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

@@ -1,21 +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
+==============================
+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

@@ -1,87 +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
+.. 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

@@ -1,28 +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 
-
+.. 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 
+