presentation: add add_cyclic_conjugates

Author: james-d-mitchell

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

@@ -34,6 +34,7 @@ Contents
 .. autosummary::
     :signatures: short
 
+    add_cyclic_conjugates
     add_identity_rules
     add_inverse_rules
     add_rule

src/libsemigroups_pybind11/presentation/__init__.py

@@ -53,6 +53,7 @@
     presentation_throw_if_bad_inverses as _throw_if_bad_inverses,
     presentation_to_gap_string as _to_gap_string,
     presentation_balance as _balance,
+    presentation_add_cyclic_conjugates as _add_cyclic_conjugates,
 )
 
 from libsemigroups_pybind11.detail.cxx_wrapper import (
@@ -265,3 +266,4 @@ def __init__(self: _Self, *args, **kwargs) -> None:
 throw_if_bad_inverses = _wrap_cxx_free_fn(_throw_if_bad_inverses)
 to_gap_string = _wrap_cxx_free_fn(_to_gap_string)
 balance = _wrap_cxx_free_fn(_balance)
+add_cyclic_conjugates = _wrap_cxx_free_fn(_add_cyclic_conjugates)

src/present.cpp

@@ -1369,6 +1369,34 @@ appended to the front of the right-hand side.
   actually inverses for the values in *letters*, and balances the relations
   as described above.
 )pbdoc");
+
+      m.def(
+          "presentation_add_cyclic_conjugates",
+          [](Presentation<Word>& p, Word const& relator) {
+            presentation::add_cyclic_conjugates(p, relator);
+          },
+          py::arg("p"),
+          py::arg("relator"),
+          R"pbdoc(
+:sig=(p: Presentation, relator: Word) -> None:
+:only-document-once:
+
+Add all cyclic permutations of a word as relators in a presentation.
+
+This function adds one rule with left-hand side ``w`` and right-hand side the
+empty word to the presentation *p*, for every cyclic permutation ``w`` of
+*relator*.
+
+:param p: the presentation.
+:type p: Presentation
+
+:param relator: the word.
+:type relator: :ref:`Word<pseudo_word_type_helper>`
+
+:raises LibsemigroupsError:
+  if *relator* contains any letters not belonging to ``p.alphabet()``.
+
+:raises LibsemigroupsError:  if *p* does not contain the empty word.)pbdoc");
     }  // bind_present
 
     template <typename Word>

tests/test_present.py

@@ -2156,3 +2156,39 @@ def test_presentation_balance_3_arg():
         "cacacaccacacbbbb",
         "accacbabbbcbcab",
     ]
+
+
+def test_presentation_add_cyclic_conjugates():
+    p = Presentation("abc")
+    p.contains_empty_word(True)
+
+    presentation.add_cyclic_conjugates(p, "abcaabbcc")
+    assert p.rules == [
+        "abcaabbcc",
+        "",
+        "bcaabbcca",
+        "",
+        "caabbccab",
+        "",
+        "aabbccabc",
+        "",
+        "abbccabca",
+        "",
+        "bbccabcaa",
+        "",
+        "bccabcaab",
+        "",
+        "ccabcaabb",
+        "",
+        "cabcaabbc",
+        "",
+        "abcaabbcc",
+        "",
+    ]
+    p.rules = []
+    p.contains_empty_word(False)
+
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_cyclic_conjugates(p, "abcaabbcc")
+    with pytest.raises(LibsemigroupsError):
+        presentation.add_cyclic_conjugates(p, "dadadad")