Skip to content

Commit 302cb3d

Browse files
james-d-mitchelljames-d-mitchell
committed
Action renovation x4
1 parent 8ef0342 commit 302cb3d

File tree

10 files changed

+340
-195
lines changed

10 files changed

+340
-195
lines changed

‎docs/source/_ext/libsemigroups_pybind11_extensions.py

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -99,25 +99,18 @@ def no_doc_run(self):
9999
# signature if "good type" is a valid (potentially user defined) python type
100100
type_replacements = {
101101
r"libsemigroups::WordGraph<unsigned int>": r"WordGraph",
102-
r"libsemigroups::Gabow<unsigned int>": r"Gabow",
103102
r"libsemigroups::SimsStats": r"SimsStats",
104103
r"libsemigroups::Sims1": r"Sims1",
105104
r"libsemigroups::Sims2": r"Sims2",
106105
r"libsemigroups::RepOrc": r"RepOrc",
107106
r"libsemigroups::MinimalRepOrc": r"MinimalRepOrc",
108-
(
109-
r"libsemigroups::BooleanProd, libsemigroups::BooleanZero, "
110-
r"libsemigroups::BooleanOne, int>"
111-
): r"Matrix",
107+
r"libsemigroups::BooleanOne, int>": r"Matrix",
112108
}
113109

114110
# This dictionary should be of the form class_name -> (pattern, repl), where
115111
# "pattern" should be replaced by "repl" in the signature of all functions in
116112
# "class_name"
117113
class_specific_replacements = {
118-
"RightActionPPerm1List": [
119-
("libsemigroups::PPerm<0ul, unsigned char>", "Element"),
120-
],
121114
"Transf1": [
122115
("PTransfBase1", "Transf1"),
123116
],

‎docs/source/main-algorithms/action/action.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. Copyright (c) 2024, James D. Mitchell
2+
3+
Distributed under the terms of the GPL license version 3.
4+
5+
The full license is in the file LICENSE, distributed with this software.
6+
7+
.. currentmodule:: libsemigroups_pybind11
8+
9+
The Action class
10+
================
11+
12+
.. autoclass:: Action
13+
:doc-only:
14+
:class-doc-from: class
15+
16+
Contents
17+
--------
18+
19+
.. autosummary::
20+
:signatures: short
21+
22+
~Action
23+
Action.add_generator
24+
Action.add_seed
25+
Action.cache_scc_multipliers
26+
Action.current_size
27+
Action.empty
28+
Action.init
29+
Action.multiplier_from_scc_root
30+
Action.multiplier_to_scc_root
31+
Action.position
32+
Action.reserve
33+
Action.root_of_scc
34+
Action.scc
35+
Action.size
36+
Action.word_graph
37+
38+
Full API
39+
--------
40+
41+
.. autoclass:: Action
42+
:members:
43+
:class-doc-from: init
44+
:exclude-members:
45+
current_state, dead, finished, kill,
46+
last_report, report, report_every, report_prefix, report_why_we_stopped,
47+
reset_last_report, reset_start_time, run, run_for, run_until, running,
48+
running_for, running_until, start_time, started, state, stopped,
49+
stopped_by_predicate, success, timed_out

‎docs/source/main-algorithms/action/index.rst

Lines changed: 9 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -4,89 +4,18 @@
44
55
The full license is in the file LICENSE, distributed with this software.
66
7-
.. currentmodule:: _libsemigroups_pybind11
7+
.. currentmodule:: libsemigroups_pybind11
88

99
Actions
1010
=======
1111

12-
This page contains details of the ``Action`` class in
13-
``libsemigroups_pybind11`` for finding actions of semigroups, monoids, or
14-
groups, on sets. The notion of an "action" in the context of
15-
``libsemigroups_pybind11`` is analogous to the notion of an orbit of a group.
16-
17-
The function :any:`run <Runner.run>` finds points that can be obtained by
18-
acting on the seeds of the action by the generators of the action until no further
19-
points can be found, or :any:`stopped <Runner.stopped>` returns ``True``. This
20-
is achieved by performing a breadth first search.
21-
22-
In this documentation we refer to:
23-
24-
* ``Element`` -- the type of the elements of the underlying semigroup
25-
* ``Point`` -- the type of the objects on which the semigroup elements act
26-
* ``Func`` -- the function that computes the action of ``Element`` on ``Point``
27-
* ``Side`` -- the side of the action (if it is a left or a right action).
28-
29-
The following helper functions are also available:
30-
31-
* :any:`LeftAction`
32-
* :any:`RightAction`
33-
34-
.. doctest::
35-
36-
>>> from libsemigroups_pybind11 import RightAction, BMat8
37-
>>> from libsemigroups_pybind11.bmat8 import row_space_basis
38-
>>> o = RightAction(
39-
... seeds=[
40-
... row_space_basis(
41-
... BMat8([[1, 1, 1, 0], [1, 1, 0, 0], [0, 1, 0, 1], [0, 1, 0, 0]])
42-
... )
43-
... ],
44-
... generators=[
45-
... BMat8([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]),
46-
... BMat8([[0, 1, 0, 0], [1, 0, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]),
47-
... BMat8([[0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1], [1, 0, 0, 0]]),
48-
... BMat8([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [1, 0, 0, 1]]),
49-
... BMat8([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 0]]),
50-
... ],
51-
... )
52-
>>> len(o)
53-
553
54-
55-
Contents
56-
--------
57-
58-
.. autosummary::
59-
:signatures: short
60-
61-
~RightActionPPerm1List
62-
RightActionPPerm1List.add_generator
63-
RightActionPPerm1List.add_seed
64-
RightActionPPerm1List.cache_scc_multipliers
65-
RightActionPPerm1List.current_size
66-
RightActionPPerm1List.empty
67-
RightActionPPerm1List.init
68-
RightActionPPerm1List.iterator
69-
RightActionPPerm1List.multiplier_from_scc_root
70-
RightActionPPerm1List.multiplier_to_scc_root
71-
RightActionPPerm1List.position
72-
RightActionPPerm1List.reserve
73-
RightActionPPerm1List.root_of_scc
74-
RightActionPPerm1List.scc
75-
RightActionPPerm1List.size
76-
RightActionPPerm1List.word_graph
77-
78-
Full API
79-
--------
80-
81-
.. currentmodule:: libsemigroups_pybind11
82-
83-
.. autofunction:: RightAction
84-
85-
.. autofunction:: LeftAction
12+
This page contains links to the documentation for the classes in
13+
``libsemigroups_pybind11`` for semigroup actions.
8614

87-
.. currentmodule:: _libsemigroups_pybind11
15+
.. toctree::
16+
:maxdepth: 1
8817

89-
.. autoclass:: RightActionPPerm1List
90-
:members:
91-
:show-inheritance:
92-
:class-doc-from: class
18+
action
19+
rightaction
20+
leftaction
21+
side

‎docs/source/main-algorithms/action/leftaction.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. Copyright (c) 2024, James D. Mitchell
2+
3+
Distributed under the terms of the GPL license version 3.
4+
5+
The full license is in the file LICENSE, distributed with this software.
6+
7+
.. currentmodule:: libsemigroups_pybind11
8+
9+
The LeftAction class
10+
====================
11+
12+
.. autoclass:: LeftAction
13+
:doc-only:
14+
:class-doc-from: class
15+
16+
Full API
17+
--------
18+
19+
.. autoclass:: LeftAction
20+
:members:
21+
:show-inheritance:
22+
:class-doc-from: init

‎docs/source/main-algorithms/action/rightaction.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. Copyright (c) 2024, James D. Mitchell
2+
3+
Distributed under the terms of the GPL license version 3.
4+
5+
The full license is in the file LICENSE, distributed with this software.
6+
7+
.. currentmodule:: libsemigroups_pybind11
8+
9+
The RightAction class
10+
=====================
11+
12+
.. autoclass:: RightAction
13+
:doc-only:
14+
:class-doc-from: class
15+
16+
Full API
17+
--------
18+
19+
.. autoclass:: RightAction
20+
:members:
21+
:show-inheritance:
22+
:class-doc-from: init

‎docs/source/main-algorithms/action/side.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
2+
.. Copyright (c) 2024, James D. Mitchell
3+
4+
Distributed under the terms of the GPL license version 3.
5+
6+
The full license is in the file LICENSE, distributed with this software.
7+
8+
.. currentmodule:: libsemigroups_pybind11
9+
10+
The side enum
11+
=============
12+
13+
This page describes the enum class ``side`` in ``libsemigroups_pybind11``
14+
for representing whether an action is a left or a right action.
15+
16+
Full API
17+
--------
18+
19+
.. autoclass:: side

‎libsemigroups_pybind11/action.py

Lines changed: 93 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -176,18 +176,50 @@ class Action(_CxxWrapper): # pylint: disable=missing-class-docstring
176176
# Special methods
177177
########################################################################
178178

179-
def __init__(self: _Self, *args, seeds=[], generators=[], **kwargs) -> None:
179+
def __init__(
180+
self: _Self, *args, generators=None, seeds=None, func=None, side=None
181+
) -> None:
182+
"""
183+
:sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
184+
185+
Construct an action from generators, seeds, function, and side.
186+
187+
:Keyword Arguments:
188+
189+
* **generators** (*List[Element]*)-- at least one generator for the action.
190+
* **seeds** (*List[Point]*) -- at least one seed point for the action.
191+
* **func** (*Callable[[Point, Element], Point]*) -- the function defining the action.
192+
* **side** (:any:`side <side>`)-- the side of the action.
193+
194+
:raises TypeError:
195+
if *generators* or *seeds* is not a list.
196+
:raises ValueError:
197+
if *generators* or *seeds* has length ``0``.
198+
:raises KeyError:
199+
if the action defined by the arguments is not defined.
200+
"""
201+
180202
super().__init__(
181-
*args,
182203
required_kwargs=("func", "side", "seeds", "generators"),
183-
seeds=seeds,
184204
generators=generators,
185-
**kwargs,
205+
seeds=seeds,
206+
func=func,
207+
side=side,
186208
)
187209
if _to_cxx(self) is not None:
188210
return
189-
# TODO if len(args) != 0 raise
190-
# TODO check if generators is a list and if seeds is a list
211+
if len(args) != 0:
212+
raise ValueError(f"expected 0 positional arguments, but found {len(args)}")
213+
if not isinstance(generators, list):
214+
raise TypeError(
215+
"expected the keyword argument 'generators' to be "
216+
f"a list but found {type(generators)}"
217+
)
218+
if not isinstance(seeds, list):
219+
raise TypeError(
220+
"expected the keyword argument 'seeds' to be "
221+
f"a list but found {type(seeds)}"
222+
)
191223
if len(generators) == 0:
192224
raise ValueError(
193225
"no generators have been specified, please specify at least one generator, "
@@ -204,8 +236,8 @@ def __init__(self: _Self, *args, seeds=[], generators=[], **kwargs) -> None:
204236
self.py_template_params = (
205237
type(generators[0]),
206238
type(seeds[0]),
207-
kwargs["func"],
208-
kwargs["side"],
239+
func,
240+
side,
209241
)
210242
self.init_cxx_obj()
211243
for x in generators:
@@ -239,10 +271,35 @@ def __contains__(self: _Self, pt: Point) -> bool:
239271

240272

241273
class RightAction(Action):
242-
# TODO doc
274+
"""
275+
Class representing a right action of a semigroup or monoid on a set.
276+
277+
This page contains the documentation for the class ``RightAction``, which
278+
just calls :any:`Action` with the keyword arguments *func* given by
279+
:any:`ImageRightAction` and *side* given by :py:class:`side.right`.
280+
"""
243281

244-
def __init__(self: _Self, *args, generators=[], seeds=[], **kwargs) -> None:
282+
def __init__(self: _Self, *args, generators=[], seeds=[]) -> None:
283+
"""
284+
:sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
285+
286+
Construct an :any:`Action` from generators and seeds,
287+
:any:`ImageRightAction` and :py:class:`side.right`.
288+
289+
:Keyword Arguments:
290+
291+
* **generators** (*List[Element]*)-- at least one generator for the action.
292+
* **seeds** (*List[Point]*) -- at least one seed point for the action.
293+
294+
:raises TypeError:
295+
if *generators* or *seeds* is not a list.
296+
:raises ValueError:
297+
if *generators* or *seeds* has length ``0``.
298+
:raises KeyError:
299+
if the action defined by the arguments is not defined.
300+
"""
245301
super().__init__(
302+
*args,
246303
generators=generators,
247304
seeds=seeds,
248305
side=side.right,
@@ -256,9 +313,33 @@ def __init__(self: _Self, *args, generators=[], seeds=[], **kwargs) -> None:
256313

257314

258315
class LeftAction(Action):
259-
# TODO doc
316+
"""
317+
Class representing a left action of a semigroup or monoid on a set.
318+
319+
This page contains the documentation for the class ``LeftAction``, which
320+
just calls :any:`Action` with the keyword arguments *func* given by
321+
:any:`ImageLeftAction` and *side* given by :py:class:`side.left`.
322+
"""
323+
324+
def __init__(self: _Self, *args, generators=[], seeds=[]) -> None:
325+
"""
326+
:sig=(self: Action, generators=None, seeds=None, func=None, side=None) -> None:
327+
328+
Construct an :any:`Action` from generators and seeds,
329+
:any:`ImageLeftAction` and :py:class:`side.left`.
330+
331+
:Keyword Arguments:
332+
333+
* **generators** (*List[Element]*)-- at least one generator for the action.
334+
* **seeds** (*List[Point]*) -- at least one seed point for the action.
260335
261-
def __init__(self: _Self, *args, generators=[], seeds=[], **kwargs) -> None:
336+
:raises TypeError:
337+
if *generators* or *seeds* is not a list.
338+
:raises ValueError:
339+
if *generators* or *seeds* has length ``0``.
340+
:raises KeyError:
341+
if the action defined by the arguments is not defined.
342+
"""
262343
super().__init__(
263344
generators=generators,
264345
seeds=seeds,

0 commit comments

Comments
 (0)