presentation: Add more rules functions

Author: Joseph-Edwards

docs/source/data-structures/presentations/present-helpers.rst

@@ -34,10 +34,13 @@ Contents
 .. autosummary::
     :signatures: short
 
+    add_commutes_rules
     add_commutator_rule
     add_cyclic_conjugates
+    add_idempotent_rules
     add_identity_rules
     add_inverse_rules
+    add_involution_rules
     add_rule
     add_rules
     add_zero_rules

src/libsemigroups_pybind11/presentation/__init__.py

@@ -14,9 +14,12 @@
     PresentationString as _PresentationString,
     PresentationWord as _PresentationWord,
     presentation_add_commutator_rule as _add_commutator_rule,
+    presentation_add_commutes_rules as _add_commutes_rules,
     presentation_add_cyclic_conjugates as _add_cyclic_conjugates,
+    presentation_add_idempotent_rules as _add_idempotent_rules,
     presentation_add_identity_rules as _add_identity_rules,
     presentation_add_inverse_rules as _add_inverse_rules,
+    presentation_add_involution_rules as _add_involution_rules,
     presentation_add_rule as _add_rule,
     presentation_add_rules as _add_rules,
     presentation_add_zero_rules as _add_zero_rules,
@@ -232,8 +235,11 @@ def __init__(self: _Self, *args, **kwargs) -> None:
 
 
 add_commutator_rule = _wrap_cxx_free_fn(_add_commutator_rule)
+add_commutes_rules = _wrap_cxx_free_fn(_add_commutes_rules)
+add_idempotent_rules = _wrap_cxx_free_fn(_add_idempotent_rules)
 add_identity_rules = _wrap_cxx_free_fn(_add_identity_rules)
 add_inverse_rules = _wrap_cxx_free_fn(_add_inverse_rules)
+add_involution_rules = _wrap_cxx_free_fn(_add_involution_rules)
 add_rule = _wrap_cxx_free_fn(_add_rule)
 add_rules = _wrap_cxx_free_fn(_add_rules)
 add_zero_rules = _wrap_cxx_free_fn(_add_zero_rules)
@@ -277,9 +283,12 @@ def __init__(self: _Self, *args, **kwargs) -> None:
 __all__ = [
     "Presentation",
     "InversePresentation",
+    "add_commutes_rules",
     "add_commutator_rule",
+    "add_idempotent_rules",
     "add_identity_rules",
     "add_inverse_rules",
+    "add_involution_rules",
     "add_rule",
     "add_rules",
     "add_zero_rules",

src/present.cpp

@@ -491,7 +491,29 @@ the alphabet is :math:`\{a_1, \ldots, a_n\}`; the 2nd parameter *vals* is
     if :math:`e ^ {-1} = e` does not hold.
 
 :complexity:  :math:`O(n)` where :math:`n` is ``p.alphabet().size()``.)pbdoc");
+      m.def("presentation_add_involution_rules",
+            &presentation::add_involution_rules<Word>,
+            py::arg("p"),
+            py::arg("letters"),
+            R"pbdoc(
+:sig=(p: Presentation, letters: Word) -> None:
+:only-document-once:
+
+Add rules that define involutions.
+
+Adds rules to *p* of the form :math:`a^2 = \varepsilon` for every letter
+:math:`a` in *letters*.
+
+:param p: the presentation to add rules to.
+:type p: Presentation
+
+:param letters: the letters to add involution rules for.
+:type letters: :ref:`Word<pseudo_word_type_helper>`
 
+:raises LibsemigroupsError:
+  if any letter in *letters* is not in ``p.alphabet()``, or if
+  ``p.contains_empty_word()`` returns ``False``.
+)pbdoc");
       m.def(
           "presentation_add_rule",
           [](Presentation_& p, Word const& lhop, Word const& rhop) {
@@ -829,6 +851,91 @@ inverses from the rules in *p*, using :any:`try_detect_inverses`. If
   if *x*, *y*, or *id* contains a letter not belonging to
   ``p.alphabet()``, if :any:`try_detect_inverses` throws, or if *x* or
   *y* contains a letter for which no inverse was detected.
+)pbdoc");
+      m.def(
+          "presentation_add_commutes_rules",
+          [](Presentation_& p, Word const& letters) {
+            presentation::add_commutes_rules(p, letters);
+          },
+          py::arg("p"),
+          py::arg("letters"),
+          R"pbdoc(
+:sig=(p: Presentation, letters: Word) -> None:
+:only-document-once:
+
+Add rules so specific letters commute.
+
+Adds rules to *p* of the form :math:`uv = vu` for every pair of letters
+:math:`u, v` in *letters*.
+
+:param p: the presentation to add rules to.
+:type p: Presentation
+
+:param letters: the collection of letters to add rules for.
+:type letters: :ref:`Word<pseudo_word_type_helper>`
+
+:raises LibsemigroupsError:
+  if any letter in *letters* is not in ``p.alphabet()``.
+)pbdoc");
+      m.def(
+          "presentation_add_commutes_rules",
+          [](Presentation_& p, Word const& letters1, Word const& letters2) {
+            presentation::add_commutes_rules(p, letters1, letters2);
+          },
+          py::arg("p"),
+          py::arg("letters1"),
+          py::arg("letters2"),
+          R"pbdoc(
+:sig=(p: Presentation, letters1: Word, letters2: Word) -> None:
+:only-document-once:
+
+Add rules so specific letters commute.
+
+Adds rules to *p* of the form :math:`uv = vu` for every letter :math:`u` in
+*letters1* and :math:`v` in *letters2*.
+
+:param p: the presentation to add rules to.
+:type p: Presentation
+
+:param letters1: the first collection of letters to add rules for.
+:type letters1: :ref:`Word<pseudo_word_type_helper>`
+
+:param letters2: the second collection of letters to add rules for.
+:type letters2: :ref:`Word<pseudo_word_type_helper>`
+
+:raises LibsemigroupsError:
+  if any letter in *letters1* or *letters2* is not in ``p.alphabet()``.
+)pbdoc");
+      m.def(
+          "presentation_add_commutes_rules",
+          [](Presentation_& p, Word const& letters, std::vector<Word> words) {
+            presentation::add_commutes_rules(p, letters, words);
+          },
+          py::arg("p"),
+          py::arg("letters"),
+          py::arg("words"),
+          R"pbdoc(
+:sig=(p: Presentation, letters: Word, words: list[Word]) -> None:
+:only-document-once:
+
+Add rules so specific letters commute.
+
+Adds rules to *p* of the form :math:`uv = vu` for every letter :math:`u` in
+*letters* and word :math:`v` in *words*.
+
+:param p: the presentation to add rules to.
+:type p: Presentation
+
+:param letters: the collection of letters to add rules for.
+:type letters: :ref:`Word<pseudo_word_type_helper>`
+
+:param words: the collection of words to add rules for.
+:type words: list[:ref:`Word<pseudo_word_type_helper>`]
+
+
+:raises LibsemigroupsError:
+  if any letter in *letters*, or any letter in any word in *words* is not in
+  ``p.alphabet()``.
 )pbdoc");
       m.def(
           "presentation_are_rules_sorted",
@@ -1666,6 +1773,27 @@ empty word to the presentation *p*, for every cyclic permutation ``w`` of
   if *relator* contains any letters not belonging to ``p.alphabet()``.
 
 :raises LibsemigroupsError:  if *p* does not contain the empty word.)pbdoc");
+      m.def("presentation_add_idempotent_rules",
+            &presentation::add_idempotent_rules<Word>,
+            py::arg("p"),
+            py::arg("letters"),
+            R"pbdoc(
+:sig=(p: Presentation, letters: Word) -> None:
+:only-document-once:
+Add rules that define idempotents.
+
+Adds rules to *p* of the form :math:`a^2 = a` for every letter :math:`a` in
+*letters*.
+
+:param p: the presentation to add rules to.
+:type p: Presentation
+
+:param letters: the letters to make idempotent.
+:type letters: :ref:`Word<pseudo_word_type_helper>`
+
+:raises LibsemigroupsError:
+  if any letter in *letters* is not in ``p.alphabet()``.
+)pbdoc");
 
       // We do not bind presentation::find_rule because it returns an iterator
       //

tests/test_present.py

@@ -468,6 +468,78 @@ def check_add_commutator_rule(W):
     ]
 
 
+def check_add_commutes_rules(W):
+    p = Presentation(W([0]))
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_commutes_rules(p, W([0]), W([1]))
+
+    p.alphabet(W([0, 1, 2]))
+    presentation.add_rule(p, W([0, 1, 2, 1]), W([0, 0]))
+    presentation.add_commutes_rules(p, W([0]), W([1]))
+
+    assert p.rules == [W([0, 1, 2, 1]), W([0, 0]), W([0, 1]), W([1, 0])]
+
+    presentation.add_commutes_rules(p, W([1, 1]), W([2]))
+    assert p.rules == [
+        W([0, 1, 2, 1]),
+        W([0, 0]),
+        W([0, 1]),
+        W([1, 0]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 1]),
+        W([1, 2]),
+    ]
+
+    presentation.add_commutes_rules(p, W([2]))
+    assert p.rules == [
+        W([0, 1, 2, 1]),
+        W([0, 0]),
+        W([0, 1]),
+        W([1, 0]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 1]),
+        W([1, 2]),
+    ]
+
+    presentation.add_commutes_rules(p, W([2, 0]))
+    assert p.rules == [
+        W([0, 1, 2, 1]),
+        W([0, 0]),
+        W([0, 1]),
+        W([1, 0]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 0]),
+        W([0, 2]),
+    ]
+
+    presentation.add_commutes_rules(p, W([1, 2]), [W([0, 0, 1]), W([1, 0])])
+    assert p.rules == [
+        W([0, 1, 2, 1]),
+        W([0, 0]),
+        W([0, 1]),
+        W([1, 0]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 1]),
+        W([1, 2]),
+        W([2, 0]),
+        W([0, 2]),
+        W([1, 0, 0, 1]),
+        W([0, 0, 1, 1]),
+        W([1, 1, 0]),
+        W([1, 0, 1]),
+        W([2, 0, 0, 1]),
+        W([0, 0, 1, 2]),
+        W([2, 1, 0]),
+        W([1, 0, 2]),
+    ]
+
+
 def check_add_inverse_rules(W):
     p = Presentation(W([0, 1, 2]))
     presentation.add_rule(p, W([0, 1, 2, 1]), W([0, 0]))
@@ -487,6 +559,31 @@ def check_add_inverse_rules(W):
     assert p.rules == [W([0, 1, 2, 1]), W([0, 0]), W([1, 2]), W([0]), W([2, 1]), W([0])]
 
 
+def check_add_involution_rules(W):
+    p = Presentation(W([0]))
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_involution_rules(p, W([0, 1]))
+    p.alphabet(W([0, 1, 2]))
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_involution_rules(p, W([0, 1]))
+
+    p.contains_empty_word(True)
+    presentation.add_rule(p, W([0, 1, 2, 1]), W([0, 0]))
+    presentation.add_involution_rules(p, W([0, 1]))
+    assert p.rules == [W([0, 1, 2, 1]), W([0, 0]), W([0, 0]), W([]), W([1, 1]), W([])]
+
+
+def check_add_idempotent_rules(W):
+    p = Presentation(W([0]))
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_idempotent_rules(p, W([0, 1]))
+
+    p.alphabet(W([0, 1, 2]))
+    presentation.add_rule(p, W([0, 1, 2, 1]), W([0, 0]))
+    presentation.add_idempotent_rules(p, W([0, 1]))
+    assert p.rules == [W([0, 1, 2, 1]), W([0, 0]), W([0, 0]), W([0]), W([1, 1]), W([1])]
+
+
 def check_remove_duplicate_rules(W):
     p = Presentation(W([0, 1, 2]))
     presentation.add_rule(p, W([0, 1, 2, 1]), W([0, 0]))
@@ -1647,3 +1744,18 @@ def test_add_commutator_rule_errors():
 def test_add_commutator_rule():
     check_add_commutator_rule(to_word)
     check_add_commutator_rule(to_string)
+
+
+def test_add_commutes_rules():
+    check_add_commutes_rules(to_word)
+    check_add_commutes_rules(to_string)
+
+
+def test_add_involution_rules():
+    check_add_involution_rules(to_word)
+    check_add_involution_rules(to_string)
+
+
+def test_add_idempotent_rules():
+    check_add_idempotent_rules(to_word)
+    check_add_idempotent_rules(to_string)