action-digraph-helper: add follow_path

Author: james-d-mitchell

docs/source/api/digraph-helper.rst

@@ -16,7 +16,9 @@ This page contains the documentation for helper function for the class
    is_acyclic
    add_cycle
    topological_sort
+   follow_path
 
 .. autofunction:: is_acyclic
 .. autofunction:: add_cycle 
 .. autofunction:: topological_sort
+.. autofunction:: follow_path

libsemigroups_pybind11/__init__.py

@@ -33,6 +33,7 @@
     wislo,
     number_of_words,
     tril,
+    follow_path,
 )
 
 from .transf import Transf

src/action-digraph.cpp

@@ -799,5 +799,28 @@ namespace libsemigroups {
                          - **source** (int) the source node.
             :Returns: A list of ``int``.
           )pbdoc");
+    m.def("follow_path",
+          &action_digraph_helper::follow_path<size_t>,
+          py::arg("ad"),
+          py::arg("source"),
+          py::arg("path"),
+          R"pbdoc(
+            Find the node that a path starting at a given node leads to.
+
+            :param ad: the ``ActionDigraph`` object to check.
+            :type: ActionDigraph
+            :param first: the starting node.
+            :type: int
+            :param path: the path to follow.
+            :type: List[int]
+
+            :return:
+              An ``int`` corresponding to the node at the end of the path or
+              :py:class:`UNDEFINED` otherwise.
+
+            :raises RuntimeError:
+              if ``source`` is not a node in the digraph or ``path`` contains a
+              value that is not an edge-label.
+          )pbdoc");
   }
 }  // namespace libsemigroups

tests/test_actiondigraph.py

@@ -22,6 +22,7 @@
     topological_sort,
     UNDEFINED,
     POSITIVE_INFINITY,
+    follow_path,
 )
 
 
@@ -835,3 +836,17 @@ def test_010(self):
                 UNDEFINED,
             ],
         )
+
+    def test_follow_path(self):
+        ad = binary_tree(8)
+        self.assertEqual(ad.number_of_nodes(), 255)
+        self.assertEqual(follow_path(ad, 0, [0, 1, 0, 1]), 20)
+        self.assertEqual(follow_path(ad, 0, []), 0)
+        for i, w in enumerate(ad.pislo_iterator(0, 0, 10)):
+            self.assertEqual(follow_path(ad, 0, w), i)
+        self.assertEqual(follow_path(ad, 1, [0] * 10), UNDEFINED)
+
+        with self.assertRaises(RuntimeError):
+            follow_path(ad, 1, [2])
+        with self.assertRaises(RuntimeError):
+            follow_path(ad, 312, [0, 1, 1, 0])