to-inverse-present.rst

.. currentmodule:: libsemigroups_pybind11

Converting to an InversePresentation

This page contains documentation relating to converting libsemigroups_pybind11 objects into :any:`InversePresentation` instances using the :any:`to` function.

.. seealso::

    :doc:`/data-structures/to-function` for an overview of possible conversions
    between ``libsemigroups_pybind11`` types.

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 used to construct :any:`InversePresentation` objects. The following options are possible:

• :ref:`presentation-to-inverse-presentation`;
• :ref:`inverse-presentation-to-inverse-presentation`; and
• :ref:`inverse-presentation-and-function-to-inverse-presentation`.

Converting a :any:`Presentation` to an :any:`InversePresentation`

To construct an :any:`InversePresentation` from a :any:`Presentation`, specify the following values for args:

• p (:any:`Presentation`) -- the :any:`Presentation` to convert.

Additionally, specify the following for Return:

• (InversePresentation,) for constructing an :any:`InversePresentation` over words of the same type as those in p.

This function returns an :any:`InversePresentation` with rules equivalent to those of the input :any:`Presentation` p, but over a normalised alphabet. If the alphabet of p is \{a_0, a_1, \dots, a_{n-1}\}, then the alphabet of the returned :any:`InversePresentation` will be \{0, 1, \dots, n-1, n, \dots, 2n-1\}, where the inverse of letter i is the letter i + n\, (\text{mod }2n).

This function throws a :any:`LibsemigroupsError` if p.throw_if_bad_alphabet_or_rules() throws.

.. seealso::

    - :any:`Presentation.throw_if_bad_alphabet_or_rules`.

>>> from libsemigroups_pybind11 import (
...     InversePresentation,
...     presentation,
...     Presentation,
...     to,
... )

>>> p = Presentation('abc')
>>> presentation.add_rule(p, 'aaa', 'b')
>>> presentation.add_rule(p, 'bac', 'cab')

>>> ip = to(p, Return=(InversePresentation,))
>>> ip.alphabet()
'abcdef'
>>> ip.inverses()
'defabc'
>>> ip.rules == p.rules
True

Converting an :any:`InversePresentation` to an :any:`InversePresentation`

To construct an :any:`InversePresentation` from an :any:`InversePresentation`, specify the following values for args:

• ip (:any:`InversePresentation`) -- the :any:`InversePresentation` to convert.

Additionally, specify one of the following for Return:

• (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:

1. When the type of words in ip and type of words specified in Return 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 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 type to another sometimes, but not other times.

If the alphabet of of ip is \{a_0, a_1, \dots a_{n-1}\}, where each letter is of type str, then the conversion from one type to another is a_i \mapsto human_readable_index(a_i). Conversely, if each letter is of type List[int], then the conversion from one type to another is 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 p.throw_if_bad_alphabet_rules_or_inverses() throws.

.. seealso::

    - :any:`words.human_readable_index`;
    - :any:`words.human_readable_letter`; and
    - :any:`InversePresentation.throw_if_bad_alphabet_rules_or_inverses`.

>>> from typing import List
>>> from libsemigroups_pybind11 import presentation, Presentation, to

>>> ip = InversePresentation('abc')
>>> ip.inverses('cba')
<inverse semigroup presentation with 3 letters, 0 rules, and length 0>
>>> presentation.add_rule(ip, 'aaa', 'b')
>>> presentation.add_rule(ip, 'bac', 'cab')

>>> ip == to(ip, Return=(InversePresentation, str))
True

>>> iq = to(ip, Return=(InversePresentation, List[int]))
>>> iq.alphabet()
[0, 1, 2]
>>> iq.inverses()
[2, 1, 0]
>>> iq.rules
[[0, 0, 0], [1], [1, 0, 2], [2, 0, 1]]

Converting an :any:`InversePresentation` to n :any:`InversePresentation` with a function

To construct a :any:`InversePresentation` from a :any:`InversePresentation` using a custom letter conversion function, specify the following values for args:

• ip (:any:`InversePresentation`) -- the :any:`InversePresentation` to convert.
• 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:

• (InversePresentation, str) for constructing an :any:`InversePresentation` over words of type str.
• (InversePresentation, List[int]) for constructing a :any:`InversePresentation` over words of type List[int].

This function returns an :any:`InversePresentation` equivalent to the input :any:`InversePresentation` ip but over words with letters of a different type (for example, can be used to convert from :any:`str` to :any:`int`). The second parameter f specifies how to map the letters of one :any:`InversePresentation` 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.

.. seealso::

    - :any:`InversePresentation.throw_if_bad_alphabet_rules_or_inverses`.

>>> from libsemigroups_pybind11 import (
...     InversePresentation,
...     presentation,
...     Presentation,
...     to,
... )

>>> ip = InversePresentation('abc')
>>> ip.inverses('cba')
<inverse semigroup presentation with 3 letters, 0 rules, and length 0>
>>> presentation.add_rule(ip, 'aaa', 'b')
>>> presentation.add_rule(ip, 'bac', 'cab')

>>> iq = to(
...     ip,                                 # ip
...     lambda x: chr(ord(x) + 11),         # f
...     Return=(InversePresentation, str)
... )
>>> iq.alphabet()
'lmn'
>>> iq.inverses()
'nml'
>>> iq.rules
['lll', 'm', 'mln', 'nlm']