Update to libsemigroups v3.4.0 and add features introduced there

.gitignore

@@ -1,22 +1,25 @@
+_build
+_generate
+.cache
+.ccls
+.coverage
+.DS_Store
 *.aux
 *.ccls-cache
 *.egg-info
+*.fdb_latexmk
+*.fls
 *.gv
 *.log
 *.pdf
 *.py[cod]
 *.so
 *.whl
-.DS_Store
-.cache
-.ccls
-.coverage
-compile_commands.json
-MANIFEST
-_build
-_generate
 build
+compile_commands.json
 coverage.xml
+docs/pictures/to-table.synctex.gz
 gh-pages/
 htmlcov
+MANIFEST
 src/libsemigroups_pybind11/_version.py

build_tools/__init__.py

@@ -11,4 +11,4 @@ def minimum_libsemigroups_version():
     """Returns the minimum required version of libsemigroups required to build
     libsemigroups_pybind11.
     """
-    return "3.3.0"
+    return "3.4.0"

docs/pictures/to-table.tex

@@ -20,29 +20,40 @@
   \rotatebox{90}{\texttt{Presentation}}          &
   \rotatebox{90}{\texttt{SchreierSims}}          &
   \rotatebox{90}{\texttt{Stephen}}               &
-  \rotatebox{90}{\texttt{ToddCoxeter}}
+  \rotatebox{90}{\texttt{ToddCoxeter}}           &
+  \rotatebox{90}{\texttt{WordGraph}}
   \\
   \midrule
   \texttt{to(*args, rtype=Congruence)}          & \xmark & \cmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \cmark \\\hline
   \texttt{to(*args, rtype=FroidurePin)}         & \cmark & \xmark &
-  \xmark & \cmark & \cmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
+  \xmark & \cmark & \cmark & \xmark & \xmark & \xmark & \xmark & \cmark
+  & \cmark \\\hline
   \texttt{to(*args, rtype=InversePresentation)} & \xmark & \xmark &
-  \cmark & \xmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
+  \cmark & \xmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=Kambites)}            & \xmark & \xmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=KnuthBendix)}         & \xmark & \cmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \cmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=Konieczny)}           & \xmark & \xmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=Presentation)}        & \cmark & \cmark &
-  \xmark & \cmark & \cmark & \xmark & \cmark & \xmark & \cmark & \cmark \\\hline
+  \xmark & \cmark & \cmark & \xmark & \cmark & \xmark & \cmark & \cmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=SchreierSims)}        & \xmark & \xmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=Stephen)}             & \xmark & \xmark &
-  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
+  \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \xmark \\\hline
   \texttt{to(*args, rtype=ToddCoxeter)}         & \xmark & \cmark &
-  \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark \\
+  \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark
+  & \xmark \\
 \end{tabular}
 % \cmark = implemented, \xmark = not yet implemented, -
 % = not applicable

docs/source/data-structures/presentations/to-inverse-present.rst

@@ -22,8 +22,8 @@ using the :any:`to` function.
 Various uses
 ------------
 
-Recall that the signature for the :any:`to` function is ``to(*args, Return)``.
-In what follows, we explain how different values of *args* and *Return* may be
+Recall that the signature for the :any:`to` function is ``to(*args, rtype)``.
+In what follows, we explain how different values of *args* and *rtype* may be
 used to construct :any:`InversePresentation` objects. The following options are
 possible:
 
@@ -41,7 +41,7 @@ the following values for *args*:
 
     - **p** (:any:`Presentation`) -- the :any:`Presentation` to convert.
 
-Additionally, specify the following for *Return*:
+Additionally, specify the following for *rtype*:
 
     - ``(InversePresentation,)`` for constructing an :any:`InversePresentation`
       over words of the same type as those in *p*.
@@ -92,22 +92,22 @@ specify the following values for *args*:
     - **ip** (:any:`InversePresentation`) -- the :any:`InversePresentation` to
       convert.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(InversePresentation, str)`` for constructing an
     - :any:`InversePresentation` over words of type ``str``.
     - ``(InversePresentation, list[int])`` for constructing an
       :any:`InversePresentation` over words of type ``list[int]``.
 
 This function behaves in one of two ways, depending on type of words in *p*, and
-the type of words specified in *Return*:
+the type of words specified in *rtype*:
 
-    1. When the type of words in *ip* and type of words specified in *Return*
+    1. When the type of words in *ip* and type of words specified in *rtype*
        are not the same, this function returns an :any:`InversePresentation`
        equivalent to the input :any:`InversePresentation` *ip* but with words a
        different type (for example, can be used to convert from ``str`` to
        ``list[int]``).
-    2. When the type of words in *ip* and type of words specified in *Return*
+    2. When the type of words in *ip* and type of words specified in *rtype*
        are the same, this function just returns its argument *ip*, and is
        included solely for the purpose of simplifying certain client code, where
        objects of type :any:`InversePresentation` must be converted from one
@@ -120,7 +120,7 @@ of type ``list[int]``, then the conversion from one type to another is
 :math:`a_i \mapsto` ``human_readable_letter(a_i)``.
 
 This function throws a :any:`LibsemigroupsError` if the type of words in *ip* is
-not the same as that specified in *Return* and
+not the same as that specified in *rtype* and
 ``p.throw_if_bad_alphabet_rules_or_inverses()`` throws.
 
 .. seealso::
@@ -164,7 +164,7 @@ using a custom letter conversion function, specify the following values for
     - **f** (``Callable[[str | int], int | str]``) -- the function used to
       convert between the different types of letters.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(InversePresentation, str)`` for constructing an
       :any:`InversePresentation` over words of type ``str``.
@@ -180,7 +180,7 @@ to the other.
 This function throws a :any:`LibsemigroupsError` if
 ``ip.throw_if_bad_alphabet_rules_or_inverses()`` throws, or if the function
 specified by *f* does not map letters of the type used in *ip* to letters of the
-type of word specified in *Return*.
+type of word specified in *rtype*.
 
 .. seealso::
 

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

@@ -22,8 +22,8 @@ This page contains documentation relating to converting
 Various uses
 ------------
 
-Recall that the signature for the :any:`to` function is ``to(*args, Return)``.
-In what follows, we explain how different values of *args* and *Return* may be
+Recall that the signature for the :any:`to` function is ``to(*args, rtype)``.
+In what follows, we explain how different values of *args* and *rtype* may be
 used to construct :any:`Presentation` objects. The following options are
 possible:
 
@@ -46,21 +46,21 @@ following values for *args*:
 
     - **p** (:any:`Presentation`) -- the :any:`Presentation` to convert.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation, str)`` for constructing a :any:`Presentation` over words
       of type ``str``.
     - ``(Presentation, list[int])`` for constructing a :any:`Presentation` over
       words of type ``list[int]``.
 
 This function behaves in one of two ways, depending on type of words in *p*, and
-the type of words specified in *Return*:
+the type of words specified in *rtype*:
 
-    1. When the type of words in *p* and type of words specified in *Return* are
+    1. When the type of words in *p* and type of words specified in *rtype* are
        not the same, this function returns a :any:`Presentation` equivalent to
        the input :any:`Presentation` *p* but with words a different type (for
        example, can be used to convert from ``str`` to ``list[int]``).
-    2. When the type of words in *p* and type of words specified in *Return* are
+    2. When the type of words in *p* and type of words specified in *rtype* are
        the same, this function just returns its argument *p*, and is included
        solely for the purpose of simplifying certain client code, where
        presentations must be converted from one type to another sometimes, but
@@ -73,7 +73,7 @@ of type ``list[int]``, then the conversion from one type to another is
 :math:`a_i \mapsto` ``human_readable_letter(a_i)``.
 
 This function throws a :any:`LibsemigroupsError` if the type of words in *p* is
-not the same as that specified in *Return*, and
+not the same as that specified in *rtype*, and
 ``p.throw_if_bad_alphabet_or_rules()`` throws.
 
 .. seealso::
@@ -115,7 +115,7 @@ letter conversion function, specify the following values for *args*:
     - **f** (``Callable[[str | int], int | str]``) -- the function used to
       convert between the different types of letters.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation, str)`` for constructing a :any:`Presentation` over words
       of type ``str``.
@@ -131,7 +131,7 @@ other.
 This function throws a :any:`LibsemigroupsError` if
 ``p.throw_if_bad_alphabet_or_rules()`` throws, or if the function specified by
 *f* does not map letters of the type used in *p* to letters of the type of word
-specified in *Return*.
+specified in *rtype*.
 
 .. seealso::
 
@@ -169,7 +169,7 @@ following values for *args*:
     - **kb** (:any:`KnuthBendix`) -- the :any:`KnuthBendix` from which to obtain
       the rules.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation,)`` for constructing a :any:`Presentation` over words of 
       the same type as that in *kb*.
@@ -211,7 +211,7 @@ enumerates *kb*) prior to calling this function.
     >>> kb.run()
     >>> p2 = to(kb, rtype=(Presentation,))
     >>> for p in [p1, p2]:
-    ...     # Returns whether any changes have been made
+    ...     # rtypes whether any changes have been made
     ...     presentation.sort_each_rule(p)
     ...     presentation.sort_rules(p)
     True
@@ -230,7 +230,7 @@ following values for *args*:
     - **fp** (:any:`FroidurePin`) -- the :any:`FroidurePin` from which to obtain
       the rules.
 
-Additionally, specify the following for *Return*:
+Additionally, specify the following for *rtype*:
 
     - ``(Presentation, str)`` for constructing a :any:`Presentation` over words
       of type ``str``.
@@ -282,7 +282,7 @@ following values for *args*:
     - **k** (:any:`Kambites`) -- the :any:`Kambites` from which to obtain
       the presentation.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation,)`` for constructing a :any:`Presentation` over words of
       the same type as that in *k*.
@@ -342,7 +342,7 @@ following values for *args*:
     - **tc** (:any:`ToddCoxeter`) -- the :any:`ToddCoxeter` from which to obtain
       the presentation.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation,)`` for constructing a :any:`Presentation` over words of
       the same type as that in *tc*.
@@ -402,7 +402,7 @@ following values for *args*:
     - **c** (:any:`Congruence`) -- the :any:`Congruence` from which to obtain
       the presentation.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation,)`` for constructing a :any:`Presentation` over words of
       the same type as that in *c*.
@@ -463,7 +463,7 @@ following values for *args*:
     - **s** (:any:`Stephen`) -- the :any:`Stephen` from which to obtain
       the presentation.
 
-Additionally, specify one of the following for *Return*:
+Additionally, specify one of the following for *rtype*:
 
     - ``(Presentation,)`` for constructing a :any:`Presentation` over words of
       the same type as that in *s*.

docs/source/data-structures/to-function.rst

@@ -7,6 +7,10 @@
 
 .. currentmodule:: libsemigroups_pybind11
 
+.. |br| raw:: html
+
+       <br />
+
 The ``to`` function
 ===================
 
@@ -26,6 +30,7 @@ A summary of the possible conversions available in ``libsemigroups_pybind11`` of
     :align: center
     :alt: A table containing the possible conversions of libsemigroups_pybind11 types.
 
+|br|
 A tick indicates that this conversion is implemented, and a cross that it is not
 yet implemented.
 

docs/source/main-algorithms/congruence/to-cong.rst

@@ -22,11 +22,12 @@ This page contains documentation relating to converting
 Various uses
 ------------
 
-Recall that the signature for the :any:`to` function is ``to(*args, Return)``.
-In what follows, we explain how different values of *args* and *Return* may be
+Recall that the signature for the :any:`to` function is ``to(*args, rtype)``.
+In what follows, we explain how different values of *args* and *rtype* may be
 used to construct :any:`Congruence` objects. The following options are possible:
 
     - :ref:`froidure-pin-to-congruence`.
+    - :ref:`word-graph-to-congruence`.
 
 .. _froidure-pin-to-congruence:
 
@@ -37,12 +38,12 @@ To construct a :any:`Congruence` from a :any:`FroidurePin`, specify all of the
 following values for *args*:
 
     - **knd** (:any:`congruence_kind`) -- the kind of the congruence being
-      construed;
+      constructed;
     - **fpb** (:any:`FroidurePin`) -- the :any:`FroidurePin` instance to be
       converted; and
     - **wg** (:any:`WordGraph`) -- the left or right Cayley graph of *fpb*.
 
-Additionally, specify one of the following tuples for *Return*:
+Additionally, specify one of the following tuples for *rtype*:
 
     - ``(Congruence, str)`` for constructing a :any:`Congruence` on words of
       type ``str``; or
@@ -87,3 +88,48 @@ This will throw a :any:`LibsemigroupsError` if *wg* is not the
     >>> cong.run()
     >>> S.size() == cong.number_of_classes()
     True
+
+.. _word-graph-to-congruence:
+
+Converting a :any:`WordGraph` to a :any:`Congruence`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To construct a :any:`Congruence` from a :any:`WordGraph`, specify all of the
+following values for *args*:
+
+    - **knd** (:any:`congruence_kind`) -- the kind of the congruence being
+      constructed;
+    - **wg** (:any:`WordGraph`) -- the word graph.
+
+Additionally, specify one of the following tuples for *rtype*:
+
+    - ``(Congruence, str)`` for constructing a :any:`Congruence` on words of
+      type ``str``; or
+    - ``(Congruence, list[int])`` for constructing a :any:`Congruence` on words
+      of type ``list[int]``.
+
+This function converts the :any:`WordGraph` object *wg* into a
+:any:`Congruence` object. This returned :any:`Congruence` object represents the
+trivial congruence over the word graph *wg*.
+
+.. doctest:: Python
+
+    >>> from libsemigroups_pybind11 import (
+    ...     congruence_kind,
+    ...     Congruence,
+    ...     WordGraph,
+    ...     to,
+    ... )
+
+    >>> wg = WordGraph(7, [[1, 2], [1, 3], [4, 2], [5, 3], [4, 6], [5, 3], [4, 6]])
+    >>> cong = to(congruence_kind.twosided, wg, rtype=(Congruence, list[int]))
+    >>> cong.add_generating_pair([0], [1])
+    <1-sided Congruence over <semigroup presentation with 2 letters, 0 rules, and length 0> with 1 gen. pair, 1 runners>    
+    >>> cong.number_of_classes()
+    1
+
+    >>> cong = to(congruence_kind.twosided, wg, rtype=(Congruence, str))
+    >>> cong.add_generating_pair("a", "b")
+    <1-sided Congruence over <semigroup presentation with 2 letters, 0 rules, and length 0> with 1 gen. pair, 1 runners>    
+    >>> cong.number_of_classes()
+    1