present+knuth-bendix: add missing features

Author: james-d-mitchell

docs/source/presentations/present-helpers.rst

@@ -39,14 +39,24 @@ Contents
    * - :py:func:`remove_duplicate_rules`
      - Remove duplicate rules.
 
+   * - :py:func:`remove_redundant_generators`
+     - Remove any trivially redundant generators.
+
+   * - :py:func:`remove_trivial_rules`
+     - Remove rules consisting of identical words.
+
    * - :py:func:`reduce_complements`
-     - If there are rules :math:`u = v` and :math:`v = w` where :math:`\lvert w \rvert < \lvert v \rvert`, then replace :math:`u = v` with :math:`u = w`.
+     - If there are rules :math:`u = v` and :math:`v = w` where :math:`\lvert w
+       \rvert < \lvert v \rvert`, then replace :math:`u = v` with :math:`u =
+       w`.
 
    * - :py:func:`sort_each_rule`
-     - Sort each rule :math:`u = v` so that the left hand side is shortlex greater than the right hand side.
+     - Sort each rule :math:`u = v` so that the left hand side is shortlex
+       greater than the right hand side.
 
    * - :py:func:`sort_rules`
-     - Sort the rules :math:`u_1 = v_1, \ldots, u_n = v_n` so that :math:`u_1 v_1 < \cdots < u_n v_n`, where :math:`<` is the shortlex order.
+     - Sort the rules :math:`u_1 = v_1, \ldots, u_n = v_n` so that :math:`u_1
+       v_1 < \cdots < u_n v_n`, where :math:`<` is the shortlex order.
 
    * - :py:func:`longest_common_subword`
      - Return the longest common subword of the rules.
@@ -192,8 +202,8 @@ Full API
 
    Add rules for an identity element.
 
-   Adds rules of the form :math:`a e = e a = a` for every letter :math:`a` in the alphabet of
-   ``p``, where :math:`e` is the second parameter.
+   Adds rules of the form :math:`a e = e a = a` for every letter :math:`a` in
+   the alphabet of ``p``, where :math:`e` is the second parameter.
 
    :param p: the presentation to add rules to
    :type p: Presentation
@@ -213,10 +223,11 @@ Full API
 
    Add rules for inverses.
 
-   The letter ``a`` with index ``i`` in ``vals`` is the inverse of the letter in the alphabet
-   of ``p`` with index ``i``. The rules added are :math:`a_i b_i = e`, where the alphabet is
-   :math:`\{a_i, \ldots, a_n\}`; the parameter ``vals`` is :math:`\{b_1, \ldots, b_n\}`; and
-   :math:`e` is the 3rd parameter.
+   The letter ``a`` with index ``i`` in ``vals`` is the inverse of the letter
+   in the alphabet of ``p`` with index ``i``. The rules added are :math:`a_i
+   b_i = e`, where the alphabet is :math:`\{a_i, \ldots, a_n\}`; the parameter
+   ``vals`` is :math:`\{b_1, \ldots, b_n\}`; and :math:`e` is the 3rd
+   parameter.
 
    :param p: the presentation to add rules to
    :type p: Presentation
@@ -238,9 +249,10 @@ Full API
 
    Remove duplicate rules.
 
-   Removes all but one instance of any duplicate rules (if any). Note that rules of the form
-   :math:`u = v` and :math:`v = u` (if any) are considered duplicates. Also note that the
-   rules may be reordered by this function even if there are no duplicate rules.
+   Removes all but one instance of any duplicate rules (if any). Note that
+   rules of the form :math:`u = v` and :math:`v = u` (if any) are considered
+   duplicates. Also note that the rules may be reordered by this function even
+   if there are no duplicate rules.
 
    :param p: the presentation
    :type p: Presentation
@@ -257,15 +269,50 @@ Full API
       presentation.remove_duplicate_rules(p)
       p.rules  # ['ab', 'baa']
 
+.. py:function:: remove_redundant_generators(p: Presentation) -> None
+
+   Remove any trivially redundant generators.
+
+   If one side of any of the rules in the presentation ``p`` is a letter
+   ``a`` and the other side of the rule does not contain ``a``, then this
+   function replaces every occurrence of ``a`` in every rule by the other
+   side of the rule. This substitution is performed for every such
+   rule in the presentation; and the trivial rules (with both sides being
+   identical) are removed. If both sides of a rule are letters, then the
+   greater letter is replaced by the lesser one.
+
+   :param p: the presentation
+   :type p: Presentation
+
+   :returns: None
+
+   :raises RuntimeError: if ``len(p.rules)`` is odd.
+
+.. py:function:: remove_trivial_rules(p: Presentation) -> None
+
+   Remove rules consisting of identical words.
+
+   Removes all instance of rules (if any) where the left hand side and the
+   right hand side are identical.
+
+   :param p: the presentation
+   :type p: Presentation
+
+   :returns: None
+
+   :raises RuntimeError: if ``len(p.rules)`` is odd.
+
 .. py:function:: reduce_complements(p: Presentation) -> None
 
-   If there are rules :math:`u = v` and :math:`v = w` where :math:`\lvert w \rvert < \lvert v \rvert`, then replace :math:`u = v` with :math:`u = w`.
+   If there are rules :math:`u = v` and :math:`v = w` where :math:`\lvert w
+   \rvert < \lvert v \rvert`, then replace :math:`u = v` with :math:`u = w`.
 
-   Attempts to reduce the length of the words by finding the equivalence relation on the
-   relation words generated by the pairs of identical relation words. If
-   :math:`\{u_1, u_2, \ldots, u_n\}` are distinct words in an equivalence class and
-   :math:`u_1` is the shortlex minimum word in the class, then the relation words are
-   replaced by :math:`u_1 = u_2, u_1 = u_3, \ldots, u_1 = u_n`.
+   Attempts to reduce the length of the words by finding the equivalence
+   relation on the relation words generated by the pairs of identical relation
+   words. If :math:`\{u_1, u_2, \ldots, u_n\}` are distinct words in an
+   equivalence class and :math:`u_1` is the shortlex minimum word in the class,
+   then the relation words are replaced by :math:`u_1 = u_2, u_1 = u_3, \ldots,
+   u_1 = u_n`.
 
    :param p: the presentation
    :type p: Presentation
@@ -284,8 +331,8 @@ Full API
 
 .. py:function:: sort_each_rule(p: Presentation) -> None
 
-   Sort each rule :math:`u = v` so that the left hand side is shortlex greater than the right
-   hand side.
+   Sort each rule :math:`u = v` so that the left hand side is shortlex greater
+   than the right hand side.
 
    :param p: the presentation
    :type p: Presentation
@@ -306,24 +353,45 @@ Full API
 
    Return the longest common subword of the rules.
 
-   If it is possible to find a subword :math:`w` of the rules
-   :math:`u_1 = v_1, \ldots, u_n = v_n` such that the introduction of a new generator
-   :math:`z` and the relation :math:`z = w` reduces the length (see :py:func:`length`)
-   of the presentation, then this function returns the word :math:`w`. If no such word can be
-   found, a word of length :math:`0` is returned.
+   If it is possible to find a subword :math:`w` of the rules :math:`u_1 = v_1,
+   \ldots, u_n = v_n` such that the introduction of a new generator :math:`z`
+   and the relation :math:`z = w` reduces the length (see :py:func:`length`) of
+   the presentation, then this function returns the word :math:`w`. If no such
+   word can be found, a word of length :math:`0` is returned.
 
    :param p: the presentation
    :type p: Presentation
 
    :returns: None
 
+.. py:function:: replace_subword(p: Presentation, existing: Union[str, List[int]], replacement: Union[str, List[int]])
+   :noindex:
+
+   Replace non-overlapping instances of a subword by another word.
+
+   If ``existing`` and ``replacement`` are words, then this function replaces
+   every non-overlapping instance of ``existing`` in every rule by
+   ``replacement``. The presentation ``p`` is changed in-place.
+
+   :param p: the presentation
+   :type p: Presentation
+   :param existing: the word to be replaced
+   :type existing: str or List[int]
+   :param replacement: the replacement word.
+   :type replacement: str or List[int]
+
+   :returns: None
+
+   :raises RuntimeError: if ``existing`` is empty.
+
 .. py:function:: replace_subword(p: Presentation, w: Union[str, List[int]])
 
    Replace non-overlapping instances of a subword.
 
-   A new generator :math:`z` is added to the presentation, along with the rule :math:`w = z`.
-   Each (if any) non-overlapping instance (from left to right) of the word :math:`w` in every
-   rule of the presentation is replaced with :math:`z`.
+   A new generator :math:`z` is added to the presentation, along with the rule
+   :math:`w = z`. Each (if any) non-overlapping instance (from left to right)
+   of the word :math:`w` in every rule of the presentation is replaced with
+   :math:`z`.
 
    :param p: the presentation
    :type p: Presentation
@@ -359,10 +427,11 @@ Full API
 
 .. py:function:: normalize_alphabet(p: Presentation) -> None
 
-   Modify the presentation so that the alphabet is :math:`\{0, \ldots, n - 1\}` (or equivalent),
-   and rewrites the rules to use this alphabet.
+   Modify the presentation so that the alphabet is :math:`\{0, \ldots, n - 1\}`
+   (or equivalent), and rewrites the rules to use this alphabet.
 
-   If the alphabet is already normalized, then no changes are made to the presentation.
+   If the alphabet is already normalized, then no changes are made to the
+   presentation.
 
    :param p: the presentation
    :type p: Presentation

libsemigroups_pybind11/presentation.py

@@ -22,6 +22,8 @@
     add_identity_rules,
     add_inverse_rules,
     remove_duplicate_rules,
+    remove_trivial_rules,
+    remove_redundant_generators,
     reduce_complements,
     sort_each_rule,
     sort_rules,

src/knuth-bendix.cpp

@@ -691,6 +691,20 @@ namespace libsemigroups {
                :Parameters: None
 
                :return: A copy of an :py:class:`ActionDigraph`.
+             )pbdoc")
+        .def("rewrite",
+             py::overload_cast<std::string>(&fpsemigroup::KnuthBendix::rewrite,
+                                            py::const_),
+             R"pbdoc(
+               Rewrite a word.
+
+               Rewrites a copy of the string  ``w`` rewritten according to the current
+               rules in the ``KnuthBendix`` instance.
+
+               :param w: the word to rewrite.
+               :type w: str
+
+               :returns: A copy of the argument ``w`` after it has been rewritten.
              )pbdoc");
   }
 }  // namespace libsemigroups

src/present.cpp

@@ -98,16 +98,24 @@ namespace libsemigroups {
       m.def("add_identity_rules", &presentation::add_identity_rules<T>);
       m.def("add_inverse_rules", &presentation::add_inverse_rules<T>);
       m.def("remove_duplicate_rules", &presentation::remove_duplicate_rules<T>);
+      m.def("remove_trivial_rules", &presentation::remove_trivial_rules<T>);
       m.def("reduce_complements", &presentation::reduce_complements<T>);
       m.def("sort_each_rule", &presentation::sort_each_rule<T>);
       m.def("sort_rules", &presentation::sort_rules<T>);
       m.def("longest_common_subword", &presentation::longest_common_subword<T>);
       m.def("replace_subword",
             py::overload_cast<Presentation<T>&, T const&>(
                 &presentation::replace_subword<T>));
+      m.def(
+          "replace_subword",
+          [](Presentation<T>& p, T const& existing, T const& replace) -> void {
+            presentation::replace_subword(p, existing, replace);
+          });
       m.def("length", &presentation::length<T>);
       m.def("reverse", &presentation::reverse<T>);
       m.def("normalize_alphabet", &presentation::normalize_alphabet<T>);
+      m.def("remove_redundant_generators",
+            &presentation::remove_redundant_generators<T>);
 
       m.def(
           "make",

tests/fpsemi_intf.py

@@ -184,10 +184,10 @@ def check_operators(t):
         x.normal_form("z")
 
     if hasattr(t, "rewrite"):
-        assert x.rewrite("aa") == ""
+        assert x.rewrite("aa") == "e"
         assert x.rewrite("bb") == "B"
 
-        with pytest.raises(TypeError):
+        with pytest.raises(RuntimeError):
             x.rewrite("z")
 
 

tests/test_present.py

@@ -248,6 +248,21 @@ def check_longest_common_subword(W):
         W([p.letter(3)]),
         W([1, 2, 1]),
     ]
+    presentation.replace_subword(p, W([1, 2, 1]), W([1]))
+    assert p.rules == [
+        W([0, p.letter(3)]),
+        W([p.letter(3)]),
+        W([p.letter(3)]),
+        W([1, p.letter(3)]),
+        W([1, p.letter(3)]),
+        W([1, 1]),
+        W([1, 1]),
+        W([p.letter(3)]),
+        W([p.letter(3)]),
+        W([0]),
+        W([p.letter(3)]),
+        W([1]),
+    ]
 
 
 def check_redundant_rule(W):
@@ -677,3 +692,31 @@ def test_issue_52_022():
     p.validate()
 
     assert presentation.redundant_rule(p, timedelta(seconds=1)) == len(p.rules)
+
+
+def test_helpers_remove_trivial_rules():
+    p = Presentation([])
+    presentation.add_rule(p, [0], [0])
+    presentation.add_rule(p, [1], [1])
+    presentation.add_rule(p, [1, 0, 1], [1])
+    p.alphabet_from_rules()
+    p.validate()
+
+    presentation.remove_trivial_rules(p)
+
+    assert p.rules == [[1, 0, 1], [1]]
+
+
+def test_helpers_remove_redundant_generators():
+    p = Presentation([])
+    presentation.add_rule(p, [0], [1])
+    presentation.add_rule(p, [1], [1])
+    presentation.add_rule(p, [1, 0, 1], [1])
+    p.alphabet_from_rules()
+    p.validate()
+
+    presentation.remove_redundant_generators(p)
+    assert p.rules == [[0, 0, 0], [0]]
+    p.rules = p.rules + [[1, 1, 1], [0]]
+    presentation.remove_redundant_generators(p)
+    assert p.rules == [[1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1]]