r"""
Geometric objects on surfaces.
This includes singularities, saddle connections and cylinders.
.. jupyter-execute::
:hide-code:
# Allow jupyter-execute blocks in this module to contain doctests
import jupyter_doctest_tweaks
"""
# ****************************************************************************
# This file is part of sage-flatsurf.
#
# Copyright (C) 2017-2020 W. Patrick Hooper
# 2017-2020 Vincent Delecroix
# 2023 Julian Rüth
#
# sage-flatsurf is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# sage-flatsurf is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with sage-flatsurf. If not, see <https://www.gnu.org/licenses/>.
# ****************************************************************************
from sage.misc.cachefunc import cached_method
from sage.modules.free_module_element import vector
from sage.plot.graphics import Graphics
from sage.plot.polygon import polygon2d
from sage.rings.qqbar import AA
from sage.structure.sage_object import SageObject
from sage.structure.element import Element
from flatsurf.geometry.similarity import SimilarityGroup
[docs]
def Singularity(similarity_surface, label, v, limit=None):
r"""
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()
"""
import warnings
warnings.warn(
"Singularity() is deprecated and will be removed in a future version of sage-flatsurf. Use surface.point() instead."
)
return similarity_surface.point(
label, similarity_surface.polygon(label).vertex(v), limit=limit
)
[docs]
class SurfacePoint(Element):
r"""
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
TESTS:
Verify that #275 has been resolved, i.e., points on the boundary can be
created::
sage: from flatsurf import Polygon, MutableOrientedSimilaritySurface
sage: S = MutableOrientedSimilaritySurface(QQ)
sage: S.add_polygon(Polygon(vertices=[(0,0), (-1, -1), (1,0)]))
0
sage: S.add_polygon(Polygon(vertices=[(0,0), (0, 1), (-1,-1)]))
1
sage: S.glue((0, 0), (1, 2))
sage: S.set_immutable()
sage: S
Translation Surface with boundary built from 2 triangles
sage: S(0, (0, 0))
Vertex 0 of polygon 0
sage: S(0, (1/2, 0))
Point (1/2, 0) of polygon 0
sage: S(0, (1, 0))
Vertex 2 of polygon 0
"""
def __init__(self, surface, label, point, ring=None, limit=None):
if limit is not None:
import warnings
warnings.warn(
"limit has been deprecated as a keyword argument when creating points and will be removed without replacement in a future version of sage-flatsurf"
)
self._surface = surface
if ring is None:
ring = surface.base_ring()
if ring is not surface.base_ring():
import warnings
warnings.warn(
"the ring parameter is deprecated and will be removed in a future version of sage-flatsurf; define the surface over a larger ring instead so that this points' coordinates live in the base ring"
)
polygon = surface.polygon(label)
from sage.all import ZZ
if point in ZZ:
point = surface.polygon(label).vertex(point)
point = (ring**2)(point)
point.set_immutable()
position = polygon.get_point_position(point)
if not position.is_inside():
raise NotImplementedError(
"point must be positioned within the polygon with the given label"
)
if position.is_in_interior():
self._representatives = {(label, point)}
elif position.is_in_edge_interior():
self._representatives = {(label, point)}
opposite_edge = surface.opposite_edge(label, position.get_edge())
if opposite_edge is not None:
cross_label, cross_edge = opposite_edge
cross_point = surface.edge_transformation(label, position.get_edge())(
point
)
cross_point.set_immutable()
self._representatives.add((cross_label, cross_point))
elif position.is_vertex():
self._representatives = set()
source_edge = position.get_vertex()
def collect_representatives(label, source_edge, direction, limit):
def rotate(label, source_edge, direction):
if direction == -1:
source_edge = (source_edge - 1) % len(
surface.polygon(label).vertices()
)
opposite_edge = surface.opposite_edge(label, source_edge)
if opposite_edge is None:
return None
label, source_edge = opposite_edge
if direction == 1:
source_edge = (source_edge + 1) % len(
surface.polygon(label).vertices()
)
return label, source_edge
while True:
self._representatives.add((label, source_edge))
# Rotate to the next edge that is leaving at the vertex
rotated = rotate(label, source_edge, direction)
if rotated is None:
# Surface is disconnected
return
label, source_edge = rotated
if limit is not None:
limit -= 1
if limit < 0:
raise ValueError(
"number of edges at singularity exceeds limit"
)
if (label, source_edge) in self._representatives:
break
# Collect respresentatives of edge walking clockwise and counterclockwise
collect_representatives(label, source_edge, 1, limit)
collect_representatives(label, source_edge, -1, limit)
self._representatives = {
(label, surface.polygon(label).vertex(vertex))
for (label, vertex) in self._representatives
}
else:
raise NotImplementedError
self._representatives = frozenset(self._representatives)
super().__init__(surface)
[docs]
def surface(self):
r"""
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
"""
return self._surface
[docs]
def is_vertex(self):
r"""
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
"""
label, coordinates = self.representative()
position = self.surface().polygon(label).get_point_position(coordinates)
return position.is_vertex()
[docs]
def one_vertex(self):
r"""
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)
"""
import warnings
warnings.warn(
"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"
)
label, coordinates = self.representative()
vertex = (
self.surface().polygon(label).get_point_position(coordinates).get_vertex()
)
return label, vertex
[docs]
def representatives(self):
r"""
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))})
"""
return self._representatives
[docs]
def representative(self):
r"""
Return a representative of this point, i.e., the first of
:meth:`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))
"""
return next(iter(self.representatives()))
[docs]
def vertex_set(self):
r"""
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)]
"""
import warnings
warnings.warn(
"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"
)
return [
(
label,
self.surface()
.polygon(label)
.get_point_position(coordinates)
.get_vertex(),
)
for label, coordinates in self.representatives()
]
[docs]
def contains_vertex(self, label, v=None):
r"""
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
"""
import warnings
warnings.warn(
"contains_vertex() is deprecated and will be removed in a future version of sage-flatsurf; use the == operator instead"
)
if v is None:
label, v = label
return Singularity(self.surface(), label, v) == self
[docs]
def num_coordinates(self):
r"""
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
"""
import warnings
warnings.warn(
"num_coordinates() is deprecated and will be removed in a future version of sage-flatsurf; use len(representatives()) instead."
)
return len(self._representatives)
[docs]
def labels(self):
r"""
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}
"""
return {label for (label, _) in self._representatives}
[docs]
def coordinates(self, label):
r"""
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))
"""
return tuple(
coordinates for (l, coordinates) in self._representatives if l == label
)
[docs]
def graphical_surface_point(self, graphical_surface=None):
r"""
Return a
:class:`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()
"""
from flatsurf.graphical.surface_point import GraphicalSurfacePoint
return GraphicalSurfacePoint(self, graphical_surface=graphical_surface)
[docs]
def plot(self, *args, **kwargs):
r"""
Return a plot of this point.
EXAMPLES:
.. jupyter-execute::
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
.. jupyter-execute::
sage: p = S.point(0, (0, 25/12))
sage: p.plot()
...Graphics object consisting of 1 graphics primitive
"""
graphical_surface = None
if args:
graphical_surface = args[0]
args = args[1:]
return self.graphical_surface_point(graphical_surface=graphical_surface).plot(
*args, **kwargs
)
def __repr__(self):
r"""
Return a printable representation of this point.
TESTS::
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: S.point(0, (1/2, 1/2))
Point (1/2, 1/2) of polygon 0
"""
def render(label, coordinates):
if self.is_vertex():
vertex = (
self.surface()
.polygon(label)
.get_point_position(coordinates)
.get_vertex()
)
return "Vertex {} of polygon {}".format(vertex, label)
return "Point {} of polygon {}".format(coordinates, label)
# We pick a specific representative to make our lives easier when doctesting
return min(
render(label, coordinates)
for (label, coordinates) in self.representatives()
)
def __eq__(self, other):
r"""
Return whether this point is indistinguishable from ``other``.
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: p == p
True
sage: q = S.point(0, (1/2, 1/3))
sage: p == q
False
TESTS:
Verify that points can be compared to non-points so they can be put into sets and dicts with other objects::
sage: p == 42
False
"""
if self is other:
return True
if not isinstance(other, SurfacePoint):
return False
if not self._surface == other._surface:
return False
return self._representatives == other._representatives
def _test_category(self, **options):
r"""
Check that this point inherits from the element class of its surface's
category.
Overridden to disable these tests when this is a point of a mutable
surface since the category might then change as the surface becomes
immutable.
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: p._test_category()
"""
if self.surface().is_mutable():
return
super()._test_category(**options)
def __hash__(self):
r"""
Return a hash value 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: q = S.point(4, (0, 0))
sage: hash(p) == hash(q)
True
"""
return hash(self._representatives)
def __ne__(self, other):
r"""
Return whether this point is distinguishable from ``other``.
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: p != p
False
sage: q = S.point(0, (1/2, 1/3))
sage: p != q
True
"""
return not (self == other)
[docs]
class SaddleConnection(SageObject):
r"""
Represents a saddle connection on a SimilaritySurface.
"""
def __init__(
self,
surface,
start_data,
direction,
end_data=None,
end_direction=None,
holonomy=None,
end_holonomy=None,
check=True,
limit=1000,
):
r"""
Construct a saddle connection on a SimilaritySurface.
The only necessary parameters are the surface, start_data, and direction
(to start). If there is missing data that can not be inferred from the surface
type, then a straight-line trajectory will be computed to confirm that this is
indeed a saddle connection. The trajectory will pass through at most limit
polygons before we give up.
Details of the parameters are provided below.
Parameters
----------
surface : a SimilaritySurface
which will contain the saddle connection being constructed.
start_data : a pair
consisting of the label of the polygon where the saddle connection starts
and the starting vertex.
direction : 2-dimensional vector with entries in the base_ring of the surface
representing the direction the saddle connection is moving in (in the
coordinates of the initial polygon).
end_data : a pair
consisting of the label of the polygon where the saddle connection terminates
and the terminating vertex.
end_direction : 2-dimensional vector with entries in the base_ring of the surface
representing the direction to move backward from the end point (in the
coordinates of the terminal polygon). If the surface is a DilationSurface
or better this will be the negation of the direction vector. If the surface
is a HalfDilation surface or better, then this will be either the direction
vector or its negation. In either case the value can be inferred from the
end_data.
holonomy : 2-dimensional vector with entries in the base_ring of the surface
the holonomy of the saddle connection measured from the start. To compute this
you develop the saddle connection into the plane starting from the starting
polygon.
end_holonomy : 2-dimensional vector with entries in the base_ring of the surface
the holonomy of the saddle connection measured from the end (with the opposite
orientation). To compute this you develop the saddle connection into the plane
starting from the terminating polygon. For a translation surface, this will be
the negation of holonomy, and for a HalfTranslation surface it will be either
equal to holonomy or equal to its negation. In both these cases the end_holonomy
can be inferred and does not need to be passed to the constructor.
check : boolean
If all data above is provided or can be inferred, then when check=False this
geometric data is not verified. With check=True the data is always verified
by straight-line flow. Erroroneous data will result in a ValueError being thrown.
Defaults to true.
limit :
The combinatorial limit (in terms of number of polygons crossed) to flow forward
to check the saddle connection geometry.
"""
from flatsurf.geometry.categories import SimilaritySurfaces
if surface not in SimilaritySurfaces():
raise TypeError
self._surface = surface
# Sanitize the direction vector:
V = self._surface.base_ring().fraction_field() ** 2
self._direction = V(direction)
if self._direction == V.zero():
raise ValueError("Direction must be nonzero.")
# To canonicalize the direction vector we ensure its endpoint lies in the boundary of the unit square.
xabs = self._direction[0].abs()
yabs = self._direction[1].abs()
if xabs > yabs:
self._direction = self._direction / xabs
else:
self._direction = self._direction / yabs
# Fix end_direction if not standard.
if end_direction is not None:
xabs = end_direction[0].abs()
yabs = end_direction[1].abs()
if xabs > yabs:
end_direction = end_direction / xabs
else:
end_direction = end_direction / yabs
self._surfacetart_data = tuple(start_data)
if end_direction is None:
from flatsurf.geometry.categories import DilationSurfaces
# Attempt to infer the end_direction.
if self._surface in DilationSurfaces().Positive():
end_direction = -self._direction
elif self._surface in DilationSurfaces() and end_data is not None:
p = self._surface.polygon(end_data[0])
from flatsurf.geometry.euclidean import ccw
if (
ccw(p.edge(end_data[1]), self._direction) >= 0
and ccw(
p.edge(
(len(p.vertices()) + end_data[1] - 1) % len(p.vertices())
),
self._direction,
)
> 0
):
end_direction = self._direction
else:
end_direction = -self._direction
if end_holonomy is None and holonomy is not None:
# Attempt to infer the end_holonomy:
from flatsurf.geometry.categories import (
HalfTranslationSurfaces,
TranslationSurfaces,
)
if self._surface in TranslationSurfaces():
end_holonomy = -holonomy
if self._surface in HalfTranslationSurfaces():
if direction == end_direction:
end_holonomy = holonomy
else:
end_holonomy = -holonomy
if (
end_data is None
or end_direction is None
or holonomy is None
or end_holonomy is None
or check
):
v = self.start_tangent_vector()
traj = v.straight_line_trajectory()
traj.flow(limit)
if not traj.is_saddle_connection():
raise ValueError(
"Did not obtain saddle connection by flowing forward. Limit="
+ str(limit)
)
tv = traj.terminal_tangent_vector()
self._end_data = (tv.polygon_label(), tv.vertex())
if end_data is not None:
if end_data != self._end_data:
raise ValueError(
"Provided or inferred end_data="
+ str(end_data)
+ " does not match actual end_data="
+ str(self._end_data)
)
self._end_direction = tv.vector()
# Canonicalize again.
xabs = self._end_direction[0].abs()
yabs = self._end_direction[1].abs()
if xabs > yabs:
self._end_direction = self._end_direction / xabs
else:
self._end_direction = self._end_direction / yabs
if end_direction is not None:
if end_direction != self._end_direction:
raise ValueError(
"Provided or inferred end_direction="
+ str(end_direction)
+ " does not match actual end_direction="
+ str(self._end_direction)
)
if traj.segments()[0].is_edge():
# Special case (The below method causes error if the trajectory is just an edge.)
self._holonomy = self._surface.polygon(start_data[0]).edge(
start_data[1]
)
self._end_holonomy = self._surface.polygon(self._end_data[0]).edge(
self._end_data[1]
)
else:
from .similarity import SimilarityGroup
sim = SimilarityGroup(self._surface.base_ring()).one()
itersegs = iter(traj.segments())
next(itersegs)
for seg in itersegs:
sim = sim * self._surface.edge_transformation(
seg.start().polygon_label(), seg.start().position().get_edge()
)
self._holonomy = (
sim(traj.segments()[-1].end().point())
- traj.initial_tangent_vector().point()
)
self._end_holonomy = -((~sim.derivative()) * self._holonomy)
if holonomy is not None:
if holonomy != self._holonomy:
print("Combinatorial length: " + str(traj.combinatorial_length()))
print("Start: " + str(traj.initial_tangent_vector().point()))
print("End: " + str(traj.terminal_tangent_vector().point()))
print("Start data:" + str(start_data))
print("End data:" + str(end_data))
raise ValueError(
"Provided holonomy "
+ str(holonomy)
+ " does not match computed holonomy of "
+ str(self._holonomy)
)
if end_holonomy is not None:
if end_holonomy != self._end_holonomy:
raise ValueError(
"Provided or inferred end_holonomy "
+ str(end_holonomy)
+ " does not match computed end_holonomy of "
+ str(self._end_holonomy)
)
else:
self._end_data = tuple(end_data)
self._end_direction = end_direction
self._holonomy = holonomy
self._end_holonomy = end_holonomy
# Make vectors immutable
self._direction.set_immutable()
self._end_direction.set_immutable()
self._holonomy.set_immutable()
self._end_holonomy.set_immutable()
[docs]
def surface(self):
return self._surface
[docs]
def direction(self):
r"""
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.
"""
return self._direction
[docs]
def end_direction(self):
r"""
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.
"""
return self._end_direction
[docs]
def start_data(self):
r"""
Return the pair (l, v) representing the label and vertex of the corresponding polygon
where the saddle connection originates.
"""
return self._surfacetart_data
[docs]
def end_data(self):
r"""
Return the pair (l, v) representing the label and vertex of the corresponding polygon
where the saddle connection terminates.
"""
return self._end_data
[docs]
def holonomy(self):
r"""
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.
"""
return self._holonomy
[docs]
def length(self):
r"""
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.
"""
from flatsurf.geometry.categories import ConeSurfaces
if self._surface not in ConeSurfaces():
raise NotImplementedError(
"length of a saddle connection only makes sense for cone surfaces"
)
return vector(AA, self._holonomy).norm()
[docs]
def end_holonomy(self):
r"""
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.
"""
return self._end_holonomy
[docs]
def start_tangent_vector(self):
r"""
Return a tangent vector to the saddle connection based at its start.
"""
return self._surface.tangent_vector(
self._surfacetart_data[0],
self._surface.polygon(self._surfacetart_data[0]).vertex(
self._surfacetart_data[1]
),
self._direction,
)
[docs]
@cached_method(key=lambda self, limit, cache: None)
def trajectory(self, limit=1000, cache=None):
r"""
Return a straight line trajectory representing this saddle connection.
Fails if the trajectory passes through more than limit polygons.
"""
if cache is not None:
import warnings
warnings.warn(
"The cache keyword argument of trajectory() is ignored. Trajectories are always cached."
)
v = self.start_tangent_vector()
traj = v.straight_line_trajectory()
traj.flow(limit)
if not traj.is_saddle_connection():
raise ValueError(
"Did not obtain saddle connection by flowing forward. Limit="
+ str(limit)
)
return traj
[docs]
def plot(self, *args, **options):
r"""
Equivalent to ``.trajectory().plot(*args, **options)``
"""
return self.trajectory().plot(*args, **options)
[docs]
def end_tangent_vector(self):
r"""
Return a tangent vector to the saddle connection based at its start.
"""
return self._surface.tangent_vector(
self._end_data[0],
self._surface.polygon(self._end_data[0]).vertex(self._end_data[1]),
self._end_direction,
)
[docs]
def invert(self):
r"""
Return this saddle connection but with opposite orientation.
"""
return SaddleConnection(
self._surface,
self._end_data,
self._end_direction,
self._surfacetart_data,
self._direction,
self._end_holonomy,
self._holonomy,
check=False,
)
[docs]
def intersections(self, traj, count_singularities=False, include_segments=False):
r"""
See documentation of :meth:`~.straight_line_trajectory.AbstractStraightLineTrajectory.intersections`
"""
return self.trajectory().intersections(
traj, count_singularities, include_segments
)
[docs]
def intersects(self, traj, count_singularities=False):
r"""
See documentation of :meth:`~.straight_line_trajectory.AbstractStraightLineTrajectory.intersects`
"""
return self.trajectory().intersects(
traj, count_singularities=count_singularities
)
def __eq__(self, other):
r"""
Return whether this saddle connection is indistinguishable from
``other``.
EXAMPLES::
sage: from flatsurf import translation_surfaces
sage: S = translation_surfaces.square_torus()
sage: connections = S.saddle_connections(13)
sage: connections[0] == connections[0]
True
sage: connections[0] == connections[1]
False
TESTS:
Verify that saddle connections can be compared to arbitrary objects (so
they can be put into dicts with other objects)::
sage: connections[0] == 42
False
::
sage: len(connections)
32
sage: len(set(connections))
32
"""
if self is other:
return True
if not isinstance(other, SaddleConnection):
return False
if not self._surface == other._surface:
return False
if not self._direction == other._direction:
return False
if not self._surfacetart_data == other._surfacetart_data:
return False
# Initial data should determine the saddle connection:
return True
def __ne__(self, other):
return not self == other
def __hash__(self):
return 41 * hash(self._direction) - 97 * hash(self._surfacetart_data)
def _test_geometry(self, **options):
# Test that this saddle connection actually exists on the surface.
SaddleConnection(
self._surface,
self._surfacetart_data,
self._direction,
self._end_data,
self._end_direction,
self._holonomy,
self._end_holonomy,
check=True,
)
def __repr__(self):
return "Saddle connection in direction {} with start data {} and end data {}".format(
self._direction, self._surfacetart_data, self._end_data
)
def _test_inverse(self, **options):
# Test that inverting works properly.
SaddleConnection(
self._surface,
self._end_data,
self._end_direction,
self._surfacetart_data,
self._direction,
self._end_holonomy,
self._holonomy,
check=True,
)
[docs]
class Cylinder(SageObject):
r"""
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)
"""
def __init__(self, s, label0, edges):
r"""
Construct a cylinder on the surface `s` from an initial label and a
sequence of edges crossed.
Parameters
----------
s: A SimilaritySurface
the surface containing the cylinder
label0: An initial label
representing a polygon the cylinder passes through.
edges: a list
giving the sequence of edges the cylinder crosses until it closes.
"""
self._surface = s
self._label0 = label0
self._edges = tuple(edges)
ss = s.minimal_cover(cover_type="planar")
SG = SimilarityGroup(s.base_ring())
labels = [(label0, SG.one())] # labels of polygons on the cover ss.
for e in edges:
labels.append(ss.opposite_edge(labels[-1], e)[0])
if labels[0][0] != labels[-1][0]:
raise ValueError("Combinatorial path does not close.")
trans = labels[-1][1]
if not trans.is_translation():
raise NotImplementedError(
"Only cylinders with translational monodromy are currently supported"
)
m = trans.matrix()
v = vector(s.base_ring(), (m[0][2], m[1][2])) # translation vector
from flatsurf.geometry.euclidean import ccw
p = ss.polygon(labels[0])
e = edges[0]
min_y = ccw(v, p.vertex(e))
max_y = ccw(v, p.vertex((e + 1) % len(p.vertices())))
if min_y >= max_y:
raise ValueError("Combinatorial data does not represent a cylinder")
# Stores the vertices where saddle connections starts:
min_list = [0]
max_list = [0]
for i in range(1, len(edges)):
e = edges[i]
p = ss.polygon(labels[i])
y = ccw(v, p.vertex(e))
if y == min_y:
min_list.append(i)
elif y > min_y:
min_list = [i]
min_y = y
if min_y >= max_y:
raise ValueError("Combinatorial data does not represent a cylinder")
y = ccw(v, p.vertex((e + 1) % len(p.vertices())))
if y == max_y:
max_list.append(i)
elif y < max_y:
max_list = [i]
max_y = y
if min_y >= max_y:
raise ValueError("Combinatorial data does not represent a cylinder")
# Extract the saddle connections on the right side:
from flatsurf.geometry.surface_objects import SaddleConnection
sc_set_right = set()
vertices = []
for i in min_list:
label = labels[i]
p = ss.polygon(label)
vertices.append((i, p.vertex(edges[i])))
i, vert_i = vertices[-1]
vert_i = vert_i - v
j, vert_j = vertices[0]
if vert_i != vert_j:
li = labels[i]
li = (li[0], SG(-v) * li[1])
lio = ss.opposite_edge(li, edges[i])
lj = labels[j]
sc = SaddleConnection(
s,
(lio[0][0], (lio[1] + 1) % len(ss.polygon(lio[0]).vertices())),
(~lio[0][1])(vert_j) - (~lio[0][1])(vert_i),
)
sc_set_right.add(sc)
i = j
vert_i = vert_j
for j, vert_j in vertices[1:]:
if vert_i != vert_j:
li = labels[i]
li = (li[0], SG(-v) * li[1])
lio = ss.opposite_edge(li, edges[i])
lj = labels[j]
sc = SaddleConnection(
s,
(lio[0][0], (lio[1] + 1) % len(ss.polygon(lio[0]).vertices())),
(~lio[0][1])(vert_j) - (~lio[0][1])(vert_i),
limit=j - i,
)
sc_set_right.add(sc)
i = j
vert_i = vert_j
# Extract the saddle connections on the left side:
sc_set_left = set()
vertices = []
for i in max_list:
label = labels[i]
p = ss.polygon(label)
vertices.append((i, p.vertex((edges[i] + 1) % len(p.vertices()))))
i, vert_i = vertices[-1]
vert_i = vert_i - v
j, vert_j = vertices[0]
if vert_i != vert_j:
li = labels[i]
li = (li[0], SG(-v) * li[1])
lio = ss.opposite_edge(li, edges[i])
lj = labels[j]
sc = SaddleConnection(
s,
(lj[0], (edges[j] + 1) % len(ss.polygon(lj).vertices())),
(~lj[1])(vert_i) - (~lj[1])(vert_j),
)
sc_set_left.add(sc)
i = j
vert_i = vert_j
for j, vert_j in vertices[1:]:
if vert_i != vert_j:
li = labels[i]
lio = ss.opposite_edge(li, edges[i])
lj = labels[j]
sc = SaddleConnection(
s,
(lj[0], (edges[j] + 1) % len(ss.polygon(lj).vertices())),
(~lj[1])(vert_i) - (~lj[1])(vert_j),
)
sc_set_left.add(sc)
i = j
vert_i = vert_j
self._boundary1 = frozenset(sc_set_right)
self._boundary2 = frozenset(sc_set_left)
self._boundary = frozenset(self._boundary1.union(self._boundary2))
edge_intersections = []
i = min_list[0]
label = labels[i]
p = ss.polygon(label)
right_point = p.vertex(edges[i]) # point on the right boundary
i = max_list[0]
label = labels[i]
p = ss.polygon(label)
left_point = p.vertex((edges[i] + 1) % len(p.vertices()))
from flatsurf.geometry.euclidean import solve
for i in range(len(edges)):
label = labels[i]
p = ss.polygon(label)
e = edges[i]
v1 = p.vertex(e)
v2 = p.vertex((e + 1) % len(p.vertices()))
a, b = solve(left_point, v, v1, v2 - v1)
w1 = (~(label[1]))(v1 + b * (v2 - v1))
a, b = solve(right_point, v, v1, v2 - v1)
w2 = (~(label[1]))(v1 + b * (v2 - v1))
edge_intersections.append((w1, w2))
polygons = []
pair1 = edge_intersections[-1]
l1 = labels[-2][0]
e1 = edges[-1]
for i in range(len(edges)):
l2 = labels[i][0]
pair2 = edge_intersections[i]
e2 = edges[i]
trans = s.edge_transformation(l1, e1)
pair1p = (trans(pair1[0]), trans(pair1[1]))
polygon_verts = [pair1p[0], pair1p[1]]
if pair2[1] != pair1p[1]:
polygon_verts.append(pair2[1])
if pair2[0] != pair1p[0]:
polygon_verts.append(pair2[0])
from flatsurf import Polygon
polygons.append(
(l2, Polygon(vertices=polygon_verts, base_ring=s.base_ring()))
)
l1 = l2
pair1 = pair2
e1 = e2
self._polygons = tuple(polygons)
[docs]
def surface(self):
return self._surface
[docs]
def initial_label(self):
r"""
Return one label on the surface that the cylinder passes through.
"""
return self._label0
[docs]
def edges(self):
r"""
Return a tuple of edge numbers representing the edges crossed
when the cylinder leaves the polygon with `initial_label` until
it returns by closing.
"""
return self._edges
[docs]
def boundary(self):
r"""
Return the set of saddle connections in the boundary, oriented so that
the surface is on the left.
"""
return self._boundary
[docs]
def polygons(self):
r"""
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.
"""
return self._polygons
[docs]
@cached_method
def area(self):
r"""
Return the area of this cylinder if it is contained in a ConeSurface.
"""
from flatsurf.geometry.categories import ConeSurfaces
if self._surface not in ConeSurfaces():
raise NotImplementedError("area only makes sense for cone surfaces")
area = 0
for label, p in self.polygons():
area += p.area()
return area
[docs]
def plot(self, **options):
r"""
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_surface : a GraphicalSurface
If not provided or `None`, the plot method uses the default graphical
surface for the surface.
"""
if "graphical_surface" in options and options["graphical_surface"] is not None:
gs = options["graphical_surface"]
if gs.get_surface() != self._surface:
raise ValueError("graphical surface for the wrong surface")
del options["graphical_surface"]
else:
gs = self._surface.graphical_surface()
plt = Graphics()
for label, p in self.polygons():
if gs.is_visible(label):
gp = gs.graphical_polygon(label)
t = gp.transformation()
pp = t(p)
poly = polygon2d(pp.vertices(), **options)
plt += poly.plot()
return plt
[docs]
@cached_method
def labels(self):
r"""
Return the set of labels that this cylinder passes through.
"""
polygons = self.polygons()
return frozenset([label for label, p in polygons])
[docs]
def boundary_components(self):
r"""
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.
"""
return frozenset([self._boundary1, self._boundary2])
[docs]
def next(self, sc):
r"""
Return the next saddle connection as you move around the cylinder boundary
moving from sc in the direction of its orientation.
"""
if sc not in self._boundary:
raise ValueError
v = sc.end_tangent_vector()
v = v.clockwise_to(-v.vector())
from flatsurf.geometry.euclidean import is_parallel
for sc2 in self._boundary:
if sc2.start_data() == (
v.polygon_label(),
v.vertex(),
) and is_parallel(sc2.direction(), v.vector()):
return sc2
raise ValueError("Failed to find next saddle connection in boundary set.")
[docs]
def previous(self, sc):
r"""
Return the previous saddle connection as you move around the cylinder boundary
moving from sc in the direction opposite its orientation.
"""
if sc not in self._boundary:
raise ValueError
v = sc.start_tangent_vector()
v = v.counterclockwise_to(-v.vector())
from flatsurf.geometry.euclidean import is_parallel
for sc2 in self._boundary:
if sc2.end_data() == (v.polygon_label(), v.vertex()) and is_parallel(
sc2.end_direction(), v.vector()
):
return sc2
raise ValueError("Failed to find previous saddle connection in boundary set.")
[docs]
@cached_method
def holonomy(self):
r"""
In a translation surface, return one of the two holonomy vectors of the cylinder,
which differ by a sign.
"""
from flatsurf.geometry.categories import TranslationSurfaces
if self._surface not in TranslationSurfaces():
raise NotImplementedError(
"holonomy currently only computable for translation surfaces"
)
V = self._surface.base_ring() ** 2
total = V.zero()
for sc in self._boundary1:
total += sc.holonomy()
# Debugging:
total2 = V.zero()
for sc in self._boundary2:
total2 += sc.holonomy()
assert (
total + total2 == V.zero()
), "Holonomy of the two boundary components should sum to zero."
return total
[docs]
@cached_method
def circumference(self):
r"""
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.
"""
from flatsurf.geometry.categories import ConeSurfaces
if self._surface not in ConeSurfaces():
raise NotImplementedError(
"circumference only makes sense for cone surfaces"
)
total = 0
for sc in self._boundary1:
total += sc.length()
return total