Merge branch 'v1' into runner-hpp

docs/source/action.rst

@@ -0,0 +1,115 @@
+.. Copyright (c) 2024, James 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
+
+Actions
+=======
+
+This page contains details of the ``RowActionBMat8`` class in
+``libsemigroups_pybind11`` for finding actions of semigroups, or groups, on sets.  The
+notion of an "action" in the context of ``libsemigroups_pybind11`` is analogous to the
+notion of an orbit of a group.
+
+The function :any:`run <Runner.run>` finds points that can be obtained by
+acting on the seeds of the action by the generators of the action until no further
+points can be found, or :any:`stopped <Runner.stopped>` returns ``True``.  This
+is achieved by performing a breadth first search.
+
+In this documentation we refer to:
+
+* ``Element`` -- the type of the elements of the underlying semigroup
+* ``Point`` -- the type of the objects on which the semigroup elements act
+* ``Func`` -- the function that computes the action of ``Element`` on ``Point``
+* ``Side`` -- the side of the action (if it is a left or a right action).
+
+The following helper functions are also available:
+
+* :any:`LeftAction`
+* :any:`RightAction`
+
+.. doctest::
+
+  >>> from libsemigroups_pybind11 import RightAction, BMat8
+  >>> o = RightAction(Element=BMat8, Point=BMat8)
+  >>> o.add_seed(
+  ...     BMat8(
+  ...         [[1, 1, 1, 0],
+  ...          [1, 1, 0, 0],
+  ...          [0, 1, 0, 1],
+  ...          [0, 1, 0, 0]]).row_space_basis()
+  ... ).add_generator(
+  ...     BMat8([[1, 0, 0, 0],
+  ...            [0, 1, 0, 0],
+  ...            [0, 0, 1, 0],
+  ...            [0, 0, 0, 1]])
+  ... ).add_generator(
+  ...     BMat8([[0, 1, 0, 0],
+  ...            [1, 0, 0, 0],
+  ...            [0, 0, 1, 0],
+  ...            [0, 0, 0, 1]])
+  ... ).add_generator(
+  ...     BMat8([[0, 1, 0, 0],
+  ...            [0, 0, 1, 0],
+  ...            [0, 0, 0, 1],
+  ...            [1, 0, 0, 0]])
+  ... ).add_generator(
+  ...     BMat8([[1, 0, 0, 0],
+  ...            [0, 1, 0, 0],
+  ...            [0, 0, 1, 0],
+  ...            [1, 0, 0, 1]])
+  ... ).add_generator(
+  ...     BMat8([[1, 0, 0, 0],
+  ...            [0, 1, 0, 0],
+  ...            [0, 0, 1, 0],
+  ...            [0, 0, 0, 0]])
+  ... )
+  <incomplete right action with 5 generators, 1 points>
+  >>> o.size()
+  553
+
+Contents
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    ~RowActionBMat8
+    RowActionBMat8.__getitem__
+    RowActionBMat8.add_generator
+    RowActionBMat8.add_seed
+    RowActionBMat8.cache_scc_multipliers
+    RowActionBMat8.current_size
+    RowActionBMat8.empty
+    RowActionBMat8.init
+    RowActionBMat8.iterator
+    RowActionBMat8.multiplier_from_scc_root
+    RowActionBMat8.multiplier_to_scc_root
+    RowActionBMat8.position
+    RowActionBMat8.reserve
+    RowActionBMat8.root_of_scc
+    RowActionBMat8.scc
+    RowActionBMat8.size
+    RowActionBMat8.word_graph
+
+Full API
+--------
+
+.. currentmodule:: libsemigroups_pybind11
+
+.. autofunction:: RightAction
+
+.. autofunction:: LeftAction
+
+.. currentmodule:: _libsemigroups_pybind11
+
+.. autoclass:: RowActionBMat8
+    :members:
+    :show-inheritance:
+    :class-doc-from: class
+
+    .. autofunction:: libsemigroups_pybind11.action.Action
+

docs/source/conf.py

@@ -68,6 +68,9 @@
 # signature if "good type" is a valid (potentially user defined) python type
 type_replacements = {
     r"libsemigroups::Presentation<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >": r"Presentation",
+    r"libsemigroups::BMat8": r"BMat8",
+    r"libsemigroups::WordGraph<unsigned int>": r"WordGraph",
+    r"libsemigroups::Gabow<unsigned int>": r"Gabow",
 }
 
 # This dictionary should be of the form class_name -> (pattern, repl), where

docs/source/index.rst

@@ -49,7 +49,8 @@ See the installation instructions:
 .. toctree::
    :caption: API REFERENCE
    :hidden:
-
+
+   action
    congruences
    digraph
    elements

etc/replace-strings-in-doc.py

@@ -41,6 +41,8 @@ def dive(path):
     "KnuthBendixRewriteTrie": "KnuthBendix",
     r"_libsemigroups_pybind11.": "",
     "libsemigroups::Presentation<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >": "Presentation",
+    "RowActionBMat8": "Action",
+    "libsemigroups::BMat8": "BMat8",
 }
 files = all_html_files(html_path)
 

libsemigroups_pybind11/__init__.py

@@ -51,21 +51,24 @@
         to_word,
         LibsemigroupsError,
         is_obviously_infinite,
+        BMat8,
+        side,
     )
 except ModuleNotFoundError as e:
     raise ModuleNotFoundError(
         (
             f'{e.msg}, did you forget to run "pip install ." in the libsemigroups_pybind11 '
-            f"director? {DISCLAIMER}"
+            f"directory? {DISCLAIMER}"
         )
     ) from e
 
 
+from .action import Action, RightAction, LeftAction
+from .adapters import ImageRightAction, ImageLeftAction
 from .knuth_bendix import KnuthBendix
 from .presentation import Presentation
 from .transf import PPerm, Transf
 
-
 # from .froidure_pin import FroidurePin
 # from .konieczny import Konieczny
 # from .matrix import Matrix, MatrixKind, make_identity

libsemigroups_pybind11/action.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 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.
+
+# pylint:disable=no-name-in-module, unused-import
+
+"""
+This package provides the user-facing python part of libsemigroups_pybind11 for
+the Action class from libsemigroups.
+"""
+
+from _libsemigroups_pybind11 import RowActionBMat8 as _RowActionBMat8
+from _libsemigroups_pybind11 import ColActionBMat8 as _ColActionBMat8
+from _libsemigroups_pybind11 import BMat8, side
+from .adapters import ImageRightAction, ImageLeftAction
+
+
+def Action(**kwargs):  # pylint: disable=invalid-name
+    """
+    Construct an :any:`Action` instance.
+
+    :Keyword Arguments:
+        * *Element* -- the type of the elements in the action
+        * *Point* -- the type of the points acted on
+        * *Func* -- the function defining the action
+        * *Side* -- the side (or handedness) of the action
+    """
+    if len(kwargs) != 4:
+        raise TypeError(f"expected 4 keyword arguments, found {len(kwargs)}")
+    for kwarg in ("Element", "Point", "Func", "Side"):
+        if kwarg not in kwargs:
+            raise ValueError(
+                f'unexpected keyword argument "{kwarg}", expected'
+                + '"Element", "Point", "Func", and "Side"'
+            )
+
+    if (
+        kwargs["Element"] == BMat8
+        and kwargs["Point"] == BMat8
+        and kwargs["Func"] == ImageRightAction
+        and kwargs["Side"] == side.right
+    ):
+        return _RowActionBMat8()
+    if (
+        kwargs["Element"] == BMat8
+        and kwargs["Point"] == BMat8
+        and kwargs["Func"] == ImageLeftAction
+        and kwargs["Side"] == side.left
+    ):
+        return _ColActionBMat8()
+    raise ValueError("unexpected keyword argument combination")
+
+
+def RightAction(
+    Func=ImageRightAction, **kwargs
+):  # pylint: disable=invalid-name
+    """
+    Construct a right :any:`Action` instance.
+
+    :Keyword Arguments:
+        * *Element* -- the type of the elements in the action
+        * *Point* -- the type of the points acted on
+        * *Func* -- the function defining the action (defaults to :any:`ImageRightAction`)
+
+    """
+    # TODO probably this will generate unhelpful error messages
+    return Action(
+        Func=Func,
+        Element=kwargs["Element"],
+        Point=kwargs["Point"],
+        Side=side.right,
+    )
+
+
+def LeftAction(Func=ImageLeftAction, **kwargs):  # pylint: disable=invalid-name
+    """
+    Construct a left :any:`Action` instance.
+
+    :Keyword Arguments:
+        * *Element* -- the type of the elements in the action
+        * *Point* -- the type of the points acted on
+        * *Func* -- the function defining the action (defaults to :any:`ImageLeftAction`)
+
+    """
+    # TODO probably this will generate unhelpful error messages
+    return Action(
+        Func=Func,
+        Element=kwargs["Element"],
+        Point=kwargs["Point"],
+        Side=side.left,
+    )

libsemigroups_pybind11/adapters.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 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.
+
+# pylint:disable=no-name-in-module, unused-import
+
+"""
+This package provides the user-facing python part of libsemigroups_pybind11 for
+various adapters from libsemigroups.
+"""
+from _libsemigroups_pybind11 import (
+    ImageRightActionBMat8BMat8 as _ImageRightActionBMat8BMat8,
+    ImageLeftActionBMat8BMat8 as _ImageLeftActionBMat8BMat8,
+)
+from _libsemigroups_pybind11 import BMat8
+
+
+def ImageRightAction(**kwargs):  # pylint: disable=invalid-name
+    """
+    Construct a ImageRightAction instance.
+
+    :Keyword Arguments:
+        * *Element* -- the type of the elements in the action
+        * *Point* -- the type of the points acted on
+    """
+    if len(kwargs) != 2:
+        raise TypeError(f"expected 2 keyword arguments, found {len(kwargs)}")
+    for kwarg in ("Element", "Point"):
+        if kwarg not in kwargs:
+            raise ValueError(
+                f'unexpected keyword argument "{kwarg}", expected'
+                + '"Element" and "Point"'
+            )
+
+    if kwargs["Element"] == BMat8 and kwargs["Point"] == BMat8:
+        return _ImageRightActionBMat8BMat8()
+
+    raise ValueError("unexpected keyword argument combination")
+
+
+def ImageLeftAction(**kwargs):  # pylint: disable=invalid-name
+    """
+    Construct a ImageLeftAction instance.
+
+    :Keyword Arguments:
+        * *Element* -- the type of the elements in the action
+        * *Point* -- the type of the points acted on
+    """
+    if len(kwargs) != 2:
+        raise TypeError(f"expected 2 keyword arguments, found {len(kwargs)}")
+    for kwarg in ("Element", "Point"):
+        if kwarg not in kwargs:
+            raise ValueError(
+                f'unexpected keyword argument "{kwarg}", expected'
+                + '"Element" and "Point"'
+            )
+
+    if kwargs["Element"] == BMat8 and kwargs["Point"] == BMat8:
+        return _ImageLeftActionBMat8BMat8()
+
+    raise ValueError("unexpected keyword argument combination")