surface_objects

Geometric objects on surfaces.

This includes singularities, saddle connections and cylinders.

class flatsurf.geometry.surface_objects.Cylinder(s, label0, edges)

Represents a cylinder in a SimilaritySurface. A cylinder for these purposes is a topological annulus in a surface bounded by a finite collection of saddle connections meeting at 180 degree angles.

To Do

• Support cylinders whose monodromy is a dilation.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: s = translation_surfaces.octagon_and_squares()
sage: from flatsurf.geometry.surface_objects import Cylinder
sage: cyl = Cylinder(s, 0, [2, 3, 3, 3, 2, 0, 1, 3, 2, 0])
sage: cyl.initial_label()
0
sage: cyl.edges()
(2, 3, 3, 3, 2, 0, 1, 3, 2, 0)
sage: # a = sqrt(2) below.
sage: cyl.area()
2*a + 4
sage: cyl.circumference().minpoly()
x^4 - 680*x^2 + 400
sage: cyl.holonomy()
(8*a + 12, 4*a + 6)

area()

Return the area of this cylinder if it is contained in a ConeSurface.

boundary()

Return the set of saddle connections in the boundary, oriented so that the surface is on the left.

boundary_components()

Return a set of two elements: the set of saddle connections on the right and left sides. Saddle connections are oriented so that the surface is on the left.

circumference()

In a cone surface, return the circumference, i.e., the length of a geodesic loop running around the cylinder. Since this may not lie in the field of definition of the surface, it is returned as an element of the Algebraic Real Field.

edges()

Return a tuple of edge numbers representing the edges crossed when the cylinder leaves the polygon with \(initial_label\) until it returns by closing.

holonomy()

In a translation surface, return one of the two holonomy vectors of the cylinder, which differ by a sign.

initial_label()

Return one label on the surface that the cylinder passes through.

labels()

Return the set of labels that this cylinder passes through.

next(sc)

Return the next saddle connection as you move around the cylinder boundary moving from sc in the direction of its orientation.

plot(**options)

Plot this cylinder in coordinates used by a graphical surface. This plots this cylinder as a union of subpolygons. Only the intersections with polygons visible in the graphical surface are shown.

Parameters other than \(graphical_surface\) are passed to \(polygon2d\) which is called to render the polygons.

Parameters

graphical_surfacea GraphicalSurface

If not provided or \(None\), the plot method uses the default graphical surface for the surface.

polygons()

Return a list of pairs each consisting of a label and a polygon. Each polygon represents a sub-polygon of the polygon on the surface with the given label. The union of these sub-polygons form the cylinder. The subpolygons are listed in cyclic order.

previous(sc)

Return the previous saddle connection as you move around the cylinder boundary moving from sc in the direction opposite its orientation.

surface()

class flatsurf.geometry.surface_objects.SaddleConnection(surface, start_data, direction, end_data=None, end_direction=None, holonomy=None, end_holonomy=None, check=True, limit=1000)

Represents a saddle connection on a SimilaritySurface.

direction()

Returns a vector parallel to the saddle connection pointing from the start point.

The will be normalized so that its $l_infty$ norm is 1.

end_data()

Return the pair (l, v) representing the label and vertex of the corresponding polygon where the saddle connection terminates.

end_direction()

Returns a vector parallel to the saddle connection pointing from the end point.

The will be normalized so that its \(l_\infty\) norm is 1.

end_holonomy()

Return the holonomy vector of the saddle connection (measured from the end).

In a SimilaritySurface this notion corresponds to developing the saddle connection into the plane using the initial chart coming from the initial polygon.

end_tangent_vector()

Return a tangent vector to the saddle connection based at its start.

holonomy()

Return the holonomy vector of the saddle connection (measured from the start).

In a SimilaritySurface this notion corresponds to developing the saddle connection into the plane using the initial chart coming from the initial polygon.

intersections(traj, count_singularities=False, include_segments=False)

See documentation of intersections()

intersects(traj, count_singularities=False)

See documentation of intersects()

invert()

Return this saddle connection but with opposite orientation.

length()

In a cone surface, return the length of this saddle connection. Since this may not lie in the field of definition of the surface, it is returned as an element of the Algebraic Real Field.

plot(*args, **options)

Equivalent to .trajectory().plot(*args, **options)

start_data()

Return the pair (l, v) representing the label and vertex of the corresponding polygon where the saddle connection originates.

start_tangent_vector()

Return a tangent vector to the saddle connection based at its start.

surface()

trajectory(limit=1000, cache=None)

Return a straight line trajectory representing this saddle connection. Fails if the trajectory passes through more than limit polygons.

flatsurf.geometry.surface_objects.Singularity(similarity_surface, label, v, limit=None)

Return the point of similarity_surface at the v-th vertex of the polygon label.

If the surface is infinite, the limit can be set. In this case the construction of the singularity is successful if the sequence of vertices hit by passing through edges closes up in limit or less steps.

EXAMPLES:

sage: from flatsurf.geometry.similarity_surface_generators import TranslationSurfaceGenerators
sage: s=TranslationSurfaceGenerators.veech_2n_gon(5)
sage: from flatsurf.geometry.surface_objects import Singularity
sage: sing=Singularity(s, 0, 1)
doctest:warning
...
UserWarning: Singularity() is deprecated and will be removed in a future version of sage-flatsurf. Use surface.point() instead.
sage: print(sing)
Vertex 1 of polygon 0
sage: TestSuite(sing).run()

class flatsurf.geometry.surface_objects.SurfacePoint(surface, label, point, ring=None, limit=None)

A point on surface.

INPUT:

• surface – a similarity surface

• label – a polygon label for the polygon with respect to which the point coordinates can be made sense of

• point – coordinates of a point in the polygon label or the index of the vertex of the polygon with label

• ring – a SageMath ring or None (default: None); the coordinate ring for point

• limit – an integer or None (default: None for an unlimited number of steps); if this is a singularity of the surface, then this limits the number of edges that are crossed to determine all the edges adjacent to that singularity. An error is raised if the limit is insufficient.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)

A point can have a single representation with coordinates when it is in interior of a polygon:

sage: S.point(1, (1/2, 1/2))
Point (1/2, 1/2) of polygon 1

A point can have two representations when it is in interior of an edge:

sage: p = S.point(1, (1/2, 0))
sage: q = S.point(2, (1/2, 1))
sage: p == q
True
sage: p.coordinates(2)
((1/2, 1),)

A point can have even more representations when it is a vertex:

sage: S.point(1, (0, 0))
Vertex 0 of polygon 1

contains_vertex(label, v=None)

Checks if the pair (label, v) is in the equivalence class returning true or false. If v is None, the both the pair (label, v) is passed as a single parameter in label.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: p.contains_vertex((1, 0))
doctest:warning
...
UserWarning: contains_vertex() is deprecated and will be removed in a future version of sage-flatsurf; use the == operator instead
doctest:warning
...
UserWarning: Singularity() is deprecated and will be removed in a future version of sage-flatsurf. Use surface.point() instead.
True
sage: p.contains_vertex(label=1, v=0)
True

coordinates(label)

Return coordinates for the point in the in the polygon label.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.mcmullen_L(1, 1, 1, 1)

sage: p = S.point(0, (0, 0))
sage: p.coordinates(0)  # random output: order depends on the Python version
((0, 0), (1, 0), (0, 1), (1, 1))

graphical_surface_point(graphical_surface=None)

Return a flatsurf.graphical.surface_point.GraphicalSurfacePoint to represent this point graphically.

EXAMPLES:

sage: from flatsurf import half_translation_surfaces
sage: S = half_translation_surfaces.step_billiard([1, 1, 1, 1], [1, 1/2, 1/3, 1/4])
sage: p = S.point(0, (1/2, 1/2))
sage: G = p.graphical_surface_point()

is_vertex()

Return whether this point is a singularity of the surface.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))

sage: p.is_vertex()
True

labels()

Return the labels of polygons containing the point.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.mcmullen_L(1, 1, 1, 1)

For a point in the interior of polygon, there is exactly one label:

sage: p = S.point(0, (1/2, 1/2))
sage: p.labels()
{0}

For a point in the interior of an edge of a polygon, there can be up to two labels:

sage: p = S.point(0, (0, 1/2))
sage: p.labels()
{0, 2}

For a point at a vertex, there can be more labels:

sage: p = S.point(0, (0, 0))
sage: p.labels()
{0, 1, 2}

num_coordinates()

Return the number of different coordinate representations of the point.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: p.num_coordinates()
doctest:warning
...
UserWarning: num_coordinates() is deprecated and will be removed in a future version of sage-flatsurf; use len(representatives()) instead.
4

one_vertex()

Return a pair (l, v) from the equivalence class of this singularity.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: p.one_vertex()  # random output: depends on the Python version
doctest:warning
...
UserWarning: one_vertex() is deprecated and will be removed in a future version of sage-flatsurf; use (label, coordinates) = point.representative(); vertex = surface.polygon(label).get_point_position(coordinates).get_vertex() instead
(2, 1)

plot(*args, **kwargs)

Return a plot of this point.

EXAMPLES:

sage: from flatsurf import half_translation_surfaces
sage: S = half_translation_surfaces.step_billiard([1, 1, 1, 1], [1, 1/2, 1/3, 1/4])
sage: p = S.point(0, (0, 0))
sage: p.plot()
...Graphics object consisting of 1 graphics primitive

sage: p = S.point(0, (0, 25/12))
sage: p.plot()
...Graphics object consisting of 1 graphics primitive

representative()

Return a representative of this point, i.e., the first of representatives().

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: p.representative()  # random output: depends on the Python version
(2, (1, 0))

representatives()

Return the representatives of this point as pairs of polygon labels and coordinates.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: p.representatives()
frozenset({(1, (0, 0)), (1, (1, 1)), (2, (0, 1)), (2, (1, 0))})

surface()

Return the surface containing this point.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (1/2, 1/2))
sage: p.surface() is S
True

vertex_set()

Return the list of pairs (l, v) in the equivalence class of this singularity.

EXAMPLES:

sage: from flatsurf import translation_surfaces

sage: permutation = SymmetricGroup(2)('(1, 2)')
sage: S = translation_surfaces.origami(permutation, permutation)
sage: p = S.point(1, (0, 0))
sage: list(p.vertex_set())  # random output: ordering depends on the Python version
doctest:warning
...
UserWarning: vertex_set() is deprecated and will be removed in a future version of sage-flatsurf; use representatives() and then vertex = surface.polygon(label).get_point_position(coordinates).get_vertex() instead
[(2, 1), (1, 2), (1, 0), (2, 3)]