Add MutableOrientedHyperbolicSurface

[saraedum]

Checklist

• Added an entry in doc/news/.
• Added a test for this change.
• Added new .py files to the documentation in doc/geometry or doc/graphical.

TODO

• Printing of segments as "geodesic ∩ half-plane ∩ half-plane" is very noisy. It's usually easier to parse "point → point".
• edges() of polygons with marked vertices should return the individual segments surrounding a marked vertex Fix edges() of hyperbolic convex polygons with marked vertices #244
• Check that the assumption that a polygon with n edges must have n vertices is not used anymore (in areas that could affect hyperbolic surfaces.)
• Add polygons mod n formed by inserting orbifold points in a followup PR.

Demo

sage: from flatsurf import HyperbolicPlane
sage: H = HyperbolicPlane(QQ)
sage: from flatsurf import MutableOrientedHyperbolicSurface
sage: S = MutableOrientedHyperbolicSurface(H)
sage: S.add_polygon(H.polygon([
....:     H.vertical(3).left_half_space(),
....:     H.vertical(1).right_half_space(),
....:     H.half_circle(2, 4).left_half_space(),
....:     H.half_circle(2, 16).right_half_space(),
....: ]))
0
sage: S.add_polygon(H.polygon([
....:     H.vertical(3).left_half_space(),
....:     H.vertical(1).right_half_space(),
....:     H.half_circle(2, 4).left_half_space(),
....:     H.half_circle(2, 16).right_half_space(),
....: ]))
1
sage: S.polygon(0).edges()
{(2/5, 3/5) → (6/13, 11/13), (6/13, 11/13) → (6/25, 23/25), (6/25, 23/25) → (2/17, 15/17), (2/17, 15/17) → (2/5, 3/5)}
sage: S.glue((0, 0), (1, 0))
sage: S.glue((0, 1), (1, 3))
sage: S.glue((0, 2), (1, 2))
sage: S.glue((0, 3), (1, 1))
sage: S.set_immutable()
sage: S
Hyperbolic Surface with 2 orbifold points built from 2 quadrilaterals
sage: S.vertices()
{Vertex 0 of polygon 0,
 Vertex 0 of polygon 1,
 Vertex 2 of polygon 0,
 Vertex 2 of polygon 1}
sage: S.orbifold_points()
{Vertex 0 of polygon 0, Vertex 0 of polygon 1}
sage: [v.angle(numerical=True) for v in S.vertices()]
[0.419569376744834, 0.333333333333334, 0.333333333333334, 0.419569376744834]
sage: S.plot()

[github-actions]

Documentation preview for this PR is ready! 🎉
Built with commit: a907243

[saraedum]

Can we call _layout_one_trajectory several times (ie layout several trajectories)?

You can actually call gs.layout(algorithm="trajectory", trajectory=L) several times with different trajectories I think.

[videlec]

A useful method at the level of surfaces glued from polygon is is_orbifold() (ie whether all angles are of the form $2\pi/n$ with $n \in {1,2,\ldots}$ (one can allow $+\infty$ as well in the hyperbolic settings to mean cusp). If the surface is an orbifold, then it is a global quotient $\Gamma \backslash \mathbb{H}^2$ (hyperbolic setting) or $\Gamma \backslash \mathbb{R}^2$ (flat setting).