Skip to content

Commit e02365f

Browse files
Joseph-Edwardsjames-d-mitchell
Joseph-Edwards
and
james-d-mitchell
authored
Add to function for FroidurePin (#216)
* Add to_froidure_pin * Correct copyright * Add EOF * Remove old init and constructor * Add more to_froidure_pin functions * Add to function * Add to function to docs * Add tests for to function * Add to for other rewriters * Add to_todd_coxeter * Add to_todd_coxeter to to function * Update cayley graph return value policy * Add to_todd_coxeter_string * Construct FroidurePin from FroidurePin (broken elements) * rename return_type -> Return * Add ToddCoxeter to to * Update tests * Add TODO * Add Presentation and InversePresentation in to function * Add tests for to (Inverse)Presentaiton * Remove to_presentation from docs * to_presentation.cpp -> to-presentation.cpp * Add to_knuth_bendix (incomplete) * Add to_knuth_bendix to to function * Update test names * Add to_knuth_bendix tests * Add to_congruence * Update includes * Use dictionary instead of big if statement * Add newline at end of file * Fix linting * Update to function doc * Add docs for to(Return=Congruence) * Remove reversible paths * Add stubs for to-Class documentation * Add doc for to-cong * Add doc for to-knuth-bendix * Add doc for to-todd-coxeter * Add doc for to-froidure-pin * Remove nested quotes from fstring * Remove backslash from f-string * Add docs for to-(inverse-)presentation * Doc tweaks * Add comment to tests * set ReportGuard(False) by default for doctest * Correct typos * Fix codespell * fix spelling Co-authored-by: James Mitchell <james-d-mitchell@users.noreply.github.com> * Add Element not implemented errors * Changes from review --------- Co-authored-by: James Mitchell <james-d-mitchell@users.noreply.github.com>
1 parent fc4d91a commit e02365f

35 files changed

+8982
-620
lines changed

‎docs/pictures/to-table.svg

Lines changed: 6105 additions & 0 deletions
Loading

‎docs/pictures/to-table.tex

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
\documentclass[png]{standalone}
2+
\usepackage{booktabs} % For professional tables
3+
\usepackage{pifont} % For check and cross symbols
4+
\usepackage{graphicx} % For rotating text
5+
\usepackage[table]{xcolor}
6+
7+
\newcommand{\cmark}{\cellcolor{green!25}\ding{51}} % Check mark
8+
\newcommand{\xmark}{\cellcolor{red!25}\ding{55}}
9+
10+
\begin{document}
11+
12+
\begin{tabular}{l|c|c|c|c|c|c|c|c|c|c|c}
13+
&
14+
\rotatebox{90}{\texttt{Congruence}} &
15+
\rotatebox{90}{\texttt{FroidurePin}} &
16+
\rotatebox{90}{\texttt{InversePresentation}} &
17+
\rotatebox{90}{\texttt{Kambites}} &
18+
\rotatebox{90}{\texttt{KnuthBendix}} &
19+
\rotatebox{90}{\texttt{Konieczny}} &
20+
\rotatebox{90}{\texttt{Presentation}} &
21+
\rotatebox{90}{\texttt{SchreierSims}} &
22+
\rotatebox{90}{\texttt{Stephen}} &
23+
\rotatebox{90}{\texttt{ToddCoxeter}}
24+
\\
25+
\midrule
26+
\texttt{to(*args, Return=Congruence)} & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
27+
\texttt{to(*args, Return=FroidurePin)} & \cmark & \xmark & \xmark & \cmark & \cmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
28+
\texttt{to(*args, Return=InversePresentation)} & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
29+
\texttt{to(*args, Return=Kambites)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
30+
\texttt{to(*args, Return=KnuthBendix)} & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
31+
\texttt{to(*args, Return=Konieczny)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
32+
\texttt{to(*args, Return=Presentation)} & \xmark & \cmark & \xmark & \xmark & \cmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
33+
\texttt{to(*args, Return=SchreierSims)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
34+
\texttt{to(*args, Return=Stephen)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
35+
\texttt{to(*args, Return=ToddCoxeter)} & \xmark & \cmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark \\
36+
\end{tabular}
37+
% \cmark = implemented, \xmark = not yet implemented, -
38+
% = not applicable
39+
\end{document}

‎docs/source/conf.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,9 @@ def no_doc_run(self):
142142

143143
autoclass_content = "both"
144144

145+
doctest_global_setup = """from libsemigroups_pybind11 import ReportGuard
146+
ReportGuard(False)"""
147+
145148
# This dictionary should be of the form "bad type" -> "good type", and
146149
# replacements will be performed globally. Hyperlinks will be added in the
147150
# signature if "good type" is a valid (potentially user defined) python type

‎docs/source/data-structures/presentations/index.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,10 @@ semigroups and monoids are:
3939

4040
.. toctree::
4141
:maxdepth: 1
42-
42+
4343
present
4444
inverse-present
4545
present-helpers
4646
examples
47-
to-presentation
47+
to-present
48+
to-inverse-present

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

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. Copyright (c) 2025 Joseph Edwards
2+
3+
Distributed under the terms of the GPL license version 3.
4+
5+
The full license is in the file LICENSE, distributed with this software.
6+
7+
.. currentmodule:: libsemigroups_pybind11
8+
9+
Converting to an InversePresentationStrings
10+
===========================================
11+
12+
This page contains documentation relating to converting
13+
``libsemigroups_pybind11`` objects into :any:`InversePresentationStrings`
14+
instances using the :any:`to` function.
15+
16+
.. seealso::
17+
18+
:doc:`/data-structures/to-function` for an overview of possible conversions
19+
between ``libsemigroups_pybind11`` types.
20+
21+
Various uses
22+
------------
23+
24+
Recall that the signature for the :any:`to` function is ``to(*args, Return)``.
25+
In what follows, we explain how different values of *args* and *Return* may
26+
be used to construct :any:`InversePresentationStrings` objects. The following
27+
options are possible:
28+
29+
* :ref:`presentation-to-inverse-presentation`;
30+
* :ref:`inverse-presentation-to-inverse-presentation`; and
31+
* :ref:`inverse-presentation-and-function-to-inverse-presentation`.
32+
33+
.. _presentation-to-inverse-presentation:
34+
35+
Converting a :any:`PresentationStrings` to an :any:`InversePresentationStrings`
36+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
37+
38+
To construct an :any:`InversePresentationStrings` from a
39+
:any:`PresentationStrings`, specify the following values for *args*:
40+
41+
* **p** (:any:`PresentationStrings`) -- the :any:`PresentationStrings` to
42+
convert.
43+
44+
Additionally, specify the following for *Return*:
45+
46+
* ``InversePresentation`` for constructing an
47+
:any:`InversePresentationStrings` over words of the same type as those in
48+
*p*.
49+
50+
This function returns an :any:`InversePresentationStrings` with rules equivalent
51+
to those of the input :any:`PresentationStrings` *p*, but over a normalised
52+
alphabet. If the alphabet of *p* is :math:`\{a_0, a_1, \dots, a_{n-1}\}`, then
53+
the alphabet of the returned :any:`InversePresentationStrings` will be
54+
:math:`\{0, 1, \dots, n-1, n, \dots, 2n-1\}`, where the inverse of letter
55+
:math:`i` is the letter :math:`i + n\, (\text{mod }2n)`.
56+
57+
This function throws a :any:`LibsemigroupsError` if ``p.validate()`` throws.
58+
59+
.. seealso::
60+
61+
* :any:`PresentationStrings.validate`.
62+
63+
.. doctest:: Python
64+
65+
>>> from libsemigroups_pybind11 import (
66+
... InversePresentation,
67+
... presentation,
68+
... Presentation,
69+
... to,
70+
... )
71+
72+
>>> p = Presentation('abc')
73+
>>> presentation.add_rule(p, 'aaa', 'b')
74+
>>> presentation.add_rule(p, 'bac', 'cab')
75+
76+
>>> ip = to(p, Return=InversePresentation)
77+
>>> ip.alphabet()
78+
'abcdef'
79+
>>> ip.inverses()
80+
'defabc'
81+
>>> ip.rules == p.rules
82+
True
83+
84+
.. _inverse-presentation-to-inverse-presentation:
85+
86+
Converting an :any:`InversePresentationStrings` to an :any:`InversePresentationStrings`
87+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88+
89+
To construct an :any:`InversePresentationStrings` from an
90+
:any:`InversePresentationStrings`, specify the following values for *args*:
91+
92+
* **ip** (:any:`InversePresentationStrings`) -- the
93+
:any:`InversePresentationStrings` to convert.
94+
95+
Additionally, specify one of the following for *Return*:
96+
97+
* ``(InversePresentation, str)`` for constructing an
98+
* :any:`InversePresentationStrings` over words of type ``str``.
99+
* ``(InversePresentation, List[int])`` for constructing an
100+
:any:`InversePresentationStrings` over words of type ``List[int]``.
101+
102+
This function behaves in one of two ways, depending on type of words in *p*, and
103+
the type of words specified in *Return*:
104+
105+
#. When the type of words in *ip* and type of words specified in *Return*
106+
are not the same, this function returns an
107+
:any:`InversePresentationStrings` equivalent to the input
108+
:any:`InversePresentationStrings` *ip* but with words a different type
109+
(for example, can be used to convert from ``str`` to ``List[int]``).
110+
#. When the type of words in *ip* and type of words specified in *Return*
111+
are the same, this function just returns its argument *ip*, and is
112+
included solely for the purpose of simplifying certain client code, where
113+
objects of type :any:`InversePresentationStrings` must be converted from
114+
one type to another sometimes, but not other times.
115+
116+
If the alphabet of of *ip* is :math:`\{a_0, a_1, \dots a_{n-1}\}`, where each
117+
letter is of type ``str``, then the conversion from one type to another is
118+
:math:`a_i \mapsto` ``human_readable_index(a_i)``. Conversely, if each letter is
119+
of type ``List[int]``, then the conversion from one type to another is
120+
:math:`a_i \mapsto` ``human_readable_letter(a_i)``.
121+
122+
This function throws a :any:`LibsemigroupsError` if the type of words in *ip* is
123+
not the same as that specified in *Return* and ``p.validate()`` throws.
124+
125+
.. seealso::
126+
127+
* :any:`words.human_readable_index`;
128+
* :any:`words.human_readable_letter`; and
129+
* :any:`InversePresentationStrings.validate`.
130+
131+
.. doctest:: Python
132+
133+
>>> from typing import List
134+
>>> from libsemigroups_pybind11 import presentation, Presentation, to
135+
136+
>>> ip = InversePresentation('abc')
137+
>>> ip.inverses('cba')
138+
<inverse semigroup presentation with 3 letters, 0 rules, and length 0>
139+
>>> presentation.add_rule(ip, 'aaa', 'b')
140+
>>> presentation.add_rule(ip, 'bac', 'cab')
141+
142+
>>> ip == to(ip, Return=(InversePresentation, str))
143+
True
144+
145+
>>> iq = to(ip, Return=(InversePresentation, List[int]))
146+
>>> iq.alphabet()
147+
[0, 1, 2]
148+
>>> iq.inverses()
149+
[2, 1, 0]
150+
>>> iq.rules
151+
[[0, 0, 0], [1], [1, 0, 2], [2, 0, 1]]
152+
153+
.. _inverse-presentation-and-function-to-inverse-presentation:
154+
155+
Converting an :any:`InversePresentationStrings` to n :any:`InversePresentationStrings` with a function
156+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157+
158+
To construct a :any:`InversePresentationStrings` from a
159+
:any:`InversePresentationStrings` using a custom letter conversion function,
160+
specify the following values for *args*:
161+
162+
* **ip** (:any:`InversePresentationStrings`) -- the
163+
:any:`InversePresentationStrings` to convert.
164+
* **f** (``Callable[[str | int], int | str]``) -- the function used to
165+
convert between the different types of letters.
166+
167+
Additionally, specify one of the following for *Return*:
168+
169+
* ``(InversePresentation, str)`` for constructing an
170+
:any:`InversePresentationStrings` over words of type ``str``.
171+
* ``(InversePresentation, List[int])`` for constructing a
172+
:any:`InversePresentationStrings` over words of type ``List[int]``.
173+
174+
This function returns an :any:`InversePresentationStrings` equivalent to the
175+
input :any:`InversePresentationStrings` *ip* but over words with letters of a
176+
different type (for example, can be used to convert from :any:`str` to
177+
:any:`int`). The second parameter *f* specifies how to map the letters of one
178+
:any:`InversePresentationStrings` to the other.
179+
180+
This function throws a :any:`LibsemigroupsError` if ``ip.validate()`` throws, or
181+
if the function specified by *f* does not map letters of the type used in *ip*
182+
to letters of the type of word specified in *Return*.
183+
184+
.. seealso::
185+
186+
* :any:`InversePresentationStrings.validate`.
187+
188+
.. doctest:: Python
189+
190+
>>> from libsemigroups_pybind11 import (
191+
... InversePresentation,
192+
... presentation,
193+
... Presentation,
194+
... to,
195+
... )
196+
197+
>>> ip = InversePresentation('abc')
198+
>>> ip.inverses('cba')
199+
<inverse semigroup presentation with 3 letters, 0 rules, and length 0>
200+
>>> presentation.add_rule(ip, 'aaa', 'b')
201+
>>> presentation.add_rule(ip, 'bac', 'cab')
202+
203+
>>> iq = to(
204+
... ip, # ip
205+
... lambda x: chr(ord(x) + 11), # f
206+
... Return=(InversePresentation, str)
207+
... )
208+
>>> iq.alphabet()
209+
'lmn'
210+
>>> iq.inverses()
211+
'nml'
212+
>>> iq.rules
213+
['lll', 'm', 'mln', 'nlm']

0 commit comments

Comments
 (0)