Add support for Konieczny

Author: james-d-mitchell

docs/source/conf.py

@@ -38,6 +38,11 @@
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 htmlhelp_basename = "libsemigroups_pybind11"
 
+# The option in the next line stops the page sections and toc (which have the
+# same names) from being duplicated in the sidebar on the Konieczny and
+# FroidurePin pages
+html_theme_options = {"titles_only": True}
+
 man_pages = [
     (
         master_doc,

docs/source/konieczny.rst

@@ -0,0 +1,28 @@
+.. Copyright (c) 2022, J. D. Mitchell
+
+   Distributed under the terms of the GPL license version 3.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+Konieczny
+=========
+
+``libsemigroups_pybind11`` contains a preliminary implementation of Konieczny's
+generalisation of the Lallement-McFadden algorithm for computing the structure
+of finite semigroups that act on sets; see the documentation below for further
+details. It is preliminary in the sense that the interface exposed by the
+relevant classes is minimal, and that certain optimisations remain to be
+performed.
+
+The implementation of the Konieczny and Lallement-McFadden algorithm can be
+used "interactively", in the sense that they can be run for a particular amount
+of time, or until some condition is met; for further details see, for example,
+:py:meth:`Konieczny.run_for` and :py:meth:`Konieczny.run_until`.
+
+The classes implementing the Konieczny and Lallement-McFadden algorithm are:
+
+.. toctree::
+   :maxdepth: 1
+  
+   konieczny/index.rst
+   konieczny/dclass/index.rst

docs/source/konieczny/attributes.rst

@@ -0,0 +1,39 @@
+.. Copyright (c) 2022, J. D. Mitchell
+
+   Distributed under the terms of the GPL license version 3.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+Attributes
+==========
+
+This page contains information about attributes of the :py:class:`Konieczny`
+class.
+
+.. py:method:: Konieczny.degree(self: Konieczny) -> int
+
+   Returns the degree of any and all elements.
+
+   :Parameters: None
+   :Returns: An ``int``.
+
+.. py:method:: Konieczny.size(self: Konieczny) -> int
+
+   Returns the size.
+
+   :note:
+     This function triggers a full enumeration of the frames of every
+     :math:`\mathscr{D}`-class.
+
+   :Parameters: None
+   :Returns: An ``int``.
+
+.. py:method:: Konieczny.current_size(self: Konieczny) -> int
+
+   Returns the current size.
+
+   :note:
+     This function triggers no enumeration.
+
+   :Parameters: None
+   :return: An ``int``.

docs/source/konieczny/dclass/index.rst

@@ -0,0 +1,56 @@
+.. Copyright (c) 2022, J. D. Mitchell
+
+   Distributed under the terms of the GPL license version 3.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+
+Konieczny.DClass
+=================
+
+.. py:class:: Konieczny.DClass
+
+
+   The nested abstract class :py:obj:`Konieczny.DClass` represents a
+   :math:`\mathscr{D}`-class of a finite semigroup via a frame as computed in
+   Konieczny’s algorithm. See :py:obj:`Konieczny` for more details.
+
+   :py:obj:`Konieczny.DClass` instances cannot be directly constructed; instead
+   you should obtain a :math:`\mathscr{D}`-class by calling
+   :py:meth:`Konieczny.D_class_of_element`.
+
+.. toctree::
+   :hidden:
+
+   methods.rst
+
+Methods
+-------
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 0
+
+   * - :py:meth:`Konieczny.DClass.contains`
+     - Test membership of an element.
+
+   * - :py:meth:`Konieczny.DClass.is_regular_D_class`
+     - Test regularity of a :math:`\mathscr{D}`-class.
+
+   * - :py:meth:`Konieczny.DClass.number_of_L_classes`
+     - Returns the number of :math:`\mathscr{L}`-classes.
+
+   * - :py:meth:`Konieczny.DClass.number_of_R_classes`
+     - Returns the number of :math:`\mathscr{R}`-classes.
+
+   * - :py:meth:`Konieczny.DClass.number_of_idempotents`
+     - Returns the number of idempotents.
+
+   * - :py:meth:`Konieczny.DClass.rep`
+     - Returns a representative of the :math:`\mathscr{D}`-class.
+
+   * - :py:meth:`Konieczny.DClass.size`
+     - Returns the size of a :math:`\mathscr{D}`-class.
+
+   * - :py:meth:`Konieczny.DClass.size_H_class`
+     - Returns the size of the :math:`\mathscr{H}`-classes.

docs/source/konieczny/dclass/methods.rst

@@ -0,0 +1,72 @@
+.. Copyright (c) 2022, J. D. Mitchell
+
+   Distributed under the terms of the GPL license version 3.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+Methods
+=======
+
+This page contains information about the methods of the
+:py:class:`Konieczny.DClass` class.
+
+.. py:method:: Konieczny.DClass.contains(self: Konieczny.DClass, x: Element) -> bool
+
+   Test membership of an element in a :math:`\mathscr{D}`-class.
+
+   :param x: a possible element.
+   :type x: Element
+
+   :return: A ``bool``.
+
+.. py:method:: Konieczny.DClass.is_regular_D_class(self: Konieczny.DClass) -> bool
+
+   Test regularity of a :math:`\mathscr{D}`-class.
+
+   :Parameters: None
+
+   :return: A ``bool``.
+
+.. py:method:: Konieczny.DClass.number_of_R_classes(self: Konieczny.DClass) -> int
+
+   Returns the number of :math:`\mathscr{R}`-classes.
+
+   :Parameters: None
+
+   :return: An integer.
+
+.. py:method:: Konieczny.DClass.number_of_L_classes(self: Konieczny.DClass) -> int
+
+   Returns the number of :math:`\mathscr{L}`-classes.
+
+   :Parameters: None
+
+   :return: An integer.
+
+.. py:method:: Konieczny.DClass.number_of_idempotents(self: Konieczny.DClass) -> int
+
+   Returns the number of idempotents.
+
+   :Parameters: None
+   :return: An ``int``.
+
+.. py:method:: Konieczny.DClass.rep(self: Konieczny.DClass) -> Element
+
+   Returns a representative of the :math:`\mathscr{D}`-class.
+
+   :Parameters: None
+   :return: An ``Element``.
+
+.. py:method:: Konieczny.DClass.size(self: Konieczny.DClass) -> int
+
+   Returns the size of a :math:`\mathscr{D}`-class.
+
+   :Parameters: None
+   :Returns: An ``int``.
+
+.. py:method:: Konieczny.DClass.size_H_class(self: Konieczny.DClass) -> int
+
+   Returns the size of the :math:`\mathscr{H}`-classes.
+
+   :Parameters: None
+   :Returns: An ``int``.

docs/source/konieczny/generators.rst

@@ -0,0 +1,47 @@
+.. Copyright (c) 2021, J. D. Mitchell
+
+   Distributed under the terms of the GPL license version 3.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+Generators
+----------
+
+This page contains information about the methods of the :py:class:`Konieczny`
+class that relate to generators.
+
+.. py:method:: Konieczny.add_generator(self: Konieczny, x: Element) -> None
+
+   Add a copy of an element to the generators.
+
+   :param x: the generator to add.
+   :type x: Element
+
+   :return: None
+
+.. py:method:: Konieczny.number_of_generators(self: Konieczny) -> int
+
+   Returns the number of generators.
+
+   :Parameters: None
+   :return: An ``int``.
+
+.. py:method:: Konieczny.generator(self: Konieczny, i: int) -> Element
+
+   Returns the generator with specified index.
+
+   :param i: the index of a generator.
+   :type i: int
+
+   :return: An element.
+
+.. py:method:: Konieczny.generators(self: Konieczny) -> Iterator
+
+   Returns an iterator pointing to the first generator.
+
+   This  function does not trigger any enumeration; the iterator returned may
+   be invalidated by any call to a method of the :py:obj:`Konieczny`
+   class.
+
+   :Parameters: None
+   :return: An iterator.