Use proper class for Kambites

Author: james-d-mitchell

docs/source/conf.py

@@ -220,6 +220,7 @@ def no_doc_run(self):
         ),
     ],
     "Congruence": [("detail::CongruenceCommon", "Congruence")],
+    "Kambites": [("detail::CongruenceCommon", "Kambites")],
 }
 
 # This is what sphinx considers to be a signature

docs/source/main-algorithms/froidure-pin/to-froidure-pin.rst

@@ -79,14 +79,14 @@ This function throws a :any:`LibsemigroupsError` if ``cong.kind`` is not
 
 .. _kambites-to-froidure-pin:
 
-Converting a :any:`KambitesMultiStringView` to a :any:`FroidurePinPBR`
+Converting a :any:`Kambites` to a :any:`FroidurePinPBR`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To construct a :any:`FroidurePinPBR` from a :any:`KambitesMultiStringView`,
+To construct a :any:`FroidurePinPBR` from a :any:`Kambites`,
 specify the following values for *args*:
 
-    * **k** (:any:`KambitesMultiStringView`) -- the
-      :any:`KambitesMultiStringView` object being converted.
+    * **k** (:any:`Kambites`) -- the
+      :any:`Kambites` object being converted.
 
 Additionally, specify the following for *Return*:
 
@@ -96,7 +96,7 @@ The :any:`FroidurePinPBR` object returned is isomorphic to the quotient
 semigroup or monoid represented by *k*.
 
 This function throws a :any:`LibsemigroupsError` if the 
-:any:`KambitesMultiStringView.small_overlap_class` of *k* is not at least
+:any:`Kambites.small_overlap_class` of *k* is not at least
 :math:`4`.
 
 .. warning::

docs/source/main-algorithms/kambites/class.rst

@@ -4,12 +4,12 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-.. currentmodule:: _libsemigroups_pybind11
+.. currentmodule:: libsemigroups_pybind11
 
-The KambitesMultiStringView class
-=================================
+The Kambites class
+==================
 
-.. autoclass:: KambitesMultiStringView
+.. autoclass:: Kambites
    :doc-only:
    :class-doc-from: class
 
@@ -19,21 +19,27 @@ Contents
 .. autosummary::
     :signatures: short
 
-    ~KambitesMultiStringView
-    KambitesMultiStringView.contains
-    KambitesMultiStringView.currently_contains
-    KambitesMultiStringView.generating_pairs
-    KambitesMultiStringView.init
-    KambitesMultiStringView.number_of_classes
-    KambitesMultiStringView.presentation
-    KambitesMultiStringView.reduce
-    KambitesMultiStringView.reduce_no_run
-    KambitesMultiStringView.small_overlap_class
-    KambitesMultiStringView.ukkonen
+    ~Kambites
+    Kambites.contains
+    Kambites.currently_contains
+    Kambites.generating_pairs
+    Kambites.init
+    Kambites.number_of_classes
+    Kambites.presentation
+    Kambites.reduce
+    Kambites.reduce_no_run
+    Kambites.small_overlap_class
+    Kambites.ukkonen
 
 Full API
 --------
 
-.. autoclass:: KambitesMultiStringView
+.. autoclass:: Kambites
    :members:
    :class-doc-from: init
+   :exclude-members: 
+      current_state, dead, finished, internal_generating_pairs, kill,
+      last_report, report, report_every, report_prefix, report_why_we_stopped,
+      reset_last_report, reset_start_time, run, run_for, run_until, running,
+      running_for, running_until, start_time, started, state, stopped,
+      stopped_by_predicate, success, timed_out, 

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

@@ -4,17 +4,17 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-KambitesMultiStringView helper functions
-========================================
+.. currentmodule:: libsemigroups_pybind11.kambites
+
+Kambites helper functions
+=========================
 
 This page contains the documentation for various helper functions for
-manipulating :any:`KambitesMultiStringView` objects.
+manipulating :any:`Kambites` objects.
 
 Contents
 --------
 
-.. currentmodule:: libsemigroups_pybind11.kambites
-
 .. autosummary::
    :signatures: short
 
@@ -30,4 +30,3 @@ Full API
 .. automodule:: libsemigroups_pybind11.kambites
    :members:
    :exclude-members: Kambites
-   :imported-members:

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

@@ -4,10 +4,8 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
-.. currentmodule:: _libsemigroups_pybind11
-
-KambitesMultiStringView
-=======================
+Kambites
+========
 
 On this page there are links to the documentation for the algorithms in
 ``libsemigroups_pybind11`` for small overlap monoids by Mark Kambites and the

docs/source/main-algorithms/todd-coxeter/class/common.rst

@@ -11,7 +11,7 @@ Common methods
 
 This page contains documentation of the methods of :any:`ToddCoxeterWord` that
 are implemented in all of the classes :any:`Congruence`,
-:any:`KambitesMultiStringView`, :any:`KnuthBendixStringRewriteTrie`, and
+:any:`Kambites`, :any:`KnuthBendixStringRewriteTrie`, and
 :any:`ToddCoxeterWord`.
 
 .. automethod:: ToddCoxeterWord.add_generating_pair

etc/replace-strings-in-doc.py

@@ -6,7 +6,9 @@
 
 def dict_sub(replacements, string):
     """replacements has the form {"regex1": "replacement", "regex2": "replacement2", ...}"""
-    global_expression = re.compile("|".join("(" + x + ")" for x in replacements))
+    global_expression = re.compile(
+        "|".join("(" + x + ")" for x in replacements)
+    )
     replacements_by_group = {}
     group = 1
     for expr, replacement in replacements.items():
@@ -39,7 +41,6 @@ def dive(path):
     "FroidurePinPBR": "FroidurePin",
     "ImageLeftActionPPerm1PPerm1": "ImageLeftAction",
     "ImageRightActionPPerm1PPerm1": "ImageRightAction",
-    "KambitesMultiStringView": "Kambites",
     "KnuthBendixImplRewriteTrie": "KnuthBendix",
     "KnuthBendixStringRewriteTrie": "KnuthBendix",
     "PPerm1": "PPerm",

libsemigroups_pybind11/congruence.py

@@ -93,7 +93,7 @@ def get(self: Self, t: type):
 
         :param t:
             The type of object being sought (must be
-            :any:`KambitesMultiStringView`,
+            :any:`Kambites`,
             :any:`KnuthBendixStringRewriteTrie`, or :any:`ToddCoxeterWord`).
         :type t: type
 
@@ -121,7 +121,7 @@ def has(self: Self, t: type) -> bool:
         *t*, and ``False`` if not.
 
         :param t:
-            The type of object being sought (must be :any:`KambitesMultiStringView`,
+            The type of object being sought (must be :any:`Kambites`,
             :any:`KnuthBendixStringRewriteTrie`, or :any:`ToddCoxeterWord`).
         :type t: type
 

libsemigroups_pybind11/kambites.py

@@ -6,61 +6,99 @@
 #
 # The full license is in the file LICENSE, distributed with this software.
 
-# pylint: disable=unused-import, no-name-in-module, invalid-name
+# pylint: disable=unused-import, no-name-in-module,
 # pylint: disable=protected-access, duplicate-code
+# pylint: disable=missing-class-docstring, invalid-name
+# pylint: disable=missing-function-docstring
 
 """
 This package provides the user-facing python part of libsemigroups_pybind11 for
 the libsemigroups::kambites namespace from libsemigroups.
 """
 
 from typing import List
+from typing_extensions import Self
 
 from _libsemigroups_pybind11 import (
     KambitesMultiStringView as _KambitesMultiStringView,
     KambitesWord as _KambitesWord,
     PresentationStrings as _PresentationStrings,
     PresentationWords as _PresentationWords,
     congruence_kind as _congruence_kind,
-    kambites_non_trivial_classes as non_trivial_classes,
-    kambites_normal_forms as normal_forms,
-    kambites_partition as partition,
+    kambites_non_trivial_classes as _kambites_non_trivial_classes,
+    kambites_normal_forms as _kambites_normal_forms,
+    kambites_partition as _kambites_partition,
 )
 
 from .detail.decorators import (
     may_return_positive_infinity as _may_return_positive_infinity,
+    copydoc as _copydoc,
 )
 
-from .detail import cong_intf
-
-
-def Kambites(*args, **kwargs):  # pylint: disable=invalid-name
-    """
-    Function pretending to be a class, just dispatches to the corresponding
-    constructor of the appropriate type based on the arguments.
-    """
-    cong_intf.raise_if_bad_args(*args, **kwargs)
-    if len(args) == 0:
-        Word = kwargs["Word"]
-    else:
-        assert len(args) == 2
-        if isinstance(args[1], _PresentationStrings):
-            Word = str
-        elif isinstance(args[1], _PresentationWords):
-            Word = List[int]
+from .detail import cong_intf as _cong_intf
+from .detail.cxx_wrapper import (
+    CxxWrapper as _CxxWrapper,
+    copy_cxx_mem_fns as _copy_cxx_mem_fns,
+    to_cxx as _to_cxx,
+)
+
+
+class Kambites(_CxxWrapper):
+    __doc__ = _KambitesWord.__doc__
+
+    _py_to_cxx_type_dict = {
+        List[int]: _KambitesWord,
+        str: _KambitesMultiStringView,
+    }
+
+    @_copydoc(_KambitesWord.__init__)
+    def __init__(  # pylint: disable=super-init-not-called
+        self: Self, *args, **kwargs
+    ) -> None:
+        _cong_intf.raise_if_bad_args(*args, **kwargs)
+        if len(args) == 0:
+            Word = kwargs["Word"]
         else:
-            raise TypeError(
-                f"expected the 2nd argument to be Presentation, but found {type(args[1])}"
-            )
+            assert len(args) == 2
+            if isinstance(args[1], _PresentationStrings):
+                Word = str
+            elif isinstance(args[1], _PresentationWords):
+                Word = List[int]
+            else:
+                raise TypeError(
+                    f"expected the 2nd argument to be Presentation, but found {type(args[1])}"
+                )
+
+        self._cxx_obj = self._py_to_cxx_type_dict[Word](*args)
+
+    @_copydoc(_KambitesWord._number_of_classes)
+    @_may_return_positive_infinity
+    def number_of_classes(self: Self) -> int:
+        return _to_cxx(self)._number_of_classes()
+
+    @_copydoc(_KambitesWord._small_overlap_class)
+    @_may_return_positive_infinity
+    def small_overlap_class(self: Self) -> int:
+        return _to_cxx(self)._small_overlap_class()
+
+
+_copy_cxx_mem_fns(_KambitesWord, Kambites)
+
+
+@_copydoc(_kambites_partition)
+def partition(
+    k: Kambites, words: List[List[int]] | List[str]
+) -> List[List[List[int]]] | List[List[str]]:
+    return _kambites_partition(_to_cxx(k), words)
+
 
-    cpp_type = {List[int]: _KambitesWord, str: _KambitesMultiStringView}
-    return cpp_type[Word](*args)
+@_copydoc(_kambites_non_trivial_classes)
+def non_trivial_classes(
+    k: Kambites, words: List[List[int]] | List[str]
+) -> List[List[List[int]]] | List[List[str]]:
+    return _kambites_non_trivial_classes(_to_cxx(k), words)
 
 
-for _Kambites in [_KambitesWord, _KambitesMultiStringView]:
-    _Kambites.number_of_classes = _may_return_positive_infinity(
-        _Kambites._number_of_classes  # pylint: disable=protected-access
-    )
-    _Kambites.small_overlap_class = _may_return_positive_infinity(
-        _Kambites._small_overlap_class  # pylint: disable=protected-access
-    )
+@_copydoc(_kambites_normal_forms)
+def normal_forms(k: Kambites) -> List[List[int]] | List[str]:
+    return _kambites_normal_forms(_to_cxx(k))

src/cong.cpp

@@ -38,7 +38,7 @@ namespace libsemigroups {
       py::class_<Congruence<Word>, detail::CongruenceCommon> thing(m,
                                                                    name,
                                                                    R"pbdoc(
-Class for running :any:`KambitesMultiStringView`,
+Class for running :any:`Kambites`,
 :any:`KnuthBendixStringRewriteTrie`, and :any:`ToddCoxeterWord` in parallel.
 
 On this page we describe the functionality relating to the class
@@ -47,7 +47,7 @@ congruence over a semigroup or monoid by running every applicable algorithm
 from ``libsemigroups`` (and some variants of the same algorithm) in parallel.
 This class is provided for convenience, at present it is not very customisable,
 and lacks some of the fine grained control offered by the classes implementing
-individual algorithms, such as :any:`KambitesMultiStringView`,
+individual algorithms, such as :any:`Kambites`,
 :any:`KnuthBendixStringRewriteTrie`, and :any:`ToddCoxeterWord`.
 
 .. seealso::  :any:`Runner`, :any:`congruence_kind`, and :any:`tril`.
@@ -137,7 +137,7 @@ Get the current maximum number of threads.
 :sig=(self: Congruence) -> int:
 
 Get the number of runners. This function returns the number of distinct
-instances of :any:`KambitesMultiStringView`,
+instances of :any:`Kambites`,
 :any:`KnuthBendixStringRewriteTrie`, and/or :any:`ToddCoxeterWord` that are
 contained in a :any:`Congruence` object.