Skip to content

Commit 6fdae37

Browse files
Joseph-Edwardsjames-d-mitchell
Joseph-Edwards
authored and
james-d-mitchell
committed
Doc: update README
1 parent 426ad00 commit 6fdae37

File tree

1 file changed

+138
-89
lines changed

1 file changed

+138
-89
lines changed

‎README.md

Lines changed: 138 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -4,108 +4,157 @@
44

55
[![DOI](https://zenodo.org/badge/299898305.svg)](https://zenodo.org/badge/latestdoi/299898305)
66

7-
### What is `libsemigroups`?
8-
9-
`libsemigroups` is a C++14 library containing implementations of several
10-
algorithms for computing finite and finitely presented semigroups.
11-
Namely:
12-
13-
- the [Froidure-Pin algorithm](https://www.irif.fr/~jep/PDF/Rio.pdf)
14-
for computing finite semigroups
15-
- the [Todd-Coxeter
16-
algorithm](https://en.wikipedia.org/wiki/Todd%E2%80%93Coxeter_algorithm)
17-
for finitely presented semigroups and monoids;
18-
- the [Knuth-Bendix
19-
algorithm](https://en.wikipedia.org/wiki/Knuth%E2%80%93Bendix_completion_algorithm)
20-
for finitely presented semigroups and monoids;
21-
- the [Schreier-Sims
22-
algorithm](https://en.wikipedia.org/wiki/Schreier%E2%80%93Sims_algorithm)
23-
for permutation groups;
24-
- a preliminary implementation of the
25-
[Konieczny](https://link.springer.com/article/10.1007/BF02573672)
26-
and
27-
[Lallement-McFadden](https://www.sciencedirect.com/science/article/pii/S0747717108800570)
28-
algorithm for computing finite semigroups which act on sets.
29-
30-
`libsemigroups_pybind11` is a python package exposing much (but not all)
31-
of the functionality of `libsemigroups`.
32-
33-
The development version of `libsemigroups_pybind11` is available on
34-
[github](https://github.com/libsemigroups/libsemigroups_pybind11), and
35-
some related projects are [here](https://github.com/libsemigroups).
36-
37-
# Installation
38-
39-
## Installing with pip
40-
41-
It's possible to install `libsemigroups_pybind11` using `pip` via one of:
42-
43-
pip install libsemigroups_pybind11
44-
pip3 install libsemigroups_pybind11
45-
python -m pip install libsemigroups_pybind11
46-
python3 -m pip install libsemigroups_pybind11
47-
48-
## Installing with conda
49-
50-
This installation method assumes that you have anaconda or miniconda
51-
installed. See the [getting started](http://bit.ly/33B0Vfs) and
52-
[miniconda download page](https://conda.io/miniconda.html) on the
53-
[conda](https://conda.io/) website.
54-
55-
It might be a good idea to create and activate a conda environment to
56-
contain the installation of the `libsemigroups_pybind11`:
57-
58-
conda create --name libsemigroups
59-
conda activate libsemigroups
60-
61-
Install `libsemigroups_pybind11`:
62-
63-
conda install -c conda-forge libsemigroups_pybind11
64-
65-
At present this does not work for Macs with M1 processors.
66-
67-
## From the sources
68-
69-
Before installing `libsemigroups_pybind11` from its sources you should
70-
first perform a system install of the C++ library `libsemigroups`. For
71-
information about how to install `libsemigroups` see [the installation
72-
guide](https://libsemigroups.readthedocs.io/en/latest/install.html).
73-
74-
Assuming that you have `libsemigroups` installed you can install
7+
## What is [libsemigroups][]?
8+
9+
Before explaining what `libsmigroups_pybind11` is, it is first necessary to
10+
explain [libsemigroups][]. [libsemigroups][] is a C++17 library containing
11+
implementations of several algorithms for computing finite, and finitely
12+
presented, semigroups and monoids. The main algorithms implemented in
13+
[libsemigroups][] are:
14+
15+
- the [Froidure-Pin algorithm][] for computing semigroups and monoids defined
16+
by a generating set consisting of elements whose multiplication and equality
17+
is decidable (such as transformations, partial permutations, permutations,
18+
bipartitions, and matrices over a semiring);
19+
- Kambites' algorithm for solving the word problem in small overlap monoids
20+
from [Small overlap monoids I: The word problem][],
21+
and the algorithm from
22+
[An explicit algorithm for normal forms in small overlap monoids][];
23+
- the [Knuth-Bendix algorithm][] for finitely presented semigroups and monoids;
24+
a version of Sims' low index subgroup algorithm for computing congruences of a
25+
semigroup or monoid from
26+
[Computing finite index congruences of finitely presented semigroups and monoids][]
27+
in the classes;
28+
- a generalized version of the algorithms described in
29+
[Green's equivalences in finite semigroups of binary relations][] by
30+
Konieczny, and
31+
[On the determination of Green's relations in finite transformation semigroups][]
32+
by Lallement and Mcfadden for computing finite semigroups and monoids
33+
admitting a pair of actions with particular properties;
34+
- the algorithm from
35+
[Efficient Testing of Equivalence of Words in a Free Idempotent Semigroup][]
36+
by Radoszewski and Rytter;
37+
- a non-random version of the [Schreier-Sims algorithm][] for permutation groups;
38+
- a version of Stephen's procedure from
39+
[Applications of automata theory to presentations of monoids and inverse monoids][]
40+
for finitely presented inverse semigroups and monoids (for a given word `w`
41+
this procedure is for determining words equivalent to `w` or that are
42+
left divisors of `w`);
43+
- the [Todd-Coxeter algorithm][] for finitely presented semigroups and monoids;
44+
see also [The Todd-Coxeter algorithm for semigroups and monoids][].
45+
46+
[libsemigroups][] is partly based on
47+
[Algorithms for computing finite semigroups][Froidure-Pin algorithm],
48+
[Expository Slides][], and [Semigroupe 2.01][] by [Jean-Eric Pin][].
49+
50+
[Froidure-Pin algorithm]: https://www.irif.fr/~jep/PDF/Rio.pdf
51+
[Small overlap monoids I: The word problem]: https://doi.org/10.1016/j.jalgebra.2008.09.038
52+
[An explicit algorithm for normal forms in small overlap monoids]: https://doi.org/10.1016/j.jalgebra.2023.04.019
53+
[Knuth-Bendix algorithm]: https://en.wikipedia.org/wiki/Knuth%E2%80%93Bendix_completion_algorithm
54+
[Computing finite index congruences of finitely presented semigroups and monoids]: https://arxiv.org/abs/2302.06295
55+
[Green's equivalences in finite semigroups of binary relations]: https://link.springer.com/article/10.1007/BF02573672
56+
[On the determination of Green's relations in finite transformation semigroups]: https://www.sciencedirect.com/science/article/pii/S0747717108800570
57+
[Efficient Testing of Equivalence of Words in a Free Idempotent Semigroup]: https://link.springer.com/chapter/10.1007/978-3-642-11266-9_55
58+
[Applications of automata theory to presentations of monoids and inverse monoids]: https://digitalcommons.unl.edu/dissertations/AAI8803771/
59+
[Todd-Coxeter algorithm]: https://en.wikipedia.org/wiki/Todd%E2%80%93Coxeter_algorithm
60+
[The Todd-Coxeter algorithm for semigroups and monoids]: https://doi.org/10.1007/s00233-024-10431-z
61+
[Schreier-Sims algorithm]: https://en.wikipedia.org/wiki/Schreier%E2%80%93Sims_algorithm
62+
[Expository Slides]: https://www.irif.fr/~jep/PDF/Exposes/StAndrews.pdf
63+
[Semigroupe 2.01]: https://www.irif.fr/~jep/Logiciels/Semigroupe2.0/semigroupe2.html
64+
[Jean-Eric Pin]: https://www.irif.fr/~jep/
65+
66+
## What is `libsemigroups_pybind11`?
67+
68+
`libsemigroups_pybind11` is a package for Python 3.9+ exposing much
69+
(but not all) of the functionality of [libsemigroups][]. It is built with the help
70+
of the excellent library [pybind11][], for which we are very grateful.
71+
72+
## How to install `libsemigroups_pybind11`
73+
74+
### Installing with pip
75+
76+
It's possible to install `libsemigroups_pybind11` using `pip` by doing one
77+
of the following (depending on your system and setup):
78+
79+
```console
80+
pip install libsemigroups_pybind11
81+
```
82+
83+
```console
84+
pip3 install libsemigroups_pybind11
85+
```
86+
87+
```console
88+
python -m pip install libsemigroups_pybind11
89+
```
90+
91+
### From the sources
92+
93+
Before installing `libsemigroups_pybind11` from its sources, you should first
94+
perform a system install of `libsemigroups`. For information
95+
about how to do this, see the
96+
[libsemigroups installation guid](https://libsemigroups.github.io/libsemigroups/md_install.html).
97+
98+
Assuming that you have `libsemigroups` installed, you can install
7599
`libsemigroups_pybind11` as follows:
76100

77-
git clone https://github.com/libsemigroups/libsemigroups_pybind11
78-
cd libsemigroups_pybind11
79-
pip install .
101+
```console
102+
git clone https://github.com/libsemigroups/libsemigroups_pybind11
103+
cd libsemigroups_pybind11
104+
pip install .
105+
```
80106

81107
### From a release archive
82108

83109
To build `libsemigroups_pybind11` from a release archive:
84110

85-
curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-0.10.1.tar.gz
86-
tar -xf libsemigroups_pybind11-0.10.1.tar.gz
87-
rm -f libsemigroups_pybind11-0.10.1.tar.gz
88-
cd libsemigroups_pybind11-0.10.1
89-
pip install .
111+
```console
112+
curl -L -O https://github.com/libsemigroups/libsemigroups_pybind11/releases/latest/download/libsemigroups_pybind11-1.0.0.tar.gz
113+
tar -xf libsemigroups_pybind11-1.0.0.tar.gz
114+
rm -f libsemigroups_pybind11-1.0.0.tar.gz
115+
cd libsemigroups_pybind11-1.0.0
116+
pip install .
117+
```
90118

91119
## Building the documentation
92120

93-
The following are required to be able to build the documentation:
94-
95-
1. `python3`
96-
2. the python packages:
97-
`jinja2 sphinx sphinx_rtd_theme sphinxcontrib-bibtex sphinx_copybutton`
98-
99-
Assuming you already have `python3` install, on Mac OSX you can install
100-
all of the above by doing:
121+
Assuming you have `python3` and `make` installed, you can build the doc by
122+
using:
101123

102-
python3 -m pip3 install -r requirements.txt
124+
```console
125+
python3 -m pip3 install -r requirements.txt
126+
make doc
127+
```
103128

104-
Then it ought to be possible to just run `make doc` in the
105-
`libsemigroups_pybind11` directory.
129+
If you don't have `make`, you can run the executable `./etc/make-doc.sh`
130+
instead of running `make doc` (which is precisely what `make doc` does).
106131

107132
## Issues
108133

109134
If you find any problems with `libsemigroups_pybind11`, or have any
110-
suggestions for features that you'd like to see, please use the [issue
111-
tracker](https://github.com/libsemigroups/libsemigroups_pybind11/issues).
135+
suggestions for features that you'd like to see, please use the
136+
[issue tracker][].
137+
138+
## Acknowledgements
139+
140+
In addition to [libsemigroups][], there are several excellent projects that are
141+
utilised in the development of `libsemigroups_pybind11`, specifically:
142+
143+
- [codespell][], [cpplint][], [Pylint][] and [Ruff][] for code quality;
144+
- [Graphviz][] for graph visualisation;
145+
- [pybind11][] for assistance in the binding of [libsemigroups][];
146+
- [pytest][] for testing; and
147+
- [Sphinx][] for the documentation.
148+
149+
We would like to thank the authors and contributors of these projects!
150+
151+
[codespell]: https://github.com/codespell-project/codespell
152+
[cpplint]: https://github.com/cpplint/cpplint
153+
[Pylint]: https://pylint.readthedocs.io/en/latest/
154+
[Ruff]: https://docs.astral.sh/ruff
155+
[pytest]: https://docs.pytest.org/en/stable/
156+
[Sphinx]: https://www.sphinx-doc.org/en/master/
157+
[libsemigroups]: https://libsemigroups.github.io/libsemigroups/
158+
[issue tracker]: https://github.com/libsemigroups/libsemigroups_pybind11/issues
159+
[Graphviz]: https://www.graphviz.org
160+
[pybind11]: https://pybind11.readthedocs.io/en/stable/#

0 commit comments

Comments
 (0)