Merge pull request #313 from saraedum/homology-coeffs

Improve interface of homology classes

doc/examples/boshernitzan_conjecture.md

@@ -1,5 +1,6 @@
 ---
 jupytext:
+  encoding: '# -*- coding: utf-8 -*-'
   formats: ipynb,md:myst,sage:light
   text_representation:
     extension: .md

doc/examples/siegel_veech.md

@@ -1,5 +1,6 @@
 ---
 jupytext:
+  encoding: '# -*- coding: utf-8 -*-'
   formats: ipynb,md:myst,sage:light
   text_representation:
     extension: .md

doc/news/homology-coeffs.rst

@@ -0,0 +1,3 @@
+**Added:**
+
+* Added method ``SimplicialHomologyClass.chain()`` and examples that show how to rewrite a homology class into edges with multiplicities or into a holonomy vector.

flatsurf/geometry/homology.py

@@ -328,6 +328,36 @@ def _repr_(self):
         """
         return repr(self._chain)
 
+    def chain(self):
+        r"""
+        Return a lift of this element to the
+        :meth:`SimplicialHomologyGroup.chain_module`.
+
+        EXAMPLES::
+
+            sage: from flatsurf import translation_surfaces, SimplicialHomology
+            sage: T = translation_surfaces.square_torus()
+            sage: H = SimplicialHomology(T)
+            sage: a, b = H.gens()
+            sage: a.chain()
+            B[(0, 1)]
+
+        We can use the chain representation to write a homology class as
+        simplices, i.e., edges, with multiplicities::
+
+            sage: coeffs = (a - b).chain().monomial_coefficients()
+            sage: coeffs  # random output due to random ordering of edges
+            {(0, 1): 1, (0, 0): -1}
+
+        From this representation, we determine the holonomy vector that a chain
+        encodes on a translation surface::
+
+            sage: sum(c * T.polygon(label).edge(edge) for ((label, edge), c) in coeffs.items())
+            (-1, 1)
+
+        """
+        return self._chain
+
     def coefficient(self, gen):
         r"""
         Return the multiplicity of this class at a generator of homology.
@@ -337,7 +367,7 @@ def coefficient(self, gen):
             sage: from flatsurf import translation_surfaces, SimplicialHomology
             sage: T = translation_surfaces.square_torus()
             sage: H = SimplicialHomology(T)
-            sage: a,b = H.gens()
+            sage: a, b = H.gens()
             sage: a.coefficient(a)
             1
             sage: a.coefficient(b)