topological_surfaces

The category of topological surfaces.

This module provides a base category for all surfaces in sage-flatsurf.

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 MutableOrientedSimilaritySurface
sage: S = MutableOrientedSimilaritySurface(QQ)

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: S in TopologicalSurfaces()
True

class flatsurf.geometry.categories.topological_surfaces.TopologicalSurfaces

The category of topological surfaces, i.e., surfaces that are locally homeomorphic to the real plane or the closed upper half plane.

This category does not provide much functionality but just a common base for all the other categories defined in sage-flatsurf.

In particular, this does not require a topology since there is no general concept of open subsets of a surface in sage-flatsurf.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: TopologicalSurfaces()
Category of topological surfaces

class Compact(base_category)

The axiom satisfied by surfaces that are compact as topological spaces.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: 'Compact' in S.category().axioms()
True

class ParentMethods

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

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

is_compact()

Return whether this surface is compact, i.e., return True.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_compact()
True

class Connected(base_category)

The axiom satisfied by surfaces that are topologically connected.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: 'Connected' in S.category().axioms()
True

class ParentMethods

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

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

is_connected()

Return whether this surface is connected, i.e., return True.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_connected()
True

class Orientable(base_category)

The axiom satisfied by surfaces that can be oriented.

As of 2023, all surfaces in sage-flatsurf satisfy this axiom.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: 'Orientable' in S.category().axioms()
True

class ParentMethods

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

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

is_orientable()

Return whether this surface is orientable, i.e., return True.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_orientable()
True

class ParentMethods

Provides methods available to all surfaces in sage-flatsurf.

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

genus()

Return the genus of this surface.

EXAMPLES:

sage: from flatsurf import translation_surfaces
sage: translation_surfaces.octagon_and_squares().genus()
3

is_compact()

Return whether this surface is compact.

All surfaces in sage-flatsurf must implement this method.

Note

This method is used by refined_category() to determine whether this surface satisfies the axiom of compactness. Surfaces can override this method to perform specialized logic, see the note in flatsurf.geometry.categories for performance considerations.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_compact()
True

is_connected()

Return whether this surface is connected.

All surfaces in sage-flatsurf must implement this method.

Note

This method is used by refined_category() to determine whether this surface satisfies the axiom of connectedness. Surfaces can override this method to perform specialized logic, see the note in flatsurf.geometry.categories for performance considerations.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_connected()
True

is_mutable()

Return whether this surface allows modifications.

All surfaces in sage-flatsurf must implement this method.

Note

We do not specify the interface of such mutations. Any mutable surface should come up with a good interface for its use case. The point of this method is to signal that is likely unsafe to use this surface in caches (since it might change later) and that the category of the surface might still change.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S._test_refined_category()

is_orientable()

Return whether this surface is orientable.

All surfaces in sage-flatsurf must implement this method.

Note

This method is used by refined_category() to determine whether this surface satisfies the axiom TopologicalSurfaces.Orientable. Surfaces must override this method to perform specialized logic, see the note in flatsurf.geometry.categories for performance considerations.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_orientable()
True

is_with_boundary()

Return whether this a topological surface with boundary.

All surfaces in sage-flatsurf must implement this method.

Note

This method is used by refined_category() to determine whether this surface satisfies the axiom WithBoundary or TopologicalSurfaces.WithoutBoundary. Surfaces must override this method to perform specialized logic, see the note in flatsurf.geometry.categories for performance considerations.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_with_boundary()
False

refined_category()

Return the smallest subcategory that this surface is in.

The result of this method can be fed to _refine_category_ to change the category of the surface (and enable functionality specific to the smaller classes of surfaces).

Note that this method does have much effect for a general topological surface. Subcategories and implementations of surfaces should override this method to derive more features.

EXAMPLES:

sage: from flatsurf import MutableOrientedSimilaritySurface
sage: S = MutableOrientedSimilaritySurface(QQ)

sage: from flatsurf import polygons
sage: S.add_polygon(polygons.square(), label=0)
0
sage: S.refined_category()
Category of connected with boundary finite type translation surfaces

sage: S.glue((0, 0), (0, 2))
sage: S.glue((0, 1), (0, 3))
sage: S.refined_category()
Category of connected without boundary finite type translation surfaces

class SubcategoryMethods

Orientable()

Return the subcategory of surfaces that can be oriented.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: TopologicalSurfaces().Orientable()
Category of orientable topological surfaces

WithBoundary()

Return the subcategory of surfaces that have a boundary, i.e., points at which they are homeomorphic to the closed upper half plane.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: TopologicalSurfaces().WithBoundary()
Category of with boundary topological surfaces

WithoutBoundary()

Return the subcategory of surfaces that have no boundary, i.e., they are everywhere isomorphic to the real plane.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: TopologicalSurfaces().WithoutBoundary()
Category of without boundary topological surfaces

class WithBoundary(base_category)

The axiom satisfied by surfaces that have a boundary, i.e., at some points this surface is homeomorphic to the closed upper half plane.

EXAMPLES:

sage: from flatsurf import MutableOrientedSimilaritySurface
sage: S = MutableOrientedSimilaritySurface(QQ)

sage: from flatsurf import polygons
sage: S.add_polygon(polygons.square(), label=0)
0
sage: S.set_immutable()
sage: 'WithBoundary' in S.category().axioms()
True

class ParentMethods

Provides methods available to all surfaces with boundary in sage-flatsurf.

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

is_with_boundary()

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

EXAMPLES:

sage: from flatsurf import MutableOrientedSimilaritySurface
sage: S = MutableOrientedSimilaritySurface(QQ)

sage: from flatsurf import polygons
sage: S.add_polygon(polygons.square(), label=0)
0
sage: S.set_immutable()
sage: S.is_with_boundary()
True

class WithoutBoundary(*args, **kwargs)

An impossible category, the surfaces with and without boundary.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: C = TopologicalSurfaces()
sage: C.WithBoundary().WithoutBoundary()
Traceback (most recent call last):
...
TypeError: a surface cannot be both with and without boundary
sage: C.WithoutBoundary().WithBoundary()
Traceback (most recent call last):
...
TypeError: a surface cannot be both with and without boundary

class WithoutBoundary(base_category)

The axiom satisfied by surfaces that have no boundary, i.e., the surface is everywhere homeomorphic to the real plane.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: 'WithoutBoundary' in S.category().axioms()
True

class ParentMethods

Provides methods available to all surfaces without boundary in sage-flatsurf.

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

is_with_boundary()

Return whether this is a surface with boundary, i.e., return False.

EXAMPLES:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(vertices=[(0,0), (2,0), (1,4), (0,5)])
sage: S = similarity_surfaces.self_glued_polygon(P)
sage: S.is_with_boundary()
False

super_categories()

Return the categories a topological surface is also a member of.

EXAMPLES:

sage: from flatsurf.geometry.categories import TopologicalSurfaces
sage: TopologicalSurfaces().super_categories()
[Category of topological spaces]