order: add support for wr_cmp

Co-authored-by: James Mitchell <jdm3@st-andrews.ac.uk>

Author: codex

docs/source/data-structures/order/index.rst

@@ -30,6 +30,7 @@ Contents
     rev_rpo_cmp
     rpo_cmp
     shortlex_compare
+    wr_cmp
 
 Full API
 --------
@@ -47,3 +48,5 @@ Full API
 .. autofunction:: rpo_cmp
 
 .. autofunction:: shortlex_compare
+
+.. autofunction:: wr_cmp

src/libsemigroups_pybind11/__init__.py

@@ -22,6 +22,7 @@
     knuth_bendix,
     konieczny,
     matrix,
+    order,
     paths,
     pbr,
     presentation,
@@ -52,6 +53,7 @@
 from .knuth_bendix import KnuthBendix
 from .konieczny import Konieczny
 from .matrix import Matrix, MatrixKind
+from .order import wr_cmp
 from .presentation import InversePresentation, Presentation
 from .schreier_sims import SchreierSims
 from .sims import MinimalRepOrc, RepOrc, Sims1, Sims2, SimsRefinerFaithful, SimsRefinerIdeals
@@ -183,6 +185,7 @@
     "shortlex_compare",
     "side",
     "tril",
+    "wr_cmp",
     # Submodules
     "action",
     "adapters",
@@ -199,6 +202,7 @@
     "knuth_bendix",
     "konieczny",
     "matrix",
+    "order",
     "paths",
     "pbr",
     "presentation",

src/libsemigroups_pybind11/order.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 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.
+
+"""Word-ordering comparison functions."""
+
+from _libsemigroups_pybind11 import wr_cmp as _wr_cmp
+
+from .detail.cxx_wrapper import wrap_cxx_free_fn as _wrap_cxx_free_fn
+
+wr_cmp = _wrap_cxx_free_fn(_wr_cmp)
+
+__all__ = ["wr_cmp"]

src/order.cpp

@@ -18,6 +18,7 @@
 
 // C++ stl headers....
 #include <string>  // for string
+#include <vector>  // for vector
 
 // libsemigroups....
 #include <libsemigroups/order.hpp>  // for *_cmp, Order
@@ -260,6 +261,85 @@ Compare two words using reversed recursive-path ordering.
    This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use
    :any:`rev_rpo_cmp`.
 )pbdoc");
+
+      m.def(
+          "wr_cmp",
+          [](std::vector<size_t> const& levels, Word const& x, Word const& y) {
+            return wr_cmp(levels, x, y);
+          },
+          py::arg("levels"),
+          py::arg("x"),
+          py::arg("y"),
+          R"pbdoc(
+:sig=(levels: list[int], x: str | list[int], y: str | list[int]) -> bool:
+:only-document-once:
+Compare two words using wreath-product ordering.
+
+The *i*-th entry of *levels* is the level assigned to generator *i*.
+Differences at higher levels dominate differences at lower levels, and
+differences within one level are compared using len-lex ordering.
+
+:param levels: the level assigned to each generator.
+:type levels: list[int]
+:param x: the first word.
+:type x: str | list[int]
+:param y: the second word.
+:type y: str | list[int]
+:returns: Whether *x* is less than *y*.
+:rtype: bool
+
+:raises LibsemigroupsError: if a letter is not a valid index into *levels*.
+
+.. doctest:: python
+
+  >>> from libsemigroups_pybind11 import wr_cmp
+  >>> levels = [1, 1, 0]
+  >>> wr_cmp(levels, [2, 1, 2, 2], [2, 2, 1, 2])
+  True
+)pbdoc");
+
+      m.def(
+          "wr_cmp",
+          [](Alphabet<Word> const&      alphabet,
+             std::vector<size_t> const& levels,
+             Word const&                x,
+             Word const& y) { return wr_cmp(alphabet, levels, x, y); },
+          py::arg("alphabet"),
+          py::arg("levels"),
+          py::arg("x"),
+          py::arg("y"),
+          R"pbdoc(
+:sig=(alphabet: Alphabet, levels: list[int], x: str | list[int], y: str | list[int]) -> bool:
+:only-document-once:
+Compare two words using alphabet-aware wreath-product ordering.
+
+Letters are mapped to their positions in *alphabet*, and the *i*-th entry of
+*levels* is the level assigned to the *i*-th letter of *alphabet*.
+Differences at higher levels dominate differences at lower levels, and
+differences within one level are compared using len-lex ordering.
+
+:param alphabet: the ordered alphabet containing the letters of both words.
+:type alphabet: Alphabet
+:param levels: the level assigned to each letter of *alphabet*.
+:type levels: list[int]
+:param x: the first word.
+:type x: str | list[int]
+:param y: the second word.
+:type y: str | list[int]
+:returns: Whether *x* is less than *y*.
+:rtype: bool
+
+:raises LibsemigroupsError: if a letter does not belong to *alphabet*, or its
+  position in *alphabet* is not a valid index into *levels*.
+
+.. doctest:: python
+
+  >>> from libsemigroups_pybind11 import Alphabet, wr_cmp
+  >>> alphabet = Alphabet("bac")
+  >>> levels = [1, 1, 0]
+  >>> wr_cmp(alphabet, levels, "cbcc", "ccbc")
+  True
+)pbdoc");
     }
   }  // namespace
 
@@ -322,7 +402,7 @@ respectively, in new code.
 
     The recursive-path ordering, as described in :cite:`Jantzen2012aa`
     (Definition 1.2.14, page 24).
-  
+
     This is deprecated; use :any:`Order.rpo` instead.
 )pbdoc")
         .value("none", Order::none)

src/present.cpp

@@ -1581,18 +1581,16 @@ modified version.
       * :any:`is_strongly_compressible`
 
 )pbdoc");
-
       m.def(
           "presentation_to_gap_string",
           [](Presentation_ const& p, std::string const& var_name) {
             return presentation::to_gap_string(p, var_name);
           },
           py::arg("p"),
-          py::arg("var_name") = "S",
+          py::arg("var_name"),
           R"pbdoc(
 :sig=(p: Presentation, var_name: str) -> str:
 :only-document-once:
-
 Return the code that would create *p* in GAP.
 
 This function returns the string of GAP code that could be used to create an
@@ -1602,26 +1600,12 @@ are created by taking quotients of free semigroups or monoids.
 :param p: the presentation.
 :type p: Presentation
 
-:param var_name: the name of the variable to be used in GAP (defaults to ``"S"``).
+:param var_name: the name of the variable to be used in GAP.
 :type var_name: str
 
 :returns: The GAP string.
 :rtype: str
-
-.. doctest::
-
-    >>> from libsemigroups_pybind11 import Presentation, presentation
-    >>> p = Presentation("ab")
-    >>> presentation.add_rule(p, "ab", "ba")
-    >>> print(presentation.to_gap_string(p), end="")
-    F := FreeSemigroup("a", "b");
-    AssignGeneratorVariables(F);;
-    R := [
-           [a * b, b * a]
-         ];
-    S := F / R;
 )pbdoc");
-
       m.def(
           "presentation_to_ace_string",
           [](Presentation_ const& p) { return presentation::to_ace_string(p); },

src/schreier-sims.cpp

@@ -78,14 +78,11 @@ the list *gens*.
       for this class, or the number of generators exceeds the maximum capacity.
 )pbdoc");
 
-      thing.def("__copy__", [](SchreierSims_ const& self) {
-        return std::make_unique<SchreierSims_>(self);
-      });
+      thing.def("__copy__",
+                [](SchreierSims_ const& self) { return SchreierSims_(self); });
       thing.def(
           "copy",
-          [](SchreierSims_ const& self) {
-            return std::make_unique<SchreierSims_>(self);
-          },
+          [](SchreierSims_ const& self) { return SchreierSims_(self); },
           R"pbdoc(
 :sig=(self: SchreierSims) -> SchreierSims:
 

tests/test_order.py

@@ -19,6 +19,7 @@
     rev_rpo_cmp,
     rpo_cmp,
     shortlex_compare,
+    wr_cmp,
 )
 
 
@@ -73,3 +74,31 @@ def test_deprecated_comparisons(old_compare, new_compare):
     with pytest.deprecated_call():
         result = old_compare("ab", "ba")
     assert result == new_compare("ab", "ba")
+
+
+def test_wr_cmp_for_integer_words():
+    """Check wreath-product comparison, validation, and its unchecked form."""
+    levels = [0, 0, 1]
+    x = [0, 2]
+    y = [1, 2]
+
+    assert wr_cmp(levels, x, y)
+    assert not wr_cmp(levels, y, x)
+
+    with pytest.raises(LibsemigroupsError):
+        wr_cmp([0, 1], [0, 2], [0, 1])
+
+
+def test_wr_cmp_with_alphabet():
+    """Check wreath-product comparison over an explicitly ordered alphabet."""
+    alphabet = Alphabet("bac")
+    levels = [1, 1, 0]
+
+    assert wr_cmp(alphabet, levels, "cbcc", "ccbc")
+    assert wr_cmp(alphabet, levels, "ac", "ca")
+
+    word_alphabet = Alphabet([1, 0])
+    assert wr_cmp(word_alphabet, [0, 0], [1], [0])
+
+    with pytest.raises(LibsemigroupsError):
+        wr_cmp(alphabet, levels, "d", "b")

tests/test_present.py

@@ -819,38 +819,6 @@ def check_to_ace_string(W):
     )
 
 
-def check_to_gap_string(W):
-    p = Presentation(W([0, 1]))
-    presentation.add_rule(p, W([0, 1]), W([1, 0]))
-
-    a, b = ("s0", "s1") if W is to_word else ("a", "b")
-    assert (
-        presentation.to_gap_string(p)
-        == f"""F := FreeSemigroup("{a}", "{b}");
-AssignGeneratorVariables(F);;
-R := [
-       [{a} * {b}, {b} * {a}]
-     ];
-S := F / R;
-"""
-    )
-
-    a, b = ("m0", "m1") if W is to_word else ("a", "b")
-    p.contains_empty_word(True)
-    presentation.add_rule(p, W([0, 0]), W([]))
-    assert (
-        presentation.to_gap_string(p, "M")
-        == f"""F := FreeMonoid("{a}", "{b}");
-AssignGeneratorVariables(F);;
-R := [
-       [{a} * {b}, {b} * {a}],
-       [{a} * {a}, One(F)]
-     ];
-M := F / R;
-"""
-    )
-
-
 ###############################################################################
 # Test functions begin
 ###############################################################################
@@ -1812,8 +1780,3 @@ def test_add_idempotent_rules():
 def test_to_ace_string():
     check_to_ace_string(to_word)
     check_to_ace_string(to_string)
-
-
-def test_to_gap_string():
-    check_to_gap_string(to_word)
-    check_to_gap_string(to_string)