snappy 3.2__cp311-cp311-macosx_10_12_x86_64.whl

snappy/doc/_sources/ptolemy_examples1.rst.txt

@@ -0,0 +1,298 @@
+Step-by-step examples: Part 1
+=============================
+
+.. _ptolemy-example-basic:
+
+The Ptolemy variety for SL(*N*, **C**)
+--------------------------------------
+
+Given a SnapPy triangulation, we obtain the reduced Ptolemy variety to find
+SL(2, **C**)-representations as follows::
+
+  >>> M=Manifold("m003")
+  >>> M.ptolemy_variety(N = 2)
+  Ptolemy Variety for m003, N = 2
+    c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+    c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+    - 1 + c_0011_0
+
+The result of ``M.ptolemy_variety(2)`` is an object of type ``PtolemyVariety``.
+
+**Remark:** The exact formatting of the output might change between SnapPy versions and sage.
+
+**Remark:** The first two equations are the two Ptolemy relations 
+for the two tetrahedra in ``m003``. The last equation :ref:`reduces <ptolemy-reduced-variety>` the Ptolemy variety.
+
+Similar, we can obtain the Ptolemy variety for higher *N*, say SL(3, **C**)::
+
+  >>> M=Manifold("m004")
+  >>> M.ptolemy_variety(3)
+  Ptolemy Variety for m003, N = 3
+        c_0012_0 * c_1101_0 + c_0012_1 * c_0111_0 - c_0102_0 * c_1011_0
+        c_0012_1 * c_1110_0 - c_0102_0 * c_0111_0 + c_0102_1 * c_1011_0
+        c_0012_0 * c_0111_0 + c_0102_0 * c_1101_0 - c_0102_1 * c_1110_0
+        c_0012_0 * c_1110_0 + c_0012_1 * c_1011_0 - c_0102_1 * c_1101_0
+        - c_0012_0 * c_0111_0 - c_0012_1 * c_1101_0 + c_0102_1 * c_1011_0
+        - c_0012_0 * c_1110_0 - c_0102_0 * c_1011_0 + c_0102_1 * c_0111_0
+        - c_0012_1 * c_0111_0 + c_0102_0 * c_1110_0 - c_0102_1 * c_1101_0
+        - c_0012_0 * c_1011_0 - c_0012_1 * c_1110_0 + c_0102_0 * c_1101_0
+        - 1 + c_0012_0
+        - 1 + c_0111_0
+
+**Remark:** Similarly, we obtain four Ptolemy relations for each of the two tetrahedra in ``m004`` corresponding to the four subsimplices of a tetrahedron we get for *N*\ =3 (see Figure 2 of [GTZ2011]_).
+
+Using auto-completion
+---------------------
+
+Let us assign a Ptolemy variety to ``p`` and then type ``p.``::
+
+    >>> p=Manifold("m003").ptolemy_variety(2)
+    >>> p.
+
+If we are in SnapPy, sage or ipython, we can now hit the tab-key and see a list of attributes and methods available for a Ptolemy variety::
+
+    >>> p.
+    p.canonical_representative           p.filename_base                      p.to_magma
+    p.compute_decomposition              p.path_to_file                       p.to_magma_file
+    p.compute_solutions                  p.py_eval_section                    p.variables
+    p.degree_to_shapes                   p.py_eval_variable_dict              p.variables_with_non_zero_condition
+    p.equations                          p.retrieve_decomposition             
+    p.equations_with_non_zero_condition  p.retrieve_solutions                 
+
+We can get further help by using the ``?``::
+
+    >>> p.filename_base?
+    ...
+    Definition: p.filename_base(self)
+    Docstring:
+    Preferred filename base for writing out this Ptolemy variety
+    ...
+
+This is a general mechanism and works for all objects in SnapPy, sage or ipython.
+
+.. _ptolemy-example-retrieve-exact-solutions:
+
+Retrieving exact solutions from the database
+--------------------------------------------
+
+Given a Ptolemy variety, we can access the database at `ptolemy.unhyperbolic.org <http://ptolemy.unhyperbolic.org/>`_ to retrieve solutions for it with ``retrieve_solutions`` (if this is not working, please check your Internet connection)::
+
+    >>> p=Manifold("m003").ptolemy_variety(2)
+    >>> sols=p.retrieve_solutions()
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/02_tetrahedra/m003__sl2_c0.magma_out ...
+    Parsing..
+    >>> sols
+    [PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0101_0': Mod(x, x^2 - x - 1),
+          'c_0101_1': Mod(-x, x^2 - x - 1),
+          'c_0110_0': Mod(-x, x^2 - x - 1),
+          'c_0110_1': Mod(x, x^2 - x - 1),
+          'c_1001_0': -1,
+          'c_1001_1': 1,
+          'c_1010_0': Mod(x, x^2 - x - 1),
+          'c_1010_1': Mod(-x, x^2 - x - 1),
+          'c_1100_0': 1,
+          'c_1100_1': -1,
+          's_0_0': 1,
+          's_0_1': 1,
+          's_1_0': 1,
+          's_1_1': 1,
+          's_2_0': 1,
+          's_2_1': 1,
+          's_3_0': 1,
+          's_3_1': 1},
+         is_numerical = False, ...)]
+    
+The result is a list of solutions (up to Galois conjugation), here the list contains only one solution. Let us pick that one::
+
+    >>> len(sols)
+    1
+    >>> sol = sols[0]
+    PtolemyCoordinates(
+        {'c_0011_0': 1,
+         'c_0011_1': -1,
+         'c_0101_0': Mod(x, x^2 - x - 1),
+         'c_0101_1': Mod(-x, x^2 - x - 1),
+         'c_0110_0': Mod(-x, x^2 - x - 1),
+         'c_0110_1': Mod(x, x^2 - x - 1),
+         'c_1001_0': -1,
+         'c_1001_1': 1,
+         'c_1010_0': Mod(x, x^2 - x - 1),
+         'c_1010_1': Mod(-x, x^2 - x - 1),
+         'c_1100_0': 1,
+         'c_1100_1': -1,
+         's_0_0': 1,
+         's_0_1': 1,
+         's_1_0': 1,
+         's_1_1': 1,
+         's_2_0': 1,
+         's_2_1': 1,
+         's_3_0': 1,
+         's_3_1': 1},
+        is_numerical = False, ...)
+
+As we can see, a solution assigns a value to each Ptolemy coordinate c\ :sub:`...`\ . It is of type ``PtolemyCoordinates`` (a subclass of python's ``dict``) and more details are discussed in :ref:`a later example <ptolemy-example-structure-of-solution>`.
+
+**Remark:** We can give the additional argument ``verbose=False`` to suppress the messages about the database access::
+
+    >>> sols = Manifold("m003").ptolemy_variety(2).retrieve_solutions(verbose=False)
+
+.. _ptolemy-example-matrices:
+
+Compute the matrices for a representation
+-----------------------------------------
+
+**Remark:** Requires SnapPy 2.3 or later.
+
+Given a solution as above, we can take a word in the fundamental group and get its image under the representation using :py:meth:`~snappy.ptolemy.coordinates.PtolemyCoordinates.evaluate_word`. Here, we do it for the two generators::
+
+    >>> M = Manifold("m003")
+    >>> sol = M.ptolemy_variety(2).retrieve_solutions()[0]
+    >>> sol.evaluate_word('a')
+    [[0, Mod(1, x^2 - x - 1)], [Mod(-1, x^2 - x - 1), Mod(-x, x^2 - x - 1)]]
+    >>> sol.evaluate_word('b')
+    [[Mod(x, x^2 - x - 1), Mod(x, x^2 - x - 1)],
+    [Mod(-x, x^2 - x - 1), Mod(-1, x^2 - x - 1)]]
+
+By default, this word is with respect to the unsimplified presentation of the fundamental group. Thus, we expect the identity matrix when we evaluate a relator (for PSL(*N*, **C**) the diagonal element will be an *N*-th root of unity)::
+
+    >>> M.fundamental_group(simplify_presentation=False)
+    Generators:
+       a,b,c
+    Relators:
+       BCaC
+       AbCbA
+    >>> sol.evaluate_word('BCaC')
+    [[Mod(1, x^2 - x - 1), 0], [0, Mod(1, x^2 - x - 1)]]
+
+We revisit computing the matrices :ref:`here <ptolemy-detailed-example-matrices>` to explain how to use a different presentation of the fundamental group.
+
+**Remark:** The matrices are currently returned as a list of list of pari ``POLMOD`` objects. In the future, the ptolemy module should return the matrices as sage matrices over a `sage NumberField <http://doc.sagemath.org/html/en/reference/number_fields/sage/rings/number_field/number_field.html>`_.
+
+.. _ptolemy-example-traces:
+
+Compute the traces
+------------------
+
+**Remark:** Requires SnapPy 2.3.2 or later.
+
+We can compute the traces of these matrices::
+
+    >>> sol = Manifold("m003").ptolemy_variety(2).retrieve_solutions(verbose=False)[0]
+    >>> from snappy.ptolemy.matrix import matrix_trace
+    >>> matrix_trace(sol.evaluate_word('a'))
+    Mod(-1, x^2 - x - 1)
+    >>> matrix_trace(sol.evaluate_word('b'))
+    Mod(-x -1, x^2 -x -1)
+    >>> matrix_trace(sol.evaluate_word('ab'))
+    Mod(-x + 2, x^2 + x + 1)
+    >>> matrix_trace(sol.evaluate_word('ba'))
+    Mod(-x + 2, x^2 + x + 1)
+
+**Remark:** Since this representation is irreducible, it is uniquely determined up to conjugacy by the above 4 traces, see Slide 30 of 
+`Marc Culler's slides <http://www.math.illinois.edu/GEAR/resources/Culler/Culler-lecture3-slides.pdf>`_.
+
+.. _ptolemy-examples-trace-field:
+
+Compute the trace field for a PSL(*2*, **C**)-representation
+------------------------------------------------------------
+
+    >>> sol = Manifold("m003").ptolemy_variety(2).retrieve_solutions(verbose=False)[0]
+    >>> sol.number_field()
+    x^2 + x + 1
+
+This is the Ptolemy field which is equal to the trace field if *N*\ = 2 by results of [GGZ2014]_.
+
+.. _ptolemy-example-volume:
+
+Compute the volume
+------------------
+
+We can also compute the volume of the representations::
+
+    >>> sol = Manifold("m003").ptolemy_variety(2).retrieve_solutions(verbose=False)[0]
+    >>> sol.volume_numerical()
+    [0.E-38, 1.88266550875941 E-14]
+
+Recall that we had an algebraic solution in the number field with defining polynomial x\ :sup:`2`\ +x+1. This number field has two embeddings into **C**, yielding two representations. This is why the result is a list of two volumes. In this case, they are both zero up to numerical precision.
+
+.. _ptolemy-example-increase-precision:
+
+Increase precision
+------------------
+
+We can get higher precision be setting it in pari (in decimal digits)::
+
+    >>> sol = Manifold("m011").ptolemy_variety(2).retrieve_solutions(verbose=False)[0]
+    >>> sol.volume_numerical()
+    [-4.30211422042248 E-16, -0.942707362776931, 0.942707362776931]
+    >>> pari.set_real_precision(40)
+    15
+    >>> sol.volume_numerical()
+    [-1.5819817649675358086 E-40,
+     -0.9427073627769277209212996030922116475902,
+     0.9427073627769277209212996030922116475902]
+
+**Remark:** This is not using interval arithmetics (although this is planned for the future). For now, the computed value of a quantity might differ from the real value by far more than the number of displayed digits suggests. To be confident about the result, we can increase the precision and see how many digits of the result are stabilizing.
+
+.. _ptolemy-example-obstruction-class:
+
+Ptolemy varieties for PSL(*N*, **C**)-representations
+-----------------------------------------------------
+
+The representations of ``m003`` we detected so far had trivial volume and thus cannot include the geometric representation. This is because the geometric representation is a boundary-unipotent PSL(2, **C**)-representation but not a :ref:`boundary-unipotent SL(2, C)-representation <ptolemy-boundary-unipotent>` and we only detect the latter ones above.
+
+We can obtain the Ptolemy varieties for all :ref:`obstruction classes <obstruction-class>` to find the PSL(*N*, **C**)-representation that do not lift to boundary-unipotent SL(*N*, **C**)-representations as well::
+
+    >>> M = Manifold("m003")
+    >>> M.ptolemy_variety(N = 2, obstruction_class = 'all')
+    [Ptolemy Variety for m003, N = 2, obstruction_class = 0
+        c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+        c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+        - 1 + c_0011_0,
+     Ptolemy Variety for m003, N = 2, obstruction_class = 1
+        - c_0011_0 * c_0101_0 - c_0011_0^2 - c_0101_0^2
+        - c_0011_0 * c_0101_0 - c_0011_0^2 - c_0101_0^2
+        - 1 + c_0011_0]
+
+The first Ptolemy variety in this list always corresponds to the trivial obstruction class. Let us try the non-trivial obstruction class::
+    
+    >>> p = M.ptolemy_variety(2, 'all')[1]
+    >>> sols=p.retrieve_solutions(verbose=False)
+    >>> sols.volume_numerical()
+    [[2.02988321281931, -2.02988321281931]]
+
+We now see a representation with volume twice that of a regular ideal tetrahedron. This is the geometric representation of ``m003``.
+Here is python code to iterate over all obstruction classes:
+
+    >>> for p in Manifold("m003").ptolemy_variety(2,'all'):
+    ...     sols = p.retrieve_solutions(verbose=False)
+    ...     print(sols.volume_numerical())
+    [[0.E-19, 1.88267370443418 E-14]]
+    [[2.02988321281931, -2.02988321281931]]    
+
+And in functional style::
+
+    >>> [p.retrieve_solutions().volume_numerical() for p in Manifold("m003").ptolemy_variety(2,'all')]
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/02_tetrahedra/m003__sl2_c0.magma_out ...
+    Parsing...
+    Trying to retrieve solutions from http://ptolemy.unhyperbolic.org/data/pgl2/OrientableCuspedCensus/02_tetrahedra/m003__sl2_c1.magma_out ...
+    Parsing...
+    [[[0.E-19, 1.88267370443418 E-14]], [[2.02988321281931, -2.02988321281931]]]
+
+**Remark**: As we see, it is not necessary to use named arguments ``N = 2`` and ``obstruction_class = 'all'`` for faster typing. However, for better readability of our code, we recommend to include the names.
+
+A short cut for a PSL(*N*, **C**) Ptolemy variety
+-------------------------------------------------
+
+We have seen that ``M.ptolemy_variety(2, 'all')`` gives a Ptolemy variety for each obstruction class. We used ``M.ptolemy_variety(2, 'all')[3]`` to pick one, here the fourth, of those varieties. A shorter form of doing this is::
+
+    >>> M = Manifold("m009")
+    >>> M.ptolemy_variety(2, 3)
+    Ptolemy Variety for m009, N = 2, obstruction_class = 3
+        c_0011_0^2 + c_0101_0 * c_0101_1 + c_0101_1^2
+        - c_0011_0^2 + c_0101_0^2 + c_0101_1^2
+        - c_0011_0^2 - c_0101_0 * c_0101_1 - c_0101_1^2
+        - 1 + c_0011_0

snappy/doc/_sources/ptolemy_examples2.rst.txt

@@ -0,0 +1,363 @@
+Step-by-step examples: Part 2
+=============================
+    
+.. _ptolemy-example-smart-lists:
+
+The Ptolemy list type
+---------------------
+
+Recall that ``ptolemy_variety`` with ``obstruction_class='all'`` returns a list of varieties, one for each obstruction class::
+    
+    >>> M = Manifold("m003")
+    >>> M.ptolemy_variety(2, obstruction_class = 'all')
+    [Ptolemy Variety for m003, N = 2, obstruction_class = 0
+        c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+        c_0011_0 * c_0101_0 + c_0011_0^2 - c_0101_0^2
+        - 1 + c_0011_0,
+     Ptolemy Variety for m003, N = 2, obstruction_class = 1
+        - c_0011_0 * c_0101_0 - c_0011_0^2 - c_0101_0^2
+        - c_0011_0 * c_0101_0 - c_0011_0^2 - c_0101_0^2
+        - 1 + c_0011_0]
+
+Also recall that ``retrieve_solutions`` was a method of a ``PtolemyVariety``. Assume we want to call ``retrieve_solutions`` for each Ptolemy variety. As in the previous example, we could write a loop such as::
+ 
+    >>> [p.retrieve_solutions(verbose=False) for p in M.ptolemy_variety(2, 'all')]
+
+The ptolemy module allows to do this in a much shorter way::
+
+    >>> M.ptolemy_variety(2, 'all').retrieve_solutions(verbose=False)
+    [[PtolemyCoordinates(
+          {'c_0011_0': 1,
+           'c_0011_1': -1,
+           'c_0101_0': Mod(x, x^2 - x - 1),
+	   ...,
+           's_3_1': 1},
+          is_numerical = False, ...)],
+     [PtolemyCoordinates(
+          {'c_0011_0': 1,
+           'c_0011_1': -1,
+           'c_0101_0': Mod(x, x^2 + x + 1),
+	   ...,
+           's_3_1': 1},
+          is_numerical = False, ...)]]
+
+This behavior is specific to the ptolemy module. It works with many methods of the ptolemy module that
+can potentially return more than one object. These methods return a special kind of list (usually
+``MethodMappingList``, a subclass of python ``list``) that tries to call the method of the given name (here ``retrieve_solutions``) with
+the given arguments (here ``verbose=False``) on each element in the list (here the two Ptolemy varieties).
+
+Since ``retrieve_solutions`` itself actually returns a list, the result is a list of lists of solutions which are of type ``PtolemyCoordinates``. The first level groups the solutions by obstruction class. The inner lists contain the different (non-Galois conjugate) solutions for each obstruction class (here, for ``m003``, each inner lists contains only one element).
+
+Using the Ptolemy list type recursively
+---------------------------------------
+
+The list type described in the previous example works recursively. Recall that an algebraic solution to a Ptolemy variety (of type ``PtolemyCoordinates``) has a method ``volume_numerical`` that returns a list of volumes::
+
+     >>> M=Manifold("m003")
+     >>> p=M.ptolemy_variety(2,1)
+     >>> sol=p.retrieve_solutions(verbose=False)[0]
+     >>> sol.volume_numerical()
+     [0.E-19, 1.88267370443418 E-14]
+
+We can chain these commands together to retrieve the volumes of all boundary-unipotent PSL(2, **C**) (that are :ref:`generically decorated <ptolemy-generically-decorated>` with respect to the triangulation) in just one line::
+
+    >>> Manifold("m003").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical()
+    [[[0.E-19, 1.88267370443418 E-14]], [[2.02988321281931, -2.02988321281931]]]
+
+Note that the volumes of the representations are in a list of lists of lists. At the first level the volumes are grouped by obstruction class, then by Galois conjugacy.
+
+**Remark:** There might be an extra level for witness points.
+
+**Remark:** Unfortunately, this is not compatible with tab-autocompletion, see :ref:`later <ptolemy-example-missing-auto-completion>`.
+
+A comparison of ``m003`` and ``m004``
+-------------------------------------
+
+We can now compare the set of volumes of ``m003`` and ``m004``:
+
+    >>> Manifold("m003").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical()
+    [[[0.E-19, 1.88267370443418 E-14]], [[2.02988321281931, -2.02988321281931]]]
+    >>> Manifold("m004").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical()
+    [[], [[-2.02988321281931, 2.02988321281931]]]
+
+We see that the two manifolds are distinguished by their volumes of boundary-unipotent representations: ``m004`` has no representation with trivial volume (this is not a proof as in theory, there could be such a representation which is not :ref:`generically decorated <ptolemy-generically-decorated>` with respect to the given triangulation) and no representation that can be lifted to a boundary-unipotent SL(2, **C**)-representation.
+
+A non-hyperbolic example
+------------------------
+
+We can also compute the volumes for a manifold that might be non-hyperbolic, here the complement of the 5\ :sub:`1` knot::
+
+    >>> Manifold("5_1").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical()
+    [[], [[1.52310839130992 E-14, 0.E-37]]]
+
+Note that one of the Ptolemy varieties is non-empty which proves that all edges of the triangulation are essential. We also see that all volumes are 0 and thus smaller than the volume 2.029883... of the figure-eight knot complement that is proven to be the smallest volume of any orientable cusped manifold. Thus, it follows from Theorem 1.3 and Remark 1.4 of [GGZ2014]_ that 5\ :sub:`1` is not hyperbolic.
+
+**Remark:** The ptolemy module does not (yet) support interval arithmetics, otherwise, this would be a proof that 5\ :sub:`1` is not hyperbolic.
+
+
+Flattening nested structures
+----------------------------
+
+If we want to loose some of the grouping, we can call ``flatten`` on the results. Here the grouping by obstruction class is lost::
+
+    >>> Manifold("m003").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical().flatten()
+    [[0.E-19, 1.88267370443418 E-14], [2.02988321281931, -2.02988321281931]]
+
+And now, the grouping by Galois conjugacy is lost as well, resulting in a flat list::
+
+    >>> Manifold("m003").ptolemy_variety(2,'all').retrieve_solutions(verbose=False).volume_numerical().flatten(2)
+    [0.E-19, 1.88267370443418 E-14, 2.02988321281931, -2.02988321281931]
+
+So the result is just a flat list.
+
+**Remark:** We cannot `overflatten`. If we give an even larger argument to flatten, the result will just stay a flat list.
+
+.. _ptolemy-example-missing-auto-completion:
+
+Lack of tab-autocompletion for nested structures
+-------------------------------------------------
+
+Unfortunately, the autocompletion does not list all the desired results when we have a nested structure. For example::
+
+    >>> sols = Manifold("m003").ptolemy_variety(2,'all').retrieve_solutions(verbose=False)
+    >>> sols.
+
+When we now hit the tab key::
+
+    >>> sols.
+    sols.append   sols.extend   sols.index    sols.pop      sols.reverse  
+    sols.count    sols.flatten  sols.insert   sols.remove   sols.sort
+
+... we only get ``list`` methods, but not the desired ``volume_numerical``. One way to discover the available methods is to pick a leaf of the nested structure and hit the tab key::
+
+    >>> sol = sols.flatten(100)[0]
+    >>> sol.
+    sol.N                                   sol.keys
+    sol.check_against_manifold              sol.long_edge
+    ...
+    sol.itervalues                          sol.volume_numerical
+
+The overview diagram might also be helpful.
+
+Converting exact solutions into numerical solutions
+---------------------------------------------------
+
+We can turn exact solutions into numerical solutions by calling ``numerical``::
+
+    >>> sol = Manifold("m003").ptolemy_variety(2, 1).retrieve_solutions()[0]
+    >>> sol
+    PtolemyCoordinates(
+        {'c_0011_0': 1,
+         'c_0011_1': -1,
+         'c_0101_0': Mod(x, x^2 + x + 1),
+	 ...
+         's_3_1': 1},
+        is_numerical = False, ...)
+    >>> sol.numerical()
+    [PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0101_0': -0.500000000000000 - 0.866025403784439*I,
+	  ...,
+          's_3_1': 1},
+         is_numerical = True, ...),
+     PtolemyCoordinates(
+         {'c_0011_0': 1,
+          'c_0011_1': -1,
+          'c_0101_0': -0.500000000000000 + 0.866025403784439*I,
+	  ...,
+          's_3_1': 1},
+         is_numerical = True, ...)]
+
+Note that the one exact (algebraic) solution turns into a list of numerical solutions which are Galois conjugates.
+
+**Remark:** This uses the current pari precision. See the :ref:`above example <ptolemy-example-increase-precision>`, in particular, the comment about interval arithmetics.
+
+**Remark:** Calling ``numerical()`` on a numerical solution does nothing.
+
+**Remark:** ``CrossRatios`` also support ``numerical``.
+
+.. _ptolemy-example-numerical-matrix:
+
+Working with exact vs numerical solutions
+-----------------------------------------
+
+Most methods such as ``evaluate_word`` or ``cross_ratios`` work just the same way on an exact solution::
+
+   >>> exact_sol = Manifold("m004").ptolemy_variety(2, 1).retrieve_solutions()[0]
+   >>> exact_sol
+   PtolemyCoordinates(
+       {'c_0011_0': 1,
+        'c_0011_1': -1,
+        'c_0101_0': 1,
+        'c_0101_1': Mod(x, x^2 + x + 1),
+        ...,
+	's_3_1': -1},
+       is_numerical = False, ...)
+   >>> exact_sol.evaluate_word('a')
+   [[Mod(-2*x, x^2 + x + 1), Mod(-x - 1, x^2 + x + 1)],
+    [Mod(x, x^2 + x + 1), Mod(x + 1, x^2 + x + 1)]]
+
+... as they do on a numerical solution::
+
+   >>> numerical_sol = sol.numerical()[0]
+   >>> numerical_sol
+   PtolemyCoordinates(
+       {'c_0011_0': 1,
+        'c_0011_1': -1,
+        'c_0101_0': 1,
+        'c_0101_1': -0.500000000000000 - 0.866025403784439*I,
+	...,
+	's_3_1': -1},
+       is_numerical = False, ...)
+   >>> numerical_sol.evaluate_word('a')
+   [[1.00000000000000 + 1.73205080756888*I,
+     -0.500000000000000 + 0.866025403784439*I],
+    [-0.500000000000000 - 0.866025403784439*I,
+     0.500000000000000 - 0.866025403784439*I]]
+
+Methods with postfix ``_numerical`` are special: when applied to an exact solution, they implicitly convert it to a list
+of Galois conjugate numerical solutions first. ``volume_numerical`` is an example (because volume is a transcendental function)::
+
+    >>> exact_sol.volume_numerical()
+    [-2.02988321281931, 2.02988321281931]
+    >>> numerical_sol.volume_numerical()
+    -2.02988321281931
+
+.. _ptolemy-example-retrieve-numerical-solutions:
+
+Computing numerical solutions directly
+--------------------------------------
+
+We can also directly compute numerical solutions::
+
+    >>> M = Manifold("m004")
+    >>> sols = M.ptolemy_variety(2,'all').retrieve_solutions(numerical = True)
+    [[],
+     [[PtolemyCoordinates(
+           {'c_0011_0': 1.00000000000000 + 0.E-19*I,
+            'c_0011_1': -1.00000000000000 + 0.E-19*I,
+            'c_0101_0': 1.00000000000000 + 0.E-19*I,
+            'c_0101_1': -0.500000000000000 - 0.866025403784439*I,
+	    ...,
+            's_3_1': -1},
+           is_numerical = True, ...),
+       PtolemyCoordinates(
+           {'c_0011_0': 1.00000000000000 + 0.E-19*I,
+            'c_0011_1': -1.00000000000000 + 0.E-19*I,
+            'c_0101_0': 1.00000000000000 + 0.E-19*I,
+            'c_0101_1': -0.500000000000000 + 0.866025403784439*I,
+	    ...,
+            's_3_1': -1},
+           is_numerical = True, ...)]]]    
+
+The structure is as described earlier, a list of lists of lists: first solutions are grouped by obstruction class, then by Galois conjugacy.
+
+The advantage over going through the exact solutions is that it might be much faster
+(because it can avoid computing the number field from the lexicographic Groebner basis, see later). For example, many PSL(3, **C**) examples only work when using ``numerical = True``.
+
+.. _ptolemy-example-cross-ratios:
+
+Computing cross ratios from Ptolemy coordinates
+-----------------------------------------------
+
+Given exact or numerical solutions to the Ptolemy variety, we can also compute the cross ratios/shape parameters::
+
+    >>> sols = Manifold("m004").ptolemy_variety(2,'all').retrieve_solutions(verbose=False)
+    >>> zs=sols.cross_ratios()
+    >>> zs
+    [[],
+     [CrossRatios({'z_0000_0': Mod(x + 1, x^2 + x + 1),
+                   'z_0000_1': Mod(x + 1, x^2 + x + 1),
+                   'zp_0000_0': Mod(x + 1, x^2 + x + 1),
+                   'zp_0000_1': Mod(x + 1, x^2 + x + 1),
+                   'zpp_0000_0': Mod(x + 1, x^2 + x + 1),
+                   'zpp_0000_1': Mod(x + 1, x^2 + x + 1)},
+		  is_numerical = False, ...)]]
+
+**Remark**: The shapes will be given as element in the Ptolemy field with defining polynomial being the second argument to ``Mod(..., ...)``, here, x\ :sup:`2`\ +x+1. The Ptolemy field is a (possibly trivial) extension of the shape field. For *N* =2, the Ptolemy field is the trace field [GGZ2014]_ and an iterated square extension of the shape field which is the invariant trace field for a cusped manifold.
+
+And numerically, so that we can compare to SnapPy's shapes::
+
+    >>> zs.numerical()
+    [[],
+     [[CrossRatios(
+           {'z_0000_0': 0.500000000000000 - 0.866025403784439*I,
+            'z_0000_1': 0.500000000000000 - 0.866025403784439*I,
+            'zp_0000_0': 0.500000000000000 - 0.866025403784439*I,
+            'zp_0000_1': 0.500000000000000 - 0.866025403784439*I,
+            'zpp_0000_0': 0.500000000000000 - 0.866025403784439*I,
+            'zpp_0000_1': 0.500000000000000 - 0.866025403784439*I},
+           is_numerical = True, ...),
+       CrossRatios(
+           {'z_0000_0': 0.500000000000000 + 0.866025403784439*I,
+            'z_0000_1': 0.500000000000000 + 0.866025403784439*I,
+            'zp_0000_0': 0.500000000000000 + 0.866025403784439*I,
+            'zp_0000_1': 0.500000000000000 + 0.866025403784439*I,
+            'zpp_0000_0': 0.500000000000000 + 0.866025403784439*I,
+            'zpp_0000_1': 0.500000000000000 + 0.866025403784439*I},
+           is_numerical = True, ...)]]]
+    >>> Manifold("m004").tetrahedra_shapes('rect')
+    [0.5000000000 + 0.8660254038*I, 0.5000000000 + 0.8660254038*I]
+
+The result is of type ``CrossRatios`` and assigns z as well as z'=1/(1-z) and z''=1-1/z a value.
+
+.. _ptolemy-non-zero-dim-comp:
+
+The dimension of a component
+----------------------------
+
+A Ptolemy variety might have positively dimensional components (note that this might or might not be a positively dimensional family of representations, see :ref:`here <ptolemy-generically-decorated>`). For example, the Ptolemy variety for ``m371`` and the trivial obstruction class has a 1-dimensional component. This is indicated by::
+
+    >>> M.ptolemy_variety(2).retrieve_solutions()
+    [NonZeroDimensionalComponent(dimension = 1)]
+
+Or::
+
+    >>> M=Manifold("m371")
+    >>> M.ptolemy_variety(2).retrieve_solutions()
+    [[ 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'])) ]]
+
+The latter actually also provides a sample point (:ref:`witness <ptolemy-example-find-witness>` which we will use :ref:`later <ptolemy-example-non-zero-dim-rep>` to determine whether this corresponds to a 1-dimensional family of representations or not) on the 1-dimensional component. A ``NonZeroDimensionalComponent`` as well as ``PtolemyCoordinates`` (that correspond to 0-dimensional components of the Ptolemy variety)) has a ``dimension`` attribute, so we can do::
+ 
+    >>> M=Manifold("m371")
+    >>> sols = M.ptolemy_variety(2,'all').retrieve_solutions()
+    >>> sols.dimension
+    [[1], [], [0], []]
+
+This means that the Ptolemy variety for the trivial obstruction class has a 1-dimensional component and that the Ptolemy variety of one of the other obstruction classes a 0-dimensional component.
+
+A ``NonZeroDimensionalComponent`` is actually again a list whose elements will be witness points if witnesses have been computed for this Ptolemy variety.
+
+**Warning:** This implies that if we ``flatten`` too much, the reported dimension becomes 0 which is the dimension of the witness point instead of 1::
+
+    >>> sols.flatten()
+    [1, 0]
+    
+Too much ``flatten``::
+    
+    >>> sols.flatten()
+    [0, 0]
+
+The advantage is that we can still call methods such as ``volume_numerical`` and actually see the volume of a witness point (it is known that the volume stays constant on a component of boundary-unipotent representations, so one witness point can tell us the volume of all representation in that component)::
+
+    >>> sols.volume_numerical()
+    [[[ [0.E-38, 0.E-38] (witnesses for NonZeroDimensionalComponent(dimension = 1, free_variables = ['c_0110_2'])) ]],
+     [],
+     [[4.75170196551790,
+       -4.75170196551790,
+       4.75170196551790,
+       -4.75170196551790,
+       1.17563301006556,
+       -1.17563301006556,
+       1.17563301006556,
+       -1.17563301006556]],
+     []]