petercorke · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/README.md b/README.md
@@ -34,7 +34,7 @@
 [![powered by Matplotlib](https://img.shields.io/badge/powered_by-Matplotlib-11557c?logo=matplotlib&logoColor=white)](https://matplotlib.org)
 [![Powered by Spatial Maths](https://raw.githubusercontent.com/petercorke/spatialmath-python/master/.github/svg/sm_powered.min.svg)](https://github.com/petercorke/spatialmath-python)
 
-This package provides classes for directed and undirected graphs: vertices
+This pure-Python package provides classes for directed and undirected graphs: vertices
 connected by edges, with edge costs and path planning.  Self-loops and
 parallel edges are permitted.
 
@@ -66,7 +66,7 @@ for route in routes:
     g.add_edge(route[0], route[1], cost=route[2])
 
 # plan a path from Hughenden to Brisbane
-p = g.path_Astar('Hughenden', 'Brisbane')
+p, length, _ = g.path_Astar('Hughenden', 'Brisbane')
 g.plot(block=False) # plot it
 g.highlight_path(p)  # overlay the path
 ```
@@ -85,6 +85,7 @@ Graphs belong to the class `UGraph` or `DGraph` for undirected or directed graph
 - `g.plot()` plots the vertices and edges
 - `g.nc` the number of graph components, 1 if fully connected
 - `g.component(v)` the component that vertex `v` belongs to
+- `g.samecomponent(v1, v2)` predicate for vertices belonging to the same component
 
     ***
 - `g.path_BFS()` breadth-first search
@@ -101,27 +102,26 @@ Vertices are instances of the class `Vertex`, for both undirected and directed g
 - `v.coord` the coordinate vector for embedded graph (optional)
 - `v.name` the name of the vertex (optional)
 - `v.adjacent()` is a list of the adjacent vertices (`neighbours()` and `neighbors()` are the same)
-- `v1.samecomponent(v2)` predicate for vertices belonging to the same component
 
 Vertices can be named and referenced by name.
 
 ### Properties and methods of an edge
 Edges are instances of the class `Edge`.
-Each edge references a pair of vertices, the graph lists all of its edges in `g.edges()`, and the vertices reference the edges.  For a directed graph only the start vertex of an edge references the edge object, whereas for an undirected graph both vertices reference the edge object.
+Each edge references a pair of vertices, the graph lists all of its edges in `g.edges()`, and the vertices reference the edges.
 
 - `e.cost` cost of edge for planning methods
 - `e.next(v)` vertex on edge `e` that is not `v`
 - `e.v1`, `e.v2` the two vertices that define the edge `e`
 
 ## Modifying a graph
 
-- `g.remove(v)` remove vertex `v`
-- `e.remove()` remove edge `e`
+- `g.remove_vertex(v)` or `v.remove()` remove vertex `v`
+- `g.remove_edge(e)` or `e.remove()` remove edge `e`
 
-## Subclasing pgraph classes
+## Subclassing pgraph classes
 
-Consider a user class `Foo` that we would like to connect using a graph _overlay_, ie.
-instances of `Foo` becomes vertices in a graph.
+Consider a user class `Foo` that we would like to connect using a graph _overlay_, i.e.
+instances of `Foo` become vertices in a graph.
 
 - Have it subclass `Vertex`
 - Then place instances of `Foo` into the graph using `add_vertex` and create edges as required
@@ -138,8 +138,8 @@ g.add_vertex(f1)
 g.add_vertex(f2)
 
 f1.connect(f2, cost=3)
-for f in f1.neighbours():
-    # say hi to the neighbours
+for f in f1.adjacent():
+    f.say_hi()  # say hi to the neighbours
 ```
 
 ## MATLAB version

diff --git a/docs/figs/datastructures.ezdraw b/docs/figs/datastructures.ezdraw
diff --git a/docs/figs/datastructures.svg b/docs/figs/datastructures.svg
diff --git a/docs/source/analysis.rst b/docs/source/analysis.rst
@@ -1,67 +1,179 @@
 Graph analysis
 ===============
 
-Querying structure -- counts, adjacent vertices, connectivity, distance -- for directed and
-undirected graphs.
-See :doc:`planning` for
-finding paths between vertices, and :doc:`representations` for matrix/dot forms of the
-whole graph.
+Querying structure -- counts, adjacent vertices, incident edges, degree,
+connectivity, distance -- for directed and undirected graphs.
+See :doc:`planning` for finding paths between vertices, and
+:doc:`representations` for the matrix and dot forms of the whole graph.
+
+A vertex is queried in two complementary ways: by the vertices it is
+*adjacent* to, and by the *edges* incident on it.  For the adjacent vertices
+:meth:`~pgraph.PGraph.Vertex.adjacent` is the canonical name; for a directed
+graph :meth:`~pgraph.PGraph.Vertex.successors` is the same list under its
+directed name, and :meth:`~pgraph.PGraph.Vertex.predecessors` is the vertices
+with an edge *to* the vertex.  The edges are
+:meth:`~pgraph.PGraph.Vertex.out_edges` and
+:meth:`~pgraph.PGraph.Vertex.in_edges`, and
+:meth:`~pgraph.PGraph.Vertex.incidences` pairs each adjacent vertex with the
+edge that leads to it.  :meth:`~pgraph.PGraph.Vertex.edgeto` is the edge to
+one adjacent vertex, the cheapest if there are parallel edges, and
+:meth:`~pgraph.PGraph.Vertex.edges_to` lists all of them.
 
 Graph
 -----
 
+The size and kind of the graph
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. autosummary::
    :nosignatures:
 
    ~pgraph.PGraph.Graph.n
    ~pgraph.PGraph.Graph.ne
    ~pgraph.PGraph.Graph.nc
+   ~pgraph.PGraph.Graph.directed
    ~pgraph.PGraph.Graph.edges
-   ~pgraph.PGraph.Graph.average_degree
+
+Structure and connectivity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
    ~pgraph.PGraph.Graph.iscyclic
-   ~pgraph.PGraph.Graph.connectivity
    ~pgraph.PGraph.Graph.component
    ~pgraph.PGraph.Graph.samecomponent
+   ~pgraph.PGraph.Graph.connectivity
+   ~pgraph.PGraph.Graph.average_degree
+
+Geometry and consistency
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
    ~pgraph.PGraph.Graph.closest
+   ~pgraph.PGraph.Graph.validate
+
+The matrices of a graph (:meth:`~pgraph.PGraph.Graph.adjacency`,
+:meth:`~pgraph.PGraph.Graph.degree`, :meth:`~pgraph.PGraph.Graph.incidence`,
+:meth:`~pgraph.PGraph.Graph.laplacian`, :meth:`~pgraph.PGraph.Graph.distance`)
+are in :doc:`representations`.
 
 Vertex
 ------
 
+Identity and position
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
+   ~pgraph.PGraph.Vertex.name
+   ~pgraph.PGraph.Vertex.label
+   ~pgraph.PGraph.Vertex.x
+   ~pgraph.PGraph.Vertex.y
+   ~pgraph.PGraph.Vertex.z
+
+Adjacent vertices
+^^^^^^^^^^^^^^^^^^
+
 .. autosummary::
    :nosignatures:
 
-   ~pgraph.PGraph.Vertex.edges
    ~pgraph.PGraph.Vertex.adjacent
    ~pgraph.PGraph.Vertex.isadjacent
+   ~pgraph.PGraph.Vertex.successors
+   ~pgraph.PGraph.Vertex.predecessors
+
+.. note:: ``neighbours()`` and ``neighbors()`` are the same method as
+   :meth:`~pgraph.PGraph.Vertex.adjacent`, and ``isneighbour()`` and
+   ``isneighbor()`` the same as :meth:`~pgraph.PGraph.Vertex.isadjacent`.
+   They are spelling variants, not deprecated.
+
+Incident edges
+^^^^^^^^^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
+   ~pgraph.PGraph.Vertex.edges
+   ~pgraph.PGraph.Vertex.out_edges
+   ~pgraph.PGraph.Vertex.in_edges
    ~pgraph.PGraph.Vertex.incidences
+   ~pgraph.PGraph.Vertex.edgeto
+   ~pgraph.PGraph.Vertex.edges_to
+
+Degree
+^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
    ~pgraph.PGraph.Vertex.degree
-   ~pgraph.PGraph.Vertex.heuristic_distance
+   ~pgraph.PGraph.Vertex.in_degree
+   ~pgraph.PGraph.Vertex.out_degree
+
+Distance
+^^^^^^^^^
+
+.. autosummary::
+   :nosignatures:
+
    ~pgraph.PGraph.Vertex.distance
-   ~pgraph.PGraph.Vertex.x
-   ~pgraph.PGraph.Vertex.y
-   ~pgraph.PGraph.Vertex.z
+   ~pgraph.PGraph.Vertex.heuristic_distance
+   ~pgraph.PGraph.Vertex.closest
+
+Edge
+----
+
+An :class:`~pgraph.PGraph.Edge` is described in full on :doc:`edges_vertices`.  The
+attributes and methods used to query one are
+
+.. autosummary::
+   :nosignatures:
+
+   ~pgraph.PGraph.Edge.v1
+   ~pgraph.PGraph.Edge.v2
+   ~pgraph.PGraph.Edge.endpoints
+   ~pgraph.PGraph.Edge.next
+
+and every edge also has ``cost`` and ``data`` attributes.
 
 Details
 -------
 
 .. autoproperty:: pgraph.PGraph.Graph.n
 .. autoproperty:: pgraph.PGraph.Graph.ne
 .. autoproperty:: pgraph.PGraph.Graph.nc
+.. autoproperty:: pgraph.PGraph.Graph.directed
 .. automethod:: pgraph.PGraph.Graph.edges
-.. automethod:: pgraph.PGraph.Graph.average_degree
 .. automethod:: pgraph.PGraph.Graph.iscyclic
-.. automethod:: pgraph.PGraph.Graph.connectivity
 .. automethod:: pgraph.PGraph.Graph.component
 .. automethod:: pgraph.PGraph.Graph.samecomponent
+.. automethod:: pgraph.PGraph.Graph.connectivity
+.. automethod:: pgraph.PGraph.Graph.average_degree
 .. automethod:: pgraph.PGraph.Graph.closest
+.. automethod:: pgraph.PGraph.Graph.validate
 
-.. automethod:: pgraph.PGraph.Vertex.edges
+.. autoproperty:: pgraph.PGraph.Vertex.name
+.. autoproperty:: pgraph.PGraph.Vertex.label
+.. autoproperty:: pgraph.PGraph.Vertex.x
+.. autoproperty:: pgraph.PGraph.Vertex.y
+.. autoproperty:: pgraph.PGraph.Vertex.z
 .. automethod:: pgraph.PGraph.Vertex.adjacent
 .. automethod:: pgraph.PGraph.Vertex.isadjacent
+.. automethod:: pgraph.PGraph.Vertex.successors
+.. automethod:: pgraph.PGraph.Vertex.predecessors
+.. automethod:: pgraph.PGraph.Vertex.edges
+.. automethod:: pgraph.PGraph.Vertex.out_edges
+.. automethod:: pgraph.PGraph.Vertex.in_edges
 .. automethod:: pgraph.PGraph.Vertex.incidences
+.. automethod:: pgraph.PGraph.Vertex.edgeto
+.. automethod:: pgraph.PGraph.Vertex.edges_to
 .. autoproperty:: pgraph.PGraph.Vertex.degree
-.. automethod:: pgraph.PGraph.Vertex.heuristic_distance
+.. autoproperty:: pgraph.PGraph.Vertex.in_degree
+.. autoproperty:: pgraph.PGraph.Vertex.out_degree
 .. automethod:: pgraph.PGraph.Vertex.distance
-.. autoproperty:: pgraph.PGraph.Vertex.x
-.. autoproperty:: pgraph.PGraph.Vertex.y
-.. autoproperty:: pgraph.PGraph.Vertex.z
+.. automethod:: pgraph.PGraph.Vertex.heuristic_distance
+.. automethod:: pgraph.PGraph.Vertex.closest
diff --git a/docs/source/common.rst b/docs/source/common.rst
@@ -4,26 +4,22 @@ Common methods
 The package supports both directed (prefix ``D``) and undirected graphs (prefix ``U``), and the classes for these
 share a common interface. 
 
-The graph classes represent a single graph, either directed or undirected, and they share :class:`Graph`:
+The graph classes represent a single graph, either directed or undirected, and they share :class:`~pgraph.PGraph.Graph`:
 
 .. inheritance-diagram:: pgraph.PGraph.UGraph pgraph.PGraph.DGraph
    :parts: 1
    :private-bases:
    :top-classes: pgraph.PGraph.Graph
 
-The vertices of both kinds of graph are :class:`Vertex` objects: a vertex has
-no direction of its own, the graph it belongs to decides how an edge is
-recorded at its ends.
+The vertices of both kinds of graph are :class:`~pgraph.PGraph.Vertex` objects.  A vertex has
+no direction of its own: the graph it belongs to decides how an edge is recorded
+in the edge lists of its vertices.
+Edges are represented by the :class:`~pgraph.PGraph.Edge` class, which is used by both directed and undirected graphs.
 
 The graph classes share almost their entire interface, defined once on their
-common base class :class:`Graph`. This section documents that shared interface
-by task rather than by class; see :doc:`construction` for the :class:`DGraph`
-and :class:`UGraph` classes and :doc:`edges_vertices` for vertices and edges.
-
-Edges are represented by the :class:`Edge` class, which is used by both directed and undirected graphs.
-
-.. inheritance-diagram:: pgraph.PGraph.Edge
-   :parts: 1
+common base class :class:`~pgraph.PGraph.Graph`. This section documents that shared interface
+by task rather than by class; see :doc:`construction` for the :class:`~pgraph.PGraph.DGraph`
+and :class:`~pgraph.PGraph.UGraph` classes and :doc:`edges_vertices` for vertices and edges.
 
 
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -45,6 +45,7 @@
 ]
 
 autosummary_generate = True
+add_module_names = False  # show Graph.n, not pgraph.PGraph.Graph.n
 
 # copybutton configuration: strip >>> and ... prompts when copying
 copybutton_prompt_text = r">>> |\.\.\. "

diff --git a/docs/source/construction.rst b/docs/source/construction.rst
@@ -1,15 +1,17 @@
 Construction and basic usage
 =============================
 
-There are a number of ways to build a :class:`DGraph`/:class:`UGraph` (a plain constructor, or from
-a dictionary/adjacency matrix).
+There are a number of ways to build a :class:`~pgraph.PGraph.UGraph` (undirected) or :class:`~pgraph.PGraph.DGraph` (directed): a plain
+constructor, or from a dictionary or an adjacency matrix.  :class:`~pgraph.PGraph.Graph` is their common base class,
+used in type hints, and ``Graph(directed=flag)`` chooses the kind from a value.
 
 See :doc:`policy` for the rules around constructing vertices/edges
 standalone, independent of a graph.
 
 .. autosummary::
    :nosignatures:
 
+   ~pgraph.PGraph.Graph
    ~pgraph.PGraph.DGraph
    ~pgraph.PGraph.UGraph
    ~pgraph.PGraph.Graph.Dict
@@ -36,4 +38,9 @@ Inherited methods for all graph types
    :members: copy, vertex_copy, metric, heuristic, show, vertex_class, edge_class
    :special-members: __init__, __str__, __repr__, __getitem__, __iter__, __contains__
 
+Copying a vertex
+----------------
+
+.. automethod:: pgraph.PGraph.Vertex.copy
+
 
diff --git a/docs/source/edge.rst b/docs/source/edge.rst