The bindings of Stephen (#224)

Author: reiniscirpons

docs/source/libsemigroups.bib

@@ -636,3 +636,10 @@ @misc{Abram2024aa
 	title = {Power Quotients of Plactic-like Monoids},
 	year = {2024}
 }
+@article{Stephen1987aa,
+	title = {Applications of automata theory to presentations of monoids and inverse monoids},
+	url = {https://digitalcommons.unl.edu/dissertations/AAI8803771},
+	journal = {ETD collection for University of Nebraska-Lincoln},
+	author = {Stephen, Joseph Buchanan},
+	month = {01},
+	year = {1987}}

docs/source/main-algorithms/stephen/index.rst

@@ -8,12 +8,11 @@ Stephen
 =======
 
 This page contains links to the functionality in ``libsemigroups_pybind11``
-related to Stephen's procedure for finitely presented semigroups.
+related to Stephen's procedure :cite:`Stephen1987aa` for finitely presented
+semigroups.
 
 .. toctree::
    :maxdepth: 1
 
    stephen
    stephen-helpers
-
-

docs/source/main-algorithms/stephen/stephen-helpers.rst

@@ -1,4 +1,4 @@
-.. Copyright (c) 2022-2024 J. D. Mitchell
+.. Copyright (c) 2022-2025 R. Cirpons, J. D. Mitchell
 
    Distributed under the terms of the GPL license version 3.
 
@@ -7,9 +7,34 @@
    This file only exists because Breathe always displays all members when
    documenting a namespace, and this is nicer for now.
 
-.. currentmodule:: _libsemigroups_pybind11
+Helpers functions for Stephen's procedure
+=========================================
 
-Stephen helpers
----------------
+This page contains the documentation for various helper functions for
+manipulating :any:`StephenPresentationWords` objects.
 
-TODO
+Contents
+--------
+
+.. currentmodule:: libsemigroups_pybind11.stephen
+
+.. autosummary::
+   :signatures: short
+
+   accepts
+   dot
+   is_left_factor
+   left_factors
+   number_of_left_factors
+   number_of_words_accepted
+   words_accepted
+   
+Full API
+--------
+
+.. currentmodule:: libsemigroups_pybind11
+
+.. automodule:: libsemigroups_pybind11.stephen
+   :members:
+   :exclude-members: Stephen
+   :imported-members:

docs/source/main-algorithms/stephen/stephen.rst

@@ -1,12 +1,37 @@
-.. Copyright (c) 2022-2024 J. D. Mitchell
+.. Copyright (c) 2022-2025 R. Cirpons, J. D. Mitchell
 
    Distributed under the terms of the GPL license version 3.
 
    The full license is in the file LICENSE, distributed with this software.
 
 .. currentmodule:: _libsemigroups_pybind11
 
-Stephen
-=======
+The Stephen class
+=====================
 
-TODO
+.. autoclass:: StephenPresentationWords
+   :doc-only:
+   :class-doc-from: class
+
+Contents
+--------
+
+.. autosummary::
+   :signatures: short
+
+   ~StephenPresentationWords
+   StephenPresentationWords.accept_state
+   StephenPresentationWords.init
+   StephenPresentationWords.is_word_set
+   StephenPresentationWords.presentation
+   StephenPresentationWords.set_word
+   StephenPresentationWords.word
+   StephenPresentationWords.word_graph
+   StephenPresentationWords.initial_state
+
+Full API
+--------
+
+.. autoclass:: StephenPresentationWords
+   :class-doc-from: init
+   :members:

etc/replace-strings-in-doc.py

@@ -27,6 +27,7 @@
     "PPerm1": "PPerm",
     "Perm1": "Perm",
     "PresentationStrings": "Presentation",
+    "PresentationWords": "Presentation",
     "RightActionPPerm1List": "Action",
     "SchreierSimsPerm1": "SchreierSims",
     "ToddCoxeterImpl": "ToddCoxeter",
@@ -43,6 +44,7 @@
     r"SimsSettingsSims1": "SimsSettings",
     r"_libsemigroups_pybind11.": "",
     r"libsemigroups_pybind11\.": "",
+    r"StephenPresentationWords": "Stephen",
 }
 
 html_glob = "docs/_build/html/**/*.html"

libsemigroups_pybind11/__init__.py

@@ -111,5 +111,7 @@
 from .froidure_pin import FroidurePin
 from .schreier_sims import SchreierSims
 
+from .stephen import Stephen
+
 from .to import to
 from .konieczny import Konieczny

libsemigroups_pybind11/stephen.py

@@ -14,10 +14,63 @@
 """
 
 from _libsemigroups_pybind11 import (
+    PresentationWords as _PresentationWords,
+    InversePresentationWords as _InversePresentationWords,
+    StephenPresentationWords as _StephenPresentationWords,
+    StephenInversePresentationWords as _StephenInversePresentationWords,
     accepts,
+    dot,
     is_left_factor,
     left_factors,
     number_of_left_factors,
     number_of_words_accepted,
     words_accepted,
 )
+
+
+# TODO(2): Make this work with string presentations once it works
+# TODO(0): Change this to a proper class similar to what's done with Kambites
+#          (once the proper classes PR is merged)
+def Stephen(*args):  # pylint: disable=invalid-name
+    """Construct a Stephen instance of the type specified by its arguments.
+
+    Options for calling this function are:
+    1  Stephen(presentation: PresentationWords)
+    2  Stephen(presentation: InversePresentationWords)
+    3  Stephen(presentation: StephenPresentationWords)
+    4  Stephen(presentation: StephenInversePresentationWords)
+
+    In cases 1 and 2 a new Stephen object is constructed with the given
+    presentation. In cases 3 and 4 the Stephen object is constructed by copying
+    an existing Stephen object. In cases 1 and 3 a StephenPresentationWords
+    object is returned. In cases 2 and 4 a StephenInversePresentationWords
+    object is returned.
+    """
+
+    if len(args) != 1:
+        raise ValueError(f"expected 1 argument, but got {len(args)}")
+
+    presentation_or_stephen = args[0]
+    # Order important here due to inheritance
+    if isinstance(
+        presentation_or_stephen,
+        (_InversePresentationWords, _StephenInversePresentationWords),
+    ):
+        PresentationType = _InversePresentationWords
+    elif isinstance(
+        presentation_or_stephen, (_PresentationWords, _StephenPresentationWords)
+    ):
+        PresentationType = _PresentationWords
+    else:
+        raise TypeError(
+            f"expected first argument to have type in {{PresentationWords, "
+            f"InversePresentationWords, StephenPresentationWords, "
+            f"StephenInversePresentationWords}}, but found {type(presentation_or_stephen)}"
+        )
+
+    cpp_type = {
+        _PresentationWords: _StephenPresentationWords,
+        _InversePresentationWords: _StephenInversePresentationWords,
+    }
+
+    return cpp_type[PresentationType](presentation_or_stephen)

src/main.cpp

@@ -152,7 +152,7 @@ The valid values are:
     m.attr("LIBSEMIGROUPS_EIGEN_ENABLED")
         = static_cast<bool>(LIBSEMIGROUPS_EIGEN_ENABLED);
 #else
-    m.attr("LIBSEMIGROUPS_EIGEN_ENABLED") = false;
+    m.attr("LIBSEMIGROUPS_EIGEN_ENABLED")   = false;
 #endif
 
 #ifdef LIBSEMIGROUPS_HPCOMBI_ENABLED
@@ -218,6 +218,7 @@ The valid values are:
     init_inverse_present(m);
     init_to_present(m);
     init_sims(m);
+    init_stephen(m);
     init_transf(m);
     init_ranges(m);
     init_words(m);
@@ -246,7 +247,7 @@ The valid values are:
 #ifdef VERSION_INFO
     m.attr("__version__") = VERSION_INFO;
 #else
-    m.attr("__version__") = "dev";
+    m.attr("__version__")                   = "dev";
 #endif
 
     ////////////////////////////////////////////////////////////////////////

src/main.hpp

@@ -54,6 +54,7 @@ namespace libsemigroups {
   void init_ranges(py::module&);
   void init_reporter(py::module&);
   void init_runner(py::module&);
+  void init_stephen(py::module&);
   void init_schreier_sims(py::module&);
   void init_sims(py::module&);
   void init_to_congruence(py::module&);