diff --git a/docs/source/authors.rst b/docs/source/authors.rst index 21072724e..5a210f430 100644 --- a/docs/source/authors.rst +++ b/docs/source/authors.rst @@ -10,7 +10,7 @@ Authors ======= -- `Reinis Cirpons`_ (rc234@st-andrews.ac.uk)_ +- `Reinis Cirpons`_ (rc234@st-andrews.ac.uk) - `Joseph Edwards`_ (jde1@st-andrews.ac.uk) - `James Mitchell`_ (jdm3@st-andrews.ac.uk) - `Maria Tsalakou`_ (mt200@st-andrews.ac.uk) diff --git a/docs/source/changelog-v1.rst b/docs/source/changelog-v1.rst index e3789c3a6..b18f4b18a 100644 --- a/docs/source/changelog-v1.rst +++ b/docs/source/changelog-v1.rst @@ -99,11 +99,11 @@ This is a major release that significantly expands the API of ``libsemigroups_pybind11`` to expose much of the functionality implemented in version 3 of libsemigroups_. The extent of the changes made in this release means that it is likely that any code written with earlier versions of -``libsemigroups_pybin11`` will no longer work. +``libsemigroups_pybind11`` will no longer work. The structure of ``libsemigroups_pybind11`` is very tightly linked to the structure of libsemigroups_. Therefore, some of the differences between -v0.10.1 and v1.0.0 of ``libsemigroups_pyind11`` will be related to the +v0.10.1 and v1.0.0 of ``libsemigroups_pybind11`` will be related to the differences between v2 and v3 of libsemigroups_, such as changes to class names and interfaces. These changes can be found in the `libsemigroups changelog `_. diff --git a/docs/source/data-structures/presentations/to-inverse-present.rst b/docs/source/data-structures/presentations/to-inverse-present.rst index 6a81c712c..5070b987c 100644 --- a/docs/source/data-structures/presentations/to-inverse-present.rst +++ b/docs/source/data-structures/presentations/to-inverse-present.rst @@ -94,11 +94,11 @@ specify the following values for *args*: Additionally, specify one of the following for *rtype*: - ``(InversePresentation, str)`` for constructing an - - :any:`InversePresentation` over words of type ``str``. + :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 +This function behaves in one of two ways, depending on type of words in *ip*, and the type of words specified in *rtype*: 1. When the type of words in *ip* and type of words specified in *rtype* @@ -151,8 +151,8 @@ not the same as that specified in *rtype* or .. _inverse-presentation-and-function-to-inverse-presentation: -Converting an :any:`InversePresentation` to n :any:`InversePresentation` with a function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Converting an :any:`InversePresentation` to an :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 diff --git a/docs/source/data-structures/presentations/to-present.rst b/docs/source/data-structures/presentations/to-present.rst index 075b0dc92..315f19f65 100644 --- a/docs/source/data-structures/presentations/to-present.rst +++ b/docs/source/data-structures/presentations/to-present.rst @@ -175,7 +175,7 @@ Additionally, specify one of the following for *rtype*: the same type as that in *kb*. - ``(Presentation, str)`` for constructing a :any:`Presentation` over words of type ``str``. - - ``(Presentation, list[int]`` for constructing a :any:`Presentation` over + - ``(Presentation, list[int])`` for constructing a :any:`Presentation` over words of type ``list[int]``. This function constructs and returns a :any:`Presentation` object using the diff --git a/docs/source/main-algorithms/knuth-bendix/to-knuth-bendix.rst b/docs/source/main-algorithms/knuth-bendix/to-knuth-bendix.rst index 3b2363db2..be6870a37 100644 --- a/docs/source/main-algorithms/knuth-bendix/to-knuth-bendix.rst +++ b/docs/source/main-algorithms/knuth-bendix/to-knuth-bendix.rst @@ -100,9 +100,9 @@ following values for *args*: Additionally, specify one of the following for *rtype*: - ``(KnuthBendix, 'RewriteTrie')`` for constructing a :any:`KnuthBendix` - with the ``RewriteTrie'`` rewriter. + with the ``RewriteTrie`` rewriter. - ``(KnuthBendix, 'RewriteFromLeft')`` for constructing a :any:`KnuthBendix` - with the ``RewriteFromLeft'`` rewriter. + with the ``RewriteFromLeft`` rewriter. This function converts a :any:`ToddCoxeter` object *tc* to a :any:`KnuthBendix` object with the rewriter as specified above, using @@ -155,21 +155,21 @@ following values for *args*: Additionally, specify one of the following for *rtype*: - ``(KnuthBendix, str, 'RewriteTrie')`` for constructing a - :any:`KnuthBendix` on words with type ``str`` using the ``RewriteTrie'`` + :any:`KnuthBendix` on words with type ``str`` using the ``RewriteTrie`` rewriter. - ``(KnuthBendix, list[int], 'RewriteTrie')`` for constructing a :any:`KnuthBendix` on words with type ``list[int]`` using the - ``RewriteTrie'`` rewriter. + ``RewriteTrie`` rewriter. - ``(KnuthBendix, str, 'RewriteFromLeft')`` for constructing a :any:`KnuthBendix` on words with type ``str`` using the - ``RewriteFromLeft'`` rewriter. + ``RewriteFromLeft`` rewriter. - ``(KnuthBendix, list[int], 'RewriteFromLeft')`` for constructing a :any:`KnuthBendix` on words with type ``list[int]`` using the - ``RewriteFromLeft'`` rewriter. + ``RewriteFromLeft`` rewriter. This function converts a :any:`FroidurePin` object *fpb* to a :any:`KnuthBendix` object with the word type and rewriter as specified above. This is done using -the presentation obtained from ``to(fpb, rtype=(Presentation, Word)`` where +the presentation obtained from ``to(fpb, rtype=(Presentation, Word))`` where ``Word`` is either ``str`` or ``list[int]``. This returned :any:`KnuthBendix` object represents the trivial congruence over diff --git a/src/cong-common.cpp b/src/cong-common.cpp index 5acd8f405..b74f593fe 100644 --- a/src/cong-common.cpp +++ b/src/cong-common.cpp @@ -227,7 +227,7 @@ of kind *knd* over the semigroup or monoid defined by the presentation *p*. {detail} -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param p: the presentation. @@ -307,7 +307,7 @@ had been newly constructed from *knd* and *p*. {detail} -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: :any:`congruence_kind` :param p: the presentation. diff --git a/src/sims.cpp b/src/sims.cpp index f203afcb3..950dc2cab 100644 --- a/src/sims.cpp +++ b/src/sims.cpp @@ -162,7 +162,7 @@ The purpose of this is to improve the backtrack search by reducing the time spent processing "long" rules in each node of the search tree, and to only check them at the leaves. -:param pos: position of the the left hand side of the first long rule. +:param pos: position of the left-hand side of the first long rule. :type pos: int :returns: The first argument *self*. @@ -172,7 +172,7 @@ check them at the leaves. if *pos* is not a valid position in ``self.presentation().rules``. :raises LibsemigroupsError: - if the rule at position *pos* is not the left hand side of a rule (i.e. if + if the rule at position *pos* is not the left-hand side of a rule (i.e. if *pos* is odd). )pbdoc", doc_type) @@ -340,7 +340,6 @@ Add a pruner to the search tree. py::arg("pruner"), fmt::format(R"pbdoc( :sig=(self: {0}, pruner: collections.abc.Callable[[WordGraph], bool]) -> {0}: - collections.abc.Callable[[WordGraph], bool]) -> Sims1: :only-document-once: Add a pruner to the search tree. @@ -348,7 +347,7 @@ Add a pruner to the search tree. :type pruner: collections.abc.Callable[[WordGraph], bool] :returns: The first argument *self*. -:rtype@ {0} +:rtype: {0} .. warning:: When running the Sims low-index backtrack with multiple threads, each added @@ -377,12 +376,12 @@ Clear the set of pruners. }, fmt::format(R"pbdoc( :sig=(self: {0}) -> list[list[int]]: -Returns the set of pairs that must be excluded from every congruence. +Returns the set of pairs that must be included in every congruence. This function returns the list of included pairs. The congruences computed by a :any:`Sims1` or :any:`Sims2` instance always contain the relations of this list. In other words, the congruences computed by this instance are only taken -among those that contains the pairs of elements of the underlying semigroup +among those that contain the pairs of elements of the underlying semigroup (defined by the presentation returned by :py:meth:`~Sims1.presentation()` and :py:meth:`~Sims1.long_rules()`) represented by the relations of the list of words returned by :py:meth:`~Sims1.included_pairs()`. @@ -405,10 +404,10 @@ words returned by :py:meth:`~Sims1.included_pairs()`. :sig=(self: {0}, lhs: list[int], rhs: list[int]) -> {0}: Add a pair that should be included in every congruence. -:param lhs: the left hand side of the rule being added. +:param lhs: the left-hand side of the pair being added. :type lhs: list[int] -:param rhs: the right hand side of the rule being added. +:param rhs: the right-hand side of the pair being added. :type rhs: list[int] :returns: The first argument *self*. @@ -427,7 +426,7 @@ Add a pair that should be included in every congruence. return self.clear_included_pairs(); }, fmt::format(R"pbdoc( -Clear the set of included words. +Clear the set of included pairs. :returns: The first argument *self*. :rtype: {0} @@ -444,11 +443,11 @@ Returns the set of pairs that must be excluded from every congruence. This function returns the list of excluded pairs. The congruences computed by a :any:`Sims1` or :any:`Sims2` instance will never contain the relations of this -presentation. In other words, the congruences computed by this instance are +list. In other words, the congruences computed by this instance are only taken among those that do not contain any of the pairs of elements of the underlying semigroup (defined by the presentation returned by :py:meth:`~Sims1.presentation()` and :py:meth:`~Sims1.long_rules()`) -represented by the relations of the presentation returned by +represented by the relations of the list of words returned by :py:meth:`~Sims1.excluded_pairs()`. :returns: @@ -470,10 +469,10 @@ represented by the relations of the presentation returned by Add a pair that must be excluded from every congruence. -:param lhs: the left hand side of the rule being added. +:param lhs: the left-hand side of the pair being added. :type lhs: list[int] -:param rhs: the right hand side of the rule being added. +:param rhs: the right-hand side of the pair being added. :type rhs: list[int] :returns: The first argument *self*. @@ -492,7 +491,7 @@ Add a pair that must be excluded from every congruence. return self.clear_excluded_pairs(); }, fmt::format(R"pbdoc( -Clear the set of excluded words. +Clear the set of excluded pairs. :returns: The first argument *self*. :rtype: {0} @@ -572,7 +571,7 @@ This function sets the idle thread restart attempt count. The default value is :sig=(self: {0}, word: type) -> None: This function returns an uninitialized :any:`{0}` object that uses -words of type specified by *word*. +words of the type specified by *word*. :Keyword Arguments: * **word** (*type*) -- the type of words to use, must be ``list[int]``. @@ -615,7 +614,7 @@ Reinitialize an existing :any:`{0}` object. This function re-initializes a :any:`{0}` instance to be in the same state as *that*. -:param that: the instance use for reinitialization. +:param that: The instance used for reinitialization. :type that: {0} :returns: The re-initialized object. @@ -712,14 +711,14 @@ This function exists to: * provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of the number of congruence to be performed using +* allow for the computation of the number of congruences to be performed using :py:meth:`~{0}.number_of_threads` in parallel. :param n: the maximum number of congruence classes. :type n: int :returns: - The number of one sided congruences with at most *n* congruence classes. + The number of one-sided congruences with at most *n* congruence classes. :rtype: int :raises LibsemigroupsError: if *n* is ``0``. @@ -823,7 +822,7 @@ represent the congruences with at most *n* classes. The order in which the congruences are yielded by the iterator is implementation specific. The meaning of the :any:`WordGraph` objects yielded by the iterator depends on whether the input is a monoid presentation (i.e. -:py:meth:`~Presentation.contains_empty_word()` returns ``True`` ) or a +:py:meth:`~Presentation.contains_empty_word()` returns ``True``) or a semigroup presentation. If the input is a monoid presentation for a monoid :math:`M`, then the @@ -835,7 +834,7 @@ If the input is a semigroup presentation for a semigroup :math:`S`, then the :any:`WordGraph` has at most *n* + 1 nodes, and the right action of :math:`S` on the nodes :math:`\{{1, \ldots, n\}}` of the :any:`WordGraph` is isomorphic to the action of :math:`S` on the classes of a right congruence. It'd probably be -better in this case if node :math:`0` was not included in the output +better in this case if node :math:`0` were not included in the output :any:`WordGraph`, but it is required in the implementation of the low-index congruence algorithm, and to avoid unnecessary copies, we've left it in for the time being. @@ -932,7 +931,7 @@ or :any:`Sims2`. R"pbdoc( Get the number of congruences found at time of last report. -This function returns member holds the number of congruences found by the +This function returns the member that holds the number of congruences found by the :any:`Sims1` or :any:`Sims2` algorithm at the time of the last call to :py:meth:`~SimsStats.stats_check_point`. @@ -947,7 +946,7 @@ This function returns member holds the number of congruences found by the "count_now", [](SimsStats const& d) { return d.count_now.load(); }, R"pbdoc( -Get number of congruences found up to this point. +Get the number of congruences found up to this point. This function returns the total number of congruences found during the running of the :any:`Sims1` or :any:`Sims2` algorithm. @@ -985,7 +984,7 @@ the future in the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment. This function returns the total number of pending definitions that occur at the time of the last call to :py:meth:`~SimsStats.stats_check_point`. This is the same as the number of -nodes in the search tree encounter during the running of :any:`Sims1` or +nodes in the search tree encountered during the running of :any:`Sims1` or :any:`Sims2`. :returns: The number of pending definitions. @@ -1007,7 +1006,7 @@ the future in the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment. This function returns the total number of pending definitions that occur during the running of the algorithms in :any:`Sims1` or :any:`Sims2`. This is the same as the number of nodes in the -search tree encounter during the running of :any:`Sims1` or :any:`Sims2`. +search tree encountered during the running of :any:`Sims1` or :any:`Sims2`. :returns: The number of pending definitions. :rtype: int @@ -1063,7 +1062,7 @@ atomic load on the member variables of *that*. :param that: the :any:`SimsStats` to reinitialize from. :type that: SimsStats -:Returns: The first argument *self*. +:returns: The first argument *self*. :rtype: SimsStats )pbdoc"); @@ -1078,7 +1077,7 @@ and :py:meth:`~SimsStats.total_pending_now` respectively. Triggers an atomic load on :py:meth:`~SimsStats.count_now` and :py:meth:`~SimsStats.total_pending_now`. -:Returns: The first argument *self*. +:returns: The first argument *self*. :rtype: SimsStats )pbdoc"); @@ -1087,7 +1086,7 @@ load on :py:meth:`~SimsStats.count_now` and R"pbdoc( Set all statistics to zero. -:Returns: The first argument *self*. +:returns: The first argument *self*. :rtype: SimsStats )pbdoc"); @@ -1123,7 +1122,7 @@ v)` such that every vertex of the word graph is compatible with :math:`(u, v)`. :sig=(self: SimsRefinerFaithful, word: type) -> None: This function returns an uninitialized :any:`SimsRefinerFaithful` object that uses -words of type specified by *word*. +words of the type specified by *word*. :Keyword Arguments: * **word** (*type*) -- the type of words to use, must be ``list[int]``. @@ -1133,7 +1132,7 @@ words of type specified by *word*. py::arg("forbid"), R"pbdoc( :sig=(self: SimsRefinerFaithful, forbid: list[list[int]]) -> None: -Construct from set of forbidden pairs. +Construct from a set of forbidden pairs. This function constructs a :any:`SimsRefinerFaithful` pruner with respect to the set of forbidden relations in *forbid*. If *forbid* contains no trivial pairs (i.e. @@ -1203,7 +1202,7 @@ Reinitialize an existing :any:`SimsRefinerFaithful` object from a set of forbidden pairs. This function puts an object back into the same state as if it had been newly -constructed from set of forbidden pairs *forbid*. +constructed from the set of forbidden pairs *forbid*. :param forbid: a list of words such that ``(forbid[2*i], forbid[2*i+1])`` is the ``i``-th @@ -1222,7 +1221,7 @@ constructed from set of forbidden pairs *forbid*. Check if a word graph can be extended to one defining a faithful congruence. Returns ``False`` if there is no way of adding edges and nodes to -*wg* which will result in a word graph defining a faithful congruence. +*wg* which will result in a word graph defining a faithful congruence. Otherwise returns ``True``. :param wg: a word graph. @@ -1256,7 +1255,7 @@ or two-sided congruences arising from ideals (Rees congruences). :sig=(self: SimsRefinerIdeals, word: type) -> None: This function returns an uninitialized :any:`SimsRefinerIdeals` object that uses -words of type specified by *word*. +words of the type specified by *word*. :Keyword Arguments: * **word** (*type*) -- the type of words to use, must be ``list[int]``. @@ -1307,7 +1306,7 @@ constructed from the presentation *p*. :returns: The first argument *self*. :rtype: SimsRefinerIdeals -:raises LibsemigroupsError: if *p* is not valid +:raises LibsemigroupsError: if *p* is not valid. :raises LibsemigroupsError: if *p* has 0-generators and 0-relations. .. seealso:: :py:meth:`~SimsRefinerIdeals.presentation` @@ -1338,7 +1337,7 @@ instance. R"pbdoc( Check if a word graph can be extended to one defining a Rees congruence. -Returns ``False`` if there is no way of adding edges and nodes to *wg* which +Returns ``False`` if there is no way of adding edges and nodes to *wg* which will result in a word graph defining a Rees congruence. Otherwise returns ``True``. @@ -1357,14 +1356,14 @@ will result in a word graph defining a Rees congruence. Otherwise returns For computing small degree transformation representations of a finite semigroup or monoid. -This class is a helper for :any:`Sims1` calling the :any:`word_graph` member -function attempts to find a right congruence, represented as an +This class is a helper for :any:`Sims1` whose :any:`word_graph` member function +attempts to find a right congruence, represented as an :any:`WordGraph`, of the semigroup or monoid defined by the presentation consisting of its :py:meth:`~RepOrc.presentation` and :py:meth:`~RepOrc.long_rules` with the following properties: * the transformation semigroup defined by the :any:`WordGraph` has size - :py:meth:`~RepOrc.target_size` ; + :py:meth:`~RepOrc.target_size`; * the number of nodes in the :any:`WordGraph` is at least :py:meth:`~RepOrc.min_nodes` and at most :py:meth:`~RepOrc.max_nodes`. @@ -1400,7 +1399,7 @@ Set the maximum number of nodes. This function sets the maximum number of nodes in the :any:`WordGraph` that we are seeking. -:param val: the maximum number of nodes +:param val: the maximum number of nodes. :type val: int :returns: The first argument *self*. @@ -1432,7 +1431,7 @@ Set the minimum number of nodes. This function sets the minimal number of nodes in the :any:`WordGraph` that we are seeking. -:param val: the minimum number of nodes +:param val: the minimum number of nodes. :type val: int :returns: The first argument *self*. @@ -1449,10 +1448,10 @@ Get the word graph. This function attempts to find a right congruence, represented as an :any:`WordGraph`, of the semigroup or monoid defined by the presentation consisting of its :py:meth:`~RepOrc.presentation` and -:py:meth`~RepOrc.long_rules` with the following properties: +:py:meth:`~RepOrc.long_rules` with the following properties: * the transformation semigroup defined by the :any:`WordGraph` has size - :py:meth:`~RepOrc.target_size` ; + :py:meth:`~RepOrc.target_size`; * the number of nodes in the :any:`WordGraph` is at least :py:meth:`~RepOrc.min_nodes` and at most :py:meth:`~RepOrc.max_nodes`. @@ -1475,14 +1474,14 @@ returned (with ``0`` nodes and ``0`` edges). For computing the minimal degree of a transformation representation arising from a right congruence of a finite semigroup or monoid. -This class is a helper for :any:`Sims1`, calling the :any:`word_graph` member -function attempts to find a right congruence, represented as an +This class is a helper for :any:`Sims1` whose :any:`word_graph` member function +attempts to find a right congruence, represented as an :any:`WordGraph`, with the minimum possible number of nodes such that the action of the semigroup or monoid defined by the presentation consisting of its :py:meth:`~MinimalRepOrc.presentation` on the nodes of the :any:`WordGraph` corresponds to a semigroup of size :py:meth:`~MinimalRepOrc.target_size`. -If no such ::any:`WordGraph` can be found, then an empty :any:`WordGraph` is +If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with ``0`` nodes and ``0`` edges). )pbdoc"); @@ -1548,7 +1547,7 @@ iterator returned by :py:meth:`~Sims1.iterator` yields :any:`WordGraph` instances representing the action of the semigroup or monoid on the classes of a congruence. -.. seealso:: :any:`Sims2` for equivalent functionality for 2-sided congruences. +.. seealso:: :any:`Sims2` for equivalent functionality for two-sided congruences. )pbdoc"); bind_sims_settings(sss1, "Sims1"); @@ -1743,7 +1742,7 @@ semigroup or monoid defined by *p* and ``False`` otherwise. :param wg: a word graph. :type wg: WordGraph -:returns: An boolean. +:returns: A boolean. :rtype: bool )pbdoc"); @@ -1771,7 +1770,7 @@ semigroup or monoid defined by *p*. :param wg: a word graph. :type wg: WordGraph -:returns: An boolean. +:returns: A boolean. :rtype: bool )pbdoc"); @@ -1785,7 +1784,7 @@ semigroup or monoid defined by *p*. R"pbdoc( :sig=(p: Presentation, wg: WordGraph) -> bool: -Check if a word graph defines a two sided congruence on an f.p. semigroup or +Check if a word graph defines a two-sided congruence on an f.p. semigroup or monoid. Returns ``True`` if the word graph *wg* defines a two-sided congruence on the @@ -1797,7 +1796,7 @@ semigroup or monoid defined by *p* and ``False`` otherwise. :param wg: a word graph. :type wg: WordGraph -:returns: An boolean. +:returns: A boolean. :rtype: bool )pbdoc"); @@ -1823,7 +1822,7 @@ the semigroup or monoid defined by *p* and ``False`` otherwise. :param wg: a word graph. :type wg: WordGraph -:returns: An boolean. +:returns: A boolean. :rtype: bool )pbdoc"); @@ -1852,7 +1851,7 @@ congruence lattice of the semigroup or monoid. :param sims: a :any:`Sims1` object. :type sims: Sims1 -:param n: maximum number of congruence classes. +:param n: the maximum number of congruence classes. :type n: int :returns: A boolean matrix defining the congruence poset. @@ -1884,7 +1883,7 @@ computing the two-sided congruence lattice of the semigroup or monoid. :param sims: a :any:`Sims2` object. :type sims: Sims2 -:param n: maximum number of congruence classes. +:param n: the maximum number of congruence classes. :type n: int :returns: A boolean matrix defining the congruence poset. diff --git a/src/stephen.cpp b/src/stephen.cpp index 2b713fa44..9691f99c5 100644 --- a/src/stephen.cpp +++ b/src/stephen.cpp @@ -39,7 +39,7 @@ namespace libsemigroups { py::class_ thing(m, name.c_str(), R"pbdoc( -Class for constructing a word graph of left factors a word in a finitely +Class for constructing a word graph of left factors of a word in a finitely presented semigroup. This page describes the class :any:`Stephen` which implements Stephen's @@ -178,11 +178,11 @@ the last presentation change and ``False`` otherwise. R"pbdoc( Append a Stephen object. -This function appends the :any:`Stephen` object *other* to *self* . This +This function appends the :any:`Stephen` object *other* to *self*. This modifies the current :any:`Stephen` instance in-place. The result is a :any:`Stephen` instance with underlying word equal to the concatenation of -``this.word()`` and ``other.word()``.The advantage of this is other if either -*self* or *other* have already been (partially) run, then we can reuse the +``self.word()`` and ``other.word()``. The advantage is that if either *self* +or *other* has already been (partially) run, then we can reuse the underlying word graphs instead of having to recompute them completely from scratch. @@ -247,7 +247,7 @@ Get the initial word. Returns the word set by :py:meth:`~Stephen.set_word`. -:returns: A word. +:returns: A word. :rtype: list[int] :raises LibsemigroupsError: @@ -278,7 +278,7 @@ implemented in this class is not triggered by calls to this function. thing.def_static("initial_state", &Stephen_::initial_state, R"pbdoc( -:sig=(self: Stephen) -> int: +:sig=() -> int: Get the initial state of the word graph. @@ -310,7 +310,7 @@ word *w* is accepted if and only if :math:`uu^{-1}w` is equivalent to :math:`u` in the semigroup defined by :any:`Stephen.presentation`, where :math:`u` is the value of :any:`Stephen.word`. -:param s: the Stephen instance +:param s: the Stephen instance. :type s: Stephen :param w: the input word. @@ -357,7 +357,7 @@ Check if a word is a left factor of :any:`Stephen.word`. This function triggers the algorithm implemented in this class (if it hasn't been triggered already), and then returns ``True`` if the input word *w* is a left factor of :any:`Stephen.word` in the semigroup defined by -:any:`Stephen.presentation` . A word is a left factor of :any:`Stephen.word` if +:any:`Stephen.presentation`. A word is a left factor of :any:`Stephen.word` if it labels a path in :any:`Stephen.word_graph` with source ``0``. :param s: the Stephen instance. @@ -385,14 +385,17 @@ it labels a path in :any:`Stephen.word_graph` with source ``0``. R"pbdoc( :sig=(s: Stephen) -> Paths: :only-document-once: -Returns a :any:`Paths` object containing all the words (in short-lex order) that are left factors of :any:`Stephen.word`. +Returns a :any:`Paths` object containing all the words (in short-lex order) +that are left factors of :any:`Stephen.word`. -This function triggers the algorithm implemented in this class (if it hasn't been triggered already). +This function triggers the algorithm implemented in this class (if it hasn't +been triggered already). -:param s: the Stephen instance +:param s: the Stephen instance. :type s: Stephen -:returns: A :any:`Paths` object containing all the words (in short-lex order) that are left factors of :any:`Stephen.word`. +:returns: A :any:`Paths` object containing all the words (in short-lex order) + that are left factors of :any:`Stephen.word`. :rtype: Paths :raises LibsemigroupsError: @@ -463,7 +466,7 @@ in the range *min* to *max*. Returns the number of words accepted with length in a given range. This function triggers the algorithm implemented in this class (if it hasn't -been triggered already) and then returns the the number of paths in +been triggered already) and then returns the number of paths in :any:`Stephen.word_graph` with source ``0``, target :any:`Stephen.accept_state`, and length in the range *min* to *max*. @@ -508,14 +511,17 @@ equivalent to :math:`u` in the semigroup defined by :sig=(s: Stephen) -> Paths: :only-document-once: -Returns a :any:`Paths` object containing all words accepted by a Stephen instance in short-lex order. +Returns a :any:`Paths` object containing all words accepted by a +:any:`Stephen` instance in short-lex order. -This function triggers the algorithm implemented in this class (if it hasn't been triggered already). +This function triggers the algorithm implemented in this class (if it hasn't +been triggered already). -:param s: the Stephen instance +:param s: the Stephen instance. :type s: Stephen -:returns: A :any:`Paths` object containing all words equivalent to :any:`Stephen.word` in short-lex order. +:returns: A :any:`Paths` object containing all words equivalent to + :any:`Stephen.word` in short-lex order. :rtype: Paths :raises LibsemigroupsError: diff --git a/src/todd-coxeter-impl.cpp b/src/todd-coxeter-impl.cpp index 4ae851af2..ceb349000 100644 --- a/src/todd-coxeter-impl.cpp +++ b/src/todd-coxeter-impl.cpp @@ -46,8 +46,9 @@ namespace libsemigroups { py::class_ options(thing, "options", R"pbdoc( -This class containing various options that can be used to control the -behaviour of Todd-Coxeter.)pbdoc"); +This class contains various options that can be used to control the +behaviour of Todd-Coxeter. +)pbdoc"); py::options enum_settings; enum_settings.disable_enum_members_docstring(); @@ -63,7 +64,7 @@ The values in this enum can be used as the argument for the method :py:meth:`ToddCoxeter.strategy` to specify which strategy should be used when performing a coset enumeration. -The valid values are : +The valid values are: .. py:attribute:: strategy.hlt :value: @@ -78,7 +79,7 @@ The valid values are : .. py:attribute:: strategy.CR :value: - This strategy is meant to mimic the ACE strategy of the same name. The Felsch is run until at least :any:`f_defs` nodes are defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. These steps are repeated until the enumeration terminates. + This strategy is meant to mimic the ACE strategy of the same name. The Felsch strategy is run until at least :any:`f_defs` nodes are defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. These steps are repeated until the enumeration terminates. .. py:attribute:: strategy.R_over_C :value: @@ -93,7 +94,7 @@ The valid values are : .. py:attribute:: strategy.Rc :value: - This strategy is meant to mimic the ACE strategy Rc. The HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` new nodes have been defined (where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs) the Felsch strategy is then run until at least :any:`f_defs` new nodes are defined, and then the HLT strategy is run. + This strategy is meant to mimic the ACE strategy Rc. The HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` new nodes have been defined (where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs). The Felsch strategy is then run until at least :any:`f_defs` new nodes are defined, and then the HLT strategy is run. @@ -117,7 +118,7 @@ The values in this enum can be used as the argument for :any:`ToddCoxeter.lookahead_extent` to specify the extent of any lookahead that should be performed. -The valid values are : +The valid values are: .. py:attribute:: lookahead_extent.full :value: @@ -144,7 +145,7 @@ The values in this enum can be used as the argument for :any:`ToddCoxeter.lookahead_style` to specify the style of any lookahead that should be performed. -The valid values are : +The valid values are: .. py:attribute:: lookahead_style.hlt :value: @@ -196,12 +197,12 @@ The valid values are: .. py:attribute:: def_policy.purge_from_top :value: - If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are popped from the top of the stack (if any). + If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source nodes are popped from the top of the stack (if any). .. py:attribute:: def_policy.purge_all :value: - If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are popped from the entire of the stack (if any). + If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source nodes are popped from the entire stack (if any). .. py:attribute:: def_policy.discard_all_if_no_space :value: @@ -263,7 +264,7 @@ The valid values are: def_currently_contains(thing, "ToddCoxeterImpl_"); def_contains(thing, "ToddCoxeterImpl_"); def_reduce_no_run(thing, "ToddCoxeterImpl_", doc{.detail = R"pbdoc( -If the :any:`ToddCoxeter` instance is not :any:`Runner.finished`, +If the :any:`ToddCoxeter` instance is not :any:`Runner.finished`, then it might be that equivalent input words produce different output words. This function triggers no congruence enumeration.)pbdoc"sv}); def_reduce(thing, "ToddCoxeterImpl_"); @@ -288,7 +289,7 @@ congruence of kind *knd* over the :any:`ToddCoxeter` instance *tc*. The :any:`ToddCoxeter` instance constructed in this way represents a quotient of the word graph represented by *tc*. -:param knd: the kind (onesided, or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param tc: the :any:`ToddCoxeter` instance. @@ -297,8 +298,9 @@ the word graph represented by *tc*. :raises LibsemigroupsError: if the arguments *knd* and *tc* are not compatible. If the first item is ``tc.kind()`` and the second is the parameter *knd*, then compatible - arguments are (one-sided, one-sided), (two-sided, one-sided), and (two-sided, - two-sided).)pbdoc"); + arguments are (`onesided`, `onesided`), (`twosided`, `onesided`), and (`twosided`, + `twosided`). +)pbdoc"); thing.def(py::init const&>(), py::arg("knd"), @@ -317,7 +319,7 @@ or right Cayley graph of a semigroup or monoid, then the :any:`ToddCoxeter` instance will represent a quotient of that semigroup. -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param wg: the word graph. @@ -343,7 +345,7 @@ This function puts a :any:`ToddCoxeter` instance back into the state that it would have been in if it had just been newly constructed from *knd* and *tc*. -:param knd: the kind (onesided, or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param tc: the :any:`ToddCoxeter` instance. @@ -355,8 +357,8 @@ that it would have been in if it had just been newly constructed from :raises LibsemigroupsError: if the arguments *knd* and *tc* are not compatible. If the first item is ``tc.kind()`` and the second is the parameter *knd*, then compatible - arguments are (one-sided, one-sided), (two-sided, one-sided), and (two-sided, - two-sided). + arguments are (`onesided`, `onesided`), (`twosided`, `onesided`), and (`twosided`, + `twosided`). )pbdoc"); thing.def( @@ -378,7 +380,7 @@ This function puts a :any:`ToddCoxeter` instance back into the state that it would have been in if it had just been newly constructed from *knd* and *wg*. -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param wg: the word graph. @@ -418,7 +420,7 @@ definitions. Set the maximum number of definitions in the stack. This setting specifies the maximum number of definitions that can be in the -stack at any given time. What happens if there are the maximum number of +stack at any given time. What happens if there is the maximum number of definitions in the stack and a new definition is generated is governed by :any:`ToddCoxeter.def_policy`. @@ -491,8 +493,8 @@ The current value of the definition version setting. R"pbdoc( :sig=(self: ToddCoxeter, val: ToddCoxeter.options.def_version) -> ToddCoxeter: -This function can be used to specify how which version of definition handling -to use. For details see :any:`options.def_version`. +This function can be used to specify which version of definition handling to +use. For details see :any:`options.def_version`. The default value of this setting is :any:`def_version.two`. @@ -510,13 +512,12 @@ The default value of this setting is :any:`def_version.two`. :sig=(self: ToddCoxeter) -> int: Get the number of Felsch style definitions in ACE strategies. This -function returns the approx number of Felsch style definitions in each +function returns the approximate number of Felsch style definitions in each phase of the `ACE `_ style strategies: - :any:`strategy.CR`; - :any:`strategy.R_over_C`; -- :any:`strategy.R_over_C`; - :any:`strategy.Cr`; and - :any:`strategy.Rc`. @@ -542,13 +543,12 @@ The default value of this setting is ``10 ** 5``. Set the number of Felsch style definitions in ACE strategies. -This function can be used to set the approx number of Felsch style definitions +This function can be used to set the approximate number of Felsch style definitions in each phase of the `ACE `_ style strategies: * :any:`strategy.CR`; * :any:`strategy.R_over_C`; -* :any:`strategy.R_over_C`; * :any:`strategy.Cr`; and * :any:`strategy.Rc`. @@ -573,12 +573,11 @@ The default value of this setting is ``10 ** 5``. :sig=(self: ToddCoxeter) -> int: Get the number of HLT style definitions in ACE strategies. This function -returns the approx number of HLT style definitions in each phase of +returns the approximate number of HLT style definitions in each phase of the `ACE `_ style strategies: - :any:`strategy.CR`; - :any:`strategy.R_over_C`; -- :any:`strategy.R_over_C`; - :any:`strategy.Cr`; and - :any:`strategy.Rc`. @@ -604,13 +603,12 @@ The default value of this setting is ``10 ** 5``. Set the number of HLT style definitions in ACE strategies. -This function can be used to set the approx number of HLT style definitions in -each phase of the `ACE `_ +This function can be used to set the approximate number of HLT style +definitions in each phase of the `ACE `_ style strategies: * :any:`strategy.CR`; * :any:`strategy.R_over_C`; -* :any:`strategy.R_over_C`; * :any:`strategy.Cr`; and * :any:`strategy.Rc`. @@ -661,7 +659,7 @@ collapse. By default when processing coincidences nodes are merged in the word graph one pair at a time, and the in-neighbours of the surviving node are updated at the same time. If the number of coincidences is large, then it might be that a pair of nodes are merged at one step, then the surviving node is -merged with another node at a future step, and this may happen many many times. +merged with another node at a future step, and this may happen many times. This results in the in-neighbours of the surviving nodes being repeatedly traversed, which can result in a significant performance penalty. It can be beneficial to stop updating the in-neighbours as nodes are merged, and to just @@ -754,7 +752,7 @@ of active nodes already exceeds the value of :any:`lookahead_next` or the number of nodes killed during the lookahead is less than the number of active nodes divided by :any:`lookahead_growth_threshold`, then the value of :any:`lookahead_next` is increased by a multiple of *val*. The default value -is of this setting is ``2.0``. +of this setting is ``2.0``. :param val: the value indicating the lookahead growth factor. :type val: float @@ -836,10 +834,10 @@ After a lookahead is performed the value of :any:`lookahead_next` is modified depending on the outcome of the current lookahead. If the return value of :any:`lookahead_next` is too small or too large, then the value is adjusted according to :any:`lookahead_growth_factor` and -:any:`lookahead_growth_threshold`. This setting specified the minimum possible +:any:`lookahead_growth_threshold`. This setting specifies the minimum possible value for :any:`lookahead_next()`. The default value is ``10 ** 4``. -:param val: value indicating the minimum value of lookahead_next. +:param val: the value indicating the minimum value of lookahead_next. :type val: int :returns: *self*. @@ -877,7 +875,7 @@ lookahead of style :any:`ToddCoxeter.lookahead_style` and extent :any:`ToddCoxeter.lookahead_extent` will be triggered. The default value is ``5 * 10 ** 6``. -:param val: value indicating the initial threshold. +:param val: the value indicating the initial threshold. :type val: int :returns: *self*. @@ -917,7 +915,7 @@ During any lookaheads that are performed, it is periodically checked what proportion of the active nodes have been killed since the previous such check. This function can be used to set the interval between these checks. The purpose of this setting is to allow lookaheads to be stopped early if the number of -nodes being killed is too small (for example, if :math:`<1%` of nodes were +nodes being killed is too small (for example, if less than 1% of nodes were killed in the previous second, then we might want to stop the lookahead early, since lookaheads take some time but may not result in many nodes being killed). @@ -1045,8 +1043,8 @@ full description of this setting. R"pbdoc( :sig=(self: ToddCoxeter, val: int) -> ToddCoxeter: -Specify the minimum number of classes that may permit any enumeration early -stop. +Specify the minimum number of classes that may permit an enumeration to stop +early. This function can be used to set a lower bound for the number of classes of the congruence represented by a :any:`ToddCoxeter` instance. If the number of @@ -1054,10 +1052,10 @@ active nodes becomes at least the value of the argument, and the word graph is complete (:any:`word_graph.is_complete` returns ``True``), then the enumeration is terminated. When the given bound is equal to the number of classes, this may prevent following the paths labelled by relations at many -nodes when there is no possibility of finding coincidences.The default value is +nodes when there is no possibility of finding coincidences. The default value is :any:`UNDEFINED`. -:param val: value indicating the lower bound. +:param val: the value indicating the lower bound. :type val: int :returns: *self*. @@ -1093,7 +1091,7 @@ If the argument of this function is ``True`` and the HLT strategy is being used, then definitions are processed during any enumeration. The default value is ``False``. -:param val: value indicating whether or not to process deductions. +:param val: the value indicating whether or not to process definitions. :type val: bool :returns: *self*. @@ -1127,7 +1125,7 @@ Specify the congruence enumeration strategy. The strategy used during the enumeration can be specified using this function. The default value is :any:`strategy.hlt`. -:param val: value indicating which strategy to use. +:param val: the value indicating which strategy to use. :type val: ToddCoxeter.options.strategy :returns: *self*. @@ -1192,10 +1190,10 @@ by :any:`current_word_graph`). This spanning tree is only populated during calls to :any:`standardize` and as such might contain nothing, or a spanning tree of a previous value of :any:`current_word_graph`. Some care should be used with the return value of this function, and it might be better to use the -function :any:`spanning_tree`, which has none of these limitation. If -:any:`Runner.finished` returns ``True``, and :any:`standardize` has been called prior -to a call to this function, then the returned :any:`Forest` will represent a -valid spanning tree for the :any:`WordGraph` returned by +function :any:`spanning_tree`, which has none of these limitations. If +:any:`Runner.finished` returns ``True``, and :any:`standardize` has been called +prior to a call to this function, then the returned :any:`Forest` will +represent a valid spanning tree for the :any:`WordGraph` returned by :any:`current_word_graph` or :any:`word_graph`. :returns: @@ -1222,13 +1220,13 @@ In some sense, the purpose of the Todd-Coxeter algorithm is to produce a :any:`WordGraph` of the action of a set of generators on the classes of a congruence. This function can be used to obtain that :any:`WordGraph` as it currently exists within a :any:`ToddCoxeter` -instance. This function does not trigger any enumeration.The :any:`WordGraph` +instance. This function does not trigger any enumeration. The :any:`WordGraph` returned by this function may be in a rather complicated state. No guarantees are given: about the values of the active nodes (i.e. they may be any non-negative integers in any order); that the number of nodes (including those that are inactive) should coincide with the number of active nodes; that the graph is complete; or that the graph is compatible with the relations of the -:any:`presentation` or with the generating_pairs. The functions +:any:`presentation` or with the generating pairs. The functions :any:`standardize` and :any:`shrink_to_fit` can be used to modify the returned word graph in-place to have (possibly) more reasonable characteristics. @@ -1250,7 +1248,7 @@ word graph in-place to have (possibly) more reasonable characteristics. Check if the word graph is currently standardized with respect to any order. This function returns ``True`` if the :any:`current_word_graph` -has been standardized with respect to the any :any:`Order` other than +has been standardized with respect to any :any:`Order` other than :any:`Order.none`. :returns: @@ -1271,9 +1269,9 @@ has been standardized with respect to the any :any:`Order` other than Check if the word graph is currently standardized with respect to a given order. This function returns ``True`` if the :any:`current_word_graph` has been -standardized with respect to the order *val* ; and ``False`` if not. +standardized with respect to the order *val*, and ``False`` if not. -:param val: the Order to check for. +:param val: the order to check for. :type val: Order :returns: @@ -1338,8 +1336,8 @@ The return value of this function indicates the following: - :any:`Order.lex` implies that: - - the return values of :any:`todd_coxeter.normal_forms` will be ordered lexicographically. - - the return values of :any:`reduce` and the indexes of class are + - the return values of :any:`todd_coxeter.normal_forms` will be ordered lexicographically; + - the return values of :any:`reduce` and the indices of classes are essentially arbitrary because there is not necessarily a lexicographically least word in every class; @@ -1373,7 +1371,7 @@ In some sense, the purpose of the Todd-Coxeter algorithm is to produce a congruence. This function can be used to obtain that :any:`WordGraph` instance. This function triggers a full enumeration. The :any:`WordGraph` returned by this function may be in a rather complicated -state. The active nodes (and nodes) will be :math:`\{0, \ldots, n - 1\}` where +state. The active nodes will be :math:`\{0, \ldots, n - 1\}` where :math:`n` is the number of classes in the congruence if :any:`presentation` contains the empty word; or the number of classes plus one if :any:`presentation` does not contain the empty word. The returned @@ -1428,7 +1426,7 @@ settings are ignored. :sig=(self: ToddCoxeter) -> None: Shrink the underlying word graph to remove all dead nodes. This function -triggers a full enumeration, and standardization, and removes from +triggers a full enumeration and standardization, and removes from :any:`word_graph` any dead nodes. If :any:`Runner.finished` returns ``False``, then this function does nothing. )pbdoc"); @@ -1446,7 +1444,7 @@ does not trigger any enumeration. See :any:`standardization_order` for a full description. The return value of this function indicates whether or not the :any:`current_word_graph` was modified. In other words, if this function returns ``True``, then the word graph was not previously standardized with -respect to *val*, and was modified by calling this function if ``False`` is +respect to *val*, and was modified by calling this function. If ``False`` is returned, then the word graph was previously standardized with respect to *val* (although this might not have been known), and was not modified by calling this function. diff --git a/src/todd-coxeter.cpp b/src/todd-coxeter.cpp index 10ad3aaf6..8916746b1 100644 --- a/src/todd-coxeter.cpp +++ b/src/todd-coxeter.cpp @@ -50,7 +50,7 @@ computing 1-sided (right), and 2-sided congruences on a semigroup or monoid. In this documentation we use the term "congruence enumeration" to mean the execution of (any version of) the Todd-Coxeter algorithm. -.. seealso :any:`congruence_kind`, :any:`tril`, and :any:`Runner`. +.. seealso:: :any:`congruence_kind`, :any:`tril`, and :any:`Runner`. .. |name| replace:: :any:`ToddCoxeter` @@ -163,7 +163,7 @@ congruence of kind *knd* over the :any:`ToddCoxeter` instance *tc*. The :any:`ToddCoxeter` instance constructed in this way represents a quotient of the word graph represented by *tc*. -:param knd: the kind (onesided, or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param tc: the :any:`ToddCoxeter` instance. @@ -173,7 +173,8 @@ the word graph represented by *tc*. if the arguments *knd* and *tc* are not compatible. If the first item is ``tc.kind()`` and the second is the parameter *knd*, then compatible arguments are (one-sided, one-sided), (two-sided, one-sided), and (two-sided, - two-sided).)pbdoc"); + two-sided). +)pbdoc"); thing.def( "init", @@ -184,13 +185,13 @@ the word graph represented by *tc*. R"pbdoc( :sig=(self: ToddCoxeter, knd: congruence_kind, tc: ToddCoxeter) -> ToddCoxeter: -Re-initialize a ToddCoxeter instance. +Re-initialize a :any:`ToddCoxeter` instance. This function puts a :any:`ToddCoxeter` instance back into the state that it would have been in if it had just been newly constructed from *knd* and *tc*. -:param knd: the kind (onesided, or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param tc: the :any:`ToddCoxeter` instance. @@ -222,7 +223,7 @@ or right Cayley graph of a semigroup or monoid, then the :any:`ToddCoxeter` instance will represent a quotient of that semigroup. -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param wg: the word graph. @@ -241,17 +242,12 @@ semigroup. R"pbdoc( :sig=(self: ToddCoxeter, knd: congruence_kind, wg: WordGraph) -> ToddCoxeter: -Construct from :any:`congruence_kind` and :any:`WordGraph`. +Re-initialize from :any:`congruence_kind` and :any:`WordGraph`. -This function constructs a :any:`ToddCoxeter` instance representing a -congruence of kind *knd* over the :any:`WordGraph` *wg*. The -:any:`ToddCoxeter` instance constructed in this way represents a -quotient of the word graph *wg*. If *wg* happens to be the left -or right Cayley graph of a semigroup or monoid, then the -:any:`ToddCoxeter` instance will represent a quotient of that -semigroup. +This function puts a :any:`ToddCoxeter` instance back into the state that it +would have been in if it had just been newly constructed from *knd* and *wg*. -:param knd: the kind (onesided or twosided) of the congruence. +:param knd: the kind (`onesided` or `twosided`) of the congruence. :type knd: congruence_kind :param wg: the word graph. @@ -275,7 +271,7 @@ semigroup. Returns the current index of the class containing a word. This function returns the current index of the class containing the word -*w* No enumeration is triggered by calls to this function. Unless +*w*. No enumeration is triggered by calls to this function. Unless :any:`Runner.finished` returns ``True``, the index returned by this function is essentially arbitrary, and can only really be used to check whether or not two words are currently known to belong to the congruence. @@ -290,7 +286,7 @@ there is no such path, then :any:`UNDEFINED` is returned. :rtype: int | Undefined :raises LibsemigroupsError: - if any of the values in *w* is out of range, i.e. they do not belong to + if any value in *w* is out of range, i.e. it does not belong to ``presentation().alphabet()`` and ``Presentation.throw_if_letter_not_in_alphabet`` raises. )pbdoc"); @@ -323,7 +319,7 @@ value is never :any:`UNDEFINED`. :rtype: int :raises LibsemigroupsError: - if any of the values in *w*, i.e. they do not belong to + if any value in *w* is out of range, i.e. it does not belong to ``presentation().alphabet()`` and ``Presentation.throw_if_letter_not_in_alphabet`` raises. )pbdoc"); @@ -396,7 +392,7 @@ This function can be used to explicitly perform a lookahead. The style and extent of this lookahead are controlled by the settings :any:`ToddCoxeter.lookahead_style` and :any:`ToddCoxeter.lookahead_extent`. -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter .. seealso:: @@ -423,7 +419,7 @@ happens first. :param t: the time to run for. :type t: datetime.timedelta -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter )pbdoc"); @@ -445,7 +441,7 @@ This function runs a lookahead until the nullary predicate *pred* returns :param pred: the nullary predicate. :type pred: collections.abc.Callable[[], bool] -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter )pbdoc"); @@ -501,10 +497,10 @@ either. But doing the following: tc.number_of_classes() # returns 1 -returns the correct answer in about 5 seconds (on a 2024 Macbook Pro M4 +returns the correct answer in about 5 seconds (on a 2024 MacBook Pro M4 Pro). -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: @@ -551,14 +547,14 @@ function :any:`ToddCoxeter.reduce_no_run`. the congruence represented by *self*. :type collapser: collections.abc.Callable[[Word], Word] -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: if *self* is a one-sided congruence and has any generating pairs (because in this case :any:`perform_lookbehind` does nothing but still might take some time to run). -.. warning. +.. warning:: No checks are performed on the argument *collapser* to ensure that the word graph produced by using it to collapse nodes is valid. It is the responsibility of the caller to ensure that this is valid. @@ -602,7 +598,7 @@ happens first. :param t: the time to run for. :type t: datetime.timedelta -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: if *self* is a one-sided congruence and @@ -646,7 +642,7 @@ happens first. See :any:`perform_lookbehind_no_checks` for more details. the congruence represented by *self*. :type collapser: collections.abc.Callable[[Word], Word] -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: if *self* is a one-sided congruence and @@ -672,7 +668,7 @@ This function runs a lookbehind until the nullary predicate *pred* returns :param pred: the nullary predicate. :type pred: collections.abc.Callable[[], bool] -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: if *self* is a one-sided congruence and @@ -713,9 +709,9 @@ whichever happens first. a function taking a ``str`` or ``list[int]`` (depending on the type used by *self* for words) and which returns a word equivalent to the input word in the congruence represented by *self*. -:type collapser: collections.abc.Callable[[Word], Word]) +:type collapser: collections.abc.Callable[[Word], Word] -:returns: *self* +:returns: *self*. :rtype: ToddCoxeter :raises LibsemigroupsError: if *self* is a one-sided congruence and @@ -859,7 +855,7 @@ instance *tc*. Calls to this function trigger a full enumeration of *tc*. Returns an iterator yielding every word (of the same type as *w*) in the congruence class of the given word *w*. -This function returns an iterator yielding every word in belonging to +This function returns an iterator yielding every word belonging to the same class as the input word *w* in the congruence represented by the :any:`ToddCoxeter` instance *tc*. Calls to this function trigger a full enumeration of *tc*. @@ -874,9 +870,10 @@ full enumeration of *tc*. :rtype: collections.abc.Iterator[list[int] | str] :raises LibsemigroupsError: - if any of the values in *w* is out of range, i.e. they do not belong to + if any value in *w* is out of range, i.e. it does not belong to ``presentation().alphabet()`` and ``Presentation.throw_if_letter_not_in_alphabet`` - raises.)pbdoc"); + raises. +)pbdoc"); m.def("todd_coxeter_is_non_trivial", &todd_coxeter::is_non_trivial, @@ -916,7 +913,7 @@ non-trivial congruence containing the congruence represented by a :returns: Whether or not a non-trivial quotient was found. :rtype: tril - )pbdoc"); +)pbdoc"); m.def("todd_coxeter_perform_lookbehind", &todd_coxeter::perform_lookbehind, @@ -974,11 +971,12 @@ either. But doing the following: tc.perform_lookahead(True) tc.number_of_classes() # returns 1 -returns the correct answer in about 22 seconds (on a 2024 Macbook Pro M4 +returns the correct answer in about 22 seconds (on a 2024 MacBook Pro M4 Pro). -:param tc: the :any:`ToddCoxeter` instance. -:type tc: ToddCoxeter)pbdoc"); +:param tc: the :any:`ToddCoxeter` instance. +:type tc: ToddCoxeter +)pbdoc"); } // bind_todd_coxeter } // namespace diff --git a/src/transf.cpp b/src/transf.cpp index 3b7e1fe4c..2304f3647 100644 --- a/src/transf.cpp +++ b/src/transf.cpp @@ -84,7 +84,8 @@ the image of the point ``i`` under the {0} is ``imgs[i]``. :param imgs: the list of images. :type imgs: list[int] -:raises LibsemigroupsError: if any value in *imgs* exceeds ``len(imgs)``. +:raises LibsemigroupsError: + if any value in *imgs* is greater than or equal to ``len(imgs)``. {1} @@ -214,7 +215,7 @@ Increases the degree of *self* in-place, leaving existing values unaltered. :param m: the number of points to add. :type m: int -:returns: *self* +:returns: *self*. :rtype: {0} :complexity: @@ -231,7 +232,7 @@ Increases the degree of *self* in-place, leaving existing values unaltered. Returns the identity {0} on *N* points. This function returns a newly constructed {0} with degree equal to *N* that fixes every value from ``0`` to -*N*. +``N - 1``. :param N: the degree. :type N: int @@ -317,7 +318,7 @@ Swap with another {0} of the same type. Returns the identity on the same number of points as the degree of *f*. This function returns a newly constructed object of the same type as *f* -that fixes every value from ``0`` to ``f.degree()``. +that fixes every value from ``0`` to ``f.degree() - 1``. :param f: the transformation, partial perm, or permutation. :type f: Transf | PPerm | Perm @@ -336,14 +337,15 @@ that fixes every value from ``0`` to ``f.degree()``. :sig=(f: Transf | PPerm | Perm) -> list[int]: :only-document-once: -Returns the set of points in the image of a partial transformation. +Returns the set of points in the image of a transformation, partial perm, or +permutation. Returns a ``list[int]`` containing those values ``f[i]`` such that: -* :math:`i\in \{0, \ldots, n - 1\}` where `n` is the degree of *f*; and +* :math:`i\in \{0, \ldots, n - 1\}` where ``n`` is the degree of *f*; and * ``f[i] != UNDEFINED``. -:param f: the transformation. +:param f: the transformation, partial perm, or permutation. :type f: Transf | PPerm | Perm :returns: The sorted list of points in the image. @@ -360,11 +362,12 @@ Returns a ``list[int]`` containing those values ``f[i]`` such that: :sig=(f: Transf | PPerm | Perm) -> list[int]: :only-document-once: -Returns the set of points where a partial transformation is defined. +Returns the set of points in the domain of a transformation, partial perm, or +permutation. This function returns a ``list[int]`` containing those values ``i`` such that: -* :math:`i\in \{0, \ldots, n - 1\}` where `n` is the degree of *f*; and +* :math:`i\in \{0, \ldots, n - 1\}` where ``n`` is the degree of *f*; and * ``f[i] != UNDEFINED`` (only applies to partial perms). :param f: the transformation, partial perm, or permutation. @@ -546,7 +549,7 @@ with fewer points requiring less space per point. :sig=(self: PPerm, imgs: list[int | Undefined]) -> None: A partial perm can be constructed from a list of images, as follows: -the image of the point ``i`` under the {1} is ``imgs[i]``. +the image of the point ``i`` under the partial perm is ``imgs[i]``. :param imgs: the list of images. :type imgs: list[int | Undefined] @@ -554,7 +557,7 @@ the image of the point ``i`` under the {1} is ``imgs[i]``. :raises LibsemigroupsError: if there are repeated values in *imgs* that do not equal :any:`UNDEFINED`. :raises LibsemigroupsError: - if any integer value in *imgs* exceeds ``len(imgs)``. + if any integer value in *imgs* is greater than or equal to ``len(imgs)``. :complexity: Linear in :py:meth:`degree`. )pbdoc"); @@ -566,7 +569,7 @@ the image of the point ``i`` under the {1} is ``imgs[i]``. py::arg("im"), py::arg("n"), R"pbdoc( -:sig=(self: PPerm, dom: list[int], im: list[int], n:int) -> None: +:sig=(self: PPerm, dom: list[int], im: list[int], n: int) -> None: Construct from domain, image, and degree. @@ -583,7 +586,8 @@ all ``i`` and which is :any:`UNDEFINED` on every other value in the range :raises LibsemigroupsError: the value *n* is not compatible with the type. :raises LibsemigroupsError: *dom* and *im* do not have the same size. -:raises LibsemigroupsError: any value in *dom* or *im* is greater than *n*. +:raises LibsemigroupsError: + any value in *dom* or *im* is greater than or equal to *n*. :raises LibsemigroupsError: there are repeated entries in *dom* or *im*. )pbdoc"); @@ -674,7 +678,8 @@ Class for representing permutations on up to ``2 ** 32`` points. A *permutation* :math:`f` is an injective transformation defined on the whole of :math:`\{0, 1, \ldots, n - 1\}` for some integer :math:`n` called the *degree* of :math:`f`. A permutation is stored as a list of the images of -:math:`(0, 1, \ldots, n - 1)`, i.e. :math:`((0)f, (1)f, \ldots, (n - 1)f)`. +:math:`\{0, 1, \ldots, n - 1\}`, i.e. +:math:`((0)f, (1)f, \ldots, (n - 1)f)`. Permutations are optimised for the number of points in the image with fewer points requiring less space per point. diff --git a/src/types.cpp b/src/types.cpp index 4c31eb1d5..da17d308e 100644 --- a/src/types.cpp +++ b/src/types.cpp @@ -49,25 +49,25 @@ The valid values are: .. py:attribute:: tril.unknown :value: - Value representing unknown (either true or false). + Value representing a result that is not currently known. )pbdoc") .value("true", tril::TRUE) .value("false", tril::FALSE) .value("unknown", tril::unknown); py::enum_(m, "congruence_kind", R"pbdoc( -The values in this class can be used to indicate that a congruence should -be 1-sided or 2-sided. +The values in this enum can be used to indicate that a congruence should +be one-sided or two-sided. .. py:attribute:: congruence_kind.onesided :value: - Value representing 1-sided (right) congruences. + Value representing one-sided (right) congruences. .. py:attribute:: congruence_kind.twosided :value: - Value representing 2-sided congruences. + Value representing two-sided congruences. )pbdoc") .value("onesided", congruence_kind::onesided) diff --git a/src/ukkonen.cpp b/src/ukkonen.cpp index a58a5c5a8..96d998d84 100644 --- a/src/ukkonen.cpp +++ b/src/ukkonen.cpp @@ -50,7 +50,7 @@ namespace libsemigroups { Find the index of a word in the suffix tree. -If the *w* is one of the words that the suffix tree contains +If *w* is one of the words that the suffix tree contains (the words added to the suffix tree via :any:`ukkonen.add_word`), then this function returns the index of that word. If the word *w* is not one of the words that the suffix tree represents, then :any:`UNDEFINED` is returned. @@ -114,7 +114,7 @@ the tree). If an identical word is already in the tree, then this function does nothing except increase the multiplicity of that word. If *w* is empty, then this function does nothing. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word to add. :type w: str | list[int] @@ -142,7 +142,7 @@ If *w* is empty, then this function does nothing. :only-document-once: Add all words in a list to an :any:`Ukkonen` object. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param words: the list of words to add. :type words: list[str] | list[list[int]] @@ -170,10 +170,10 @@ Add all words in a list to an :any:`Ukkonen` object. Check if a word is a piece (occurs in two distinct places in the words of the suffix tree). This function returns ``True`` if *w* occurs in at least :math:`2` different (possibly -overlapping) places in the words contained in *u*. If no such prefix exists, +overlapping) places in the words contained in *u*. If no such occurrence exists, then ``False`` is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word to check. :type w: str | list[int] @@ -208,7 +208,7 @@ Check if a word is a subword of any word in a suffix tree. This function returns ``True`` if *w* is a subword of one of the words in the suffix tree represented by the :any:`Ukkonen` instance *u*. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word to check. :type w: str | list[int] @@ -243,7 +243,7 @@ Check if a word is a suffix of any word in a suffix tree. This function returns ``True`` if *w* is a suffix of one of the words in the suffix tree represented by the :any:`Ukkonen` instance *u*. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word to check. :type w: str | list[int] @@ -256,7 +256,10 @@ suffix tree represented by the :any:`Ukkonen` instance *u*. :complexity: Linear in the length of *w*. -.. seealso:: :any:`Ukkonen.throw_if_contains_unique_letter`.)pbdoc"); +.. seealso:: + + :any:`Ukkonen.throw_if_contains_unique_letter`. +)pbdoc"); m.def( "ukkonen_length_maximal_piece_prefix", @@ -272,11 +275,11 @@ suffix tree represented by the :any:`Ukkonen` instance *u*. Find the length of the maximal prefix of a word occurring in two different places in a word in a suffix tree. -This function returns the length of the maximal length prefix of *w* that occurs in at least +This function returns the length of the maximal prefix of *w* that occurs in at least :math:`2` different (possibly overlapping) places in the words contained in *u*. If no such prefix exists, then ``0`` is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -309,11 +312,11 @@ If no such prefix exists, then ``0`` is returned. Find the length of the maximal suffix of a word occurring in two different places in a word in a suffix tree. -This function returns the length of the maximal length prefix of *w* that occurs in at least +This function returns the length of the maximal suffix of *w* that occurs in at least :math:`2` different (possibly overlapping) places in the words contained in *u*. -If no such prefix exists, then ``0`` is returned. +If no such suffix exists, then ``0`` is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -343,11 +346,11 @@ If no such prefix exists, then ``0`` is returned. :only-document-once: Find the maximal prefix of a word occurring in two different places in a word in a suffix tree. -This function returns the maximal length prefix of the word corresponding *w* that occurs in +This function returns the maximal prefix of *w* that occurs in at least :math:`2` different (possibly overlapping) places in the words contained in *u*. If no such prefix exists, then an empty word is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -378,11 +381,11 @@ contained in *u*. If no such prefix exists, then an empty word is returned. :only-document-once: Find the maximal suffix of a word occurring in two different places in a word in a suffix tree. -This function returns the maximal length suffix of the word corresponding *w* that occurs in +This function returns the maximal suffix of *w* that occurs in at least :math:`2` different (possibly overlapping) places in the words contained in *u*. If no such suffix exists, then an empty word is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -419,7 +422,7 @@ such a product exists, and ``0`` if no such product exists. Recall that a *piece* is a word that occurs in two distinct positions (possibly overlapping) of the words in the suffix tree *u*. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -453,7 +456,7 @@ product exists, and an empty list if no such product exists. Recall that a *piece* is a word that occurs in two distinct positions (possibly overlapping) of the words in the suffix tree *u*. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] @@ -487,17 +490,17 @@ overlapping) of the words in the suffix tree *u*. Traverse the suffix tree from the root. This function traverses the edges in the suffix tree, starting at the root node, -that are labelled by the letters in *W*. The suffix tree is traversed until the -end of *W* is reached, or a letter not corresponding to an edge is encountered. +that are labelled by the letters in *w*. The suffix tree is traversed until the +end of *w* is reached, or a letter not corresponding to an edge is encountered. A pair consisting of the state reached, and the portion of *w* consumed in the traversal is returned. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param w: the word. :type w: str | list[int] -:returns: A tuple containing the :any:`State` reached, and the word consumed. +:returns: A tuple containing the :any:`Ukkonen.State` reached, and the word consumed. :rtype: tuple[Ukkonen.State, str | list[int]] :raises LibsemigroupsError: @@ -526,12 +529,12 @@ Traverse the suffix tree from the root. This function traverses the edges in the suffix tree, starting at the :any:`Ukkonen.State` *st*, that are labelled by the letters in *w*. The suffix -tree is traversed until the end of *w*is reached, or a letter not corresponding +tree is traversed until the end of *w* is reached, or a letter not corresponding to an edge is encountered. The state *st* is modified in-place to contain the last state in the tree reached in the traversal. The returned word represents the portion of *w* that was consumed in the traversal. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :param st: the :any:`Ukkonen.State` object from which to traverse. :type st: Ukkonen.State @@ -561,16 +564,17 @@ the portion of *w* that was consumed in the traversal. py::class_ thing(m, "Ukkonen", R"pbdoc( -For an implementation of Ukkonen's algorithm. +An implementation of Ukkonen's algorithm. This class implements Ukkonen's algorithm for constructing a generalised suffix tree consisting of ``list[int]``. The implementation in this class is based on: `https://cp-algorithms.com/string/suffix-tree-ukkonen.html `_ The suffix tree is updated when the member function :any:`ukkonen.add_word` is -invoked. Every non-duplicate word added to the tree has a unique letter appended -to the end. If a duplicate word is added, then the tree is not modified, but the -:any:`multiplicity` of the word is increased. +invoked. Every non-duplicate word added to the tree has a unique letter +appended to the end. If a duplicate word `w` is added, then the tree is not +modified, but the value returned by :any:`Ukkonen.multiplicity` applied to `w` +is increased. )pbdoc"); //////////////////////////////////////////////////////////////////////// @@ -673,16 +677,16 @@ The index of one past the last letter in the edge leading to the node. py::arg("r") = 0, py::arg("parent") = static_cast(UNDEFINED), R"pbdoc( -:sig=(self: Ukkonen, l: int = 0, r: int = 0, parent: int | Undefined = UNDEFINED) -> None: +:sig=(self: Ukkonen.Node, l: int = 0, r: int = 0, parent: int | Undefined = UNDEFINED) -> None: -Construct a node from left most index, right most index, and parent. +Construct a node from leftmost index, one-past-rightmost index, and parent. :param l: - the left most index and value of the data member *l* (defaults to ``0``). + the leftmost index and value of the data member *l* (defaults to ``0``). :type l: int :param r: - one after the right most index and value of the data member *r* + one after the rightmost index and value of the data member *r* (defaults to ``0``). :type r: int @@ -713,18 +717,18 @@ Copy a :any:`Ukkonen.Node` object. The index of the child node corresponding to a letter (if any). -:param c: the first letter in the edge of the node. +:param c: the first letter in the edge leading to the child node. :type c: int :returns: The index of the child node. :rtype: int -:complexity: Logarithmic in the size of ``len(children)``. +:complexity: Logarithmic in the number of children. )pbdoc"); node.def("is_leaf", &Ukkonen::Node::is_leaf, R"pbdoc( -Returns ``True``` if the node is a leaf and ``False`` if not. +Returns ``True`` if the node is a leaf and ``False`` if not. :returns: Whether the node is a leaf. :rtype: bool @@ -851,7 +855,7 @@ This is the total length of all the words added to the suffix tree including dup thing.def("max_word_length", &Ukkonen::max_word_length, R"pbdoc( -Returns the maximum length of word in the suffix tree. +Returns the maximum length of a word in the suffix tree. :returns: The maximum length of a word. :rtype: int @@ -868,7 +872,7 @@ Returns the multiplicity of a word by index. This function returns the number of times that the word corresponding to the index *i* was added to the suffix tree. -:param i: the node index. +:param i: the word index. :type i: int :returns: The multiplicity. @@ -909,7 +913,7 @@ duplicates, if any. :returns: The number of words. :rtype: int -:complexity: :math:`O(n)` where :math:`n` is the return value of :any:`number_of_distinct_words`. +:complexity: :math:`O(n)` where :math:`n` is the return value of :any:`number_of_distinct_words`. )pbdoc"); thing.def("unique_letter", &Ukkonen::unique_letter, @@ -989,14 +993,14 @@ Internally, all words added to the suffix tree are stored as a single string delimited by unique letters. The edge labels present in this :any:`Dot` object correspond to intervals of letters in that delimited string. -:param u: the :any:`Ukkonen` object. +:param u: the generalised suffix tree. :type u: Ukkonen :returns: A :any:`Dot` object representing *u*. :rtype: Dot -:raises LibsemigroupsError: if *u* does not contain any words. -:raises LibsemigroupsError: if the number of words in *u* is greater than ``24``. +:raises LibsemigroupsError: if *u* does not contain any words. +:raises LibsemigroupsError: if the number of words in *u* is greater than ``24``. )pbdoc"); m.def("ukkonen_number_of_distinct_subwords", @@ -1006,13 +1010,13 @@ correspond to intervals of letters in that delimited string. :sig=(u: Ukkonen) -> int: Returns the total number of distinct subwords of the words in the suffix tree *u*. -:param u: the Ukkonen object. +:param u: the generalised suffix tree. :type u: Ukkonen :returns: The total number of distinct subwords. :rtype: int -:complexity: Linear in ``Ukkonen.length_of_distinct_words``. +:complexity: Linear in :any:`Ukkonen.length_of_distinct_words`. )pbdoc"); bind_ukkonen_extras(m, thing); diff --git a/src/word-graph.cpp b/src/word-graph.cpp index bcc212231..f618af4ea 100644 --- a/src/word-graph.cpp +++ b/src/word-graph.cpp @@ -54,8 +54,8 @@ Class for representing word graphs. Instances of this class represent word graphs. If the word graph has ``n`` nodes, they are represented by the numbers :math:`\{0, ..., n - 1\}`, and every -node has the same number ``m`` of out-edges (edges with source that node and -target any other node or :any:`UNDEFINED`). The number ``m`` is referred to as +node has the same number ``m`` of out-edges (edges with that node as source and +any other node or :any:`UNDEFINED` as target). The number ``m`` is referred to as the *out-degree* of the word graph, or any of its nodes.)pbdoc"); thing.def("__repr__", [](WordGraph_ const& self) { @@ -117,7 +117,7 @@ out-degree of any node is *n*. There are no edges in the defined word graph. R"pbdoc( :sig=(self: WordGraph, num_nodes: int, targets: list[list[int | Undefined | PositiveInfinity | LimitMax]]) -> None: -Construct a word graph from a number of nodes and an list of targets. +Construct a word graph from a number of nodes and a list of targets. This function constructs a word graph from its arguments whose out-degree is specified by the length of the first item in *targets*. @@ -125,12 +125,12 @@ out-degree is specified by the length of the first item in *targets*. :param num_nodes: the number of nodes in the word graph. :type num_nodes: int -:param targets: list of the targets. +:param targets: the list of targets. :type targets: list[list[int | Undefined | PositiveInfinity | LimitMax]] :raises LibsemigroupsError: - if any target is specified in *targets* is greater than or equal to + if any target specified in *targets* is greater than or equal to *num_nodes*. .. doctest:: @@ -228,7 +228,7 @@ to the source node *source*. This target might equal :any:`UNDEFINED`. :raises LibsemigroupsError: if *source* is out of range (i.e. greater than or equal to - :any:`number_of_nodes`). + :any:`WordGraph.number_of_nodes`). :complexity: Constant. @@ -278,7 +278,7 @@ subgraph induced by the range of nodes *first* to *last*. :returns: *self*. :rtype: WordGraph -:raises LibsemigroupsError: if *first* or *last* is out of range. +:raises LibsemigroupsError: if *first* or *last* is out of range. :raises LibsemigroupsError: if any edge with source in the range *first* to *last* has target outside @@ -339,7 +339,7 @@ targets of edges with source *source*. :returns: An iterator. :rtype: collections.abc.Iterator[tuple[int, int | Undefined]] -:raises LibsemigroupsError: if *source* is out of bounds.)pbdoc"); +:raises LibsemigroupsError: if *source* is out of bounds.)pbdoc"); thing.def( "next_label_and_target", @@ -351,7 +351,7 @@ targets of edges with source *source*. R"pbdoc( :sig=(self: WordGraph, s: int, a: int) -> tuple[int | Undefined, int | Undefined]: -Get the next target of an edge incident to a given node that doesn't equal +Get the next target of an edge incident to a given node that does not equal :any:`UNDEFINED`. This function returns the next target of an edge with label greater than or @@ -367,7 +367,7 @@ equal to *a* that is incident to the node *s*. If ``target(s, b)`` equals :type a: int :returns: - Returns a pair where the first entry is the next label after *a* and the + A pair where the first entry is the next label after *a* and the second is the next target of *s* that is not :any:`UNDEFINED`. :rtype: tuple[int | Undefined, int | Undefined] @@ -410,12 +410,12 @@ This function returns the number of edges incident to the given source node :param s: the node. :type s: int -:returns: The number of edge incident to *s*. +:returns: The number of edges incident to *s*. :rtype: int -:raises LibsemigroupsError: if *s* is not a node. +:raises LibsemigroupsError: if *s* is not a node. -:complexity: :math:`O(n)` where ``n`` is :any:`out_degree()`.)pbdoc"); +:complexity: :math:`O(n)` where ``n`` is :any:`WordGraph.out_degree`.)pbdoc"); thing.def("number_of_nodes", &WordGraph_::number_of_nodes, R"pbdoc( @@ -473,7 +473,7 @@ This reduces the out-degree by ``1``. :returns: *self*. :rtype: WordGraph -:raises LibsemigroupsError: if *a* is out of range. +:raises LibsemigroupsError: if *a* is out of range. )pbdoc"); thing.def("remove_target", &WordGraph_::remove_target, @@ -489,13 +489,13 @@ This function removes the edge with source node *s* labelled by *a*. :param s: the source node. :type s: int -:param a: the label of the edge from s. +:param a: the label of the edge from *s*. :type a: int :returns: *self*. :rtype: WordGraph -:raises LibsemigroupsError: if *s* or *a* is out of range. +:raises LibsemigroupsError: if *s* or *a* is out of range. :complexity: Constant. )pbdoc"); @@ -549,7 +549,7 @@ with the target of the edge from the node *n* labelled *a*. :returns: *self*. :rtype: WordGraph -:raises LibsemigroupsError: if any of *m*, *n*, and *a* is out of +:raises LibsemigroupsError: if any of *m*, *n*, and *a* is out of range. :complexity: Constant @@ -563,12 +563,12 @@ with the target of the edge from the node *n* labelled *a*. py::arg("a"), py::arg("t"), R"pbdoc( -:sig=(self: WordGraph, s:int, a: int, t:int) -> WordGraph: +:sig=(self: WordGraph, s: int, a: int, t: int) -> WordGraph: Add an edge from one node to another with a given label. If *s* and *t* are nodes in *self*, and *a* is in the range ``[0, -out_degree())``, then this function adds an edge from *a* to *b* labelled *a*. +out_degree())``, then this function adds an edge from *s* to *t* labelled *a*. :param s: the source node. :type s: int @@ -576,13 +576,13 @@ out_degree())``, then this function adds an edge from *a* to *b* labelled *a*. :param a: the label of the edge. :type a: int -:param t: the range node. +:param t: the target node. :type t: int :returns: *self*. :rtype: WordGraph -:raises LibsemigroupsError: if *s*, *a*, or *t* is not valid. +:raises LibsemigroupsError: if *s*, *a*, or *t* is not valid. :complexity: Constant.)pbdoc"); thing.def( @@ -593,7 +593,7 @@ out_degree())``, then this function adds an edge from *a* to *b* labelled *a*. py::arg("source"), py::arg("a"), R"pbdoc( -:sig=(self: WordGraph, source:int, a: int) -> int: +:sig=(self: WordGraph, source: int, a: int) -> int: Get the target of the edge with given source node and label. @@ -607,7 +607,7 @@ label *a*. :type a: int :returns: - Returns the node adjacent to *source* via the edge labelled *a*, or + The node adjacent to *source* via the edge labelled *a*, or :any:`UNDEFINED`. :rtype: int @@ -638,8 +638,8 @@ out-degree *out_degree*. :returns: A random word graph. :rtype: WordGraph -:raises LibsemigroupsError: if *number_of_nodes* is less than ``2`` -:raises LibsemigroupsError: if *out_degree* is less than ``2`` +:raises LibsemigroupsError: if *number_of_nodes* is less than ``2``. +:raises LibsemigroupsError: if *out_degree* is less than ``2``. :complexity: :math:`O(mn)` where ``m`` is the number of nodes, and ``n`` is the out-degree of the word graph.)pbdoc"); @@ -655,7 +655,7 @@ out-degree *out_degree*. py::arg("n"), R"pbdoc( :sig=(wg: WordGraph, n: int) -> None: -Adds a cycle consisting of *N* new nodes. +Adds a cycle consisting of *n* new nodes. :param wg: the WordGraph object to add a cycle to. @@ -722,11 +722,11 @@ This function returns a :any:`Dot` object representing the word graph *wg*. py::arg("first"), py::arg("last"), R"pbdoc( -:sig=(x: WordGraph, y: WordGraph, first: int, last:int) -> bool: +:sig=(x: WordGraph, y: WordGraph, first: int, last: int) -> bool: Compares two word graphs on a range of nodes. This function returns ``True`` if the word graphs *x* and *y* are equal -on the range of nodes from *first* to *last* ; and ``False`` otherwise. +on the range of nodes from *first* to *last*; and ``False`` otherwise. The word graphs *x* and *y* are equal at a node *s* if: @@ -751,7 +751,7 @@ The word graphs *x* and *y* are equal at a node *s* if: :rtype: bool :raises LibsemigroupsError: - if *first* is not a node in *x* or not a node in *y* ; or if ``last - 1`` + if *first* is not a node in *x* or not a node in *y*; or if ``last - 1`` is not a node in *x* or not a node in *y*. .. note:: @@ -804,7 +804,7 @@ This function returns ``True`` if the word graph *wg* is acyclic and ``False`` otherwise. A word graph is acyclic if every directed cycle in the word graph is trivial. -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :returns: Whether or not the word graph is acyclic. @@ -848,7 +848,7 @@ reachable from *source* in the word graph *wg* is acyclic and ``False`` if not. A word graph is *acyclic* if every directed cycle in the word graph is trivial. -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :param source: the source node. @@ -902,7 +902,7 @@ reachable from *source* and from which *target* is reachable, in the word graph *wg*, is acyclic; and ``False`` if not. A word graph is *acyclic* if every directed cycle of the word graph is trivial. -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :param source: the source node. @@ -1049,8 +1049,8 @@ Check if a word graph is connected. This function returns ``True`` if the word graph *wg* is connected and ``False`` if it is not. A word graph is *connected* if for every pair of -nodes ``s`` and ``t`` in the graph there exists a sequence :math:`u_0 = s, -\ldots, u_{n}= t` for some :math:`n\in \mathbb{N}` such that for every +nodes ``s`` and ``t`` in the graph there exists a sequence +:math:`u_0 = s, \ldots, u_n = t` for some :math:`n\in \mathbb{N}` such that for every :math:`i` there exists a label ``a`` such that :math:`(u_i, a, u_{i + 1})` or :math:`(u_{i + 1}, a, u_i)` is an edge in the graph. @@ -1079,13 +1079,13 @@ Check if there is a path from one node to another. This function returns ``True`` if there is a path from the node *source* to the node *target* in the word graph *wg*. -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :param source: the source node. :type source: int -:param target: the source node. +:param target: the target node. :type target: int :returns: @@ -1113,17 +1113,17 @@ Check if every node is reachable from some node. This function returns ``True`` if there exists a node in *wg* from which every other node is reachable; and ``False`` otherwise. A word graph is *strictly cyclic* if there exists a node :math:`v` from which every node is -reachable (including :math:`v` ). There must be a path of length at least +reachable (including :math:`v`). There must be a path of length at least :math:`1` from the original node :math:`v` to itself (i.e. :math:`v` is not considered to be reachable from itself by default). -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :returns: Whether or not every node is reachable from one specific node. :rtype: bool -:raises LibsemigroupsError: if any target in *wg* is out of bounds. +:raises LibsemigroupsError: if any target in *wg* is out of bounds. :complexity: :math:`O(m + n)` where :math:`m` is the number of nodes in the @@ -1252,8 +1252,8 @@ algorithm given in :cite:`Carnino2011`. :returns: A random acyclic word graph. :rtype: WordGraph -:raises LibsemigroupsError: if *number_of_nodes* is less than ``2`` -:raises LibsemigroupsError: if *out_degree* is less than ``2`` +:raises LibsemigroupsError: if *number_of_nodes* is less than ``2``. +:raises LibsemigroupsError: if *out_degree* is less than ``2``. :complexity: At least :math:`O(mn)` where ``m`` is the number of nodes, and ``n`` is the out-degree of the word graph.)pbdoc"); @@ -1328,7 +1328,7 @@ Standardizes a word graph in-place. This function standardizes the word graph *wg* according to the reduction order specified by *val*, and replaces the contents of the :any:`Forest` -*f* with a spanning tree rooted at ``0`` for the node reachable from +*f* with a spanning tree rooted at ``0`` for the nodes reachable from ``0``. The spanning tree corresponds to the order *val*. :param wg: the word graph. @@ -1359,7 +1359,7 @@ Standardizes a word graph in-place. This function standardizes the word graph *wg* according to the reduction order specified by *val*, and returns a :any:`Forest` object containing -a spanning tree rooted at ``0`` for the node reachable from ``0``. The +a spanning tree rooted at ``0`` for the nodes reachable from ``0``. The spanning tree corresponds to the order *val*. :param wg: the word graph. @@ -1394,8 +1394,8 @@ in the list. :type wg: WordGraph :returns: - A list of the nodes of *wg* in topological order (if possible) and is - otherwise empty. + A list of the nodes of *wg* in topological order if possible, and an + empty list otherwise. :rtype: list[int] :complexity: @@ -1420,20 +1420,20 @@ If it is not empty, the returned list has the property that if an edge from a node ``n`` points to a node ``m``, then ``m`` occurs before ``n`` in the list, and the last item in the list is *source*. -:param wg: the WordGraph object to check. +:param wg: the word graph. :type wg: WordGraph :param source: the source node. :type source: int :returns: - A list of the nodes reachable from *source* in *wg* in topological order (if - possible) and is otherwise empty. + A list of the nodes reachable from *source* in *wg* in topological order if + possible, and an empty list otherwise. :rtype: list[int] :complexity: At worst :math:`O(m + n)` where :math:`m` is the number of - nodes in the subword graph of those nodes reachable from *source* and + nodes in the subgraph of those nodes reachable from *source* and :math:`n` is the number of edges.)pbdoc"); //////////////////////////////////////////////////////////////////////// @@ -1447,8 +1447,8 @@ Class for taking meets of word graphs. This class exists for its call operators which can be used to find the meet of two word graphs with the same :any:`WordGraph.out_degree`. This class -implements the same algorithm as that used for computing a finite state -automata recognising the intersection of the languages accepted by two given +implements the same algorithm as that used for computing a finite-state +automaton recognising the intersection of the languages accepted by two given automata. The input word graphs need not be complete, and the root nodes can also be specified.)pbdoc"); meeter.def("__repr__", @@ -1490,9 +1490,9 @@ corresponding language in *y*. :returns: Whether or not *x* is a subrelation of *y*. :rtype: bool -:raises LibsemigroupsError: if *x* has no nodes; -:raises LibsemigroupsError: if *y* has no nodes; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); +:raises LibsemigroupsError: if *x* has no nodes; +:raises LibsemigroupsError: if *y* has no nodes; +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); meeter.def( "is_subrelation", [](Meeter& self, @@ -1674,7 +1674,7 @@ and *y*. :raises LibsemigroupsError: if *y* has no nodes; :raises LibsemigroupsError: if *xroot* isn't a node in *x*; :raises LibsemigroupsError: if *yroot* isn't a node in *y*; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); //////////////////////////////////////////////////////////////////////// // Joiner @@ -1687,15 +1687,15 @@ Class for taking joins of word graphs. This class exists for its call operators which can be used to find the join of two word graphs with the same :any:`WordGraph.out_degree`. This class -implements the Hopcroft-Karp algorithm :cite:`Hop71` for computing a finite -state automata recognising the union of the languages accepted by two given +implements the Hopcroft-Karp algorithm :cite:`Hop71` for computing a +finite-state automaton recognising the union of the languages accepted by two given automata. The input word graphs need not be complete, and the root nodes can also be specified.)pbdoc"); joiner.def("__repr__", [](Joiner const& joiner) { return to_human_readable_repr(joiner); }); joiner.def(py::init<>(), R"pbdoc( - Default constructor.)pbdoc"); +Default constructor.)pbdoc"); joiner.def("__copy__", [](Joiner const& wg) { return Joiner(wg); }); joiner.def( "copy", @@ -1730,9 +1730,9 @@ corresponding language in *y*. :returns: Whether or not *x* is a subrelation of *y*. :rtype: bool -:raises LibsemigroupsError: if *x* has no nodes; -:raises LibsemigroupsError: if *y* has no nodes; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``. +:raises LibsemigroupsError: if *x* has no nodes; +:raises LibsemigroupsError: if *y* has no nodes; +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``. )pbdoc"); joiner.def( "is_subrelation", @@ -1774,7 +1774,7 @@ corresponding language in *y*. :raises LibsemigroupsError: if *y* has no nodes; :raises LibsemigroupsError: if *xroot* isn't a node in *x*; :raises LibsemigroupsError: if *yroot* isn't a node in *y*; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); joiner.def( "__call__", @@ -1817,7 +1817,7 @@ join of the word graphs *x* and *y*. :raises LibsemigroupsError: if *y* has no nodes; :raises LibsemigroupsError: if *xroot* isn't a node in *x*; :raises LibsemigroupsError: if *yroot* isn't a node in *y*; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); joiner.def( "__call__", @@ -1879,14 +1879,14 @@ and *y*. :param yroot: the node to use as a root in y. :type yroot: int -:returns: The join of *x* an *y*. +:returns: The join of *x* and *y*. :rtype: WordGraph :raises LibsemigroupsError: if *x* has no nodes; :raises LibsemigroupsError: if *y* has no nodes; :raises LibsemigroupsError: if *xroot* isn't a node in *x*; :raises LibsemigroupsError: if *yroot* isn't a node in *y*; -:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); +:raises LibsemigroupsError: if ``x.out_degree() != y.out_degree()``.)pbdoc"); joiner.def( "__call__", diff --git a/src/word-range.cpp b/src/word-range.cpp index 1549c49e5..6f09de90a 100644 --- a/src/word-range.cpp +++ b/src/word-range.cpp @@ -126,7 +126,7 @@ Copy a :any:`WordRange` object. For converting from ``list[int]`` to :any:`str`. This allows the pipe operator ``|`` to be used with a :any:`ToString` object to -convert the output of a :any:`WordRange` object strings. +convert the output of a :any:`WordRange` object to strings. )pbdoc"); thing1.def("__len__", &WordRange::count); thing1.def( @@ -140,12 +140,12 @@ Default constructor. Constructs an empty range with: -* :any:`WordRange.min()` equal to ``0`` ; -* :any:`WordRange.max()` equal to ``0`` ; -* :any:`WordRange.order()` equal to :any:`Order.shortlex` ; +* :any:`WordRange.min()` equal to ``0``; +* :any:`WordRange.max()` equal to ``0``; +* :any:`WordRange.order()` equal to :any:`Order.shortlex`; * :any:`WordRange.first()` equal to the empty word; * :any:`WordRange.last()` equal to the empty word; -* :any:`WordRange.upper_bound()` equal to ``0`` ; +* :any:`WordRange.upper_bound()` equal to ``0``; * :any:`WordRange.alphabet_size()` equal to ``0``. )pbdoc"); @@ -166,7 +166,7 @@ Returns ``True`` if a :any:`WordRange` object is exhausted, and ``False`` if not The actual size of the range. Returns the number of words in a :any:`WordRange` object. If :any:`WordRange.order()` is -:any:`Order.shortlex` , then :any:`WordRange.size_hint()` is used. If :any:`WordRange.order()` is +:any:`Order.shortlex`, then :any:`WordRange.size_hint()` is used. If :any:`WordRange.order()` is not :any:`Order.shortlex`, then a copy of the range may have to be looped over in order to find the return value of this function. @@ -210,7 +210,8 @@ then the object will be empty. :returns: *self*. :rtype: WordRange -.. seealso:: :any:`WordRange.min` +.. seealso:: + :any:`WordRange.min` )pbdoc"); thing1.def("get", &WordRange::get, @@ -280,7 +281,7 @@ greater than :any:`WordRange.alphabet_size()`, then the :any:`WordRange` object Set one past the last word in the range by length. Sets one past the last word in a :any:`WordRange` object to be -``words.pow(0_w, val)`` (the word consisting of *val* letters equal to ``0`` ). +``words.pow(0_w, val)`` (the word consisting of *val* letters equal to ``0``). :param val: the exponent. :type val: int @@ -298,7 +299,7 @@ Sets one past the last word in a :any:`WordRange` object to be Set the first word in the range by length. Sets the first word in a :any:`WordRange` object to be ``pow(0_w, val)`` -(the word consisting of *val* letters equal to ``0`` ). +(the word consisting of *val* letters equal to ``0``). :param val: the exponent. :type val: int @@ -313,7 +314,8 @@ Advance to the next value. Advances a :any:`WordRange` object to the next value (if any). -.. seealso:: :any:`WordRange.at_end` +.. seealso:: + :any:`WordRange.at_end` )pbdoc"); thing1.def( "alphabet_size", @@ -373,7 +375,7 @@ Sets the order of the words in a :any:`WordRange` object to *val*. :returns: *self*. :rtype: WordRange -:raises LibsemigroupsError: if val is not :any:`Order.shortlex` or :any:`Order.lex`. +:raises LibsemigroupsError: if *val* is not :any:`Order.shortlex` or :any:`Order.lex`. )pbdoc"); thing1.def("size_hint", &WordRange::size_hint, @@ -425,7 +427,7 @@ This setting is only used if :any:`WordRange.order()` is :any:`Order.lex`. R"pbdoc( Returns whether or not the settings have been changed since the last time either next or get has been called. -Other than by calling :any:`WordRange.next()` , the value returned by :any:`WordRange.get()` may be +Other than by calling :any:`WordRange.next()`, the value returned by :any:`WordRange.get()` may be altered by a call to one of the following: * ``order(Order)`` @@ -452,7 +454,7 @@ since the last time :any:`WordRange.next()` or :any:`WordRange.get()` is called, Class for generating strings in a given range and in a particular order. The ``StringRange`` class implements a range object for strings and produces the -same output as ``WordRange() | ToString("ab")`` , but is more convenient in some +same output as ``WordRange() | ToString("ab")``, but is more convenient in some cases. The order and range of the words in a :any:`StringRange` instance can be set @@ -531,10 +533,10 @@ Copy a :any:`StringRange` object. return sr | to_wrd; }, R"pbdoc( -For converting from to :any:`str` to ``list[int]``. +For converting from :any:`str` to ``list[int]``. This allows the pipe operator ``|`` to be used with a :any:`ToWord` object to -convert the output of a :any:`StringRange` object list[int]. +convert the output of a :any:`StringRange` object to ``list[int]``. )pbdoc"); thing2.def("__len__", &StringRange::count); @@ -548,12 +550,12 @@ convert the output of a :any:`StringRange` object list[int]. Default constructor. Constructs an empty range with: -* :any:`StringRange.min()` equal to ``0`` ; -* :any:`StringRange.max()` equal to ``0`` ; -* :any:`StringRange.order()` equal to :any:`Order.shortlex` ; +* :any:`StringRange.min()` equal to ``0``; +* :any:`StringRange.max()` equal to ``0``; +* :any:`StringRange.order()` equal to :any:`Order.shortlex`; * :any:`StringRange.first()` equal to the empty string; * :any:`StringRange.last()` equal to the empty string; -* :any:`StringRange.upper_bound()` equal to ``0`` ; +* :any:`StringRange.upper_bound()` equal to ``0``; * :any:`StringRange.alphabet()` equal to the empty string. )pbdoc"); @@ -585,7 +587,7 @@ Sets the alphabet in a :any:`StringRange` object. :returns: *self*. :rtype: StringRange -:raises LibsemigroupsError: if *x* contains repeated letters. +:raises LibsemigroupsError: if *x* contains repeated letters. )pbdoc"); thing2.def("at_end", &StringRange::at_end, @@ -612,7 +614,7 @@ object. :returns: An input iterator. .. seealso:: - :any:`end`. + :any:`StringRange.last`. )pbdoc"); thing2.def("count", @@ -621,8 +623,8 @@ object. The actual size of the range. Returns the number of strings in the range object. If :any:`StringRange.order()` -is :any:`Order.shortlex` , then :any:`StringRange.size_hint()` is used. If -:any:`order()` is not :any:`Order.shortlex` , then a copy of the range may have +is :any:`Order.shortlex`, then :any:`StringRange.size_hint()` is used. If +:any:`StringRange.order()` is not :any:`Order.shortlex`, then a copy of the range may have to be looped over in order to find the return value of this function. :returns: The size of the range. @@ -640,7 +642,7 @@ Returns the first string in a :any:`StringRange` object. :rtype: str .. seealso:: - :any:`min` + :any:`StringRange.min` )pbdoc"); thing2.def( @@ -660,7 +662,8 @@ Sets the first string in a :any:`StringRange` object to be *frst*. :returns: *self*. :rtype: StringRange -.. seealso:: :any:`min` +.. seealso:: + :any:`StringRange.min` )pbdoc"); thing2.def("get", &StringRange::get, @@ -696,7 +699,7 @@ Returns one past the last string in a :any:`StringRange` object. :rtype: str .. seealso:: - :any:`max` + :any:`StringRange.max` )pbdoc"); thing2.def( "last", @@ -709,7 +712,7 @@ Set one past the last string in the range. Sets one past the last string in a :any:`StringRange` object to be *lst*. -:param lst: the first string. +:param lst: one past the last string. :type lst: str :returns: *self*. @@ -718,7 +721,7 @@ Sets one past the last string in a :any:`StringRange` object to be *lst*. :raises LibsemigroupsError: if *lst* contains letters not belonging to :any:`StringRange.alphabet()`. .. seealso:: - :any:`max` + :any:`StringRange.max` )pbdoc"); thing2.def( "max", @@ -772,7 +775,7 @@ Advance to the next value. Advances a :any:`StringRange` object to the next value (if any). .. seealso:: - :any:`at_end` + :any:`StringRange.at_end` )pbdoc"); thing2.def( "order", @@ -802,16 +805,16 @@ Sets the order of the strings in a :any:`StringRange` object to *val*. :returns: *self*. :rtype: StringRange -:raises LibsemigroupsError: if *val* is not :any:`Order.shortlex` or :any:`Order.lex`. +:raises LibsemigroupsError: if *val* is not :any:`Order.shortlex` or :any:`Order.lex`. )pbdoc"); thing2.def("size_hint", &StringRange::size_hint, R"pbdoc( The possible size of the range. -Returns the number of words in a :any:`StringRange` object if -:any:`StringRange.order()` is :any:`Order.shortlex`. If :any:`order()` is not -:any:`Order.shortlex` , then the return value of this function is meaningless. +Returns the number of strings in a :any:`StringRange` object if +:any:`StringRange.order()` is :any:`Order.shortlex`. If :any:`StringRange.order()` is not +:any:`Order.shortlex`, then the return value of this function is meaningless. :returns: A value of type ``int``. :rtype: int @@ -894,7 +897,7 @@ Construct a :any:`ToWord` object with the given alphabet. :param alphabet: the alphabet. :type alphabet: str -:raises LibsemigroupsError: if there are repeated letters in *alphabet*. +:raises LibsemigroupsError: if there are repeated letters in *alphabet*. )pbdoc"); thing3.def( "copy", @@ -939,12 +942,12 @@ performed using :any:`words.human_readable_index`. &ToWord::can_convert_letter, py::arg("c"), R"pbdoc( -Check if the current ToWord instance can convert a specified letter. +Check if the current :any:`ToWord` instance can convert a specified letter. This function returns ``True`` if *c* can be converted to an :any:`int` using this :any:`ToWord` instance, and ``False`` otherwise. -:param c: the letter to check the convertibility of. +:param c: the letter whose convertibility is being checked. :type c: str :returns: Whether the letter can be converted. @@ -956,7 +959,7 @@ this :any:`ToWord` instance, and ``False`` otherwise. "init", [](ToWord& self) -> ToWord& { return self.init(); }, R"pbdoc( -Initialize an existing ToWord object. +Initialize an existing :any:`ToWord` object. This function puts a :any:`ToWord` object back into the same state as if it had been newly default constructed. @@ -975,7 +978,7 @@ been newly default constructed. }, py::arg("alphabet"), R"pbdoc( -Initialize an existing ToWord object. +Initialize an existing :any:`ToWord` object. This function puts a :any:`ToWord` object back into the same state as if it had been newly constructed from *alphabet*. @@ -986,7 +989,7 @@ been newly constructed from *alphabet*. :returns: *self*. :rtype: ToWord -:raises LibsemigroupsError: if there are repeated letters in *alphabet*. +:raises LibsemigroupsError: if there are repeated letters in *alphabet*. .. seealso:: :any:`ToWord(str)` @@ -1005,7 +1008,7 @@ Convert a string to a ``list[int]``. This function converts its argument *input* into a ``list[int]``. The characters of *input* are converted using the alphabet used to construct the object or set -via :any:`ToWord.init()` , or with :any:`words.human_readable_index` if +via :any:`ToWord.init()`, or with :any:`words.human_readable_index` if :any:`ToWord.empty()` returns ``True``. :param input: the string to convert. @@ -1063,7 +1066,7 @@ Construct a :any:`ToString` object with the given alphabet. :param alphabet: the alphabet. :type alphabet: str -:raises LibsemigroupsError: if there are repeated letters in *alphabet*. +:raises LibsemigroupsError: if there are repeated letters in *alphabet*. )pbdoc"); thing4.def( "copy", @@ -1100,12 +1103,12 @@ performed using :any:`words.human_readable_letter`. R"pbdoc( :sig=(self: ToString, l: int) -> bool: -Check if the current ToString instance can convert a specified letter. +Check if the current :any:`ToString` instance can convert a specified letter. This function returns ``True`` if *l* can be converted to a :any:`str` using this ToString instance, and ``False`` otherwise. -:param l: the letter to check the convertibility of. +:param l: the letter whose convertibility is being checked. :type l: int :returns: Whether the letter can be converted. @@ -1116,16 +1119,16 @@ ToString instance, and ``False`` otherwise. R"pbdoc( Check if the alphabet is defined. -This function return ``True`` if no alphabet has been defined, and ``False`` otherwise. +This function returns ``True`` if no alphabet has been defined, and ``False`` otherwise. -:returns: A whether the alphabet is empty. +:returns: Whether the alphabet is empty. :rtype: bool )pbdoc"); thing4.def( "init", [](ToString& self) -> ToString& { return self.init(); }, R"pbdoc( -Initialize an existing ToString object. +Initialize an existing :any:`ToString` object. This function puts a :any:`ToString` object back into the same state as if it had been newly default constructed. @@ -1144,7 +1147,7 @@ had been newly default constructed. }, py::arg("alphabet"), R"pbdoc( -Initialize an existing Tostring object. +Initialize an existing :any:`ToString` object. This function puts a :any:`ToString` object back into the same state as if it had been newly constructed from *alphabet*. @@ -1172,17 +1175,21 @@ had been newly constructed from *alphabet*. Convert a ``list[int]`` to a :any:`str`. -This function converts its argument *input* into a :any:`str`. The characters of +This function converts its argument *input* into a :any:`str`. The entries of *input* are converted using the alphabet used to construct the object or set via -:any:`init()`, or with :any:`words.human_readable_letter` if :any:`empty()` returns ``True``. +:any:`ToString.init()`, or with :any:`words.human_readable_letter` if +:any:`ToString.empty()` returns ``True``. -:param input: the string to convert. +:param input: the list to convert. :type input: list[int] :returns: The converted string. :rtype: str -:raises LibsemigroupsError: if the alphabet used to define an instance of :any:`ToString` is not empty and *input* contains letters that do not correspond to letters of the alphabet. +:raises LibsemigroupsError: + if the alphabet used to define an instance of :any:`ToString` is not empty + and *input* contains values that do not correspond to letters of the + alphabet. )pbdoc"); //////////////////////////////////////////////////////////////////////////// @@ -1206,7 +1213,7 @@ Returns the number of words over a given alphabet in some range. :param max: one greater than the maximum length of a word. :type max: int -:returns: The number words over an alphabet with *n* letters with length in the range ``[min, max)``. +:returns: The number of words over an alphabet with *n* letters with length in the range ``[min, max)``. :rtype: int .. doctest:: @@ -1236,7 +1243,7 @@ Returns a random word. :raises LibsemigroupsError: if *nr_letters* is ``0``. .. seealso:: - :py:func:`random_string`. + :any:`random_string`. )pbdoc"); @@ -1314,11 +1321,11 @@ the specified alphabet. py::arg("min"), py::arg("max"), R"pbdoc( -:sig=(alphabet: str, number: int, min: int, max:int) -> collections.abc.Iterator[str]: +:sig=(alphabet: str, number: int, min: int, max: int) -> collections.abc.Iterator[str]: Returns an iterator of random strings. -Returns an iterator of random strings, each of which with random length +Returns an iterator of random strings, each with random length in the range ``[min, max)`` over the specified alphabet. :param alphabet: the alphabet over which the string is constructed. @@ -1384,15 +1391,15 @@ expression, and has the following behaviour: py::arg("c"), R"pbdoc( :sig=(c: str) -> int: -Returns the index of a character in human readable order. +Returns the index of a character in human-readable order. This function is the inverse of :any:`words.human_readable_letter`, see the documentation of that function for more details. -:param c: character whose index is sought. +:param c: the character whose index is sought. :type c: str -:returns: The human readable index. +:returns: The human-readable index. :rtype: int :raises ValueError: if *c* is not exactly one character long. @@ -1406,13 +1413,13 @@ documentation of that function for more details. py::arg("i"), R"pbdoc( :sig=(i: int) -> str: -Returns a character by index in human readable order. +Returns a character by index in human-readable order. This function exists to map the numbers ``0`` to ``255`` to the possible values of a one-byte char, in such a way that the first characters are -``a-zA-Z0-9``. The ascii ranges for these characters are: :math:`[97, 123)`, -:math:`[65, 91)`, :math:`[48, 58)` so the remaining range of chars that are -appended to the end after these chars are :math:`[0,48)`, :math:`[58, 65)`, +``a-zA-Z0-9``. The ASCII ranges for these characters are: :math:`[97, 123)`, +:math:`[65, 91)`, :math:`[48, 58)`, so the remaining ranges of chars that are +appended to the end after these chars are :math:`[0, 48)`, :math:`[58, 65)`, :math:`[91, 97)`, :math:`[123, 255]`. This function is the inverse of :any:`words.human_readable_index`. @@ -1420,7 +1427,7 @@ This function is the inverse of :any:`words.human_readable_index`. :param i: the index of the character. :type i: int -:returns: The human readable character. +:returns: The human-readable character. :rtype: str :raises LibsemigroupsError: if *i* exceeds ``255``.