Merge branch 'main' into perf/path-planners

Author: petercorke

docs/source/edges_vertices.rst

@@ -15,6 +15,142 @@ For the directed case, each vertex maintains two edge lists: a list of outgoing
 The graph class provides methods for adding and removing vertices and edges (see :doc:`modification`)
 and for querying its structure (see :doc:`analysis`).
 
+What a vertex holds
+~~~~~~~~~~~~~~~~~~~~
+
+
+Each vertex has **two** private edge lists, plus a back-pointer to its graph.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 55 30
+
+   * - Attribute
+     - For undirected graphs
+     - For directed graphs
+   * - ``_edgelist``
+     - the edges *incident on* it
+     - the edges *leaving* it
+   * - ``_inlist``
+     - empty
+     - the edges *entering* it
+   * - ``_graph``
+     - the graph it belongs to (``None`` if standalone)
+     - the graph it belongs to (``None`` if standalone)
+
+Every list entry is a reference to the same :class:`~pgraph.PGraph.Edge` class object, and
+there is exactly one edge object for each edge in the graph.
+
+* **Undirected:** one list does everything, since an undirected edge is both "out"
+  and "in".  That is also why a loop is stored twice, once for each end, and why it
+  counts 2 towards ``degree``.
+* **Directed:** the two lists are the out-list and the in-list.  A loop sits once in
+  each, so ``degree`` (in + out) is 2 there too.
+
+An example, as lists
+~~~~~~~~~~~~~~~~~~~~~~
+
+For these simple graphs
+
+.. plot::
+   :include-source: no
+   :alt: the example graph drawn as an undirected and as a directed graph: two parallel edges e1 and e2 from a to b, e3 from b to c and a loop e4 on c
+
+   import matplotlib.pyplot as plt
+   from matplotlib.patches import Circle, FancyArrowPatch
+
+   pos = {"a": (0.0, 0.0), "b": (2.0, 0.0), "c": (4.0, 0.0)}
+   # (name, from, to, curvature, label offset): e1 and e2 are parallel, drawn
+   # as two arcs curving to either side
+   edges = [("e1", "a", "b", 0.3, (0, 0.5)), ("e2", "a", "b", -0.3, (0, -0.5)),
+            ("e3", "b", "c", 0, (0, 0.18))]
+
+   fig, axs = plt.subplots(1, 2, figsize=(9, 2.3))
+   for ax, is_directed, title in zip(axs, (False, True), ("UGraph", "DGraph")):
+       style = "-|>" if is_directed else "-"
+       for name, p, q, rad, (dx, dy) in edges:
+           ax.add_patch(FancyArrowPatch(pos[p], pos[q], arrowstyle=style, mutation_scale=16,
+                                        connectionstyle=f"arc3,rad={rad}", shrinkA=15, shrinkB=15,
+                                        color="0.15", lw=1.6))
+           mx = (pos[p][0] + pos[q][0]) / 2 + dx
+           my = (pos[p][1] + pos[q][1]) / 2 + dy
+           ax.text(mx, my, name, ha="center", va="center", fontsize=10, color="0.15")
+       x, y = pos["c"]  # e4: a loop, an edge from c to itself
+       ax.add_patch(FancyArrowPatch((x - 0.15, y + 0.15), (x + 0.15, y + 0.15), arrowstyle=style,
+                                    mutation_scale=16, connectionstyle="arc3,rad=-1.8",
+                                    color="0.15", lw=1.6))
+       ax.text(x, y + 0.62, "e4", ha="center", va="center", fontsize=10, color="0.15")
+       for name, (x, y) in pos.items():
+           ax.add_patch(Circle((x, y), 0.2, fc="#1f77b4", ec="none", zorder=3))
+           ax.text(x, y, name, ha="center", va="center", color="white", fontsize=11, zorder=4)
+       ax.set_xlim(-0.6, 4.6)
+       ax.set_ylim(-0.8, 0.95)
+       ax.set_aspect("equal")
+       ax.axis("off")
+       ax.set_title(title, fontsize=11)
+   fig.tight_layout()
+
+The vertices ``a``, ``b`` and ``c`` and edges ``e1`` and ``e2`` are added in that order.
+The resulting vertex lists are
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 30 30 30
+
+   * - Vertex name
+     - ``UGraph`` ``_edgelist``
+     - ``DGraph`` ``_edgelist``
+     - ``DGraph`` ``_inlist``
+   * - ``a``
+     - ``[e1, e2]``
+     - ``[e1, e2]``
+     - ``[]``
+   * - ``b``
+     - ``[e1, e2, e3]``
+     - ``[e3]``
+     - ``[e1, e2]``
+   * - ``c``
+     - ``[e3, e4, e4]``
+     - ``[e4]``
+     - ``[e3, e4]``
+
+The graph also keeps **every edge once** in ``graph._edges`` (an insertion-ordered
+dict, so ``[e1, e2, e3, e4]``).
+
+The public view of those lists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Method
+     - Returns for ``UGraph``
+     - Returns for ``DGraph``
+   * - ``edges()``, ``out_edges()``
+     - a copy of ``_edgelist``
+     - a copy of ``_edgelist`` 
+   * - ``in_edges()``
+     - a copy of ``_edgelist``
+     - a copy of ``_inlist`` 
+   * - ``degree``
+     - ``len(_edgelist)``
+     - ``len(_edgelist) + len(_inlist)``
+   * - ``in_degree``
+     - ``len(_edgelist)``
+     - ``len(_inlist)``
+   * - ``out_degree``
+     - ``len(_edgelist)``
+     - ``len(_edgelist)``
+   * - ``adjacent()``
+     - the far end of each edge in ``_edgelist``
+     - the far end of each edge in ``_edgelist``
+   * - ``incidences()``
+     - ``adjacent()`` paired with ``out_edges()``
+     - ``adjacent()`` paired with ``out_edges()``
+
+All are returned in the order the edges were connected.
+
 
 Working with vertices and edges directly
 -----------------------------------------

src/pgraph/PGraph.py

@@ -290,6 +290,8 @@ def __str__(self) -> str:
         :return: one-line summary of vertex/edge/component counts
         :rtype: str
 
+        Counts of 1,000 or more have thousands separators.
+
         .. runblock:: pycon
 
             >>> from pgraph import UGraph
@@ -303,7 +305,7 @@ def __str__(self) -> str:
 
         :seealso: :meth:`show`
         """
-        s = f"{self.__class__.__name__}: {self.n} {'vertex' if self.n==1 else 'vertices'}, {self.ne} edge{'s'[:self.ne^1]}, {self.nc} component{'s'[:self.nc^1]}"
+        s = f"{self.__class__.__name__}: {self.n:,} {'vertex' if self.n==1 else 'vertices'}, {self.ne:,} edge{'s'[:self.ne^1]}, {self.nc:,} component{'s'[:self.nc^1]}"
         return s
 
     def __repr__(self) -> str:

tests/test_components.py

@@ -17,6 +17,7 @@
 
 import signal
 import unittest
+import unittest.mock
 from contextlib import contextmanager
 
 import numpy as np
@@ -197,6 +198,41 @@ def test_samecomponent(self):
         self.assertFalse(g.samecomponent(g[1], g[2]))
 
 
+class TestNotRecomputed(unittest.TestCase):
+    """The traversal runs once, and again only after the graph has changed"""
+
+    def traversals(self, g, ask):
+        calls = []
+        original = type(g[0]).adjacent
+
+        def spy(vertex, *args, **kwargs):
+            calls.append(vertex)
+            return original(vertex, *args, **kwargs)
+
+        with unittest.mock.patch.object(type(g[0]), "adjacent", spy):
+            ask()
+        return len(calls)
+
+    def check(self, cls):
+        g = build(cls, 4, [(0, 1), (2, 3)])
+        ask = lambda: (g.nc, g.component(g[0]), g.samecomponent(g[0], g[1]), g[2].label)
+
+        self.assertGreater(self.traversals(g, ask), 0)  # first time: does the work
+        self.assertEqual(self.traversals(g, ask), 0)  # nothing changed: none
+        self.assertEqual(self.traversals(g, ask), 0)
+
+        g.add_edge(g[1], g[2])  # a change: once more, and the answer is new
+        self.assertGreater(self.traversals(g, ask), 0)
+        self.assertEqual(g.nc, 1)
+        self.assertEqual(self.traversals(g, ask), 0)
+
+    def test_undirected(self):
+        self.check(UGraph)
+
+    def test_directed(self):
+        self.check(DGraph)
+
+
 class TestUndirectedComponents(_Components, unittest.TestCase):
     cls = UGraph
 

tests/test_export.py

@@ -408,6 +408,8 @@ def test_dotfile_prints_to_console(self):
             g.dotfile()
         self.assertEqual(out.getvalue(), g.export(format="dot", costs=False))
         self.assertNotIn("label=", out.getvalue())
+        # writing to the console must leave it usable (0.6.5 closed it)
+        self.assertFalse(out.closed)
 
     def test_dotfile_to_path_and_stream(self):
         g, *_ = line_graph(UGraph)

tests/test_graph.py

@@ -3,7 +3,7 @@
 import numpy as np
 import numpy.testing as nt
 
-from pgraph import *
+from pgraph import DGraph, Edge, UGraph, Vertex
 
 class TestUGraph(unittest.TestCase):
 
@@ -51,6 +51,21 @@ def test_str(self):
         self.assertEqual(len(lines), 3)  # class-name header + one line per vertex
         self.assertEqual(lines[0], "DGraph:")
 
+
+    def test_str_has_thousands_separators(self):
+        # counts of 1,000 or more are easier to read with separators
+        g = UGraph()
+        vs = [g.add_vertex() for _ in range(1001)]
+        self.assertEqual(str(g), "UGraph: 1,001 vertices, 0 edges, 1,001 components")
+        for a, b in zip(vs, vs[1:]):
+            g.add_edge(a, b)
+        self.assertEqual(str(g), "UGraph: 1,001 vertices, 1,000 edges, 1 component")
+        # below a thousand it is as before
+        h = UGraph()
+        for _ in range(999):
+            h.add_vertex()
+        self.assertEqual(str(h), "UGraph: 999 vertices, 0 edges, 999 components")
+
     def test_attr(self):
 
         g = UGraph()
@@ -298,6 +313,24 @@ def test_edge_vertices_deprecated(self):
             verts = e.vertices()
         self.assertEqual(verts, e.endpoints)
 
+    def test_planners_validate_start_and_goal(self):
+        # 0.6.5 checked the type of the start twice and never the goal
+        g = UGraph()
+        a = g.add_vertex(coord=[0, 0], name="a")
+        b = g.add_vertex(coord=[1, 0], name="b")
+        g.add_edge(a, b)
+
+        for planner in (g.path_BFS, g.path_UCS, g.path_Astar):
+            with self.subTest(planner=planner.__name__):
+                with self.assertRaises(TypeError):
+                    planner(a, 42)
+                with self.assertRaises(TypeError):
+                    planner(42, b)
+                with self.assertRaises(KeyError):
+                    planner(a, "no such vertex")
+                # by name and by reference both work
+                self.assertEqual(planner("a", "b")[0], [a, b])
+
     def test_edge3(self):
 
         g = UGraph()