snappy 3.2__cp310-cp310-macosx_10_12_x86_64.whl

snappy/doc/_sources/spherogram.rst.txt

@@ -0,0 +1,103 @@
+.. Documentation of the Spherogram part of SnapPy
+
+..   automodule:: spherogram
+		     
+Links: planar diagrams and invariants
+=======================================
+
+
+
+Tutorial
+--------
+
+SnapPy includes the `Spherogram
+<https://github.com/3-manifolds/Spherogram>`_ module which allows one to
+create links programmatically.  The graphical conventions used are
+`summarized here
+<https://github.com/3-manifolds/Spherogram/raw/master/spherogram_src/links/doc.pdf>`_.
+
+First, here is the figure-8 knot assembled manually from four crossings, with conventions similar to those used by `KnotTheory <http://katlas.org/wiki/Planar_Diagrams>`_::
+       
+       >>> a, b, c, d = [Crossing(x) for x in 'abcd']
+       >>> a[0], a[1], a[2], a[3] = c[1], d[0], b[1], b[0]
+       >>> b[2], b[3] = d[3], c[2]
+       >>> c[3], c[0] = d[2], d[1]
+       >>> L = Link([a,b,c,d])
+       >>> E = L.exterior()
+       >>> E.volume()
+       2.029883212819
+       >>> Manifold('4_1').is_isometric_to(E)
+       True
+
+We can also give the same knot as a rational tangle::
+
+       >>> L = RationalTangle(3,5).denominator_closure()
+       >>> L.PD_code()
+       [[6, 3, 7, 4], [4, 2, 5, 1], [0, 6, 1, 5], [2, 7, 3, 0]]
+       >>> L.DT_code(True)
+       'DT[dadCDAB]'
+
+The natural algebra of tangles `shown here
+<https://github.com/3-manifolds/Spherogram/raw/master/spherogram_src/links/doc.pdf>`_
+all works.  For instance, we can build the (-2, 3, 7) pretzel knot by
+adding together three rational tangles::
+      
+      >>> T = RationalTangle(-1, 2) + RationalTangle(1, 3) + RationalTangle(1, 7)
+      >>> L = T.numerator_closure()
+      >>> Manifold('m016').is_isometric_to(L.exterior())
+      True
+      
+To create the figure-8 knot as a closed braid, we first mash tangles
+together horizontally using "|" to make the standard braid generators;
+then multiplication in the braid group is just tangle multiplication::
+
+   >>> C, Id = RationalTangle(1), IdentityBraid(1)
+   >>> x = sigma_1 = C | Id
+   >>> y = sigma_2_inverse = Id | -C
+   >>> L = (x*y*x*y).denominator_closure()
+   >>> E = L.exterior()
+   >>> Manifold('4_1').is_isometric_to(E)
+   True
+
+Here's the minimally-twisted five chain from Figure 2 of `this paper
+<http://arxiv.org/abs/math.GT/0209214>`_::
+
+      def twisted_chain(n, k):
+           T = RationalTangle(1, 2)
+	   m = (n+1)//2
+	   base = (m*[T, -T])[:n]
+           tangles = base + [RationalTangle(k)]
+           return sum(tangles, RationalTangle(0) ).bridge_closure()
+
+      >>> L = twisted_chain(5, -1)
+      >>> L.exterior().volume()
+      10.14941606410
+
+Spherogram includes ways to create very large random links, see below.
+When used inside `Sage <http://sagemath.org>`_, one can compute many
+basic link invariants, including the Jones polynomial.  See the
+complete list of Link methods below.  
+
+  
+Random Links
+------------
+
+.. autofunction:: spherogram.random_link
+
+
+The Link class
+--------------
+
+.. autoclass:: spherogram.Link
+   :members:
+   :inherited-members:
+   :undoc-members:
+
+The ClosedBraid class
+---------------------
+
+The ClosedBraid class provides an alternative way to construct links
+as closed braids.  It is a subclass of Link, and currently defines
+the same methods and attributes.
+
+.. autoclass:: spherogram.ClosedBraid

snappy/doc/_sources/todo.rst.txt

@@ -0,0 +1,47 @@
+To Do List
+==========
+
+- For a more current list, see the GitHub `issues list
+  <https://github.com/3-manifolds/SnapPy/issues>`_.
+
+- GUI
+  
+  - Allow you to get the info (position, radius) of a horoball by clicking it.  
+
+- Documentation
+
+  - More hyperlinks
+
+  - Expand tutorial 
+
+  - Make more screencasts
+
+- snappy 
+  
+- Kernel 
+
+- Minor 
+
+  - dual_curves should really cache its result and have this used by
+    drill
+  
+  - One should be able to convert a SymmetryGroup to a Sage permutation group.   
+
+  - Also, the SymmetryGroup presentation function should be wrapped.
+    There is code for this in the old SnapPeaPython.  
+
+- Ambitious
+
+  - A new basic (sub)class: S3Knot (and/or S3Link).
+ 
+  - Consider adding a HeegaardSplitting class 
+
+  - Consider merging our t3m project and normal surface code into
+    SnapPy. 
+
+  - Redo much of Snap in the context of Sage/SnapPy.   
+
+     - Add a method for computing tetrahedron shapes to arbitrary precision.
+
+     - Add methods for computing invariant trace fields and related number
+       fields.

snappy/doc/_sources/triangulation.rst.txt

@@ -0,0 +1,11 @@
+.. Documentation of the Python part of SnapPy
+
+Triangulation
+=================
+
+The main snappy class, namely Manifold, is derived from the more
+basic class below.
+
+..   autoclass:: snappy.Triangulation
+     :members:
+     :inherited-members:

snappy/doc/_sources/tutorial.rst.txt

@@ -0,0 +1,49 @@
+========
+Tutorial
+========
+
+The easiest way to learn to use SnapPy is to watch the screencasts
+available on `YouTube <http://youtube.com/user/NathanDunfield>`_:
+
+- Intro and quickstart: an 11 minute video with the basics: `Part I
+  <http://www.youtube.com/watch?v=ezo19L-JTTI>`_ and `Part II
+  <http://www.youtube.com/watch?v=Js4qwyIs-Oo>`_. 
+
+- An hour-long demo `Practical computation with hyperbolic
+  3-manifolds <http://youtu.be/j8enbAkAvdY>`_, recorded at the Thurston Memorial
+  Conference.
+
+- The SnapPy 2.0 `new feature demo <http://youtu.be/bCYe_a48viA>`_.
+
+- `SnapPy, SageMath, and Docker are friends
+  <https://icerm.brown.edu/video_archive/?play=1992>`_ with associated
+  `materials (4 pages), including homework
+  <https://icerm.brown.edu/materials/Abstracts/tw19-3-pods/Computation_Demonstration_2_]_Nathan_Dunfield,_University_of_Illinois,_Urbana-Champaign.pdf>`_.
+
+- `Notes, problem sheets, and references
+  <http://dunfield.info/warwick2017/>`_ from the LMS-CMI Research
+  School in Warwick in 2017.
+
+- Another hour-long demo `Practical computations with hyperbolic
+  3-manifolds <https://icerm.brown.edu/video_archive/?play=1856>`_
+  given at ICERM in 2019.
+
+The **key** thing to remember when using the SnapPy command shell window is
+that you can explore objects using introspection and tab-completion::
+
+     In [1]: Manifold? <hit return-key>
+     ...instructions for creating a manifold...
+
+So now we create a manifold::
+
+   In [2]: M = Manifold("m004")
+
+But what can we do with it?  ::
+
+    In [3]: M.<hit tab-key>
+    ...list of methods...
+
+What does the "cover" method do? ::
+     
+     In [4]: M.cover? <hit return-key>
+     ...description of cover method..

snappy/doc/_sources/verify.rst.txt

@@ -0,0 +1,210 @@
+Verified computations
+========================================
+
+.. _verify-primer:
+
+Introduction
+------------
+
+Several SnapPy methods use numerical computations with floating point
+approximations and can potentially result in incorrect results. This even
+applies to methods whose output is purely combinatorial such as
+:meth:`~snappy.Manifold.canonical_retriangulation`.
+
+Many of these SnapPy methods can be supplied with a :attr:`verified` flag to
+ensure that the result is provably correct. Note that verified computations are
+only available when using SnapPy inside `SageMath <http://sagemath.org>`_.
+If the flag :attr:`verified=True` is specified, an incorrect result is
+never returned. Instead the method clearly indicates a failure, usually through
+an exception::
+
+  sage: M=Manifold("m004")
+  sage: M.drill_word('abc', verified=True, bits_prec = 40)
+  ...
+  InsufficientPrecisionError: When re-tracing the geodesic, the intersection with the next tetrahedron face was too close to the previous to tell them apart. Increasing the precision will probably avoid this problem.
+
+Often, such a failure can be advoided by increasing the precision. In
+particular, this applies if the exception is a (subclass of)
+:class:`InsufficientPrecisionError`::
+         
+  sage: M.drill_word('abc', verified=True, bits_prec = 60)
+  m004_drilled(0,0)(0,0)
+
+Note that, :meth:`~snappy.Manifold.verify_hyperbolicity` is different though
+and does not throw an exception. Instead, it returns a bool indicating success
+as part of its output. This is for compatibility with
+`HIKMOT <http://www.oishi.info.waseda.ac.jp/~takayasu/hikmot/>`_'s
+``verify_hyperbolicty``::
+
+  sage: M.verify_hyperbolicity(bits_prec=10)
+  (False, [])
+  sage: M.verify_hyperbolicity()
+  (True,
+   [0.50000000000000? + 0.86602540378444?*I,
+    0.50000000000000? + 0.86602540378444?*I])
+
+As illustrated above, the result consists of intervals
+(of type SageMath's ``RealIntervalField`` or
+``ComplexIntervalField``) if the output of a computation is numerical
+and :attr:`verified=True` is specified. These intervals contain the true
+value.
+
+Overview
+--------
+
+Some examples of verified computations are:
+
+* Verify the hyperbolicity
+  of an orientable 3-manifold giving complex intervals for the
+  shapes corresponding to a hyperbolic structure or holonomy representation with
+  :meth:`~snappy.Manifold.verify_hyperbolicity`::
+
+   sage: M = Manifold("m015")
+   sage: M.verify_hyperbolicity()
+   (True,
+    [0.6623589786224? + 0.5622795120623?*I,
+     0.6623589786224? + 0.5622795120623?*I,
+     0.6623589786224? + 0.5622795120623?*I])
+   sage: M.verify_hyperbolicity(holonomy=True)[1].SL2C('a')
+   [-0.324717957? - 1.124559024?*I -0.704807293? + 0.398888830?*I]
+   [ 1.409614585? - 0.797777659?*I       -1.000000000? + 0.?e-9*I]
+
+* Intervals for the volume and complex volume of a hyperbolic orientable 3-manifold::
+
+   sage: M = Manifold("m003(-3,1)")
+   sage: M.volume(verified=True, bits_prec = 100)
+   0.942707362776927720921299603?
+   sage: M = Manifold("m015")
+   sage: M.complex_volume(verified_modulo_2_torsion=True)
+   2.8281220883? + 1.9106738240?*I
+
+  (Note that when using verified computation, the Chern-Simons invariant is only computed
+  modulo pi^2/2 even though it is defined modulo pi^2.)
+
+* Give the (a close relative to the canonical cell decomposition) of a cusped
+  hyperbolic manifold using intervals or exact arithmetic if necessary with
+  :meth:`~snappy.Manifold.canonical_retriangulation`::
+
+   sage: M = Manifold("m412")
+   sage: K = M.canonical_retriangulation(verified = True)
+   sage: len(K.isomorphisms_to(K)) # Certified size of isometry group
+   8
+ 
+  **Remark:** For the case of non-tetrahedral canonical cell, exact values
+  are used which are found
+  using the   `LLL-algorithm 
+  <http://en.wikipedia.org/wiki/Lenstra%E2%80%93Lenstra%E2%80%93Lov%C3%A1sz_lattice_basis_reduction_algorithm>`_
+  and then verified using exact computations. These computations can be slow. A massive speed-up was achieved by
+  recent improvements so that the computation of the isometry signature of any manifold in ``OrientableCuspedCensus``
+  takes at most a couple of seconds, typically, far less. Manifolds with more simplices might require setting
+  a higher value for 
+  :attr:`exact_bits_prec_and_degrees`.
+
+* The isometry signature which is a complete invariant of the isometry type
+  of a cusped hyperbolic manifold (i.e., two manifolds are isometric if and only
+  if they have the same isometry signature)::
+
+   sage: M = Manifold("m412")
+   sage: M.isometry_signature(verified = True)
+   'mvvLALQQQhfghjjlilkjklaaaaaffffffff'
+
+  The isometry signature can be strengthened to include the peripheral curves
+  such that it is a complete invariant of a hyperbolic link::
+
+   sage: M = Manifold("L5a1")
+   sage: M.isometry_signature(of_link = True, verified = True)
+   'eLPkbdcddhgggb_baCbbaCb'
+
+  See :meth:`~snappy.Manifold.isometry_signature` for details.
+
+  **Remark:** The isometry signature is based on the canonical
+  retriangulation so the same warning applies.
+
+* The maximal cusp area matrix which characterizes the configuration
+  space of disjoint cusp neighborhoods with
+  :meth:`~snappy.Manifold.cusp_area_matrix`::
+
+   sage: M=Manifold("m203")
+   sage: M.cusp_area_matrix(method='maximal', verified=True)
+   [   27.000000? 9.0000000000?]
+   [9.0000000000?   27.0000000?]
+
+  In this example, the cusp neighborhood about cusp 0 or 1 is only
+  embedded if and only if its area is less than sqrt(27). The cusp
+  neighborhood about cusp 0 is only disjoint from the one about cusp 1
+  if and only if the product of their areas is less than 9.
+
+* Compute areas for disjoint cusp neighborhoods with
+  :meth:`~snappy.Manifold.cusp_areas`::
+
+   sage: M=Manifold("m203")
+   sage: M.cusp_areas(policy = 'unbiased', method='maximal', verified = True)
+   [3.00000000000?, 3.00000000000?]
+
+  With the above parameters, the result is intrinsic to the hyperbolic
+  manifold with labeled cusped.
+
+* Find all slopes of length less or equal to 6 when measured on the boundary
+  of disjoint cusp neighborhoods::
+
+   sage: M=Manifold("m203")
+   sage: M.short_slopes(policy = 'unbiased', method='maximal', verified = True)
+   [[(1, 0), ...,  (1, 2)], [(1, 0), ...,  (1, 2)]]
+
+  First block has all short slopes for first cusp, ..., see
+  :meth:`~snappy.Manifold.short_slopes` for details.
+
+  By `Agol's <http://arxiv.org/abs/math/9906183>`_ and `Lackenby's
+  <http://arxiv.org/abs/math/9808120>`_ 6-Theorem any Dehn-filling
+  resulting in a non-hyperbolic manifold must contain one of the above
+  slopes.  Thus, :meth:`~snappy.Manifold.short_slopes` can be used
+  to implement the techniques to find exceptional Dehn surgeries
+  (`arXiv:1109.0903 <https://arxiv.org/abs/1109.0903>`_ and
+  `arXiv:1310.3472 <https://arxiv.org/abs/1310.3472>`_).
+
+* An example of finding all geodesics up to length 1::
+
+    sage: from sage.all import RIF
+    sage: L = RIF(1)
+    sage: M = Manifold("m003")
+    sage: spec = M.length_spectrum_alt_gen(verified=True)
+    sage: n = 0
+    sage: for g in spec:
+    ...       if g.length.real() > L:
+    ...           break # Done! All subsequent geodesics will be longer.
+    ...       if g.length.real() < L:
+    ...           n += 1
+    ...           continue
+    ...       raise Exception("Interval too large. Increase precision.")
+    sage: n
+    4
+
+Additionally, we can compute complex intervals for the shapes that are
+guaranteed to contain a true solution to the rectangular gluing equations
+that is not necessarily a geometric solution (specify :attr:`bits_prec`
+or :attr:`dec_prec` for higher precision intervals.)::
+
+      sage: M = Manifold("m015(3,1)")
+      sage: M.tetrahedra_shapes('rect', intervals=True)
+      [0.625222762246? + 3.177940133813?*I,
+       -0.0075523593782? + 0.5131157955971?*I,
+       0.6515818912107? - 0.1955023488930?*I]
+
+This is all based on a reimplementation of `HIKMOT
+<http://www.oishi.info.waseda.ac.jp/~takayasu/hikmot/>`_ which
+pioneered the use of interval methods for hyperbolic manifolds (also see
+`Zgliczynski's notes <http://ww2.ii.uj.edu.pl/~zgliczyn/cap07/krawczyk.pdf>`_). It
+can be used in a way very similar to HIKMOT, but uses Sage's complex
+interval types for certification. It furthermore makes use of code by 
+`Dunfield, Hoffman, Licata <http://arxiv.org/abs/1407.7827/>`_.
+
+This verification code was contributed by Matthias Goerner.  
+
+
+Verified computation topics
+---------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   verify_internals

snappy/doc/_sources/verify_internals.rst.txt

@@ -0,0 +1,79 @@
+Internals of verified computations
+==================================
+
+
+
+Naming
+------
+
+The names of methods containing ``check`` will raise an exception if
+the desired property cannot be certified. There are different types of
+Exceptions to indicate how the certification failed. This type can be
+used by other methods to perform some action such as changing the
+triangulation or increasing precision or to give up.
+
+The user-facing methods have names starting with ``verify`` or
+``verified`` and will fail more gracefully returning ``False`` or
+``None`` in such a case.
+
+
+
+Generating certified shape intervals
+------------------------------------
+
+The recommended way to obtain certified intervals for the shapes is via
+``manifold.tetrahedra_shapes(intervals=True)`` as :doc:`described
+earlier <verify>`. Here we document the ``KrawczykShapesEngine`` and
+``IntervalNewtonShapesEngine`` which is implemented internally to
+generate the intervals. It is of interest for those users who want to
+understand the underlying interval math and experiment with the Newton
+interval method or the Krawczyk test.  ``CertifiedShapesEngine`` is an
+alias of either ``KrawczykShapesEngine`` or
+``IntervalNewtonShapesEngine`` to determine the default method used by
+verify.
+
+..   automodule:: snappy.verify
+..   autoclass:: CertifiedShapesEngine
+     :members:
+     :inherited-members:
+
+..   autoclass:: IntervalNewtonShapesEngine
+     :members:
+     :inherited-members:
+
+..   autoclass:: KrawczykShapesEngine
+     :members:
+     :inherited-members:
+
+
+Verification of hyperbolicity
+-----------------------------
+
+Methods containing ``check`` will raise an exception if the desired property
+cannot be certified. Methods containing ``verify`` or ``verified`` will fail
+more gracefully returning ``False`` or ``None`` in such a case.
+
+..   autofunction:: snappy.verify.hyperbolicity.check_logarithmic_gluing_equations_and_positively_oriented_tets
+
+Verified canonical cell decompositions
+--------------------------------------
+
+..   autofunction:: snappy.verify.canonical.interval_checked_canonical_triangulation
+..   autofunction:: snappy.verify.canonical.exactly_checked_canonical_retriangulation
+
+Exact computations for cusp cross sections
+------------------------------------------
+
+..   automodule:: snappy.verify.square_extensions
+
+..   autofunction:: snappy.verify.square_extensions.find_shapes_as_complex_sqrt_lin_combinations
+..   autoclass:: SqrtLinCombination
+     :members:
+..   autoclass:: ComplexSqrtLinCombination
+     :members:
+
+Exceptions
+----------
+
+..   automodule:: snappy.verify.exceptions
+     :members:

snappy/doc/_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}