snappy 3.1.1__cp310-cp310-macosx_11_0_arm64.whl → 3.2__cp310-cp310-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/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -237,6 +237,10 @@ a.headerlink {
     visibility: hidden;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -670,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;
@@ -738,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 {

snappy/doc/_static/css/badge_only.css

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