translation_surfaces

The category of translation surfaces.

This module provides shared functionality for all surfaces in sage-flatsurf that are built from Euclidean polygons whose glued edges can be transformed into each other with translations.

See flatsurf.geometry.categories for a general description of the category framework in sage-flatsurf.

Normally, you won’t create this (or any other) category directly. The correct category is automatically determined for immutable surfaces.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.square_torus()
sage: C = S.category()

sage: from flatsurf.geometry.categories import TranslationSurfaces
sage: C.is_subcategory(TranslationSurfaces())
True

class flatsurf.geometry.categories.translation_surfaces.TranslationSurfaces(base_category)

The category of surfaces built by gluing (Euclidean) polygons with translations.

EXAMPLES:

sage: from flatsurf.geometry.categories import TranslationSurfaces
sage: TranslationSurfaces()
Category of translation surfaces

class FiniteType(base_category)

The category of translation surfaces built from finitely many polygons.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: s = translation_surfaces.octagon_and_squares()
sage: s.category()
Category of connected without boundary finite type translation surfaces

class ParentMethods

Provides methods available to all translation surfaces built from finitely many polygons.

If you want to add functionality to such surfaces you most likely want to put it here.

pyflatsurf()

Return an isomorphism to a surface backed by libflatsurf.

EXAMPLES:

sage: from flatsurf import Polygon, MutableOrientedSimilaritySurface

sage: S = MutableOrientedSimilaritySurface(QQ)
sage: S.add_polygon(Polygon(vertices=[(0, 0), (1, 0), (1, 1)]), label=0)
0
sage: S.add_polygon(Polygon(vertices=[(0, 0), (1, 1), (0, 1)]), label=1)
1

sage: S.glue((0, 0), (1, 1))
sage: S.glue((0, 1), (1, 2))
sage: S.glue((0, 2), (1, 0))

sage: S.set_immutable()

sage: T = S.pyflatsurf().codomain()  # optional: pyflatsurf  # random output due to cppyy deprecation warnings
sage: T  # optional: pyflatsurf
Surface backed by FlatTriangulationCombinatorial(vertices = (1, -3, 2, -1, 3, -2), faces = (1, 2, 3)(-1, -2, -3)) with vectors {1: (1, 0), 2: (0, 1), 3: (-1, -1)}

class WithoutBoundary(base_category)

The category of translation surfaces without boundary built from finitely many polygons.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: s = translation_surfaces.octagon_and_squares()
sage: s.category()
Category of connected without boundary finite type translation surfaces

class ParentMethods

Provides methods available to all translation surfaces without boundary that are built from finitely many polygons.

If you want to add functionality for such surfaces you most likely want to put it here.

canonicalize(in_place=None)

Return a canonical version of this translation surface.

EXAMPLES:

We will check if an element lies in the Veech group:

sage: from flatsurf import translation_surfaces
sage: s = translation_surfaces.octagon_and_squares()
sage: s
Translation Surface in H_3(4) built from 2 squares and a regular octagon
sage: from flatsurf.geometry.categories import TranslationSurfaces
sage: s in TranslationSurfaces()
True
sage: a = s.base_ring().gen()
sage: mat = Matrix([[1,2+a],[0,1]])
sage: s1 = s.canonicalize()
sage: s1.set_immutable()
sage: s2 = (mat*s).canonicalize()
sage: s2.set_immutable()
sage: s1.cmp(s2) == 0
True
sage: hash(s1) == hash(s2)
True

erase_marked_points()

Return an isometric or similar surface with a minimal number of regular vertices of angle 2π.

EXAMPLES:

sage: import flatsurf

sage: G = SymmetricGroup(4)
sage: S = flatsurf.translation_surfaces.origami(G('(1,2,3,4)'), G('(1,4,2,3)'))
sage: S.stratum()
H_2(2, 0)
sage: S.erase_marked_points().stratum() # optional: pyflatsurf  # long time (1s)  # random output due to matplotlib warnings with some combinations of setuptools and matplotlib
H_2(2)

sage: for (a,b,c) in [(1,4,11), (1,4,15), (3,4,13)]: # long time (10s), optional: pyflatsurf
....:     T = flatsurf.polygons.triangle(a,b,c)
....:     S = flatsurf.similarity_surfaces.billiard(T)
....:     S = S.minimal_cover("translation")
....:     print(S.erase_marked_points().stratum())
H_6(10)
H_6(2^5)
H_8(12, 2)

If the surface had no marked points then it is returned unchanged by this function:

sage: O = flatsurf.translation_surfaces.regular_octagon()
sage: O.erase_marked_points() is O
True

j_invariant()

Return the Kenyon-Smillie J-invariant of this translation surface.

It is assumed that the coordinates are defined over a number field.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: O = translation_surfaces.regular_octagon()
sage: O.j_invariant()
(
          [2 2]
(0), (0), [2 1]
)

rel_deformation(deformation, local=None, limit=None)

Return a deformed surface obtained by shifting the vertices by deformation.

INPUT:

• deformation – a dict which maps the vertices of this surfaces to vectors. The rel deformation will move each vertex by that amount (relative to the others); any vertex not present in the dict will be treated as a deformation by the zero vector.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.arnoux_yoccoz(4)
sage: S1 = S.rel_deformation({S(0, 0): (1, 0)}).canonicalize()  # optional: pyflatsurf

sage: a = S.base_ring().gen()
sage: S2 = S.rel_deformation({S(0, 0): (a, 0)}).canonicalize()  # optional: pyflatsurf

sage: M = matrix([[a, 0], [0, ~a]])
sage: S2.cmp((M*S1).canonicalize())  # optional: pyflatsurf
0

stratum()

Return the stratum this surface belongs to.

This uses the package surface-dynamics (see http://www.labri.fr/perso/vdelecro/flatsurf_sage.html)

EXAMPLES:

sage: import flatsurf.geometry.similarity_surface_generators as sfg
sage: sfg.translation_surfaces.octagon_and_squares().stratum()
H_3(4)

class ParentMethods

Provides methods available to all translation surfaces in sage-flatsurf.

If you want to add functionality for such surfaces you most likely want to put it here.

canonicalize_mapping()

Return a SurfaceMapping canonicalizing this translation surface.

edge_matrix(p, e=None)

Returns the 2x2 matrix representing a similarity which when applied to the polygon with label \(p\) makes it so the edge \(e\) can be glued to its opposite edge by translation.

Since this is a translation surface, this is just the identity.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.square_torus()
sage: S.edge_matrix(0, 0)
[1 0]
[0 1]

is_translation_surface(positive=True)

Return whether this surface is a translation surface, i.e., return True.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.square_torus()
sage: S.is_translation_surface(positive=True)
True
sage: S.is_translation_surface(positive=False)
True

minimal_translation_cover()

Return the minimal cover of this surface that makes this surface a translation surface, i.e., return this surface itself.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.square_torus()
sage: S.minimal_translation_cover() is S
True

extra_super_categories()

Return the other categories that a translation surface is automatically a member of (apart from being a positive half-translation surface, its orientation is compatible with the orientation of the polygons in the real plane, so it’s “oriented.”)

EXAMPLES:

sage: from flatsurf.geometry.categories import TranslationSurfaces
sage: C = TranslationSurfaces()
sage: C.extra_super_categories()
(Category of oriented polygonal surfaces,)