presentation: add to_ace_string

Author: Joseph-Edwards

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

@@ -77,6 +77,7 @@ Contents
     sort_rules
     strongly_compress
     throw_if_bad_inverses
+    to_ace_string
     to_gap_string
     try_detect_inverses
 

src/libsemigroups_pybind11/presentation/__init__.py

@@ -56,6 +56,7 @@
     presentation_sort_rules as _sort_rules,
     presentation_strongly_compress as _strongly_compress,
     presentation_throw_if_bad_inverses as _throw_if_bad_inverses,
+    presentation_to_ace_string as _to_ace_string,
     presentation_to_gap_string as _to_gap_string,
     presentation_try_detect_inverses as _try_detect_inverses,
 )
@@ -272,6 +273,7 @@ def __init__(self: _Self, *args, **kwargs) -> None:
 sort_rules = _wrap_cxx_free_fn(_sort_rules)
 strongly_compress = _wrap_cxx_free_fn(_strongly_compress)
 throw_if_bad_inverses = _wrap_cxx_free_fn(_throw_if_bad_inverses)
+to_ace_string = _wrap_cxx_free_fn(_to_ace_string)
 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)
@@ -321,6 +323,7 @@ def __init__(self: _Self, *args, **kwargs) -> None:
     "sort_rules",
     "strongly_compress",
     "throw_if_bad_inverses",
+    "to_ace_string",
     "to_gap_string",
     "balance",
     "add_cyclic_conjugates",

src/present.cpp

@@ -1605,6 +1605,38 @@ are created by taking quotients of free semigroups or monoids.
 
 :returns: The GAP string.
 :rtype: str
+)pbdoc");
+      m.def(
+          "presentation_to_ace_string",
+          [](Presentation_ const& p) { return presentation::to_ace_string(p); },
+          py::arg("p"),
+          R"pbdoc(
+:sig=(p: Presentation) -> str:
+:only-document-once:
+Return the code that would create a presentation to be used with ACE.
+
+This function returns the string of ACE input that could be used to create an
+object with the same alphabet and rules as *p*.
+
+:param p: the presentation.
+:type p: Presentation
+
+:returns: The ACE string.
+:rtype: str
+
+:raises LibsemigroupsError: if ``p.alphabet()`` contains any duplicate letters.
+:raises LibsemigroupsError: if any of the letters in the alphabet of
+  *p* are not lowercase, or do not correspond to a lowercase letter when
+  transformed to a string using :any:`words.human_readable_letter`.
+
+.. note::
+
+  ACE assumes that presentations are group presentations, where the the alphabet
+  consists of lowercase letters, and inverses correspond to the equivalent
+  uppercase letters. Therefore, a valid ACE presentation may not be a valid
+  libsemigroups presentation; for example, it is possible for relations in an
+  ACE presentation to contain uppercase letters that are not explicitly named as
+  generators, as long as their lowercase counterparts are listed as generators.
 )pbdoc");
       m.def(
           "presentation_throw_if_bad_inverses",

tests/test_present.py

@@ -803,6 +803,22 @@ def letter(x):
         p.remove_generator(letter(11))
 
 
+def check_to_ace_string(W):
+    p = Presentation(W([0, 1]))
+    p.contains_empty_word(True)
+    presentation.add_rule(p, W([0, 0]), W([]))
+    presentation.add_rule(p, W([1, 1, 1]), W([]))
+    presentation.add_rule(p, W([0, 1, 0, 1]), W([]))
+    assert (
+        presentation.to_ace_string(p)
+        == """Group: a, b;
+wo: 4g; # workspace size, adjust as necessary
+Rel: aa, bbb, abab;
+Mess: 100000; # message frequency, adjust as necessary
+End;"""
+    )
+
+
 ###############################################################################
 # Test functions begin
 ###############################################################################
@@ -1759,3 +1775,8 @@ def test_add_involution_rules():
 def test_add_idempotent_rules():
     check_add_idempotent_rules(to_word)
     check_add_idempotent_rules(to_string)
+
+
+def test_to_ace_string():
+    check_to_ace_string(to_word)
+    check_to_ace_string(to_string)