Converting to a Presentation

This page contains documentation relating to converting libsemigroups_pybind11 objects into Presentation instances using the to function.

See also

The to function for an overview of possible conversions between libsemigroups_pybind11 types.

Various uses

Recall that the signature for the to function is to(*args, Return). In what follows, we explain how different values of args and Return may be used to construct Presentation objects. The following options are possible:

• Converting a Presentation to a Presentation;

• Converting a Presentation to a Presentation with a function;

• Converting a KnuthBendix to a Presentation;

• Converting a FroidurePin to a Presentation;

• Converting a Kambites to a Presentation;

• Converting a ToddCoxeter to a Presentation;

• Converting a Congruence to a Presentation; and

• Converting a Stephen to a Presentation.

Converting a Presentation to a Presentation

To construct a Presentation from a Presentation, specify the following values for args:

• p (Presentation) – the Presentation to convert.

Additionally, specify one of the following for Return:

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a 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:

1. When the type of words in p and type of words specified in Return are not the same, this function returns a Presentation equivalent to the input 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 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 not other times.

If the alphabet of of p 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 LibsemigroupsError if the type of words in p is not the same as that specified in Return, and p.throw_if_bad_alphabet_or_rules() throws.

See also

• words.human_readable_index;

• words.human_readable_letter; and

• Presentation.throw_if_bad_alphabet_or_rules.

>>> from libsemigroups_pybind11 import presentation, Presentation, to

>>> p = Presentation('abcdef')
>>> presentation.add_zero_rules(p, 'e')
>>> p.rules
['ae', 'e', 'ea', 'e', 'be', 'e', 'eb', 'e', 'ce', 'e', 'ec', 'e', 'de', 'e', 'ed', 'e', 'ee', 'e', 'fe', 'e', 'ef', 'e']

>>> p == to(p, rtype=(Presentation, str))
True

>>> q = to(p, rtype=(Presentation, list[int]))
>>> q.alphabet()
[0, 1, 2, 3, 4, 5]
>>> q.rules
[[0, 4], [4], [4, 0], [4], [1, 4], [4], [4, 1], [4], [2, 4], [4], [4, 2], [4], [3, 4], [4], [4, 3], [4], [4, 4], [4], [5, 4], [4], [4, 5], [4]]

>>> p == to(q, rtype=(Presentation, str))
True

Converting a Presentation to a Presentation with a function

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

• p (Presentation) – the Presentation 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:

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function returns a Presentation equivalent to the input Presentation p but over words with letters of a different type (for example, can be used to convert from str to int). The second parameter f specifies how to map the letters of one Presentation to the other.

This function throws a 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.

See also

• Presentation.throw_if_bad_alphabet_or_rules.

>>> from libsemigroups_pybind11 import presentation, Presentation, to

>>> p = Presentation([0, 2, 4, 6])
>>> presentation.add_zero_rules(p, 4)
>>> p.rules
[[0, 4], [4], [4, 0], [4], [2, 4], [4], [4, 2], [4], [4, 4], [4], [6, 4], [4], [4, 6], [4]]

>>> double = lambda x: 2*x

>>> q = to(
...    p,                               # p
...    double,                          # f
...    rtype=(Presentation, list[int])
... )
>>> q.alphabet()
[0, 4, 8, 12]
>>> q.rules
[[0, 8], [8], [8, 0], [8], [4, 8], [8], [8, 4], [8], [8, 8], [8], [12, 8], [8], [8, 12], [8]]

Converting a KnuthBendix to a Presentation

To construct a Presentation from a KnuthBendix, specify the following values for args:

• kb (KnuthBendix) – the KnuthBendix from which to obtain the rules.

Additionally, specify one of the following for Return:

• (Presentation,) for constructing a Presentation over words of the same type as that in kb.

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int] for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object using the currently active rules of kb.

No enumeration of the argument kb is performed, so it might be the case that the resulting Presentation does not define the same semigroup/monoid as kb. To ensure that the resulting Presentation defines the same semigroup/monoid as kb, run kb.run() (or any other function that fully enumerates kb) prior to calling this function.

See also

• KnuthBendix.active_rules; and

• Runner.run.

>>> from libsemigroups_pybind11 import (
...     congruence_kind,
...     KnuthBendix,
...     Presentation,
...     presentation,
...     to,
... )

>>> p1 = Presentation([0, 1])
>>> presentation.add_rule(p1, [0, 1], [1, 0])
>>> presentation.add_rule(p1, [0, 0], [0])
>>> presentation.add_rule(p1, [1, 1], [1])

>>> kb = KnuthBendix(congruence_kind.twosided, p1)
>>> kb.run()
>>> p2 = to(kb, rtype=(Presentation,))
>>> for p in [p1, p2]:
...     # Returns whether any changes have been made
...     presentation.sort_each_rule(p)
...     presentation.sort_rules(p)
True
False
>>> p1 == p2
True

Converting a FroidurePin to a Presentation

To construct a Presentation from a FroidurePin, specify the following values for args:

• fp (FroidurePin) – the FroidurePin from which to obtain the rules.

Additionally, specify the following for Return:

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object using the rules of a FroidurePin object.

No enumeration of the argument fp is performed, so it might be the case that the resulting Presentation does not define the same semigroup as fp. To ensure that the resulting Presentation defines the same semigroup as fp, run fp.run() (or any other function that fully enumerates fp) prior to calling this function.

See also

• froidure_pin.rules; and

• Runner.run.

>>> from libsemigroups_pybind11 import (
...     Bipartition,
...     FroidurePin,
...     Presentation,
...     presentation,
...     to,
... )

>>> b1 = Bipartition([[1, -1], [2, -2], [3, -3], [4, -4]])
>>> b2 = Bipartition([[1, -2], [2, -3], [3, -4], [4, -1]])
>>> b3 = Bipartition([[1, -2], [2, -1], [3, -3], [4, -4]])
>>> b4 = Bipartition([[1, 2], [3, -3], [4, -4], [-1, -2]])
>>> S = FroidurePin(b1, b2, b3, b4)

>>> p = to(S, rtype=(Presentation, str))
>>> len(p.alphabet()) == 4
True

Converting a Kambites to a Presentation

To construct a Presentation from a Kambites, specify the following values for args:

• k (Kambites) – the Kambites from which to obtain the presentation.

Additionally, specify one of the following for Return:

• (Presentation,) for constructing a Presentation over words of the same type as that in k.

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object that is equivalent to the presentation used to construct the Kambites object. When the word type matches, this function returns a reference to k.presentation(). When the word types differ, a converted copy is returned.

No computation is performed by this function; it simply retrieves the presentation that was used to define the Kambites object.

See also

• Kambites.presentation.

>>> from libsemigroups_pybind11 import (
...     congruence_kind,
...     Kambites,
...     Presentation,
...     presentation,
...     to,
... )

>>> p = Presentation([5, 6, 7, 8, 9])
>>> presentation.add_rule(p, [5, 6], [7])
>>> presentation.add_rule(p, [6, 7], [8])
>>> presentation.add_rule(p, [7, 8], [9])
>>> presentation.add_rule(p, [8, 9], [5])
>>> presentation.add_rule(p, [9, 5], [6])

>>> k = Kambites(congruence_kind.twosided, p)
>>> result = to(k, rtype=(Presentation, list[int]))
>>> result == p
True

>>> result_str = to(k, rtype=(Presentation, str))
>>> result_str.alphabet()
'abcde'
>>> result_str.rules
['ab', 'c', 'bc', 'd', 'cd', 'e', 'de', 'a', 'ea', 'b']

Converting a ToddCoxeter to a Presentation

To construct a Presentation from a ToddCoxeter, specify the following values for args:

• tc (ToddCoxeter) – the ToddCoxeter from which to obtain the presentation.

Additionally, specify one of the following for Return:

• (Presentation,) for constructing a Presentation over words of the same type as that in tc.

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object that is equivalent to the presentation used to construct the ToddCoxeter object. When the word type matches, this function returns a reference to tc.presentation(). When the word types differ, a converted copy is returned.

No computation is performed by this function; it simply retrieves the presentation that was used to define the ToddCoxeter object.

See also

• ToddCoxeter.presentation.

>>> from libsemigroups_pybind11 import (
...     congruence_kind,
...     ToddCoxeter,
...     Presentation,
...     presentation,
...     to,
... )

>>> p = Presentation([5, 6, 7, 8, 9])
>>> presentation.add_rule(p, [5, 6], [7])
>>> presentation.add_rule(p, [6, 7], [8])
>>> presentation.add_rule(p, [7, 8], [9])
>>> presentation.add_rule(p, [8, 9], [5])
>>> presentation.add_rule(p, [9, 5], [6])

>>> tc = ToddCoxeter(congruence_kind.twosided, p)
>>> result = to(tc, rtype=(Presentation, list[int]))
>>> result == p
True

>>> result_str = to(tc, rtype=(Presentation, str))
>>> result_str.alphabet()
'abcde'
>>> result_str.rules
['ab', 'c', 'bc', 'd', 'cd', 'e', 'de', 'a', 'ea', 'b']

Converting a Congruence to a Presentation

To construct a Presentation from a Congruence, specify the following values for args:

• c (Congruence) – the Congruence from which to obtain the presentation.

Additionally, specify one of the following for Return:

• (Presentation,) for constructing a Presentation over words of the same type as that in c.

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object that is equivalent to the presentation used to construct the Congruence object. When the word type matches, this function returns a reference to c.presentation(). When the word types differ, a converted copy is returned.

No computation is performed by this function; it simply retrieves the presentation that was used to define the Congruence object. Note that any generating pairs added via Congruence.add_generating_pair are not included in the returned presentation.

See also

• Congruence.presentation; and

• Congruence.add_generating_pair.

>>> from libsemigroups_pybind11 import (
...     congruence_kind,
...     Congruence,
...     Presentation,
...     presentation,
...     to,
... )

>>> p = Presentation("abc")
>>> presentation.add_rule(p, "aa", "b")
>>> presentation.add_rule(p, "bb", "c")
>>> presentation.add_rule(p, "cc", "a")

>>> c = Congruence(congruence_kind.twosided, p)
>>> result = to(c, rtype=(Presentation, str))
>>> result == p
True

>>> result_word = to(c, rtype=(Presentation, list[int]))
>>> result_word.alphabet()
[0, 1, 2]
>>> result_word.rules
[[0, 0], [1], [1, 1], [2], [2, 2], [0]]

Converting a Stephen to a Presentation

To construct a Presentation from a Stephen, specify the following values for args:

• s (Stephen) – the Stephen from which to obtain the presentation.

Additionally, specify one of the following for Return:

• (Presentation,) for constructing a Presentation over words of the same type as that in s.

• (Presentation, str) for constructing a Presentation over words of type str.

• (Presentation, list[int]) for constructing a Presentation over words of type list[int].

This function constructs and returns a Presentation object that is equivalent to the presentation used to construct the Stephen object. A converted copy is always returned (even when word types match).

No computation is performed by this function; it simply retrieves the presentation that was used to define the Stephen object. Note that Stephen can be constructed from either a Presentation or an InversePresentation; in both cases, this function returns a Presentation.

See also

• Stephen.presentation.

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

>>> p = Presentation([5, 6, 7, 8, 9])
>>> presentation.add_rule(p, [5, 6], [7])
>>> presentation.add_rule(p, [6, 7], [8])
>>> presentation.add_rule(p, [7, 8], [9])
>>> presentation.add_rule(p, [8, 9], [5])
>>> presentation.add_rule(p, [9, 5], [6])

>>> s = Stephen(p)
>>> result = to(s, rtype=(Presentation, list[int]))
>>> result == p
True

>>> result_str = to(s, rtype=(Presentation, str))
>>> result_str.alphabet()
'abcde'
>>> result_str.rules
['ab', 'c', 'bc', 'd', 'cd', 'e', 'de', 'a', 'ea', 'b']