Add methods related to cylinder decompositions

[saraedum]

We want to add the following methods to TranslationSurface.

def cylinder_decomposition(self, direction, transversals=None):
    r"""
    Return a :class:`Deformation` which maps this surface to a representation of this
    surface as a decomposition into cylinders in ``direction``.

    The codomain of the deformation is built from parallelograms (with added points
    along the sides in ``direction`` to establish the gluing of the cylinders.) The transversal
    edge of these parallelograms are taken from ``transversals`` if specified.
    """
    # Except for the transversals part, this is implemented in libflatsurf.
    # We need to wrap libflatsurf's Deformation to some extend to make this work.

def flow_decomposition(self, direction, transversals=None):
    # Essentially the same but we allow minimal components.

def cylinders(self, direction, check=True):
    r"""
    Return the cylinders of this surface in ``direction``.

    The surface must already be decomposed into cylinders, e.g., the codomain
    of :meth:`cylinder_decomposition`.

    The cylinders are returned as their perimeters, i.e., a :class:`Path` composed of a
    ``bottom``, ``right``, ``top``, and ``left`` part.
    """
    # This is implemented in libflatsurf already but we probably just want to implement this from scratch.
    # We might want to wrap libflatsurf's Perimeter and Path for this to work.

To make the transversals parameter of cylinder_decomposition easy to use, we should implement something like this on the level of polygons that are parallelograms with added points.

def transversal(top=None, bottom=None, direction=None, twists=0):
    r"""
    Return the transversal (w.r.t. ``direction``) of minimal positive slope that
    connects the vertex ``top`` to ``bottom``.

    Additional full ``twists`` can be added to that transversal counted in the
    ``direction`` (to obtain a negative or non-minimal slope.)
    """

Once cylinders are citizens of sage-flatsurf, we should also add things such as writing the perimeter of a cylinder in terms of homology.

---

These ideas came up while discussing #162.

---

Dependencies

• [ ] #126

[videlec]

The allow_minimal_components argument inside cylinder_decomposition sounds a bit weird. To my mind we should either call the method flow_decomposition (and allow minimal/unknown components) or don't have the argument. We could even have both : cylinder_decomposition would call flow_decomposition and checks that it is indeed a completely periodic direction.

[videlec]

Should we solve #126 before?

[saraedum]

Yes, sounds good. I updated the description.