From a7266aad20374988a3576fbf8c2b267e9f811d04 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 17:53:46 +0100 Subject: [PATCH 01/24] Fix Froidure-Pin base documentation wording --- src/froidure-pin-base.cpp | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/froidure-pin-base.cpp b/src/froidure-pin-base.cpp index 501ce5669..f95e40ae9 100644 --- a/src/froidure-pin-base.cpp +++ b/src/froidure-pin-base.cpp @@ -34,7 +34,7 @@ namespace libsemigroups { "FroidurePinBase", R"pbdoc( Base class for :any:`FroidurePin` containing non-element specific data and -member functions. :any:`FroidurePin` is an abstract class which cannot be +member functions. :any:`FroidurePinBase` is an abstract class which cannot be instantiated directly, only via the derived class :any:`FroidurePin`.)pbdoc"); thing.def( @@ -67,7 +67,7 @@ Set a new value for the batch size. The *batch size* is the number of new elements to be found by any call to :any:`Runner.run`. This is used by, for example, :any:`FroidurePin.position` so that it is possible to find the position of an element after only partially -enumerating the semigroup.The default value of the batch size is ``8192``. +enumerating the semigroup. The default value of the batch size is ``8192``. :param val: the new value for the batch size. :type val: int @@ -171,7 +171,7 @@ This function return the right Cayley graph of the semigroup as it has been enumerated so-far. No enumeration is triggered by calls to this function. :returns: - The (possibly partially enumerated) left Cayley graph. + The (possibly partially enumerated) right Cayley graph. :rtype: WordGraph @@ -292,7 +292,8 @@ first letter of the element. Check if the categorical multiplicative identity is an element. :returns: - Whether or not the one of any of the elements belongs to the semigroup. + Whether or not the categorical multiplicative identity belongs to the + semigroup. :rtype: bool @@ -310,7 +311,8 @@ Check if the categorical multiplicative identity is an element. Check if the categorical multiplicative identity is an element. :returns: - Whether or not the one of any of the elements belongs to the semigroup. + Whether or not the categorical multiplicative identity belongs to the + semigroup. :rtype: bool @@ -424,7 +426,7 @@ trigger any enumeration. Returns the total number of relations in a presentation defining the semigroup. This function triggers a full enumeration of the semigroup. -:returns: The number of rules so-far found. +:returns: The total number of rules. :rtype: int :complexity: @@ -632,7 +634,7 @@ Returns an iterator yielding the so-far enumerated normal forms (if any). This function returns an iterator yielding the normal forms of the semigroup represented by *fp* instance (if any). This function does not perform any enumeration of *fp*. If you want to obtain the -complete set of rules, then use :any:`normal_forms` instead. +complete set of normal forms, then use :any:`normal_forms` instead. :param fp: the :any:`FroidurePin` object. @@ -753,7 +755,7 @@ Returns an iterator yielding the rules. This function returns an iterator yielding the rules in a confluent terminating rewriting system defining a semigroup isomorphic to the one defined by -*fp*. This function performs a full enumeration of *fp* If you want to +*fp*. This function performs a full enumeration of *fp*. If you want to obtain the current set of rules without triggering any enumeration, then use :any:`current_rules` instead. From 329ca3f49cbc9be45f5e7583fb1704a9f8b072e6 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 17:57:02 +0100 Subject: [PATCH 02/24] Fix Froidure-Pin base documentation wording --- src/froidure-pin.cpp | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/froidure-pin.cpp b/src/froidure-pin.cpp index c31e41b05..bd61e0f12 100644 --- a/src/froidure-pin.cpp +++ b/src/froidure-pin.cpp @@ -91,7 +91,7 @@ Copy a :any:`FroidurePin` object. R"pbdoc( :sig=(self: FroidurePin, i: int) -> int: -Returns the position in of the generator with specified index. +Returns the position of the generator with specified index. In many cases :any:`FroidurePin.current_position` called with argument *i* will return *i*, examples of when this will not be the case are: @@ -148,7 +148,7 @@ better to just multiply the transformations together. :rtype: int :raises LibsemigroupsError: - if the values *i* and *j* are greater than or equal to + if *i* or *j* is greater than or equal to :any:`FroidurePin.current_size`. )pbdoc"); @@ -283,7 +283,7 @@ elements are sorted, or :any:`UNDEFINED` if *i* is greater than Returns the position corresponding to a word. -This function returns the position in *fp* corresponding to the the word +This function returns the position in *fp* corresponding to the word *w* (in the generators). No enumeration is performed, and :any:`UNDEFINED` is returned if the position of the element corresponding to *w* cannot be determined. @@ -365,7 +365,7 @@ is that the resulting factorisation may not be minimal. :param x: a possible element, or index of element, to factorise. :type x: Element | int -:returns: Returns a word in the generators which evaluates to *x*. +:returns: A word in the generators which evaluates to *x*. :rtype: list[int] :raises LibsemigroupsError: @@ -548,7 +548,7 @@ Add a copy of an element to the generators. This function can be used to add new generators to an existing :any:`FroidurePin` instance in such a way that any previously enumerated data is preserved and not recomputed, or copied. This can be faster than recomputing -the semigroup generated by the old generators and the new generators.This +the semigroup generated by the old generators and the new generators. This function changes the semigroup in-place, thereby invalidating possibly previously known data about the semigroup, such as the left or right Cayley graphs, number of idempotents, and so on. @@ -863,7 +863,7 @@ in the same state as if it had just been constructed from *gens*. Find the position of an element with enumeration if necessary. -This function the position of *x* in a :any:`FroidurePin` instance, or +This function returns the position of *x* in a :any:`FroidurePin` instance, or :any:`UNDEFINED` if *x* is not an element. :param x: a possible element. From eafc9b6ca264c8094b4c2b89b14f68cc3f6e4abe Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:00:28 +0100 Subject: [PATCH 03/24] Fix Gabow documentation --- src/gabow.cpp | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/gabow.cpp b/src/gabow.cpp index b5766cf78..0ddfb90c0 100644 --- a/src/gabow.cpp +++ b/src/gabow.cpp @@ -102,7 +102,7 @@ This function constructs a :any:`Gabow` object from a :any:`WordGraph` *wg*. Returns a list containing the strongly connected component with given index. -This function returns a list containing the strongly connected components with +This function returns a list containing the strongly connected component with index *i* of the :any:`WordGraph` (returned by :any:`Gabow.word_graph`) used to construct the :any:`Gabow` instance. @@ -113,7 +113,7 @@ to construct the :any:`Gabow` instance. :rtype: list[int] :raises LibsemigroupsError: - if there is *i* is greater than or equal to + if *i* is greater than or equal to :any:`number_of_components`. .. note:: @@ -131,8 +131,8 @@ to construct the :any:`Gabow` instance. Returns a list containing the strongly connected component of a given node. -This function returns a list containing the strongly connected components of -the node *n* of the :any:`WordGraph` (returned by :any:`Gabow.word_graph` ) used to +This function returns a list containing the strongly connected component of +the node *n* of the :any:`WordGraph` (returned by :any:`Gabow.word_graph`) used to construct the :any:`Gabow` instance. :param n: the node. @@ -262,8 +262,8 @@ Returns the root of the strongly connected component containing a given node. This function returns the root of the strongly connected component containing the node *n* of the underlying :any:`WordGraph`. Two nodes ``a`` and ``b`` -belong to the same strongly connected component if and only if ``root_of(a) == -root_of(b)``. +belong to the same strongly connected component if and only if +``root_of(a) == root_of(b)``. :param n: the node. :type n: int From 4d67e4c29f9bda1b0c1bf3924bd73e428aaf5e5e Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:13:18 +0100 Subject: [PATCH 04/24] Fix hpcombi documentation --- src/hpcombi.cpp | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/hpcombi.cpp b/src/hpcombi.cpp index 7245cc02c..62060a852 100644 --- a/src/hpcombi.cpp +++ b/src/hpcombi.cpp @@ -496,7 +496,8 @@ item in position ``i`` is the number of occurrences of ``i`` in *self*. :returns: The counts. :rtype: Vect16 -.. warning: Values in *self* larger than ``15`` are ignored. +.. warning:: + Values in *self* larger than ``15`` are ignored. .. doctest:: @@ -600,7 +601,7 @@ Construct a :any:`PTransf16` from a list of images. This function constructs a :any:`PTransf16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`PTransf16` -is fixed points at the end. +is padded with fixed points at the end. :param img: The list of images. :type img: list[int] @@ -625,9 +626,9 @@ is fixed points at the end. Construct from domain and image. -Constructs a partial transformation of degree *n* such that ``(dom[i])f = +Constructs a partial transformation of degree ``16`` such that ``(dom[i])f = im[i]`` for all ``i`` and which is undefined (``255`` represents undefined in -this context) on every other value in the range :math:`[0, n)`. +this context) on every other value in the range :math:`[0, 16)`. :param dom: the domain. :type dom: list[int] @@ -812,8 +813,8 @@ Returns a bit mask (as an ``int``) for the image of *self* (or its complement). This function returns a bitset mask for the image of *self* or its complement depending on the value of *complement*. If *complement* is ``True``, then the -returned mask has ``1`` in bit ``i`` if and only if ``i`` is in the image of -*self*. If *complement* is ``False``, then the returned mask has ``0`` in bit +returned mask has ``1`` in bit ``i`` if and only if ``i`` is not in the image of +*self*. If *complement* is ``False``, then the returned mask has ``1`` in bit ``i`` if and only if ``i`` is in the image of *self*. :param complement: whether or not the complement is sought (defaults to ``False``). @@ -881,8 +882,8 @@ Returns a bit mask (as an ``int``) for the domain of *self* (or its complement). This function returns a bitset mask for the domain of *self* or its complement depending on the value of *complement*. If *complement* is ``True``, then the -returned mask has ``1`` in bit ``i`` if and only if ``i`` is in the domain of -*self*. If *complement* is ``False``, then the returned mask has ``0`` in bit +returned mask has ``1`` in bit ``i`` if and only if ``i`` is not in the domain of +*self*. If *complement* is ``False``, then the returned mask has ``1`` in bit ``i`` if and only if ``i`` is in the domain of *self*. :param complement: whether or not the complement is sought (defaults to ``False``). @@ -1025,9 +1026,9 @@ Returns a mask for the fixed points of a partial transformation. This function returns a mask for the fixed points of *self* or its complement depending on the value of *complement*. If *complement* is ``True``, then the -returned mask has ``255`` in position ``i`` for every fixed point ``i`` of -*self* and ``0`` (undefined) otherwise. If *complement* is ``False``, then -``0`` and ``255`` are switched in the output. +returned mask has ``255`` in position ``i`` for every non-fixed point ``i`` of +*self* and ``0`` otherwise. If *complement* is ``False``, then ``0`` and ``255`` +are switched in the output. :param complement: whether or not the complement is sought (defaults to ``False``). :type complement: bool @@ -1060,8 +1061,8 @@ Returns a bit mask (as an ``int``) for the fixed, or non-fixed, points of *self* This function returns a bitset mask for the fixed points of *self* or the non-fixed points of *self* depending on the value of *complement*. If *complement* is ``True``, then the returned mask has ``1`` in bit ``i`` if and -only if ``i`` is fixed by *self*. If *complement* is ``False``, then the -returned mask has ``0`` in bit ``i`` if and only if ``i`` is fixed by *self*. +only if ``i`` is not fixed by *self*. If *complement* is ``False``, then the +returned mask has ``1`` in bit ``i`` if and only if ``i`` is fixed by *self*. :param complement: whether or not the complement is sought (defaults to ``False``). :type complement: bool @@ -1179,7 +1180,7 @@ This function returns the largest integer ``i`` such that Returns the number of fixed points. This function returns the number of integers ``i`` such that -``self[i] != i`` and ``i < 16``. +``self[i] == i`` and ``i < 16``. :returns: The number of fixed points. :rtype: int @@ -2156,7 +2157,7 @@ This class belongs to the ``hpcombi`` subpackage of ``libsemigroups_pybind11``. The functionality described on this page is only available if :any:`LIBSEMIGROUPS_HPCOMBI_ENABLED` is ``True``. -:any:`Perm16` inherits from :any:`PTransf16`. +:any:`PPerm16` inherits from :any:`PTransf16`. )pbdoc"); //////////////////////////////////////////////////////////////////////// @@ -2350,7 +2351,7 @@ Returns the inverse permutation. This function returns the inverse of *self*. The inverse of a partial perm :math:`x` is the unique partial permutation :math:`y` such that :math:`xyx = x` -and :math:`xyx = x`. +and :math:`yxy = y`. :returns: The inverse of *self*. :rtype: PPerm16 From a45167b009ece91f5cfc5fb922ca4e90c731a93d Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:18:10 +0100 Subject: [PATCH 05/24] Fix Kambites documentation --- src/kambites.cpp | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/kambites.cpp b/src/kambites.cpp index d3e1f526e..589f96817 100644 --- a/src/kambites.cpp +++ b/src/kambites.cpp @@ -49,11 +49,11 @@ small overlap monoids. This page describes the class :any:`Kambites` for determining the small overlap class of a presentation, and, for small overlap monoids (those -with small overlap class 4 or higher) checking equality of words and for +with small overlap class 4 or higher) checking equality of words and computing normal forms. Note that a :any:`Kambites` instance represents a congruence on the free monoid or semigroup containing the rules of a -presentation used to construct the instance, and the -:any:`Kambites.generating_pairs`. As such generating pairs or rules are +presentation used to construct the instance, and the pairs returned by +:any:`Kambites.generating_pairs`. As such, generating pairs or rules are interchangeable in the context of :any:`Kambites` objects. .. seealso:: :any:`Runner`. @@ -73,7 +73,7 @@ interchangeable in the context of :any:`Kambites` objects. auto extra_detail = R"pbdoc(:any:`Kambites` instances can only be used to compute two-sided congruences, and so the first parameter *knd* must always be ``congruence_kind.twosided``. The parameter *knd* is -included for uniformity of interface between with +included for uniformity of interface among :any:`KnuthBendix`, :any:`ToddCoxeter`, and :any:`Congruence`.)pbdoc"sv; auto extra_raises = R"pbdoc( @@ -100,6 +100,10 @@ instances can only compute the number of classes if the condition of the previous sentence is fulfilled, and in this case the number of classes is always :any:`POSITIVE_INFINITY`. Otherwise an exception is raised.)pbdoc"sv; + extra_raises = R"pbdoc( +:raises LibsemigroupsError: + if :any:`small_overlap_class` is not at least :math:`4`. +)pbdoc"sv; def_number_of_classes( thing, @@ -164,8 +168,8 @@ at least :math:`n`. :returns: The greatest positive integer :math:`n` such that the finitely - semigroup or monoid represented by *self* satisfies the condition - :math:`C(n)` ; or :any:`POSITIVE_INFINITY` if no word occurring in a + presented semigroup or monoid represented by *self* satisfies the condition + :math:`C(n)`; or :any:`POSITIVE_INFINITY` if no word occurring in a relation can be written as a product of pieces. :rtype: int | PositiveInfinity @@ -184,7 +188,7 @@ at least :math:`n`. Returns the generalised suffix tree used to compute pieces. This function returns the generalised suffix tree :any:`Ukkonen` object -containing the relation words of a :any:`Kambites` object, that +containing the relation words of a :any:`Kambites` object, which is used to determine the pieces, and decompositions of the relation words. :returns: @@ -229,7 +233,7 @@ is used to determine the pieces, and decompositions of the relation words. :sig=(k: Kambites) -> bool: Function for checking if the finitely presented semigroup or monoid defined by -a :any:`Kambites` object obviously has infinite many classes. +a :any:`Kambites` object obviously has infinitely many classes. This function returns ``True`` if the finitely presented semigroup or monoid defined by a :any:`Kambites` object is obviously infinite; @@ -245,7 +249,7 @@ defined by a :any:`Kambites` object is obviously infinite; bool .. note:: - If this function returns ``False``, it is still possible that finitely + If this function returns ``False``, it is still possible that the finitely presented semigroup or monoid defined by *k* is infinite. )pbdoc"); } // bind_kambites From d3ac52bffbda49f0bacc2542ea7c3b095a752346 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:20:45 +0100 Subject: [PATCH 06/24] Fix KnuthBendixImpl documentation --- src/knuth-bendix-impl.cpp | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/knuth-bendix-impl.cpp b/src/knuth-bendix-impl.cpp index 77fbe9cbe..ae01dcd21 100644 --- a/src/knuth-bendix-impl.cpp +++ b/src/knuth-bendix-impl.cpp @@ -147,7 +147,7 @@ The default value is ``128``. A value of ``1`` means :any:`Runner.run` should attempt to add each rule as it is created without waiting for rules to accumulate. -:return: The batch size. +:return: The maximum number of pending rules. :rtype: int .. seealso:: :any:`Runner.run`. @@ -167,7 +167,7 @@ The default value is ``128``, and should be set to ``1`` if :any:`Runner.run` should attempt to add each rule as it is created without waiting for rules to accumulate. -:param val: The new value of the batch size. +:param val: The new maximum number of pending rules. :type val: int :return: *self*. @@ -239,7 +239,7 @@ Return the maximum length of overlaps to be considered. This function returns the maximum length of the overlap of two left hand sides of rules that should be considered in :any:`Runner.run`. -:return: The maximum overlap length +:return: The maximum overlap length. :rtype: int | PositiveInfinity .. seealso:: :any:`Runner.run`. @@ -259,7 +259,7 @@ of rules that should be considered in :any:`Runner.run`. Set the maximum length of overlaps to be considered. This function can be used to specify the maximum length of the overlap of two -left hand sides of rules that should be considered in :any:`Runner.run`. +left hand sides of rules that should be considered in :any:`Runner.run`. If this value is less than the longest left hand side of a rule, then :any:`Runner.run` can terminate without the system being confluent. @@ -284,14 +284,14 @@ If this value is less than the longest left hand side of a rule, then Return the maximum number of rules. This member function returns the (approximate) maximum number of rules that the -system should contain. If this is number is exceeded in calls to :any:`Runner.run` +system should contain. If this number is exceeded in calls to :any:`Runner.run` or :any:`knuth_bendix.by_overlap_length`, then they will terminate and the system may not be confluent. :return: The maximum number of rules the system should contain. :rtype: int | PositiveInfinity -.. seealso:: :any:`Runner.run`. +.. seealso:: :any:`Runner.run`. )pbdoc"); thing.def( @@ -308,7 +308,7 @@ system may not be confluent. Set the maximum number of rules. This member function sets the (approximate) maximum number of rules that the -system should contain. If this is number is exceeded in calls to :any:`Runner.run` +system should contain. If this number is exceeded in calls to :any:`Runner.run` or :any:`knuth_bendix.by_overlap_length`, then they will terminate and the system may not be confluent. @@ -393,9 +393,9 @@ Return the current number of inactive rules. R"pbdoc( :sig=(self: KnuthBendix) -> int: -Return the number of rules that have been created +Return the number of rules that have been created. -Return the total number of Rule instances that have been created whilst whilst +Return the total number of Rule instances that have been created whilst the Knuth-Bendix algorithm has been running. Note that this is not the sum of :any:`number_of_active_rules` and :any:`number_of_inactive_rules`, due to the re-initialisation of rules where possible. From 484795fab157677b96e6345e01a7e245e1815f64 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:22:38 +0100 Subject: [PATCH 07/24] Fix KnuthBendix documentation --- src/knuth-bendix.cpp | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/knuth-bendix.cpp b/src/knuth-bendix.cpp index c058082f3..21802eeef 100644 --- a/src/knuth-bendix.cpp +++ b/src/knuth-bendix.cpp @@ -120,7 +120,7 @@ the current rules in the :py:class:`KnuthBendix` instance. Return a copy of the active rules. -This member function returns an iterator yielding of the pairs of strings +This member function returns an iterator yielding the pairs of strings which represent the rewriting rules. The first entry in every such pair is greater than the second according to the reduction ordering of the :py:class:`KnuthBendix` instance. The rules are sorted @@ -136,12 +136,12 @@ entry. R"pbdoc( :sig=(self: KnuthBendix) -> list[str]: -Return the node labels of the Gilman :py:class:`WordGraph` +Return the node labels of the Gilman :py:class:`WordGraph`. Return the node labels of the Gilman :py:class:`WordGraph`, corresponding to the unique prefixes of the left-hand sides of the rules of the rewriting system. -:return: The node labels of the Gilman :py:class:`WordGraph` +:return: The node labels of the Gilman :py:class:`WordGraph`. :rtype: list[str] .. seealso:: :any:`gilman_graph`. @@ -241,7 +241,7 @@ before those overlaps of length :math:`n + 1`. py::arg("kb1"), py::arg("kb2"), R"pbdoc( -:sig=(kb1: KnuthBendix, kb2: KnuthBendix) -> list[list[list[int]] | list[str]]: +:sig=(kb1: KnuthBendix, kb2: KnuthBendix) -> list[list[list[int]]] | list[list[str]]: :only-document-once: Find the non-trivial classes of the quotient of one @@ -259,13 +259,13 @@ non-trivial classes of *kb1* in *kb2* if there are only finitely many finite such classes, regardless of whether or not *kb2* or *kb1* has infinitely many classes. -:param kb1: the instance to compute the partition. +:param kb1: the instance to compute the partition with. :type kb1: KnuthBendix :param kb2: the instance whose normal forms will be partitioned. :type kb2: KnuthBendix :returns: The non-trivial classes of *kb1* in *kb2*. -:rtype: list[list[list[int]] | list[str]] +:rtype: list[list[list[int]]] | list[list[str]] :raises LibsemigroupsError: if *kb1* has infinitely many classes and *kb2* has finitely many classes (so @@ -312,7 +312,7 @@ classes. :sig=(kb: KnuthBendix) -> bool: :only-document-once: -Check if the all rules are reduced with respect to each other. +Check if all rules are reduced with respect to each other. :param kb: the :any:`KnuthBendix` instance defining the rules that are @@ -322,7 +322,7 @@ Check if the all rules are reduced with respect to each other. :returns: ``True`` if for each pair :math:`(A, B)` and :math:`(C, D)` of rules stored within the :any:`KnuthBendix` instance, :math:`C` is neither a - subword of :math:`A` nor :math:`B`. Returns ``False`` otherwise. + subword of :math:`A` nor of :math:`B`. Returns ``False`` otherwise. :rtype: bool )pbdoc"); } // bind_knuth_bendix From c47a898796acb89cbd6dfc1022f35ae435273616 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:28:18 +0100 Subject: [PATCH 08/24] Fix Konieczny documentation --- src/konieczny.cpp | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/src/konieczny.cpp b/src/konieczny.cpp index 801b92d5a..1f395ba2e 100644 --- a/src/konieczny.cpp +++ b/src/konieczny.cpp @@ -83,7 +83,6 @@ Copy a Konieczny. py::arg("gens"), R"pbdoc( :sig=(self: Konieczny, gens: list[Element]) -> None: -:only-document-once: Construct from generators. @@ -93,7 +92,7 @@ not count as distinct elements, they do count as distinct generators. In other words, the generators are precisely (a copy of) *gens* in the same order they occur in *gens*. -:param gens: the generators represented by this. +:param gens: the generators. :type gens: list[Element] :raises LibsemigroupsError: if *gens* is empty. @@ -117,8 +116,7 @@ same (logical) state as if it had just been default-constructed. // This constructor can't be used directly so isn't documented. thing.def(py::init<>(), R"pbdoc( -:sig=(self: Konieczny, gens: list[Element]) -> None: -:only-document-once: +:sig=(self: Konieczny) -> None: )pbdoc"); thing.def("add_generator", @@ -139,7 +137,7 @@ times. :rtype: Konieczny :raises LibsemigroupsError: - if the degree of *x* is incompatible with the existing degree. + if the degree of *gen* is incompatible with the existing degree. :raises LibsemigroupsError: if :any:`started` returns ``True``. )pbdoc"); @@ -165,10 +163,10 @@ See :any:`Konieczny.add_generator` for a detailed description. :rtype: Konieczny :raises LibsemigroupsError: - the degree of any item in *coll* is incompatible + if the degree of any item in *coll* is incompatible with the existing degree (if any). :raises LibsemigroupsError: - :any:`started` returns ``True``. + if :any:`started` returns ``True``. )pbdoc"); thing.def( "current_D_classes", @@ -317,10 +315,10 @@ Returns the current number of :math:`\mathscr{L}`-classes. R"pbdoc( :sig=(self: Konieczny) -> int: -Returns the current number of regular :math:`\mathscr{R}`-classes. +Returns the current number of :math:`\mathscr{R}`-classes. :returns: - The number of :math:`\mathscr{L}`-classes so far enumerated. + The number of :math:`\mathscr{R}`-classes so far enumerated. :rtype: int )pbdoc"); @@ -329,7 +327,7 @@ Returns the current number of regular :math:`\mathscr{R}`-classes. R"pbdoc( :sig=(self: Konieczny) -> int: -Returns the current number of regular :math:`\mathscr{D}`-classes +Returns the current number of regular :math:`\mathscr{D}`-classes. :returns: The number of regular :math:`\mathscr{D}`-classes so far enumerated. @@ -382,7 +380,7 @@ Returns the current size. :returns: The number of elements so far enumerated. :rtype: int -.. seealso:: :any:`Konieczny.size`. +.. seealso:: :any:`Konieczny.size`. )pbdoc"); thing.def( "D_class_of_element", @@ -433,7 +431,8 @@ This function returns the generator of *self* with index *pos*. :rtype: Element :raises LibsemigroupsError: - if the value of *pos* is greater than :any:`number_of_generators()`. + if the value of *pos* is greater than or equal to + :any:`Konieczny.number_of_generators`. :complexity: Constant. @@ -449,12 +448,12 @@ This function returns the generator of *self* with index *pos*. Test regularity of an element. This function returns ``True`` if *x* is a regular element -and ``False`` if it is not. +and ``False`` if it is not. If *x* is not an element of *self*, then ``False`` is also returned. -:param x: a possible element. +:param x: an element. :type x: Element -:returns: Whether or not *x* belongs to *self*. +:returns: Whether or not *x* is a regular element. :rtype: bool )pbdoc"); thing.def("number_of_D_classes", @@ -594,7 +593,7 @@ This function triggers a full enumeration. :returns: The size. :rtype: int -.. seealso:: :any:`current_size`. +.. seealso:: :any:`current_size`. )pbdoc"); py::class_ thing2( @@ -609,7 +608,7 @@ details. :any:`Konieczny.DClass` objects cannot be directly constructed; instead should obtain a :math:`\mathscr{D}`-class by calling :any:`Konieczny.D_class_of_element`. -.. seealso:: :any:`Konieczny`.)pbdoc"); +.. seealso:: :any:`Konieczny`.)pbdoc"); thing2.def("__repr__", [](typename Konieczny_::DClass const& self) { return to_human_readable_repr>(self); @@ -633,7 +632,7 @@ should obtain a :math:`\mathscr{D}`-class by calling Test membership of an element. Given an element *x*, this function returns whether *x* is an element of the -:math:`\mathscr{D}`-class represented by *self* . This function triggers the +:math:`\mathscr{D}`-class represented by *self*. This function triggers the computation of most of the frame for *self*, if it is not already known. :param x: the element. From e248b7294a94c53134d410e349f54b804c626d2b Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:37:31 +0100 Subject: [PATCH 09/24] Fix Matrix documentation --- src/matrix.cpp | 51 +++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/src/matrix.cpp b/src/matrix.cpp index 1d87dae9a..d02d27511 100644 --- a/src/matrix.cpp +++ b/src/matrix.cpp @@ -373,10 +373,10 @@ submodule :any:`libsemigroups_pybind11.matrix`. thing.def( "__setitem__", [](Mat& mat, size_t r, py::list row) { - if (row.size() != mat.number_of_rows()) { + if (row.size() != mat.number_of_cols()) { LIBSEMIGROUPS_EXCEPTION( "invalid row length, expected {}, but found {}", - mat.number_of_rows(), + mat.number_of_cols(), row.size()); } auto py_int_type = py::globals()["__builtins__"].attr("int"); @@ -511,7 +511,7 @@ Copy a :any:`Matrix` object. R"pbdoc( :sig=(self: Matrix, x: Matrix, y: Matrix) -> None: -Multiply two matrices and stores the product in *self*. +Multiply two matrices and store the product in *self*. :param x: first matrix to multiply. :type x: Matrix @@ -538,7 +538,7 @@ Transposes the matrix in-place. Swaps the contents of *self* with the contents of *that*. -:param that: the matrix to swap contents with +:param that: the matrix to swap contents with. :type that: Matrix)pbdoc"); thing.def( "scalar_zero", @@ -555,7 +555,7 @@ matrix. .. doctest:: >>> from libsemigroups_pybind11 import Matrix, MatrixKind, POSITIVE_INFINITY - >>> x = Matrix(MatrixKind.MinPlusTrunc, 11 ,[[0, 1, 1], [0] * 3, [1] * 3]) + >>> x = Matrix(MatrixKind.MinPlusTrunc, 11, [[0, 1, 1], [0] * 3, [1] * 3]) >>> x.scalar_zero() == POSITIVE_INFINITY True)pbdoc"); thing.def( @@ -573,7 +573,7 @@ matrix. .. doctest:: >>> from libsemigroups_pybind11 import Matrix, MatrixKind - >>> x = Matrix(MatrixKind.MinPlusTrunc, 11 ,[[0, 1, 1], [0] * 3, [1] * 3]) + >>> x = Matrix(MatrixKind.MinPlusTrunc, 11, [[0, 1, 1], [0] * 3, [1] * 3]) >>> x.scalar_one() 0)pbdoc"); @@ -685,15 +685,15 @@ Construct a matrix from rows. :param rows: the rows of the matrix. :type rows: list[list[int | PositiveInfinity | NegativeInfinity]] -:raise TypeError: if *kind* is +:raises TypeError: if *kind* is :any:`MatrixKind.MaxPlusTrunc`, :any:`MatrixKind.MinPlusTrunc`, or :any:`MatrixKind.NTP`. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if the entries in *rows* are not of equal length. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if any of the entries of the lists in *rows* do not belong to the underlying semiring. )pbdoc"); @@ -712,7 +712,7 @@ Construct an uninitialized *r* by *c* matrix. :param c: the number of columns in the matrix. :type c: int -:raise TypeError: if *kind* is +:raises TypeError: if *kind* is :any:`MatrixKind.MaxPlusTrunc`, :any:`MatrixKind.MinPlusTrunc`, or :any:`MatrixKind.NTP`. @@ -741,7 +741,7 @@ Construct an uninitialized *r* by *c* matrix. R"pbdoc( :sig=(self: Matrix, kind: MatrixKind, threshold: int, r: int, c: int) -> None: -Construct an uninitialized `r` by `c` matrix. +Construct an uninitialized *r* by *c* matrix. :param kind: specifies the underlying semiring. :type kind: MatrixKind @@ -749,13 +749,13 @@ Construct an uninitialized `r` by `c` matrix. :param threshold: the threshold of the underlying semiring. :type threshold: int -:param r: the number of rows in the matrix +:param r: the number of rows in the matrix. :type r: int -:param c: the number of columns in the matrix +:param c: the number of columns in the matrix. :type c: int -:raise TypeError: +:raises TypeError: if *kind* is not :any:`MatrixKind.MaxPlusTrunc` or :any:`MatrixKind.MinPlusTrunc`. @@ -788,14 +788,14 @@ Construct a matrix from threshold and rows. :param rows: the rows of the matrix. :type rows: list[list[int | PositiveInfinity | NegativeInfinity]] -:raise TypeError: +:raises TypeError: if *kind* is not :any:`MatrixKind.MaxPlusTrunc` or :any:`MatrixKind.MinPlusTrunc`. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if the entries in *rows* are not of equal length. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if any of the entries of the lists in *rows* do not belong to the underlying semiring. )pbdoc"); @@ -862,12 +862,12 @@ Construct a matrix from threshold, period, and rows. :param rows: the rows of the matrix. :type rows: list[list[int]] -:raise TypeError: if *kind* is not :any:`MatrixKind.NTP`. +:raises TypeError: if *kind* is not :any:`MatrixKind.NTP`. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if the entries in *rows* are not of equal length. -:raise LibsemigroupsError: +:raises LibsemigroupsError: if any of the entries of the lists in *rows* do not belong to the underlying semiring.)pbdoc"); thing.def( @@ -877,7 +877,7 @@ Construct a matrix from threshold, period, and rows. R"pbdoc( :sig=(self: Matrix, kind: MatrixKind, threshold: int, period: int, r: int, c: int) -> None: -Construct an uninitialized `r` by `c` matrix with threshold and period. +Construct an uninitialized *r* by *c* matrix with threshold and period. :param kind: specifies the underlying semiring. :type kind: MatrixKind @@ -894,7 +894,7 @@ Construct an uninitialized `r` by `c` matrix with threshold and period. :param c: the number of columns in the matrix. :type c: int -:raise TypeError: if *kind* is not :any:`MatrixKind.NTP`. +:raises TypeError: if *kind* is not :any:`MatrixKind.NTP`. .. doctest:: @@ -937,7 +937,8 @@ This function returns the identity matrix of the same dimensions as *self*. [](Mat const& x) { return matrix::period(x); }, py::arg("x"), R"pbdoc( -:sig=(x:Matrix)->int: +:sig=(x: Matrix) -> int: + Returns the period of an ntp matrix. This function returns the period of the ntp matrix *x* using its underlying semiring. @@ -973,7 +974,7 @@ the ntp matrix *x* using its underlying semiring. [](BMat<> const& x) { return matrix::row_space_size(x); }, py::arg("x"), R"pbdoc( -:sig=(x:Matrix)->int: +:sig=(x: Matrix) -> int: Returns the size of the row space of a boolean matrix. This function returns the size of the row space of the boolean matrix *x*. @@ -1008,7 +1009,7 @@ the size of the row space of the boolean matrix *x*. R"pbdoc( :sig=(x: Matrix) -> list[list[int | PositiveInfinity | NegativeInfinity]]: :only-document-once: -Returns a row space basis of a matrix as a list of lists. The matrix *x* which +Returns a row space basis of a matrix as a list of lists. The matrix *x* must be one of: * :any:`MatrixKind.Boolean` From 432606573e30ebe5b7bf50c854a2ef3bed152480 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:38:43 +0100 Subject: [PATCH 10/24] Fix is_obviously_infinite documentation --- src/obvinf.cpp | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/obvinf.cpp b/src/obvinf.cpp index 33811d0bf..a5ee77b7d 100644 --- a/src/obvinf.cpp +++ b/src/obvinf.cpp @@ -41,7 +41,7 @@ namespace libsemigroups { :sig=(p: Presentation) -> bool: Function for checking if the finitely presented semigroup or monoid -defined by a :any:`Presentation` object is obviously infinite or not. +defined by a :any:`Presentation` object is obviously infinite. This function returns ``True`` if the finitely presented semigroup or monoid defined by the :any:`Presentation` object *p* is obviously infinite. @@ -55,10 +55,10 @@ monoid defined by the :any:`Presentation` object *p* is obviously infinite. :rtype: bool -:raises LibsemigroupsError: If the presentation *p* is not valid. +:raises LibsemigroupsError: if the presentation *p* is not valid. .. note:: - If this function returns ``False``, it is still possible that semigroup or + If this function returns ``False``, it is still possible that the semigroup or monoid defined by *p* is infinite. )pbdoc"); @@ -72,7 +72,7 @@ monoid defined by the :any:`Presentation` object *p* is obviously infinite. :only-document-once: Function for checking if the finitely presented semigroup or monoid -defined by a :any:`Presentation` object is obviously infinite or not. +defined by a :any:`Presentation` object is obviously infinite. This function returns ``True`` if the finitely presented semigroup or monoid defined by the :any:`Presentation` object *p* is obviously infinite. @@ -86,10 +86,10 @@ monoid defined by the :any:`Presentation` object *p* is obviously infinite. :rtype: bool -:raises LibsemigroupsError: If the presentation *p* is not valid. +:raises LibsemigroupsError: if the presentation *p* is not valid. .. note:: - If this function returns ``False``, it is still possible that semigroup or + If this function returns ``False``, it is still possible that the semigroup or monoid defined by *p* is infinite. )pbdoc"); @@ -103,7 +103,7 @@ monoid defined by the :any:`Presentation` object *p* is obviously infinite. :sig=(tc: ToddCoxeter) -> bool: Function for checking if the quotient of a finitely presented semigroup or -monoid defined by a :any:`ToddCoxeter` object is obviously infinite or not. +monoid defined by a :any:`ToddCoxeter` object is obviously infinite. This function returns ``True`` if the quotient of the finitely presented semigroup or monoid defined by the :any:`ToddCoxeter` object *tc* is obviously From 10c54b3907650735b9c40a56a7672f51489ac554 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:41:27 +0100 Subject: [PATCH 11/24] Fix order documentation --- src/order.cpp | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/order.cpp b/src/order.cpp index 1480d7ba8..94d108526 100644 --- a/src/order.cpp +++ b/src/order.cpp @@ -56,7 +56,7 @@ The valid values are: .. py:attribute:: Order.shortlex :value: - The short-lex ordering. Word are first ordered by length, and then + The short-lex ordering. Words are first ordered by length, and then lexicographically. .. py:attribute:: Order.lex @@ -87,7 +87,7 @@ The valid values are: R"pbdoc( :sig=(x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two values of type :any:`str` or ``list[int]`` using using lexicographical ordering. +Compare two values of type :any:`str` or ``list[int]`` using lexicographical ordering. :param x: the first object for comparison. :type x: str | list[int] @@ -133,7 +133,7 @@ Compare two values of type :any:`str` or ``list[int]`` using shortlex ordering. :param y: the second object for comparison. :type y: str | list[int] -:returns: The boolean value ``True`` if *x`* is short-lex less than *y*, and ``False`` otherwise. +:returns: The boolean value ``True`` if *x* is short-lex less than *y*, and ``False`` otherwise. :rtype: bool :complexity: At most :math:`O(n)` where :math:`n` is the minimum of the length of *x* and the length of *y*. @@ -165,7 +165,9 @@ Compare two values of type :any:`str` or ``list[int]`` using shortlex ordering. :only-document-once: Compare two values of type :any:`str` or ``list[int]`` using recursive-path ordering. -Compare two values of type :any:`str` or ``list[int]`` using the recursive path comparison described in :cite:`Jantzen2012aa` (Definition 1.2.14, page 24). +This function compares two values of type :any:`str` or ``list[int]`` using the +recursive-path ordering described in :cite:`Jantzen2012aa` (Definition 1.2.14, +page 24). If :math:`u, v\in X ^ {*}`, :math:`u \neq v`, and :math:`u = a'u`, :math:`v = bv'` for some :math:`a,b \in X`, :math:`u',v'\in X ^ {*}`, then @@ -187,7 +189,9 @@ is based on the source code of :cite:`Holt2018aa`. :returns: The boolean value ``True`` if *x* is less than *y* with respect to the recursive path ordering, and ``False`` otherwise. :rtype: bool -:warning: This function has significantly worse performance than :any:`shortlex_compare` and :any:`lexicographical_compare`. +.. warning:: + This function has significantly worse performance than + :any:`shortlex_compare` and :any:`lexicographical_compare`. )pbdoc"); // No prefix because not in subpackage From b790971639210f283d60a51591f676cc1ecd9917 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:44:55 +0100 Subject: [PATCH 12/24] Fix Paths doc --- src/paths.cpp | 39 +++++++++++++++++++-------------------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/src/paths.cpp b/src/paths.cpp index 1d1c8e524..d57587682 100644 --- a/src/paths.cpp +++ b/src/paths.cpp @@ -104,12 +104,12 @@ Copy a :any:`Paths` object. Reinitialize a :any:`Paths` object. This function puts a :any:`Paths` object back into the same state as if it had -been newly constructs from the :any:`WordGraph` *wg*. +been newly constructed from the :any:`WordGraph` *wg*. :param wg: the word graph. :type wg: WordGraph -:returns: *self* +:returns: *self*. :rtype: Paths )pbdoc"); @@ -170,7 +170,7 @@ return value of :any:`count` decreases by ``1``). Get the current target node of the path labelled by :any:`Paths.get`. This function returns the current target node of the path labelled by :any:`Paths.get`. If there is no such path (because, for example, the source -node hasn't been defined, then :any:`UNDEFINED` is returned). +node has not been defined), then :any:`UNDEFINED` is returned. :returns: The current target node of the path labelled by :any:`Paths.get` or @@ -202,7 +202,7 @@ Get the current path in the range. :sig=(self: Paths) -> int | PositiveInfinity: :only-document-once: -Get the maximum length of path in the range. +Get the maximum length of paths in the range. This function returns the current maximum length of paths in the range. The initial value is :any:`POSITIVE_INFINITY`. @@ -221,9 +221,9 @@ The initial value is :any:`POSITIVE_INFINITY`. R"pbdoc( :sig=(self: Paths, val: int | PositiveInfinity) -> Paths: :only-document-once: -Set the maximum length of path in the range. +Set the maximum length of paths in the range. -This function can be used to set the maximum length of path that will be +This function can be used to set the maximum length of paths that will be contained in the range. If this function is not called, then the range will contain paths of unbounded length (possibly infinitely many). @@ -245,7 +245,7 @@ contain paths of unbounded length (possibly infinitely many). "min", [](Paths_ const& self) { return self.min(); }, R"pbdoc( -Get the minimum length of path in the range. This function returns the +Get the minimum length of paths in the range. This function returns the current minimum length of paths in the range. The initial value is ``0``. @@ -261,7 +261,7 @@ current minimum length of paths in the range. The initial value is R"pbdoc( :sig=(self: Paths, val: int) -> Paths: -Set the minimum length of path in the range. +Set the minimum length of paths in the range. This function can be used to set the minimum length of paths that will be contained in the range. If this function is not called, then the range will @@ -280,9 +280,8 @@ contain paths starting with length ``0``. p.next(); }, R"pbdoc( -Advance to the next path in the range. Advance to the current path in -the range. If :any:`at_end` returns ``True``, then this function does -nothing. +Advance to the next path in the range. If :any:`at_end` returns ``True``, +then this function does nothing. :raises LibsemigroupsError: if ``source() == UNDEFINED``. )pbdoc"); @@ -324,8 +323,8 @@ a :any:`Paths` object. The initial value is :any:`Order.shortlex`. [](Paths_ const& self) { return self.source(); }, R"pbdoc( Get the current source node of every path in the range. This function -returns the current source node of the every path in the range defined -by a :any:`Paths` object. This initial value is :any:`UNDEFINED`. +returns the current source node of every path in the range defined by a +:any:`Paths` object. The initial value is :any:`UNDEFINED`. :returns: The current source node. @@ -358,8 +357,8 @@ This function can be used to set the source node of all of the paths in the rang [](Paths_ const& self) { return self.target(); }, R"pbdoc( Get the current target node of every path in the range. This function -returns the target node of the every path in the range defined by a -:any:`Paths` object. This initial value is :any:`UNDEFINED`. +returns the target node of every path in the range defined by a :any:`Paths` +object. The initial value is :any:`UNDEFINED`. :returns: The target node. @@ -395,7 +394,7 @@ node is set to :any:`UNDEFINED`, then the range will contain every path from thing1.def("word_graph", &Paths_::word_graph, R"pbdoc( -The underlying word graph. This function returns underlying +The underlying word graph. This function returns the underlying :any:`WordGraph` of the :any:`Paths` object. This is the :any:`WordGraph` defining the paths in the range. @@ -409,7 +408,7 @@ The underlying word graph. This function returns underlying options.disable_enum_members_docstring(); py::enum_(m, "paths_algorithm", R"pbdoc( - An enum for specifying the algorithm to the functions :any:`number_of_paths`. +An enum for specifying the algorithm for the functions :any:`number_of_paths`. The valid values are: @@ -600,7 +599,7 @@ This function returns the number of paths in the word graph *wg* starting at :cite:`Guennebaud2010aa`). .. warning:: - If the number of paths exceeds ``2 ** 64``, then return value of + If the number of paths exceeds ``2 ** 64``, then the return value of this function will not be correct. )pbdoc"); @@ -668,7 +667,7 @@ length in a given range. :cite:`Guennebaud2010aa`). .. warning:: - If the number of paths exceeds ``2 ** 64``, then return value of + If the number of paths exceeds ``2 ** 64``, then the return value of this function will not be correct. .. warning:: @@ -745,7 +744,7 @@ and ending at node *target* with length in a given range. :cite:`Guennebaud2010aa`). .. warning:: - If the number of paths exceeds ``2 ** 64``, then return value of + If the number of paths exceeds ``2 ** 64``, then the return value of this function will not be correct. .. warning:: From f7f43de4c62036bc5218b7651e8fae5c484500b4 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:52:26 +0100 Subject: [PATCH 13/24] Fix PBR doc --- src/pbr.cpp | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/src/pbr.cpp b/src/pbr.cpp index 2e94f30bf..628611fe8 100644 --- a/src/pbr.cpp +++ b/src/pbr.cpp @@ -38,7 +38,7 @@ namespace libsemigroups { Class for representing PBRs. *Partitioned binary relations* (PBRs) are a -generalisation of a bipartitions, and were introduced by Martin and Mazorchuk in +generalisation of bipartitions, and were introduced by Martin and Mazorchuk in :cite:`Martin2011aa`. )pbdoc"); thing.def("__repr__", @@ -48,9 +48,9 @@ generalisation of a bipartitions, and were introduced by Martin and Mazorchuk in R"pbdoc( :sig=(self: PBR, n: int) -> None: -Construct empty PBR of given degree. +Construct an empty PBR of given degree. -:param n: the degree +:param n: the degree. :type n: int )pbdoc"); thing.def(py::init([](PBR::vector_type left, @@ -60,7 +60,7 @@ Construct empty PBR of given degree. py::arg("left"), py::arg("right"), R"pbdoc( -:sig=(self: PBR, left: list[list[int]], right: list[list[int]]) -> None: +:sig=(self: PBR, left: list[list[int]], right: list[list[int]]) -> None: Construct from adjacencies ``1`` to ``n`` and ``-1`` to ``-n``. @@ -68,19 +68,20 @@ Construct from adjacencies ``1`` to ``n`` and ``-1`` to ``-n``. The parameters *left* and *right* should be containers of ``n`` lists of integer values, so that the list in position ``i`` of *left* is the list of points adjacent to ``i`` in the :any:`PBR`, and the list in position ``i`` of *right* is the -list of points adjacent to ``n + i`` in the :any:`PBR`. A negative value ``i`` -corresponds to ``n - i``. +list of points adjacent to ``-i`` in the :any:`PBR`. A negative value ``i`` +corresponds to ``n - i`` in the underlying zero-based indexing. -:param left: container of adjacencies of ``1`` to ``n`` +:param left: container of adjacencies of ``1`` to ``n``. :type left: list[list[int]] -:param right: container of adjacencies of ``n + 1`` to ``2n``. +:param right: container of adjacencies of ``-1`` to ``-n``. :type right: list[list[int]] :raises LibsemigroupsError: if the resultant PBR: * would not describe a binary relation on an even number of points; or - * would have a point related to a point that is greater than :any:`PBR.degree`; + * would have a point related to a point whose absolute value is greater + than or equal to :any:`PBR.degree`; )pbdoc"); thing.def( py::init([](PBR::vector_type x) { return make(x); }), @@ -101,7 +102,8 @@ in the :any:`PBR` constructed. :raises LibsemigroupsError: if the resultant PBR: * would not describe a binary relation on an even number of points; or - * would have a point related to a point that is greater than :any:`PBR.degree`; + * would have a point related to a point that is greater than or equal to + :any:`PBR.number_of_points`; * *x* contains a list of points related to a point that is not sorted. )pbdoc"); @@ -113,7 +115,7 @@ Compare for less. :param that: a PBR to compare with. :type that: PBR -:returns: ``True`` if *self* is less than *that*, and ``False`` otherwise. +:returns: ``True`` if *self* is less than *that*, and ``False`` otherwise. :rtype: bool :complexity: At worst linear in :any:`PBR.degree`. @@ -126,7 +128,7 @@ Compare two PBRs for equality. :param that: a PBR to compare with. :type that: PBR -:returns: ``True`` if *self* equals *that*, and ``False`` otherwise. +:returns: ``True`` if *self* equals *that*, and ``False`` otherwise. :rtype: bool :complexity: At worst linear in :any:`PBR.degree`. @@ -151,13 +153,13 @@ Returns a newly constructed PBR equal to the product of *self* and *that*. :param that: a PBR. -type that: PBR +:type that: PBR -:returns: *self* * *that* +:returns: ``self * that``. :rtype: PBR :complexity: -Cubic in :any:`PBR.degree`. + Cubic in :any:`PBR.degree`. )pbdoc"); thing.def("__ge__", [](PBR const& a, PBR const& b) { return a >= b; }); thing.def("__gt__", [](PBR const& a, PBR const& b) { return a > b; }); @@ -177,9 +179,9 @@ Returns the nodes adjacent to the given node. :type i: int :returns: The nodes adjacent to *i*. -:rtype: int +:rtype: list[int] -:raises LibsemigroupsError: if *i* >= :any:`number_of_nodes`. +:raises LibsemigroupsError: if *i* >= :any:`PBR.number_of_points`. )pbdoc"); thing.def("degree", @@ -229,7 +231,7 @@ then bad things will happen. :raises LibsemigroupsError: if: * the :any:`PBR.degree` of *x* is not the same as the :any:`PBR.degree` of *y*; * the :any:`PBR.degree` of *self* is not the same as the :any:`PBR.degree` of *x*; or - * either *x* or *y* is the same object as `self`. + * either *x* or *y* is the same object as *self*. )pbdoc"); thing.def( "copy", @@ -254,7 +256,7 @@ Returns the identity PBR with degree ``x.degree()``. This member function returns a new :any:`PBR` with degree equal to the :any:`PBR.degree` of *x*, where every value is adjacent to its negative. Equivalently, ``i`` is -adjacent ``i + n`` and vice versa for every ``i`` less than the degree +adjacent to ``i + n`` and vice versa for every ``i`` less than the degree ``n``. :param x: A PBR. @@ -273,7 +275,7 @@ adjacent ``i + n`` and vice versa for every ``i`` less than the degree Returns the identity PBR with specified degree. This function returns a new :any:`PBR` with degree equal to *n* where every -value is adjacent to its negative. Equivalently, ``i`` is adjacent +value is adjacent to its negative. Equivalently, ``i`` is adjacent to ``i + n`` and vice versa for every ``i`` less than the degree ``n``. :param n: the degree. From 4d80efac1810f0a665dfe07511890787619c8af3 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 18:55:45 +0100 Subject: [PATCH 14/24] Fix Presentation doc --- src/present.cpp | 70 ++++++++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/src/present.cpp b/src/present.cpp index 51ca7ecb9..b7a2a7081 100644 --- a/src/present.cpp +++ b/src/present.cpp @@ -56,7 +56,7 @@ namespace libsemigroups { R"pbdoc( Presentations for semigroups and monoids. -This class can be used to construction presentations for semigroups or monoids +This class can be used to construct presentations for semigroups or monoids and is intended to be used as the input to other algorithms in ``libsemigroups_pybind11``. The idea is to provide a shallow wrapper around a collection of words of type :ref:`Word`. We refer to @@ -118,14 +118,14 @@ Return the alphabet of the presentation. :sig=(self: Presentation, n: int) -> Presentation: Set the alphabet by size. -Sets the alphabet to the the first :math:`n` values with type +Sets the alphabet to the first :math:`n` values with type :ref:`Letter`. For :any:`str`-types, we assume the order of letters to be ``a-zA-Z0-9``. :param n: the size of the alphabet. :type n: int -:returns: *self* +:returns: *self*. :rtype: Presentation :raises LibsemigroupsError: if the value of *n* is greater than the @@ -152,7 +152,7 @@ Sets the alphabet to be the letters in *lphbt*. :param lphbt: the alphabet. :type lphbt: :ref:`Word` -:returns: *self* +:returns: *self*. :rtype: Presentation :raises LibsemigroupsError: if there are duplicate letters in *lphbt*. @@ -169,7 +169,7 @@ Sets the alphabet to be the letters in *lphbt*. Set the alphabet to be the letters in the rules. -:returns: *self* +:returns: *self*. :rtype: Presentation :complexity: At most :math:`O(mn)` where :math:`m` is the number of rules, @@ -210,7 +210,7 @@ but is not given as a quotient of a free monoid. R"pbdoc( :sig=(self: Presentation, val: bool) -> Presentation: -Set whether whether the empty word is a valid relation word. +Set whether the empty word is a valid relation word. Specify whether the empty word should be a valid relation word (corresponding to *val* being ``True``), or not (corresponding to *val* being ``False``). @@ -222,10 +222,10 @@ monoid, but is not given as a quotient of a free monoid. :param val: whether the presentation can contain the empty word. :type val: bool -:returns: *self* +:returns: *self*. :rtype: Presentation -:complexity: Constant +:complexity: Constant. )pbdoc"); thing.def("in_alphabet", &Presentation_::in_alphabet, @@ -238,7 +238,7 @@ Check if a letter belongs to the alphabet or not. :param val: the letter to check. :type val: :ref:`Letter` -:returns: whether the letter belongs to the alphabet +:returns: Whether the letter belongs to the alphabet. :rtype: bool :complexity: Constant on average, worst case linear in the size of the @@ -252,8 +252,8 @@ Check if a letter belongs to the alphabet or not. Return the index of a letter in the alphabet. -After checking that *val* is in the the alphabet, get the index of a letter in -the alphabet +After checking that *val* is in the alphabet, get the index of a letter in +the alphabet. :param val: the letter. :type val: :ref:`Letter` @@ -293,7 +293,7 @@ position *i*. :param i: the index. :type i: int -:returns: the letter +:returns: The letter. :rtype: :ref:`Letter` :raises LibsemigroupsError: if *i* is not in the range :math:`[0, n)`.)pbdoc"); @@ -308,7 +308,7 @@ Check if the alphabet and rules are valid. :any:`throw_if_bad_rules` does. :complexity: - Worst case :math:`O(mnp)` where :math:`m` is the length of length of the + Worst case :math:`O(mnp)` where :math:`m` is the length of the longest word, :math:`n` is the size of the alphabet and :math:`p` is the number of rules.)pbdoc"); thing.def( @@ -381,7 +381,7 @@ Add a generator. Add the first letter not in the alphabet as a generator, and return this letter. -:returns: the letter added to the alphabet. +:returns: The letter added to the alphabet. :rtype: :ref:`Letter` )pbdoc"); @@ -417,7 +417,7 @@ Remove the letter *x* as a generator. :returns: *self*. :rtype: Presentation -:raises LibsemigroupsError: if *x* is not in `p.alphabet()`. +:raises LibsemigroupsError: if *x* is not in ``p.alphabet()``. :complexity: Average case: linear in the length of the alphabet, worst case: quadratic in the length of the alphabet. @@ -469,8 +469,8 @@ Add rules for inverses. The letter *a* with index ``i`` in *vals* is the inverse of the letter in ``alphabet()`` with index ``i``. The rules added are :math:`a_ib_i = e` where -the alphabet is :math:`\{a_1, \ldots, a_n\}` ; the 2nd parameter *vals* is -:math:`\{b_1, \ldots, b_n\}` ; and :math:`e` is the 3rd parameter. +the alphabet is :math:`\{a_1, \ldots, a_n\}`; the 2nd parameter *vals* is +:math:`\{b_1, \ldots, b_n\}`; and :math:`e` is the 3rd parameter. :param p: the presentation to add rules to. :type p: Presentation @@ -635,7 +635,7 @@ contained in *p*. :param rhs: the right-hand side of the rule. :type rhs: :ref:`Word` -:returns: whether the presentation contains the rule +:returns: Whether the presentation contains the rule. :rtype: bool :complexity: Linear in the number of rules. @@ -713,7 +713,7 @@ was in after the previous iteration. :only-document-once: Return true if the :math:`1`-relation presentation can be strongly compressed. -A :math:`1` -relation presentation is *strongly compressible* if both relation +A :math:`1`-relation presentation is *strongly compressible* if both relation words start with the same letter and end with the same letter. In other words, if the alphabet of the presentation *p* is :math:`A` and the relation words are of the form :math:`aub = avb` where :math:`a, b\in A` (possibly :math:` a = b` ) @@ -723,7 +723,7 @@ See `Section 3.2 `_ for details. :param p: the presentation. :type p: Presentation -:returns: whether the presentation is strongly compressible +:returns: Whether the presentation is strongly compressible. :rtype: bool .. seealso:: @@ -742,7 +742,7 @@ Return the sum of the lengths of the rules. :param p: the presentation. :type p: Presentation -:returns: the length of the presentation +:returns: The length of the presentation. :rtype: int )pbdoc"); @@ -767,7 +767,7 @@ lengths of its left-hand and right-hand sides. :param p: the presentation. :type p: Presentation -:returns: the index of the rule +:returns: The index of the rule. :rtype: int :raises LibsemigroupsError: if the length of ``p.rules`` is odd. @@ -792,7 +792,7 @@ is defined to be the sum of the lengths of its left-hand and right-hand sides. :param p: the presentation. :type p: Presentation -:returns: the maximum length +:returns: The maximum length. :rtype: int :raises LibsemigroupsError: if the length of ``p.rules`` is odd. @@ -965,7 +965,7 @@ rule are letters, then the greater letter is replaced by the lesser one. :only-document-once: Remove rules consisting of identical words. -Removes all instance of rules (if any) where the left-hand side and the +Removes all instances of rules (if any) where the left-hand side and the right-hand side are identical. :param p: the presentation. @@ -1110,7 +1110,7 @@ is defined to be the sum of the lengths of its left-hand and right-hand sides. :param p: the presentation. :type p: Presentation -:returns: the length of the shortest rule +:returns: The length of the shortest rule. :rtype: int :raises LibsemigroupsError: if the length of ``p.rules`` is odd. @@ -1258,7 +1258,7 @@ checks that :math:`v_i = x_j`, and therefore that :math:`(x_i^{-1})^{-1} = x_i`. :param p: the presentation. :type p: Presentation -:param vals: the values to check if the act as inverses. +:param vals: the values to check if they act as inverses. :type vals: :ref:`Word` :raises LibsemigroupsError: @@ -1305,7 +1305,7 @@ an exception is thrown. py::arg("p"), py::arg("inverses"), R"pbdoc( -:sig=(p: Presentation, inverses : Word) -> None: +:sig=(p: Presentation, inverses: Word) -> None: :only-document-once: Balance the length of the left-hand and right-hand sides. @@ -1337,12 +1337,12 @@ parameter is defined to be ``p.alphabet()``. py::arg("letters"), py::arg("inverses"), R"pbdoc( -:sig=(p: Presentation, letters: Word, inverses : Word) -> None: +:sig=(p: Presentation, letters: Word, inverses: Word) -> None: :only-document-once: Balance the length of the left-hand and right-hand sides. -This function first sorts the sides of each rules so that the larger +This function first sorts the sides of each rule so that the larger side of the rule is on the left. Then for each rule, while the last letter of the left-hand side is in *letters*, the last letter of the left-hand side is removed and the corresponding value in *inverses* is @@ -1360,7 +1360,7 @@ appended to the front of the right-hand side. :param inverses: the inverses of the letters. :type inverses: :ref:`Word` -:raises LibsemigroupsError: if throw_if_bad_alphabet_or_rules throws. +:raises LibsemigroupsError: if :any:`throw_if_bad_alphabet_or_rules` throws. :raises LibsemigroupsError: if :any:`throw_if_bad_inverses` throws when called with *letters* and @@ -1414,7 +1414,7 @@ empty word to the presentation *p*, for every cyclic permutation ``w`` of Returns the index of a rule or :any:`UNDEFINED`. This function returns the minimum index ``i`` of *lhs* such that ``p.rules[i + -1]`` equals *rhs* ; or :any:`UNDEFINED` if there is not such rule +1]`` equals *rhs*; or :any:`UNDEFINED` if there is no such rule. :param p: the presentation. :type p: Presentation @@ -1495,7 +1495,7 @@ and *rhs* is the next item in ``p.rules``. Try to detect group inverses. This function tries to deduce group theoretic inverses defined by the rules of -the presentation *p* as following: the rules of the presentation where one +the presentation *p* as follows: the rules of the presentation where one side has length 2 and the other has length 0 are detected. For any such rule we remember that the first letter is a possible inverse of the second. If rules of the form ``ab=1`` and ``ba=1`` are detected, then ``a`` has inverse ``b`` and @@ -1525,9 +1525,9 @@ raised. py::class_> thing(m, name.c_str(), R"pbdoc( -For an implementation of inverse presentations for semigroups or monoids. +An implementation of inverse presentations for semigroups or monoids. -This class can be used to construction inverse presentations for semigroups or +This class can be used to construct inverse presentations for semigroups or monoids and is intended to be used as the input to other algorithms in ``libsemigroups_pybind11``. @@ -1549,7 +1549,7 @@ from a :any:`Presentation`. :sig=(self: InversePresentation) -> None: Default constructor. -Constructs an empty :any:`InversePresentation` with no rules, no alphabet and +Constructs an empty :any:`InversePresentation` with no rules, no alphabet, and no inverses.)pbdoc"); thing.def( "copy", From df003a53bfddab4686a707ed33e3085cbb895052 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 19:03:25 +0100 Subject: [PATCH 15/24] Fix presentation examples doc --- src/presentation-examples.cpp | 255 +++++++++++++++------------------- 1 file changed, 114 insertions(+), 141 deletions(-) diff --git a/src/presentation-examples.cpp b/src/presentation-examples.cpp index 1ebbde40c..8720f809d 100644 --- a/src/presentation-examples.cpp +++ b/src/presentation-examples.cpp @@ -140,10 +140,10 @@ least congruence containing the relation :math:`a^{\sigma(a)} = a` for each resultant :math:`\sigma`-plactic monoid is known as the stylic monoid, and is given in :any:`stylic_monoid`. -:param sigma: a list representing the image of $\sigma$. +:param sigma: a list representing the image of :math:`\sigma`. :type sigma: list[int] -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation :raises LibsemigroupsError: if ``len(sigma) < 1``. @@ -267,7 +267,7 @@ A presentation for the Motzkin monoid. This function returns a monoid presentation defining the Motzkin monoid of degree *n*, as described in Theorem 4.1 of :cite:`Posner2013aa`, with the -additional relations :math:` r_i t_i l_i = r_i^ 2 ` added to fix a hole in +additional relations :math:`r_i t_i l_i = r_i^2` added to fix a hole in Lemma 4.10 which rendered the presentation as stated in the paper incorrect. :param n: the degree. @@ -310,7 +310,7 @@ This function returns a semigroup presentation defining the Fibonacci semigroup A presentation for the plactic monoid. This function returns a monoid presentation defining the plactic monoid with *n* -generators, as in see Theorem 6 of :cite:`Knuth1970aa`. +generators, as in Theorem 6 of :cite:`Knuth1970aa`. :param n: the number of generators. :type n: int @@ -403,7 +403,7 @@ generators and :math:`\frac{1}{2}n(n - 1)` relations. A presentation for the symmetric group. This function returns a monoid presentation for the symmetric group of degree -*n*, as in in Theorem A' of :cite:`Moore1897aa`. This presentation has :math:`2` +*n*, as in Theorem A' of :cite:`Moore1897aa`. This presentation has :math:`2` generators and :math:`n + 1` relations for :math:`n \geq 4`. If :math:`n<4` then there are :math:`4` relations. @@ -622,7 +622,7 @@ monoid of degree *n* due to Shutov :cite:`Shutov1960aa`, as in Theorem :sig=(n: int) -> Presentation: A presentation for the symmetric inverse monoid. -This function returns a monoid presentation defining the partial transformation +This function returns a monoid presentation defining the symmetric inverse monoid of degree *n*, as in Theorem 1.4 of :cite:`Mitchell2024aa`. :param n: the degree of the symmetric inverse monoid. @@ -738,8 +738,8 @@ of the cyclic inverse monoid of degree *n*, as in Theorem 2.17 of A presentation for the monoid of partial isometries of a cycle graph. This function returns a monoid presentation defining the monoid of partial -isometries of an :math:`n` -cycle graph, as in Theorem 2.8 of -:cite:`Fernandes2022ab` +isometries of an :math:`n`-cycle graph, as in Theorem 2.8 of +:cite:`Fernandes2022ab`. :param n: the number of vertices of the cycle graph. :type n: int @@ -782,7 +782,7 @@ This function returns a presentation for the special linear group :param q: the order of the finite field over which the special linear group is constructed. This should be an odd prime for the returned presentation to - define claimed group. + define the claimed group. :type q: int :returns: The specified presentation. @@ -817,7 +817,7 @@ from :any:`plactic_monoid_Knu70`. :sig=(n: int) -> Presentation: A presentation for the :math:`0`-rook monoid. -This function returns a presentation for the :math:`0` -rook monoid of degree +This function returns a presentation for the :math:`0`-rook monoid of degree *n*, as in Definition 4.1.1 in :cite:`Gay2018aa`. :param n: the degree. @@ -836,7 +836,7 @@ This function returns a presentation for the :math:`0` -rook monoid of degree :sig=(l: int, q: int) -> Presentation: A presentation for the Renner monoid of type B. -This functions returns a presentation for the Renner monoid of type B with size +This function returns a presentation for the Renner monoid of type B with size *l* and Iwahori-Hecke deformation *q*. When ``q == 0``, this corresponds to Definition 8.4.1 and Example 8.4.2 of @@ -850,10 +850,10 @@ When ``q == 1``, this corresponds to Theorem 8.4.19 of :cite:`Gay2018aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. )pbdoc"); m.def("presentation_examples_not_renner_type_B_monoid_Gay18", &examples::not_renner_type_B_monoid_Gay18, @@ -863,7 +863,7 @@ When ``q == 1``, this corresponds to Theorem 8.4.19 of :cite:`Gay2018aa`. :sig=(l: int, q: int) -> Presentation: A presentation that incorrectly claims to be the Renner monoid of type B. -This functions returns a presentation that incorrectly claims to be the Renner +This function returns a presentation that incorrectly claims to be the Renner monoid of type B with size *l* and Iwahori-Hecke deformation *q*. When ``q == 0``, this corresponds to Example 7.1.2 of :cite:`Gay2018aa`. @@ -876,10 +876,10 @@ When ``q == 1``, this corresponds to Section 3.2 of :cite:`Godelle2009aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. )pbdoc"); m.def("presentation_examples_renner_type_D_monoid_Gay18", &examples::renner_type_D_monoid_Gay18, @@ -889,10 +889,10 @@ When ``q == 1``, this corresponds to Section 3.2 of :cite:`Godelle2009aa`. :sig=(l: int, q: int) -> Presentation: A presentation for the Renner monoid of type D. -This functions returns a presentation for the Renner monoid of type D with size +This function returns a presentation for the Renner monoid of type D with size *l* and Iwahori-Hecke deformation *q*. -When ``q == 0``, this corresponds Definition 8.4.22 of :cite:`Gay2018aa`. +When ``q == 0``, this corresponds to Definition 8.4.22 of :cite:`Gay2018aa`. When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. @@ -902,10 +902,10 @@ When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. )pbdoc"); m.def("presentation_examples_not_renner_type_D_monoid_God09", &examples::not_renner_type_D_monoid_God09, @@ -915,7 +915,7 @@ When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. :sig=(l: int, q: int) -> Presentation: A presentation that incorrectly claims to be the Renner monoid of type D. -This functions returns a presentation that incorrectly claims to be the Renner +This function returns a presentation that incorrectly claims to be the Renner monoid of type D with size *l* and Iwahori-Hecke deformation *q*. When ``q == 1``, this corresponds to Section 3.3 of :cite:`Godelle2009aa`. @@ -926,10 +926,10 @@ When ``q == 1``, this corresponds to Section 3.3 of :cite:`Godelle2009aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. )pbdoc"); m.def("presentation_examples_stellar_monoid", &examples::stellar_monoid, @@ -952,9 +952,8 @@ This function returns a monoid presentation defining the stellar monoid with .. note:: This function returns exactly the same presentation as :any:`stellar_monoid_GH19`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_dual_symmetric_inverse_monoid", &examples::dual_symmetric_inverse_monoid, @@ -976,10 +975,9 @@ monoid of degree *n*, as in Section 3 of :cite:`Easdown2007aa`. .. note:: - This function returns exactly the same presentation as :any:`dual_symmetric_inverse_monoid`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + This function returns exactly the same presentation as :any:`dual_symmetric_inverse_monoid_EEF07`, + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_uniform_block_bijection_monoid", &examples::uniform_block_bijection_monoid, @@ -1002,9 +1000,8 @@ monoid of degree *n*, as in :cite:`FitzGerald2003aa`. .. note:: This function returns exactly the same presentation as :any:`uniform_block_bijection_monoid_Fit03`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_partition_monoid", &examples::partition_monoid, @@ -1053,9 +1050,8 @@ monoid of degree *n*, as in Theorem 5 of :cite:`Maltcev2007aa`. .. note:: This function returns exactly the same presentation as :any:`singular_brauer_monoid_MM07`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_orientation_preserving_monoid", &examples::orientation_preserving_monoid, @@ -1079,9 +1075,8 @@ preserving mappings on a finite chain of order *n*, as described in .. note:: This function returns exactly the same presentation as :any:`orientation_preserving_monoid_AR00`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_orientation_preserving_reversing_monoid", &examples::orientation_preserving_reversing_monoid, @@ -1105,9 +1100,8 @@ preserving or reversing mappings on a finite chain of order *n*, as described in .. note:: This function returns exactly the same presentation as :any:`orientation_preserving_reversing_monoid_AR00`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_temperley_lieb_monoid", &examples::temperley_lieb_monoid, @@ -1130,9 +1124,8 @@ with *n* generators, as described in Theorem 2.2 of :cite:`East2022aa`. .. note:: This function returns exactly the same presentation as :any:`temperley_lieb_monoid_Eas21`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_brauer_monoid", &examples::brauer_monoid, @@ -1155,9 +1148,8 @@ degree *n*, as described in Theorem 3.1 of :cite:`Kudryavtseva2006aa`. .. note:: This function returns exactly the same presentation as :any:`brauer_monoid_KM07`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_partial_brauer_monoid", &examples::partial_brauer_monoid, @@ -1180,9 +1172,8 @@ of degree *n*, as described in Theorem 5.1 of :cite:`Kudryavtseva2006aa`. .. note:: This function returns exactly the same presentation as :any:`partial_brauer_monoid_KM07`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_motzkin_monoid", &examples::motzkin_monoid, @@ -1193,7 +1184,7 @@ A presentation for the Motzkin monoid. This function returns a monoid presentation defining the Motzkin monoid of degree *n*, as described in Theorem 4.1 of :cite:`Posner2013aa`, with the -additional relations :math:` r_i t_i l_i = r_i ^ 2 ` added to fix a hole in +additional relations :math:`r_i t_i l_i = r_i^2` added to fix a hole in Lemma 4.10 which rendered the presentation as stated in the paper incorrect. :param n: the degree. @@ -1207,9 +1198,8 @@ Lemma 4.10 which rendered the presentation as stated in the paper incorrect. .. note:: This function returns exactly the same presentation as :any:`motzkin_monoid_PHL13`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_fibonacci_semigroup", &examples::fibonacci_semigroup, @@ -1240,9 +1230,8 @@ This function returns a semigroup presentation defining the Fibonacci semigroup .. note:: This function returns exactly the same presentation as :any:`fibonacci_semigroup_CRRT94`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_plactic_monoid", @@ -1253,7 +1242,7 @@ This function returns a semigroup presentation defining the Fibonacci semigroup A presentation for the plactic monoid. This function returns a monoid presentation defining the plactic monoid with -*n* generators, as in see Theorem 6 of :cite:`Knuth1970aa`. +*n* generators, as in Theorem 6 of :cite:`Knuth1970aa`. :param n: the number of generators. :type n: int @@ -1266,9 +1255,8 @@ This function returns a monoid presentation defining the plactic monoid with .. note:: This function returns exactly the same presentation as :any:`plactic_monoid_Knu70`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_stylic_monoid", &examples::stylic_monoid, @@ -1291,9 +1279,8 @@ This function returns a monoid presentation defining the stylic monoid with .. note:: This function returns exactly the same presentation as :any:`stylic_monoid_AR22`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_symmetric_group", &examples::symmetric_group, @@ -1345,9 +1332,8 @@ degree *n*, as in Theorem B of :cite:`Moore1897aa`. .. note:: This function returns exactly the same presentation as :any:`alternating_group_Moo97`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_rectangular_band", &examples::rectangular_band, @@ -1375,9 +1361,8 @@ rectangular band, as given in Proposition 4.2 of :cite:`Ayik2000aa`. .. note:: This function returns exactly the same presentation as :any:`rectangular_band_ACOR00`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_full_transformation_monoid", &examples::full_transformation_monoid, @@ -1429,7 +1414,7 @@ monoid of degree *n*, as in Theorem 1.6 of :cite:`Mitchell2024aa`. .. seealso:: - For a specific presentation of the full transformation monoid, see one + For a specific presentation of the partial transformation monoid, see one of the following functions: * :any:`partial_transformation_monoid_Shu60`; @@ -1440,12 +1425,12 @@ monoid of degree *n*, as in Theorem 1.6 of :cite:`Mitchell2024aa`. py::arg("n"), R"pbdoc( :sig=(n: int) -> Presentation: -A presentation for the partial transformation monoid. +A presentation for the symmetric inverse monoid. -This function returns a monoid presentation defining the partial transformation -monoid of degree *n*, as in Theorem 1.6 of :cite:`Mitchell2024aa`. +This function returns a monoid presentation defining the symmetric inverse +monoid of degree *n*, as in Theorem 1.4 of :cite:`Mitchell2024aa`. -:param n: the degree of the partial transformation monoid. +:param n: the degree of the symmetric inverse monoid. :type n: int :returns: The specified presentation. @@ -1455,7 +1440,7 @@ monoid of degree *n*, as in Theorem 1.6 of :cite:`Mitchell2024aa`. .. seealso:: - For a specific presentation of the full transformation monoid, see one of + For a specific presentation of the symmetric inverse monoid, see one of the following functions: * :any:`symmetric_inverse_monoid_Sol04`; @@ -1483,9 +1468,8 @@ generators, as in :cite:`Cassaigne2001aa`. .. note:: This function returns exactly the same presentation as :any:`chinese_monoid_CEKNH01`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_monogenic_semigroup", &examples::monogenic_semigroup, @@ -1535,9 +1519,8 @@ order preserving transformations of degree *n*, as described in Section 2 of .. note:: This function returns exactly the same presentation as :any:`order_preserving_monoid_AR00`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_cyclic_inverse_monoid", &examples::cyclic_inverse_monoid, @@ -1562,7 +1545,7 @@ This presentation has :math:`2` generators and .. seealso:: - For a specific presentation of the full transformation monoid, see one of + For a specific presentation of the cyclic inverse monoid, see one of the following functions: * :any:`cyclic_inverse_monoid_Fer22_a`; @@ -1590,9 +1573,8 @@ of the cyclic inverse monoid of degree *n*, as in Theorem 2.17 of .. note:: This function returns exactly the same presentation as :any:`order_preserving_cyclic_inverse_monoid_Fer22`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_partial_isometries_cycle_graph_monoid", &examples::partial_isometries_cycle_graph_monoid, @@ -1603,7 +1585,7 @@ A presentation for the monoid of partial isometries of a cycle graph. This function returns a monoid presentation defining the monoid of partial isometries of an :math:`n`-cycle graph, as in Theorem 2.8 of -:cite:`Fernandes2022ab` +:cite:`Fernandes2022ab`. :param n: the number of vertices of the cycle graph. :type n: int @@ -1616,9 +1598,8 @@ isometries of an :math:`n`-cycle graph, as in Theorem 2.8 of .. note:: This function returns exactly the same presentation as :any:`partial_isometries_cycle_graph_monoid_FP22`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_not_symmetric_group", &examples::not_symmetric_group, @@ -1642,9 +1623,8 @@ symmetric group of degree *n*, but does not, as in Section 2.2 of .. note:: This function returns exactly the same presentation as :any:`not_symmetric_group_GKKL08`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_special_linear_group_2", &examples::special_linear_group_2, @@ -1659,7 +1639,7 @@ where *q* is an odd prime, as in Theorem 4 of :cite:`Campbell1980aa`. :param q: the order of the finite field over which the special linear group is constructed. This should be an odd prime for the returned presentation to - define claimed group. + define the claimed group. :type q: int :returns: The specified presentation. @@ -1670,9 +1650,8 @@ where *q* is an odd prime, as in Theorem 4 of :cite:`Campbell1980aa`. .. note:: This function returns exactly the same presentation as :any:`special_linear_group_2_CR80`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_hypo_plactic_monoid", &examples::hypo_plactic_monoid, @@ -1698,9 +1677,8 @@ includes the rules from :any:`plactic_monoid_Knu70`. .. note:: This function returns exactly the same presentation as :any:`hypo_plactic_monoid_Nov00`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_sigma_plactic_monoid", @@ -1735,7 +1713,7 @@ and is given in :any:`stylic_monoid`. A presentation for the :math:`0`-rook monoid. This function returns a presentation for the :math:`0`-rook monoid of degree -*n*, as in Definition 4.1.1 in :cite:`Gay2018aa` +*n*, as in Definition 4.1.1 in :cite:`Gay2018aa`. :param n: the degree. :type n: int @@ -1748,9 +1726,8 @@ This function returns a presentation for the :math:`0`-rook monoid of degree .. note:: This function returns exactly the same presentation as :any:`zero_rook_monoid_Gay18`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_renner_type_B_monoid", &examples::renner_type_B_monoid, @@ -1760,7 +1737,7 @@ This function returns a presentation for the :math:`0`-rook monoid of degree :sig=(l: int, q: int) -> Presentation: A presentation for the Renner monoid of type B. -This functions returns a presentation for the Renner monoid of type B with size +This function returns a presentation for the Renner monoid of type B with size *l* and Iwahori-Hecke deformation *q*. When ``q == 0``, this corresponds to Definition 8.4.1 and Example 8.4.2 of @@ -1774,17 +1751,16 @@ When ``q == 1``, this corresponds to Theorem 8.4.19 of :cite:`Gay2018aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. .. note:: This function returns exactly the same presentation as :any:`renner_type_B_monoid_Gay18`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_not_renner_type_B_monoid", &examples::not_renner_type_B_monoid, @@ -1794,7 +1770,7 @@ When ``q == 1``, this corresponds to Theorem 8.4.19 of :cite:`Gay2018aa`. :sig=(l: int, q: int) -> Presentation: A presentation that incorrectly claims to be the Renner monoid of type B. -This functions returns a presentation that incorrectly claims to be the Renner +This function returns a presentation that incorrectly claims to be the Renner monoid of type B with size *l* and Iwahori-Hecke deformation *q*. When ``q == 0``, this corresponds to Example 7.1.2 of :cite:`Gay2018aa`. @@ -1807,17 +1783,16 @@ When ``q == 1``, this corresponds to Section 3.2 of :cite:`Godelle2009aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. .. note:: This function returns exactly the same presentation as :any:`not_renner_type_B_monoid_Gay18`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_renner_type_D_monoid", &examples::renner_type_D_monoid, @@ -1827,10 +1802,10 @@ When ``q == 1``, this corresponds to Section 3.2 of :cite:`Godelle2009aa`. :sig=(l: int, q: int) -> Presentation: A presentation for the Renner monoid of type D. -This functions returns a presentation for the Renner monoid of type D with size +This function returns a presentation for the Renner monoid of type D with size *l* and Iwahori-Hecke deformation *q*. -When ``q == 0``, this corresponds Definition 8.4.22 of :cite:`Gay2018aa`. +When ``q == 0``, this corresponds to Definition 8.4.22 of :cite:`Gay2018aa`. When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. @@ -1840,17 +1815,16 @@ When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. .. note:: This function returns exactly the same presentation as :any:`renner_type_D_monoid_Gay18`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_not_renner_type_D_monoid", @@ -1861,7 +1835,7 @@ When ``q == 1``, this corresponds to Theorem 8.4.43 of :cite:`Gay2018aa`. :sig=(l: int, q: int) -> Presentation: A presentation that incorrectly claims to be the Renner monoid of type D. -This functions returns a presentation that incorrectly claims to be the Renner +This function returns a presentation that incorrectly claims to be the Renner monoid of type D with size *l* and Iwahori-Hecke deformation *q*. When ``q == 1``, this corresponds to Section 3.3 of :cite:`Godelle2009aa`. @@ -1872,17 +1846,16 @@ When ``q == 1``, this corresponds to Section 3.3 of :cite:`Godelle2009aa`. :param q: the Iwahori-Hecke deformation. :type q: int -:returns: The specified presentation +:returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``q != 0`` or ``q != 1``. +:raises LibsemigroupsError: if ``q`` is neither ``0`` nor ``1``. .. note:: This function returns exactly the same presentation as :any:`not_renner_type_D_monoid_God09`, - and exists as a convenience function for when a presentation for the - alternating group is required, but the specific presentation - is not important. + and exists as a convenience function for when a presentation is required, + but the specific presentation is not important. )pbdoc"); m.def("presentation_examples_abacus_jones_monoid", @@ -1895,12 +1868,12 @@ When ``q == 1``, this corresponds to Section 3.3 of :cite:`Godelle2009aa`. A presentation for the abacus Jones monoid. This function returns a monoid presentation defining the abacus Jones monoid of -degree *n*; as defined in Proposition 3.2 of :cite:`Aicardi2025aa`. The +degree *n*, as defined in Proposition 3.2 of :cite:`Aicardi2025aa`. The abacus Jones monoid is formed by the diagrams of the Jones monoid (aka the Temperley-Lieb monoid) whose arcs have at most ``d − 1`` beads sliding on each arc. This presentation has :math:`2n - 1` -generators, :math:`5n ^ 2 - 5n + 2 + 2(n - 1)(d - 1)` relations, and -defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the +generators, :math:`5n^2 - 5n + 2 + 2(n - 1)(d - 1)` relations, and +defines a monoid of size :math:`C_n d^n` where :math:`C_n` is the :math:`n`-th Catalan number :math:`\frac{1}{n + 1}\binom{2n}{n}`. :param n: the degree. @@ -1912,7 +1885,7 @@ defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the :returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``n < 3`` or if ``d = 0``. +:raises LibsemigroupsError: if ``n < 3`` or if ``d == 0``. .. seealso:: :any:`abacus_jones_monoid_AJP25`. )pbdoc"); @@ -1927,12 +1900,12 @@ defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the A presentation for the abacus Jones monoid. This function returns a monoid presentation defining the abacus Jones monoid of -degree *n*; as defined in Proposition 3.2 of :cite:`Aicardi2025aa`. The +degree *n*, as defined in Proposition 3.2 of :cite:`Aicardi2025aa`. The abacus Jones monoid is formed by the diagrams of the Jones monoid (aka the Temperley-Lieb monoid) whose arcs have at most ``d − 1`` beads sliding on each arc. This presentation has :math:`2n - 1` -generators, :math:`5n ^ 2 - 5n + 2 + 2(n - 1)(d - 1)` relations, and -defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the +generators, :math:`5n^2 - 5n + 2 + 2(n - 1)(d - 1)` relations, and +defines a monoid of size :math:`C_n d^n` where :math:`C_n` is the :math:`n`-th Catalan number :math:`\frac{1}{n + 1}\binom{2n}{n}`. :param n: the degree. @@ -1944,7 +1917,7 @@ defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the :returns: The specified presentation. :rtype: Presentation -:raises LibsemigroupsError: if ``n < 3`` or if ``d = 0``. +:raises LibsemigroupsError: if ``n < 3`` or if ``d == 0``. )pbdoc"); m.def("presentation_examples_braid_group", @@ -1953,10 +1926,10 @@ defines a monoid of size :math:`C_n\ d ^n` where :math:`C_n` is the R"pbdoc( :sig=(n: int) -> Presentation: -A presentation for the Braid group. +A presentation for the braid group. -This function returns a monoid presentation defining the Braid group with -:math:`n - 1` generators, as described in Equation (2) of :any:`Birman2005aa`. +This function returns a monoid presentation defining the braid group with +:math:`n - 1` generators, as described in Equation (2) of :cite:`Birman2005aa`. :param n: the degree, or equivalently the number of generators plus 1. :type n: int From 2f0d3c081c3d8e2e7a53d243122c975b339a0089 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 19:05:55 +0100 Subject: [PATCH 16/24] Fix Report doc --- src/report.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/report.cpp b/src/report.cpp index ae71a7b06..0b5321eab 100644 --- a/src/report.cpp +++ b/src/report.cpp @@ -32,8 +32,8 @@ namespace libsemigroups { "ReportGuard", R"pbdoc( Objects of this type can be used to enable printing of some information -during various of the computation in ``libsemigroups_pybind11``. Reporting -is enabled (or not) at construction time, and disable when the +during various computations in ``libsemigroups_pybind11``. Reporting +is enabled (or not) at construction time, and disabled when the :any:`ReportGuard` goes out of scope. )pbdoc") .def(py::init(), From 8100bac1b419150a5d435f53fff06032665eb336 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 19:10:10 +0100 Subject: [PATCH 17/24] Fix Runner doc --- src/runner.cpp | 59 ++++++++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/src/runner.cpp b/src/runner.cpp index 9b00e38d8..dd4ec3c5f 100644 --- a/src/runner.cpp +++ b/src/runner.cpp @@ -220,7 +220,7 @@ return ``True`` again after at least time ``s + val`` has elapsed. :returns: *self*. :rtype: Reporter -.. seealso:: :any:`report_every` +.. seealso:: :any:`report_every`. )pbdoc"); thing.def( "report_every", @@ -245,7 +245,7 @@ which is also the time of construction of a :any:`Reporter` instance if :any:`reset_start_time()` is not explicitly called. :returns: - The time delta representing the start time. + The start time. :rtype: datetime.datetime @@ -331,7 +331,7 @@ Set the prefix string for reporting. This function sets the return value of :any:`report_prefix()` to (a copy of) the argument *val*. Typically this prefix should be the name of the algorithm -being run at the outmost level. +being run at the outermost level. :param val: the new value of the report prefix. :type val: str @@ -347,7 +347,7 @@ Get the current prefix string for reporting. This function gets the current value of the prefix string for reporting (set via :any:`report_prefix`), which is typically the name of the algorithm being -run at the outmost level. +run at the outermost level. :returns: The prefix string. @@ -366,15 +366,16 @@ Abstract class for derived [#sortof]_ classes that run an algorithm. Many of the classes in ``libsemigroups_pybind11`` implementing the algorithms, that are the reason for the existence of this package, are derived from :any:`Runner`. The :any:`Runner` class exists to collect various common tasks -required by such a derived class with a possibly long running :any:`run`. These +required by such a derived class with a possibly long-running :any:`Runner.run`. These common tasks include: * running for a given amount of time (:any:`run_for`) * running until a nullary predicate is true (:any:`run_until`) -* checking the status of the algorithm: has it :any:`started` ? +* checking the status of the algorithm: has it :any:`started`? :any:`finished`? been killed by another thread (:any:`dead`)? has it timed out (:any:`timed_out`)? has it :any:`stopped` for any reason? -* permit the function :any:`run` to be killed from another thread (:any:`kill`). +* permitting the function :any:`Runner.run` to be killed from another thread + (:any:`kill`). Because :any:`Runner` is an abstract class it is not possible to create instances of :any:`Runner` except via a derived class. @@ -403,7 +404,7 @@ The valid values are: .. py:attribute:: state.never_run :value: - + Indicates that none of :any:`Runner.run`, :any:`Runner.run_for`, or :any:`Runner.run_until` has been called since construction or the last call to :any:`Runner.init`. @@ -447,7 +448,7 @@ The valid values are: .. py:attribute:: state.dead :value: - + Indicates that the Runner was killed (by another thread). )pbdoc"); state.value("never_run", Runner::state::never_run) @@ -477,8 +478,10 @@ been newly default constructed. thing.def("run", &Runner::run, R"pbdoc( -Run until finished. Run the main algorithm implemented by a derived -class of :any:`Runner`. +Run until finished. + +This function runs the main algorithm implemented by a derived class of +:any:`Runner`. )pbdoc"); thing.def( "run_for", @@ -490,13 +493,14 @@ class of :any:`Runner`. Run for a specified amount of time. For this to work it is necessary to periodically check if :any:`timed_out()` -returns ``True``, and to stop if it is, in the :any:`run()` member function of +returns ``True``, and to stop if it does, in the :any:`run()` member function of any derived class of :any:`Runner`. :param t: the time to run for. :type t: datetime.timedelta -.. seealso:: :any:`run_for`)pbdoc"); +.. seealso:: :any:`run_for`. +)pbdoc"); thing.def("run_until", (void(Runner::*)(std::function&)) & Runner::run_until, py::arg("func"), @@ -514,7 +518,7 @@ Run until a nullary predicate returns true or finished. R"pbdoc( Check if the amount of time passed to run_for has elapsed. -:returns: Whether or not :any:`run_for` timed out. +:returns: Whether :any:`run_for` timed out. :rtype: bool .. seealso:: :any:`run_for`. @@ -522,15 +526,15 @@ Check if the amount of time passed to run_for has elapsed. thing.def("report_why_we_stopped", &Runner::report_why_we_stopped, R"pbdoc( -Report why run stopped. Reports whether :any:`run()` was stopped because +Report why :any:`Runner.run` stopped. Reports whether :any:`run()` was stopped because it is :any:`finished()`, :any:`timed_out()`, or :any:`dead()`. )pbdoc"); thing.def("finished", &Runner::finished, R"pbdoc( -Check if run has been run to completion or not. +Check if :any:`Runner.run` has run to completion. -This function returns ``True`` if :any:`run()` has been run to completion. For +This function returns ``True`` if :any:`run()` has run to completion. For this to work, the implementation of :any:`run()` in a derived class of :any:`Runner` must implement a specialisation of ``finished_impl``. @@ -542,12 +546,12 @@ this to work, the implementation of :any:`run()` in a derived class of thing.def("success", &Runner::success, R"pbdoc( -Check if run has been run to completion successfully. +Check if :any:`Runner.run` has run to completion successfully. -This function returns ``True`` if :any:`run()` has been run to completion and +This function returns ``True`` if :any:`run()` has run to completion and it was successful. -:returns: Whether or not :any:`run` was successful or not. +:returns: Whether :any:`Runner.run` was successful. :rtype: bool .. seealso:: :any:`started()` @@ -555,7 +559,7 @@ it was successful. thing.def("started", &Runner::started, R"pbdoc( -Check if run has been called at least once before. +Check if :any:`Runner.run` has been called at least once before. This function returns ``True`` if :any:`run()` has started to run (it can be running or not). @@ -571,9 +575,9 @@ running or not). Check if currently running. This function returns ``True`` if :any:`run()` is in the process of running and -``False`` it is not. +``False`` if it is not. -:returns: Whether or not the runner is running. +:returns: Whether the runner is running. :rtype: bool .. seealso:: :any:`finished()` @@ -581,16 +585,19 @@ This function returns ``True`` if :any:`run()` is in the process of running and thing.def("kill", &Runner::kill, R"pbdoc( -Stop run from running (thread-safe). +Stop :any:`Runner.run` from running (thread-safe). + This function can be used to terminate :any:`run()` from another thread. After :any:`kill()` has been called the :any:`Runner` may no longer be in a valid state, but will return ``True`` from :any:`dead()`. -.. seealso:: :any:`finished()`)pbdoc"); +.. seealso:: :any:`finished()`. +)pbdoc"); thing.def("dead", &Runner::dead, R"pbdoc( Check if the runner is dead. + This function can be used to check if we should terminate :any:`run()` because it has been killed by another thread. @@ -617,7 +624,7 @@ other words, it checks if :any:`timed_out()`, :any:`finished()`, or &Runner::stopped_by_predicate, R"pbdoc( Check if the runner was stopped, or should stop, because of the argument -last passed to run_until. If *self* is running, then the nullary +last passed to :any:`run_until`. If *self* is running, then the nullary predicate is called and its return value is returned. If *self* is not running, then ``True`` is returned if and only if the last time *self* was running it was stopped by a call to the nullary predicate passed to From 9c333ce7bc1cbbaf6b6fe6c63ad9f02a1df2ebcd Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 30 Apr 2026 19:13:43 +0100 Subject: [PATCH 18/24] Fix SchreierSims doc --- src/schreier-sims.cpp | 61 ++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/src/schreier-sims.cpp b/src/schreier-sims.cpp index 20dc8464f..994e0d053 100644 --- a/src/schreier-sims.cpp +++ b/src/schreier-sims.cpp @@ -74,9 +74,8 @@ the list *gens*. :param gens: the list of generators. :type gens: list[Element] -:raises LibsemigroupsError: if the generators do not have degree equal to - :math:`255` or :math:`511`, or the number of generators exceeds the - maximum capacity. +:raises LibsemigroupsError: if the generators do not have the expected degree + for this class, or the number of generators exceeds the maximum capacity. )pbdoc"); thing.def("__copy__", @@ -112,7 +111,8 @@ Add a base point to the stabiliser chain. :raises LibsemigroupsError: if :any:`finished()` returns ``True``. -:complexity: Linear in the current number of base points.)pbdoc"); +:complexity: Linear in the current number of base points. +)pbdoc"); thing.def("add_generator", &SchreierSims_::add_generator, @@ -122,20 +122,20 @@ Add a base point to the stabiliser chain. Add a generator. -This functions adds the argument *x* as a new generator if and only if *x* is +This function adds the argument *x* as a new generator if and only if *x* is not already an element of the group represented by the Schreier-Sims object. :param x: the generator to add. :type x: Element -:returns: ``True`` if *x* is added as a generator and ``False`` if it is not. +:returns: ``True`` if *x* is added as a generator and ``False`` if it is not. :rtype: bool -:raises LibsemigroupsError: if the degree of *x* is not equal to :math:`255` - or :math:`511`, or if *self* already contains the maximum number of - elements. +:raises LibsemigroupsError: if the degree of *x* is not equal to the expected + degree for this class, or if *self* already contains the maximum number + of elements. -:complexity: Constant +:complexity: Constant. )pbdoc"); thing.def("base", &SchreierSims_::base, @@ -181,7 +181,7 @@ Test membership of an element. :param x: the possible element. :type x: Element -:returns: ``True`` if *element* is a contained in the :any:`SchreierSims` +:returns: ``True`` if *x* is contained in the :any:`SchreierSims` instance, and ``False`` otherwise. :rtype: bool )pbdoc"); @@ -198,7 +198,7 @@ This function tests the membership of an element without running the algorithm. :param x: the possible element. :type x: Element -:returns: ``True`` if *x* is a contained in the :any:`SchreierSims` +:returns: ``True`` if *x* is contained in the :any:`SchreierSims` instance, and ``False`` otherwise. :rtype: bool )pbdoc"); @@ -209,7 +209,7 @@ This function tests the membership of an element without running the algorithm. Check if any generators have been added so far. -:returns: ``True`` if ``number_of_generators() == 0`` and ``False`` otherwise. +:returns: ``True`` if ``number_of_generators() == 0`` and ``False`` otherwise. :rtype: bool :complexity: Constant. @@ -221,7 +221,7 @@ Check if any generators have been added so far. Check if the stabiliser chain is fully enumerated. -:returns: ``True`` if the stabiliser chain is fully enumerated and ``False`` otherwise. +:returns: ``True`` if the stabiliser chain is fully enumerated and ``False`` otherwise. :rtype: bool :complexity: Constant. @@ -268,12 +268,12 @@ represents the trivial group, as if *self* had been newly constructed. py::arg("depth"), py::arg("pt"), R"pbdoc( -:sig=(self: SchreierSims, depth:int, pt: int) -> Element: +:sig=(self: SchreierSims, depth: int, pt: int) -> Element: Get an inverse of a transversal element. -This function returns the transversal element at depth *depth* which sends *pt* -to the basepoint. +This function returns the inverse transversal element at depth *depth* which +sends *pt* to the base point. :param depth: the depth. :type depth: int @@ -282,12 +282,12 @@ to the basepoint. element. :type pt: int -:returns: the inverse transversal element. +:returns: The inverse transversal element. :rtype: Element :raises LibsemigroupsError: if the *depth* is out of bounds. -:raises LibsemigroupsError: if *pt* is not in the orbit of the basepoint. +:raises LibsemigroupsError: if *pt* is not in the orbit of the base point. :complexity: Constant. )pbdoc"); @@ -346,7 +346,7 @@ permutations belonging to a :any:`SchreierSims` object. R"pbdoc( :sig=(self: SchreierSims, depth: int, pt: int) -> bool: -Check if a point is in the orbit of a basepoint. +Check if a point is in the orbit of a base point. :param depth: the depth. :type depth: int @@ -360,7 +360,7 @@ Check if a point is in the orbit of a basepoint. :rtype: bool :raises LibsemigroupsError: - if the *depth*` is out of bounds or if *pt* is out of bounds. + if *depth* is out of bounds or if *pt* is out of bounds. :complexity: Constant. )pbdoc"); @@ -383,7 +383,7 @@ Run the Schreier-Sims algorithm. :sig=(self: SchreierSims, x: Element) -> Element: Sift an element through the stabiliser chain. -:param x: A group element. +:param x: a group element. :type x: Element :returns: A sifted element. @@ -413,7 +413,7 @@ Sift an element through the stabiliser chain in-place. Returns the size of the group represented by *self*. -:returns: the size of the group. +:returns: The size of the group. :rtype: int )pbdoc"); thing.def("current_size", @@ -421,9 +421,10 @@ Returns the size of the group represented by *self*. R"pbdoc( :sig=(self: SchreierSims) -> int: -Returns the size of the group represented by this, without running the algorithm. +Returns the size of the group represented by *self*, without running the +algorithm. -:returns: the size of the group. +:returns: The size of the group. :rtype: int )pbdoc"); thing.def("strong_generator", @@ -444,7 +445,7 @@ This function returns the generator with a given depth and index. :param index: the index of the generator to return. :type index: int -:returns: The strong generator of at depth *depth* and with index *index*. +:returns: The strong generator at depth *depth* and with index *index*. :rtype: Element :raises LibsemigroupsError: if the *depth* is out of bounds. @@ -461,15 +462,15 @@ This function returns the generator with a given depth and index. R"pbdoc( :sig=(self: SchreierSims, depth: int, pt: int) -> Element: -Get an transversal element. +Get a transversal element. This function returns the transversal element at depth *depth* which sends the -corresponding basepoint to the point *pt*. +corresponding base point to the point *pt*. :param depth: the depth. :type depth: int -:param pt: the image of the base point under the traversal. +:param pt: the image of the base point under the transversal element. :type pt: int :returns: The transversal element. @@ -477,7 +478,7 @@ corresponding basepoint to the point *pt*. :raises LibsemigroupsError: if *depth* is out of bounds. -:raises LibsemigroupsError: if *pt* is not in the orbit of the basepoint. +:raises LibsemigroupsError: if *pt* is not in the orbit of the base point. :complexity: Constant. )pbdoc"); From f43d1be7ba18865ec5f237717ed9a39ab262992e Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Fri, 1 May 2026 23:26:57 +0100 Subject: [PATCH 19/24] :return: -> :returns: --- src/errors.cpp | 2 +- src/freeband.cpp | 2 +- src/knuth-bendix-impl.cpp | 32 ++++++++++++++++---------------- src/knuth-bendix.cpp | 4 ++-- src/word-range.cpp | 2 +- 5 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/errors.cpp b/src/errors.cpp index cfe1a70f9..f749d1c56 100644 --- a/src/errors.cpp +++ b/src/errors.cpp @@ -87,7 +87,7 @@ emanate from C++. This function returns whether :any:`LibsemigroupsError` messages contain a prefix that indicates which C++ function raised the exception. -:return: Whether :any:`LibsemigroupsError` messages contain a prefix about the +:returns: Whether :any:`LibsemigroupsError` messages contain a prefix about the C++ function that raised the exception. :rtype: bool )pbdoc"); diff --git a/src/freeband.cpp b/src/freeband.cpp index dc28dfed3..ec497d1b9 100644 --- a/src/freeband.cpp +++ b/src/freeband.cpp @@ -53,7 +53,7 @@ band. :param y: the second word to compare in the free band. :type y: list[int] -:return: +:returns: ``True`` if both words are the same as elements of the free band and ``False`` otherwise. :rtype: bool diff --git a/src/knuth-bendix-impl.cpp b/src/knuth-bendix-impl.cpp index ae01dcd21..34d924244 100644 --- a/src/knuth-bendix-impl.cpp +++ b/src/knuth-bendix-impl.cpp @@ -147,7 +147,7 @@ The default value is ``128``. A value of ``1`` means :any:`Runner.run` should attempt to add each rule as it is created without waiting for rules to accumulate. -:return: The maximum number of pending rules. +:returns: The maximum number of pending rules. :rtype: int .. seealso:: :any:`Runner.run`. @@ -170,7 +170,7 @@ to accumulate. :param val: The new maximum number of pending rules. :type val: int -:return: *self*. +:returns: *self*. :rtype: KnuthBendix .. seealso:: :any:`Runner.run`. @@ -190,7 +190,7 @@ confluent. This function can be used to return how frequently this happens. It is the number of new overlaps that should be considered before checking confluence. -:return: The interval at which confluence is checked. +:returns: The interval at which confluence is checked. :rtype: int .. seealso:: :any:`Runner.run`. @@ -222,7 +222,7 @@ system is already confluent. :param val: The new value of the interval. :type val: int | LimitMax -:return: *self*. +:returns: *self*. :rtype: KnuthBendix )pbdoc"); @@ -239,7 +239,7 @@ Return the maximum length of overlaps to be considered. This function returns the maximum length of the overlap of two left hand sides of rules that should be considered in :any:`Runner.run`. -:return: The maximum overlap length. +:returns: The maximum overlap length. :rtype: int | PositiveInfinity .. seealso:: :any:`Runner.run`. @@ -267,7 +267,7 @@ If this value is less than the longest left hand side of a rule, then :param val: The new value of the maximum overlap length. :type val: int | PositiveInfinity -:return: *self*. +:returns: *self*. :rtype: KnuthBendix .. seealso:: :any:`Runner.run`. @@ -288,7 +288,7 @@ system should contain. If this number is exceeded in calls to :any:`Runner.run` or :any:`knuth_bendix.by_overlap_length`, then they will terminate and the system may not be confluent. -:return: The maximum number of rules the system should contain. +:returns: The maximum number of rules the system should contain. :rtype: int | PositiveInfinity .. seealso:: :any:`Runner.run`. @@ -317,7 +317,7 @@ By default this value is :any:`POSITIVE_INFINITY`. :param val: The maximum number of rules. :type val: int | PositiveInfinity -:return: *self*. +:returns: *self*. :rtype: KnuthBendix .. seealso:: :any:`Runner.run`. @@ -334,7 +334,7 @@ Return the overlap policy. This function returns the way that the length of an overlap of two words in the system is measured. -:return: The overlap policy. +:returns: The overlap policy. :rtype: KnuthBendix.options.overlap .. seealso:: :any:`overlap`. @@ -356,7 +356,7 @@ two words in the system is measured. :param val: The overlap policy. :type val: KnuthBendix.options.overlap -:return: *self*. +:returns: *self*. :rtype: KnuthBendix .. seealso:: :any:`overlap`. @@ -373,7 +373,7 @@ two words in the system is measured. Return the current number of active rules. -:return: The current number of active rules. +:returns: The current number of active rules. :rtype: int )pbdoc"); @@ -384,7 +384,7 @@ Return the current number of active rules. Return the current number of inactive rules. -:return: The current number of inactive rules. +:returns: The current number of inactive rules. :rtype: int )pbdoc"); @@ -400,7 +400,7 @@ the Knuth-Bendix algorithm has been running. Note that this is not the sum of :any:`number_of_active_rules` and :any:`number_of_inactive_rules`, due to the re-initialisation of rules where possible. -:return: The total number of rules. +:returns: The total number of rules. :rtype: int )pbdoc"); @@ -415,7 +415,7 @@ to the re-initialisation of rules where possible. Check `confluence `_ of the current rules. -:return: ``True`` if the :py:class:`KnuthBendix` +:returns: ``True`` if the :py:class:`KnuthBendix` instance is confluent and ``False`` if it is not. :rtype: bool )pbdoc"); @@ -427,7 +427,7 @@ Check `confluence `_ of the current rules. Check if the current system knows the state of confluence of the current rules. -:return: +:returns: ``True`` if the confluence of the rules in the :py:class:`KnuthBendix` instance is known, and ``False`` if it is not. @@ -450,7 +450,7 @@ normal forms of the semigroup elements. The semigroup is finite if the graph is acyclic, and infinite otherwise. -:return: The Gilman :py:class:`WordGraph`. +:returns: The Gilman :py:class:`WordGraph`. :rtype: WordGraph .. warning:: diff --git a/src/knuth-bendix.cpp b/src/knuth-bendix.cpp index 21802eeef..b5f9fa488 100644 --- a/src/knuth-bendix.cpp +++ b/src/knuth-bendix.cpp @@ -127,7 +127,7 @@ greater than the second according to the reduction ordering of the according to the reduction ordering used by the rewriting system, on the first entry. -:return: An iterator yielding the currently active rules. +:returns: An iterator yielding the currently active rules. :rtype: collections.abc.Iterator[tuple[str, str]] )pbdoc"); @@ -141,7 +141,7 @@ Return the node labels of the Gilman :py:class:`WordGraph`. Return the node labels of the Gilman :py:class:`WordGraph`, corresponding to the unique prefixes of the left-hand sides of the rules of the rewriting system. -:return: The node labels of the Gilman :py:class:`WordGraph`. +:returns: The node labels of the Gilman :py:class:`WordGraph`. :rtype: list[str] .. seealso:: :any:`gilman_graph`. diff --git a/src/word-range.cpp b/src/word-range.cpp index 3e8f6b49c..fc0f69388 100644 --- a/src/word-range.cpp +++ b/src/word-range.cpp @@ -1230,7 +1230,7 @@ Returns a random word. :param nr_letters: the size of the alphabet. :type nr_letters: int -:return: A random word on ``[0, ..., nr_letters - 1]`` of length *length*. +:returns: A random word on ``[0, ..., nr_letters - 1]`` of length *length*. :rtype: list[int] :raises LibsemigroupsError: if *nr_letters* is ``0``. From cefcd14b5f21aa2ba3cc3e28ae9ad8cea9910c0e Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Fri, 1 May 2026 23:32:40 +0100 Subject: [PATCH 20/24] doc: Capitalise return sentences --- src/aho-corasick.cpp | 4 ++-- src/cong-common.cpp | 2 +- src/dot.cpp | 6 +++--- src/forest.cpp | 2 +- src/hpcombi.cpp | 6 +++--- src/present.cpp | 26 +++++++++++++------------- src/sims.cpp | 2 +- src/stephen.cpp | 4 ++-- src/word-range.cpp | 2 +- 9 files changed, 27 insertions(+), 27 deletions(-) diff --git a/src/aho-corasick.cpp b/src/aho-corasick.cpp index feb25fba2..7509621e5 100644 --- a/src/aho-corasick.cpp +++ b/src/aho-corasick.cpp @@ -106,7 +106,7 @@ This function returns the index of the child of the node with index :param letter: the edge-label connecting the parent to the desired child. :type letter: int -:returns: the index of the child. +:returns: The index of the child. :rtype: int | Undefined :raises LibsemigroupsError: if ``throw_if_node_index_not_active(parent)`` raises an exception. @@ -126,7 +126,7 @@ Calculate the height of a node. :param i: the index of the node whose height is sought :type i: int -:returns: the height. +:returns: The height. :rtype: int :raises LibsemigroupsError: if ``throw_if_node_index_not_active(i)`` raises an exception. diff --git a/src/cong-common.cpp b/src/cong-common.cpp index 4dd536580..5acd8f405 100644 --- a/src/cong-common.cpp +++ b/src/cong-common.cpp @@ -313,7 +313,7 @@ had been newly constructed from *knd* and *p*. :param p: the presentation. :type p: Presentation -:returns: *self*. +:returns: *self*. :rtype: {name} :raises LibsemigroupsError: if *p* is not valid. diff --git a/src/dot.cpp b/src/dot.cpp index 80f74d89d..476503065 100644 --- a/src/dot.cpp +++ b/src/dot.cpp @@ -213,7 +213,7 @@ This function adds a node with name *name*. :param name: the name of the node to add. :type name: str -:returns: a newly created :any:`Dot.Node` object with name *name*. +:returns: A newly created :any:`Dot.Node` object with name *name*. :rtype: Dot.Node :raises LibsemigroupsError: if there is already a node with name *name*. @@ -235,7 +235,7 @@ This function adds an edge from the node named *head* to the node named *tail*. :param tail: the name of the node at the tail of the edge. :type tail: str -:returns: a newly created :any:`Dot.Edge` object. +:returns: A newly created :any:`Dot.Edge` object. :rtype: Dot.Edge :raises LibsemigroupsError: if there is no node named *head* and/or *tail*. @@ -326,7 +326,7 @@ the represented graph and ``False`` otherwise. :param name: the name of the node. :type name: str -:returns: whether or not *name* is the name of a node. +:returns: Whether or not *name* is the name of a node. :rtype: bool )pbdoc"); dot.def("kind", diff --git a/src/forest.cpp b/src/forest.cpp index 7b11f78e7..e8b0116e3 100644 --- a/src/forest.cpp +++ b/src/forest.cpp @@ -545,7 +545,7 @@ Get the size of the range. This function returns the number of paths in the range. -:returns: the number of paths in the range. +:returns: The number of paths in the range. :rtype: int )pbdoc"); diff --git a/src/hpcombi.cpp b/src/hpcombi.cpp index 62060a852..4c4f000c5 100644 --- a/src/hpcombi.cpp +++ b/src/hpcombi.cpp @@ -1823,7 +1823,7 @@ Returns the Lehmer code of a permutation. This function returns the Lehmer code of a permutation computed using fast vector comparison. -:returns: the Lehmer code. +:returns: The Lehmer code. :rtype: Vect16 .. doctest:: @@ -1844,7 +1844,7 @@ Returns the Lehmer code of a permutation. This function returns the Lehmer code of a permutation computed using loop and indexed access. -:returns: the Lehmer code. +:returns: The Lehmer code. :rtype: Vect16 .. doctest:: @@ -1865,7 +1865,7 @@ Returns the Lehmer code of a permutation. This function returns the Lehmer code of a permutation computed using array, loop, and indexed access. -:returns: the Lehmer code. +:returns: The Lehmer code. :rtype: Vect16 .. doctest:: diff --git a/src/present.cpp b/src/present.cpp index b7a2a7081..35a6b22cf 100644 --- a/src/present.cpp +++ b/src/present.cpp @@ -195,7 +195,7 @@ If the presentation is not allowed to contain the empty word (according to this function), the presentation may still be isomorphic to a monoid, but is not given as a quotient of a free monoid. -:returns: whether the presentation can contain the empty word. +:returns: Whether the presentation can contain the empty word. :rtype: bool :complexity: Constant. @@ -258,7 +258,7 @@ the alphabet. :param val: the letter. :type val: :ref:`Letter` -:returns: the index. +:returns: The index. :rtype: int :raises LibsemigroupsError: if *val* does not belong to the alphabet. @@ -582,7 +582,7 @@ Check if the rules :math:`u_1 = v_1, \ldots, u_n = v_n` satisfy :param p: the presentation to check. :type p: Presentation -:returns: whether the rules are sorted. +:returns: Whether the rules are sorted. :rtype: bool :raises LibsemigroupsError: if ``p.rules.size()`` is odd. @@ -654,7 +654,7 @@ such that ``!p.in_alphabet(letter(p, i))`` if such a letter exists. :param p: the presentation. :type p: Presentation -:returns: the letter. +:returns: The letter. :rtype: :ref:`Letter` :raises LibsemigroupsError: if *p* already has an alphabet of the maximum @@ -814,7 +814,7 @@ If no such word can be found, then a word of length :math:`0` is returned. :param p: the presentation. :type p: Presentation -:returns: the longest common subword, if it exists. +:returns: The longest common subword, if it exists. :rtype: :ref:`Word` )pbdoc"); @@ -1085,7 +1085,7 @@ lengths of its left-hand and right-hand sides. :param p: the presentation. :type p: Presentation -:returns: the index of the rule. +:returns: The index of the rule. :rtype: int :raises LibsemigroupsError: if the length of ``p.rules`` is odd. @@ -1132,7 +1132,7 @@ the right-hand side, and return :any:`True` if any of the rules are changed. :param p: the presentation whose rules should be sorted. :type p: Presentation -:returns: whether any of the rules were changed. +:returns: Whether any of the rules were changed. :rtype: bool :raises LibsemigroupsError: if ``p.rules.size()`` is odd. @@ -1162,7 +1162,7 @@ rules are changed. :param cmp: the comparison function. :type cmp: collections.abc.Callable[[:ref:`Word`, :ref:`Word`], bool] -:returns: whether any of the rules were changed. +:returns: Whether any of the rules were changed. :rtype: bool :raises LibsemigroupsError: if ``p.rules.size()`` is odd. @@ -1202,7 +1202,7 @@ modified version. :param p: the presentation. :type p: Presentation -:returns: whether or not the presentation has been modified. +:returns: Whether or not the presentation has been modified. :rtype: bool .. seealso:: @@ -1231,7 +1231,7 @@ are created by taking quotients of free semigroups or monoids. :param var_name: the name of the variable to be used in GAP. :type var_name: str -:returns: the GAP string. +:returns: The GAP string. :rtype: str )pbdoc"); m.def( @@ -1580,7 +1580,7 @@ Returns the inverse of the letter *x*. :param x: the letter whose inverse is sought. :type x: :ref:`Letter` -:returns: the inverse of *x*. +:returns: The inverse of *x*. :rtype: :ref:`Letter` :raises LibsemigroupsError: if no inverses have been set, or if ``index(x)`` throws. @@ -1594,7 +1594,7 @@ Return the inverse of each letter in the alphabet. Returns the inverse of each letter in the alphabet. -:returns: the inverses. +:returns: The inverses. :rtype: :ref:`Word` )pbdoc"); thing.def( @@ -1654,7 +1654,7 @@ defined in the alphabet, and that the inverses act as semigroup inverses. * :any:`presentation.throw_if_bad_inverses` )pbdoc"); } // bind_inverse_present - } // namespace + } // namespace void init_present(py::module& m) { bind_present(m, "PresentationWord"); diff --git a/src/sims.cpp b/src/sims.cpp index d1c038759..fc81c856b 100644 --- a/src/sims.cpp +++ b/src/sims.cpp @@ -711,7 +711,7 @@ This function exists to: :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``. diff --git a/src/stephen.cpp b/src/stephen.cpp index abab08991..2b713fa44 100644 --- a/src/stephen.cpp +++ b/src/stephen.cpp @@ -110,7 +110,7 @@ This function gets the accept state of the word graph. Running this function triggers the algorithm implemented in this class (if it hasn't been triggered already), and then returns the accept state of the produced word graph. -:returns: the node. +:returns: The node. :rtype: int :raises LibsemigroupsError: @@ -282,7 +282,7 @@ implemented in this class is not triggered by calls to this function. Get the initial state of the word graph. -:returns: the node. +:returns: The node. :rtype: int )pbdoc"); diff --git a/src/word-range.cpp b/src/word-range.cpp index fc0f69388..1549c49e5 100644 --- a/src/word-range.cpp +++ b/src/word-range.cpp @@ -1011,7 +1011,7 @@ via :any:`ToWord.init()` , or with :any:`words.human_readable_index` if :param input: the string to convert. :type input: str -:returns: the converted list. +:returns: The converted list. :rtype: list[int] :raises LibsemigroupsError: From a50c5581254f40f129d3e713b5c64e641200df0e Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Fri, 1 May 2026 23:39:11 +0100 Subject: [PATCH 21/24] doc: Don't capitalise first letter after param --- src/errors.cpp | 2 +- src/gabow.cpp | 2 +- src/hpcombi.cpp | 34 +++++++++++++------------- src/knuth-bendix-impl.cpp | 10 ++++---- src/pbr.cpp | 2 +- src/present.cpp | 2 +- src/sims.cpp | 50 +++++++++++++++++++-------------------- 7 files changed, 51 insertions(+), 51 deletions(-) diff --git a/src/errors.cpp b/src/errors.cpp index f749d1c56..a481a8cfb 100644 --- a/src/errors.cpp +++ b/src/errors.cpp @@ -103,7 +103,7 @@ emanate from C++. This function specifies whether :any:`LibsemigroupsError` messages should contain a prefix that indicates which C++ function raised the exception. By default, this information is not included. -:param val: Whether :any:`LibsemigroupsError` messages should contain a prefix +:param val: whether :any:`LibsemigroupsError` messages should contain a prefix about the C++ function that raised the exception. :type val: bool diff --git a/src/gabow.cpp b/src/gabow.cpp index 0ddfb90c0..88b25d6d7 100644 --- a/src/gabow.cpp +++ b/src/gabow.cpp @@ -210,7 +210,7 @@ underlying graph of a :any:`Gabow` instance. This function re-initializes a :any:`Gabow` object so that it is in the same state as if it had just been constructed from *wg*. -:param wg: The word graph. +:param wg: the word graph. :type wg: WordGraph :returns: *self*. diff --git a/src/hpcombi.cpp b/src/hpcombi.cpp index 4c4f000c5..688b7762c 100644 --- a/src/hpcombi.cpp +++ b/src/hpcombi.cpp @@ -153,7 +153,7 @@ This function constructs a :any:`Vect16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`Vect16` is padded with ``0`` values at the end. -:param img: The list of images. +:param img: the list of images. :type img: list[int] :raises LibsemigroupsError: if any value in *img* exceeds ``255``. @@ -212,10 +212,10 @@ This function returns the first diff in *self* and *other* among the first where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* and *other* agree up to position ``bound - 1``, then ``16`` is returned. -:param other: The vector for comparison. +:param other: the vector for comparison. :type other: Vect16 -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the first difference or ``16``. @@ -242,10 +242,10 @@ This function returns the last diff in *self* and *other* among the first where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* and *other* agree up to position ``bound - 1``, then ``16`` is returned. -:param other: The vector for comparison. +:param other: the vector for comparison. :type other: Vect16 -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the last difference or ``16``. @@ -271,7 +271,7 @@ That is, the minimum ``i`` such that ``self[i] == 0`` where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* contains no zeros, then ``16`` is returned. -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the first zero or ``16``. @@ -301,7 +301,7 @@ That is, the maximum ``i`` such that ``self[i] == 0`` where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* contains no zeros, then ``16`` is returned. -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the last zero or ``16``. @@ -331,7 +331,7 @@ That is, the minimum ``i`` such that ``self[i] != 0`` where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* contains no non-zero items, then ``16`` is returned. -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the first zero or ``16``. @@ -359,7 +359,7 @@ That is, the minimum ``i`` such that ``self[i] != 0`` where ``i`` is in the range from ``0`` to ``bound - 1``. If *self* contains no non-zero items, then ``16`` is returned. -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The position of the first zero or ``16``. @@ -401,10 +401,10 @@ Returns the difference of the first diff. This function returns the first non-zero difference (if any) between in ``self[i]`` and ``other[i]`` among the first *bound* entries or ``0``. -:param other: The vector for comparison. +:param other: the vector for comparison. :type other: Vect16 -:param bound: The bound (defaults to ``16``). +:param bound: the bound (defaults to ``16``). :type bound: int :returns: The difference or ``0``. @@ -521,7 +521,7 @@ Returns whether or not the vector defines a permutation. This function returns ``True`` if the first *bound* entries of *self* define a permutation; and ``False`` otherwise. -:param bound: The number of entries to check (defaults to ``16``). +:param bound: the number of entries to check (defaults to ``16``). :type bound: int :returns: Whether or not *self* is a permutation of its first *bound* entries. @@ -603,7 +603,7 @@ This function constructs a :any:`PTransf16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`PTransf16` is padded with fixed points at the end. -:param img: The list of images. +:param img: the list of images. :type img: list[int] :raises LibsemigroupsError: if any value in *img* exceeds ``16`` and is not equal to ``255``. @@ -1268,7 +1268,7 @@ This function constructs a :any:`Transf16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`Transf16` is padded with fixed points at the end. -:param img: The list of images. +:param img: the list of images. :type img: list[int] :raises LibsemigroupsError: if any value in *img* is in the range :math:`[16, 256)`. @@ -1512,7 +1512,7 @@ order. This function returns the *r*-th permutation of size ``16`` in the Steinhaus–Johnson–Trotter order. -:param r: The index. +:param r: the index. :type r: int :returns: The *r*-th permutation. @@ -1565,7 +1565,7 @@ This function constructs a :any:`Perm16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`Perm16` is padded with fixed points at the end. -:param img: The list of images. +:param img: the list of images. :type img: list[int] :raises LibsemigroupsError: if any value in *img* is in the range :math:`[16, 256)`. @@ -2273,7 +2273,7 @@ This function constructs a :any:`PPerm16` from the list *img* of its entries. If the length of *img* is less than ``16``, then the constructed :any:`PPerm16` is padded with fixed points at the end. -:param img: The list of images. +:param img: the list of images. :type img: list[int] :raises LibsemigroupsError: diff --git a/src/knuth-bendix-impl.cpp b/src/knuth-bendix-impl.cpp index 34d924244..a6a9d01c5 100644 --- a/src/knuth-bendix-impl.cpp +++ b/src/knuth-bendix-impl.cpp @@ -167,7 +167,7 @@ The default value is ``128``, and should be set to ``1`` if :any:`Runner.run` should attempt to add each rule as it is created without waiting for rules to accumulate. -:param val: The new maximum number of pending rules. +:param val: the new maximum number of pending rules. :type val: int :returns: *self*. @@ -219,7 +219,7 @@ The default value is ``4096``, and should be set to :py:obj:`LIMIT_MAX` if :any:`Runner.run` should never check if the system is already confluent. -:param val: The new value of the interval. +:param val: the new value of the interval. :type val: int | LimitMax :returns: *self*. @@ -264,7 +264,7 @@ left hand sides of rules that should be considered in :any:`Runner.run`. If this value is less than the longest left hand side of a rule, then :any:`Runner.run` can terminate without the system being confluent. -:param val: The new value of the maximum overlap length. +:param val: the new value of the maximum overlap length. :type val: int | PositiveInfinity :returns: *self*. @@ -314,7 +314,7 @@ system may not be confluent. By default this value is :any:`POSITIVE_INFINITY`. -:param val: The maximum number of rules. +:param val: the maximum number of rules. :type val: int | PositiveInfinity :returns: *self*. @@ -353,7 +353,7 @@ Set the overlap policy. This function can be used to determine the way that the length of an overlap of two words in the system is measured. -:param val: The overlap policy. +:param val: the overlap policy. :type val: KnuthBendix.options.overlap :returns: *self*. diff --git a/src/pbr.cpp b/src/pbr.cpp index 628611fe8..76c4d94a7 100644 --- a/src/pbr.cpp +++ b/src/pbr.cpp @@ -259,7 +259,7 @@ This member function returns a new :any:`PBR` with degree equal to the :any:`PBR adjacent to ``i + n`` and vice versa for every ``i`` less than the degree ``n``. -:param x: A PBR. +:param x: a PBR. :type x: PBR :returns: The identity. diff --git a/src/present.cpp b/src/present.cpp index 35a6b22cf..316856814 100644 --- a/src/present.cpp +++ b/src/present.cpp @@ -1228,7 +1228,7 @@ are created by taking quotients of free semigroups or monoids. :param p: the presentation. :type p: Presentation -:param var_name: the name of the variable to be used in GAP. +:param var_name: the name of the variable to be used in GAP. :type var_name: str :returns: The GAP string. diff --git a/src/sims.cpp b/src/sims.cpp index fc81c856b..f68654a50 100644 --- a/src/sims.cpp +++ b/src/sims.cpp @@ -610,7 +610,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 use for reinitialization. :type that: {0} :returns: The re-initialized object. @@ -1142,7 +1142,7 @@ accepted by :any:`SimsRefinerFaithful` are not guaranteed to be faithful and must be checked by some other means. :param forbid: - A list of words such that ``(forbid[2*i], forbid[2*i+1])`` is the ``i``-th + a list of words such that ``(forbid[2*i], forbid[2*i+1])`` is the ``i``-th forbidden pair. :type forbid: list[list[int]] )pbdoc"); @@ -1198,7 +1198,7 @@ This function puts an object back into the same state as if it had been newly constructed from set of forbidden pairs *forbid*. :param forbid: - A list of words such that ``(forbid[2*i], forbid[2*i+1])`` is the ``i``-th + a list of words such that ``(forbid[2*i], forbid[2*i+1])`` is the ``i``-th forbidden pair. :type forbid: list[list[int]] @@ -1217,7 +1217,7 @@ 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. Otherwise returns ``True``. -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: A boolean. @@ -1262,7 +1262,7 @@ Construct from presentation. This function constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid defined by *p*. -:param p: A presentation. +:param p: a presentation. :type p: Presentation )pbdoc"); sri.def( @@ -1293,7 +1293,7 @@ Reinitialize an existing :any:`SimsRefinerIdeals` object from a presentation. This function puts an object back into the same state as if it had been newly constructed from the presentation *p*. -:param p: A presentation. +:param p: a presentation. :type p: Presentation :returns: The first argument *self*. @@ -1334,7 +1334,7 @@ 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``. -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: A boolean. @@ -1596,10 +1596,10 @@ This function returns the right congruence generating pairs of the right congruence defined by the word graph *wg* on the semigroup or monoid defined by *p*. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An iterator of generating pairs. @@ -1628,7 +1628,7 @@ the free monoid. This function returns the right congruence generating pairs of the right congruence defined by the word graph *wg* on the free monoid. -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An iterator of generating pairs. @@ -1658,10 +1658,10 @@ This function returns the two-sided congruence generating pairs of the two-sided congruence defined by the word graph *wg* on the semigroup or monoid defined by *p*. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An iterator of generating pairs. @@ -1696,7 +1696,7 @@ monoid. This function returns the two-sided congruence generating pairs of the two-sided congruence defined by the word graph *wg* on the free monoid. -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An iterator of generating pairs. @@ -1729,10 +1729,10 @@ monoid. Returns ``True`` if the word graph *wg* defines a right congruence on the semigroup or monoid defined by *p* and ``False`` otherwise. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An boolean. @@ -1757,10 +1757,10 @@ of the semigroup or monoid defined by *p* and ``False`` otherwise. This is equivalent to checking if the word graph defines a left congruence in the semigroup or monoid defined by *p*. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An boolean. @@ -1783,10 +1783,10 @@ monoid. Returns ``True`` if the word graph *wg* defines a two-sided congruence on the semigroup or monoid defined by *p* and ``False`` otherwise. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An boolean. @@ -1809,10 +1809,10 @@ or monoid. Returns ``True`` if the word graph *wg* defines a maximal right congruence on the semigroup or monoid defined by *p* and ``False`` otherwise. -:param p: A presentation. +:param p: a presentation. :type p: Presentation -:param wg: A word graph. +:param wg: a word graph. :type wg: WordGraph :returns: An boolean. @@ -1841,10 +1841,10 @@ When *n* is large enough, so that :any:`Sims1` computes all right congruences of a given semigroup or monoid, then this is equivalent to computing the right congruence lattice of the semigroup or monoid. -:param sims: A :any:`Sims1` object. +:param sims: a :any:`Sims1` object. :type sims: Sims1 -:param n: Maximum number of congruence classes. +:param n: maximum number of congruence classes. :type n: int :returns: A boolean matrix defining the congruence poset. @@ -1873,10 +1873,10 @@ When *n* is large enough, so that :any:`Sims2` computes all two-sided congruences of a given semigroup or monoid, then this is equivalent to computing the two-sided congruence lattice of the semigroup or monoid. -:param sims: A :any:`Sims2` object. +:param sims: a :any:`Sims2` object. :type sims: Sims2 -:param n: Maximum number of congruence classes. +:param n: maximum number of congruence classes. :type n: int :returns: A boolean matrix defining the congruence poset. From 71b7864c39a9abdc962b212320b583f7e94744cc Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Fri, 1 May 2026 23:44:45 +0100 Subject: [PATCH 22/24] Fox more doc with presentation examples --- src/presentation-examples.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/presentation-examples.cpp b/src/presentation-examples.cpp index 8720f809d..94194a5f0 100644 --- a/src/presentation-examples.cpp +++ b/src/presentation-examples.cpp @@ -1023,7 +1023,7 @@ degree *n*, as in Theorem 41 of :cite:`East2011aa`. .. seealso:: - For a specific presentation of the symmetric group, see one of the + For a specific presentation of the partition monoid, see one of the following functions: * :any:`partition_monoid_Eas11`; From ffdf50d4a87d0ad8ba3e8c3ff9b1f4295eca4331 Mon Sep 17 00:00:00 2001 From: Joseph Edwards Date: Fri, 1 May 2026 23:54:20 +0100 Subject: [PATCH 23/24] Fix a vs an --- src/todd-coxeter.cpp | 2 +- src/ukkonen.cpp | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/todd-coxeter.cpp b/src/todd-coxeter.cpp index a88b0c197..10ad3aaf6 100644 --- a/src/todd-coxeter.cpp +++ b/src/todd-coxeter.cpp @@ -836,7 +836,7 @@ instance *tc*. Calls to this function trigger a full enumeration of *tc*. :param n: the index of the class. :type n: int -:returns: A iterator yielding the class with index *n*. +:returns: An iterator yielding the class with index *n*. :rtype: collections.abc.Iterator[list[int] | str] :raises LibsemigroupsError: diff --git a/src/ukkonen.cpp b/src/ukkonen.cpp index 536f82e19..dc8036ae2 100644 --- a/src/ukkonen.cpp +++ b/src/ukkonen.cpp @@ -800,7 +800,7 @@ had been newly default constructed. Check if a state corresponds to a suffix. -This function returns a an int if the state *st* corresponds to a suffix of any +This function returns an int if the state *st* corresponds to a suffix of any word in the suffix tree. The value returned is the index of the word which the state is a suffix of if such a word exists, and :any:`UNDEFINED` otherwise. From 967527262782b3fdf06e29cd1083ca3d8335f0ef Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Sat, 2 May 2026 09:17:33 +0100 Subject: [PATCH 24/24] Format --- src/present.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/present.cpp b/src/present.cpp index 316856814..d367baf17 100644 --- a/src/present.cpp +++ b/src/present.cpp @@ -1654,7 +1654,7 @@ defined in the alphabet, and that the inverses act as semigroup inverses. * :any:`presentation.throw_if_bad_inverses` )pbdoc"); } // bind_inverse_present - } // namespace + } // namespace void init_present(py::module& m) { bind_present(m, "PresentationWord");