From b73e2d1579fa4328b105e08e170233ac3037a627 Mon Sep 17 00:00:00 2001 From: Matthias Goerner <1239022+unhyperbolic@users.noreply.github.com> Date: Tue, 23 Jul 2024 19:27:04 -0700 Subject: [PATCH] Another round of documentation clean-up. --- cython/core/manifold.pyx | 21 ++++---- cython/core/triangulation.pyx | 83 +++++++++++++++---------------- python/cusps/cusp_area_matrix.py | 3 +- python/ptolemy/manifoldMethods.py | 50 +++++++++---------- python/snap/nsagetools.py | 3 +- 5 files changed, 77 insertions(+), 83 deletions(-) diff --git a/cython/core/manifold.pyx b/cython/core/manifold.pyx index 3bd5cd8d..67c7f187 100644 --- a/cython/core/manifold.pyx +++ b/cython/core/manifold.pyx @@ -536,15 +536,12 @@ cdef class Manifold(Triangulation): def cover(self, permutation_rep): """ - M.cover(permutation_rep) - - Returns a Manifold representing the finite cover - specified by a transitive permutation representation. The - representation is specified by a list of permutations, one for - each generator of the simplified presentation of the - fundamental group. Each permutation is specified as a list P - such that set(P) == set(range(d)) where d is the degree of the - cover. + Returns a Manifold representing the finite cover specified by a + transitive permutation representation. The representation is + specified by a list of permutations, one for each generator of the + simplified presentation of the fundamental group. Each permutation is + specified as a list ``P`` such such that ``set(P) == set(range(d))`` + where ``d`` is the degree of the cover. >>> M = Manifold('m004') >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) @@ -552,9 +549,9 @@ cdef class Manifold(Triangulation): True - If within Sage, the permutations can also be of type - PermutationGroupElement, in which case they act on the set - range(1, d + 1). Or, you can specify a GAP or Magma subgroup + If within SageMath, the permutations can also be of type + ``PermutationGroupElement``, in which case they act on the set + ``range(1, d + 1)``. Or, you can specify a GAP or Magma subgroup of the fundamental group. Some examples:: sage: M = Manifold('m004') diff --git a/cython/core/triangulation.pyx b/cython/core/triangulation.pyx index 76ad550a..8e8f82bd 100644 --- a/cython/core/triangulation.pyx +++ b/cython/core/triangulation.pyx @@ -347,8 +347,8 @@ cdef class Triangulation(): If the manifold is stored as a link complement in your current session then it returns the number of components and crossing of the link. To view and interact with the - link see :py:meth:`spherogram.Link.view` - and :py:meth:`Manifold.plink`. + link see :meth:`spherogram.Link.view` + and :meth:`plink `. """ if self._PDcode is not None: return spherogram.Link(self._PDcode) @@ -360,7 +360,7 @@ cdef class Triangulation(): cdef set_c_triangulation(self, c_Triangulation* c_triangulation): self.c_triangulation = c_triangulation - def num_cusps(self, cusp_type='all'): + def num_cusps(self, cusp_type='all') -> int: """ Return the total number of cusps. By giving the optional argument 'orientable' or 'nonorientable' it will only count cusps of that type. @@ -1046,7 +1046,7 @@ cdef class Triangulation(): repr += '(%g,%g)'% info['filling'] return repr - def name(self): + def name(self) -> str: """ Return the name of the triangulation. @@ -1058,7 +1058,7 @@ cdef class Triangulation(): return return to_str(get_triangulation_name(self.c_triangulation)) - def set_name(self, new_name): + def set_name(self, new_name : str) -> None: """ Give the triangulation a new name. @@ -1113,7 +1113,7 @@ cdef class Triangulation(): def _set_PDcode(self, code): self._PDcode = code - def num_tetrahedra(self): + def num_tetrahedra(self) -> int: """ Return the number of tetrahedra in the triangulation. @@ -1125,7 +1125,7 @@ cdef class Triangulation(): return 0 return get_num_tetrahedra(self.c_triangulation) - def dehn_fill(self, filling_data, which_cusp=None): + def dehn_fill(self, filling_data, which_cusp=None) -> None: """ Set the Dehn filling coefficients of the cusps. This can be specified in the following ways, where the cusps are numbered @@ -1157,7 +1157,7 @@ cdef class Triangulation(): >>> N m004(-3,4) - Does not return a new Triangulation. + Does not return a new :class:`Triangulation`. """ if self.c_triangulation is NULL: raise ValueError('The Triangulation is empty.') @@ -1421,11 +1421,9 @@ cdef class Triangulation(): v += 1 return ans - def gluing_equations_pgl(self, N=2, equation_type='all'): + def gluing_equations_pgl(self, N : int =2, equation_type='all'): """ - M.gluing_equations_pgl(N = 2, equation_type='all') - Returns a NeumannZagierTypeEquations object that contains a matrix encoding the gluing equations for boundary-parabolic PGL(N,C) representations together with explanations of the meaning @@ -1437,7 +1435,7 @@ cdef class Triangulation(): "Gluing Equations for PGL(n,C)-Representations of 3-Manifolds" (http://arxiv.org/abs/1207.6711). - The result of the traditional gluing_equations() can be obtained from + The result of the :meth:`gluing_equations` can be obtained from the general method by: >>> M = Triangulation('m004') @@ -1463,17 +1461,21 @@ cdef class Triangulation(): The first row of the matrix means that the edge equation for edge 0 is - z_0000_0 ^ 2 * zp_0000_0 * z_0000_1 * zpp_0000_1 ^ 2 = 1. + .. math:: + + {z_{0000,0}}^2 * z'_{0000,0} * z_{0000,1} * {z''_{0000,1}}^2 = 1. Similarly, the next row encodes the edge equation for the other edge and the next two rows encode peripheral equations. - Following the SnapPy convention, a z denotes the cross ratio z at the - edge (0,1), a zp the cross ratio z' at the edge (0,2) and a zpp the cross - ratio z" at the edge (1,2). The entire symbol z_xxxx_y then + Following the SnapPy convention, a ``z`` denotes the cross ratio + :math:`z` at the edge (0,1), a ``zp`` the cross ratio :math:`z'` at + the edge (0,2) and a ``zpp`` the cross + ratio :math:`z''` at the edge (1,2). The entire symbol ``z_xxxx_y`` then denotes the cross ratio belonging to the subsimplex at integral - point xxxx (always 0000 for N = 2) of the simplex y. Note: the - SnapPy convention is different from the paper + point ``xxxx`` (always ``0000`` for ``N = 2``) of the simplex ``y``. + + Note: the SnapPy convention is different from the paper mentioned above, e.g., compare kernel_code/edge_classes.c with Figure 3. We follow the SnapPy convention here so that all computations done in SnapPy are @@ -1487,19 +1489,19 @@ cdef class Triangulation(): ['z_0000_0', 'zp_0000_0', 'zpp_0000_0', 'z_0000_1', 'zp_0000_1', 'zpp_0000_1'] A subset of all gluing equations can be obtained by setting the - equation_type: + ``equation_type``: - * all gluing equations: 'all' - * non-peripheral equations: 'non_peripheral' + * all gluing equations: ``all`` + * non-peripheral equations: ``non_peripheral`` - * edge gluing equations: 'edge' - * face gluing equations: 'face' - * internal gluing equations: 'internal' + * edge gluing equations: ``edge`` + * face gluing equations: ``face`` + * internal gluing equations: ``internal`` - * cusp gluing equations: 'peripheral' + * cusp gluing equations: ``peripheral`` - * cusp gluing equations for meridians: 'meridian' - * cusp gluing equations for longitudes: 'longitude' + * cusp gluing equations for meridians: ``meridian`` + * cusp gluing equations for longitudes: ``longitude`` """ cdef Integer_matrix_with_explanations c_matrix @@ -2359,13 +2361,12 @@ cdef class Triangulation(): def cover(self, permutation_rep): """ - Returns a Triangulation representing the finite cover - specified by a transitive permutation representation. The - representation is specified by a list of permutations, one for - each generator of the simplified presentation of the - fundamental group. Each permutation is specified as a list P - such that set(P) == set(range(d)) where d is the degree of the - cover. + Returns a :class:`Triangulation` representing the finite cover specified + by a transitive permutation representation. The representation is + specified by a list of permutations, one for each generator of the + simplified presentation of the fundamental group. Each permutation is + specified as a list ``P`` such that ``set(P) == set(range(d))`` where + ``d`` is the degree of the cover. >>> M = Triangulation('m004') >>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]]) @@ -2379,10 +2380,10 @@ cdef class Triangulation(): 5 Within Sage the permutations can also be of type - PermutationGroupElement, in which case they act on the set - range(1, d + 1). Or, you can specify a GAP or Magma subgroup - of the fundamental group. For examples, see the docstring for - Manifold.cover + ``PermutationGroupElement``, in which case they act on the set + ``range(1, d + 1)``. Or, you can specify a GAP or Magma subgroup + of the fundamental group. For more examples, see the docstring for + :meth:`Manifold.cover`. """ cdef RepresentationIntoSn* c_representation cdef c_Triangulation* c_triangulation @@ -2459,8 +2460,6 @@ cdef class Triangulation(): def covers(self, degree, method=None, cover_type='all'): """ - M.covers(degree, method=None, cover_type='all') - Returns a list of Triangulations corresponding to all of the finite covers of the given degree. The default method is 'low_index' for general covers and 'snappea' for cyclic @@ -2859,9 +2858,9 @@ cdef class Triangulation(): raise ValueError('The peripheral data %s is not acceptable.' % peripheral_data) - def has_finite_vertices(self): + def has_finite_vertices(self) -> bool: """ - Returns True if and only if the triangulation has finite (non-ideal) + Returns ``True`` if and only if the triangulation has finite (non-ideal) vertices. >>> T = Triangulation("m004") diff --git a/python/cusps/cusp_area_matrix.py b/python/cusps/cusp_area_matrix.py index 7ee9f6eb..08bb301f 100644 --- a/python/cusps/cusp_area_matrix.py +++ b/python/cusps/cusp_area_matrix.py @@ -48,8 +48,7 @@ def cusp_area_matrix(manifold, method='trigDependentTryCanonize', [ 7.0000000000000000? 21.4375000000000000? 7.0000000000000000?] [ 7.0000000000000000? 7.0000000000000000? 21.4375000000000000?] - For expert users - ---------------- + **For expert users** Besides the two values above, ``method`` can be ``trigDependent``: this result is also fast to compute by making the assumption that diff --git a/python/ptolemy/manifoldMethods.py b/python/ptolemy/manifoldMethods.py index 7cc4344f..99bba21e 100644 --- a/python/ptolemy/manifoldMethods.py +++ b/python/ptolemy/manifoldMethods.py @@ -26,7 +26,7 @@ def get_ptolemy_obstruction_classes(manifold): s_f_t takes values +/-1 and is the value of evaluating the cocycle on face f of tetrahedron t. - === Examples === + **Examples** Get the obstruction classes for 4_1: @@ -172,8 +172,9 @@ def compute_solutions(self, *args, **kwargs): for p in self ]) -def get_ptolemy_variety(manifold, N, obstruction_class=None, - simplify=True, eliminate_fixed_ptolemys=False): +def get_ptolemy_variety(manifold, N, obstruction_class = None, + simplify : bool =True, + eliminate_fixed_ptolemys : bool =False): """ Generates Ptolemy variety as described in (1) Garoufalidis, Thurston, Zickert @@ -187,29 +188,26 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None, The variety can be exported to magma or sage and solved there. The solutions can be processed to compute invariants. See below. - === Arguments === + :param N: which SL(N,C) we want the variety. - N --- which SL(N,C) we want the variety. + :param obstruction_class: class from Definition 1.7 of (1). + ``None`` for trivial class, + a value returned from :meth:`get_ptolemy_obstruction_classes`, + an integer indexing the obstruction classes returned from + :meth:`get_ptolemy_obstruction_classes`, + or 'all' to return a list of Ptolemy varieties, one for each + obstruction class. - obstruction_class --- class from Definition 1.7 of (1). - None for trivial class or a value returned from get_ptolemy_obstruction_classes. - Short cuts: obstruction_class = 'all' returns a list of Ptolemy varieties - for each obstruction. For easier iteration, can set obstruction_class to - an integer. + :param simplify: indicate whether to simplify the equations which + significantly reduces the number of variables. Simplifying means that several identified Ptolemy coordinates :math:`x = y = z = ...` + are eliminated instead of adding relations :math:`x - y = 0, y - z = 0, ...` - simplify --- boolean to indicate whether to simplify the equations which - significantly reduces the number of variables. - Simplifying means that several identified Ptolemy coordinates x = y = z = ... - are eliminated instead of adding relations x - y = 0, y - z = 0, ... - Defaults to True. + :param eliminate_fixed_ptolemys: boolean to indicate whether to eliminate + the Ptolemy coordinates that are set to 1 for fixing the decoration. + Even though this simplifies the resulting representation, setting it to + ``True`` can cause magma to run longer when finding a Groebner basis. - eliminate_fixed_ptolemys --- boolean to indicate whether to eliminate - the Ptolemy coordinates that are set to 1 for fixing the decoration. - Even though this simplifies the resulting representation, setting it to - True can cause magma to run longer when finding a Groebner basis. - Defaults to False. - - === Examples for 4_1 === + **Examples for 4_1** >>> from snappy import Manifold >>> M = Manifold("4_1") @@ -248,7 +246,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None, - === If you have a magma installation === + **If you have a magma installation** Call p.compute_solutions() to automatically call magma on the above output and produce exact solutions!!! @@ -258,7 +256,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None, ... except: ... sols = None # magma failed, use precomputed output instead - === If you do not have a magma installation === + **If you do not have a magma installation** Load a precomputed example from magma which is provided with the package: @@ -282,7 +280,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None, >>> if sols is None: # calling magma failed, so use precomputed example ... sols = solutions_from_magma(_magma_output_for_4_1__sl3) - === Continue here whether you have or do not have magma === + **Continue here whether you have or do not have magma** Pick the first solution of the three different solutions (up to Galois conjugates): @@ -306,7 +304,7 @@ def get_ptolemy_variety(manifold, N, obstruction_class=None, >>> len(simplified.equations), len(full.equations) (24, 72) - === ONLY DOCTESTS, NOT PART OF DOCUMENTATION === + **ONLY DOCTESTS, NOT PART OF DOCUMENTATION** >>> varieties = get_ptolemy_variety(M, N = 2, obstruction_class = "all", eliminate_fixed_ptolemys = True) diff --git a/python/snap/nsagetools.py b/python/snap/nsagetools.py index ad312a04..ea490b0c 100644 --- a/python/snap/nsagetools.py +++ b/python/snap/nsagetools.py @@ -332,7 +332,8 @@ def alexander_polynomial(manifold, **kwargs): sage: N.alexander_polynomial() a^2*b + a*b^2 + a*b + a + b - Any provided keyword arguments are passed to fundamental_group and + Any provided keyword arguments are passed to + :meth:`fundamental_group ` and so affect the group presentation used in the computation. """ if manifold.homology().order() != 'infinite':