`homology`#

Absolute and relative (simplicial) homology of surfaces.

EXAMPLES:

The absolute homology of the regular octagon:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: S = translation_surfaces.regular_octagon()
sage: H = SimplicialHomology(S)

A basis of homology, with generators written as (sums of) oriented edges:

sage: H.gens()
(B[(0, 1)], B[(0, 2)], B[(0, 3)], B[(0, 0)])

The absolute homology of the unfolding of the (3, 4, 13) triangle:

sage: from flatsurf import Polygon, similarity_surfaces
sage: P = Polygon(angles=[3, 4, 13])
sage: S = similarity_surfaces.billiard(P).minimal_cover(cover_type="translation")
sage: S.genus()
8
sage: H = SimplicialHomology(S)
sage: len(H.gens())
16

Relative homology, relative to the singularities of the surface:

sage: S = S.erase_marked_points()  # optional: pyflatsurf  # random output due to deprecation warnings
sage: H1 = SimplicialHomology(S, relative=S.vertices())  # optional: pyflatsurf
sage: len(H1.gens())  # optional: pyflatsurf
17

We can also form relative \(H_0\) and \(H_2\), though they are not overly interesting of course:

sage: H0 = SimplicialHomology(S, relative=S.vertices(), k=0)
sage: len(H0.gens())
0

sage: H2 = SimplicialHomology(S, relative=S.vertices(), k=2)
sage: len(H2.gens())
1

We create the homology class corresponding to the core curve of a cylinder (the interface here is terrible at the moment, see https://github.com/flatsurf/sage-flatsurf/issues/166):

sage: from flatsurf import Polygon, similarity_surfaces, SimplicialHomology, GL2ROrbitClosure

sage: P = Polygon(angles=[3, 4, 13])
sage: S = similarity_surfaces.billiard(P).minimal_cover(cover_type="translation").triangulate()

sage: from flatsurf.geometry.pyflatsurf_conversion import FlatTriangulationConversion  # optional: pyflatsurf
sage: conversion = FlatTriangulationConversion.to_pyflatsurf(S)  # optional: pyflatsurf
sage: T = conversion.codomain()  # optional: pyflatsurf
sage: O = GL2ROrbitClosure(T)  # optional: pyflatsurf

sage: D = O.decomposition((13, 37))  # optional: pyflatsurf
sage: cylinder = D.cylinders()[0]  # optional: pyflatsurf

sage: H = SimplicialHomology(S)
sage: core = sum(int(str(chain[edge])) * H(conversion.section(edge.positive())) for segment in cylinder.right() for chain in [segment.saddleConnection().chain()] for edge in T.edges())  # optional: pyflatsurf
sage: core  # optional: pyflatsurf
972725347814111665129717*B[((0, -1/2*c0, -1/2*c0^2 + 3/2), 2)] + 587352809047576581321682*B[((0, -1/2*c0^2 + 1, -1/2*c0^3 + 3/2*c0), 2)] + 60771110563809382932401*B[((0, -1/2*c0^2 + 1, 1/2*c0^3 - 3/2*c0), 2)] ...

flatsurf.geometry.homology.SimplicialHomology(surface, k=1, coefficients=None, relative=None, implementation='generic', category=None)[source]#

Return the k-th simplicial homology group of surface.

INPUT:

surface – a surface
k – an integer (default: 1)
coefficients – a ring (default: the integer ring); consider the homology with coefficients in this ring
relative – a set (default: the empty set); if non-empty, then relative homology with respect to this set is constructed.
implementation – a string (default: "generic"); the algorithm used to compute the homology groups. Currently only "generic" is supported, i.e., the groups are computed with the generic homology machinery from SageMath.
category – a category; if not specified, a category for the homology group is chosen automatically depending on coefficients.

class flatsurf.geometry.homology.SimplicialHomologyClass(parent, chain)[source]#

An element of a homology group.

INPUT:

parent – a SimplicialHomology
chain – an element of the SimplicialHomologyGroup.chain_module().

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: S = translation_surfaces.regular_octagon()
sage: H0 = SimplicialHomology(S, k=0)
sage: g0 = H0.gens()[0]
sage: g0
B[Vertex 0 of polygon 0]

sage: H1 = SimplicialHomology(S, k=1)
sage: g1 = H1.gens()[0]
sage: g1
B[(0, 1)]

sage: H2 = SimplicialHomology(S, k=2)
sage: g2 = H2.gens()[0]
sage: g2
B[0]

algebraic_intersection(other)[source]#

Return the algebraic intersection of this class of a closed curve with other.

INPUT:

other - a SimplicialHomologyClass in the same homology

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: S = translation_surfaces.regular_octagon()
sage: H = SimplicialHomology(S)

sage: H((0, 0)).algebraic_intersection(H((0, 1)))
1

sage: a = H((0, 1))
sage: b = 3 * H((0, 0)) + 5 * H((0, 2)) - 2 * H((0, 4))
sage: a.algebraic_intersection(b)
0

sage: a = 2 * H((0, 0)) + H((0, 1)) + 3 * H((0, 2)) + H((0, 3)) + H((0, 4)) + H((0, 5)) + H((0, 7))
sage: b = H((0, 0)) + 2 * H((0, 1)) + H((0, 2)) + H((0, 3)) + 2 * H((0, 4)) + 3 * H((0, 5)) + 4 * H((0, 6)) + 3 * H((0, 7))
sage: a.algebraic_intersection(b)
-6

sage: S = translation_surfaces.cathedral(1, 4)
sage: H = SimplicialHomology(S)
sage: a = H((0, 3))
sage: b = H((2, 1))
sage: a.algebraic_intersection(b)
0

sage: a = H((0, 3))
sage: b = H((3, 4)) + 3 * H((0, 3)) + 2 * H((0, 0)) - H((1, 7)) + 7 * H((2, 1)) - 2 * H((2, 2))
sage: a.algebraic_intersection(b)
2

coefficient(gen)[source]#

Return the multiplicity of this class at a generator of homology.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: a,b = H.gens()
sage: a.coefficient(a)
1
sage: a.coefficient(b)
0

coefficients()[source]#

Return the coefficients of this element in terms of the generators of homology.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.gens()[0].coefficients()
(1, 0)
sage: H.gens()[1].coefficients()
(0, 1)

surface()[source]#

Return the surface on which this homology class in defined.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: h = H.gens()[0]
sage: h.surface()
Translation Surface in H_1(0) built from a square

class flatsurf.geometry.homology.SimplicialHomologyGroup(surface, k, coefficients, relative, implementation, category)[source]#

The k-th simplicial homology group of the surface with coefficients.

INPUT:

surface – a finite type surface without boundary
k – an integer
coefficients – a ring
relative – a subset of points of the surface
implementation – a string; the algorithm used to compute the homology, only "generic" is supported at the moment which uses the generic homology machinery of SageMath.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology, MutableOrientedSimilaritySurface
sage: T = translation_surfaces.square_torus()

Surfaces must be immutable to compute their homology:

sage: T = MutableOrientedSimilaritySurface.from_surface(T)
sage: SimplicialHomology(T)
Traceback (most recent call last):
...
ValueError: surface must be immutable to compute homology

sage: T.set_immutable()
sage: SimplicialHomology(T)
H₁(Translation Surface in H_1(0) built from a square)

Element#: alias of SimplicialHomologyClass

boundary(chain)[source]#

Return the boundary of chain as an element of the chain_module() in lower dimension.

INPUT:

chain – an element of chain_module()

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()

sage: H = SimplicialHomology(T, k=0)
sage: c = H.chain_module().an_element(); c
2*B[Vertex 0 of polygon 0]
sage: H.boundary(c)
0

sage: H = SimplicialHomology(T, k=1)
sage: c = H.chain_module().an_element(); c
2*B[(0, 0)] + 2*B[(0, 1)]
sage: H.boundary(c)
0

sage: H = SimplicialHomology(T, k=2)
sage: c = H.chain_module().an_element(); c
2*B[0]
sage: H.boundary(c)
0

chain_module()[source]#

Return the free module of simplicial chains of the surface i.e., formal sums of simplicies, e.g., formal sums of edges of the surface.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.chain_module()
Free module generated by {(0, 1), (0, 0)} over Integer Ring

change(k=None)[source]#

Return this homology but in dimension k.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H
H₁(Translation Surface in H_1(0) built from a square)

sage: H.change(k=0)
H₀(Translation Surface in H_1(0) built from a square)

degree()[source]#

Return the degree \(k\) for this homology \(H_k\).

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()

sage: H = SimplicialHomology(T)
sage: H.degree()
1

gens()[source]#

Return generators of homology.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()

sage: H = SimplicialHomology(T)
sage: H.gens()
(B[(0, 1)], B[(0, 0)])

sage: H = SimplicialHomology(T, 0)
sage: H.gens()
(B[Vertex 0 of polygon 0],)

sage: H = SimplicialHomology(T, 2)
sage: H.gens()
(B[0],)

is_absolute()[source]#

Return whether this is absolute homology (and not relative to some set of points.)

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.is_absolute()
True

simplices()[source]#

Return the simplices that form the generators of chain_module().

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()

In dimension 1, this is the set of edges:

sage: H = SimplicialHomology(T)
sage: H.simplices()
((0, 1), (0, 0))

In dimension 0, this is the set of vertices:

sage: H = SimplicialHomology(T, k=0)
sage: H.simplices()
(Vertex 0 of polygon 0,)

In dimension 2, this is the set of polygons:

sage: H = SimplicialHomology(T, k=2)
sage: H.simplices()
(0,)

In all other dimensions, there are no simplices:

sage: H = SimplicialHomology(T, k=12)
sage: H.simplices()
()

some_elements()[source]#

Return some typical homology classes (for testing.)

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.some_elements()
[0, B[(0, 1)], B[(0, 0)]]

surface()[source]#

Return the surface of which this is the homology.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.surface() == T
True

symplectic_basis()[source]#

Return a symplectic basis of generators of this homology group.

TODO: Add a reference and a definition.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()

sage: H = SimplicialHomology(T)
sage: H.symplectic_basis()
[B[(0, 0)], B[(0, 1)]]

zero()[source]#

Return the zero homology class.

EXAMPLES:

sage: from flatsurf import translation_surfaces, SimplicialHomology
sage: T = translation_surfaces.square_torus()
sage: T.set_immutable()
sage: H = SimplicialHomology(T)
sage: H.zero()
0

homology#

`homology`#