Sync forest and Forest

Author: james-d-mitchell

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

@@ -17,10 +17,11 @@ This page contains links to the documentation for the parts of
     :maxdepth: 1
 
     forest
+    forest-helpers
     gabow
     joiner
     meeter
     paths
     word-graph
     paths-helpers
-    helpers
+    word-graph-helpers

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

@@ -300,8 +300,7 @@ then node ``i`` is a root node.
         R"pbdoc(
 :sig=(self: Forest, i: int) -> list[int]:
 
-Returns a list containing the labels of the edges on the path from a root node
-to *i*.
+Returns a list containing the labels of the edges on the path from the node *i* to a root node.
 
 :param i: the node.
 :type i: int
@@ -340,6 +339,185 @@ Set the parent and edge label for a node. This function sets the parent of
   if *node* or *parent* exceeds :any:`number_of_nodes()`.
 
 :complexity: Constant.
+)pbdoc");
+
+    ////////////////////////////////////////////////////////////////////////
+    // Helpers
+    ////////////////////////////////////////////////////////////////////////
+
+    m.def(
+        "forest_path_to_root",
+        [](Forest const& f, node_type n) { return forest::path_to_root(f, n); },
+        py::arg("f"),
+        py::arg("n"),
+        R"pbdoc(
+:sig=(f: Forest, n: int) -> list[int]:
+
+Returns a list containing the labels of the edges on the path from node *n* to
+a root node.
+
+:param f: the Forest.
+:type f: Forest
+
+:param n: the node.
+:type n: int
+
+:returns: The word labelling the path from the root to *n*.
+:rtype: list[int]
+
+:raises LibsemigroupsError:
+  if *n* is greater than or equal to :any:`Forest.number_of_nodes`.
+)pbdoc");
+
+    m.def(
+        "forest_depth",
+        [](Forest const& f, node_type n) { return forest::depth(f, n); },
+        py::arg("f"),
+        py::arg("n"),
+        R"pbdoc(
+:sig=(f: Forest, n: int) -> int:
+
+Returns the depth of a node in the forest, i.e. the distance, in terms of the
+number of edges, from a root.
+
+This function returns the length of the word returned by
+:any:`path_to_root` and :any:`path_from_root`.
+
+:param f: the Forest.
+:type f: Forest
+
+:param n: the node.
+:type n: int
+
+:returns: The depth of *n*.
+:rtype: int
+
+:raises LibsemigroupsError:
+   if *n* is out of bounds (i.e. it is greater than or equal to
+   :any:`Forest.number_of_nodes`).
+)pbdoc");
+
+    m.def(
+        "forest_dot",
+        [](Forest const& f) { return forest::dot(f); },
+        py::arg("f"),
+        R"pbdoc(
+Returns a :any:`Dot` object representing a Forest.
+
+This function returns a :any:`Dot` object representing the :any:`Forest` *f*.
+
+:param f: the Forest.
+:type f: Forest
+
+:returns: A :any:`Dot` object.
+
+:rtype: Dot
+)pbdoc");
+
+    m.def(
+        "forest_dot",
+        [](Forest const& f, std::vector<std::string> const& labels) {
+          return forest::dot(f, labels);
+        },
+        py::arg("f"),
+        py::arg("labels"),
+        R"pbdoc(
+:sig=(f: Forest, labels: list[str]) -> Dot:
+
+Returns a :any:`Dot` object representing a Forest.
+
+This function returns a :any:`Dot` object representing the :any:`Forest` *f*.
+If *labels* is not empty, then each node is labelled with the path from
+that node to the root of its tree with each letter replaced by the string
+in the corresponding position of *labels*. If *labels* is empty, then
+the nodes are not labelled by their paths.
+
+:param f: the Forest.
+:type f: Forest
+
+:param labels: substitute for each edge label.
+:type labels: list[str]
+
+:returns: A :any:`Dot` object.
+:rtype: Dot
+
+:raises LibsemigroupsError:
+    if the size of *labels* is not the same as the :any:`max_label` plus one.
+)pbdoc");
+
+    m.def("forest_is_root",
+          &forest::is_root,
+          py::arg("f"),
+          py::arg("n"),
+          R"pbdoc(
+:sig=(f: Forest, n: int) -> bool:
+
+Check if a node is the root of any tree in the :any:`Forest`.
+
+This function returns ``True`` if the node *n* in the :any:`Forest` *f* is
+a root node, and ``False`` if it is not.
+
+:param f: the Forest.
+:type f: Forest
+
+:param n: the node.
+:type n: int
+
+:returns: Whether or not *n* is a root of *f*.
+:rtype: bool
+
+:raises LibsemigroupsError:
+   if *n* is out of bounds (i.e. it is greater than or equal to
+   :any:`Forest.number_of_nodes`).
+)pbdoc");
+
+    m.def(
+        "forest_max_label",
+        [](Forest const& f) -> int_or_unsigned_constant<Forest::label_type> {
+          return from_int(forest::max_label(f));
+        },
+        py::arg("f"),
+        R"pbdoc(
+:sig=(f: Forest) -> int | Undefined:
+
+Returns the maximum label of any edge in a :any:`Forest`.
+
+This function returns the maximum label of any edge in the :any:`Forest` *f*
+or :any:`UNDEFINED` if there are no edges.
+
+:param f: the Forest.
+:type f: Forest
+
+:returns: The maximum label or :any:`UNDEFINED`.
+:rtype: int | Undefined
+)pbdoc");
+
+    m.def(
+        "forest_path_from_root",
+        [](Forest const& f, Forest::node_type n) {
+          return forest::path_from_root(f, n);
+        },
+        py::arg("f"),
+        py::arg("n"),
+        R"pbdoc(
+:sig=(f: Forest, n: int) -> list[int]:
+
+Returns a word containing the labels of the edges on the path from a root node
+to *n*.
+
+This function returns a word containing the labels of the edges on the path
+from a root node to the node *n*.
+
+:param f: the forest.
+:type f: Forest
+
+:param n: the node.
+:type n: int
+
+:returns: The word labelling the path from a root node to *n*.
+:rtype: list[int]
+
+.. seealso:: :any:`PathsFromRoots`
 )pbdoc");
   }
 }  // namespace libsemigroups

src/forest.cpp

@@ -15,6 +15,7 @@
 import libsemigroups_pybind11.blocks
 import libsemigroups_pybind11.bmat8
 import libsemigroups_pybind11.congruence
+import libsemigroups_pybind11.forest
 import libsemigroups_pybind11.froidure_pin
 import libsemigroups_pybind11.kambites
 import libsemigroups_pybind11.knuth_bendix

src/libsemigroups_pybind11/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+"""
+This page contains the documentation for various helper functions for
+manipulating :any:`Forest` objects. All such functions are contained in
+the submodule ``forest``.
+"""
+
+from typing_extensions import Self as _Self
+
+from _libsemigroups_pybind11 import (  # pylint: disable=no-name-in-module
+    forest_depth as depth,
+    forest_dot as dot,
+    forest_is_root as is_root,
+    forest_path_to_root as path_to_root,
+    forest_path_from_root as path_from_root,
+    forest_max_label as max_label,
+)

src/libsemigroups_pybind11/forest.py

@@ -15,7 +15,7 @@
 
 import pytest
 
-from libsemigroups_pybind11 import Forest, UNDEFINED
+from libsemigroups_pybind11 import Forest, UNDEFINED, forest
 
 
 @pytest.fixture(name="f")
@@ -30,3 +30,82 @@ def test_forest_return_policy(f):
     assert f.parents() is not f.parents()
     assert f.labels() is not f.labels()
     assert f.set_parent_and_label(1, 0, 10) is f
+
+
+def test_forest_depth(f):
+    assert [forest.depth(f, n) for n in range(f.number_of_nodes())] == [
+        0,
+        1,
+        2,
+        3,
+        4,
+    ]
+
+
+def test_forest_path_to_root(f):
+    assert [forest.path_to_root(f, n) for n in range(f.number_of_nodes())] == [
+        [],
+        [0],
+        [0] * 2,
+        [0] * 3,
+        [0] * 4,
+    ]
+
+
+def test_forest_path_from_root(f):
+    assert [forest.path_from_root(f, n) for n in range(f.number_of_nodes())] == [
+        [],
+        [0],
+        [0] * 2,
+        [0] * 3,
+        [0] * 4,
+    ]
+
+
+def test_forest_dot(f):
+    assert (
+        str(forest.dot(f))
+        == """digraph Forest {
+  rankdir="BT"
+  0  [label="0: ε", shape="box"]
+  1  [label="1: 0", shape="box"]
+  2  [label="2: 00", shape="box"]
+  3  [label="3: 000", shape="box"]
+  4  [label="4: 0000", shape="box"]
+  1 -> 0  [color="#00ff00"]
+  2 -> 1  [color="#00ff00"]
+  3 -> 2  [color="#00ff00"]
+  4 -> 3  [color="#00ff00"]
+}"""
+    )
+    assert (
+        str(forest.dot(f, ["a"]))
+        == """digraph Forest {
+  rankdir="BT"
+  0  [label="0: ε", shape="box"]
+  1  [label="1: a", shape="box"]
+  2  [label="2: aa", shape="box"]
+  3  [label="3: aaa", shape="box"]
+  4  [label="4: aaaa", shape="box"]
+  1 -> 0  [color="#00ff00"]
+  2 -> 1  [color="#00ff00"]
+  3 -> 2  [color="#00ff00"]
+  4 -> 3  [color="#00ff00"]
+}"""
+    )
+
+
+def test_forest_is_root(f):
+    assert [forest.is_root(f, n) for n in range(f.number_of_nodes())] == [
+        True,
+        False,
+        False,
+        False,
+        False,
+    ]
+
+
+def test_forest_max_label(f):
+    assert forest.max_label(f) == 0
+    f = Forest()
+    assert forest.max_label(f) == UNDEFINED