From 8be057843a863fd3fd3231fa6e61ea8f1ee70410 Mon Sep 17 00:00:00 2001 From: reiniscirpons Date: Wed, 30 Oct 2024 16:59:15 +0000 Subject: [PATCH] First pass formatting changes to docs --- docs/source/conf.py | 29 +- src/sims.cpp | 934 +++++++++++++++++++++++++++++--------------- 2 files changed, 645 insertions(+), 318 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ef9637ca..614aae72 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,7 +55,9 @@ def doc_only_run(self): docstring = list(node.findall(condition=desc_content)) if not docstring: - logger.warning(f"The docstring for {self.arguments[0]} cannot be found.") + logger.warning( + f"The docstring for {self.arguments[0]} cannot be found." + ) return [] return docstring @@ -101,7 +103,9 @@ def no_doc_run(self): source_suffix = ".rst" master_doc = "index" project = "libsemigroups_pybind11" -copyright = "2021-2024, Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte" +copyright = ( + "2021-2024, Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte" +) author = "Joseph Edwards, James Mitchell, Maria Tsalakou, Murray Whyte" version = "1.0.0" release = "1.0.0" @@ -158,6 +162,8 @@ def no_doc_run(self): r"libsemigroups::IntegerProd, libsemigroups::IntegerZero" r", libsemigroups::IntegerOne, long long>" ): r"Matrix", + r"libsemigroups::Sims1": r"Sims1", + r"SimsSettingsSims1": r"Sims1", } # This dictionary should be of the form class_name -> (pattern, repl), where @@ -181,6 +187,10 @@ def no_doc_run(self): "FroidurePinPBR": [(r"\bPBR\b", "Element")], "SchreierSimsPerm1": [(r"\bPerm1\b", "Element")], "ReversiblePaths": [(r"\bPaths\b", "ReversiblePaths")], + "Sims1": [("SubclassType", "Sims1")], + "Sims2": [("SubclassType", "Sims2")], + "RepOrc": [("SubclassType", "RepOrc")], + "MinimalRepOrc": [("SubclassType", "MinimalRepOrc")], } # This is what sphinx considers to be a signature @@ -302,7 +312,8 @@ def make_only_doc(lines): if not called_correctly: raise RuntimeError( ":only-document-once: has been invoked in a function where " - "documentation has not been repeated. Invoked in:\n" + "\n".join(lines) + "documentation has not been repeated. Invoked in:\n" + + "\n".join(lines) ) # If the new doc shouldn't be overloaded, remove the "Overloaded @@ -312,7 +323,9 @@ def make_only_doc(lines): del lines[0] -def only_doc_once(app, what, name, obj, options, lines): # pylint:disable=too-many-arguments,too-many-positional-arguments +def only_doc_once( + app, what, name, obj, options, lines +): # pylint:disable=too-many-arguments,too-many-positional-arguments """ Edit docstring to only include one version of the doc for an overloaded function if necessary @@ -322,7 +335,9 @@ def only_doc_once(app, what, name, obj, options, lines): # pylint:disable=too-m make_only_doc(lines) -def fix_overloads(app, what, name, obj, options, lines): # pylint:disable=too-many-arguments,too-many-positional-arguments +def fix_overloads( + app, what, name, obj, options, lines +): # pylint:disable=too-many-arguments,too-many-positional-arguments """Indent overloaded function documentation and format signatures""" overloading = False overloaded_function = "" @@ -395,7 +410,9 @@ def fix_overloads(app, what, name, obj, options, lines): # pylint:disable=too-m } -def remove_doc_annotations(app, what, name, obj, options, lines): # pylint:disable=too-many-arguments,too-many-positional-arguments +def remove_doc_annotations( + app, what, name, obj, options, lines +): # pylint:disable=too-many-arguments,too-many-positional-arguments """Remove any special decorations from the documentation""" for i in range(len(lines) - 1, -1, -1): for bad, good in docstring_replacements.items(): diff --git a/src/sims.cpp b/src/sims.cpp index ddd31e05..80c5854f 100644 --- a/src/sims.cpp +++ b/src/sims.cpp @@ -56,9 +56,13 @@ namespace libsemigroups { py::class_ ss(m, name.c_str(), R"pbdoc( -For setting the presentation and various runtime parameters of the Sims low index algorithm. +For setting the presentation and various runtime parameters of the Sims low +index algorithm. -Defined in ``sims.hpp``. On this page we describe the :any:`SimsSettings` class. The purpose of this class is to allow us to use the same interface for settings for :any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , and :any:`MinimalRepOrc`. +Defined in ``sims.hpp``. On this page we describe the :any:`SimsSettings` +class. The purpose of this class is to allow us to use the same interface for +settings for :any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , and +:any:`MinimalRepOrc`. .. seealso:: :any:`Sims1` @@ -66,9 +70,11 @@ Defined in ``sims.hpp``. On this page we describe the :any:`SimsSettings` class. .. seealso:: :any:`RepOrc` -.. seealso:: :any:`MinimalRepOrc`)pbdoc"); +.. seealso:: :any:`MinimalRepOrc` +)pbdoc"); ss.def(py::init<>(), R"pbdoc( -Default constructor.Constructs a :any:`SimsSettings` object. Defaults to a single thread and 64 idle thread restarts, no other settings set. Use +Default constructor.Constructs a :any:`SimsSettings` object. Defaults to a +single thread and 64 idle thread restarts, no other settings set. Use * :any:`presentation` to set the presentation; * :any:`number_of_threads` to set the number of threads; @@ -82,12 +88,16 @@ Default constructor.Constructs a :any:`SimsSettings` object. Defaults to a singl :parameters (none): -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +)pbdoc"); ss.def(py::init(), R"pbdoc( :param that: the SimsSettings to copy. :type that: SimsSettings -Copy constructor.Returns a :any:`SimsSettings` object that is a copy of ``that`` . The state of the new :any:`SimsSettings` object is the same as ``that``. + +Copy constructor.Returns a :any:`SimsSettings` object that is a copy of +``that`` . The state of the new :any:`SimsSettings` object is the same as +``that``. :exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); ss.def( @@ -95,26 +105,28 @@ Copy constructor.Returns a :any:`SimsSettings` object that is a copy of ``that`` [](SimsSettings_& self) -> Subclass& { return self.init(); }, R"pbdoc( Reinitialize an existing SimsSettings object. -This function puts a :any:`SimsSettings` object back into the same state as if it had been newly default constructed. -:parameters (none): +This function puts a :any:`SimsSettings` object back into the same state as if +it had been newly default constructed. -:raises This: function guarantees not to throw a :any:`LibsemigroupsError`. - -:returns: A reference to ``self``. +:raises: This function guarantees not to throw a :any:`LibsemigroupsError`. -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def("settings", &SimsSettings_::settings, R"pbdoc( -Returns the settings object of *this.The settings object contains all the settings that are common to :any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , and :any:`MinimalRepOrc` , which are currently: +Returns the settings object of *this.The settings object contains all the +settings that are common to :any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , and +:any:`MinimalRepOrc` , which are currently: * :any:`presentation` * :any:`long_rules` * :any:`number_of_threads` -The return value of this function can be used to initialise another :any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , or :any:`MinimalRepOrc` with these settings. +The return value of this function can be used to initialise another +:any:`Sims1` , :any:`Sims2` , :any:`RepOrc` , or :any:`MinimalRepOrc` with +these settings. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -135,21 +147,20 @@ Set the number of threads. :param val: the maximum number of threads to use. :type val: int -This function sets the number of threads to be used by :any:`Sims1` or :any:`Sims2`.The default value is ``1``. -:raises LibsemigroupsError: if the argument ``val`` is 0. +This function sets the number of threads to be used by :any:`Sims1` or +:any:`Sims2`. The default value is ``1``. +:raises LibsemigroupsError: if the argument *val* is 0. -:returns: A reference to ``self``. -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def( "number_of_threads", [](SimsSettings_ const& self) { return self.number_of_threads(); }, R"pbdoc( Get the number of threads. -Returns the current number of threads. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -164,24 +175,29 @@ Returns the current number of threads. }, py::arg("p"), R"pbdoc( -Set the presentation over which the congruences produced by an instance are defined. - -:param p: the presentation. -:type p: Presentation -Set the presentation over which the congruences produced by an instance are defined. These are the rules used at every node in the depth first search conducted by objects of this type.If the template parameter ``Word`` is not ``word_type`` , then the parameter ``p`` is first converted to a value of type ``Presentation`` and it is this converted value that is used. +:sig=(self: SubclassType, p: Presentation) -> SubclassType: +:only-document-once: -:raises LibsemigroupsError: if ``to_presentation(p)`` throws. +Set the presentation over which the congruences produced by an instance are +defined. -:raises LibsemigroupsError: if ``p`` is not valid. +This function sets the presentation over which the congruences produced by an +instance are defined. These are the rules used at every node in the depth first +search conducted by objects of this type. The parameter *p* is always first +converted to a :any:`Presentation` of :ref:`Word` and +it is this converted value that is used. -:raises LibsemigroupsError: if the alphabet of ``p`` is non-empty and not equal to that of :any:`long_rules` or :any:`presentation`. +:type p: Presentation +:param p: the presentation. -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. +:returns: A reference to *self*. +:raises LibsemigroupsError: if :any:`to_presentation(p)` throws. -:returns: A reference to ``self``. +:raises LibsemigroupsError: if the alphabet of *p* is non-empty and not equal +to that of :any:`long_rules` or :any:`presentation`. -:rtype: typename Word +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. )pbdoc"); ss.def( "presentation", @@ -189,37 +205,49 @@ Set the presentation over which the congruences produced by an instance are defi -> Subclass& { return self.presentation(p); }, py::arg("p"), R"pbdoc( -Set the presentation over which the congruences produced by an instance are defined. - -:param p: the presentation. -:type p: Presentation -Set the presentation over which the congruences produced by an instance are defined. These are the rules used at every node in the depth first search conducted by objects of this type.If the template parameter ``Word`` is not ``word_type`` , then the parameter ``p`` is first converted to a value of type ``Presentation`` and it is this converted value that is used. +:sig=(self: SubclassType, p: Presentation) -> SubclassType: +:only-document-once: -:raises LibsemigroupsError: if ``to_presentation(p)`` throws. +Set the presentation over which the congruences produced by an instance are +defined. -:raises LibsemigroupsError: if ``p`` is not valid. +This function sets the presentation over which the congruences produced by an +instance are defined. These are the rules used at every node in the depth first +search conducted by objects of this type. The parameter *p* is always first +converted to a :any:`Presentation` of :ref:`Word` and +it is this converted value that is used. -:raises LibsemigroupsError: if the alphabet of ``p`` is non-empty and not equal to that of :any:`long_rules` or :any:`presentation`. +:param p: the presentation. +:type p: Presentation -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. +:returns: A reference to *self*. +:raises LibsemigroupsError: if :any:`to_presentation(p)` throws. -:returns: A reference to ``self``. +:raises LibsemigroupsError: if the alphabet of *p* is non-empty and not equal +to that of :any:`long_rules` or :any:`presentation`. -:rtype: typename Word +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. )pbdoc"); ss.def( "presentation", [](SimsSettings_ const& self) { return self.presentation(); }, R"pbdoc( -Get the presentation over which the congruences produced by an instance are defined. -Returns a const reference to the current relations of the underlying presentation.This function returns the defining presentation of a :any:`Sims1` or :any:`Sims2` instance. The congruences computed by ``cbegin`` and ``cend`` of the appropriate subclass are defined over the semigroup or monoid defined by this presentation. +:sig=(self: SubclassType) -> Presentation: +:only-document-once: -:exceptions: This function is ``noexcept`` and is guaranteed never to throw. +Get the presentation over which the congruences produced by an instance are +defined. -:returns: A const reference to ``Presentation``. +This function returns the defining presentation of a :any:`Sims1` or +:any:`Sims2` instance. The congruences computed by `~Sims1.iterator` of the +appropriate subclass are defined over the semigroup or monoid defined by this +presentation. +:returns: A const reference to ``Presentation``. :rtype: Presentation + +:exceptions: This function is ``noexcept`` and is guaranteed never to throw. )pbdoc"); ss.def( "first_long_rule_position", @@ -232,16 +260,24 @@ Set the beginning of the long rules (position). :param pos: position of the the left hand side of the first long rule. :type pos: int -Set the beginning of the long rules using a position in ``presentation().rules``.The "long rules" are the rules used after a complete deterministic word graph has been found in the search. If such a word graph is compatible with the long rules specified by this function, then this word graph is accepted, and if not it is rejected.The purpose of this is to improve the backtrack search by reducing the time spent processing "long" rules in each node of the search tree, and to only check them at the leaves. -:raises LibsemigroupsError: if ``pos`` is not a valid position in ``presentation().rules`` +This function sets the beginning of the long rules using a position in +``self.presentation().rules``. The "long rules" are the rules used after a +complete deterministic word graph has been found in the search. If such a word +graph is compatible with the long rules specified by this function, then this +word graph is accepted, and if not it is rejected. -:raises LibsemigroupsError: if the rule at position ``pos`` is not the left hand side of a rule (i.e. if ``pos`` is odd). +The purpose of this is to improve the backtrack search by reducing the time +spent processing "long" rules in each node of the search tree, and to only +check them at the leaves. +:raises LibsemigroupsError: if *pos* is not a valid position in +``self.presentation().rules``. -:returns: A reference to ``self``. +:raises LibsemigroupsError: if the rule at position *pos* is not the left hand +side of a rule (i.e. if *pos* is odd). -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def( "long_rules", @@ -250,14 +286,15 @@ Set the beginning of the long rules using a position in ``presentation().rules`` self.presentation().rules.cend()); }, R"pbdoc( -Get the pointer to the first long rule. -Returns the pointer to the first long rule. +Get the long rules. + +Returns an iterator of long rules. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:returns: A const reference to ``Presentation``. +:returns: A const reference to :any:`Presentation`. -:rtype: Iterator +:rtype: Iterator[Tuple[Word, Word]] )pbdoc"); ss.def( "clear_long_rules", @@ -269,9 +306,7 @@ Clear the set of long rules. :exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. - -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def("number_of_long_rules", &SimsSettings_::number_of_long_rules, @@ -287,22 +322,33 @@ Returns the number of rules marked as long rules. R"pbdoc( Set the length of a long rule. -:param val: the value of the long rule length. +:param val: the long rule length. :type val: int -Define the length of a "long" rule.This function modifies :any:`presentation` so that the rules whose length (sum of the lengths of both sizes) is at least ``val`` (if any) occur at the end of ``presentation().rules`` and so that ``cbegin_long_rules`` points at the such rule.The relative orders of the rules within :any:`presentation` may not be preserved. -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +Define the length of a "long" rule. This function modifies +:py:meth:`~Sims1.presentation()` so that the rules whose length (sum of the +lengths of both sides) is at least *val* (if any) occur at the end of +``presentation().rules`` and so that :py:meth:`~Sims1.long_rules` returns all +such rules. The relative orders of the rules within +:py:meth:`~Sims1.presentation` may not be preserved. +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. - -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def("pruners", &SimsSettings_::pruners, R"pbdoc( Get all active pruners of the search tree. -Returns a const reference to the set of pruners.A pruner is any function that takes as input a word graph and returns a boolean. We require that if a pruner returns false for a word graph ``wg`` , then it returns false for all word graphs that are descended from ``wg`` in the Sims word graph search tree. The pruners are used to refine the congruence search tree during the execution of the Sims algorithm. As such, the congruences computed by this instance are only taken among those whose word graphs are accepted by all pruners returned by :any:`pruners`. + +Returns a const reference to the set of pruners.A pruner is any function that +takes as input a word graph and returns a boolean. We require that if a pruner +returns false for a word graph ``wg`` , then it returns false for all word +graphs that are descended from ``wg`` in the Sims word graph search tree. The +pruners are used to refine the congruence search tree during the execution of +the Sims algorithm. As such, the congruences computed by this instance are only +taken among those whose word graphs are accepted by all pruners returned by +:any:`pruners`. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -315,16 +361,22 @@ Returns a const reference to the set of pruners.A pruner is any function that ta [](SimsSettings_& self, SimsRefinerIdeals const& func) -> Subclass& { return self.add_pruner(func); }, + py::arg("pruner"), R"pbdoc( - TODO(0) +:sig=(self: Sims1, pruner: Callable[[WordGraph], bool]) -> Sims1: +:only-document-once: +TODO(0) Doc )pbdoc"); ss.def( "add_pruner", [](SimsSettings_& self, SimsRefinerFaithful const& func) -> Subclass& { return self.add_pruner(func); }, + py::arg("pruner"), R"pbdoc( - TODO(0) +:sig=(self: Sims1, pruner: Callable[[WordGraph], bool]) -> Sims1: +:only-document-once: +TODO(0) Doc )pbdoc"); ss.def( "add_pruner", @@ -332,8 +384,11 @@ Returns a const reference to the set of pruners.A pruner is any function that ta std::function func) -> Subclass& { return self.add_pruner(func); }, + py::arg("pruner"), R"pbdoc( - TODO(0) +:sig=(self: Sims1, pruner: Callable[[WordGraph], bool]) -> Sims1: +:only-document-once: +TODO(0) Doc )pbdoc"); ss.def( "clear_pruners", @@ -343,22 +398,27 @@ Clear the set of pruners. :exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. - -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def( "include", [](SimsSettings_ const& self) { return self.include(); }, R"pbdoc( -Get the set of pairs that must be included in every congruence. -Returns a const reference to the (one-sided) defining pairs.The congruences computed by a :any:`Sims1` or :any:`Sims2` instance always contain the relations of this presentation. In other words, the congruences computed by this instance are only taken among those that contains the pairs of elements of the underlying semigroup (defined by the presentation returned by :any:`presentation` and :any:`long_rules` ) represented by the relations of the presentation returned by :any:`include`. +:sig=(self: SubclassType) -> List[Word]: +Returns the set of pairs that must be excluded from every congruence. -:exceptions: This function is ``noexcept`` and is guaranteed never to throw. +This function returns the list of included pairs The congruences computed by a +:any:`Sims1` or :any:`Sims2` instance always contain the relations of this +list. In other words, the congruences computed by this instance are only taken +among those that contains the pairs of elements of the underlying semigroup +(defined by the presentation returned by :py:meth:`~Sims1.presentation()` and +:py:meth:`~Sims1.long_rules()`) represented by the relations of the list of +words returned by :py:meth:`~Sims1.include()`. -:returns: A const reference to ``Presentation``. +:exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:rtype: list +:returns: A list of words ``result`` such that ``(result[2*i], result[2*i+1])`` +is the ``i``-th included pair. )pbdoc"); ss.def( "include", @@ -367,45 +427,46 @@ Returns a const reference to the (one-sided) defining pairs.The congruences comp py::arg("lhs"), py::arg("rhs"), R"pbdoc( +:sig=(self: SubclassType, lhs: Word, rhs: Word) -> SubclassType: Add a pair that should be included in every congruence. :param lhs: the left hand side of the rule being added. -:type lhs: word_type +:type lhs: :ref:`Word` :param rhs: the right hand side of the rule being added. -:type rhs: word_type -Add a pair that should be included in every congruence. - -:raises LibsemigroupsError: if ``validate_word(lhs)`` or ``validate_word(rhs)`` throws. +:type rhs: :ref:`Word` -.. seealso:: :any:`include` +:raises LibsemigroupsError: if :any:`validate_word` throws on *lhs* or *rhs*. - -:returns: A reference to ``self``. - -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def( "include", [](SimsSettings_& self, std::vector const& c) -> Subclass& { return self.include(c); }, - py::arg("c"), + py::arg("included_pairs"), R"pbdoc( -Define the set of pairs that must be included in every congruence (container). - -:param c: A container of rules to be included. -:type c: Container -Define the set of pairs that must be included in every congruence.The congruences computed by an instance of this type will always contain the relations input here. In other words, the congruences computed are only taken among those that contains the pairs of elements of the underlying semigroup (defined by the presentation returned by :any:`presentation` ) represented by the relations returned by :any:`include`. +:sig=(self: SubclassType, included_pairs: list[Word]) -> SubclassType: +Define the set of pairs that must be included in every congruence. -:raises LibsemigroupsError: if ``c`` does not define a set of pairs, i.e. there are an odd number of words in ``c``. +:param included_pairs: A list of pairs to be included. +:type included_pairs: List[:ref:`Word`] -:raises LibsemigroupsError: if ``validate_word(w)`` throws for any word ``w`` in ``c``. +Define the set of pairs that must be included in every congruence. The +congruences computed by an instance of this type will always contain the +relations input here. In other words, the congruences computed are only taken +among those that contains the pairs of elements of the underlying semigroup +(defined by the presentation returned by :py:meth:`~Sims1.presentation` ) +represented by the relations returned by :py:meth:`~Sims1.include`. +:raises LibsemigroupsError: if *included_pairs* does not define a set of +pairs, i.e. there are an odd number of words in *included_pairs*. -:returns: A reference to ``self``. +:raises LibsemigroupsError: if :py:meth:`validate_word` throws for any word +``w`` in *included_pairs. -:rtype: typename Container +:returns: A reference to *self*. )pbdoc"); ss.def( "clear_include", @@ -415,22 +476,29 @@ Clear the set of included words. :exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. +:returns: A reference to *self*. -:rtype: Subclass )pbdoc"); ss.def( "exclude", [](SimsSettings_ const& self) { return self.exclude(); }, R"pbdoc( -Get the set of pairs that must be excluded from every congruence. -Returns a const reference to the excluded pairs.The congruences computed by a :any:`Sims1` or :any:`Sims2` instance will never contain the relations of this presentation. In other words, the congruences computed by this instance are only taken among those that do not contain any of the pairs of elements of the underlying semigroup (defined by the presentation returned by :any:`presentation` and :any:`long_rules` ) represented by the relations of the presentation returned by :any:`exclude`. +:sig=(self: SubclassType) -> List[Word]: +Returns the set of pairs that must be excluded from every congruence. -:exceptions: This function is ``noexcept`` and is guaranteed never to throw. +This function returns the list of excluded pairs. The congruences computed by a +:any:`Sims1` or :any:`Sims2` instance will never contain the relations of this +presentation. In other words, the congruences computed by this instance are +only taken among those that do not contain any of the pairs of elements of the +underlying semigroup (defined by the presentation returned by +:py:meth:`~Sims1.presentation()` and :py:meth:`~Sims1.long_rules()`) +represented by the relations of the presentation returned by +:py:meth:`~Sims1.exclude()`. -:returns: A const reference to ``Presentation``. +:exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:rtype: list +:returns: A list of words ``result`` such that ``(result[2*i], result[2*i+1])`` +is the ``i``-th excluded pair. )pbdoc"); ss.def( "exclude", @@ -440,39 +508,47 @@ Returns a const reference to the excluded pairs.The congruences computed by a :a py::arg("lhs"), py::arg("rhs"), R"pbdoc( +:sig=(self: SubclassType, lhs: Word, rhs: Word) -> SubclassType: Add a pair that must be excluded from every congruence. :param lhs: the left hand side of the rule being added. -:type lhs: word_type +:type lhs: :ref:`Word` :param rhs: the right hand side of the rule being added. -:type rhs: word_type -Add a pair that must be excluded from every congruence. +:type rhs: :ref:`Word` -:raises LibsemigroupsError: if ``validate_word(lhs)`` or ``validate_word(rhs)`` throws. +:raises LibsemigroupsError: if :any:`validate_word` throws on *lhs* or *rhs*. -.. seealso:: :any:`exclude`)pbdoc"); +:returns: A reference to *self*. +)pbdoc"); ss.def( "exclude", [](SimsSettings_& self, std::vector const& c) -> Subclass& { return self.exclude(c); }, - py::arg("c"), + py::arg("excluded_pairs"), R"pbdoc( -Define the set of pairs that must be excluded from every congruence (container). +:sig=(self: SubclassType, exluded_pairs: list[Word]) -> SubclassType: +Define the set of pairs that must be excluded from every congruence. -:param c: A container of rules to be excluded. -:type c: Container -Define the set of pairs that must be excluded from every congruence.The congruences computed by an instance of this type will never contain the relations input here. In other words, the congruences computed are only taken among those that do not contain the pairs of elements of the underlying semigroup (defined by the presentation returned by :any:`presentation` ) represented by the relations returned by ``exclude()``.Define a set of pairs that should be included in every congruence. +:param excluded_pairs: A list of pairs to be excluded. +:type excluded_pairs: List[:ref:`Word`] -:raises LibsemigroupsError: if ``c`` does not define a set of pairs, i.e. there are an odd number of words in ``c``. +This function defines the set of pairs that must be excluded from every +congruence. The congruences computed by an instance of this type will never +contain the relations input here. In other words, the congruences computed are +only taken among those that do not contain the pairs of elements of the +underlying semigroup (defined by the presentation returned by +:py:meth:`~Sims1.presentation` ) represented by the relations returned by +:py:meth:`~Sims1.exclude`. -:raises LibsemigroupsError: if ``validate_word(w)`` throws for any word ``w`` in ``c``. +:raises LibsemigroupsError: if *excluded_pairs* does not define a set of +pairs, i.e. there are an odd number of words in *excluded_pairs*. +:raises LibsemigroupsError: if :py:meth:`validate_word` throws for any word +``w`` in *excluded_pairs. -:returns: A reference to ``self``. - -:rtype: typename Container +:returns: A reference to *self*. )pbdoc"); ss.def( "clear_exclude", @@ -482,15 +558,18 @@ Clear the set of excluded words. :exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. +:returns: A reference to *self*. -:rtype: Subclass )pbdoc"); ss.def("stats", &SimsSettings_::stats, R"pbdoc( Get the current stats object. -Returns a const reference to the current stats object.The value returned by this function is a ``SimsStats`` object which contains some statistics related to the current :any:`Sims1` or :any:`Sims2` instance and any part of the depth first search already conducted. + +Returns a const reference to the current stats object.The value returned by +this function is a ``SimsStats`` object which contains some statistics related +to the current :any:`Sims1` or :any:`Sims2` instance and any part of the depth +first search already conducted. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -503,13 +582,11 @@ Returns a const reference to the current stats object.The value returned by this [](SimsSettings_ const& self) { return self.idle_thread_restarts(); }, R"pbdoc( Get the idle thread restart attempt count. -Returns the number of times an idle thread will attempt to restart before yielding during the execution of :any:`Sims1` or :any:`Sims2`. -:exceptions: This function is ``noexcept`` and is guaranteed never to throw. - -:returns: A const reference to ``std::vector>`` , the set of all pruners. +Returns the number of times an idle thread will attempt to restart before +yielding during execution. -:rtype: int +:exceptions: This function is ``noexcept`` and is guaranteed never to throw. )pbdoc"); ss.def( "idle_thread_restarts", @@ -520,16 +597,16 @@ Returns the number of times an idle thread will attempt to restart before yieldi R"pbdoc( Set the idle thread restart attempt count. -:param val: the maximum number of times an idle thread will attempt to restart before yielding. +:param val: the maximum number of times an idle thread will attempt to restart +before yielding. :type val: int -This function sets the idle thread restart attempt count used in :any:`Sims1` or :any:`Sims2`.The default value is ``64``. -:raises LibsemigroupsError: if the argument ``val`` is 0. +This function sets the idle thread restart attempt count. The default value is +``64``. +:raises LibsemigroupsError: if the argument *val* is 0. -:returns: A reference to ``self``. - -:rtype: Subclass +:returns: A reference to *self*. )pbdoc"); ss.def(py::init(), R"pbdoc( Construct from Subclass object @@ -596,9 +673,12 @@ Initialize from MinimalRepOrc object. py::class_ st(m, "SimsStats", R"pbdoc( -For keeping track of various statistics arising during the runtime of the low index algorithm. +For keeping track of various statistics arising during the runtime of the low +index algorithm. -Defined in ``sims.hpp``.On this page we describe the :any:`SimsStats` class. The purpose of this class is to collect some statistics related to :any:`Sims1` or :any:`Sims2` class template. +Defined in ``sims.hpp``.On this page we describe the :any:`SimsStats` class. +The purpose of this class is to collect some statistics related to :any:`Sims1` +or :any:`Sims2` class template. .. seealso:: :any:`Sims1` @@ -609,64 +689,96 @@ Defined in ``sims.hpp``.On this page we describe the :any:`SimsStats` class. The "count_last", [](SimsStats const& d) { return d.count_last.load(); }, R"pbdoc( -Number of congruences found at time of last report.This member holds the of the number of congruences found by the :any:`Sims1` or :any:`Sims2` algorithm at the time of the last call to :any:`stats_check_point`. +Number of congruences found at time of last report.This member holds the of the +number of congruences found by the :any:`Sims1` or :any:`Sims2` algorithm at +the time of the last call to :any:`stats_check_point`. .. seealso:: :any:`stats_check_point` -.. seealso:: :any:`count_now`)pbdoc"); +.. seealso:: :any:`count_now` +)pbdoc"); st.def( "count_now", [](SimsStats const& d) { return d.count_now.load(); }, R"pbdoc( -Number of congruences found up to this point.This member tracks the total number of congruences found during the running of the :any:`Sims1` or :any:`Sims2` algorithm. +Number of congruences found up to this point.This member tracks the total +number of congruences found during the running of the :any:`Sims1` or +:any:`Sims2` algorithm. -.. seealso:: :any:`count_last`)pbdoc"); +.. seealso:: :any:`count_last` +)pbdoc"); st.def( "max_pending", [](SimsStats const& d) { return d.max_pending.load(); }, R"pbdoc( -The maximum number of pending definitions.A *pending definition* is just an edge that will be defined at some point in the future in the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment.This member tracks the maximum number of such pending definitions that occur during the running of the algorithms in :any:`Sims1` or :any:`Sims2`.)pbdoc"); +The maximum number of pending definitions.A *pending definition* is just an +edge that will be defined at some point in the future in the :any:`WordGraph` +represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment.This +member tracks the maximum number of such pending definitions that occur during +the running of the algorithms in :any:`Sims1` or :any:`Sims2`. +)pbdoc"); st.def( "total_pending_last", [](SimsStats const& d) { return d.total_pending_last.load(); }, R"pbdoc( -The total number of pending definitions at time of last report.A *pending definition* is just an edge that will be defined at some point in the future in the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment.This member tracks the total number of pending definitions that occur at the time of the last call to :any:`stats_check_point` . This is the same as the number of nodes in the search tree encounter during the running of :any:`Sims1` or :any:`Sims2`. +The total number of pending definitions at time of last report.A *pending +definition* is just an edge that will be defined at some point in the future in +the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at +any given moment.This member tracks the total number of pending definitions +that occur at the time of the last call to :any:`stats_check_point` . This is +the same as the number of nodes in the search tree encounter during the running +of :any:`Sims1` or :any:`Sims2`. .. seealso:: :any:`stats_check_point` -.. seealso:: :any:`total_pending_now`)pbdoc"); +.. seealso:: :any:`total_pending_now` +)pbdoc"); st.def( "total_pending_now", [](SimsStats const& d) { return d.total_pending_now.load(); }, R"pbdoc( -The total number of pending definitions.A *pending definition* is just an edge that will be defined at some point in the future in the :any:`WordGraph` represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment.This member tracks the total number of pending definitions that occur during the running of the algorithms in :any:`Sims1` or :any:`Sims2` . This is the same as the number of nodes in the search tree encounter during the running of :any:`Sims1` or :any:`Sims2`. +The total number of pending definitions.A *pending definition* is just an edge +that will be defined at some point in the future in the :any:`WordGraph` +represented by a :any:`Sims1` or :any:`Sims2` instance at any given moment.This +member tracks the total number of pending definitions that occur during the +running of the algorithms in :any:`Sims1` or :any:`Sims2` . This is the same as +the number of nodes in the search tree encounter during the running of +:any:`Sims1` or :any:`Sims2`. -.. seealso:: :any:`total_pending_last`)pbdoc"); +.. seealso:: :any:`total_pending_last` +)pbdoc"); st.def(py::init<>(), R"pbdoc( -Default constructor.Constructs a :any:`SimsStats` object with all statistics set to zero. +Default constructor.Constructs a :any:`SimsStats` object with all statistics +set to zero. :parameters (none): -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +)pbdoc"); st.def(py::init(), R"pbdoc( :param that: the SimsStats to copy. :type that: SimsStats -Copy constructor.Returns a :any:`SimsStats` object that is a copy of ``that`` . The state of the new :any:`SimsStats` object is the same as ``that`` . This triggers an atomic load on the member variables of ``that``. -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); +Copy constructor.Returns a :any:`SimsStats` object that is a copy of ``that`` . +The state of the new :any:`SimsStats` object is the same as ``that`` . This +triggers an atomic load on the member variables of ``that``. + +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +)pbdoc"); st.def( "init", [](SimsStats& self) -> SimsStats& { return self.init(); }, R"pbdoc( Reinitialize an existing SimsStats object. -This function puts a :any:`SimsStats` object back into the same state as if it had been newly default constructed. +This function puts a :any:`SimsStats` object back into the same state as if it +had been newly default constructed. :parameters (none): :raises This: function guarantees not to throw a :any:`LibsemigroupsError`. -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: SimsStats )pbdoc"); @@ -683,11 +795,14 @@ Initialize from SimsStats. &SimsStats::stats_check_point, R"pbdoc( Store the current statistic values. -Overwrites the values of :any:`count_last` and :any:`total_pending_last` with :any:`count_now` and :any:`total_pending_now` respectively. Triggers an atomic load on :any:`count_now` and :any:`total_pending_now`. +Overwrites the values of :any:`count_last` and :any:`total_pending_last` with +:any:`count_now` and :any:`total_pending_now` respectively. Triggers an atomic +load on :any:`count_now` and :any:`total_pending_now`. :parameters (none): -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +)pbdoc"); st.def("stats_zero", &SimsStats::stats_zero, R"pbdoc( @@ -696,61 +811,75 @@ Set all statistics to zero. :parameters (none): -:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`.)pbdoc"); +:exceptions: This function guarantees not to throw a :any:`LibsemigroupsError`. +)pbdoc"); py::class_> s1(m, "Sims1", R"pbdoc( -For computing finite index right congruences of a finitely presented semigroup or monoid. +For computing finite index right congruences of a finitely presented semigroup +or monoid. -The algorithm implemented by this class is essentially the low index subgroup algorithm -for finitely presented groups described in Section 5.6 of :cite:`Sims1994aa`. -The low index subgroups algorithm was adapted for semigroups and monoids by -R. Cirpons, J. D. Mitchell, and M. Tsalakou; see :cite:`Anagnostopoulou-Merkouri2023aa`. +The algorithm implemented by this class is essentially the low index subgroup +algorithm for finitely presented groups described in Section 5.6 of +:cite:`Sims1994aa`. The low index subgroups algorithm was adapted for +semigroups and monoids by R. Cirpons, J. D. Mitchell, and M. Tsalakou; see +:cite:`Anagnostopoulou-Merkouri2023aa`. -The purpose of this class is to provide the functions :py:meth:`~Sims1.iterator`, -:py:meth:`~Sims1.for_each` and :py:meth:`~Sims1.find_if`, -which permit iterating through the one-sided congruences of a semigroup or monoid defined -by a presentation containing (a possibly empty) set of pairs and with at most a given -number of classes. An iterator returned by :py:meth:`~Sims1.iterator` yields :any:`WordGraph` -instances representing the action of the semigroup or monoid on the classes of a congruence. +The purpose of this class is to provide the functions +:py:meth:`~Sims1.iterator`, :py:meth:`~Sims1.for_each` and +:py:meth:`~Sims1.find_if`, which permit iterating through the one-sided +congruences of a semigroup or monoid defined by a presentation containing (a +possibly empty) set of pairs and with at most a given number of classes. An +iterator returned by :py:meth:`~Sims1.iterator` yields :any:`WordGraph` +instances representing the action of the semigroup or monoid on the classes of +a congruence. -.. seealso:: :any:`Sims2` for equivalent functionality for 2-sided congruences.)pbdoc"); +.. seealso:: :any:`Sims2` for equivalent functionality for 2-sided congruences. +)pbdoc"); s1.def("__repr__", [](Sims1 const& s1) { return to_human_readable_repr(s1); }); s1.def(py::init<>(), R"pbdoc( +:sig=(self: Sims1) -> None: +:only-document-once: Default constructor. )pbdoc"); s1.def(py::init const&>(), py::arg("p"), R"pbdoc( +:sig=(self: Sims1, p: Presentation) -> None: +:only-document-once: Construct from a presentation. -The rules of the presentation ``p`` are used at every node in the +The rules of the presentation *p* are used at every node in the depth first search conducted by an object of this type. :raises LibsemigroupsError: if :any:`to_presentation` throws -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. .. seealso:: :any:`presentation`, :py:meth:`~Sims1.init`)pbdoc"); s1.def(py::init const&>(), py::arg("p"), R"pbdoc( +:sig=(self: Sims1, p: Presentation) -> None: +:only-document-once: Construct from a presentation. -The rules of the presentation ``p`` are used at every node in the +The rules of the presentation *p* are used at every node in the depth first search conducted by an object of this type. :raises LibsemigroupsError: if :any:`to_presentation` throws -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. .. seealso:: :any:`presentation`, :py:meth:`~Sims1.init`)pbdoc"); s1.def(py::init(), py::arg("other"), R"pbdoc( +:sig=(self: Sims1, other: Sims1) -> None: +:only-document-once: Default copy constructor. )pbdoc"); s1.def( @@ -760,24 +889,21 @@ Default copy constructor. }, py::arg("p"), R"pbdoc( -Reinitialize an existing Sims1 object. +:sig=(self: Sims1, p: Presentation) -> Sims1: +:only-document-once: +Reinitialize an existing :any:`Sims1` object from a presentation. :param p: the presentation. :type p: Presentation -This function puts an object back into the same state as if it had been newly constructed from the presentation ``p``. - -:raises LibsemigroupsError: if ``to_presentation(p)`` throws - -:raises LibsemigroupsError: if ``p`` is not valid - -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. -.. seealso:: presentation(Presentation const&) +This function puts an object back into the same state as if it had been newly +constructed from the presentation *p*. +:raises LibsemigroupsError: if :any:`to_presentation(p)` throws -:returns: A reference to ``self``. +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. -:rtype: typename Word +:returns: A reference to *self*. )pbdoc"); s1.def( "init", @@ -786,46 +912,46 @@ This function puts an object back into the same state as if it had been newly co }, py::arg("p"), R"pbdoc( -Reinitialize an existing Sims1 object. +:sig=(self: Sims1, p: Presentation) -> Sims1: +:only-document-once: +Reinitialize an existing :any:`Sims1` object from a presentation. :param p: the presentation. :type p: Presentation -This function puts an object back into the same state as if it had been newly constructed from the presentation ``p``. -:raises LibsemigroupsError: if ``to_presentation(p)`` throws +This function puts an object back into the same state as if it had been newly +constructed from the presentation *p*. -:raises LibsemigroupsError: if ``p`` is not valid - -:raises LibsemigroupsError: if ``p`` has 0-generators and 0-relations. - -.. seealso:: presentation(Presentation const&) +:raises LibsemigroupsError: if :any:`to_presentation(p)` throws +:raises LibsemigroupsError: if *p* has 0-generators and 0-relations. -:returns: A reference to ``self``. - -:rtype: typename Word +:returns: A reference to *self*. )pbdoc"); s1.def("number_of_congruences", &Sims1::number_of_congruences, py::arg("n"), R"pbdoc( -Returns the number of one-sided congruences with up to a given number of classes. +Returns the number of one-sided congruences with up to a given number of +classes. :param n: the maximum number of congruence classes. :type n: int -This function is similar to ``std::distance(begin(n), end(n))`` and exists to: - -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::distance(begin(n), end(n))`` to be performed using :any:`number_of_threads` in parallel. +This function exists to: +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for the computation of the number of congruence to be performed using +:py:meth:`~Sims1.number_of_threads` in parallel. -:raises LibsemigroupsError: if ``n`` is ``0``. - -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +:raises LibsemigroupsError: if *n* is ``0``. +:raises LibsemigroupsError: if :py:meth:`~Sims1.presentation()` has +0-generators and 0-relations (i.e. it has not been initialised). -:returns: A value of type ``int``. +:returns: the number of one sided congruences with at most *n* congruence +classes. :rtype: int )pbdoc"); @@ -834,60 +960,63 @@ This function is similar to ``std::distance(begin(n), end(n))`` and exists to: py::arg("n"), py::arg("pred"), R"pbdoc( -Apply a unary predicate to every one-sided congruence with at most a given number of classes. +Apply a unary predicate to every one-sided congruence with at most a given +number of classes. :param n: the maximum number of congruence classes. :type n: int :param pred: the predicate applied to every congruence found. -:type pred: std::function -Apply the function ``pred`` to every one-sided congruence with at most ``n`` classesThis function is similar to ``std::for_each(begin(n), end(n), pred)`` and exists to: - -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::for_each(begin(n), end(n), pred)`` to be performed using :any:`number_of_threads` in parallel. - +:type pred: Callable[[WordGraph], None] +Apply the function *pred* to every one-sided congruence with at most *n* +classes. This function exists to: -:raises LibsemigroupsError: if ``n`` is ``0``. - -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). - -.. seealso:: :any:`cbegin` +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for a function to be applied to all found word graphs using +:py:meth:`~Sims1.number_of_threads` in parallel. +:raises LibsemigroupsError: if *n* is ``0``. -:returns: (None) +:raises LibsemigroupsError: if :py:meth:`~Sims1.presentation()` has +0-generators and 0-relations (i.e. it has not been initialised). -:rtype: None +.. seealso:: :py:meth:`~Sims1.iterator`, :py:meth:`~Sims1.find_if` )pbdoc"); s1.def("find_if", &Sims1::find_if, py::arg("n"), py::arg("pred"), R"pbdoc( -Apply a unary predicate to one-sided congruences with at most a given number of classes, until it returns true. +Apply a unary predicate to one-sided congruences with at most a given number of +classes, until it returns true. :param n: the maximum number of congruence classes. :type n: int :param pred: the predicate applied to every congruence found. -:type pred: std::function -Apply the function ``pred`` to every one-sided congruence with at most ``n`` classes, until it returns ``True``.This function is similar to ``std::find_if(begin(n), end(n), pred)`` and exists to: +:type pred: Callable[[WordGraph], bool] -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::find_if(begin(n), end(n), pred)`` to be performed using :any:`number_of_threads` in parallel. +This function applies the predicate *pred* to every congruence with at most *n* +classes, until a congruence satisfying the predicate is found. This function +exists to: +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for searching for a congruence satisfying certain conditions using +:py:meth:`~Sims1.number_of_threads` in parallel. +:raises LibsemigroupsError: if *n* is ``0``. -:raises LibsemigroupsError: if ``n`` is ``0``. +:raises LibsemigroupsError: if :py:meth:`~Sims1.presentation()` has +0-generators and 0-relations (i.e. it has not been initialised). -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +:returns: The first :any:`WordGraph` for which *pred* returns ``True``, or the +empty word graph if no such word graph exists. -.. seealso:: :any:`cbegin` +.. seealso:: :py:meth:`~Sims1.iterator`, :py:meth:`~Sims1.for_each` - -:returns: The first :any:`WordGraph` for which ``pred`` returns ``True``. - -:rtype: word_graph_type )pbdoc"); s1.def( "iterator", @@ -896,34 +1025,67 @@ Apply the function ``pred`` to every one-sided congruence with at most ``n`` cla }, py::arg("n"), R"pbdoc( -Returns a forward iterator pointing at the first congruence. +Returns an iterator yielding all congruences of index at most *n*. :param n: the maximum number of classes in a congruence. :type n: int -Returns a forward iterator pointing to the :any:`WordGraph` representing the first congruence described by an object of this type with at most ``n`` classes.If incremented, the iterator will point to the next such congruence. The order in which the congruences are returned is implementation specific. Iterators of the type returned by this function are equal whenever they point to equal objects. The iterator is exhausted if and only if it points to an :any:`WordGraph` with zero nodes.The meaning of the :any:`WordGraph` pointed at by the returned iterator depends on whether the input is a monoid presentation (i.e. :any:`Presentation::contains_empty_word()` returns ``True`` ) or a semigroup presentation. If the input is a monoid presentation for a monoid :math:`M` , then the :any:`WordGraph` pointed to by an iterator of this type has precisely ``n`` nodes, and the right action of :math:`M` on the nodes of the word graph is isomorphic to the action of :math:`M` on the classes of a right congruence.If the input is a semigroup presentation for a semigroup :math:`S` , then the :any:`WordGraph` has ``n`` + 1 nodes, and the right action of :math:`S` on the nodes :math:`\{1, \ldots, n\}` of the :any:`WordGraph` is isomorphic to the action of :math:`S` on the classes of a right congruence. It'd probably be better in this case if node :math:`0` was not included in the output :any:`WordGraph` , but it is required in the implementation of the low-index congruence algorithm, and to avoid unnecessary copies, we've left it in for the time being. -:raises LibsemigroupsError: if ``n`` is ``0``. +This function returns an iterator yielding instances of :any:`WordGraph` that +represent the congruences with at most *n* classes. The order in which the +congruences are yielded by the iterator is implementation specific. The meaning +of the :any:`WordGraph` objects yielded by the iterator depends on whether the +input is a monoid presentation (i.e. +:py:meth:`~Presentation::contains_empty_word()` returns ``True`` ) or a +semigroup presentation. -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +If the input is a monoid presentation for a monoid :math:`M` , then the +:any:`WordGraph` pointed to by an iterator of this type has at most *n* nodes, +and the right action of :math:`M` on the nodes of the word graph is isomorphic +to the action of :math:`M` on the classes of a right congruence. -.. seealso:: :any:`cend` +If the input is a semigroup presentation for a semigroup :math:`S`, then the +:any:`WordGraph` has at most *n* + 1 nodes, and the right action of :math:`S` +on the nodes :math:`\{1, \ldots, n\}` of the :any:`WordGraph` is isomorphic to +the action of :math:`S` on the classes of a right congruence. It'd probably be +better in this case if node :math:`0` was not included in the output +:any:`WordGraph`, but it is required in the implementation of the low-index +congruence algorithm, and to avoid unnecessary copies, we've left it in for the +time being. +:raises LibsemigroupsError: if *n* is ``0``. -:returns: An iterator ``it`` of type ``Iterator`` pointing to an :any:`WordGraph` with at most ``n`` nodes. +:raises LibsemigroupsError: if :py:meth:`~Sims1.presentation()` has +0-generators and 0-relations (i.e. it has not been initialised). -:rtype: Iterator +:returns: An iterator ``it`` pointing to :any:`WordGraph` objects with at most +*n* or *n*+1 nodes depending on the presentation, see above. + +:rtype: Iterator[WordGraph] )pbdoc"); py::class_> s2(m, "Sims2", R"pbdoc( -For computing finite index two-sided congruences of a finitely presented semigroup or monoid. - -Defined in ``sims.hpp``.On this page we describe the functionality relating to the small index congruence algorithm for 2-sided congruences. The algorithm implemented by this class is described in :any:`[1]`.The purpose of this class is to provide the functions :any:`cbegin` , :any:`cend` , :any:`for_each` , and :any:`find_if` which permit iterating through the two-sided congruences of a semigroup or monoid defined by a presentation containing, or not containing, (possibly empty) sets of pairs and with at most a given number of classes. An iterator returned by :any:`cbegin` points at an :any:`WordGraph` instance containing the action of the semigroup or monoid on the classes of a congruence. - -.. seealso:: :any:`Sims1` for equivalent functionality for 1-sided congruences. - -.. seealso:: :any:`SimsSettings` for the various things that can be set in a :any:`Sims2` object.)pbdoc"); +For computing finite index two-sided congruences of a finitely presented +semigroup or monoid. + +Defined in ``sims.hpp``.On this page we describe the functionality relating to +the small index congruence algorithm for 2-sided congruences. The algorithm +implemented by this class is described in :any:`[1]`.The purpose of this class +is to provide the functions :any:`cbegin` , :any:`cend` , :any:`for_each` , and +:any:`find_if` which permit iterating through the two-sided congruences of a +semigroup or monoid defined by a presentation containing, or not containing, +(possibly empty) sets of pairs and with at most a given number of classes. An +iterator returned by :any:`cbegin` points at an :any:`WordGraph` instance +containing the action of the semigroup or monoid on the classes of a +congruence. + +.. seealso:: :any:`Sims1` for equivalent functionality for 1-sided +congruences. + +.. seealso:: :any:`SimsSettings` for the various things that can be set in a +:any:`Sims2` object. +)pbdoc"); s2.def("__repr__", [](Sims2 const& s2) { return to_human_readable_repr(s2); }); s2.def(py::init<>(), R"pbdoc( @@ -937,7 +1099,12 @@ Construct from a presentation. :param p: the presentation :type p: Presentation -Constructs an instance from a presentation of any kind.The rules of the presentation ``p`` are used at every node in the depth first search conducted by an object of this type.If the template parameter ``Word`` is not :any:`word_type` , then the parameter ``p`` is first converted to a value of type ``Presentation`` and it is this converted value that is used. + +Constructs an instance from a presentation of any kind.The rules of the +presentation ``p`` are used at every node in the depth first search conducted +by an object of this type.If the template parameter ``Word`` is not +:any:`word_type` , then the parameter ``p`` is first converted to a value of +type ``Presentation`` and it is this converted value that is used. :raises LibsemigroupsError: if ``to_presentation(p)`` throws @@ -947,13 +1114,19 @@ Constructs an instance from a presentation of any kind.The rules of the presenta .. seealso:: presentation -.. seealso:: :any:`init`)pbdoc"); +.. seealso:: :any:`init` +)pbdoc"); s2.def(py::init const&>(), R"pbdoc( Construct from a presentation. :param p: the presentation :type p: Presentation -Constructs an instance from a presentation of any kind.The rules of the presentation ``p`` are used at every node in the depth first search conducted by an object of this type.If the template parameter ``Word`` is not :any:`word_type` , then the parameter ``p`` is first converted to a value of type ``Presentation`` and it is this converted value that is used. + +Constructs an instance from a presentation of any kind.The rules of the +presentation ``p`` are used at every node in the depth first search conducted +by an object of this type.If the template parameter ``Word`` is not +:any:`word_type` , then the parameter ``p`` is first converted to a value of +type ``Presentation`` and it is this converted value that is used. :raises LibsemigroupsError: if ``to_presentation(p)`` throws @@ -963,7 +1136,8 @@ Constructs an instance from a presentation of any kind.The rules of the presenta .. seealso:: presentation -.. seealso:: :any:`init`)pbdoc"); +.. seealso:: :any:`init` +)pbdoc"); // TODO: same as above // s2.def("init", // &Sims2::init, @@ -976,7 +1150,7 @@ Constructs an instance from a presentation of any kind.The rules of the presenta // // :raises This: function guarantees not to throw a ``LibsemigroupsError``. // - // :returns: A reference to ``self``. + // :returns: A reference to *self*. // // :rtype: Sims2 // )pbdoc"); @@ -990,15 +1164,15 @@ Returns the number of one-sided congruences with up to a given number of classes :type n: int This function is similar to ``std::distance(begin(n), end(n))`` and exists to: -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::distance(begin(n), end(n))`` to be performed using :any:`number_of_threads` in parallel. - - +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for the computation of ``std::distance(begin(n), end(n))`` to be +performed using :any:`number_of_threads` in parallel. :raises LibsemigroupsError: if ``n`` is ``0``. -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). - +:raises LibsemigroupsError: if ``presentation()`` has 0-generators and +0-relations (i.e. it has not been initialised). :returns: A value of type ``int``. @@ -1016,16 +1190,19 @@ Apply a unary predicate to every one-sided congruence with at most a given numbe :param pred: the predicate applied to every congruence found. :type pred: std::function -Apply the function ``pred`` to every one-sided congruence with at most ``n`` classesThis function is similar to ``std::for_each(begin(n), end(n), pred)`` and exists to: - -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::for_each(begin(n), end(n), pred)`` to be performed using :any:`number_of_threads` in parallel. - +Apply the function ``pred`` to every one-sided congruence with at most ``n`` +classesThis function is similar to ``std::for_each(begin(n), end(n), pred)`` +and exists to: +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for the computation of ``std::for_each(begin(n), end(n), pred)`` to be +performed using :any:`number_of_threads` in parallel. :raises LibsemigroupsError: if ``n`` is ``0``. -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +:raises LibsemigroupsError: if ``presentation()`` has 0-generators and +0-relations (i.e. it has not been initialised). .. seealso:: :any:`cbegin` @@ -1039,23 +1216,29 @@ Apply the function ``pred`` to every one-sided congruence with at most ``n`` cla py::arg("n"), py::arg("pred"), R"pbdoc( -Apply a unary predicate to one-sided congruences with at most a given number of classes, until it returns true. +Apply a unary predicate to one-sided congruences with at most a given number of +classes, until it returns true. :param n: the maximum number of congruence classes. :type n: int :param pred: the predicate applied to every congruence found. :type pred: std::function -Apply the function ``pred`` to every one-sided congruence with at most ``n`` classes, until it returns ``True``.This function is similar to ``std::find_if(begin(n), end(n), pred)`` and exists to: +Apply the function ``pred`` to every one-sided congruence with at most ``n`` +classes, until it returns ``True``.This function is similar to +``std::find_if(begin(n), end(n), pred)`` and exists to: -* provide some feedback on the progress of the computation if it runs for more than 1 second. -* allow for the computation of ``std::find_if(begin(n), end(n), pred)`` to be performed using :any:`number_of_threads` in parallel. +* provide some feedback on the progress of the computation if it runs for more +than 1 second. +* allow for the computation of ``std::find_if(begin(n), end(n), pred)`` to be +performed using :any:`number_of_threads` in parallel. :raises LibsemigroupsError: if ``n`` is ``0``. -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +:raises LibsemigroupsError: if ``presentation()`` has 0-generators and +0-relations (i.e. it has not been initialised). .. seealso:: :any:`cbegin` @@ -1075,16 +1258,38 @@ Returns a forward iterator pointing at the first congruence. :param n: the maximum number of classes in a congruence. :type n: int -Returns a forward iterator pointing to the :any:`WordGraph` representing the first congruence described by an object of this type with at most ``n`` classes.If incremented, the iterator will point to the next such congruence. The order in which the congruences are returned is implementation specific. Iterators of the type returned by this function are equal whenever they point to equal objects. The iterator is exhausted if and only if it points to an :any:`WordGraph` with zero nodes.The meaning of the :any:`WordGraph` pointed at by the returned iterator depends on whether the input is a monoid presentation (i.e. :any:`Presentation::contains_empty_word()` returns ``True`` ) or a semigroup presentation. If the input is a monoid presentation for a monoid :math:`M` , then the :any:`WordGraph` pointed to by an iterator of this type has precisely ``n`` nodes, and the right action of :math:`M` on the nodes of the word graph is isomorphic to the action of :math:`M` on the classes of a right congruence.If the input is a semigroup presentation for a semigroup :math:`S` , then the :any:`WordGraph` has ``n`` + 1 nodes, and the right action of :math:`S` on the nodes :math:`\{1, \ldots, n\}` of the :any:`WordGraph` is isomorphic to the action of :math:`S` on the classes of a right congruence. It'd probably be better in this case if node :math:`0` was not included in the output :any:`WordGraph` , but it is required in the implementation of the low-index congruence algorithm, and to avoid unnecessary copies, we've left it in for the time being. +Returns a forward iterator pointing to the :any:`WordGraph` representing the +first congruence described by an object of this type with at most ``n`` +classes.If incremented, the iterator will point to the next such congruence. +The order in which the congruences are returned is implementation specific. +Iterators of the type returned by this function are equal whenever they point +to equal objects. The iterator is exhausted if and only if it points to an +:any:`WordGraph` with zero nodes.The meaning of the :any:`WordGraph` pointed at +by the returned iterator depends on whether the input is a monoid presentation +(i.e. :any:`Presentation::contains_empty_word()` returns ``True`` ) or a +semigroup presentation. If the input is a monoid presentation for a monoid +:math:`M` , then the :any:`WordGraph` pointed to by an iterator of this type +has precisely ``n`` nodes, and the right action of :math:`M` on the nodes of +the word graph is isomorphic to the action of :math:`M` on the classes of a +right congruence.If the input is a semigroup presentation for a semigroup +:math:`S` , then the :any:`WordGraph` has ``n`` + 1 nodes, and the right action +of :math:`S` on the nodes :math:`\{1, \ldots, n\}` of the :any:`WordGraph` is +isomorphic to the action of :math:`S` on the classes of a right congruence. +It'd probably be better in this case if node :math:`0` was not included in the +output :any:`WordGraph` , but it is required in the implementation of the +low-index congruence algorithm, and to avoid unnecessary copies, we've left it +in for the time being. :raises LibsemigroupsError: if ``n`` is ``0``. -:raises LibsemigroupsError: if ``presentation()`` has 0-generators and 0-relations (i.e. it has not been initialised). +:raises LibsemigroupsError: if ``presentation()`` has 0-generators and +0-relations (i.e. it has not been initialised). .. seealso:: :any:`cend` -:returns: An iterator ``it`` of type ``Iterator`` pointing to an :any:`WordGraph` with at most ``n`` nodes. +:returns: An iterator ``it`` of type ``Iterator`` pointing to an +:any:`WordGraph` with at most ``n`` nodes. :rtype: Iterator )pbdoc"); @@ -1092,14 +1297,23 @@ Returns a forward iterator pointing to the :any:`WordGraph` representing the fir py::class_> ro(m, "RepOrc", R"pbdoc( -For computing small degree transformation representations of a finite semigroup or monoid. +For computing small degree transformation representations of a finite semigroup +or monoid. -Defined in ``sims.hpp``.This class is a helper for :any:`Sims1` calling the :any:`word_graph` member function attempts to find a right congruence, represented as an :any:`WordGraph` , of the semigroup or monoid defined by the presentation consisting of its :any:`presentation` and long_rules with the following properties: +Defined in ``sims.hpp``.This class is a helper for :any:`Sims1` calling the +:any:`word_graph` member function attempts to find a right congruence, +represented as an :any:`WordGraph` , of the semigroup or monoid defined by the +presentation consisting of its :any:`presentation` and long_rules with the +following properties: -* the transformation semigroup defined by the :any:`WordGraph` has size :any:`target_size` ; -* the number of nodes in the :any:`WordGraph` is at least :any:`min_nodes` and at most :any:`max_nodes`. +* the transformation semigroup defined by the :any:`WordGraph` has size +:any:`target_size` ; +* the number of nodes in the :any:`WordGraph` is at least :any:`min_nodes` and +at most :any:`max_nodes`. -If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with ``0`` nodes and ``0`` edges).)pbdoc"); +If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is +returned (with ``0`` nodes and ``0`` edges). +)pbdoc"); ro.def("__repr__", [](RepOrc const& ro) { return to_human_readable_repr(ro); }); ro.def(py::init<>(), R"pbdoc( @@ -1115,7 +1329,9 @@ Default constructor. [](RepOrc const& self) { return self.max_nodes(); }, R"pbdoc( Get the current maximum number of nodes. -This function returns the current value for the maximum number of nodes in the :any:`WordGraph` that we are seeking. + +This function returns the current value for the maximum number of nodes in the +:any:`WordGraph` that we are seeking. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1132,12 +1348,14 @@ Set the maximum number of nodes. :param val: the maximum number of nodes :type val: int -This function sets the maximum number of nodes in the :any:`WordGraph` that we are seeking. + +This function sets the maximum number of nodes in the :any:`WordGraph` that we +are seeking. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: RepOrc )pbdoc"); @@ -1146,7 +1364,9 @@ This function sets the maximum number of nodes in the :any:`WordGraph` that we a [](RepOrc const& self) { return self.min_nodes(); }, R"pbdoc( Get the current minimum number of nodes. -This function returns the current value for the minimum number of nodes in the :any:`WordGraph` that we are seeking. + +This function returns the current value for the minimum number of nodes in the +:any:`WordGraph` that we are seeking. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1163,12 +1383,14 @@ Set the minimum number of nodes. :param val: the minimum number of nodes :type val: int -This function sets the minimal number of nodes in the :any:`WordGraph` that we are seeking. + +This function sets the minimal number of nodes in the :any:`WordGraph` that we +are seeking. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: RepOrc )pbdoc"); @@ -1177,7 +1399,10 @@ This function sets the minimal number of nodes in the :any:`WordGraph` that we a [](RepOrc const& self) { return self.target_size(); }, R"pbdoc( Get the current target size. -This function returns the current value for the target size, i.e. the desired size of the transformation semigroup corresponding to the :any:`WordGraph` returned by the function :any:`word_graph`. + +This function returns the current value for the target size, i.e. the desired +size of the transformation semigroup corresponding to the :any:`WordGraph` +returned by the function :any:`word_graph`. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1196,12 +1421,15 @@ Set the target size. :param val: the target size. :type val: int -This function sets the target size, i.e. the desired size of the transformation semigroup corresponding to the :any:`WordGraph` returned by the function :any:`word_graph`. + +This function sets the target size, i.e. the desired size of the transformation +semigroup corresponding to the :any:`WordGraph` returned by the function +:any:`word_graph`. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: RepOrc )pbdoc"); @@ -1210,12 +1438,20 @@ This function sets the target size, i.e. the desired size of the transformation R"pbdoc( Get the word_graph. -:param (None): this function has no parameters.This function attempts to find a right congruence, represented as an :any:`WordGraph` , of the semigroup or monoid defined by the presentation consisting of its :any:`presentation` and long_rules with the following properties: +:param (None): this function has no parameters. + +This function attempts to find a +right congruence, represented as an :any:`WordGraph` , of the semigroup or +monoid defined by the presentation consisting of its :any:`presentation` and +long_rules with the following properties: -* the transformation semigroup defined by the :any:`WordGraph` has size :any:`target_size` ; -* the number of nodes in the :any:`WordGraph` is at least :any:`min_nodes` and at most :any:`max_nodes`. +* the transformation semigroup defined by the :any:`WordGraph` has size +:any:`target_size` ; +* the number of nodes in the :any:`WordGraph` is at least :any:`min_nodes` and +at most :any:`max_nodes`. -If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with ``0`` nodes and ``0`` edges). +If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is +returned (with ``0`` nodes and ``0`` edges). :exceptions this function guarantees not to throw a libsemigroupsexception. : @@ -1228,9 +1464,18 @@ If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is retu py::class_> mro(m, "MinimalRepOrc", R"pbdoc( -For computing the minimal degree of a transformation representation arising from a right congruences of a finite semigroup or monoid. - -Defined in ``sims.hpp``.This class is a helper for :any:`Sims1` , calling the :any:`word_graph` member function attempts to find a right congruence, represented as an :any:`WordGraph` , with the minimum possible number of nodes such that the action of the semigroup or monoid defined by the presentation consisting of its :any:`presentation` on the nodes of the :any:`WordGraph` corresponds to a semigroup of size :any:`target_size`.If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with ``0`` nodes and ``0`` edges).)pbdoc"); +For computing the minimal degree of a transformation representation arising +from a right congruences of a finite semigroup or monoid. + +Defined in ``sims.hpp``.This class is a helper for :any:`Sims1` , calling the +:any:`word_graph` member function attempts to find a right congruence, +represented as an :any:`WordGraph` , with the minimum possible number of nodes +such that the action of the semigroup or monoid defined by the presentation +consisting of its :any:`presentation` on the nodes of the :any:`WordGraph` +corresponds to a semigroup of size :any:`target_size`.If no such +:any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with +``0`` nodes and ``0`` edges). +)pbdoc"); mro.def("__repr__", [](MinimalRepOrc const& mro) { return to_human_readable_repr(mro); }); @@ -1247,7 +1492,10 @@ Default constructor. [](MinimalRepOrc const& self) { return self.target_size(); }, R"pbdoc( Get the current target size. -This function returns the current value for the target size, i.e. the desired size of the transformation semigroup corresponding to the :any:`WordGraph` returned by the function :any:`word_graph`. + +This function returns the current value for the target size, i.e. the desired +size of the transformation semigroup corresponding to the :any:`WordGraph` +returned by the function :any:`word_graph`. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1266,12 +1514,14 @@ Set the target size. :param val: the target size. :type val: int -This function sets the target size, i.e. the desired size of the transformation semigroup corresponding to the :any:`WordGraph` returned by the function :any:`word_graph`. -:exceptions: This function is ``noexcept`` and is guaranteed never to throw. +This function sets the target size, i.e. the desired size of the transformation +semigroup corresponding to the :any:`WordGraph` returned by the function +:any:`word_graph`. +:exceptions: This function is ``noexcept`` and is guaranteed never to throw. -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: MinimalRepOrc )pbdoc"); @@ -1280,7 +1530,16 @@ This function sets the target size, i.e. the desired size of the transformation R"pbdoc( Get the word graph. -:param (None): this function has no parameters.This function attempts to find a right congruence, represented as an :any:`WordGraph` , with the minimum possible number of nodes such that the action of the semigroup or monoid defined by the presentation consisting of its :any:`presentation` and long_rules on the nodes of the :any:`WordGraph` corresponds to a semigroup of size :any:`target_size`.If no such :any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with ``0`` nodes and ``0`` edges).The algorithm implemented by this function repeatedly runs: +:param (None): this function has no parameters. + +This function attempts to find a right congruence, represented as an +:any:`WordGraph` , with the minimum possible number of nodes such that the +action of the semigroup or monoid defined by the presentation consisting of its +:any:`presentation` and long_rules on the nodes of the :any:`WordGraph` +corresponds to a semigroup of size :any:`target_size`.If no such +:any:`WordGraph` can be found, then an empty :any:`WordGraph` is returned (with +``0`` nodes and ``0`` edges).The algorithm implemented by this function +repeatedly runs: .. code-block:: @@ -1288,7 +1547,11 @@ RepOrc(* this ) .min_nodes(1) .max_nodes(best) .target_size( :any:`target_size` ()) - .word_graph(); where ``best`` is initially :any:`target_size` , until the returned :any:`WordGraph` is empty, and then the penultimate :any:`WordGraph` is returned (if any). + .word_graph(); + +where ``best`` is initially :any:`target_size` , until the returned +:any:`WordGraph` is empty, and then the penultimate :any:`WordGraph` is +returned (if any). :exceptions this function guarantees not to throw a libsemigroupsexception. : @@ -1301,9 +1564,16 @@ RepOrc(* this ) py::class_ srf(m, "SimsRefinerFaithful", R"pbdoc( -For pruning the search tree when looking for congruences arising from right or two-sided congruences representing faithful actions. +For pruning the search tree when looking for congruences arising from right or +two-sided congruences representing faithful actions. -Defined in ``sims.hpp``.This class provides a pruner for pruning the search tree when looking for right congruences representing faithful actions. A right congruence represents a faithful action if and only if it does not contain any non-trivial two-sided congruence. Equivalently, a word graph of a right congruence represents a faithful action if and only if there is no nontrivial pair of words :math:`(u, v)` such that every vertex of the word graph is compatible with :math:`(u, v)`. +Defined in ``sims.hpp``.This class provides a pruner for pruning the search +tree when looking for right congruences representing faithful actions. A right +congruence represents a faithful action if and only if it does not contain any +non-trivial two-sided congruence. Equivalently, a word graph of a right +congruence represents a faithful action if and only if there is no nontrivial +pair of words :math:`(u, v)` such that every vertex of the word graph is +compatible with :math:`(u, v)`. .. seealso:: :any:`SimsSettings::pruners` @@ -1316,12 +1586,25 @@ Default constructor. )pbdoc"); srf.def(py::init const&>(), R"pbdoc( Construct from set of forbidden pairs. -Constructs a :any:`SimsRefinerFaithful` pruner with respect to the set of forbidden relations in ``forbid``.If ``forbid`` contains no trivial pairs (i.e. pairs of words that are equal in the underlying semigroup or monoid), then all word graphs rejected by :any:`SimsRefinerFaithful` are guaranteed to not be extendable to a word graph representing a faithful congruence. Otherwise, the pruner will incorrectly reject all word graphs.If in addition ``forbid`` is a set of relations containing all minimal congruence generating pairs of a given semigroup or monoid, then :any:`SimsRefinerFaithful` will also correctly determine if a complete word graph represents a faithful congruence. Otherwise, the complete word graphs accepted by :any:`SimsRefinerFaithful` are not guaranteed to be faithful and must be checked by some other means.)pbdoc"); + +Constructs a :any:`SimsRefinerFaithful` pruner with respect to the set of +forbidden relations in ``forbid``.If ``forbid`` contains no trivial pairs (i.e. +pairs of words that are equal in the underlying semigroup or monoid), then all +word graphs rejected by :any:`SimsRefinerFaithful` are guaranteed to not be +extendable to a word graph representing a faithful congruence. Otherwise, the +pruner will incorrectly reject all word graphs.If in addition ``forbid`` is a +set of relations containing all minimal congruence generating pairs of a given +semigroup or monoid, then :any:`SimsRefinerFaithful` will also correctly +determine if a complete word graph represents a faithful congruence. Otherwise, +the complete word graphs accepted by :any:`SimsRefinerFaithful` are not +guaranteed to be faithful and must be checked by some other means.)pbdoc"); srf.def("forbid", &SimsRefinerFaithful::forbid, R"pbdoc( Get the forbidden pairs defining the refiner. -Returns a const reference to the current forbidden pairs.This function returns the defining forbidden pairs of a :any:`SimsRefinerFaithful` instance. + +Returns a const reference to the current forbidden pairs.This function returns +the defining forbidden pairs of a :any:`SimsRefinerFaithful` instance. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1336,9 +1619,11 @@ Returns a const reference to the current forbidden pairs.This function returns t }, R"pbdoc( Reinitialize an existing SimsRefinerFaithful object. -This function puts an object back into the same state as if it had been newly default constructed. -:returns: A reference to ``self``. +This function puts an object back into the same state as if it had been newly +default constructed. + +:returns: A reference to *self*. :rtype: SimsRefinerFaithful )pbdoc"); @@ -1349,9 +1634,11 @@ This function puts an object back into the same state as if it had been newly de py::arg("forbid"), R"pbdoc( Reinitialize an existing SimsRefinerFaithful object from a set of forbidden pairs. -This function puts an object back into the same state as if it had been newly constructed from set of forbidden pairs ``forbid``. -:returns: A reference to ``self``. +This function puts an object back into the same state as if it had been newly +constructed from set of forbidden pairs ``forbid``. + +:returns: A reference to *self*. :rtype: SimsRefinerFaithful )pbdoc"); @@ -1363,14 +1650,19 @@ This function puts an object back into the same state as if it had been newly co Check if a word graph can be extended to one defining a faithful congruence. Returns ``False`` if there is no way of adding edges and nodes to -:wg: which will result in a word graph defining a faithful congruence. Otherwise returns ``True``.)pbdoc"); +:wg: which will result in a word graph defining a faithful congruence. +Otherwise returns ``True``. +)pbdoc"); py::class_ sri(m, "SimsRefinerIdeals", R"pbdoc( -For pruning the search tree when looking for congruences arising from right or two-sided ideals. +For pruning the search tree when looking for congruences arising from right or +two-sided ideals. -Defined in ``sims.hpp``.This class provides a pruner for pruning the search tree when looking for right or two-sided congruences arising from ideals (Rees congruences). +Defined in ``sims.hpp``.This class provides a pruner for pruning the search +tree when looking for right or two-sided congruences arising from ideals (Rees +congruences). .. seealso:: :any:`SimsSettings::pruners` @@ -1383,10 +1675,16 @@ Default constructor. )pbdoc"); sri.def(py::init const&>(), R"pbdoc( Construct from presentation. -Constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid defined by ``p``.)pbdoc"); + +Constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid +defined by ``p``. +)pbdoc"); sri.def(py::init const&>(), R"pbdoc( Construct from presentation. -Constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid defined by ``p``.)pbdoc"); + +Constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid +defined by ``p``. +)pbdoc"); sri.def( "init", [](SimsRefinerIdeals& self) -> SimsRefinerIdeals { @@ -1394,9 +1692,11 @@ Constructs a :any:`SimsRefinerIdeals` pruner for the semigroup or monoid defined }, R"pbdoc( Reinitialize an existing SimsRefinerIdeals object. -This function puts an object back into the same state as if it had been newly default constructed. -:returns: A reference to ``self``. +This function puts an object back into the same state as if it had been newly +default constructed. + +:returns: A reference to *self*. :rtype: typename Word )pbdoc"); @@ -1407,7 +1707,9 @@ This function puts an object back into the same state as if it had been newly de py::arg("p"), R"pbdoc( Reinitialize an existing 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``. + +This function puts an object back into the same state as if it had been newly +constructed from the presentation ``p``. :raises LibsemigroupsError: if ``p`` is not valid @@ -1415,7 +1717,7 @@ This function puts an object back into the same state as if it had been newly co .. seealso:: presentation(Presentation const&) -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: typename Word )pbdoc"); @@ -1426,7 +1728,9 @@ This function puts an object back into the same state as if it had been newly co py::arg("p"), R"pbdoc( Reinitialize an existing 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``. + +This function puts an object back into the same state as if it had been newly +constructed from the presentation ``p``. :raises LibsemigroupsError: if ``p`` is not valid @@ -1434,7 +1738,7 @@ This function puts an object back into the same state as if it had been newly co .. seealso:: presentation(Presentation const&) -:returns: A reference to ``self``. +:returns: A reference to *self*. :rtype: typename Word )pbdoc"); @@ -1442,7 +1746,10 @@ This function puts an object back into the same state as if it had been newly co &SimsRefinerIdeals::presentation, R"pbdoc( Get the presentation over which the refiner is defined. -Returns a const reference to the current relations of the underlying presentation.This function returns the defining presentation of a :any:`SimsRefinerIdeals` instance. + +Returns a const reference to the current relations of the underlying +presentation.This function returns the defining presentation of a +:any:`SimsRefinerIdeals` instance. :exceptions: This function is ``noexcept`` and is guaranteed never to throw. @@ -1456,9 +1763,12 @@ Returns a const reference to the current relations of the underlying presentatio py::arg("wg"), R"pbdoc( Check if a word graph can be extended to one defining a Rees congruence. -Returns ``False`` if there is no way of adding edges and nodes to -:wg: which will result in a word graph defining a Rees congruence. Otherwise returns ``True``.)pbdoc"); +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``. + +)pbdoc"); m.def( "right_generating_pairs",