snappy 3.0.3__cp38-cp38-macosx_11_0_arm64.whl → 3.2__cp38-cp38-macosx_11_0_arm64.whl

snappy/doc/_sources/verify.rst.txt

@@ -1,27 +1,63 @@
 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
 --------
 
-When used inside `Sage <http://sagemath.org>`_, SnapPy can verify the
-following computations:
-
-* Complex intervals for the shapes that are guaranteed to contain a true
-  but not necessarily geometric solution to the rectangular gluing equations::
-
-      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]
+Some examples of verified computations are:
 
-  (Specify :py:attr:`bits_prec` or :py:attr:`dec_prec` for higher precision intervals.)
-  
 * Verify the hyperbolicity
   of an orientable 3-manifold giving complex intervals for the
   shapes corresponding to a hyperbolic structure or holonomy representation with
-  :py:meth:`~snappy.Manifold.verify_hyperbolicity`::
+  :meth:`~snappy.Manifold.verify_hyperbolicity`::
 
    sage: M = Manifold("m015")
    sage: M.verify_hyperbolicity()
@@ -45,10 +81,9 @@ following computations:
   (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 :doc:`canonical retriangulation <verify_canon>` (a close
-  relative to the canonical cell decomposition) of a cusped hyperbolic
-  manifold using intervals or exact arithmetic if necessary with
-  :py:meth:`~snappy.Manifold.canonical_retriangulation`::
+* 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)
@@ -63,9 +98,9 @@ following computations:
   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 
-  :py:attr:`exact_bits_prec_and_degrees`.
+  :attr:`exact_bits_prec_and_degrees`.
 
-* The :doc:`isometry signature <verify_canon>` which is a complete invariant of the isometry type
+* 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)::
 
@@ -80,14 +115,14 @@ following computations:
    sage: M.isometry_signature(of_link = True, verified = True)
    'eLPkbdcddhgggb_baCbbaCb'
 
-  See :py:meth:`~snappy.Manifold.isometry_signature` for details.
+  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
-  :py:meth:`~snappy.Manifold.cusp_area_matrix`::
+  :meth:`~snappy.Manifold.cusp_area_matrix`::
 
    sage: M=Manifold("m203")
    sage: M.cusp_area_matrix(method='maximal', verified=True)
@@ -100,7 +135,7 @@ following computations:
   if and only if the product of their areas is less than 9.
 
 * Compute areas for disjoint cusp neighborhoods with
-  :py:meth:`~snappy.Manifold.cusp_areas`::
+  :meth:`~snappy.Manifold.cusp_areas`::
 
    sage: M=Manifold("m203")
    sage: M.cusp_areas(policy = 'unbiased', method='maximal', verified = True)
@@ -117,25 +152,51 @@ following computations:
    [[(1, 0), ...,  (1, 2)], [(1, 0), ...,  (1, 2)]]
 
   First block has all short slopes for first cusp, ..., see
-  :py:meth:`~snappy.Manifold.short_slopes` for details.
+  :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, :py:meth:`~snappy.Manifold.short_slopes` can be used
+  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/>`_. The code to
-compute the isomorphism signature was ported over from
-`Regina <https://regina-normal.github.io/>`_.
+`Dunfield, Hoffman, Licata <http://arxiv.org/abs/1407.7827/>`_.
 
 This verification code was contributed by Matthias Goerner.  
 
@@ -146,5 +207,4 @@ Verified computation topics
 .. toctree::
    :maxdepth: 1
 
-   verify_canon   
    verify_internals

snappy/doc/_sources/verify_internals.rst.txt

@@ -53,31 +53,20 @@ 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.verifyHyperbolicity.check_logarithmic_gluing_equations_and_positively_oriented_tets
-
-Cusp cross sections
--------------------
-
-..   autoclass:: snappy.verify.RealCuspCrossSection
-     :members:
-     :inherited-members:
-
-..   autoclass:: snappy.verify.ComplexCuspCrossSection
-     :members:
-     :inherited-members:
+..   autofunction:: snappy.verify.hyperbolicity.check_logarithmic_gluing_equations_and_positively_oriented_tets
 
 Verified canonical cell decompositions
 --------------------------------------
 
-..   autofunction:: snappy.verify.verifyCanonical.interval_checked_canonical_triangulation
-..   autofunction:: snappy.verify.verifyCanonical.exactly_checked_canonical_retriangulation
+..   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.squareExtensions
+..   automodule:: snappy.verify.square_extensions
 
-..   autofunction:: snappy.verify.squareExtensions.find_shapes_as_complex_sqrt_lin_combinations
+..   autofunction:: snappy.verify.square_extensions.find_shapes_as_complex_sqrt_lin_combinations
 ..   autoclass:: SqrtLinCombination
      :members:
 ..   autoclass:: ComplexSqrtLinCombination

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;
+}

snappy/doc/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -222,7 +222,7 @@ table.modindextable td {
 /* -- general body styles --------------------------------------------------- */
 
 div.body {
-    min-width: 450px;
+    min-width: 360px;
     max-width: 800px;
 }
 
@@ -237,14 +237,8 @@ a.headerlink {
     visibility: hidden;
 }
 
-a.brackets:before,
-span.brackets > a:before{
-    content: "[";
-}
-
-a.brackets:after,
-span.brackets > a:after {
-    content: "]";
+a:visited {
+    color: #551A8B;
 }
 
 h1:hover > a.headerlink,
@@ -335,12 +329,16 @@ p.sidebar-title {
     font-weight: bold;
 }
 
+nav.contents,
+aside.topic,
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
 
+nav.contents,
+aside.topic,
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -379,6 +377,8 @@ div.body p.centered {
 
 div.sidebar > :last-child,
 aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
@@ -386,6 +386,8 @@ div.admonition > :last-child {
 
 div.sidebar::after,
 aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -428,10 +430,6 @@ table.docutils td, table.docutils th {
     border-bottom: 1px solid #aaa;
 }
 
-table.footnote td, table.footnote th {
-    border: 0 !important;
-}
-
 th {
     text-align: left;
     padding-right: 5px;
@@ -615,19 +613,26 @@ ul.simple p {
     margin-bottom: 0;
 }
 
-dl.footnote > dt,
-dl.citation > dt {
+aside.footnote > span,
+div.citation > span {
     float: left;
-    margin-right: 0.5em;
 }
-
-dl.footnote > dd,
-dl.citation > dd {
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
     margin-bottom: 0em;
 }
-
-dl.footnote > dd:after,
-dl.citation > dd:after {
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
     content: "";
     clear: both;
 }
@@ -644,10 +649,6 @@ dl.field-list > dt {
     padding-right: 5px;
 }
 
-dl.field-list > dt:after {
-    content: ":";
-}
-
 dl.field-list > dd {
     padding-left: 0.5em;
     margin-top: 0em;
@@ -673,6 +674,16 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
 dl > dd:last-child,
 dl > dd:last-child > :last-child {
     margin-bottom: 0;
@@ -741,6 +752,14 @@ abbr, acronym {
     cursor: help;
 }
 
+.translated {
+    background-color: rgba(207, 255, 207, 0.2)
+}
+
+.untranslated {
+    background-color: rgba(255, 207, 207, 0.2)
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {
@@ -757,6 +776,7 @@ span.pre {
     -ms-hyphens: none;
     -webkit-hyphens: none;
     hyphens: none;
+    white-space: nowrap;
 }
 
 div[class*="highlight-"] {

snappy/doc/_static/css/badge_only.css

@@ -0,0 +1 @@
+.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}