Converting to a FroidurePin

This page contains documentation relating to converting libsemigroups_pybind11 objects into FroidurePin 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 FroidurePin objects. The following options are possible:

Converting a Congruence to a FroidurePin

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

Additionally, specify the following for Return:

The FroidurePin object returned is isomorphic to the quotient of the underlying semigroup or monoid of cong by the congruence represented by cong.

This function throws a LibsemigroupsError if cong.kind is not congruence_kind.twosided.

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

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

>>> cong = Congruence(congruence_kind.twosided, p)
>>> fp = to(cong, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == cong.number_of_classes()
True

Converting a Kambites to a FroidurePin

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

Additionally, specify the following for Return:

The FroidurePin object returned is isomorphic to the quotient semigroup or monoid represented by k.

This function throws a LibsemigroupsError if the Kambites.small_overlap_class of k is not at least \(4\).

Warning

The returned FroidurePin instance is always infinite, and so any calls to any member functions that that trigger a full enumeration will never terminate (or they will when your computer kills the process because it has run out of memory).

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

>>> p = Presentation('abcdefg')
>>> presentation.add_rule(p, 'abcd', 'aaaeaa')
>>> presentation.add_rule(p, 'ef', 'dg')

>>> k = Kambites(congruence_kind.twosided, p)
>>> fp = to(k, rtype=(FroidurePin,))
>>> fp.enumerate(100)

>>> fp.current_size() == 8205
True

Converting a KnuthBendix to a FroidurePin

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

Additionally, specify the following for Return:

The FroidurePin object returned is isomorphic to the quotient semigroup or monoid represented by kb.

This function throws a LibsemigroupsError if kb.kind() is not congruence.twosided.

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

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

>>> kb = KnuthBendix(congruence_kind.twosided, p)
>>> fp = to(kb, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == kb.number_of_classes()
True

Converting a ToddCoxeter to a FroidurePin

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

Additionally, specify the following for Return:

The FroidurePin object returned is isomorphic to the quotient semigroup or monoid represented by tc.

This function throws a LibsemigroupsError if tc.kind() is not congruence.twosided.

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

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

>>> tc = ToddCoxeter(congruence_kind.twosided, p)
>>> fp = to(tc, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == tc.number_of_classes()
True

Converting a WordGraph to a FroidurePin

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

or

  • wg (WordGraph) – the WordGraph object being used to construct the FroidurePin object.

  • first (int) – the value of \(a\) in the following discussion.

  • last (int) – the value of \(b\) in the following discussion.

Additionally, specify the following for Return:

Each label n in the WordGraph will correspond to a generator f in the output FroidurePin such that f[s] = t whenever there is an edge from s to t in wg labelled n.

More precisely, if \(a\) and \(b\) are the parameters first (or 0 if not specified) and last (or wg.number_of_nodes() if not specified), respectively, \(m\) is the number of nodes in the WordGraph wg, \(0 \leq a, b< m\), and \(n\) is an edge label, then we define \(f: \{a, \ldots, b - 1\} \to \{0, \ldots, m - 1\}\) so that \((x)f\) equals the target of the edge starting at node \(x\) with label \(n\). In this way, every edge label in a WordGraph corresponds to a transformation of the nodes of the digraph. If \(\{a, \ldots, b - 1\}f \subseteq \{a, \ldots, b - 1\}\), then \(f\) is a transformation in the sense of Transf. Assuming that for every edge label of the WordGraph the corresponding \(f\) satisfies \(\{a, \ldots, b - 1\}f \subseteq \{a, \ldots, b - 1\}\), then this function returns the FroidurePin object corresponding to the semigroup or monoid generated by the set of all such transformations.

This function throws a LibsemigroupsError if throw_if_image_value_out_of_range throws for any of the constructed generators. This can happen if, for example, the WordGraph is not complete (i.e. there exists an edge label and node for which there is no edge with the given label and given source) or if there is an edge label such that \(\{a, \ldots, b - 1\}f \not\subseteq \{a, \ldots, b - 1\}\) for the corresponding \(f\).

>>> from libsemigroups_pybind11 import (
...     congruence_kind,
...     FroidurePin,
...     to,
...     WordGraph,
... )

>>> w = WordGraph(3, 1)
>>> w.target(0, 0, 1)
<WordGraph with 3 nodes, 1 edges, & out-degree 1>
>>> w.target(1, 0, 1)
<WordGraph with 3 nodes, 2 edges, & out-degree 1>
>>> w.target(2, 0, 1)
<WordGraph with 3 nodes, 3 edges, & out-degree 1>

>>> fp = to(
...     w,                  # wg
...     1,                  # first
...     2,                  # last
...     rtype=(FroidurePin,)
... )
>>> fp.run()

>>> fp.number_of_rules() == 1
True