separatrix_diagram

Separatrix diagrams and cylinder diagrams

A separatrix diagram is a couple of permutation (bot,top) that have the same number of cycles in their cycle decompositions. A cylinder diagram is a separatrix diagram together with a bijection between the cycles of bot and top.

A cylinder diagram encodes the combinatorics of cylinder decomposition of a completely periodic direction in a translation surface. If we adjoin coordinates to this combinatorial datum, we have a complete description of the underlying surface. In the case of arithmetic curves, the coordinates can be taken to be rational numbers.

This representation of a surface is used in various constructions:

• square tiled surfaces

• Thurston-Veech construction of pseudo-Anosov diffeomorphism

• description of the cusp of Teichmueller curves

EXAMPLES:

sage: from surface_dynamics import *

Separatrix diagrams:

sage: s = SeparatrixDiagram('(0,1,2)(3,4)(5,6,7)','(0,4,1,2)(3,7)(5,6)')
sage: s
(0,1,2)(3,4)(5,6,7)-(0,4,1,2)(3,7)(5,6)
sage: s.bot_cycle_tuples()
[(0, 1, 2), (3, 4), (5, 6, 7)]
sage: s.top_cycle_tuples()
[(0, 4, 1, 2), (3, 7), (5, 6)]

Cylinder diagrams:

sage: c = CylinderDiagram([((0,),(4,)),((1,2),(0,1,3)),((3,4),(2,))])
sage: print(c)
(0)-(4) (1,2)-(0,1,3) (3,4)-(2)
sage: print(c.separatrix_diagram())
(0)(1,2)(3,4)-(0,1,3)(2)(4)

They can also be built from separatrix diagram:

sage: s = SeparatrixDiagram('(0,1,2)(3,4)(5,6,7)','(0,4,1,2)(3,7)(5,6)')
sage: s
(0,1,2)(3,4)(5,6,7)-(0,4,1,2)(3,7)(5,6)
sage: s.to_cylinder_diagram([(0,1),(1,0),(2,2)])
(0,1,2)-(3,7) (3,4)-(0,4,1,2) (5,6,7)-(5,6)

class surface_dynamics.flat_surfaces.separatrix_diagram.CylinderDiagram(data, check=True)

Separatrix diagram with pairing.

Each cylinder is stored as a couple (bot,top) for which the orientation is as follows:

+--------------------+
|     <-- top --     |
|                    |
|                    |
|      -- bot -->    |
+--------------------+

INPUT:

• data - list of 2-tuples - matching of bottom-top pairs

EXAMPLES:

sage: from surface_dynamics import *

We first build the simplest cylinder diagram which corresponds to a torus:

sage: CylinderDiagram([((0,),(0,))])
(0)-(0)

The same initialized from a string:

sage: CylinderDiagram('(0)-(0)')
(0)-(0)

The following initialize a cylinder diagram with two cylinder which gives a surface of genus 2 with one singularity of degree 2:

sage: CylinderDiagram([((0,1),(0,2)),((2,),(1,))])
(0,1)-(0,2) (2)-(1)

ALGORITHM:

A cylinder is represented by a couple (i,j) where i is the min in bot and j is the min in top. The data _top_to_cyl and _bot_to_cyl corresponds to the association of a separatrix to the corresponding 2-tuple. The twist coordinate correspond to the shift between those two indices.

an_origami()

Return one origami with this diagram cylinder if any.

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram('(0,1)-(0,2) (2,3)-(1,3)')
sage: cyl.an_origami()
(1,2)(3,4)
(1,3,4,2)

automorphism_group(order=False)

Return the automorphism group

INPUT:

• order - boolean (default: False) - whether or not return the order of the group

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram('(0,1)-(0,2) (2,3)-(1,3)')
sage: cyl.automorphism_group()
Permutation Group with generators [(0,3)(1,2)]

bot_to_cyl(j)

Return the cylinder above the j-th separatrix.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,2,4)-(1,3,5) (1,5)-(0) (3)-(2,4)')
sage: c
(0,2,4)-(1,3,5) (1,5)-(0) (3)-(2,4)
sage: c.bot_to_cyl(0)
((0, 2, 4), (1, 3, 5))
sage: c.bot_to_cyl(1)
((1, 5), (0,))
sage: c.bot_to_cyl(3)
((3,), (2, 4))

canonical_label(inplace=False, return_map=False)

Return a cylinder diagram with canonical labels.

Note

The canonical label might change depending on your Sage version and the optional packages available.

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram
sage: c1 = CylinderDiagram('(0,5,4)-(0,3,2,1) (1,3,2)-(4,5)')
sage: c1.canonical_label()   # random
(0,4,5)-(1,3,2,5) (1,3,2)-(0,4)
sage: c2 = c1.relabel([2,4,5,1,3,0])
sage: c3 = c1.relabel([5,3,0,1,4,2])
sage: c1.canonical_label() == c2.canonical_label() == c3.canonical_label()
True

TESTS:

sage: import itertools
sage: from surface_dynamics import CylinderDiagram
sage: c = CylinderDiagram('(0)-(1) (1,2)-(0,3) (3)-(2)')
sage: can = c.canonical_label()
sage: for p in itertools.permutations([0,1,2,3]):
....:    cc = c.relabel(p)
....:    ccan, m = cc.canonical_label(return_map=True)
....:    assert cc.relabel(m) == can == ccan

sage: c = CylinderDiagram('(0,4)-(0,3) (1,3)-(1,5) (2,5)-(2,4)')
sage: can = c.canonical_label()
sage: for p in itertools.permutations([0,1,2,3,4,5]):
....:    cc = c.relabel(p)
....:    ccan, m = cc.canonical_label(return_map=True)
....:    assert cc.relabel(m) == can == ccan

sage: c = CylinderDiagram('(0,1)-(0,2) (3,5,4)-(1,4,6) (2,6)-(3,5)')
sage: c is c.canonical_label()
False
sage: c.canonical_label() is c.canonical_label()
True
sage: c.canonical_label().canonical_label() is c.canonical_label()
True

cylcoord_to_origami(lengths, heights, twists=None)

Convert coordinates of the cylinders into an origami.

INPUT:

• lengths - lengths of the separatrices

• heights - heights of the cylinders

• twists - twists for cylinders

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram([((0,1),(1,2)),((2,),(0,))])
sage: c.stratum()
H_2(2)
sage: c.cylcoord_to_origami([1,1,1],[1,1]).stratum()
H_2(2)
sage: o1 = c.cylcoord_to_origami([2,1,2],[1,1],[1,0])
sage: o1 = o1.relabel()
sage: o2 = c.cylcoord_to_origami([2,1,2],[1,1],[0,1])
sage: o2 = o2.relabel()
sage: o3 = c.cylcoord_to_origami([2,1,2],[1,1],[1,1])
sage: o3 = o3.relabel()
sage: all(o.stratum() == Stratum([2], k=1) for o in [o1,o2,o3])
True
sage: o1 == o2 or o1 == o3 or o3 == o1
False

If the lengths are not compatible with the cylinder diagram a ValueError is raised:

sage: c.cylcoord_to_origami([1,2,3],[1,1])
Traceback (most recent call last):
...
ValueError: lengths are not compatible with cylinder equations

TESTS:

sage: c = CylinderDiagram([((0,),(1,)), ((1,2,3),(0,2,3))])
sage: c
(0)-(1) (1,2,3)-(0,2,3)
sage: lengths = [1,1,1,1]
sage: heights = [1,1]
sage: c.cylcoord_to_origami(lengths,heights,[0,0])
(1)(2,3,4)
(1,2)(3,4)
sage: c.cylcoord_to_origami(lengths,heights,[0,1])
(1)(2,3,4)
(1,2,3)(4)
sage: c.cylcoord_to_origami(lengths,heights,[0,2])
(1)(2,3,4)
(1,2,4)(3)

cylcoord_to_origami_iterator(lengths, heights)

Convert coordinates of the cylinders into an origami.

INPUT:

• lengths - lengths of the separatrices

• heights - heights of the cylinders

OUTPUT:

• iterator over all possible origamis with those lengths and heights…

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram('(0,1,2)-(3,1,2) (3)-(0)')
sage: for o in cyl.cylcoord_to_origami_iterator((1,1,1,1),(1,1)):
....:     print(o)
(1,2,3)(4)
(1,4)(2,3)
(1,2,3)(4)
(1,2,4)(3)
(1,2,3)(4)
(1,3,4)(2)

The number of origamis generated is just the product of the widths:

sage: sum(1 for _ in cyl.cylcoord_to_origami_iterator((2,1,1,2),(3,2)))
8

cylinder_graph()

Return the cylinder graph.

The cylinder graph is the graph whose vertex set are the cylinders and for each saddle connection there is a directed edge from the adjacent cylinders. The multiplicities are encoded in the labels.

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram

sage: c = CylinderDiagram('(0,1,5)-(2,5) (2)-(0,1,3) (3,4)-(4)')
sage: c.cylinder_graph()
Looped digraph on 3 vertices
sage: c.cylinder_graph().edges(sort=True)
[(0, 0, 1), (0, 1, 1), (1, 0, 2), (1, 2, 1), (2, 2, 1)]

sage: c = CylinderDiagram('(0,1,3,5)-(2,5,3) (2,4)-(0,4,1)')
sage: c.cylinder_graph().edges(sort=True)
[(0, 0, 2), (0, 1, 1), (1, 0, 2), (1, 1, 1)]

cylinders()

Return the cylinders as a list of pairs (bot, top).

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,2,4)-(1,3,5) (1,5)-(0) (3)-(2,4)')
sage: c
(0,2,4)-(1,3,5) (1,5)-(0) (3)-(2,4)
sage: c.cylinders()
[((0, 2, 4), (1, 3, 5)), ((1, 5), (0,)), ((3,), (2, 4))]

dual_graph()

The dual graph of the stable curve at infinity in the horizontal direction.

This graph is defines as follows. Cut each horizontal cylinder along a circumference, then the vertices are the equivalence class of half cylinder modulo the relation “linked by a saddle connection” and the edges are the circumferences.

EXAMPLES:

sage: from surface_dynamics import *

We consider the three diagrams of the stratum H(1,1):

sage: c1 = CylinderDiagram('(0,1,2,3)-(0,1,2,3)')
sage: c1.stratum()
H_2(1^2)
sage: c1.dual_graph()
Looped multi-graph on 1 vertex
sage: c2 = CylinderDiagram('(0,1)-(1,2) (2,3)-(0,3)')
sage: c2.stratum()
H_2(1^2)
sage: c2.dual_graph()
Looped multi-graph on 1 vertex
sage: c3 = CylinderDiagram('(0,1)-(2,3) (2)-(0) (3)-(1)')
sage: c3.stratum()
H_2(1^2)
sage: c3.dual_graph()
Looped multi-graph on 2 vertices

horizontal_symmetry()

Return the cylinder diagram obtained by reflecting the cylinder configuration along the horizontal axis.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,3,4)-(0,3,5) (1,2,5)-(1,2,4)')
sage: c.horizontal_symmetry()
(0,5,3)-(0,4,3) (1,4,2)-(1,5,2)

sage: c.separatrix_diagram().horizontal_symmetry() == c.horizontal_symmetry().separatrix_diagram()
True

sage: A = Stratum([2,2], k=1)
sage: all(c.horizontal_symmetry().stratum() == A for c in A.cylinder_diagrams())
True

inverse()

Return the inverse cylinder diagram.

The inverse of a cylinder diagram is the cylinder diagram in which all cylinders have been reversed. It corresponds to the multiplication by -1 on the underlying Abelian differential.

Combinatorially the operation is b0-t0 … bk-tk becomes t0-b0 … tk-bk

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,1)-(0,2) (3,5,4)-(1,4,6) (2,6)-(3,5)')
sage: c
(0,1)-(0,2) (2,6)-(3,5) (3,5,4)-(1,4,6)
sage: c.inverse()
(0,2)-(0,1) (1,4,6)-(3,5,4) (3,5)-(2,6)

The operation can also be defined at the level of the separatrix diagrams and the two operation commutes:

sage: c.separatrix_diagram().inverse() == c.inverse().separatrix_diagram()
True

The inversion can also be seen as the composition of the horizontal and vertical symmetries:

sage: c.horizontal_symmetry().vertical_symmetry() == c.inverse()
True
sage: c.vertical_symmetry().horizontal_symmetry() == c.inverse()
True

The inversion is an involution on cylinder diagrams:

sage: all(cc.inverse().inverse() == cc for cc in Stratum([4], k=1).cylinder_diagrams()) # long time
True

is_connected()

Test the connectedness of this cylinder diagram.

TESTS:

sage: from surface_dynamics import *

sage: CylinderDiagram('(0)-(1) (1)-(0)').is_connected()
True
sage: CylinderDiagram('(0,1)-(0) (2)-(1,2)').is_connected()
True

sage: CylinderDiagram('(0)-(0) (1)-(1)').is_connected()
False
sage: CylinderDiagram('(0,1)-(3) (2)-(2) (3)-(0,1)').is_connected()
False

is_hyperelliptic(verbose=False)

Test of hyperellipticity

Each stratum of Abelian differentials as up to three connected components. For the strata H(2g-2) and H(g-1,g-1) there is a special component called hyperelliptic in which all translation surfaces (X,omega) in that component are such that X is hyperelliptic.

This function returns True if and only if the cylinder diagrams correspond to a decomposition of a surface associated to the hyperelliptic components in H(2g-2) or H(g-1,g-1).

EXAMPLES:

sage: from surface_dynamics import *

In genus 2, strata H(2) and H(1,1), all surfaces are hyperelliptic:

sage: for c in Stratum([2], k=1).cylinder_diagrams():
....:     print("%d %s" % (c.ncyls(), c.is_hyperelliptic()))
1 True
2 True

sage: for c in Stratum([1,1], k=1).cylinder_diagrams():
....:     print("%d %s" % (c.ncyls(), c.is_hyperelliptic()))
1 True
2 True
2 True
3 True

In higher genera, some of them are, some of them are not:

sage: C = Stratum([4], k=1).cylinder_diagrams()
sage: len(C)
15
sage: sum(c.is_hyperelliptic() for c in C)
5

sage: C = Stratum([2,2], k=1).cylinder_diagrams()
sage: len(C)
41
sage: sum(c.is_hyperelliptic() for c in C)
11

is_isomorphic(other, return_map=False)

Test whether this cylinder diagram is isomorphic to other.

EXAMPLES:

sage: from surface_dynamics import *

sage: c1 = CylinderDiagram('(0,2,1)-(3,4,5) (3)-(1) (4)-(2) (5)-(0)')
sage: c2 = CylinderDiagram('(0,2,1)-(3,5,4) (3)-(1) (4)-(2) (5)-(0)')
sage: c1.is_isomorphic(c2)
False

sage: c3 = CylinderDiagram('(1,3,5)-(2,4,0) (2)-(5) (4)-(3) (0)-(1)')
sage: c1.is_isomorphic(c3)
True
sage: ans, m = c1.is_isomorphic(c3, return_map=True)
sage: assert ans is True and c1.relabel(m) == c3

sage: c4 = CylinderDiagram('(4,2,3)-(1,5,0) (1)-(3) (0)-(2) (5)-(4)')
sage: c2.is_isomorphic(c4)
True
sage: ans, m = c2.is_isomorphic(c4, return_map=True)
sage: assert ans is True and c2.relabel(m) == c4

sage: c1 = CylinderDiagram('(0,5)-(3,4) (1,4)-(2,5) (2)-(0) (3)-(1)')
sage: c2 = CylinderDiagram('(0,5)-(3,4) (1,4)-(2,5) (2)-(1) (3)-(0)')
sage: c1.is_isomorphic(c2)
False

sage: c1 = CylinderDiagram('(0,1)-(4,5) (2,4)-(0,3) (3,5)-(1,2)')
sage: c2 = CylinderDiagram('(0,1)-(2,3) (2,4)-(1,4) (3,5)-(0,5)')
sage: c3 = CylinderDiagram('(0,5)-(2,5) (1,4)-(0,4) (2,3)-(1,3)')
sage: c1.is_isomorphic(c2)
False
sage: c1.is_isomorphic(c3)
False
sage: c2.is_isomorphic(c3)
False

TESTS:

sage: from surface_dynamics import CylinderDiagram
sage: c = CylinderDiagram('(0,3)-(3,7) (1,6,4)-(0,2,4,6,8) (2,8,7,5)-(1,5)')
sage: c1 = c.relabel([4,7,0,3,2,1,6,8,5])
sage: c2 = c.relabel([6,3,1,8,2,0,4,5,7])
sage: assert c.is_isomorphic(c1) and c.is_isomorphic(c2) and c1.is_isomorphic(c2)
sage: _, m1 = c1.is_isomorphic(c, return_map=True)
sage: assert c1.relabel(m1) == c
sage: _, m2 = c2.is_isomorphic(c, return_map=True)
sage: assert c2.relabel(m2) == c

lengths_cone()

Return the rational polyhedron corresponding to the set of length with the given fixed heights.

-> one can obtain ehrhart series for each of them! It tells us that we have a nice asymptotics… and the asymptotics is simply given by the volume of this polytope (up to the ignored twists parameters)!

lengths_minimal_solution()

Return an integral solution for the lengths equation with minimal sum

matrix_relation()

Return the matrix of relation on the lengths of the separatrices.

The output matrix has size ncyls times nseps.

EXAMPLES:

sage: from surface_dynamics import *

For a one cylinder diagram, there is no relations:

sage: cyl = CylinderDiagram('(0,1,2,3)-(0,1,2,3)')
sage: cyl.matrix_relation()
[0 0 0 0]

Here is an example in the stratum H(2):

sage: cyl = CylinderDiagram('(0,1)-(0,2) (2)-(1)')
sage: cyl.stratum()
H_2(2)
sage: cyl.matrix_relation()
[ 0  1 -1]
[ 0 -1  1]

origami_iterator(n)

Iteration over all origamis with n squares.

INPUT:

• n - positive integer - the number of squares

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram('(0,1,2)-(3,1,2) (3)-(0)')
sage: for o in cyl.origami_iterator(4):
....:     print(o)
....:     print(o.stratum())
....:     print(o.nb_squares())
(1,2,3)(4)
(1,4)(2,3)
H_2(1^2)
4
(1,2,3)(4)
(1,2,4)(3)
H_2(1^2)
4
(1,2,3)(4)
(1,3,4)(2)
H_2(1^2)
4

origamis(n=None)

Return the set of origamis having n squares.

If n is None then return the origamis with less number of squares.

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram('(0,1,2)-(0,1,3) (3)-(2)')
sage: o5 = cyl.origamis(5)
sage: o5[0]
(1,2,3,4)(5)
(1,5,4,2,3)
sage: o5[1].nb_squares()
5
sage: o5[2].stratum_component()
H_2(1^2)^hyp

TESTS:

sage: c1 = CylinderDiagram("(0,1)-(0,3,4,5) (2,3,5)-(1) (4)-(2)")
sage: c2 = CylinderDiagram("(0,1)-(0,5) (2)-(4) (3,4)-(1) (5)-(2,3)")
sage: c3 = CylinderDiagram("(0,3)-(5) (1)-(0) (2,5)-(3,4) (4)-(1,2)")
sage: len(c1.origamis(8))
12
sage: len(c2.origamis(8))
12
sage: len(c3.origamis(8))
12

relabel(perm, inplace=False)

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram
sage: c = CylinderDiagram('(0,3)-(3,7) (1,6,4)-(0,2,4,6,8) (2,8,7,5)-(1,5)')
sage: c.relabel([3,1,2,6,4,5,0,7,8])
(0,4,1)-(0,8,3,2,4) (2,8,7,5)-(1,5) (3,6)-(6,7)
sage: c
(0,3)-(3,7) (1,6,4)-(0,2,4,6,8) (2,8,7,5)-(1,5)
sage: c.relabel([3,1,2,6,4,5,0,7,8], inplace=True)
(0,4,1)-(0,8,3,2,4) (2,8,7,5)-(1,5) (3,6)-(6,7)
sage: c
(0,4,1)-(0,8,3,2,4) (2,8,7,5)-(1,5) (3,6)-(6,7)

TESTS:

sage: c = CylinderDiagram('(0,3)-(3,7) (1,6,4)-(0,2,4,6,8) (2,8,7,5)-(1,5)')
sage: c1 = c.relabel([3,1,2,6,4,5,0,7,8], inplace=False)
sage: c2 = c.relabel([3,1,2,6,4,5,0,7,8], inplace=True)
sage: assert c is c2 and c1 == c2
sage: c1._check()
sage: c2._check()

sage: c1 = c.relabel([1,5,0,6,8,3,2,7,4], inplace=False)
sage: c2 = c.relabel([1,5,0,6,8,3,2,7,4], inplace=True)
sage: assert c is c2 and c1 == c2
sage: c1._check()
sage: c2._check()

separatrix_diagram()

Return the underlying separatrix diagram

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)(2,3,4)','(0,3)(1,4,2)'); s
(0,1)(2,3,4)-(0,3)(1,4,2)
sage: c = s.to_cylinder_diagram([(0,1),(1,0)]); c
(0,1)-(1,4,2) (2,3,4)-(0,3)
sage: c.separatrix_diagram() == s
True

smallest_integer_lengths()

Check if there is a integer solution that satisfy the cylinder conditions.

If there is a solution, the function returns a list a pair (total_length, list_of_lengths) that consists of the sum of the length of the separatrices together with the list of lengths. Otherwise, returns False.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,1)-(0,2) (2,3)-(1,3)')
sage: c.smallest_integer_lengths()
(4, [1, 1, 1, 1])
sage: c = CylinderDiagram('(0,1,2)-(3) (3)-(0) (4)-(1,2,4)')
sage: c.smallest_integer_lengths()
False

sage: c = CylinderDiagram('(0,1)-(0,5) (2)-(3) (3,6)-(8) (4,8)-(6,7) (5)-(2,4) (7)-(1)')
sage: c.smallest_integer_lengths()
(13, [1, 2, 1, 1, 1, 2, 1, 2, 2])

spin_parity()

Return the spin parity of any surface that is built from this cylinder diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,1,2,3,4)-(0,1,2,3,4)')
sage: c.spin_parity()
0
sage: c = CylinderDiagram('(0,1,2,3,4)-(0,1,4,2,3)')
sage: c.spin_parity()
1

sage: c = CylinderDiagram('(0,2,6,1)-(0,8,1,9,2,5,7,4) (3,7,4,8,9,5)-(3,6)')
sage: c.spin_parity()
0
sage: c = CylinderDiagram('(3,7,4,8,9,5)-(0,8,1,9,2,5,7,4) (0,2,6,1)-(3,6)')
sage: c.spin_parity()
1

stratum_component()

Return the connected component of stratum of self.

EXAMPLES:

sage: from surface_dynamics import *

sage: CylinderDiagram('(0,1)-(0,2) (2)-(1)').stratum_component()
H_2(2)^hyp

sage: c = CylinderDiagram('(0,3,2,1)-(1,4,3,2) (4,7,6,5)-(0,7,6,5)')
sage: c.stratum_component()
H_4(3^2)^hyp
sage: c = CylinderDiagram('(0,1,4)-(1,6,7) (2,5,3)-(0,2,4) (6)-(5) (7)-(3)')
sage: c.stratum_component()
H_4(3^2)^nonhyp

sage: c = CylinderDiagram('(0,6)-(1,7) (1,5,4,3,2)-(2,6,5,4,3) (7,9,8)-(0,9,8)')
sage: c.stratum_component()
H_5(4^2)^hyp
sage: c = CylinderDiagram('(0,2,6,1)-(0,8,1,9,2,5,7,4) (3,7,4,8,9,5)-(3,6)')
sage: c.stratum_component()
H_5(4^2)^even
sage: c = CylinderDiagram('(3,7,4,8,9,5)-(0,8,1,9,2,5,7,4) (0,2,6,1)-(3,6)')
sage: c.stratum_component()
H_5(4^2)^odd

symmetries()

Return a triple (horiz_sym, vert_sym, inv_sym)

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,1)-(2,3,5) (2,3,4)-(1) (5)-(0,4)')
sage: c.symmetries()
(False, True, False)

sage: c.horizontal_symmetry().is_isomorphic(c)
False
sage: c.vertical_symmetry().is_isomorphic(c)
True
sage: c.inverse().is_isomorphic(c)
False

sage: CylinderDiagram('(0,2,1,4,3)-(0,4,2,1,3)').symmetries()
(True, True, True)
sage: CylinderDiagram('(0,3)-(0,4,5) (1,4,2)-(1,3) (5)-(2)').symmetries()
(False, False, True)
sage: CylinderDiagram('(0,2,3,1)-(0,2,1,4) (4)-(3)').symmetries()
(True, False, False)
sage: CylinderDiagram('(0,1,2)-(0,3,1,4) (3,4)-(2)').symmetries()
(False, True, False)
sage: CylinderDiagram('(0,1)-(0,3,4) (2,3)-(1) (4)-(2)').symmetries()
(False, False, False)

tikz_string(cyl_height=0.8, cyl_sep=1.3, cyl_pos=None, sep_labels=None)

INPUT:

• cyl_height - (optional) height of cylinders

• cyl_sep - (optional) vertical space between cylinders

• cyl_pos - (optional) position of left corners of cylinders. If provided, cyl_sep is ignored.

• sep_labels - labels of the separatrices

to_directed_graph()

Return a labeled directed graph that encodes the cylinder diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,1,5)-(2,5) (2)-(0,1,3) (3,4)-(4)'); c
(0,1,5)-(2,5) (2)-(0,1,3) (3,4)-(4)
sage: G = c.to_directed_graph(); G
Looped multi-digraph on 6 vertices
sage: G.edges(sort=True)
[(0, 1, 'b'), (0, 1, 't'), (0, 2, 'c'), (0, 5, 'c'), (1, 2, 'c'), (1, 3, 't'), (1, 5, 'b'), (1, 5, 'c'), (2, 0, 'c'), (2, 1, 'c'), (2, 2, 'b'), (2, 3, 'c'), (2, 5, 't'), (3, 0, 't'), (3, 4, 'b'), (3, 4, 'c'), (4, 3, 'b'), (4, 4, 'c'), (4, 4, 't'), (5, 0, 'b'), (5, 2, 'c'), (5, 2, 't'), (5, 5, 'c')]

to_ribbon_graph()

Return a ribbon graph

A ribbon graph is a graph embedded in an oriented surface such that its complement is a union of topological discs. To a cylinder diagram we associate the graph which consists of separatrices together with a choice of one vertical edge in each cylinder.

The edges of the ribbon graph are labeled by (i,nseps+i) for separatrices and by (2(nseps+j),2(nseps+j)+1) for vertical in cylinders.

EXAMPLES:

sage: from surface_dynamics import *

sage: C = CylinderDiagram([((0,1),(0,2)),((2,),(1,))])
sage: C.stratum()
H_2(2)
sage: R = C.to_ribbon_graph(); R
Ribbon graph with 1 vertex, 5 edges and 2 faces
sage: l,m = R.cycle_basis(intersection=True)
sage: m.rank() == 2 * C.genus()
True

TESTS:

sage: f = lambda c: c.to_ribbon_graph().cycle_basis(intersection=True)[1]

sage: a = Stratum([2], k=1)
sage: all(f(c).rank() == 4 for c in a.cylinder_diagrams())
True
sage: a = Stratum([1,1], k=1)
sage: all(f(c).rank() == 4 for c in a.cylinder_diagrams())
True

to_ribbon_graph_with_holonomies(lengths, heights, twists)

top_to_cyl(j)

Return the cylinder below the j-th separatrix.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,2,4)-(1,3,5) (1,5)-(0) (3)-(2,4)')
sage: c.top_to_cyl(0)
((1, 5), (0,))
sage: c.top_to_cyl(2)
((3,), (2, 4))

vertical_symmetry()

Return the cylinder diagram obtained by reflecting the cylinder configuration along the vertical axis.

EXAMPLES:

sage: from surface_dynamics import *

sage: c = CylinderDiagram('(0,3,4)-(0,3,5) (1,2,5)-(1,2,4)')
sage: c.vertical_symmetry()
(0,4,3)-(0,5,3) (1,5,2)-(1,4,2)

sage: c.separatrix_diagram().vertical_symmetry() == c.vertical_symmetry().separatrix_diagram()
True

sage: A = Stratum([2,2], k=1)
sage: all(c.vertical_symmetry().stratum() == A for c in A.cylinder_diagrams())
True

volume_contribution()

Return the volume contribution of this cylinder diagram as a generalized multiple zeta values.

EXAMPLES:

sage: from surface_dynamics import *

sage: c0, c1 = Stratum([2], k=1).cylinder_diagrams()
sage: v0 = c0.volume_contribution()  # optional: latte_int
sage: v0                             # optional: latte_int
(1/3)/((w)^4)
sage: v0.integral_sum_as_mzv()       # optional: latte_int
1/3*ζ(4)
sage: v1 = c1.volume_contribution()  # optional: latte_int
sage: v1                             # optional: latte_int
(2/3)/((w1)*(w0 + w1)^3) + (1/3)/((w1)^2*(w0 + w1)^2)
sage: v1.integral_sum_as_mzv()       # optional: latte_int
2/3*ζ(1,3) + 1/3*ζ(2,2)

sage: for c in Stratum([1,1], k=1).cylinder_diagrams():  # optional: latte_int
....:     print(c, c.volume_contribution().integral_sum_as_mzv())
(0,3,1,2)-(0,3,1,2) 1/6*ζ(5)
(0)-(1) (1,2,3)-(0,2,3) 1/3*ζ(2,3) + 1/3*ζ(3,2)
(0,3)-(1,3) (1,2)-(0,2) ζ(1,4) + 1/3*ζ(2,3)
(0,1)-(2,3) (2)-(1) (3)-(0) 1/3*ζ(1,3) + 1/3*ζ(2,2) - 1/3*ζ(2,3) - 1/3*ζ(3,2) + 1/3*ζ(4) - 1/3*ζ(5)

sage: sum(c.volume_contribution() for c in Stratum([2,1,1], k=1).cylinder_diagrams(1)).integral_sum_as_mzv()  # optional: latte_int
7/180*ζ(8)

Detailed contribution of 2 cylinder diagrams:

sage: cyls = Stratum([2,1,1], k=1).cylinder_diagrams(2)
sage: sum(cyls[k].volume_contribution() for k in [2,7,8,21,22]).integral_sum_as_mzv()  # optional: latte_int
13/630*ζ(5,3) + 13/252*ζ(6,2)
sage: sum(cyls[k].volume_contribution() for k in [0,11,19,20]).integral_sum_as_mzv()  # optional: latte_int
1/21*ζ(4,4) + 4/63*ζ(5,3)
sage: sum(cyls[k].volume_contribution() for k in [3,10]).integral_sum_as_mzv()  # optional: latte_int
2/35*ζ(3,5) + 3/70*ζ(4,4)
sage: sum(cyls[k].volume_contribution() for k in [13,23,24]).integral_sum_as_mzv()  # optional: latte_int
2/21*ζ(2,6) + 4/105*ζ(3,5)
sage: sum(cyls[k].volume_contribution() for k in [9]).integral_sum_as_mzv()  # optional: latte_int
1/21*ζ(1,7) + 1/126*ζ(2,6)
sage: sum(cyls[k].volume_contribution() for k in [5]).integral_sum_as_mzv()  # optional: latte_int
2/105*ζ(3,5) + 1/70*ζ(4,4)
sage: sum(cyls[k].volume_contribution() for k in [6,26]).integral_sum_as_mzv()  # optional: latte_int
1/7*ζ(1,7) + 1/14*ζ(2,6) + 1/21*ζ(3,5) + 1/28*ζ(4,4) + 2/105*ζ(5,3)
sage: sum(cyls[k].volume_contribution() for k in [1,14]).integral_sum_as_mzv()  # optional: latte_int
2/7*ζ(1,7) + 1/7*ζ(2,6) + 2/21*ζ(3,5) + 3/70*ζ(4,4)
sage: sum(cyls[k].volume_contribution() for k in [17,27]).integral_sum_as_mzv()  # optional: latte_int
2/7*ζ(1,7) + 1/7*ζ(2,6) + 4/105*ζ(3,5)
sage: sum(cyls[k].volume_contribution() for k in [4,25]).integral_sum_as_mzv()  # optional: latte_int
1/7*ζ(1,7) + 1/42*ζ(2,6)
sage: sum(cyls[k].volume_contribution() for k in [12,28]).integral_sum_as_mzv()  # optional: latte_int
4/21*ζ(1,7) + 2/21*ζ(2,6) + 8/315*ζ(3,5)
sage: sum(cyls[k].volume_contribution() for k in [15,16]).integral_sum_as_mzv()  # optional: latte_int
4/21*ζ(1,7) + 2/21*ζ(2,6) + 8/315*ζ(3,5)
sage: sum(cyls[k].volume_contribution() for k in [18]).integral_sum_as_mzv()  # optional: latte_int
1/36*ζ(7) - 1/36*ζ(8)

weighted_adjacency_matrix(canonicalize=True)

Return the weighted adjacency matrix of this cylinder diagram.

There is a vertex per cylinder and the weight from cyl1 to cyl2 is the number of saddle connections which are on top of cyl1 and in the bottom of cyl2.

EXAMPLES:

sage: from surface_dynamics import Stratum
sage: for cd in Stratum([1,1], k=1).cylinder_diagrams():
....:     print(cd.weighted_adjacency_matrix())
[4]
[0 1]
[1 2]
[1 1]
[1 1]
[0 0 1]
[0 0 1]
[1 1 0]

widths_and_heights_iterator(n, height_one=False)

Iterate over the possible integer widths and heights of the cylinders for which the corresponding translation surface has area n.

At each iteration, the output is a pair of (lengths, heights). You can then use cylcoord_to_origami() to build the corresponding origami.

INPUT:

• height_one – (boolean default False) whether to return only coordinates with cylinder height one.

EXAMPLES:

sage: from surface_dynamics import *

sage: cyl = CylinderDiagram([((0,1),(0,2)),((2,),(1,))])
sage: cyl
(0,1)-(0,2) (2)-(1)

sage: it = cyl.widths_and_heights_iterator(10)
sage: l,h = next(it)
sage: print(l)
(2, 1, 1)
sage: print(h)
[3, 1]
sage: cyl.cylcoord_to_origami(l,h)
(1,2,3)(4,5,6)(7,8,9)(10)
(1,4,7)(2,5,8)(3,6,9,10)

sage: it = cyl.widths_and_heights_iterator(10, height_one=True)
sage: l,h = next(it)
sage: print(l)
(8, 1, 1)
sage: print(h)
[1, 1]
sage: cyl.cylcoord_to_origami(l,h)
(1,2,3,4,5,6,7,8,9)(10)
(1)(2)(3)(4)(5)(6)(7)(8)(9,10)

TESTS:

sage: c1 = CylinderDiagram("(0,1)-(0,3,4,5) (2,3,5)-(1) (4)-(2)")
sage: c2 = CylinderDiagram("(0,1)-(0,5) (2)-(4) (3,4)-(1) (5)-(2,3)")
sage: c3 = CylinderDiagram("(0,3)-(5) (1)-(0) (2,5)-(3,4) (4)-(1,2)")
sage: list(c1.widths_and_heights_iterator(8))
[((1, 3, 1, 1, 1, 1), [1, 1, 1])]
sage: list(c2.widths_and_heights_iterator(8))
[((1, 2, 1, 1, 1, 2), [1, 1, 1, 1])]
sage: list(c3.widths_and_heights_iterator(8))
[((1, 1, 1, 1, 2, 2), [1, 1, 1, 1])]

sage: for n in range(8, 12):
....:     for c in c1,c2,c3:
....:         L1 = [wh for wh in c.widths_and_heights_iterator(n) if all(h == 1 for h in wh[1])]
....:         L2 = list(c.widths_and_heights_iterator(n, height_one=True))
....:         assert L1 == L2, (L1, L2)

widths_generating_series(var='w')

Generating series of the number of lengths solutions given the widths.

WARNING: when a triangulation is involved, the generating series ignore some lower dimensional polytopes!!

INPUT:

• var - (optional) an optional name for the variable

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram

sage: c = CylinderDiagram('(0,1)-(0,2) (2)-(1)')
sage: c.widths_generating_series()  # optional: latte_int
(1)/((1 - w0)*(1 - w0*w1))

sage: c = CylinderDiagram('(0)-(2) (1,2,3)-(4,5) (4)-(3) (5)-(0,1)')
sage: c.widths_generating_series()  # optional: latte_int
(1)/((1 - w1*w3)*(1 - w1*w2)*(1 - w0*w1*w3))

sage: c = CylinderDiagram('(0,1,3)-(0,2,5) (2,4)-(1,3) (5)-(4)')
sage: c.widths_generating_series()  # optional: latte_int
(1)/((1 - w0)*(1 - w0*w1)*(1 - w0*w1*w2)^2) + (1)/((1 - w0)*(1 - w0*w1)^2*(1 - w0*w1*w2))

class surface_dynamics.flat_surfaces.separatrix_diagram.QuadraticCylinderDiagram(arg1, arg2=None)

Cylinder diagram for quadratic differentials

Cylinder diagrams are encoded as a Ribbon graph together with a pairing of faces (in particular the number of faces must be even).

EXAMPLES:

sage: from surface_dynamics import *

If you start with strings, the cylinders are preserved but the names of saddle connections are changed:

sage: QuadraticCylinderDiagram('(4,4,5)-(6,6,1) (2,3,2,0)-(1,0,5,3)')
(0,0,1)-(2,2,3) (4,5,4,6)-(3,6,1,5)

cylcoord_to_pillowcase_cover(lengths, heights, twists=None, verbose=False)

Convert coordinates of the cylinders into a pillowcase cover.

The pillow is considered as made of two 1 x 1 squares in order to avoid denominators in the input lengths, heights and twists.

INPUT:

• lengths - positive integers - lengths of the separatrices

• heights - positive integers - heights of the cylinders

• twists - (optional) non-negative integers - twists. The twist is measured as the difference in horizontal coordinates between the smallest element in bottom and the smallest in element in top.

OUTPUT: a pillowcase cover

EXAMPLES:

sage: from surface_dynamics import *

Some pillows in Q(-1^4):

sage: q = QuadraticCylinderDiagram('(0,0)-(1,1)')
sage: q.cylcoord_to_pillowcase_cover([1,1],[1],[0])
g0 = (1)
g1 = (1)
g2 = (1)
g3 = (1)
sage: q.cylcoord_to_pillowcase_cover([1,1],[1],[1])
g0 = (1)
g1 = (1)
g2 = (1)
g3 = (1)
sage: q.cylcoord_to_pillowcase_cover([2,2],[1],[0])
g0 = (1)(2)
g1 = (1,2)
g2 = (1,2)
g3 = (1)(2)
sage: q.cylcoord_to_pillowcase_cover([2,2],[1],[1])
g0 = (1)(2)
g1 = (1,2)
g2 = (1)(2)
g3 = (1,2)
sage: q.cylcoord_to_pillowcase_cover([2,2],[1],[2]) == q.cylcoord_to_pillowcase_cover([2,2],[1],[2])
True
sage: q.cylcoord_to_pillowcase_cover([3,3],[1],[0])
g0 = (1)(2,3)
g1 = (1,3)(2)
g2 = (1,3)(2)
g3 = (1)(2,3)
sage: q.cylcoord_to_pillowcase_cover([3,3],[1],[1])
g0 = (1)(2,3)
g1 = (1,3)(2)
g2 = (1)(2,3)
g3 = (1,2)(3)

sage: q.cylcoord_to_pillowcase_cover([1,1],[2],[0])
g0 = (1)(2)
g1 = (1)(2)
g2 = (1,2)
g3 = (1,2)
sage: q.cylcoord_to_pillowcase_cover([1,1],[2],[1]) == q.cylcoord_to_pillowcase_cover([1,1],[2],[0])
True

sage: q.cylcoord_to_pillowcase_cover([2,2],[2],[1])
g0 = (1)(2)(3,4)
g1 = (1,2)(3)(4)
g2 = (1,3)(2,4)
g3 = (1,4)(2,3)

Two one cylinder examples in Q(2^2):

sage: q1 = QuadraticCylinderDiagram('(0,1,0,1)-(2,3,2,3)')
sage: q2 = QuadraticCylinderDiagram('(0,1,0,2)-(3,1,3,2)')

sage: q1.cylcoord_to_pillowcase_cover([2,2,2,2],[1],[0])
g0 = (1,2,3,4)
g1 = (1,3)(2,4)
g2 = (1,3)(2,4)
g3 = (1,4,3,2)
sage: q1.cylcoord_to_pillowcase_cover([2,2,2,2],[1],[1])
g0 = (1,2,3,4)
g1 = (1,3)(2,4)
g2 = (1,4,3,2)
g3 = (1,3)(2,4)
sage: p = q1.cylcoord_to_pillowcase_cover([2,6,4,4],[3],[1])
sage: p.stratum()
Q_2(2^2)
sage: p.nb_pillows()
24

One two cylinders example in Q(2^2):

sage: q = QuadraticCylinderDiagram('(0,1)-(2,3) (0,3)-(1,2)')
sage: p = q.cylcoord_to_pillowcase_cover([1,1,1,1], [2,2], [0,1])
sage: p
g0 = (1,4,2,3)
g1 = (1,3,2,4)
g2 = (1,2)(3,4)
g3 = (1,2)(3,4)
sage: p.stratum()
Q_2(2^2)
sage: q.cylcoord_to_pillowcase_cover([1,3,1,3], [2,2], [0,1]).stratum()
Q_2(2^2)

TESTS:

sage: from surface_dynamics import *
sage: q = QuadraticCylinderDiagram('(0,0)-(1,1)')
sage: q.cylcoord_to_pillowcase_cover([1,2],[1])
Traceback (most recent call last):
...
ValueError: sum of lengths on top and bottom differ

cylinders(dart=False)

Cylinders of self

Return a list of pairs (bot, top) where, by convention the bottom corresponds to the face with smaller index in the list of faces.

EXAMPLES:

sage: from surface_dynamics import *
sage: from surface_dynamics.flat_surfaces.separatrix_diagram import QuadraticCylinderDiagram
sage: rg = RibbonGraph(edges='(0,1)(2,3)(4,5)(6,7)', faces='(0,1)(2,4,5)(3)(6,7)', connected=False)
sage: q = QuadraticCylinderDiagram(rg, '(0,1)(2,3)')
sage: q.cylinders()
[((0, 0), (1, 2, 2)), ((1,), (3, 3))]
sage: q.cylinders(True)
[((0, 1), (2, 4, 5)), ((3,), (6, 7))]

edges()

The set of edges.

lengths_cone()

Return the polytope of admissible lengths.

EXAMPLES:

sage: from surface_dynamics import *

sage: rg = RibbonGraph(edges='(0,1)(2,3)(4,5)(6,7)', faces='(0,1)(2,4,5)(3)(6,7)', connected=False)
sage: q = QuadraticCylinderDiagram(rg, '(0,1)(2,3)')
sage: q.stratum()
Q_0(1, -1^5)
sage: q.lengths_cone().rays_list()
[[1, 0, 1, 0], [1, 2, 0, 1]]

sage: rg = RibbonGraph(edges='(0,1)(2,3)(4,5)(6,7)', faces='(0,2,3)(1)(4,6,7)(5)', connected=False)
sage: q = QuadraticCylinderDiagram(rg, '(0,2)(1,3)')

sage: rg = RibbonGraph(edges='(1,2)(3,4)(5,6)(7,8)(9,10)(11,12)', faces='(1,2)(3,4,6)(5)(8)(7,9,10)(11,12)', connected=False)
sage: q = QuadraticCylinderDiagram(rg, '(0,1)(2,4)(3,5)')
sage: q.stratum()
Q_0(1^2, -1^6)
sage: L = q.lengths_cone()
sage: L
A 3-dimensional polyhedron in QQ^6 defined as the convex hull of 1 vertex and 3 rays

ncyls()

Number of cylinders.

nseps()

Number of edges

num_cylinders()

Number of cylinders.

num_darts()

Number of darts

num_edges()

Number of edges

stratum()

Return the stratum of quadratic differentials associated to this cylinder diagram

EXAMPLES:

sage: from surface_dynamics import *

sage: QuadraticCylinderDiagram('(0,0)-(1,1)').stratum()
Q_0(-1^4)

sage: QuadraticCylinderDiagram('(0,0)-(1,1,2,2,3,3)').stratum()
Q_0(1, -1^5)

sage: QuadraticCylinderDiagram('(0,2,3,2)-(1,0,1,3)').stratum()
Q_2(2^2)

sage: QuadraticCylinderDiagram('(0,1)-(2,3) (0)-(4,4) (1)-(5,5) (2)-(6,6) (3)-(7,7)').stratum()
Q_0(2^2, -1^8)

widths_generating_series(var='w')

Generating series of the number of saddle connection lengths of this quadratic differential cylinder diagram.

Warning

When a triangulation is involved, the generating series ignore some lower dimensional polytopes that are counted twice!

EXAMPLES:

sage: from surface_dynamics import *

sage: q = QuadraticCylinderDiagram('(0,1,2,3,3)-(0,4,4,2,1)')
sage: q.widths_generating_series()  # optional -- latte_int
(1)/((1 - w)^3*(1 - w^2))

sage: q = QuadraticCylinderDiagram('(0,0,1,1,2,2)-(3,3,4,4)')
sage: q.widths_generating_series()  # optional -- latte_int
(3)/((1 - w^2)^4)

sage: q = QuadraticCylinderDiagram('(0,0,1)-(2,2,3) (1,4)-(3,4)')
sage: q.widths_generating_series()  # optional -- latte_int
(1)/((1 - w1)*(1 - w0*w1)*(1 - w0^2))

sage: q = QuadraticCylinderDiagram('(0,0,1,2,3)-(1,4,4,5,6) (2,5,7,7,8)-(3,6,8,9,9)')
sage: F = q.widths_generating_series()  # optional -- latte_int
sage: q = QuadraticCylinderDiagram('(0,0,1,2,3)-(1,4,4,5,6) (2,5,7,8,8)-(3,6,7,9,9)')
sage: F = q.widths_generating_series()  # optional -- latte_int

class surface_dynamics.flat_surfaces.separatrix_diagram.SeparatrixDiagram(data, top=None, check=True, copy=True)

Separatrix diagram of oriented foliation.

A separatrix diagram is a 2-tuple of permutations (bot,top) such that bot and top share the same number of cycles.

bot (resp. top) has to be thought a bottom (resp. top) of a potential face as in the following:

    -- bot -->
-------------------
   <-- top --

The order for bot and top is chosen in such a way that it corresponds to the orientation of a face.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,2)(1,3,4)','(0,4)(2,1,3)')
sage: print(s)
(0,2)(1,3,4)-(0,4)(1,3,2)
sage: print(s.stratum())
H_3(4)

automorphism_group(implementation='graph')

Return the automorphism group of self.

That is the centralizer of the permutations top and bottom.

INPUT:

• implementation - either graph or gap

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,3,1,4,2)','(0,1,2,3,4)')
sage: G1 = S.automorphism_group(implementation='graph'); G1
Permutation Group with generators [(0,1,2,3,4)]
sage: G2 = S.automorphism_group(implementation='gap'); G2
Subgroup ...
sage: G1.is_isomorphic(G2)
True

bot()

The bot permutation as a list from 0 to nseps-1

Warning: the output list should not be modified

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0)(1,2)','(0,1)(2)')
sage: s.bot()
[0, 2, 1]

bot_cycle_string()

Return the cycles of the top permutation as a string.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,2)(3,4)','(0)(1,2,3)')
sage: S.bot_cycle_string()
'(0,2)(1)(3,4)'

bot_cycle_tuples()

Return the cycles of the bottom permutation as a list of tuples.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,2)(3,4)','(0)(1,2,3)')
sage: S.bot_cycle_tuples()
[(0, 2), (1,), (3, 4)]

bot_orbit(i)

Return the orbit of i under the bot permutation

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)(2,5)(3,4,6)','(0,1,5)(2,3,6)(4)')
sage: s.bot_orbit(0)
(0, 1)
sage: s.bot_orbit(4)
(3, 4, 6)

bot_perm()

Return the bot as a permutation (element of a group)

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0)(1,2)','(0,1)(2)')
sage: s.bot_perm()
(2,3)

canonical_label(inplace=False)

Relabel self according to some canonical labels.

The result is cached.

INPUT:

• inplace - boolean (default: True) - if True modify self if not return a new separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: bot = '(0,1,3,6,7,5)(2,4)(8)(9)'
sage: top = '(0)(1,2)(3,4,5)(6,7,8,9)'
sage: s = SeparatrixDiagram(bot,top)
sage: s.canonical_label()
(0)(1)(2,3,4,5,6,7)(8,9)-(0,1,2,3)(4,7,9)(5)(6,8)

TESTS:

sage: from surface_dynamics import *

sage: bot = [3,2,4,0,1]
sage: top = [1,0,3,4,2]
sage: b = [None]*5; t = [None]*5
sage: for p in Permutations([0,1,2,3,4]):
....:     for i in range(5):
....:         b[p[i]] = p[bot[i]]
....:         t[p[i]] = p[top[i]]
....:     s = SeparatrixDiagram(b,t)
....:     print(s.canonical_label())
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
...
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)
(0,1)(2,3,4)-(0,2,4)(1,3)

cylinder_diagram_iterator(connected=True, up_to_symmetry=True)

Construct all cylinder diagrams from given separatrix diagram (i.e. a pair of permutations).

INPUT:

• connected - boolean (default: True) - if true, returns only connected cylinder diagrams.

• up_to_symmetry - boolean (default: True) take care of the horizontal and vertical symmetries.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)(2,3)(4,5)','(1,2)(3,4)(5,0)')
sage: for c in s.cylinder_diagram_iterator(): print(c)  # random
(0,5)-(0,4) (1,4)-(1,3) (2,3)-(2,5)
(0,3)-(0,5) (1,2)-(1,4) (4,5)-(2,3)
(0,5)-(3,4) (1,4)-(0,2) (2,3)-(1,5)
sage: sum(1 for _ in s.cylinder_diagram_iterator(up_to_symmetry=False))
6
sage: sum(1 for _ in s.cylinder_diagram_iterator(up_to_symmetry=True))
3

Here is an example with some symmetry:

sage: s = SeparatrixDiagram('(0)(1)(2,3)(4,5,6)-(0,1)(2,4)(3,5)(6)')
sage: s.vertical_symmetry().canonical_label() == s
True
sage: C1 = [CylinderDiagram('(0,1)-(4) (2,4,3)-(5,6) (5)-(0,2) (6)-(1,3)'),
....:       CylinderDiagram('(0,3,1)-(0,6) (2,6)-(4,5) (4)-(1) (5)-(2,3)'),
....:       CylinderDiagram('(0,1)-(0,4) (2,3,4)-(5,6) (5)-(2) (6)-(1,3)')]
sage: C2 = s.cylinder_diagrams()
sage: assert len(C1) == len(C2)
sage: for (c1, c2) in zip(C1, C2): assert c1.is_isomorphic(c2)

TESTS:

sage: from surface_dynamics import SeparatrixDiagram
sage: s = SeparatrixDiagram('(0,3)(1,4,5)(2)','(0)(1,2)(3,4,5)')
sage: C2 = s.cylinder_diagram_iterator(up_to_isomorphism=True)
doctest:warning
...
DeprecationWarning: use the option 'up_to_symmetry' instead of 'up_to_isomorphism'
...

cylinder_diagrams(connected=True, up_to_symmetry=True)

Return the list of cylinder diagrams associated to this separatrix diagram.

We warn that the cylinder diagram may be renumeroted in the output list (in order to prevent repetitions). If you care about numerotation the option up_to_symmetry should be set to False.

INPUT:

• connected - boolean (default: True)

• up_to_symmetry - boolean (default: True)

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0)(1)(2)','(0)(1)(2)')
sage: for c in s.cylinder_diagrams(connected=True): print(c)
(0)-(2) (1)-(0) (2)-(1)
sage: for c in s.cylinder_diagrams(connected=False): print(c)
(0)-(0) (1)-(1) (2)-(2)
(0)-(1) (1)-(0) (2)-(2)
(0)-(2) (1)-(0) (2)-(1)

sage: s = SeparatrixDiagram('(0,1)(2)','(0)(1,2)')
sage: C1 = [CylinderDiagram('(0,1)-(0,2) (2)-(1)')]
sage: C2 = s.cylinder_diagrams()
sage: assert len(C1) == len(C2)
sage: for (c1, c2) in zip(C1, C2): assert c1.is_isomorphic(c2)

In the example below, there is no isomorphism problem for the cylinder diagram generation as the separatrix diagram admit no automorphism:

sage: s = SeparatrixDiagram('(0,3)(1,4,5)(2)','(0)(1,2)(3,4,5)')
sage: s.automorphism_group()
Permutation Group with generators [()]
sage: C1 = [CylinderDiagram('(0,3,1)-(5) (2,5)-(3,4) (4)-(0,2,1)'),
....:       CylinderDiagram('(0,1,2)-(0,1,5) (3,5)-(2,4) (4)-(3)'),
....:       CylinderDiagram('(0,2,3)-(2,5) (1,4)-(0,1,3) (5)-(4)')]
sage: C2 = s.cylinder_diagrams()
sage: C3 = s.cylinder_diagrams(up_to_symmetry=False)
sage: assert len(C1) == len(C2) == len(C3)
sage: for (c1, c2, c3) in zip(C1, C2, C3): assert c1.is_isomorphic(c2) and c1.is_isomorphic(c3)

TESTS:

sage: from surface_dynamics import SeparatrixDiagram
sage: s = SeparatrixDiagram('(0,3)(1,4,5)(2)','(0)(1,2)(3,4,5)')
sage: C2 = s.cylinder_diagrams(up_to_isomorphism=True)
doctest:warning
...
DeprecationWarning: use the option 'up_to_symmetry' instead of 'up_to_isomorphism'
...

degree()

Return the degree (number of separatrices) of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,1)(2,3)','(1,3,2)(0)')
sage: S.degree()
4

euler_characteristic()

Return the Euler characteristic

EXAMPLES:

sage: from surface_dynamics import *

sage: SeparatrixDiagram('(0)','(0)').euler_characteristic()
0

sage: CylinderDiagram([((0,),(0,))]).euler_characteristic()
0
sage: CylinderDiagram([((0,1),(0,2)), ((2,),(1,))]).euler_characteristic()
-2

genus()

Return the genus

EXAMPLES:

sage: from surface_dynamics import *

sage: CylinderDiagram([((0,),(0,))]).genus()
1
sage: CylinderDiagram([((0,1),(0,1))]).genus()
1
sage: CylinderDiagram([((0,1,2),(0,1,2))]).genus()
2
sage: CylinderDiagram([((0,1,2,3),(0,1,2,3))]).genus()
2
sage: CylinderDiagram([((0,1,2,3,4),(0,1,2,3,4))]).genus()
3

homological_dimension_of_cylinders()

Returns the dimension in the first homology group of the span of waist curves of horizontal cylinders.

EXAMPLES:

sage: from surface_dynamics import *

Homological dimension in the stratum H(2):

sage: c = CylinderDiagram('(0,1,2)-(0,1,2)')
sage: c.stratum()
H_2(2)
sage: c.homological_dimension_of_cylinders()
1
sage: c = CylinderDiagram('(0,1)-(1,2) (2)-(0)')
sage: c.stratum()
H_2(2)
sage: c.homological_dimension_of_cylinders()
2

Homological dimensions for cylinder diagrams in H(1,1):

sage: c = CylinderDiagram('(0,1,2,3)-(0,1,2,3)')
sage: c.stratum()
H_2(1^2)
sage: c.homological_dimension_of_cylinders()
1
sage: c = CylinderDiagram('(0,1)-(0,2) (2,3)-(1,3)')
sage: c.stratum()
H_2(1^2)
sage: c.homological_dimension_of_cylinders()
2
sage: c = CylinderDiagram('(0,1,2)-(1,2,3) (3)-(0)')
sage: c.stratum()
H_2(1^2)
sage: c.homological_dimension_of_cylinders()
2
sage: c = CylinderDiagram('(0,1)-(2,3) (2)-(0) (3)-(1)')
sage: c.stratum()
H_2(1^2)
sage: c.homological_dimension_of_cylinders()
2

homologous_cylinders()

Return the list of homologous cylinders.

OUTPUT: a list of lists. Each sublist is an equivalence class of > 1 homologous cylinders.

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram
sage: c = CylinderDiagram('(0,7,1,2)-(3,6,4,5) (3,6,4,5)-(0,7,1,2)')
sage: c.homologous_cylinders()
[[0, 1]]

sage: c = CylinderDiagram('(0,1)-(2,3) (2)-(0) (3)-(1)')
sage: c.homologous_cylinders()
[]

sage: c = CylinderDiagram('(0,2,1)-(9) (3,6,4,5)-(7,10,8) (7,9,8)-(3,6,4,5) (10)-(0,2,1)')
sage: c.homologous_cylinders()
[[0, 3], [1, 2]]

horizontal_symmetry()

Return the horizontal symmetric of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,2,3)(4,5)','(1,2,3)(4,5,0)')
sage: sh = s.horizontal_symmetry()
sage: print(sh)
(0,5,4)(1,3,2)-(0,3,2,1)(4,5)

sage: c = s.cylinder_diagrams(up_to_symmetry=False)[0].horizontal_symmetry()
sage: ch = sh.cylinder_diagrams(up_to_symmetry=False)[0]
sage: c.is_isomorphic(ch)
True

incoming_edges_perm()

Permutation associated to turning around vertices in trigonometric order.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)','(2,3)')
sage: s.incoming_edges_perm()
[1, 0, 3, 2]

sage: s = SeparatrixDiagram('(0,5,2)(1,3,4)(6,7,8)','(0,3,7,8)(1,5)(2,4,6)')
sage: s.incoming_edges_perm()
[7, 0, 8, 2, 5, 4, 3, 1, 6]

sage: c = CylinderDiagram('(0,5,2,1,4,3)-(0,4,2,1,5,3)')
sage: c.incoming_edges_perm()
[4, 5, 1, 0, 3, 2]

inverse()

Return the inverse of this separatrix diagram, that is the one we obtain after application of -Id.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,2)(3,4,5,6,7,8)-(0,1,3,5,7)(2,4,6,8)')
sage: s.inverse()
(0,1,3,5,7)(2,4,6,8)-(0,1,2)(3,4,5,6,7,8)
sage: s.horizontal_symmetry().vertical_symmetry() == s.inverse()
True
sage: s.vertical_symmetry().horizontal_symmetry() == s.inverse()
True

is_in_normal_form()

Test normal form

Return True if self is in normal form and False otherwise.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,2)(3,4,5)(6,7,8)','(0,3,7,8)(1,5)(2,4,6)')
sage: s.is_in_normal_form()
False
sage: s.canonical_label().is_in_normal_form()
True

is_isomorphic(other, return_map=False)

Test whether this separatrix diagram is isomorphic to other.

EXAMPLES:

sage: from surface_dynamics import *

sage: bot = [1,2,0,3]
sage: top = [1,0,3,2]
sage: s = SeparatrixDiagram(bot,top); s
(0,1,2)(3)-(0,1)(2,3)
sage: m = [3,0,1,2]
sage: bot2 = [0]*4
sage: top2 = [0]*4
sage: for i in range(4):
....:     bot2[m[i]] = m[bot[i]]
....:     top2[m[i]] = m[top[i]]
sage: ss = SeparatrixDiagram(bot2,top2)
sage: s.is_isomorphic(ss)
True
sage: m = [1,2,0,3]
sage: for i in range(4):
....:   bot2[m[i]] = m[bot[i]]
....:   top2[m[i]] = m[top[i]]
sage: ss = SeparatrixDiagram(bot2,top2)
sage: s.is_isomorphic(ss)
True

ncyls()

Return the number of cylinders of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,1)(2,3)','(1,3,2)(0)')
sage: S.ncyls()
2

nseps()

Return the degree (number of separatrices) of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,1)(2,3)','(1,3,2)(0)')
sage: S.degree()
4

num_edges()

Return the degree (number of separatrices) of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,1)(2,3)','(1,3,2)(0)')
sage: S.degree()
4

outgoing_edges_perm()

Permutation associated to turning around vertices in trigonometric order.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)','(2,3)')
sage: s.outgoing_edges_perm()
[1, 0, 3, 2]

sage: s = SeparatrixDiagram('(0,5,2)(1,3,4)(6,7,8)','(0,3,7,8)(1,5)(2,4,6)')
sage: s.outgoing_edges_perm()
[6, 2, 1, 5, 0, 8, 7, 4, 3]

sage: c = CylinderDiagram('(0,5,2,1,4,3)-(0,4,2,1,5,3)')
sage: c.outgoing_edges_perm()
[5, 4, 1, 0, 2, 3]

profile()

Return the angles around each vertex

EXAMPLES:

sage: from surface_dynamics import *

sage: a = Stratum([1,1,0], k=1)
sage: s = a.separatrix_diagrams()[0]
sage: s.profile()
[2, 2, 1]

relabel(perm, inplace=False)

Relabel self according to the permutation perm.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0)(2,3,4)','(0,3,2)(1)')
sage: s
(0)(1)(2,3,4)-(0,3,2)(1)(4)
sage: s.relabel(perm=[1,0,2,3,4])
(0)(1)(2,3,4)-(0)(1,3,2)(4)
sage: s.relabel(perm=[1,2,0,3,4])
(0,3,4)(1)(2)-(0,1,3)(2)(4)

saddle_connections_graph(mutable=False)

Return the fat graph (or ribbon graph) made by the saddle connections.

The return graph is a FatGraph. The saddle connection labelled i on this diagram gets labels 2i and 2i+1 in the graph (there one label per half-edge in the fat graph). The even labels correspond to half-edges in the bottom of cylinders while the odd ones correspond to the top.

EXAMPLES:

sage: from surface_dynamics import Stratum
sage: H11 = Stratum([1,1], k=1).unique_component()
sage: for cd in H11.cylinder_diagrams():
....:     fg = cd.saddle_connections_graph()
....:     print(cd.ncyls(), [comp.genus() for comp in fg.connected_components()])
1 [1]
2 [0]
2 [0]
3 [0, 0]

TESTS:

sage: from surface_dynamics import AbelianStrata
sage: for g in (2, 3):
....:     for H in AbelianStrata(genus=g):
....:         for C in H.components():
....:             for cd in C.cylinder_diagrams():
....:                 fg = cd.saddle_connections_graph()
....:                 assert fg.num_faces() == 2 * cd.ncyls()
....:                 assert fg.euler_characteristic() == cd.euler_characteristic() + 2 * cd.ncyls()
....:                 assert len(fg.connected_components()) == 1 + cd.ncyls() - cd.homological_dimension_of_cylinders()

stratum()

Return the Abelian stratum this separatrix diagram belongs to.

EXAMPLES:

sage: from surface_dynamics import *

sage: SeparatrixDiagram('(0)(1)(2)','(0)(1)(2)').stratum()
H_1(0^3)
sage: SeparatrixDiagram('(0,1)(2)','(0,2)(1)').stratum()
H_2(2)

symmetries()

Return a triple of boolean (horiz_sym, vert_sym, inverse_sym) which correspond to the symmetry of self.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,2)(3,4,5)-(0,1)(2,3,4,5)')
sage: s.symmetries()
(False, True, False)
sage: s.horizontal_symmetry().is_isomorphic(s)
False
sage: s.vertical_symmetry().is_isomorphic(s)
True
sage: s.inverse().is_isomorphic(s)
False

sage: s = SeparatrixDiagram('(0,1,3,5)(2,4)-(0,4,1,5)(2,3)')
sage: s.symmetries()
(True, False, False)
sage: s.horizontal_symmetry().is_isomorphic(s)
True
sage: s.vertical_symmetry().is_isomorphic(s)
False
sage: s.inverse().is_isomorphic(s)
False

sage: s = SeparatrixDiagram('(0,1,3,5)(2,4)-(0,3,2,1)(5,4)')
sage: s.symmetries()
(False, False, True)
sage: s.horizontal_symmetry().is_isomorphic(s)
False
sage: s.vertical_symmetry().is_isomorphic(s)
False
sage: s.inverse().is_isomorphic(s)
True

sage: s = SeparatrixDiagram('(0)(1,2,3,4,5)-(0,1,2,5,3)(4)')
sage: s.symmetries()
(False, False, False)
sage: s.horizontal_symmetry().is_isomorphic(s)
False
sage: s.vertical_symmetry().is_isomorphic(s)
False
sage: s.inverse().is_isomorphic(s)
False

TESTS:

sage: sym = lambda s: (s.horizontal_symmetry().is_isomorphic(s),
....:                  s.vertical_symmetry().is_isomorphic(s),
....:                  s.inverse().is_isomorphic(s))
sage: from surface_dynamics.flat_surfaces.separatrix_diagram import separatrix_diagram_iterator
sage: for s in separatrix_diagram_iterator((2,2,2,2)):
....:     assert s.symmetries() == sym(s)
sage: for s in separatrix_diagram_iterator((4,2)):
....:     assert s.symmetries() == sym(s)

to_cylinder_diagram(pairing)

Return a cylinder diagram with the given pairing

The pairing should be a list of 2-tuples of integer.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,3)(2,4)','(0,2)(1,4,3)'); s
(0,1,3)(2,4)-(0,2)(1,4,3)

sage: s.to_cylinder_diagram([(0,0),(1,1)])
(0,1,3)-(0,2) (2,4)-(1,4,3)
sage: s.to_cylinder_diagram([(1,1),(0,0)])
(0,1,3)-(0,2) (2,4)-(1,4,3)

sage: s.to_cylinder_diagram([(0,1),(1,0)])
(0,1,3)-(1,4,3) (2,4)-(0,2)
sage: s.to_cylinder_diagram([(1,0),(0,1)])
(0,1,3)-(1,4,3) (2,4)-(0,2)

to_directed_graph()

Return a graph that encodes this separatrix diagram.

The vertices correspond to separatrix and the edges are of two types

• ‘b’ neighbor corresponds to the right neighbors on the bottom permutation

• ‘t’ edges correspond to the neighbor of the top permutation

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,1)(2,3,4)','(0,3,2)(1,4)')
sage: G = S.to_directed_graph(); G
Looped multi-digraph on 5 vertices
sage: G.vertices(sort=True)
[0, 1, 2, 3, 4]
sage: G.edges(sort=True)
[(0, 1, 'b'), (0, 3, 't'), (1, 0, 'b'), (1, 4, 't'), (2, 0, 't'), (2, 3, 'b'), (3, 2, 't'), (3, 4, 'b'), (4, 1, 't'), (4, 2, 'b')]

top()

Return the top permutation of self as a list.

Warning: the output should not be modified

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,3)(2,4)','(0,4)(1,2,3)')
sage: s.top()
[4, 2, 3, 1, 0]

top_cycle_string()

Return the cycle of the top permutation as a string.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,2)(3,4)','(0)(1,2,3)')
sage: S.top_cycle_string()
'(0)(1,2,3)(4)'

top_cycle_tuples()

Return the cycle of the top permutation as a list of tuples.

EXAMPLES:

sage: from surface_dynamics import *

sage: S = SeparatrixDiagram('(0,2)(3,4)','(0)(1,2,3)')
sage: S.top_cycle_tuples()
[(0,), (1, 2, 3), (4,)]

top_orbit(i)

Return the orbit of i under the top permutation.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1)(2,5)(3,4,6)','(0,1,5)(2,3,6)(4)')
sage: s.top_orbit(0)
(0, 1, 5)
sage: s.top_orbit(6)
(2, 3, 6)

top_perm()

Return the top as a permutation

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0)(1,2)','(1)(0,2)')
sage: s.top_perm()
(1,3)

vertical_symmetry()

Return the vertical symmetric of this separatrix diagram.

EXAMPLES:

sage: from surface_dynamics import *

sage: s = SeparatrixDiagram('(0,1,2,3)(4,5)','(1,2,3)(4,5,0)')
sage: sv = s.vertical_symmetry()
sage: print(sv)
(0,3,2,1)(4,5)-(0,5,4)(1,3,2)

sage: c = sv.cylinder_diagrams(up_to_symmetry=False)[0].vertical_symmetry()
sage: cv = sv.cylinder_diagrams(up_to_symmetry=False)[0]
sage: c.is_isomorphic(cv)
True

vertices()

Return a list of pairs (vout, vin) where each pair represent a vertex and vout, vin are respectively the labels of outgoing/incoming separatrices at this vertex.

EXAMPLES:

sage: from surface_dynamics import CylinderDiagram
sage: from surface_dynamics.misc.permutation import perm_cycles

sage: c = CylinderDiagram('(0,1)-(0,2,6,7,4,5,3,8) (2,7,3,4,8,6,5)-(1)')
sage: c.vertices()
[([0, 1, 8, 7], [0, 4, 2, 1]), ([2, 4, 5], [3, 6, 5]), ([3, 6], [7, 8])]
sage: perm_cycles(c.outgoing_edges_perm())
[[0, 1, 8, 7], [2, 4, 5], [3, 6]]
sage: perm_cycles(c.incoming_edges_perm())
[[0, 4, 2, 1], [3, 6, 5], [7, 8]]

sage: c = CylinderDiagram('(0,1,3,4,2)-(0,1,5,7,6) (5,6)-(4) (7)-(2,3)')
sage: perm_cycles(c.outgoing_edges_perm())
[[0, 3], [1, 6], [2, 4], [5, 7]]
sage: perm_cycles(c.incoming_edges_perm())
[[0, 5], [1, 2], [3, 4], [6, 7]]

surface_dynamics.flat_surfaces.separatrix_diagram.cyclic_direction(x, y, z)

Returns 1 or -1 depending on the cyclic ordering of (x,y,z)

TESTS:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import cyclic_direction
sage: cyclic_direction(0,1,2)
1
sage: cyclic_direction(1,2,0)
1
sage: cyclic_direction(2,0,1)
1
sage: cyclic_direction(2,1,0)
-1
sage: cyclic_direction(1,0,2)
-1
sage: cyclic_direction(0,2,1)
-1

surface_dynamics.flat_surfaces.separatrix_diagram.hyperelliptic_cylinder_diagram_iterator(a, verbose=False)

Return an iterator over cylinder diagrams of Abelian differentials that double covers Q((a-2), -1^(a+2)).

The generator is up to isomorphism.

TODO:

• An optimization could be obtained by considering the generation of k-subsets of {1,…,n} up to the cyclic symmetry of the tree.

INPUT:

• a - integer - angle of the conical singularity of the quadratic differential.

• verbose - integer (default: 0) - output various information during the iteration (mainly for debug).

EXAMPLES:

sage: from surface_dynamics import *

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import hyperelliptic_cylinder_diagram_iterator
sage: it = hyperelliptic_cylinder_diagram_iterator(3)
sage: c = next(it); c.is_isomorphic(CylinderDiagram('(0,1)-(0,2) (2)-(1)'))
True
sage: c.stratum_component()
H_2(2)^hyp

sage: hyp = Stratum([2,2], k=1).hyperelliptic_component()
sage: all(c.stratum_component() == hyp for c in hyperelliptic_cylinder_diagram_iterator(6))
True

surface_dynamics.flat_surfaces.separatrix_diagram.move_backward(i, v, g01, g23)

Helper function to build pillowcase covers

EXAMPLES:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import move_backward
sage: g23 = [1,2,0]
sage: g01 = [2,0,1]
sage: i,v = 0,0
sage: for _ in range(6):
....:     i,v = move_backward(i, v, g01, g23)
....:     print("%d %d" % (i,v))
2 1
2 0
1 1
1 0
0 1
0 0

sage: i,v = 0,2
sage: for _ in range(6):
....:     i,v = move_backward(i, v, g01, g23)
....:     print("%d %d" % (i,v))
1 3
1 2
2 3
2 2
0 3
0 2

surface_dynamics.flat_surfaces.separatrix_diagram.move_forward(i, v, g01, g23)

Helper function to build pillowcase covers

EXAMPLES:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import move_forward
sage: g23 = [1,2,0]
sage: g01 = [2,0,1]
sage: i,v = 0,0
sage: for _ in range(6):
....:     i,v = move_forward(i, v, g01, g23)
....:     print("%d %d" % (i,v))
0 1
1 0
1 1
2 0
2 1
0 0

sage: i,v = 0,2
sage: for _ in range(6):
....:     i,v = move_forward(i, v, g01, g23)
....:     print("%d %d" % (i,v))
0 3
2 2
2 3
1 2
1 3
0 2

surface_dynamics.flat_surfaces.separatrix_diagram.orientation_cover(alpha, phi, a, verbose=0)

Build the cylinder diagram of Abelian differentials that double covers it.

A quadratic differrential separatrix diagram is given by three permutations

• sigma: the permutation of 1/2-separatrices around vertices

• alpha: the permutation of 1/2-separatrices that describe the separatrices

  (it is a fixed point free involution)

• phi: the permutation of 1/2-separatrices that describe the cycles.

INPUT:

• alpha – permutation

• phi – permutation

• a – number of half separatrices

EXAMPLES:

sage: from surface_dynamics import *

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import orientation_cover
sage: alpha = [3, 2, 1, 0, 5, 4, 7, 6]
sage: phi = [3, 1, 0, 2, 5, 4, 7, 6]
sage: orientation_cover(alpha,phi,3)
(0,2)-(0,1) (1)-(2)

surface_dynamics.flat_surfaces.separatrix_diagram.separatrix_diagram_fast_iterator(profile, ncyls=None)

Iterator over separatrix diagram with given profile

Return a list of 3-tuples [bot, top, s] where bot and top are list on 0, …, nseps-1 that corresponds to a separatrix diagram with profile profile while s is the element conjugacy class corresponding to the profile which equals bot * top.

If ncyls is not None, it should be a list of integers from which the number of cylinders is considered.

Warning: each isomorphism class of separatrix diagram is output more than once in general. If you want a unique representative in each isomorphism class you may consider the method separatrix_diagram_iterator instead.

Uses bounds from [Nav08].

EXAMPLES:

sage: from surface_dynamics import *

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import separatrix_diagram_fast_iterator
sage: for s in sorted(separatrix_diagram_fast_iterator([3])): print(s)
([0, 2, 1], [1, 0, 2], [(0, 1, 2)])
([1, 2, 0], [1, 2, 0], [(0, 2, 1)])
([2, 1, 0], [1, 0, 2], [(0, 2, 1)])
sage: for s in sorted(separatrix_diagram_fast_iterator([2,2])): print(s)
([0, 1, 3, 2], [1, 0, 2, 3], [(0, 1), (2, 3)])
([0, 2, 3, 1], [1, 2, 0, 3], [(0, 1), (2, 3)])
([1, 2, 3, 0], [1, 2, 3, 0], [(0, 2), (1, 3)])
([1, 3, 2, 0], [1, 2, 0, 3], [(0, 2), (1, 3)])
([2, 3, 0, 1], [1, 0, 3, 2], [(0, 3), (1, 2)])
([3, 1, 0, 2], [1, 2, 0, 3], [(0, 3), (1, 2)])
([3, 2, 1, 0], [1, 0, 3, 2], [(0, 2), (1, 3)])

surface_dynamics.flat_surfaces.separatrix_diagram.separatrix_diagram_iterator(profile, ncyls=None)

Iterator over separatrix diagram with given profile and number of cylinders.

Warning: to prevent isomorphism class to be output twice the function implement a cache mechanism. If you intend to iterate through a huge class of separatrix_diagram and do not care about isomorphism problem use separatrix_diagram_fast_iterator instead.

EXAMPLES:

sage: from surface_dynamics import *

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import separatrix_diagram_iterator

sage: for s in sorted(separatrix_diagram_iterator([1,1])): print(s)
(0,1)-(0,1)
(0)(1)-(0)(1)

sage: for s in sorted(separatrix_diagram_iterator([3])): print(s)
(0,1,2)-(0,1,2)
(0)(1,2)-(0,1)(2)

sage: for s in sorted(separatrix_diagram_iterator([2,2])): print(s)
(0,1,2,3)-(0,1,2,3)
(0)(1,2,3)-(0,1,2)(3)
(0,1)(2,3)-(0,2)(1,3)
(0)(1)(2,3)-(0,1)(2)(3)

sage: sum(1 for s in separatrix_diagram_iterator([3,2,2]))
64

surface_dynamics.flat_surfaces.separatrix_diagram.simplex_count(rays)

EXAMPLES:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import simplex_count

sage: rays = [(0,1,1), (1,0,1), (1,1,0)]
sage: simplex_count(rays)
1

sage: rays = [(0,1,1), (1,0,1), (1,1,0)]
sage: simplex_count(rays)
1

sage: rays = [(0,1,1,1),(1,0,1,1),(1,1,0,1),(1,1,1,0)]
sage: simplex_count(rays)
1

surface_dynamics.flat_surfaces.separatrix_diagram.string_to_cycle(s)

TESTS:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import string_to_cycle
sage: string_to_cycle('(3,1,2)')
(3, 1, 2)

surface_dynamics.flat_surfaces.separatrix_diagram.two_non_connected_perms_canonical_labels(bot, top)

EXAMPLES:

sage: from surface_dynamics.flat_surfaces.separatrix_diagram import two_non_connected_perms_canonical_labels
sage: two_non_connected_perms_canonical_labels([3,2,1,0],[0,1,2,3])
([1, 0, 3, 2], [0, 1, 2, 3])