Manifold: the main class

class snappy.Manifold(spec=None)

A Manifold is a Triangulation together with a geometric structure. That is, a Manifold is an ideal triangulation of the interior of a compact 3-manifold with torus boundary, where each tetrahedron has has been assigned the geometry of an ideal tetrahedron in hyperbolic 3-space. A Dehn-filling can be specified for each boundary component, allowing the description of closed 3-manifolds and some orbifolds. Here’s a quick example:

>>> M = Manifold('9_42')
>>> M.volume()
4.05686022
>>> M.cusp_info('shape')
[-4.27893632 + 1.95728680*I]

A Manifold can be specified in a number of ways, e.g.

  • Manifold(‘9_42’) : The complement of the knot 9_42 in S^3.
  • Manifold(‘m125(1,2)(4,5)’) : The SnapPea census manifold m125 where the first cusp has Dehn filling (1,2) and the second cusp has filling (4,5).
  • Manifold() : Opens a link editor window where can you specify a link complement.

In general, the specification can be from among the below, with information on Dehn fillings added.

  • SnapPea cusped census manifolds: e.g. ‘m123’, ‘s123’, ‘v123’.

  • Link complements:
    • Rolfsen’s table: e.g. ‘4_1’, ‘04_1’, ‘5^2_6’, ‘6_4^7’, ‘L20935’, ‘l104001’.
    • Hoste-Thistlethwaite Knotscape table: e.g. ‘11a17’ or ‘12n345’
    • Callahan-Dean-Weeks-Champanerkar-Kofman-Patterson knots: e.g. ‘K6_21’.
    • Dowker-Thistlethwaite code: e.g. ‘DT:[(6,8,2,4)]’
  • Once-punctured torus bundles: e.g. ‘b++LLR’, ‘b+-llR’, ‘bo-RRL’, ‘bn+LRLR’

  • Fibered manifold associated to a braid: ‘Braid[1,2,-3,4]’

    Here, the braid is thought of as a mapping class of the punctured disc, and this manifold is the corresponding mapping torus. If you want the braid closure, do (1,0) filling of the last cusp.

  • From mapping class group data using Twister:

    ‘Bundle(S_{1,1}, [a0, B1])’ or ‘Splitting(S_{1,0}, [b1, A0], [a0,B1])’

    See the help for the ‘twister’ module for more.

  • A SnapPea triangulation or link projection file: ‘filename’

    The file will be loaded if found in the current directory or the path given by the shell variable SNAPPEA_MANIFOLD_DIRECTORY.

  • A string containing the contents of a SnapPea triangulation or link projection file.

DT_code(alpha=False, flips=False)

Return the Dowker-Thistlethwaite code of this link complement, if it is a link complement. The DT code is intended to be an immutable attribute, for use with knot and link exteriors only, which is set only when the manifold was created.

Here is the Whitehead link:

>>> M = Manifold('L5a1')
>>> M.DT_code()
[(6, 8), (2, 10, 4)]
>>> M.DT_code(alpha=True)
'ebbccdaeb'
>>> M.DT_code(alpha=True, flips=True)
'ebbccdaeb.01110'
>>> M.DT_code(flips=True)
([(6, 8), (2, 10, 4)], [0, 1, 1, 1, 0])
alexander_polynomial(**kwargs)

Computes the multivariable Alexander polynomial of the manifold:

sage: M = Manifold('K12n123')
sage: M.alexander_polynomial()
2*a^6 - 14*a^5 + 34*a^4 - 45*a^3 + 34*a^2 - 14*a + 2

sage: N = Triangulation('v1539(5,1)')
sage: N.alexander_polynomial()
a^2*b + a*b^2 + a*b + a + b

Any provided keyword arguments are passed to fundamental_group and so affect the group presentation used in the computation.

browse()
>>> M = Manifold('m125')
>>> M.browse() # Opens browser window  
canonical_retriangulation(verified=False, interval_bits_precs=[53, 212], exact_bits_prec_and_degrees=[(212, 10), (1000, 20), (2000, 20)], verbose=False)

The canonical retriangulation which is closely related to the canonical cell decomposition and described in more detail here:

>>> M = Manifold("m412")
>>> K = M.canonical_retriangulation()
>>> len(K.isomorphisms_to(K)) # Unverified size of the isometry group.
8

When used inside Sage and verified = True is passed as argument, the verify module will certify the result to be correct:

sage: M = Manifold("m412")
sage: K = M.canonical_retriangulation(verified = True)
sage: len(K.isomorphisms_to(K)) # Verified size of the isometry group.
8

See verify.verified_canonical_retriangulation() for the additional options.

canonize()

Change the triangulation to an arbitrary retriangulation of the canonical cell decomposition.

>>> M = Manifold('m007')
>>> M.num_tetrahedra()
3
>>> M.canonize()
>>> M.num_tetrahedra()
4

Note: due to rounding error, it is possible that this is not actually the canonical triangulation.

chern_simons()

Returns the Chern-Simons invariant of the manifold, if it is known.

>>> M = Manifold('m015')
>>> M.chern_simons()
-0.15320413

The return value has an extra attribute, accuracy, which is the number of digits of accuracy as estimated by SnapPea.

>>> M.chern_simons().accuracy in (8, 9, 57) # Low and High precision
True

By default, when the manifold has at least one cusp, Zickert’s algorithm is used; when the manifold is closed we use SnapPea’s original algorithm, which is based on Meyerhoff-Hodgson-Neumann.

Note: When computing the Chern-Simons invariant of a closed manifold, one must sometimes compute it first for the unfilled manifold so as to initialize SnapPea’s internals. For instance,

>>> M = Manifold('5_2')
>>> M.chern_simons()
-0.15320413
>>> M.dehn_fill( (1,2) )
>>> M.chern_simons()
0.07731787

works, but will fail with ‘Chern-Simons invariant not currently known’ if the first call to chern_simons is not made.

complex_volume()
Returns the complex volume, i.e.
volume + i 2 pi^2 (chern simons)
>>> M = Manifold('5_2')
>>> M.complex_volume()
2.82812209 - 3.02412838*I
>>> M = Manifold("3_1")
>>> M.complex_volume()
0 - 1.64493407*I
copy()

Returns a copy of the manifold

>>> M = Manifold('m015')
>>> N = M.copy()
cover(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.

>>> M = Manifold('m004')
>>> N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]])
>>> abs(N0.volume()/M.volume() - 5) < 0.0000000001
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 of the fundamental group. Some examples:

sage: M = Manifold('m004')

The basic method:

sage: N0 = M.cover([[1, 3, 0, 4, 2], [0, 2, 1, 4, 3]])

From a Gap subgroup:

sage: G = gap(M.fundamental_group())
sage: H = G.LowIndexSubgroupsFpGroup(5)[9]
sage: N1 = M.cover(H)
sage: N0 == N1
True

Or a homomorphism to a permutation group:

sage: f = G.GQuotients(PSL(2,7))[1]
sage: N2 = M.cover(f)
sage: N2.volume()/M.volume()
8.00000000

Or maybe we want larger cover coming from the kernel of this:

sage: N3 = M.cover(f.Kernel())
sage: N3.volume()/M.volume()
168.00000000

Check the homology against what Gap computes directly:

sage: N3.homology().betti_number()
32
sage: len([ x for x in f.Kernel().AbelianInvariants().sage() if x == 0])
32

We can do the same for Magma:

sage: G = magma(M.fundamental_group())             #doctest: +SKIP
sage: Q, f = G.pQuotient(5, 1, nvals = 2)          #doctest: +SKIP
sage: M.cover(f.Kernel()).volume()                 #doctest: +SKIP
10.14941606
sage: h = G.SimpleQuotients(1, 11, 2, 10000)[1,1]  #doctest: +SKIP
sage: N4 = M.cover(h)                              #doctest: +SKIP
sage: N2 == N4                                     #doctest: +SKIP
True
cover_info()

If this is a manifold or triangulation which was constructed as a covering space, return a dictionary describing the cover. Otherwise return 0. The dictionary keys are ‘base’, ‘type’ and ‘degree’.

covers(degree, method=None, cover_type='all')

M.covers(degree, method=None)

Returns a list of Manifolds corresponding to all of the finite covers of the given degree.

WARNING: If the degree is large this might take a very, very, very long time.

>>> M = Manifold('m003')
>>> covers = M.covers(4)
>>> [(N, N.homology()) for N in covers]
[(m003~irr~0(0,0)(0,0), Z/5 + Z + Z), (m003~cyc~1(0,0), Z/3 + Z/15 + Z)]

You can also look just at cyclic covers, which is much faster.

>>> covers = M.covers(4, cover_type='cyclic')
>>> [(N, N.homology()) for N in covers]
[(m003~cyc~0(0,0), Z/3 + Z/15 + Z)]

If you are using Sage, you can use GAP to find the subgroups, which is often much faster, by specifying the optional argument method = ‘gap’ If you have Magma installed, you can used it to do the heavy lifting by specifying method=’magma’.

cusp_info(data_spec=None)

Returns an info object containing information about the given cusp. Usage:

>>> M = Manifold('v3227(0,0)(1,2)(3,2)')
>>> M.cusp_info(1)
Cusp 1 : torus cusp with Dehn filling coeffients (M, L) = (1.0, 2.0)

To get more detailed information about the cusp, we do

>>> c = M.cusp_info(0)
>>> c.shape
0.11044502 + 0.94677098*I
>>> c.modulus
-0.12155872 + 1.04204128*I
>>> sorted(c.keys())
['filling', 'holonomies', 'holonomy_accuracy', 'index', 'is_complete', 'modulus', 'shape', 'shape_accuracy', 'topology']

Here ‘shape’ is the shape of the cusp, i.e. (longitude/meridian) and ‘modulus’ is its shape in the geometrically preferred basis, i.e. ( (second shortest translation)/(shortest translation)). For cusps that are filled, one instead cares about the holonomies:

>>> M.cusp_info(-1)['holonomies']
(-0.59883089 + 1.09812548*I, 0.89824633 + 1.49440443*I)

The complex numbers returned for the shape and for the two holonomies have an extra attribute, accuracy, which is SnapPea’s estimate of their accuracy.

You can also get information about multiple cusps at once:

>>> M.cusp_info()
[Cusp 0 : complete torus cusp of shape 0.11044502 + 0.94677098*I,
 Cusp 1 : torus cusp with Dehn filling coeffients (M, L) = (1.0, 2.0),
 Cusp 2 : torus cusp with Dehn filling coeffients (M, L) = (3.0, 2.0)]
>>> M.cusp_info('is_complete')
[True, False, False]
cusp_neighborhood()

Returns information about the cusp neighborhoods of the manifold, in the form of data about the corresponding horoball diagrams in hyperbolic 3-space.

>>> M = Manifold('s000')
>>> CN = M.cusp_neighborhood()
>>> CN.volume()
0.32475953
>>> len(CN.horoballs(0.01))
178
>>> CN.view()  # Opens picture of the horoballs  
cusp_translations(areas=None, canonize=True, verified=False, bits_prec=None)

Chooses disjoint cusp neighborhoods and returns the respective (complex) Euclidean translations of the meridian and longitude for each cusp. When choosing the disjoint cusp neighborhoods, the method tries to make them as large as possible but the result might not be optimal, depending on the triangulation, and might be non-deterministic.

The result is a list of pairs, the second entry corresponding to a longitude is always real:

>>> M = Manifold("s776")
>>> M.cusp_translations()
[(0.43472087 + 1.15016332*I, 1.73888349), (0.35355339 + 0.93541435*I, 1.41421356), (0.57508166 + 1.52152305*I, 2.30032663)]

This method supports arbitrary precision

>>> from snappy.number import Number
>>> acc, Number._accuracy_for_testing = Number._accuracy_for_testing, None
>>> M.cusp_translations(bits_prec = 120) 
[(0.43472087... + 1.1501633...*I, 1.7388834...), (0.35355339... + 0.9354143...*I, 1.41421356...), (0.5750816... + 1.52152305...*I, 2.30032663...)]
>>> Number._accuracy_for_testing = acc

and can return verified intervals

sage: M.cusp_translations(verified = True) # doctest: +ELLIPSIS
[(0.434720872...? + 1.15016331...?*I, 1.73888348...?), (0.353553390...? + 0.9354143467...?*I, 1.4142135623...?), (0.57508165...? + 1.52152305...?*I, 2.30032663...?)]
sage: M.cusp_translations(verified = True, bits_prec = 120) # doctest: +ELLIPSIS
[(0.4347208719449914031321600799...? + 1.1501633168956030025429463178...?*I, 1.73888348777996561252864031974...?), (0.353553390593273762200422181052...? + 0.935414346693485346395937183079...?*I, 1.4142135623730950488016887242097...?), (0.5750816584478015012714731589...? + 1.52152305180746991096256027978...?*I, 2.3003266337912060050858926356...?)]

that are guaranteed to contain the true translations of cusp neighborhoods verified to be disjoint (the element corresponding to a longitude is always in a RealIntervalField).

Remark: Since the code is (potentially) non-deterministic, this does not apply to the result of

[ M.cusp_translations(verified = True)[i] for i in range(M.num_cusps()) ]

Areas can be given as hint, also see CuspNeighborhood.all_translations(). In this case, the method will, if necessary, scale down cusp neighborhoods to ensure they are disjoint:

>>> M.cusp_translations(areas = [100,1.3,1.2]) 
[(0.70710678 + 1.87082869*I, 2.8284271...), (0.35048317 + 0.92729131*I, 1.401932...), (0.33673334 + 0.89091267*I, 1.34693336)]

For better results, the computation is usually done using the proto-canonical triangulation. This can be disabled using canonize:

>>> M.cusp_translations(canonize = False)
[(0.43472087 + 1.15016332*I, 1.73888349), (0.35355339 + 0.93541435*I, 1.41421356), (0.57508166 + 1.52152305*I, 2.30032663)]
dehn_fill(filling_data, which_cusp=None)

Set the Dehn filling coefficients of the cusps. This can be specified in the following ways, where the cusps are numbered by 0,1,…,(num_cusps - 1).

  • Fill cusp 2:

    >>> M = Manifold('8^4_1')
    >>> M.dehn_fill((2,3), 2)
    >>> M
    8^4_1(0,0)(0,0)(2,3)(0,0)
    
  • Fill the last cusp:

    >>> M.dehn_fill((1,5), -1)
    >>> M
    8^4_1(0,0)(0,0)(2,3)(1,5)
    
  • Fill the first two cusps:

    >>> M.dehn_fill( [ (3,0), (1, -4) ])
    >>> M
    8^4_1(3,0)(1,-4)(2,3)(1,5)
    
  • When there is only one cusp, there’s a shortcut

    >>> N = Manifold('m004')
    >>> N.dehn_fill( (-3,4) )
    >>> N
    m004(-3,4)
    

Does not return a new Manifold.

dirichlet_domain(vertex_epsilon=default_vertex_epsilon, displacement=[0.0, 0.0, 0.0], centroid_at_origin=True, maximize_injectivity_radius=True)

Returns a DirichletDomain object representing a Dirichlet domain of the hyperbolic manifold, typically centered at a point which is a local maximum of injectivity radius. It will have ideal vertices if the manifold is not closed.

>>> M = Manifold('m015')
>>> D = M.dirichlet_domain()
>>> D
32 finite vertices, 2 ideal vertices; 54 edges; 22 faces
>>> D.view()   #Shows 3d-graphical view.  

Other options can be provided to customize the computation; the default choices are shown below:

>>> M.dirichlet_domain(vertex_epsilon=10.0**-8,  displacement = [0.0, 0.0, 0.0],
... centroid_at_origin=True, maximize_injectivity_radius=True)
32 finite vertices, 2 ideal vertices; 54 edges; 22 faces
drill(which_curve, max_segments=6)

Drills out the specified dual curve from among all dual curves with at most max_segments, which defaults to 6. The method dual_curve allows one to see the properties of curves before chosing which one to drill out.

>>> M = Manifold('v3000')
>>> N = M.drill(0, max_segments=3)
>>> (M.num_cusps(), N.num_cusps())
(1, 2)
dual_curves(max_segments=6)

Constructs a reasonable selection of simple closed curves in a manifold’s dual 1-skeleton. In particular, it returns thos e that appear to represent geodesics. The resulting curves can be drilled out.

>>> M = Manifold('m015')
>>> curves = M.dual_curves()
>>> curves
[  0: orientation-preserving curve of length 0.56239915 - 2.81543089*I,
   1: orientation-preserving curve of length 1.12479830 + 0.65232354*I,
   2: orientation-preserving curve of length 1.26080402 + 1.97804689*I,
   3: orientation-preserving curve of length 1.58826933 + 1.67347167*I,
   4: orientation-preserving curve of length 1.68719745 + 2.81543089*I]

Each curve is returned as an info object with these keys

>>> sorted(curves[0].keys())
['complete_length', 'filled_length', 'index', 'max_segments', 'parity']

We can drill out any of these curves to get a new manifold with one more cusp.

>>> N = M.drill(curves[0])
>>> (M.num_cusps(), N.num_cusps())
(1, 2)

By default, this function only finds curves of length 6; this can be changed by specifying the optional argument max_segments

>>> M.dual_curves(max_segments=2)
[  0: orientation-preserving curve of length 0.56239915 - 2.81543089*I]
edge_valences()

Returns a dictionary whose keys are the valences of the edges in the triangulation, and the value associated to a key is the number of edges of that valence.

>>> M = Triangulation('v3227')
>>> M.edge_valences()     
{10: 1, 4: 1, 5: 2, 6: 3}
filled_triangulation(cusps_to_fill='all')

Return a new Manifold where the specified cusps have been permanently filled in.

Filling all the cusps results in a Triangulation rather than a Manifold, since SnapPea can’t deal with hyperbolic structures when there are no cusps.

Examples:

>>> M = Manifold('m125(1,2)(3,4)')
>>> N = M.filled_triangulation()
>>> N.num_cusps()
0

Filling cusps 0 and 2 :

>>> M = Manifold('v3227(1,2)(3,4)(5,6)')
>>> M.filled_triangulation([0,2])
v3227_filled(3,4)
fundamental_group(simplify_presentation=True, fillings_may_affect_generators=True, minimize_number_of_generators=True, try_hard_to_shorten_relators=True)

Return a HolonomyGroup representing the fundamental group of the manifold, together with its holonomy representation. If integer Dehn surgery parameters have been set, then the corresponding peripheral elements are killed.

>>> M = Manifold('m004')
>>> G = M.fundamental_group()
>>> G
Generators:
   a,b
Relators:
   aaabABBAb
>>> G.peripheral_curves()
[('ab', 'aBAbABab')]
>>> G.SL2C('baaBA')
matrix([[ 2.50000000 - 2.59807621*I, -6.06217783 - 0.50000000*I],
        [ 0.86602540 - 2.50000000*I, -4.00000000 + 1.73205081*I]])

There are three optional arguments all of which default to True:

  • simplify_presentation
  • fillings_may_affect_generators
  • minimize_number_of_generators
>>> M.fundamental_group(False, False, False)
Generators:
   a,b,c
Relators:
   CbAcB
   BacA
gluing_equations(form='log')

In the default mode, this function returns a matrix with rows of the form

a b c d e f …

which means

a*log(z0) + b*log(1/(1-z0)) + c*log((z0-1)/z0) + d*log(z1) +… = 2 pi i

for an edge equation, and (same) = 0 for a cusp equation. Here, the cusp equations come at the bottom of the matrix, and are listed in the form: meridian of cusp 0, longitude of cusp 0, meridian of cusp 1, longitude of cusp 1,…

In terms of the tetrahedra, a is the invariant of the edge (2,3), b the invariant of the edge (0,2) and c is the invariant of the edge (1,2). See kernel_code/edge_classes.c for a detailed account of the convention used.

If the optional argument form=’rect’ is given, then this function returns a list of tuples of the form:

( [a0, a1,..,a_n], [b_0, b_1,…,b_n], c)

where this corresponds to the equation

z0^a0 (1 - z0)^b0 z1^a1(1 - z1)^b1 … = c

where c = 1 or -1.

>>> M = Triangulation('m004(2,3)')
>>> M.gluing_equations()
matrix([[ 2,  1,  0,  1,  0,  2],
        [ 0,  1,  2,  1,  2,  0],
        [ 2,  0,  0,  0, -8,  6]])
>>> M.gluing_equations(form='rect')
[([2, -1], [-1, 2], 1), ([-2, 1], [1, -2], 1), ([2, -6], [0, 14], 1)]
gluing_equations_pgl(N=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 of the rows and the columns of the matrix.

This method generalizes gluing_equations() to PGL(N,C)-representations as described in Stavros Garoufalidis, Matthias Goerner, Christian K. Zickert: “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 general method by:

>>> M = Triangulation('m004')
>>> M.gluing_equations_pgl().matrix
matrix([[ 2,  1,  0,  1,  0,  2],
        [ 0,  1,  2,  1,  2,  0],
        [ 1,  0,  0,  0, -1,  0],
        [ 0,  0,  0,  0, -2,  2]])

But besides the matrix, the method also returns explanations of the columns and rows:

>>> M = Triangulation("m004")
>>> M.gluing_equations_pgl()
NeumannZagierTypeEquations(
  matrix([[ 2,  1,  0,  1,  0,  2],
          [ 0,  1,  2,  1,  2,  0],
          [ 1,  0,  0,  0, -1,  0],
          [ 0,  0,  0,  0, -2,  2]]),
  explain_columns = ['z_0000_0', 'zp_0000_0', 'zpp_0000_0', 'z_0000_1', 'zp_0000_1', 'zpp_0000_1'],
  explain_rows = ['edge_0_0', 'edge_0_1', 'meridian_0_0', 'longitude_0_0'])

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.

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 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 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 consistent.

The explanations of the rows and columns can be obtained explicitly by:

>>> M.gluing_equations_pgl(N = 3, equation_type = 'peripheral').explain_rows
['meridian_0_0', 'meridian_1_0', 'longitude_0_0', 'longitude_1_0']
>>> M.gluing_equations_pgl(N = 2).explain_columns
['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:

  • all gluing equations: ‘all’
  • non-peripheral equations: ‘non_peripheral’
    • edge gluing equations: ‘edge’
    • face gluing equations: ‘face’
    • internal gluing equations: ‘internal’
  • cusp gluing equations: ‘peripheral’
    • cusp gluing equations for meridians: ‘meridian’
    • cusp gluing equations for longitudes: ‘longitude’
has_finite_vertices()

Returns True if and only if the triangulation has finite (non-ideal) vertices.

>>> T = Triangulation("m004")
>>> T.has_finite_vertices()
False
>>> T.dehn_fill((12,13))
>>> S = T.filled_triangulation()
>>> S.has_finite_vertices()
True

When trying to find a hyperbolic structure, SnapPea will eliminate finite vertices:

>>> M = S.with_hyperbolic_structure()
>>> M.has_finite_vertices()
False
high_precision()

Return a high precision version of this manifold.

>>> M = Manifold('m004')
>>> type(M.high_precision())
<class 'snappy.ManifoldHP'>
homological_longitude(cusp=None)

Returns the peripheral curve in the given cusp, if any, which is homologically trivial (with rational coefficients) in the manifold:

sage: M = Manifold('m015')
sage: M.homological_longitude()
(2, -1)

If no cusp is specified, the default is the first unfilled cusp; if all cusps are filled, the default is the first cusp:

sage: M = Manifold('L5a1(3,4)(0,0)')
sage: M.homological_longitude()
(0, 1)

The components of the next link have nontrivial linking number so there is no such curve:

sage: W = Manifold('L7a2')
sage: W.homological_longitude(cusp=1) == None
True

If every curve in the given cusp is trivial in the rational homology of the manifold, an exception is raised:

sage: M = Manifold('4_1(1,0)')
sage: M.homological_longitude()
Traceback (most recent call last):
...
ValueError: Every curve on cusp is homologically trivial
homology()

Returns an AbelianGroup representing the first integral homology group of the underlying (Dehn filled) manifold.

>>> M = Triangulation('m003')
>>> M.homology()
Z/5 + Z
hyperbolic_SLN_torsion(N, bits_prec=100)

Compute the torsion polynomial of the holonomy representation lifted to SL(2, C) and then followed by the irreducible representation from SL(2, C) -> SL(N, C):

sage: M = Manifold('m016')
sage: [M.hyperbolic_SLN_torsion(N).degree() for N in [2, 3, 4]]
[18, 27, 36]
hyperbolic_adjoint_torsion(bits_prec=100)

Computes the torsion polynomial of the adjoint representation a la Dubois-Yamaguichi. This is not a sign-refined computation so the result is only defined up to sign, not to mention a power of the variable ‘a’:

sage: M = Manifold('K11n42')
sage: tau = M.hyperbolic_adjoint_torsion()
sage: tau.parent()
Univariate Polynomial Ring in a over Complex Field with 100 bits of precision
sage: tau.degree()
7
hyperbolic_torsion(bits_prec=100, all_lifts=False, wada_conventions=False, phi=None)

Computes the hyperbolic torision polynomial as defined in [DFJ]:

sage: M = Manifold('K11n42')
sage: M.alexander_polynomial()
1
sage: tau = M.hyperbolic_torsion(bits_prec=200)
sage: tau.degree()
6
identify(extends_to_link=False)

Look for the manifold in all of the SnapPy databases:

>>> M = Manifold('m125')
>>> M.identify()
[m125(0,0)(0,0), L13n5885(0,0)(0,0), ooct01_00000(0,0)(0,0)]

One can require that there be an isometry taking merdians to meridians:

>>> M.identify(extends_to_link=True)
[m125(0,0)(0,0), ooct01_00000(0,0)(0,0)]

For closed manifolds, extends_to_link doesn’t make sense because of how the kernel code works:

>>> C = Manifold("m015(1,2)")
>>> C.identify()
[m006(-5,2)]
>>> C.identify(True)
[]
init_hyperbolic_structure()
invariant_trace_field_gens(fundamental_group_args=[])

The generators of the trace field as ApproximateAlgebraicNumbers. Can be used to compute the tetrahedra field, where the first two parameters are bits of precision and maximum degree of the field:

sage: M = Manifold('m007(3,1)')
sage: K = M.invariant_trace_field_gens().find_field(100, 10, optimize=True)[0]
sage: L = M.trace_field_gens().find_field(100, 10, optimize=True)[0]
sage: K.polynomial(), L.polynomial()
(x^2 - x + 1, x^4 - 2*x^3 + x^2 + 6*x + 3)
is_isometric_to(Manifold other, return_isometries=False)

Returns True if M and N are isometric, False if they not. A RuntimeError is raised in cases where the SnapPea kernel fails to determine either answer. (This is fairly common for closed manifolds.)

>>> M = Manifold('m004')
>>> N = Manifold('4_1')
>>> K = Manifold('5_2')
>>> M.is_isometric_to(N)
True
>>> N.is_isometric_to(K)
False

We can also get a complete list of isometries between the two manifolds:

>>> M = Manifold('5^2_1')  # The Whitehead link
>>> N = Manifold('m129')
>>> isoms = M.is_isometric_to(N, return_isometries = True)
>>> isoms[6]  # Includes action on cusps
0 -> 1  1 -> 0 
[1  2]  [-1 -2]
[0 -1]  [ 0  1]
Extends to link

Each transformation between cusps is given by a matrix which acts on the left. That is, the two columns of the matrix give the image of the meridian and longitude respectively. In the above example, the meridian of cusp 0 is sent to the meridian of cusp 1.

Note: The answer True is rigorous, but the answer False may not be as there could be numerical errors resulting in finding an incorrect canonical triangulation.

is_orientable()

Return whether the underlying 3-manifold is orientable.

>>> M = Triangulation('x124')
>>> M.is_orientable()
False
is_two_bridge()

If the manifold is the complement of a two-bridge knot or link in S^3, then this method returns (p,q) where p/q is the fraction describing the link. Otherwise, returns False.

>>> M = Manifold('m004')
>>> M.is_two_bridge()
(2, 5)
>>> M = Manifold('m016')
>>> M.is_two_bridge()
False

Note: An answer of ‘True’ is rigorous, but not the answer ‘False’, as there could be numerical errors resulting in finding an incorrect canonical triangulation.

isometry_signature(of_link=False, verified=False, interval_bits_precs=[53, 212], exact_bits_prec_and_degrees=[(212, 10), (1000, 20), (2000, 20)], verbose=False)

The isomorphism signature of the canonical retriangulation. This is a complete invariant of the isometry type of a hyperbolic 3-manifold and described in more defail here:

>>> M = Manifold("m125")
>>> M.isometry_signature() # Unverified isometry signature
'gLLPQccdefffqffqqof'

When used inside Sage and verified = True is passed as argument, the verify module will certify the result to be correct:

sage: M = Manifold("m125")
sage: M.isometry_signature(verified = True) # Verified isometry signature
'gLLPQccdefffqffqqof'

When of_link = True is specified, the peripheral curves are included in such a way that the result is a complete invariant of a link. In particular, isometry_signature(of_link=True) is invariant under changing the ordering or orientations of the components or flipping all crossings of a link simultaneously (it passes ignore_cusp_order = True, ignore_curve_orientations = True to Manifold.triangulation_isosig()):

>>> Manifold("5^2_1").isometry_signature(of_link = True)
'eLPkbdcddhgggb_baCbbaCb'
>>> Manifold("7^2_8").isometry_signature(of_link = True)
'eLPkbdcddhgggb_bBcBbaCb'

See verify.verified_canonical_retriangulation() for the additional options.

Note that interval methods cannot verify a canonical retriangulation with non-tetrahedral cells such as in the cas of m412, so the following call returns None:

sage: M = Manifold("m412")
sage: M.isometry_signature(verified = True, exact_bits_prec_and_degrees = None)
isomorphisms_to(Triangulation other)

Returns a complete list of combinatorial isomorphisms between the two triangulations:

>>> M = Manifold('5^2_1')
>>> N = Manifold('5^2_1')
>>> N.set_peripheral_curves([[[2,3],[-1,-1]],[[1,1],[0,1]]])
>>> isoms = M.isomorphisms_to(N)
>>> isoms[6]
0 -> 1  1 -> 0
[ 1 0]  [-1 1]
[-1 1]  [-3 2]
Does not extend to link

Each transformation between cusps is given by a matrix which acts on the left. That is, the two columns of the matrix give the image of the meridian and longitude respectively. In the above example, the meridian of cusp 0 is sent to the meridian of cusp 1.

length_spectrum(cutoff=1.0, full_rigor=True)

M.length_spectrum(cutoff=1.0)

Returns a list of geodesics (with multiplicities) of length up to the specified cutoff value. (The default cutoff is 1.0.)

name()

Return the name of the triangulation.

>>> M = Triangulation('4_1')
>>> M.name()
'4_1'
normal_boundary_slopes(subset='all', algorithm='FXrays')

For a one-cusped manifold, returns all the nonempty boundary slopes of spun normal surfaces. Provided the triangulation supports a genuine hyperbolic structure, then by Thurston and Walsh any strict boundary slope (the boundary of an essential surface which is not a fiber or semifiber) must be listed here.

>>> M = Manifold('K3_1')
>>> M.normal_boundary_slopes()
[(16, -1), (20, -1), (37, -2)]

If the subset flag is set to 'kabaya', then it only returns boundary slopes associated to vertex surfaces with a quad in every tetrahedron; by Theorem 1.1. of [DG] these are all strict boundary slopes.

>>> N = Manifold('m113')
>>> N.normal_boundary_slopes()
[(1, 1), (1, 2), (2, -1), (2, 3), (8, 11)]
>>> N.normal_boundary_slopes('kabaya')
[(8, 11)]

If the subset flag is set to 'brasile' then it returns only the boundary slopes that are associated to vertex surfaces giving isolated rays in the space of embedded normal surfaces.

>>> N.normal_boundary_slopes('brasile')
[(1, 2), (8, 11)]
normal_surfaces(algorithm='FXrays')

All the vertex spun-normal surfaces in the current triangulation.

>>> M = Manifold('m004')
>>> M.normal_surfaces()    
[<Surface 0: [0, 0] [1, 2] (4, 1)>,
 <Surface 1: [0, 1] [1, 2] (4, -1)>,
 <Surface 2: [1, 2] [2, 1] (-4, -1)>,
 <Surface 3: [2, 2] [2, 1] (-4, 1)>]
num_cusps(cusp_type='all')

Return the total number of cusps. By giving the optional argument ‘orientable’ or ‘nonorientable’ it will only count cusps of that type.

>>> M = Triangulation('m125')
>>> M.num_cusps()
2
num_tetrahedra()

Return the number of tetrahedra in the triangulation.

>>> M = Triangulation('m004')
>>> M.num_tetrahedra()
2
orientation_cover()

For a non-orientable Triangulation, returns the 2-fold cover which is orientable.

>>> X = Triangulation('x123')
>>> Y = X.orientation_cover()
>>> (X.is_orientable(), Y.is_orientable())
(False, True)
>>> Y
x123~(0,0)(0,0)
>>> Y.cover_info()['type']
'cyclic'

Brings up a link editor window if there is a link known to be associated with the manifold.

polished_holonomy(bits_prec=100, fundamental_group_args=[], lift_to_SL2=True, ignore_solution_type=False, dec_prec=None)

Return the fundamental group of M equipt with a high-precision version of the holonomy representation:

sage: M = Manifold('m004')
sage: G = M.polished_holonomy()
sage: G('a').trace()
1.5000000000000000000000000000 - 0.86602540378443864676372317075*I
sage: G = M.polished_holonomy(bits_prec=1000)
sage: G('a').trace().parent()
Complex Field with 1000 bits of precision
ptolemy_generalized_obstruction_classes(N)

M.ptolemy_generalized_obstruction_classes(N)

Returns the obstruction classes needed to compute PGL(N,C)-representations for any N, i.e., it returns a list with a representative cocycle for each element in H^2(M, boundary M; Z/N) / (Z/N)^* where (Z/N)^* are the units in Z/N. The first element in the list always corresponds to the trivial obstruction class. The generalized ptolemy obstruction classes are thus a generalization of the ptolemy obstruction classes that allow to find all boundary-unipotent PGL(N,C)-representations including those that do not lift to boundary-unipotent SL(N,C)-representations for N odd or SL(N,C)/{+1,-1}-representations for N even.

For example, 4_1 has three obstruction classes up to equivalence:

>>> M = Manifold("4_1")
>>> c = M.ptolemy_generalized_obstruction_classes(4)
>>> len(c)
3

For 4_1, we only get three obstruction classes even though we have H^2(M, boundary M; Z/4) = Z/4 because the two obstruction classes 1 in Z/4 and -1 in Z/4 are related by a unit and thus give isomorphic Ptolemy varieties.

The primary use of an obstruction class sigma is to construct the Ptolemy variety of sigma. This variety computes boundary-unipotent PGL(N,C)-representations whose obstruction class to a boundary-unipotent lift to SL(N,C) is sigma.

For example for 4_1, there are 2 obstruction classes for N = 3:

>>> M = Manifold("4_1")
>>> c = M.ptolemy_generalized_obstruction_classes(3)
>>> len(c)
2

The Ptolemy variety parametrizing boundary-unipotent SL(3,C)-representations of 4_1 is obtained by

>>> p = M.ptolemy_variety(N = 3, obstruction_class = c[0])

and the Ptolemy variety parametrizing boundary-unipotent PSL(3,C)-representations of 4_1 that do not lift to boundary-unipotent SL(3,C)-representations is obtained by

>>> p = M.ptolemy_variety(N = 3, obstruction_class = c[1])

The cocycle representing the non-trivial obstruction class looks as follows:

>>> c[1]
PtolemyGeneralizedObstructionClass([2, 0, 0, 1])

This means that the cocycle takes the value -1 in Z/3 on the first face class and 1 on the fourth face class but zero on every other of the four face classes.

ptolemy_obstruction_classes()

Returns the obstruction classes needed to compute pSL(N,C) = SL(N,C)/{+1,-1} representations for even N, i.e., it returns a list with a representative cocycle for each class in H^2(M, boundary M; Z/2). The first element in the list is always representing the trivial obstruction class.

For example, 4_1 has two obstruction classes:

>>> M = Manifold("4_1")
>>> c = M.ptolemy_obstruction_classes()
>>> len(c)
2

The primary use of these obstruction classes is to construct the Ptolemy variety as described in Definition 1.7 of Stavros Garoufalidis, Dylan Thurston, Christian K. Zickert: “The Complex Volume of SL(n,C)-Representations of 3-Manifolds” (http://arxiv.org/abs/1111.2828).

For example, to construct the Ptolemy variety for PSL(2,C)-representations of 4_1 that do not lift to boundary-parabolic SL(2,C)-representations, use:

>>> p = M.ptolemy_variety(N = 2, obstruction_class = c[1])

Or the following short-cut:

>>> p = M.ptolemy_variety(2, obstruction_class = 1)

Note that this obstruction class only makes sense for even N:

>>> p = M.ptolemy_variety(3, obstruction_class = c[1])
Traceback (most recent call last):
...
AssertionError: PtolemyObstructionClass only makes sense for even N, try PtolemyGeneralizedObstructionClass

To obtain PGL(N,C)-representations for N > 2, use the generalized obstruction class:

>>> c = M.ptolemy_generalized_obstruction_classes(3)
>>> p = M.ptolemy_variety(3, obstruction_class = c[1])

The orginal obstruction class encodes a representing cocycle in Z/2 as follows:

>>> c = M.ptolemy_obstruction_classes()
>>> c[1]
PtolemyObstructionClass(s_0_0 + 1, s_1_0 - 1, s_2_0 - 1, s_3_0 + 1, s_0_0 - s_0_1, s_1_0 - s_3_1, s_2_0 - s_2_1, s_3_0 - s_1_1)

This means that the cocycle to represent this obstruction class in Z/2 takes value 1 in Z/2 on face 0 of tetrahedra 0 (because s_0_0 = -1) and value 0 in Z/2 on face 1 of tetrahedra 0 (because s_1_0 = +1).

Face 3 of tetrahedra 0 and face 1 of tetrahedra 1 are identified, hence the cocycle takes the same value on those two faces (s_3_0 = s_1_1).

ptolemy_variety(N, obstruction_class=None, simplify=True, eliminate_fixed_ptolemys=False)

M.ptolemy_variety(N, obstruction_class = None, simplify = True, eliminate_fixed_ptolemys = False)

Returns a Ptolemy variety as described in

  • Stavros Garoufalidis, Dyland Thurston, Christian K. Zickert: “The Complex Volume of SL(n,C)-Representations of 3-Manifolds” (http://arxiv.org/abs/1111.2828)
  • Stavros Garoufalidis, Matthias Goerner, Christian K. Zickert: “Gluing Equations for PGL(n,C)-Representations of 3-Manifolds ” (http://arxiv.org/abs/1207.6711)

The variety can be exported to magma or sage and solved there. The solutions can be processed to compute invariants. The method can also be used to automatically look up precomputed solutions from the database at http://ptolemy.unhyperbolic.org/data .

Example for m011 and PSL(2,C)-representations:

>>> M = Manifold("m011")

Obtain all Ptolemy varieties for PSL(2,C)-representations:

>>> p = M.ptolemy_variety(2, obstruction_class = 'all')

There are two Ptolemy varieties for the two obstruction classes:

>>> len(p)
2

Retrieve the solutions from the database

>>> sols = p.retrieve_solutions() 

Compute the solutions using magma (default in SnapPy)

>>> sols = p.compute_solutions(engine = 'magma') 

Compute the solutions using singular (default in sage)

>>> sols = p.compute_solutions(engine = 'sage') 

Note that magma is significantly faster.

Compute all resulting complex volumes

>>> cvols = sols.complex_volume_numerical() 
>>> cvols  
[[[-4.29405713186238 E-16 + 0.725471193740844*I,
   -0.942707362776931 + 0.459731436553693*I,
   0.942707362776931 + 0.459731436553693*I]],
 [[3.94159248086745 E-15 + 0.312682687518267*I,
   4.64549527022581 E-15 + 0.680993020093457*I,
   -2.78183391239608 - 0.496837853805869*I,
   2.78183391239608 - 0.496837853805869*I]]]

Show complex volumes as a non-nested list:

>>> cvols.flatten(depth=2) 
[-4.29405713186238 E-16 + 0.725471193740844*I,
 -0.942707362776931 + 0.459731436553693*I,
 0.942707362776931 + 0.459731436553693*I,
 3.94159248086745 E-15 + 0.312682687518267*I,
 4.64549527022581 E-15 + 0.680993020093457*I,
 -2.78183391239608 - 0.496837853805869*I,
 2.78183391239608 - 0.496837853805869*I]

For more examples, go to http://ptolemy.unhyperbolic.org/

=== Optional Arguments ===

obstruction_class — class from Definiton 1.7 of (1). None for trivial class or a value returned from 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.

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, …

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.

=== Examples for 4_1 ===

>>> M = Manifold("4_1")

Get the varieties for all obstruction classes at once (use help(varieties[0]) for more information):

>>> varieties = M.ptolemy_variety(2, obstruction_class = "all")

Print the variety as an ideal (sage object) for the non-trivial class:

>>> varieties[1].ideal    
Ideal (-c_0011_0^2 + c_0011_0*c_0101_0 + c_0101_0^2, -c_0011_0^2 - c_0011_0*c_0101_0 + c_0101_0^2, c_0011_0 - 1) of Multivariate Polynomial Ring in c_0011_0, c_0101_0 over Rational Field                                                       

Print the equations of the variety for the non-trivial class:

>>> for eqn in varieties[1].equations:
...     print(eqn)          
     - 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

Generate a magma file to compute Primary Decomposition for N = 3:

>>> p = M.ptolemy_variety(3)
>>> s = p.to_magma()
>>> print(s.split("ring and ideal")[1].strip())     
R<c_0012_0, c_0012_1, c_0102_0, c_0111_0, c_0201_0, c_1011_0, c_1011_1, c_1101_0> := PolynomialRing(RationalField(), 8, "grevlex");
MyIdeal := ideal<R |
          c_0012_0 * c_1101_0 + c_0102_0 * c_0111_0 - c_0102_0 * c_1011_0,
    ...

=== If you have a magma installation ===

Call p.compute_solutions() to automatically call magma on the above output and produce exact solutions!!!

>>> try:
...     sols = p.compute_solutions()
... except:
...     # magma failed, use precomputed_solutions
...     sols = None

Check solutions against manifold >>> if sols: … dummy = sols.check_against_manifold()

=== If you do not have a magma installation ===

Load a precomputed example from magma which is provided with the package:

>>> from snappy.ptolemy.processMagmaFile import _magma_output_for_4_1__sl3, solutions_from_magma
>>> print(_magma_output_for_4_1__sl3)      

==TRIANGULATION=BEGINS==
% Triangulation
4_1
...

Parse the file and produce solutions:

>>> sols = solutions_from_magma(_magma_output_for_4_1__sl3)
>>> dummy = sols.check_against_manifold()

=== Continue here whether you have or do not have magma ===

Pick the first solution of the three different solutions (up to Galois conjugates):

>>> len(sols)
3
>>> solution = sols[0]

Read the exact value for c_1020_0 (help(solution) for more information on how to compute cross ratios, volumes and other invariants):

>>> solution['c_1020_0']
Mod(-1/2*x - 3/2, x^2 + 3*x + 4)

Example of simplified vs non-simplified variety for N = 4:

>>> simplified = M.ptolemy_variety(4, obstruction_class = 1)
>>> full = M.ptolemy_variety(4, obstruction_class = 1, simplify = False)
>>> len(simplified.variables), len(full.variables)
(21, 63)
>>> len(simplified.equations), len(full.equations)
(24, 72)
randomize()

Perform random Pachner moves on the underlying triangulation.

>>> M = Triangulation('Braid:[1,2,-3,-3,1,2]')
>>> M.randomize()
reverse_orientation()

Reverses the orientation of the Triangulation, presuming that it is orientable.

>>> M = Manifold('m015')
>>> cs = M.chern_simons()
>>> M.reverse_orientation()
>>> round(abs(cs + M.chern_simons()), 15)
0.0
save(file_name=None)

Save the triangulation as a SnapPea triangulation file.

>>> M = Triangulation('m004')
>>> M.save('fig-eight.tri')     
set_name(new_name)

Give the triangulation a new name.

>>> M = Triangulation('4_1')
>>> M.set_name('figure-eight-comp')
>>> M
figure-eight-comp(0,0)
set_peripheral_curves(peripheral_data, which_cusp=None, return_matrices=False)

Each cusp has a preferred marking. In the case of a torus cusp, this is pair of essential simple curves meeting in one point; equivalently, a basis of the first homology of the boundary torus. These curves are called the meridian and the longitude.

This method changes these markings in various ways. In many cases, if the flag return_matrices is True then it returns a list of change-of-basis matrices is returned, one per cusp, which will restore the original markings if passed as peripheral_data.

  • Make the shortest curves the meridians, and the second shortest curves the longitudes.

    >>> M = Manifold('5_2')
    >>> M.cusp_info('shape')
    [-2.49024467 + 2.97944707*I]
    >>> cob = M.set_peripheral_curves('shortest', return_matrices=True)
    >>> M.cusp_info('shape')
    [-0.49024467 + 2.97944707*I]
    >>> cob
    [[[1, 0], [-2, 1]]]
    >>> M.set_peripheral_curves(cob)
    >>> M.cusp_info('shape')
    [-2.49024467 + 2.97944707*I]
    

    You can also make just the meridians as short as possible while fixing the longitudes via the option ‘shortest_meridians’, and conversely with ‘shortest_longitudes’.

  • If cusps are Dehn filled, make those curves meridians.

    >>> M = Manifold('m125(0,0)(2,5)')
    >>> M.set_peripheral_curves('fillings')
    >>> M
    m125(0,0)(1,0)
    
  • Change the basis of a particular cusp, say the first one:

    >>> M.set_peripheral_curves( [ (1,2), (1,3) ] , 0)
    

    Here (1,2) is the new meridian written in the old basis, and (1,3) the new longitude.

  • Change the basis of all the cusps at once

    >>> new_curves = [ [(1,-1), (1,0)],  [(3,2), (-2,-1)] ]
    >>> M.set_peripheral_curves(new_curves)
    >>> M
    m125(0,0)(-1,-2)
    
set_target_holonomy(target, which_cusp=0, recompute=True)

M.set_target_holonomy(target, which_cusp=0, recompute=True)

Computes a geometric structure in which the Dehn filling curve on the specified cusp has holonomy equal to the target value. The holonomies of Dehn filling curves on other cusps are left unchanged. If the ‘recompute’ flag is False, the Dehn filling equations are modified, but not solved.

set_tetrahedra_shapes(filled_shapes=None, complete_shapes=None, fillings=None)

Replaces the tetrahedron shapes with those in the given lists, and sets the Dehn filling coefficients as specified by the fillings argument. The shapes will get double precision values; polishing will be needed for high precision shapes.

simplify()

Try to simplify the triangulation by doing Pachner moves.

>>> M = Triangulation('12n123')
>>> M.simplify()
solution_type(enum=False)

Returns the type of the current solution to the gluing equations, basically a summary of how degenerate the solution is. If the flag enum=True is set, then an integer value is returned. The possible answers are:

  • 0: ‘not attempted’
  • 1: ‘all tetrahedra positively oriented’ aka ‘geometric_solution’ Should correspond to a genuine hyperbolic structure.
  • 2: ‘contains negatively oriented tetrahedra’ aka ‘nongeometric_solution’ Probably correponds to a hyperbolic structure but some simplices have reversed orientiations.
  • 3: ‘contains flat tetrahedra’ All tetrahedra have shape in R - {0, 1}.
  • 4: ‘contains degenerate tetrahedra’ Some shapes are close to {0,1, or infinity}.
  • 5: ‘unrecognized solution type’
  • 6: ‘no solution found’
>>> M = Manifold('m007')
>>> M.solution_type()
'all tetrahedra positively oriented'
>>> M.dehn_fill( (3,1) )
>>> M.solution_type()
'contains negatively oriented tetrahedra'
>>> M.dehn_fill( (3,-1) )
>>> M.solution_type()
'contains degenerate tetrahedra'
split(which_surface)

Split the manifold open along a surface of positive characteristic found by the method “splitting_surfaces”. Returns a list of the pieces, with any sphere boundary components filled in.

Here’s an example of a Whitehead double on the trefoil.

>>> M = Manifold('K14n26039')
>>> S = M.splitting_surfaces()[0]
>>> S
Orientable two-sided with euler = 0
>>> pieces = M.split(S); pieces
[K14n26039.a(0,0)(0,0), K14n26039.b(0,0)]
>>> pieces[0].volume()
3.66386238
>>> pieces[1].fundamental_group().relators()
['aabbb']

You can also specify a surface by its index.

>>> M = Manifold('L10n111') 
>>> max( P.volume() for P in M.split(0) )
5.33348957
splitting_surfaces()

Searches for connected closed normal surfaces of nonnegative Euler characteristic. If spheres or projective planes are found, then tori and Klein bottles aren’t reported. There is no guarantee that all such normal surfaces will be found nor that any given surface is incompressible. The search is confined to surfaces whose quads are in the tetrahedra that have degenerate shapes.

You can split the manifold open along one of these surfaces using the method “split”.

A connect sum of two trefoils:

>>> M1 = Manifold('DT: fafBCAEFD')
>>> len(M1.splitting_surfaces())
2

First satellite knot in the table.

>>> M2 = Manifold('K13n4587')
>>> M2.splitting_surfaces()
[Orientable two-sided with euler = 0]
symmetric_triangulation()

Returns a Dehn filling description of the manifold realizing the symmetry group.

>>> M = Manifold('m003(-3,1)')
>>> M.symmetry_group()
D6
>>> N = M.symmetric_triangulation()
>>> N
m003(1,0)(1,0)(1,0)
>>> N.dehn_fill( [(0,0), (0,0), (0,0)] )
>>> N.symmetry_group(of_link=True)
D6
symmetry_group(of_link=False)

Returns the symmetry group of the Manifold. If the flag “of_link” is set, then it only returns symmetries that preserves the meridians.

tetrahedra_field_gens()

The shapes of the tetrahedra as ApproximateAlgebraicNumbers. Can be used to compute the tetrahedra field, where the first two parameters are bits of precision and maximum degree of the field:

sage: M = Manifold('m015')
sage: tets = M.tetrahedra_field_gens()
sage: tets.find_field(100, 10, optimize=True)    # doctest: +NORMALIZE_WHITESPACE
(Number Field in z with defining polynomial x^3 - x - 1,
<ApproxAN: -0.662358978622 - 0.562279512062*I>, [-z, -z, -z])
tetrahedra_shapes(part=None, fixed_alignment=True, bits_prec=None, dec_prec=None, intervals=False)

Gives the shapes of the tetrahedra in the current solution to the gluing equations. Returns a list containing one info object for each tetrahedron. The keys are:

  • rect : the shape of the tetrahedron, as a point in the complex plane.
  • log : the log of the shape
  • accuracies: a list of the approximate accuracies of the shapes, in order (rect re, rect im, log re, log im)

If the optional variable ‘part’ is set to one of the above, then the function returns only that component of the data.

If the flag ‘fixed_alignment’ is set to False, then the edges used to report the shape parameters are choosen so as to normalize the triangle.

>>> M = Manifold('m015')
>>> M.tetrahedra_shapes(part='rect')
[0.66235898 + 0.56227951*I, 0.66235898 + 0.56227951*I, 0.66235898 + 0.56227951*I]
>>> M.tetrahedra_shapes() 
[{'accuracies': (11, 11, 12, 11), 'log': -0.14059979 + 0.70385772*I, 'rect': 0.66235898 + 0.56227951*I},
 {'accuracies': (11, 11, 11, 11), 'log': -0.14059979 + 0.70385772*I, 'rect': 0.66235898 + 0.56227951*I},
 {'accuracies': (11, 11, 11, 11), 'log': -0.14059979 + 0.70385772*I, 'rect': 0.66235898 + 0.56227951*I}]
trace_field_gens(fundamental_group_args=[])

The generators of the trace field as ApproximateAlgebraicNumbers. Can be used to compute the tetrahedra field, where the first two parameters are bits of precision and maximum degree of the field:

sage: M = Manifold('m125')
sage: traces = M.trace_field_gens()
sage: traces.find_field(100, 10, optimize=True)    # doctest: +NORMALIZE_WHITESPACE
(Number Field in z with defining polynomial x^2 + 1,
<ApproxAN: -1.0*I>, [z + 1, z, z + 1])
triangulation_isosig(decorated=True, ignore_cusp_ordering=False, ignore_curve_orientations=False)

Returns a compact text representation of the triangulation, called a “decorated isomorphism signature”

>>> T = Triangulation('m004')
>>> T.triangulation_isosig()
'cPcbbbiht_BaCB'

You can use this string to recreate an isomorphic triangulation later

>>> A = Triangulation('y233')
>>> A.triangulation_isosig()
'hLMzMkbcdefggghhhqxqhx_BaaB'
>>> B = Triangulation('hLMzMkbcdefggghhhqxqhx_BaaB')
>>> A == B
True

By default, the returned string encodes the peripheral curves (and slopes of Dehn-fillings if any are present), but you can request only the “isomorphism signature” which can be given to Regina.

>>> E = Triangulation('K3_1')   # the (-2, 3, 7) exterior
>>> isosig = E.triangulation_isosig(decorated = False); isosig
'dLQacccjsnk'
>>> F = Triangulation(isosig)
>>> E.isomorphisms_to(F)[1]
0 -> 0
[1 18]
[0  1]
Extends to link
>>> E.triangulation_isosig()
'dLQacccjsnk_BaRsB'
>>> F.triangulation_isosig()
'dLQacccjsnk_BaaB'
>>> G = Triangulation('dLQacccjsnk_BaRsB')
>>> E.isomorphisms_to(G)[0]
0 -> 0
[1 0] 
[0 1] 
Extends to link

If you do not care about the indexing of the cusps when using a decorated signature, use ignore_cusp_ordering

>>> M = Manifold("L14n64110(1,2)(2,3)(-2,1)(3,4)(0,0)")
>>> isosig = M.triangulation_isosig(decorated = True, ignore_cusp_ordering = True)
>>> isosig
'xLLvLvMLPMPLAMQQcceflnjmmmospsrttvvvtswwwiieiifdeauinasltltahmbjn_bacBbaaBBaBbBbbaabba(2,3)(-2,1)(1,2)(3,4)(0,0)'
>>> N = Manifold(isosig).filled_triangulation()
>>> N.is_isometric_to(M.filled_triangulation())
True

If you do not care about the orientations of the peripheral curves, use ignore_curve_orientations

>>> M = Manifold("L6a1")
>>> M.triangulation_isosig()
'gLLAQcdeefffdopuado_BabbBaab'
>>> isosig = M.triangulation_isosig(decorated = True, ignore_curve_orientations = True)
>>> isosig
'gLLAQcdeefffdopuado_babbbaab'
>>> N = Manifold(isosig)
>>> M.isomorphisms_to(N)
[0 -> 0  1 -> 1
[-1 0]  [-1 0]
[ 0 1]  [ 0 1]
Extends to link, 0 -> 0  1 -> 1
[1  0]  [1  0]
[0 -1]  [0 -1]
Extends to link]

The code has been copied from Regina where the corresponding method is called “isoSig”.

Unlike dehydrations for 3-manifold triangulations, an isomorphism signature uniquely determines a triangulation up to combinatorial isomorphism. That is, two triangulations of 3-dimensional manifolds are combinatorially isomorphic if and only if their isomorphism signatures are the same string. For full details, see Simplification paths in the Pachner graphs of closed orientable 3-manifold triangulations, Burton, 2011.

For details about how the peripheral decorations work, see the SnapPy source code.

use_field_conversion(type cls, func)

A class method for specifying a numerical conversion function.

SnapPy includes its own number type, snappy.Number, which can represent floating point real or complex numbers of varying precision. (In fact, Number is a wrapper for a pari number of type ‘t_INT’, ‘t_FRAC’, ‘t_REAL’ or ‘t_COMPLEX’, and the pari gen can be extracted as an attribute: x.gen .) Methods of SnapPy objects which return numerical values will first compute the value as a Number, and then optionally convert the Number to a different numerical type which can be specified by calling this class method.

By default SnapPy returns Numbers when loaded into python, and elements of a Sage RealField or ComplexField when loaded into Sage. These will be 64 bit numbers for ordinary Manifolds and 212 bit numbers for high precision manifolds.

The func argument should be a function which accepts a number and returns a numerical type of your choosing. Alternatively, the strings ‘sage’ or ‘snappy’ can be passed as arguments to select either of the two default behaviors.

EXAMPLE:

sage: M = Manifold('m004')
sage: parent(M.volume())
Real Field with 64 bits of precision
sage: Manifold.use_field_conversion('snappy')
sage: M = Manifold('m004')
sage: parent(M.volume())
SnapPy Numbers with 64 bits precision
sage: Manifold.use_field_conversion('sage')
sage: M = Manifold('m004')
sage: parent(M.volume())
Real Field with 64 bits of precision
verify_hyperbolicity(verbose=False, bits_prec=53, holonomy=False, fundamental_group_args=[], lift_to_SL=True)

Given an orientable SnapPy Manifold, verifies its hyperbolicity. Similar to HIKMOT’s verify_hyperbolicity(), the result is either (True, listOfShapeIntervals) or (False, []) if verification failed. listOfShapesIntervals is a list of complex intervals (elements in sage’s ComplexIntervalField) certified to contain the true shapes for the hyperbolic manifold.

Higher precision intervals can be obtained by setting bits_prec:

sage: from snappy import Manifold
sage: M = Manifold("m019")
sage: M.verify_hyperbolicity() # doctest: +ELLIPSIS
(True, [0.780552527850...? + 0.914473662967...?*I, 0.780552527850...? + 0.91447366296773?*I, 0.4600211755737...? + 0.6326241936052...?*I])

sage: M = Manifold("t02333(3,4)")
sage: M.verify_hyperbolicity() # doctest: +ELLIPSIS
(True, [2.1521881536...? + 0.284940667...?*I, 1.92308491369? + 1.1036070150...?*I, 0.014388591584? + 0.143084469681?*I, -2.5493670288? + 3.7453498408?*I, 0.142120333822? + 0.176540027036?*I, 0.504866865...? + 0.82829881681?*I, 0.50479249917? + 0.98036162786?*I, -0.5894957050...? + 0.81267480427?*I])

One can instead get a holonomy representation associated to the verified hyperbolic structure. This representation takes values in 2x2 matrices with entries in the ComplexIntervalField:

sage: M = Manifold("m004(1,2)")
sage: success, rho = M.verify_hyperbolicity(holonomy=True)
sage: success
True
sage: trace = rho('aaB').trace(); trace # doctest: +ELLIPSIS
-0.111862...? + 3.853612...?*I
sage: (trace - 2).contains_zero()
False
sage: (rho('aBAbaabAB').trace() - 2).contains_zero()
True

Here, there is provably a fixed holonomy representation rho0 from the fundamental group G of M to SL(2, C) so that for each element g of G the matrix rho0(g) is contained in rho(g). In particular, the above constitutes a proof that the word ‘aaB’ is non-trivial in G. In contrast, the final computation is consistent with ‘aBAbaabAB’ being trivial in G, but does not prove this.

A non-hyperbolic manifold (False indicates that the manifold might not be hyperbolic but does not certify non-hyperbolicity. Sometimes, hyperbolicity can only be verified after increasing the precision):

sage: M = Manifold("4_1(1,0)")
sage: M.verify_hyperbolicity()
(False, [])

Under the hood, the function will call the CertifiedShapesEngine to produce intervals certified to contain a solution to the rectangular gluing equations. It then calls check_logarithmic_gluing_equations_and_positively_oriented_tets to verify that the logarithmic gluing equations are fulfilled and that all tetrahedra are positively oriented.

volume(accuracy=False, verified=False, bits_prec=None)

Returns the volume of the current solution to the hyperbolic gluing equations; if the solution is sufficiently non-degenerate, this is the sum of the volumes of the hyperbolic pieces in the geometric decomposition of the manifold.

>>> M = Manifold('m004')
>>> M.volume()
2.02988321
>>> M.solution_type()
'all tetrahedra positively oriented'

The return value has an extra attribute, accuracy, which is the number of digits of accuracy as estimated by SnapPea. When printing the volume, the result is rounded to 1 more than this number of digits.

>>> M.volume().accuracy in (10, 63) # Low precision, High precision
True

Inside Sage, verified computation of the volume of a hyperbolic manifold is also possible (this will verify first that the manifold is indeed hyperbolic):

sage: M.volume(verified=True, bits_prec=100)
2.0298832128193072500424051?
with_hyperbolic_structure()

Add a (possibly degenerate) hyperbolic structure, turning the Triangulation into a Manifold.

>>> M = Triangulation('m004')
>>> N = M.with_hyperbolic_structure()
>>> N.volume()
2.02988321
without_hyperbolic_structure()

Returns self as a Triangulation, forgetting the hyperbolic structure in the process.

>>> M = Manifold('9_42')
>>> T = M.without_hyperbolic_structure()
>>> hasattr(T, 'volume')
False