Replace the SimilaritySurface hierarchy with categories

.github/workflows/lint.yml

@@ -68,10 +68,15 @@ jobs:
       - name: Install dependencies
         shell: bash -l {0}
         run: |
+          mamba env update -n test --quiet -f environment.yml
           mamba install black=22.12
       - name: Run black
         shell: bash -l {0}
-        run: black `find -name '*.py'`
+        run: |
+          black `find -name '*.py'`
+          # We run our notebooks through black to make sure everything is nicely formatted in our examples.
+          # Consequently, we cannot use SageMath syntax in the notebooks. (But presently we do not need it anyway.)
+          jupytext --sync --pipe black doc/examples/*.md
       - name: Detect changes
         shell: bash -l {0}
         run: git diff --exit-code

.github/workflows/test.yml

@@ -13,31 +13,19 @@ jobs:
     strategy:
       matrix:
         include:
-          - optionals: "sage,flipper"
-            sagelib: "8.8"
-            environment: "environment.yml"
-            python: "3.7.12"
-          - optionals: "sage,flipper"
-            sagelib: "8.9"
-            environment: "environment.yml"
-            python: "3.7.12"
-          - optionals: "sage,flipper"
-            sagelib: "9.1"
-            environment: "environment.yml"
-            python: "3.7.12"
           - optionals: "sage,flipper"
             sagelib: "9.2"
             environment: "environment.yml"
             python: "3.9.15"
-          - optionals: "sage,flipper,eantic,exactreal"
+          - optionals: "sage,flipper,eantic"
             sagelib: "9.3"
             environment: "environment.yml"
             python: "3.9.15"
-          - optionals: "sage,flipper,eantic,exactreal,pyflatsurf"
+          - optionals: "sage,flipper,eantic,pyflatsurf"
             sagelib: "9.4"
             environment: "environment.yml"
             python: "3.9.15"
-          - optionals: "sage,flipper,eantic,exactreal,pyflatsurf"
+          - optionals: "sage,flipper,eantic,pyflatsurf"
             sagelib: "9.5"
             environment: "environment.yml"
             python: "3.9.15"
@@ -49,6 +37,11 @@ jobs:
             sagelib: "9.7"
             environment: "environment.yml"
             python: "3.10.8"
+          # surface-dynamics is not available for SageMath 9.8 on conda-forge, see https://github.com/conda-forge/surface-dynamics-feedstock/pull/17
+          # - optionals: "sage,flipper,eantic,exactreal,pyflatsurf"
+          #   sagelib: "9.8"
+          #   environment: "environment.yml"
+          #   python: "3.10.8"
           - optionals: "sage,flipper,eantic,exactreal,pyflatsurf"
             environment: "flatsurf.yml"
             python: "3.10.8"
@@ -60,6 +53,7 @@ jobs:
       - name: Install dependencies
         shell: bash -l {0}
         run: |
+          mamba upgrade -n base --all --yes  # mamba 1.4.1 segfaults sometimes, make sure we use a later version
           mamba install -n test sagelib=${{ matrix.sagelib }}
           echo "sagelib ==${{ matrix.sagelib }}" >> $CONDA_PREFIX/conda-meta/pinned
           while read; do

.pylintrc

@@ -2,5 +2,8 @@
 max-line-length=256
 max-module-lines=65536
 
+[TYPECHECK]
+mixin-class-rgx=ParentMethods|SubcategoryMethods|Parent|HyperbolicConvexSet
+
 [MESSAGES CONTROL]
-disable=import-outside-toplevel,no-name-in-module,invalid-name,invalid-unary-operand-type,no-value-for-parameter,abstract-method,arguments-differ,arguments-out-of-order,arguments-renamed,attribute-defined-outside-init,bad-classmethod-argument,bad-staticmethod-argument,broad-exception-caught,broad-exception-raised,chained-comparison,consider-merging-isinstance,consider-swap-variables,consider-using-enumerate,consider-using-f-string,consider-using-generator,consider-using-get,consider-using-in,consider-using-set-comprehension,consider-using-with,cyclic-import,dangerous-default-value,duplicate-code,import-self,inconsistent-return-statements,missing-class-docstring,missing-function-docstring,missing-module-docstring,no-else-break,no-else-continue,no-else-raise,no-else-return,non-ascii-name,non-parent-init-called,pointless-exception-statement,protected-access,raise-missing-from,raising-format-tuple,redefined-argument-from-local,redefined-builtin,redefined-outer-name,self-assigning-variable,self-cls-assignment,singleton-comparison,superfluous-parens,super-init-not-called,too-few-public-methods,too-many-arguments,too-many-boolean-expressions,too-many-branches,too-many-instance-attributes,too-many-locals,too-many-nested-blocks,too-many-public-methods,too-many-return-statements,too-many-statements,undefined-loop-variable,unidiomatic-typecheck,unnecessary-comprehension,unnecessary-dunder-call,unnecessary-lambda,unnecessary-pass,unspecified-encoding,unused-argument,unused-import,unused-variable,unused-wildcard-import,use-a-generator,use-dict-literal,useless-object-inheritance,useless-parent-delegation,wildcard-import,wrong-import-order,fixme,unreachable,reimported
+disable=import-outside-toplevel,no-name-in-module,invalid-name,invalid-unary-operand-type,no-value-for-parameter,abstract-method,arguments-differ,arguments-out-of-order,arguments-renamed,attribute-defined-outside-init,bad-classmethod-argument,bad-staticmethod-argument,broad-exception-caught,broad-exception-raised,chained-comparison,consider-merging-isinstance,consider-swap-variables,consider-using-enumerate,consider-using-f-string,consider-using-generator,consider-using-get,consider-using-in,consider-using-set-comprehension,consider-using-with,cyclic-import,dangerous-default-value,duplicate-code,import-self,inconsistent-return-statements,missing-class-docstring,missing-function-docstring,missing-module-docstring,no-else-break,no-else-continue,no-else-raise,no-else-return,non-ascii-name,non-parent-init-called,pointless-exception-statement,protected-access,raise-missing-from,raising-format-tuple,redefined-argument-from-local,redefined-builtin,redefined-outer-name,self-assigning-variable,self-cls-assignment,singleton-comparison,superfluous-parens,super-init-not-called,too-few-public-methods,too-many-arguments,too-many-boolean-expressions,too-many-branches,too-many-instance-attributes,too-many-locals,too-many-nested-blocks,too-many-public-methods,too-many-return-statements,too-many-statements,undefined-loop-variable,unidiomatic-typecheck,unnecessary-comprehension,unnecessary-dunder-call,unnecessary-lambda,unnecessary-pass,unspecified-encoding,unused-argument,unused-import,unused-variable,unused-wildcard-import,use-a-generator,use-dict-literal,useless-object-inheritance,useless-parent-delegation,wildcard-import,wrong-import-order,fixme,unreachable,reimported,too-many-ancestors

asv.conf.json

@@ -12,11 +12,11 @@
     "gap-defaults": [],
     "matplotlib-base": [],
     "pip+flipper": [],
-    "pyeantic": ["1.0.3"],
-    "pyexactreal": ["2.2.1"],
-    "pyflatsurf": ["3.9.3"],
+    "pyeantic": ["1.3.0"],
+    "pyexactreal": ["3.1.0"],
+    "pyflatsurf": ["3.13.3"],
     "python": [],
-    "sagelib": ["9.4"],
+    "sagelib": ["10.0"],
     "scipy": [],
     "surface-dynamics>=0.4.7": []
   },

doc/conf.py

@@ -3,7 +3,10 @@
 
 # -- General configuration ------------------------------------------------
 extensions = [
-    "sphinx.ext.autodoc",
+    # We need to use SageMath's autodoc to render nested classes in categories
+    # correctly. Otherwise they just render as "alias for" in the
+    # documentation.
+    "sage_docbuild.ext.sage_autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",

doc/environment.yml

@@ -9,7 +9,6 @@ channels:
   - defaults
 dependencies:
   - sphinx
-  - jupytext
   - myst-nb
   - tachyon
   - furo

doc/examples/apisa_wright.md

@@ -5,9 +5,9 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.13.0
+    jupytext_version: 1.14.6
 kernelspec:
-  display_name: SageMath 9.3
+  display_name: SageMath 9.7
   language: sage
   name: sagemath
 ---
@@ -39,62 +39,61 @@ We consider the following half-translation surface
     2               2
     |               |
     +---1---+---1---+
-    
+
 It belongs to $Q_3(10, -1^2)$.
 
-```{code-cell} ipython3
+```{code-cell}
+from flatsurf import Polygon, MutableOrientedSimilaritySurface
+
+
 def apisa_wright_surface(h24, h3, l15, l6, l7, l8):
-    from flatsurf import ConvexPolygons, HalfTranslationSurface, Surface_list
-    params = [h24, h3, l15, l6, l7, l8]
-    K = Sequence(params).universe().fraction_field()
+    K = Sequence([h24, h3, l15, l6, l7, l8]).universe().fraction_field()
+
     v24 = vector(K, (0, h24))
     v3 = vector(K, (0, h3))
     v15 = vector(K, (l15, 0))
     v6 = vector(K, (l6, 0))
     v7 = vector(K, (l7, 0))
     v8 = vector(K, (l8, 0))
-    C = ConvexPolygons(K)
-    P0 = C(edges=[v15,v15,v24,-2*v15,-v24])
-    P1 = C(edges=[2*v15,v8,v7,v6,v3,-v8,-v7,-v6,-v15,-v15,-v3])
-    P2 = C(edges=[v15,v24,-v15,-v24])
-    S = Surface_list(base_ring = C.base_ring())
-    S.rename("ApisaWrightSurface({})".format(', '.join(map(str, params))))
-    S.add_polygons([P0, P1, P2])
-    # set_edge_pairing(poly_num1, edge_num1, poly_num2, edge_num2)
-    S.set_edge_pairing(0, 0, 0, 1)
-    S.set_edge_pairing(0, 2, 0, 4)
-    S.set_edge_pairing(0, 3, 1, 0)
-    S.set_edge_pairing(1, 1, 1, 5)
-    S.set_edge_pairing(1, 2, 1, 6)
-    S.set_edge_pairing(1, 3, 1, 7)
-    S.set_edge_pairing(1, 4, 1, 10)
-    S.set_edge_pairing(1, 8, 2, 2)
-    S.set_edge_pairing(1, 9, 2, 0)
-    S.set_edge_pairing(2, 1, 2, 3)
+
+    S = MutableOrientedSimilaritySurface(K)
+
+    S.add_polygon(Polygon(edges=[v15, v15, v24, -2 * v15, -v24]))
+    S.add_polygon(
+        Polygon(edges=[2 * v15, v8, v7, v6, v3, -v8, -v7, -v6, -v15, -v15, -v3])
+    )
+    S.add_polygon(Polygon(edges=[v15, v24, -v15, -v24], base_ring=K))
+
+    S.glue((0, 0), (0, 1))
+    S.glue((0, 2), (0, 4))
+    S.glue((0, 3), (1, 0))
+    S.glue((1, 1), (1, 5))
+    S.glue((1, 2), (1, 6))
+    S.glue((1, 3), (1, 7))
+    S.glue((1, 4), (1, 10))
+    S.glue((1, 8), (2, 2))
+    S.glue((1, 9), (2, 0))
+    S.glue((2, 1), (2, 3))
     S.set_immutable()
-    return HalfTranslationSurface(S)
+    return S
 ```
 
 We use some simple parameters:
 
-```{code-cell} ipython3
-x = polygen(QQ)
-K.<c> = NumberField(x^2 - 2, embedding=AA(2).sqrt())
-S = apisa_wright_surface(1, 1+c, 1, c, 1+c, 2*c-1)
+```{code-cell}
+K = QuadraticField(2)
+a = K.gen()
+S = apisa_wright_surface(1, 1 + a, 1, a, 1 + a, 2 * a - 1)
 S.plot(edge_labels=False)
 ```
 
-Now build the canonical double cover and orbit closure:
-
-```{code-cell} ipython3
-S.stratum()
+```{code-cell}
+S
 ```
 
-```{code-cell} ipython3
-S.stratum().dimension()
-```
+Now build the canonical double cover and orbit closure:
 
-```{code-cell} ipython3
+```{code-cell}
 U = S.minimal_cover("translation")
 U.stratum()
 ```
@@ -104,37 +103,39 @@ length 16 looking for cylinders. Each decomposition into cylinders and minimal
 components provides a new tangent direction in the `GL(2,R)`-orbit closure of
 the surface via A. Wright's cylinder deformation.
 
-```{code-cell} ipython3
+```{code-cell}
 from flatsurf import GL2ROrbitClosure  # optional: pyflatsurf
-U = S.minimal_cover('translation')  # optional: pyflatsurf
-O = GL2ROrbitClosure(U) # optional: pyflatsurf
-O.dimension() # optional: pyflatsurf
+
+O = GL2ROrbitClosure(U)  # optional: pyflatsurf
+O.dimension()  # optional: pyflatsurf
 ```
 
 The above dimension is just the current dimension. At initialization it only
 consists of the `GL(2,R)`-direction.
 
-```{code-cell} ipython3
-old_dim = O.dimension() # optional: pyflatsurf
-for i, dec in enumerate(O.decompositions(16, bfs=True)): # optional: pyflatsurf
-     O.update_tangent_space_from_flow_decomposition(dec)
-     new_dim = O.dimension()
-     if old_dim != new_dim:
-         holonomies = [cyl.circumferenceHolonomy() for cyl in dec.cylinders()]
-         # .area() as reported by liblatsurf is actually twice the area
-         areas = [cyl.area()/2 for cyl in dec.cylinders()]
-         moduli = [(v.x()*v.x() + v.y()*v.y()) / area for v, area in zip(holonomies, areas)]
-         u = dec.vertical().vertical()
-         print("saddle connection number", i)
-         print("holonomy           :", u)
-         print("length             :", RDF(u.x()*u.x() + u.y()*u.y()).sqrt())
-         print("num cylinders      :", len(dec.cylinders()))
-         print("num minimal comps. :", len(dec.minimalComponents()))
-         print("current dimension  :", new_dim)
-         print("cyls. holonomies   :", holonomies)
-         print("cyls. moduli       :", moduli)
-         if new_dim == 7:
-             break
-         old_dim = new_dim
-         print('-' * 30)
+```{code-cell}
+old_dim = O.dimension()  # optional: pyflatsurf
+for i, dec in enumerate(O.decompositions(16, bfs=True)):  # optional: pyflatsurf
+    O.update_tangent_space_from_flow_decomposition(dec)
+    new_dim = O.dimension()
+    if old_dim != new_dim:
+        holonomies = [cyl.circumferenceHolonomy() for cyl in dec.cylinders()]
+        # .area() as reported by liblatsurf is actually twice the area
+        areas = [cyl.area() / 2 for cyl in dec.cylinders()]
+        moduli = [
+            (v.x() * v.x() + v.y() * v.y()) / area for v, area in zip(holonomies, areas)
+        ]
+        u = dec.vertical().vertical()
+        print("saddle connection number", i)
+        print("holonomy           :", u)
+        print("length             :", RDF(u.x() * u.x() + u.y() * u.y()).sqrt())
+        print("num cylinders      :", len(dec.cylinders()))
+        print("num minimal comps. :", len(dec.minimalComponents()))
+        print("current dimension  :", new_dim)
+        print("cyls. holonomies   :", holonomies)
+        print("cyls. moduli       :", moduli)
+        if new_dim == 7:
+            break
+        old_dim = new_dim
+        print("-" * 30)
 ```