gh-40370: Interface for Regina (3-manifold topology and normal surface theory)
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->


This PR is intended to resolve the old Trac ticket #17077 (now a GitHub
issue). This branch is based on the branch of Trac ticket #31456, which
addressed the implementation of the optional `SPKG`.

In the latter ticket it was noted that the package is not compatible
with 32-bit systems and is therefore considered *experimental* (see
#31456 (comment)).
According to
#31456 (comment),
this should now be resolved. However, I haven't verified this yet. Are
there still CI runs for this? Is this still a policy?

If this issue turns out to have resisted, I will change the type to
*experimental*.

This PR initiates the integration of [Regina](https://regina-
normal.github.io/) via the Sage interface framework. Most of the basics
should be included, but given Regina's broad functionality, this PR is
still selective focusing on some applications of knot theory. However,
future extensions should now be fairly straightforward. Explicitly it
starts with the following specific conversions:

* integers
* rationals
* rational univariate polynomials
* integral uni- and bivariate Laurent polynomials
* finitely presented groups
* links (including fundamental group and Homfly polynomial integration
and adding link simplification)

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #40370
Reported by: Sebastian Oehms
Reviewer(s): Sebastian Oehms, Travis Scrimshaw

Author: Release Manager

build/pkgs/regina/SPKG.rst

@@ -0,0 +1,22 @@
+regina: Low-dimensional topology: triangulations, knots, links, normal surfaces, angle structures
+=================================================================================================
+
+Description
+-----------
+
+Regina is a software package for 3-manifold and 4-manifold topologists, with a focus on triangulations, knots and links, normal surfaces, and angle structures.
+
+For 3-manifolds, it includes high-level tasks such as 3-sphere recognition, connected sum decomposition and Hakenness testing, comes with a rich database of census manifolds, and incorporates the SnapPea kernel for working with hyperbolic manifolds. For 4-manifolds, it offers a range of combinatorial and algebraic tools, plus support for normal hypersurfaces. For knots and links, Regina can perform combinatorial manipulation, compute knot polynomials, and work with several import/export formats.
+
+License
+-------
+
+GPLv2+
+
+Upstream Contact
+----------------
+
+Regina: https://regina-normal.github.io/
+
+We use the Python packaging from https://pypi.org/project/regina/
+(https://github.com/3-manifolds/regina_wheels)

build/pkgs/regina/dependencies

@@ -0,0 +1,4 @@
+$(PYTHON) | $(PYTHON_TOOLCHAIN) numpy
+
+----------
+All lines of this file are ignored except the first.

build/pkgs/regina/requirements.txt

@@ -0,0 +1 @@
+regina

build/pkgs/regina/spkg-configure.m4

@@ -0,0 +1 @@
+SAGE_SPKG_CONFIGURE([regina], [SAGE_PYTHON_PACKAGE_CHECK([regina])])

build/pkgs/regina/type

@@ -0,0 +1 @@
+optional

src/doc/en/reference/interfaces/index.rst

@@ -100,6 +100,7 @@ and testing to make sure nothing funny is going on).
    sage/interfaces/psage
    sage/interfaces/qepcad
    sage/interfaces/r
+   sage/interfaces/regina
    sage/interfaces/rubik
    sage/interfaces/sage0
    sage/interfaces/scilab

src/sage/doctest/external.py

@@ -384,7 +384,7 @@ def external_features():
     yield from sage.features.ffmpeg.all_features()
     import sage.features.interfaces
     for feature in sage.features.interfaces.all_features():
-        if feature.name != 'mathics':
+        if feature.name not in ('mathics', 'regina'):
             yield feature
     from sage.features.mip_backends import CPLEX, Gurobi
     yield CPLEX()

src/sage/features/interfaces.py

@@ -108,6 +108,40 @@ def __classcall__(cls):
         return InterfaceFeature.__classcall__(cls, 'mathics', 'sage.interfaces.mathics')
 
 
+class Regina(InterfaceFeature):
+    r"""
+    A :class:`~sage.features.Feature` describing whether :class:`sage.interfaces.regina.Regina`
+    is present and functional.
+
+    EXAMPLES::
+
+        sage: from sage.features.interfaces import Regina
+        sage: Regina().is_present()  # not tested
+        FeatureTestResult('regina', False)
+    """
+
+    @staticmethod
+    def __classcall__(cls):
+        r"""
+        TESTS::
+
+            sage: from sage.features.interfaces import Regina
+            sage: F = Regina()
+            sage: F.module.hide()
+            sage: regina(~7)
+            Traceback (most recent call last):
+            ...
+            FeatureNotPresentError: sage.interfaces.regina is not available.
+            Feature `sage.interfaces.regina` is hidden.
+            Use method `unhide` to make it available again.
+            sage: F.module.unhide()
+        """
+        from sage.features.join_feature import JoinFeature
+        interface = 'sage.interfaces.regina'
+        mod = JoinFeature(interface, (PythonModule('regina'), PythonModule(interface)))
+        return InterfaceFeature.__classcall__(cls, 'regina', mod)
+
+
 # The following are provided by external software only (no SPKG)
 
 class Magma(InterfaceFeature):
@@ -244,6 +278,7 @@ def all_features():
          Feature('maple'),
          Feature('macaulay2'),
          Feature('octave'),
+         Feature('regina'),
          Feature('scilab')]
     """
     return [Magma(),
@@ -253,4 +288,5 @@ def all_features():
             Maple(),
             Macaulay2(),
             Octave(),
+            Regina(),
             Scilab()]

src/sage/groups/finitely_presented.py

@@ -858,6 +858,22 @@ def _latex_(self):
         r = r+'\\rangle'
         return r
 
+    def _regina_(self, regina):
+        r"""
+        Return the string used to construct the object in Regina.
+
+        EXAMPLES::
+
+            sage: B = BraidGroup(3)
+            sage: regina(B)        # optional regina
+            <regina.GroupPresentation: < a b | a b a b^-1 a^-1 b^-1 >>
+        """
+        F = regina(self._free_group)
+        new = F.__deepcopy__()
+        for r in self.relations():
+            new.addRelation(regina(r))
+        return new
+
     def free_group(self):
         """
         Return the free group (without relations).

src/sage/groups/free_group.py

@@ -291,6 +291,29 @@ def __reduce__(self):
         """
         return (self.parent(), (self.Tietze(),))
 
+    def _regina_(self, regina):
+        r"""
+        Return the string used to construct the object in Regina.
+
+        EXAMPLES::
+
+            sage: F = FreeGroup(3)
+            sage: f = F.an_element(); f
+            x0*x1*x2
+            sage: regina(f)      # optional regina
+            <regina.GroupExpression: g0 g1 g2>
+        """
+        import string
+        word = ''
+        for i in self.Tietze():
+            if i > 0:
+                next_char = string.ascii_lowercase[i - 1]
+            else:
+                next_char = string.ascii_uppercase[-i - 1]
+            word = '%s%s' % (word, next_char)
+        res = regina.GroupExpression(word)
+        return res
+
     @cached_method
     def Tietze(self):
         """
@@ -812,6 +835,18 @@ def _gap_init_(self):
         gen_str = ', '.join(gap_names)
         return 'FreeGroup(['+gen_str+'])'
 
+    def _regina_(self, regina):
+        r"""
+        Return this group as an object in Regina.
+
+        EXAMPLES::
+
+            sage: F = FreeGroup(3)
+            sage: regina(F)              # optional regina
+            <regina.GroupPresentation: < a b c >>
+        """
+        return regina.GroupPresentation(int(self.ngens()))
+
     def _element_constructor_(self, *args, **kwds):
         """
         TESTS::