Word graph hpp (#189)

.codespellrc

@@ -1,3 +1,3 @@
 [codespell]
 skip = ./.git,./docs/_build/*,./gh-pages
-ignore-words-list=nd,alph,falsy,toword
+ignore-words-list=nd,alph,falsy,toword,noe

.github/workflows/tests.yml

@@ -10,7 +10,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python_version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python_version: ["3.9", "3.10", "3.11", "3.12"]
     runs-on: ubuntu-latest
     timeout-minutes: 15
     defaults:
@@ -66,14 +66,14 @@ jobs:
         run: |
           pip3 install pylint cpplint
       - name: "Running pylint and cpplint . . ."
-        run:  |
+        run: |
           python -m pylint setup.py tests/*.py libsemigroups_pybind11/*.py
           python -m cpplint src/*.hpp src/*.cpp
   macosx:
     strategy:
       fail-fast: false
       matrix:
-        python_version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python_version: ["3.9", "3.10", "3.11", "3.12"]
     runs-on: macOS-latest
     timeout-minutes: 15
     env:
@@ -94,8 +94,7 @@ jobs:
           echo "LD_LIBRARY_PATH=$MAMBA_ROOT_PREFIX/envs/libsemigroups/lib:/usr/local/lib" >> $GITHUB_ENV
           echo "PATH=$MAMBA_ROOT_PREFIX/envs/libsemigroups/bin:$PATH" >> $GITHUB_ENV
       - name: "Install libsemigroups dependencies . . ."
-        run :
-          brew install autoconf automake libtool
+        run: brew install autoconf automake libtool
       - name: "Setup ccache . . ."
         uses: Chocobo1/setup-ccache-action@v1
         with:
@@ -132,6 +131,6 @@ jobs:
         run: |
           pip3 install pylint cpplint
       - name: "Running pylint and cpplint . . ."
-        run:  |
+        run: |
           python -m pylint setup.py tests/*.py libsemigroups_pybind11/*.py
           python -m cpplint src/*.hpp src/*.cpp

docs/source/conf.py

@@ -138,7 +138,10 @@ def no_doc_run(self):
     )
 ]
 
-intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
 
 autodoc_default_options = {"show-inheritence": True}
 
@@ -155,6 +158,11 @@ def no_doc_run(self):
     r"libsemigroups::BMat8": r"BMat8",
     r"libsemigroups::WordGraph<unsigned int>": r"WordGraph",
     r"libsemigroups::Gabow<unsigned int>": r"Gabow",
+    (
+        r"libsemigroups::DynamicMatrix<libsemigroups::IntegerPlus<long long>, "
+        r"libsemigroups::IntegerProd<long long>, libsemigroups::IntegerZero"
+        r"<long long>, libsemigroups::IntegerOne<long long>, long long>"
+    ): "Matrix",
 }
 
 # This dictionary should be of the form class_name -> (pattern, repl), where
@@ -414,6 +422,7 @@ def fix_overloads(app, what, name, obj, options, lines):
 docstring_replacements = {
     r"aho_corasick_dot\(.*\)(\s*->\s*(\w+::)*\w*)?": "",
     r"pbr_one\(\*args, \*\*kwargs\)": "",
+    r"word_graph_dot\(.*\)(\s*->\s*(\w+::)*\w*)?": "",
 }
 
 

docs/source/data-structures/word-graph/helpers.rst

@@ -0,0 +1,62 @@
+.. Copyright (c) 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.
+
+
+Helper functions for word graphs
+================================
+
+This page contains the documentation for various helper functions for
+manipulating word graphs.
+
+Contents
+--------
+
+In ``libsemigroups_pybind11``:
+
+.. currentmodule:: libsemigroups_pybind11
+
+.. autosummary::
+   :nosignatures:
+
+   to_word_graph
+
+In ``libsemigroups_pybind11.word_graph``:
+
+.. currentmodule:: libsemigroups_pybind11.word_graph
+
+.. autosummary::
+   :nosignatures:
+
+   add_cycle
+   adjacency_matrix
+   dot
+   equal_to
+   follow_path
+   is_acyclic
+   is_compatible
+   is_complete
+   is_connected
+   is_reachable
+   is_strictly_cyclic
+   last_node_on_path
+   nodes_reachable_from
+   number_of_nodes_reachable_from
+   random_acyclic
+   spanning_tree
+   standardize
+   topological_sort
+
+Full API
+--------
+
+.. currentmodule:: libsemigroups_pybind11
+
+.. autofunction:: to_word_graph
+
+.. automodule:: libsemigroups_pybind11.word_graph
+   :members:
+   :imported-members:
+

docs/source/data-structures/word-graph/index.rst

@@ -9,13 +9,16 @@
 Word Graphs
 ===========
 
-``libsemigroups_pybind11`` has some limited functionality for word graphs.
-
-The classes in ``libsemigroups_pybind11`` for word graphs are:
+This page contains links to the documentation for the parts
+of ``libsemigroups_pybind11`` for word graphs.
 
 .. toctree::
    :maxdepth: 1
 
    forest
+   gabow/index
+   joiner
+   meeter 
    paths/index
    word-graph
+   helpers

docs/source/data-structures/word-graph/joiner.rst

@@ -0,0 +1,33 @@
+.. 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.
+
+.. currentmodule:: _libsemigroups_pybind11
+
+The Joiner class
+================
+
+.. autoclass:: Joiner
+   :doc-only:
+   :class-doc-from: class
+
+Contents
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    ~Joiner
+    Joiner.__call__
+    Joiner.copy
+    Joiner.is_subrelation
+
+Full API
+--------
+
+.. autoclass:: Joiner
+   :members:
+   :special-members: __init__, __call__
+   :class-doc-from: init

docs/source/data-structures/word-graph/meeter.rst

@@ -0,0 +1,33 @@
+.. 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.
+
+.. currentmodule:: _libsemigroups_pybind11
+
+The Meeter class
+================
+
+.. autoclass:: Meeter
+   :doc-only:
+   :class-doc-from: class
+
+Contents
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    ~Meeter
+    Meeter.__call__
+    Meeter.copy
+    Meeter.is_subrelation
+
+Full API
+--------
+
+.. autoclass:: Meeter
+   :members:
+   :special-members: __init__, __call__
+   :class-doc-from: init

docs/source/data-structures/word-graph/word-graph.rst

@@ -6,7 +6,44 @@
 
 .. currentmodule:: _libsemigroups_pybind11
 
-WordGraph
-=========
+The WordGraph class
+===================
 
-TODO
+.. autoclass:: WordGraph
+   :doc-only:
+   :class-doc-from: class
+
+Contents
+--------
+
+.. autosummary::
+    :nosignatures:
+
+    ~WordGraph
+    WordGraph.add_nodes
+    WordGraph.add_to_out_degree
+    WordGraph.copy
+    WordGraph.disjoint_union_inplace
+    WordGraph.induced_subgraph
+    WordGraph.init
+    WordGraph.labels_and_targets
+    WordGraph.next_label_and_target
+    WordGraph.nodes
+    WordGraph.number_of_edges
+    WordGraph.number_of_nodes
+    WordGraph.out_degree
+    WordGraph.random
+    WordGraph.remove_all_targets
+    WordGraph.remove_label
+    WordGraph.remove_target
+    WordGraph.reserve
+    WordGraph.swap_targets
+    WordGraph.target
+    WordGraph.targets
+
+Full API
+--------
+
+.. autoclass:: WordGraph
+   :members:
+   :class-doc-from: init

docs/source/index.rst

@@ -67,7 +67,6 @@ See the installation instructions:
    main-algorithms/aho-corasick/index.rst
    main-algorithms/congruences/index
    main-algorithms/froidure-pin/index
-   main-algorithms/gabow/index
    main-algorithms/kambites/index
    main-algorithms/knuth-bendix/index
    main-algorithms/konieczny/index

docs/source/libsemigroups.bib

@@ -6,6 +6,28 @@
 
 %% Saved with string encoding Unicode (UTF-8) 
 
+@inbook{Carnino2011,
+  title = {Random Generation of Deterministic Acyclic Automata Using Markov Chains},
+  ISBN = {9783642222566},
+  ISSN = {1611-3349},
+  url = {http://dx.doi.org/10.1007/978-3-642-22256-6_7},
+  DOI = {10.1007/978-3-642-22256-6_7},
+  booktitle = {Implementation and Application of Automata},
+  publisher = {Springer Berlin Heidelberg},
+  author = {Carnino,  Vincent and De Felice,  Sven},
+  year = {2011},
+  pages = {65–75}
+}
+
+@misc{Hop71,
+  Author = {Hopcroft, John E. and Karp, R. M.},
+  Title = {A linear algorithm for testing equivalence of finite automata},
+  Journal = {Technical Report 114, Cornell University},
+  Url = {https://hdl.handle.net/1813/5958},
+  Month={December},
+  Year = {1971},
+}
+
 @article{Gab00,
   Author = {Harold N. Gabow},
   Doi = {https://dx.doi.org/10.1016/S0020-0190(00)00051-X},
@@ -19,8 +41,6 @@ @article{Gab00
   Url = {https://www.sciencedirect.com/science/article/pii/S002001900000051X},
   Volume = {74},
   Year = {2000},
-  Bdsk-Url-2 = {https://dx.doi.org/10.1016/S0020-0190(00)00051-X},
-  Bdsk-Url-1 = {https://www.sciencedirect.com/science/article/pii/S002001900000051X},
 }
 
 @misc{Anagnostopoulou-Merkouri2023aa,

etc/build-wheels.sh

@@ -4,15 +4,15 @@
 set -e
 set -o pipefail
 
-# This script requires that python 3.8, 3.9, 3.10, and 3.11 are installed
+# This script requires that python 3.9, 3.10, 3.11 and 3.12 are installed
 # by homebrew. If you've updated your OS recently, then it's also necessary to
 # update the installations of python so that they are built against the same
 # version of the OS. Building the wheels will fail if this doesn't happen.
 #
-# Python 3.7 is not supported on non-x86_64 so 3.8 is the earliest version of
-# python we can use here.
+# Python 3.8 is end-of-life as of October 2024 so 3.9 is the earliest version of
+# python we use here.
 
-PYTHON_VERSIONS=( "3.8" "3.9" "3.10" "3.11" )
+PYTHON_VERSIONS=("3.9" "3.10" "3.11" "3.12")
 
 if ! [[ "$PWD" == *libsemigroups_pybind11 ]] ; then
   echo -e "This script must be run in the libsemigroups_pybind11 directory! Aborting!"

libsemigroups_pybind11/__init__.py

@@ -58,7 +58,9 @@
         Blocks,
         freeband_equal_to,
         to_forest,
-        Dot,
+        Meeter,
+        to_word_graph,
+        Joiner,
     )
 except ModuleNotFoundError as e:
     raise ModuleNotFoundError(
@@ -71,6 +73,7 @@
 
 from .action import Action, RightAction, LeftAction
 from .adapters import ImageRightAction, ImageLeftAction
+from ._dot import _Dot as Dot
 from .knuth_bendix import KnuthBendix
 from .matrix import _Matrix as Matrix, _MatrixKind as MatrixKind
 from .presentation import Presentation, InversePresentation