diff --git a/docs/source/links.rst b/docs/source/_static/links.rst similarity index 100% rename from docs/source/links.rst rename to docs/source/_static/links.rst diff --git a/docs/source/authors.rst b/docs/source/authors.rst index 8df156253..3112338d5 100644 --- a/docs/source/authors.rst +++ b/docs/source/authors.rst @@ -10,6 +10,7 @@ Authors ======= +- `Reinis Cirpons`_ (rc234@st-andrews.ac.uk)_ - `Joseph Edwards`_ (jde1@st-andrews.ac.uk) - `James Mitchell`_ (jdm3@st-andrews.ac.uk) - `Maria Tsalakou`_ (mt200@st-andrews.ac.uk) @@ -21,6 +22,8 @@ Authors .. _maria tsalakou: https://mariatsalakou.github.io/ +.. _reinis cirpons: https://reinisc.id.lv + Contributors ------------ diff --git a/docs/source/changelog.rst b/docs/source/changelog-v0.rst similarity index 99% rename from docs/source/changelog.rst rename to docs/source/changelog-v0.rst index 0dd5349b5..dcc3a75f3 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog-v0.rst @@ -5,8 +5,8 @@ The full license is in the file LICENSE, distributed with this software. -Changelog -========= +Changelog - version 0 +===================== v0.10.1 (released 29/03/2023) ----------------------------- diff --git a/docs/source/changelog-v1.rst b/docs/source/changelog-v1.rst new file mode 100644 index 000000000..bb5ff00ff --- /dev/null +++ b/docs/source/changelog-v1.rst @@ -0,0 +1,14 @@ +.. + Copyright (c) 2025, 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. + +Changelog - version 1 +===================== + +v1.0.0 (released ??/??/202?) +----------------------------- + +TODO diff --git a/docs/source/conf.py b/docs/source/conf.py index 6ca16dc8d..f929db90f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,7 +27,7 @@ rst_epilog = "" # Read link all targets from file -with open("links.rst", encoding="utf-8") as f: +with open("_static/links.rst", encoding="utf-8") as f: rst_epilog += f.read() autosummary_generate = True @@ -46,7 +46,9 @@ # Use the version number of the installed project version = release = importlib.metadata.version(project) language = "python" -exclude_patterns = ["_build", "_old", "links.rst"] +exclude_patterns = ["_build", "_old", "_static"] +# Don't copy the prompt characters +copybutton_exclude = ".linenos, .gp" pygments_style = "sphinx" highlight_language = "python" todo_include_todos = False diff --git a/docs/source/data-structures/misc/index.rst b/docs/source/data-structures/misc/index.rst deleted file mode 100644 index a16a830f0..000000000 --- a/docs/source/data-structures/misc/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. - Copyright (c) 2021-2024 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. - -Miscellaneous -============= - -In this section we describe some miscellaneous functionality in -``libsemigroups_pybind11``. - -.. toctree:: - :maxdepth: 1 - - obvinf - libsemigroups-error - -.. - ukkonen/index diff --git a/docs/source/data-structures/misc/libsemigroups-error.rst b/docs/source/data-structures/misc/libsemigroups-error.rst deleted file mode 100644 index 0dd2d4db2..000000000 --- a/docs/source/data-structures/misc/libsemigroups-error.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. - Copyright (c) 2024 Joseph Edwards - - Distributed under the terms of the GPL license version 3. - - The full license is in the file LICENSE, distributed with this software. - -.. currentmodule:: libsemigroups_pybind11 - -Exceptions -========== - -This page describes the custom error type used in ``libsemigroups_pybind11``, -namely :any:`LibsemigroupsError`, and related functions. Other built-in -exceptions, such as :any:`ValueError` and :any:`TypeError`, may also be raised -in this project. See the -`Python documentation `_ -for further details. - -Full API --------- - -.. autoexception:: LibsemigroupsError - :show-inheritance: - - This is the main type of exception raised by the custom data-structures and - algorithms of ``libsemigroups_pybind11``. It is raised when the underlying - C++ code from libsemigroups_ raises a ``LibsemigroupsException``. - - .. doctest:: python - - >>> from libsemigroups_pybind11 import FroidurePin, Perm - >>> gens = [Perm([3, 0, 1, 2]), Perm([1, 2, 0, 3]), Perm([2, 1, 0, 3])] - >>> S = FroidurePin(gens) - >>> S - - - >>> S.generator(3) # Bad: there are only three generators - Traceback (most recent call last): - ... - LibsemigroupsError: generator index out of bounds, expected value in [0, 3), got 3 - - .. note:: - - If you believe your code is incorrectly throwing a - :any:`LibsemigroupsError`, or isn't throwing a :any:`LibsemigroupsError` - but you think it should, please let us known by opening an issue on the - `issue tracker`_. - -.. autofunction:: error_message_with_prefix - diff --git a/docs/source/data-structures/presentations/index.rst b/docs/source/data-structures/presentations/index.rst index 8e830b59b..34117135c 100644 --- a/docs/source/data-structures/presentations/index.rst +++ b/docs/source/data-structures/presentations/index.rst @@ -15,7 +15,8 @@ the finite presentations on which these algorithms can be run is described below. In ``libsemigroups_pybind11``, a presentation is modelled as a collection of -*rules*, each of which is a pair of *words*. Each word is made up of *letters*. +*rules*, each of which is a pair of *words* (although these rules are stored as +a non-nested list with the left- and right-hand sides in the even and odd indexed positions respectively). Each word is made up of *letters*. Presently, for any given presentation, all letters must either be of the type :any:`str` or :any:`int`. In a presentation where letters are of the type :any:`str`, words have the type :any:`str`. In a presentation where letters are @@ -28,12 +29,6 @@ In what follows, we will use the pseudo-types ``Letter`` and ``Word`` instead of ``str | int`` and ``str | list[int]`` to further indicate that two types of letters and words cannot be interchanged once a presentation is constructed. -All of the classes for finitely presented semigroups and monoids in -``libsemigroups_pybind11`` 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, :any:`Runner.run_for` and -:any:`Runner.run_until`. - The classes and modules in ``libsemigroups_pybind11`` for finitely presented semigroups and monoids are: @@ -47,3 +42,4 @@ semigroups and monoids are: examples to-present to-inverse-present + obvinf diff --git a/docs/source/data-structures/misc/obvinf.rst b/docs/source/data-structures/presentations/obvinf.rst similarity index 100% rename from docs/source/data-structures/misc/obvinf.rst rename to docs/source/data-structures/presentations/obvinf.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 7d64f4492..41aad30f5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,13 +5,12 @@ .. title:: libsemigroups_pybind11 -Python bindings for the C++ library libsemigroups -------------------------------------------------- +| -What is ``libsemigroups``? +What is libsemigroups_? ~~~~~~~~~~~~~~~~~~~~~~~~~~ -``libsemigroups`` is a C++14 library containing implementations of several +libsemigroups_ is a C++14 library containing implementations of several algorithms for computing finite and finitely presented semigroups. Namely: - the `Froidure-Pin algorithm`_ for computing finite semigroups @@ -22,7 +21,7 @@ algorithms for computing finite and finitely presented semigroups. Namely: algorithm for computing finite semigroups which act on sets. ``libsemigroups_pybind11`` is a python package exposing much (but not all) of -the functionality of ``libsemigroups``. +the functionality of libsemigroups_. The development version of ``libsemigroups_pybind11`` is available on github_, and some related projects are here_. @@ -46,85 +45,23 @@ and some related projects are here_. How to use it ~~~~~~~~~~~~~ -See the installation instructions: - - * :doc:`install` - * :doc:`changelog` - -The structure of the module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Python module ``libsemigroups_pybind11`` was designed to mirror the C++ -library ``libsemigroups`` as closely as possible, whilst navigating the -fundamental difference between Python and C++. This is done with the help of the -tool `pybind11 `_. - -For various implementational reasons (mostly related to Python's lack of an -analogue for C++'s templating system), the Python code exposed by ``pybind11`` -is less streamlined and concise than the C++ library. To try and address this, -the authors of ``libsemigroups_pybind11`` have further wrapped the Python code -produced by ``pybind11`` to make the Python and C++ user experience as similar -as possible. - -The Python bindings of the ``libsemigroups`` code produced by ``pybind11`` -reside in an intermediate module called ``_libsemigroups_pybind11`` (note the -leading underscore), and the public-facing nicely wrapped code resides in this -module — ``libsemigroups_pybind11``. - -Should this impact the way you, the user, use ``libsemigroups_pybind11``? For -the most part, no. It should be possible to use ``libsemigroups_pybind11`` in -the ways documented on this site without the knowledge that -``_libsemigroups_pybind11`` even exists. The notable exceptions to this relate -to type names and error messages. A lot of the code in -``libsemigroups_pybind11`` has been imported from ``_libsemigroups_pybind11``, -and this is visible in qualified type names. For example: - -.. doctest:: python - - >>> from libsemigroups_pybind11 import WordGraph - >>> WordGraph - - -Additionally, some functions or classes in the ``_libsemigroups_pybind11`` -module have additional prefixes and suffixes relative to their -``libsemigroups_pybind11`` counterpart. These usually relate to the module that -the function or class is contained within or a type the function or class is -defined upon. These may appear in error messages. For example: - -.. doctest:: python - - >>> from libsemigroups_pybind11 import aho_corasick, AhoCorasick - >>> ac = AhoCorasick() - >>> aho_corasick.add_word(ac, False) - Traceback (most recent call last): - ... - TypeError: aho_corasick_add_word(): incompatible function arguments. The following argument types are supported: - 1. (ac: _libsemigroups_pybind11.AhoCorasick, w: list[int]) -> int - 2. (ac: _libsemigroups_pybind11.AhoCorasick, w: str) -> int - - Invoked with: , False - -The :doc:`authors ` of ``libsemigroups_pybind11`` have gone to a lot of -effort to try and make error messages clear, specific and intelligible; however, -if there you encounter any errors with unclear messages, please raise this on -the `issue tracker`_. - -Further Info ------------- - -For additional information about ``libsemigroups_pybind11``, see the following: - - * :doc:`authors` - * :doc:`biblio` +See the installation instructions :doc:`install`. + +If you encounter any issues with the package or have any suggestions, then +please let us know on the `issue tracker`_. + .. toctree:: :caption: Package Info :maxdepth: 1 :hidden: - install - changelog authors biblio + changelog-v1 + changelog-v0 + libsemigroups-error + install .. toctree:: :caption: Data Structures @@ -134,12 +71,11 @@ For additional information about ``libsemigroups_pybind11``, see the following: data-structures/constants/index data-structures/elements/index data-structures/enums/index - data-structures/misc/index data-structures/order/index data-structures/presentations/index data-structures/suffix-trees/index - data-structures/tries/index data-structures/to-function + data-structures/tries/index data-structures/visualisation/index data-structures/word-graph/index data-structures/words/index diff --git a/docs/source/install.rst b/docs/source/install.rst index f3c6bfc56..7155d1d5d 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -5,104 +5,111 @@ The full license is in the file LICENSE, distributed with this software. -.. |libsemigroups-pybind11-version| replace:: 1.0.0 - Installation ============ Installing with pip ------------------- -It's possible to install ``libsemigroups_pybind11`` using ``pip`` via one of: - -:: - - pip install libsemigroups_pybind11 - pip3 install libsemigroups_pybind11 - python -m pip install libsemigroups_pybind11 - -Installing with conda ---------------------- - -This installation method assumes that you have anaconda or miniconda installed. -See the `getting started`_ and `miniconda download page`_ on the conda_ website. - -.. _conda: https://conda.io/ - -.. _getting started: http://bit.ly/33B0Vfs +It's possible to install ``libsemigroups_pybind11`` using ``pip`` by doing one +of the following (depending on your system and setup): -.. _miniconda download page: https://conda.io/miniconda.html - -It might be a good idea to create and activate a conda environment to contain -the installation of the ``libsemigroups_pybind11``: +.. highlight:: console :: - conda create --name libsemigroups - conda activate libsemigroups + $ pip install libsemigroups_pybind11 -Install ``libsemigroups_pybind11``: :: - - conda install -c conda-forge libsemigroups_pybind11 - -.. warning:: - - At present this does not work for Macs with M1 processors. + + $ pip3 install libsemigroups_pybind11 + +:: + + $ python -m pip install libsemigroups_pybind11 + + +.. Installing with conda + --------------------- + + This installation method assumes that you have anaconda or miniconda installed. + See the `getting started`_ and `miniconda download page`_ on the conda_ website. + + .. _conda: https://conda.io/ + + .. _getting started: http://bit.ly/33B0Vfs + + .. _miniconda download page: https://conda.io/miniconda.html + + It might be a good idea to create and activate a conda environment to contain + the installation of the ``libsemigroups_pybind11``: + + :: + + conda create --name libsemigroups + conda activate libsemigroups + + Install ``libsemigroups_pybind11``: + + :: + + conda install -c conda-forge libsemigroups_pybind11 + + .. warning:: + + At present this does not work for Macs with M1 processors. From the sources ---------------- -Before installing ``libsemigroups_pybind11`` from its sources you should first +Before installing ``libsemigroups_pybind11`` from its sources, you should first perform a system install of the C++ library ``libsemigroups``. For information -about how to install ``libsemigroups`` see `the installation guide -`_. +about how to do this, see the `libsemigroups installation guide +`_. -Assuming that you have ``libsemigroups`` installed you can install +Assuming that you have ``libsemigroups`` installed, you can install ``libsemigroups_pybind11`` as follows: :: - git clone https://github.com/libsemigroups/libsemigroups_pybind11 - cd libsemigroups_pybind11 - pip install . + $ git clone https://github.com/libsemigroups/libsemigroups_pybind11 + $ cd libsemigroups_pybind11 + $ pip install . From a release archive ~~~~~~~~~~~~~~~~~~~~~~ To build ``libsemigroups_pybind11`` from a release archive: +.. Unfortunately, text replacement doesn't work inside of code blocks, so it is + necessary to update the version number below manually. + :: - curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - tar -xf libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - rm -f libsemigroups_pybind11-|libsemigroups-pybind11-version|.tar.gz - cd libsemigroups_pybind11-|libsemigroups-pybind11-version| - pip install . + $ curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-1.0.0.tar.gz + $ tar -xf libsemigroups_pybind11-1.0.0.tar.gz + $ rm -f libsemigroups_pybind11-1.0.0.tar.gz + $ cd libsemigroups_pybind11-1.0.0 + $ pip install . Building the documentation -------------------------- -The following are required to be able to build the documentation: - -1. ``python3`` -2. the python packages: ``jinja2 sphinx sphinx_rtd_theme sphinxcontrib-bibtex - sphinx_copybutton`` - -Assuming you already have ``python3`` install, on Mac OSX you can install all of -the above by doing: +Assuming you have ``python3`` and ``make`` installed, you can build the doc by +using: :: - python3 -m pip3 install -r docs/requirements + $ python3 -m pip3 install -r requirements.txt + $ make doc -Then it ought to be possible to just run ``make doc`` in the ``libsemigroups`` -directory. +If you don't have ``make``, you can run the executable ``./etc/make-doc.sh`` +instead of running ``make doc`` (which is precisely what ``make doc`` does). Issues ------ If you find any problems with ``libsemigroups_pybind11``, or have any -suggestions for features that you’d like to see, please use the +suggestions for features that you'd like to see, please use the `issue tracker`_. diff --git a/docs/source/libsemigroups-error.rst b/docs/source/libsemigroups-error.rst new file mode 100644 index 000000000..47ceef4e7 --- /dev/null +++ b/docs/source/libsemigroups-error.rst @@ -0,0 +1,105 @@ +.. + Copyright (c) 2024 Joseph Edwards + + Distributed under the terms of the GPL license version 3. + + The full license is in the file LICENSE, distributed with this software. + +.. currentmodule:: libsemigroups_pybind11 + +Exceptions +========== + +This page describes the custom error type used in ``libsemigroups_pybind11``, +namely :any:`LibsemigroupsError`, and related functions. Other built-in +exceptions, such as :any:`ValueError` and :any:`TypeError`, may also be raised +in this project. See the +`Python documentation `_ +for further details. + +The Python module ``libsemigroups_pybind11`` was designed to mirror the C++ +library libsemigroups_ as closely as possible, whilst navigating the +fundamental difference between Python and C++. This is done with the help of +`pybind11 `_. + +For various implementational reasons (mostly related to Python's lack of an +analogue for C++'s templating system), the Python code exposed by ``pybind11`` +is less streamlined and concise than the C++ library. To try and address this, +the authors of ``libsemigroups_pybind11`` have further wrapped the Python code +produced by ``pybind11`` to make the Python and C++ user experience as similar +as possible. + +The Python bindings of the libsemigroups_ code produced by ``pybind11`` +reside in an intermediate module called ``_libsemigroups_pybind11`` (note the +leading underscore), and the public-facing nicely wrapped code resides in this +module — ``libsemigroups_pybind11``. + +Should this impact the way you, the user, use ``libsemigroups_pybind11``? For +the most part, no. It should be possible to use ``libsemigroups_pybind11`` in +the ways documented on this site without the knowledge that +``_libsemigroups_pybind11`` even exists. The notable exceptions to this relate +to type names and error messages. A lot of the code in +``libsemigroups_pybind11`` has been imported from ``_libsemigroups_pybind11``, +and this is visible in qualified type names. For example: + +.. doctest:: python + + >>> from libsemigroups_pybind11 import WordGraph + >>> WordGraph + + +Additionally, some functions or classes in the ``_libsemigroups_pybind11`` +module have additional prefixes and suffixes relative to their +``libsemigroups_pybind11`` counterpart. These usually relate to the module that +the function or class is contained within or a type the function or class is +defined upon. These may appear in error messages. For example: + +.. doctest:: python + + >>> from libsemigroups_pybind11 import aho_corasick, AhoCorasick + >>> ac = AhoCorasick() + >>> aho_corasick.add_word(ac, False) + Traceback (most recent call last): + ... + TypeError: aho_corasick_add_word(): incompatible function arguments. The following argument types are supported: + 1. (ac: _libsemigroups_pybind11.AhoCorasick, w: list[int]) -> int + 2. (ac: _libsemigroups_pybind11.AhoCorasick, w: str) -> int + + Invoked with: , False + +The authors of ``libsemigroups_pybind11`` have gone to a lot of effort to try +and make error messages clear, specific and intelligible; however, if you +encounter any errors with unclear messages, please let us know on the +`issue tracker`_. + +Full API +-------- + +.. autoexception:: LibsemigroupsError + :show-inheritance: + + This is the main type of exception raised by the custom data-structures and + algorithms of ``libsemigroups_pybind11``. It is raised when the underlying + C++ code from libsemigroups_ raises a ``LibsemigroupsException``. + + .. doctest:: python + + >>> from libsemigroups_pybind11 import FroidurePin, Perm + >>> gens = [Perm([3, 0, 1, 2]), Perm([1, 2, 0, 3]), Perm([2, 1, 0, 3])] + >>> S = FroidurePin(gens) + >>> S + + + >>> S.generator(3) # Bad: there are only three generators + Traceback (most recent call last): + ... + LibsemigroupsError: generator index out of bounds, expected value in [0, 3), got 3 + + .. note:: + + If you believe your code is incorrectly throwing a + :any:`LibsemigroupsError`, or isn't throwing a :any:`LibsemigroupsError` + but you think it should, please let us known by opening an issue on the + `issue tracker`_. + +.. autofunction:: error_message_with_prefix