Konieczny hpp (#223)

* Compiling

* First stab at Konieczny

* Add missing files

* Finalising

* Finalising x2

* Lint

* Import Self from typing_extensions

* Punctuation

* Restructure doc

* Minor doc tweaks

---------

Co-authored-by: Joseph Edwards <josephdavidedwards@gmail.com>

Author: james-d-mitchell

docs/source/conf.py

@@ -56,9 +56,7 @@ def doc_only_run(self):
         docstring = list(node.findall(condition=desc_content))
 
         if not docstring:
-            logger.warning(
-                f"The docstring for {self.arguments[0]} cannot be found."
-            )
+            logger.warning(f"The docstring for {self.arguments[0]} cannot be found.")
             return []
 
         return docstring
@@ -104,9 +102,7 @@ def no_doc_run(self):
 source_suffix = ".rst"
 master_doc = "index"
 project = "libsemigroups_pybind11"
-copyright = (
-    "2021-2024, Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte"
-)
+copyright = "2021-2024, Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte"
 author = "Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte"
 version = "1.0.0"
 release = "1.0.0"
@@ -175,6 +171,8 @@ def no_doc_run(self):
         r"libsemigroups::BooleanProd, libsemigroups::BooleanZero, "
         r"libsemigroups::BooleanOne, int>"
     ): r"Matrix",
+    r"libsemigroups::Konieczny<BMat8, "
+    "libsemigroups::KoniecznyTraits<BMat8>>::DClass": "KoniecznyBMat8DClass",
 }
 
 # This dictionary should be of the form class_name -> (pattern, repl), where
@@ -184,6 +182,7 @@ def no_doc_run(self):
     "RightActionPPerm1List": [
         ("libsemigroups::PPerm<16ul, unsigned char>", "Element"),
         ("libsemigroups::Element", "Element"),
+        ("libsemigroups::PPerm<0ul, unsigned char>", "Element"),
     ],
     "Transf1": [
         ("PTransfBase1", "Transf1"),
@@ -208,6 +207,14 @@ def no_doc_run(self):
         ("SubclassType", "RepOrc"),
         ("SimsSettingsRepOrc", "RepOrc"),
     ],
+    "KoniecznyBMat8": [
+        (r"\bBMat8\b", "Element"),
+        (
+            "libsemigroups::Konieczny<libsemigroups::Element, "
+            "libsemigroups::KoniecznyTraits<libsemigroups::Element>>::DClass",
+            "KoniecznyBMat8.DClass",
+        ),
+    ],
 }
 
 # This is what sphinx considers to be a signature
@@ -436,6 +443,7 @@ def fix_overloads(app, what, name, obj, options, lines):
     r"todd_coxeter_partition.*$": "",
     r"todd_coxeter_redundant_rule.*$": "",
     r"word_graph_dot\(.*\)(\s*->\s*(\w+::)*\w*)?": "",
+    r"D_class_of_element\(.*$": "",
 }
 
 

docs/source/data-structures/elements/matrix/bmat8-helpers.rst

@@ -16,25 +16,26 @@ submodule ``libsemigroups_pybind11.bmat8``.
 Contents
 --------
 
+.. currentmodule:: libsemigroups_pybind11.bmat8
+
 .. autosummary::
    :nosignatures:
 
+   col_space_basis
+   col_space_size
+   minimum_dim
+   number_of_cols
+   number_of_rows
    one
    random
-   transpose
    row_space_basis
-   col_space_basis
-   number_of_rows
-   number_of_cols
    row_space_size
-   col_space_size
-   minimum_dim
    rows
+   transpose
 
 Full API
 --------
 
 .. automodule:: libsemigroups_pybind11.bmat8
    :members:
    :imported-members:
-

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

@@ -17,5 +17,5 @@ authors of ``libsemigroups``; see :cite:`Kambites2009aa`,
 .. toctree::
    :maxdepth: 1
 
-   class 
+   class
    helpers

docs/source/main-algorithms/konieczny/DClass.rst

@@ -0,0 +1,35 @@
+.. Copyright (c) 2025 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
+
+Konieczny.DClass
+================
+
+This page contains documentation for the nested class :any:`DClass`.
+
+Contents
+--------
+
+.. autosummary::
+   :nosignatures:
+
+   ~KoniecznyBMat8DClass
+   KoniecznyBMat8DClass.contains
+   KoniecznyBMat8DClass.is_regular_D_class
+   KoniecznyBMat8DClass.number_of_L_classes
+   KoniecznyBMat8DClass.number_of_R_classes
+   KoniecznyBMat8DClass.number_of_idempotents
+   KoniecznyBMat8DClass.rep
+   KoniecznyBMat8DClass.size
+   KoniecznyBMat8DClass.size_H_class
+
+Full API
+--------
+
+.. autoclass:: _libsemigroups_pybind11::KoniecznyBMat8DClass
+   :members:
+   :exclude-members: name

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

@@ -0,0 +1,64 @@
+.. Copyright (c) 2022-2024 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
+
+The Konieczny class
+===================
+
+.. autoclass:: KoniecznyBMat8
+   :doc-only:
+   :class-doc-from: class
+
+
+Contents
+--------
+
+.. autosummary::
+   :nosignatures:
+
+   ~KoniecznyBMat8
+   KoniecznyBMat8.add_generator
+   KoniecznyBMat8.add_generators
+   KoniecznyBMat8.contains
+   KoniecznyBMat8.copy
+   KoniecznyBMat8.current_D_classes
+   KoniecznyBMat8.current_number_of_D_classes
+   KoniecznyBMat8.current_number_of_H_classes
+   KoniecznyBMat8.current_number_of_L_classes
+   KoniecznyBMat8.current_number_of_R_classes
+   KoniecznyBMat8.current_number_of_idempotents
+   KoniecznyBMat8.current_number_of_regular_D_classes
+   KoniecznyBMat8.current_number_of_regular_L_classes
+   KoniecznyBMat8.current_number_of_regular_R_classes
+   KoniecznyBMat8.current_number_of_regular_elements
+   KoniecznyBMat8.current_regular_D_classes
+   KoniecznyBMat8.current_size
+   KoniecznyBMat8.degree
+   KoniecznyBMat8.generator
+   KoniecznyBMat8.generators
+   KoniecznyBMat8.init
+   KoniecznyBMat8.is_regular_element
+   KoniecznyBMat8.number_of_D_classes
+   KoniecznyBMat8.number_of_H_classes
+   KoniecznyBMat8.number_of_L_classes
+   KoniecznyBMat8.number_of_R_classes
+   KoniecznyBMat8.number_of_generators
+   KoniecznyBMat8.number_of_idempotents
+   KoniecznyBMat8.number_of_regular_D_classes
+   KoniecznyBMat8.number_of_regular_L_classes
+   KoniecznyBMat8.number_of_regular_R_classes
+   KoniecznyBMat8.number_of_regular_elements
+   KoniecznyBMat8.size
+
+
+
+Full API
+--------
+
+.. autoclass:: KoniecznyBMat8
+   :class-doc-from: init
+   :members:

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

@@ -7,16 +7,11 @@
 Konieczny
 =========
 
-``libsemigroups_pybind11`` contains a preliminary implementation of Konieczny's
-generalisation of the Lallement-McFadden algorithm for computing the structure
-of finite semigroups that act on sets; see the documentation below for further
-details. It is preliminary in the sense that the interface exposed by the
-relevant classes is minimal, and that certain optimisations remain to be
-performed.
+This page describes the functionality for Konieczny's algorithm in
+``libsemigroups_pybind11``.
 
-The implementation of the Konieczny and Lallement-McFadden algorithm can be
-used "interactively", in the sense that they can be run for a particular amount
-of time, or until some condition is met; for further details see, for example,
-:py:meth:`Konieczny.run_for` and :py:meth:`Konieczny.run_until`.
+.. toctree::
+   :maxdepth: 1
 
-TODO
+   class
+   DClass

docs/source/main-algorithms/low-index/helpers.rst

@@ -14,7 +14,6 @@ manipulating ``Sims1``, ``Sims2``, ``RepOrc`` or ``MinimalRepOrc``  objects.
 All such functions are contained in the submodule
 ``libsemigroups_pybind11.sims``.
 
-
 Contents
 --------
 

docs/source/main-algorithms/schreier-sims/helpers.rst

@@ -30,4 +30,3 @@ Full API
 
 .. automodule:: libsemigroups_pybind11.schreier_sims
    :members:
-   :imported-members:

etc/replace-strings-in-doc.py

@@ -6,9 +6,7 @@
 
 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():
@@ -58,9 +56,11 @@ def dive(path):
     "libsemigroups_pybind11.bmat8": "bmat8",
     "libsemigroups_pybind11.knuth_bendix": "knuth_bendix",
     r"CongruenceWord": "Congruence",
+    r"\bKoniecznyBMat8\b": "Konieczny",
+    r"KoniecznyBMat8DClass": "Konieczny.DClass",
+    r"SimsSettingsSims1": "SimsSettings",
     r"_libsemigroups_pybind11.": "",
     r"libsemigroups_pybind11\.": "",
-    r"SimsSettingsSims1": "SimsSettings",
 }
 files = all_html_files(html_path)
 

libsemigroups_pybind11/__init__.py

@@ -112,3 +112,4 @@
 from .schreier_sims import SchreierSims
 
 from .to import to
+from .konieczny import Konieczny