Skip to content

Commit 6e2e81a

Browse files
authored
Merge pull request #49 from petercorke/docs/unified-vertex-pass
docs: second documentation pass for the single Vertex class
2 parents c64ffe1 + 025df3c commit 6e2e81a

17 files changed

Lines changed: 14155 additions & 6493 deletions

‎README.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
[![powered by Matplotlib](https://img.shields.io/badge/powered_by-Matplotlib-11557c?logo=matplotlib&logoColor=white)](https://matplotlib.org)
3535
[![Powered by Spatial Maths](https://raw.githubusercontent.com/petercorke/spatialmath-python/master/.github/svg/sm_powered.min.svg)](https://github.com/petercorke/spatialmath-python)
3636

37-
This package provides classes for directed and undirected graphs: vertices
37+
This pure-Python package provides classes for directed and undirected graphs: vertices
3838
connected by edges, with edge costs and path planning. Self-loops and
3939
parallel edges are permitted.
4040

@@ -66,7 +66,7 @@ for route in routes:
6666
g.add_edge(route[0], route[1], cost=route[2])
6767
6868
# plan a path from Hughenden to Brisbane
69-
p = g.path_Astar('Hughenden', 'Brisbane')
69+
p, length, _ = g.path_Astar('Hughenden', 'Brisbane')
7070
g.plot(block=False) # plot it
7171
g.highlight_path(p) # overlay the path
7272
```
@@ -85,6 +85,7 @@ Graphs belong to the class `UGraph` or `DGraph` for undirected or directed graph
8585
- `g.plot()` plots the vertices and edges
8686
- `g.nc` the number of graph components, 1 if fully connected
8787
- `g.component(v)` the component that vertex `v` belongs to
88+
- `g.samecomponent(v1, v2)` predicate for vertices belonging to the same component
8889

8990
***
9091
- `g.path_BFS()` breadth-first search
@@ -101,27 +102,26 @@ Vertices are instances of the class `Vertex`, for both undirected and directed g
101102
- `v.coord` the coordinate vector for embedded graph (optional)
102103
- `v.name` the name of the vertex (optional)
103104
- `v.adjacent()` is a list of the adjacent vertices (`neighbours()` and `neighbors()` are the same)
104-
- `v1.samecomponent(v2)` predicate for vertices belonging to the same component
105105

106106
Vertices can be named and referenced by name.
107107

108108
### Properties and methods of an edge
109109
Edges are instances of the class `Edge`.
110-
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.
110+
Each edge references a pair of vertices, the graph lists all of its edges in `g.edges()`, and the vertices reference the edges.
111111

112112
- `e.cost` cost of edge for planning methods
113113
- `e.next(v)` vertex on edge `e` that is not `v`
114114
- `e.v1`, `e.v2` the two vertices that define the edge `e`
115115

116116
## Modifying a graph
117117

118-
- `g.remove(v)` remove vertex `v`
119-
- `e.remove()` remove edge `e`
118+
- `g.remove_vertex(v)` or `v.remove()` remove vertex `v`
119+
- `g.remove_edge(e)` or `e.remove()` remove edge `e`
120120

121-
## Subclasing pgraph classes
121+
## Subclassing pgraph classes
122122

123-
Consider a user class `Foo` that we would like to connect using a graph _overlay_, ie.
124-
instances of `Foo` becomes vertices in a graph.
123+
Consider a user class `Foo` that we would like to connect using a graph _overlay_, i.e.
124+
instances of `Foo` become vertices in a graph.
125125

126126
- Have it subclass `Vertex`
127127
- Then place instances of `Foo` into the graph using `add_vertex` and create edges as required
@@ -138,8 +138,8 @@ g.add_vertex(f1)
138138
g.add_vertex(f2)
139139
140140
f1.connect(f2, cost=3)
141-
for f in f1.neighbours():
142-
# say hi to the neighbours
141+
for f in f1.adjacent():
142+
f.say_hi() # say hi to the neighbours
143143
```
144144

145145
## MATLAB version

‎docs/figs/datastructures.ezdraw‎

Lines changed: 1105 additions & 837 deletions
Large diffs are not rendered by default.

‎docs/figs/datastructures.svg‎

Lines changed: 12689 additions & 5532 deletions
Loading

‎docs/source/analysis.rst‎

Lines changed: 131 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,179 @@
11
Graph analysis
22
===============
33

4-
Querying structure -- counts, adjacent vertices, connectivity, distance -- for directed and
5-
undirected graphs.
6-
See :doc:`planning` for
7-
finding paths between vertices, and :doc:`representations` for matrix/dot forms of the
8-
whole graph.
4+
Querying structure -- counts, adjacent vertices, incident edges, degree,
5+
connectivity, distance -- for directed and undirected graphs.
6+
See :doc:`planning` for finding paths between vertices, and
7+
:doc:`representations` for the matrix and dot forms of the whole graph.
8+
9+
A vertex is queried in two complementary ways: by the vertices it is
10+
*adjacent* to, and by the *edges* incident on it. For the adjacent vertices
11+
:meth:`~pgraph.PGraph.Vertex.adjacent` is the canonical name; for a directed
12+
graph :meth:`~pgraph.PGraph.Vertex.successors` is the same list under its
13+
directed name, and :meth:`~pgraph.PGraph.Vertex.predecessors` is the vertices
14+
with an edge *to* the vertex. The edges are
15+
:meth:`~pgraph.PGraph.Vertex.out_edges` and
16+
:meth:`~pgraph.PGraph.Vertex.in_edges`, and
17+
:meth:`~pgraph.PGraph.Vertex.incidences` pairs each adjacent vertex with the
18+
edge that leads to it. :meth:`~pgraph.PGraph.Vertex.edgeto` is the edge to
19+
one adjacent vertex, the cheapest if there are parallel edges, and
20+
:meth:`~pgraph.PGraph.Vertex.edges_to` lists all of them.
921

1022
Graph
1123
-----
1224

25+
The size and kind of the graph
26+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
27+
1328
.. autosummary::
1429
:nosignatures:
1530

1631
~pgraph.PGraph.Graph.n
1732
~pgraph.PGraph.Graph.ne
1833
~pgraph.PGraph.Graph.nc
34+
~pgraph.PGraph.Graph.directed
1935
~pgraph.PGraph.Graph.edges
20-
~pgraph.PGraph.Graph.average_degree
36+
37+
Structure and connectivity
38+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
39+
40+
.. autosummary::
41+
:nosignatures:
42+
2143
~pgraph.PGraph.Graph.iscyclic
22-
~pgraph.PGraph.Graph.connectivity
2344
~pgraph.PGraph.Graph.component
2445
~pgraph.PGraph.Graph.samecomponent
46+
~pgraph.PGraph.Graph.connectivity
47+
~pgraph.PGraph.Graph.average_degree
48+
49+
Geometry and consistency
50+
^^^^^^^^^^^^^^^^^^^^^^^^^
51+
52+
.. autosummary::
53+
:nosignatures:
54+
2555
~pgraph.PGraph.Graph.closest
56+
~pgraph.PGraph.Graph.validate
57+
58+
The matrices of a graph (:meth:`~pgraph.PGraph.Graph.adjacency`,
59+
:meth:`~pgraph.PGraph.Graph.degree`, :meth:`~pgraph.PGraph.Graph.incidence`,
60+
:meth:`~pgraph.PGraph.Graph.laplacian`, :meth:`~pgraph.PGraph.Graph.distance`)
61+
are in :doc:`representations`.
2662

2763
Vertex
2864
------
2965

66+
Identity and position
67+
^^^^^^^^^^^^^^^^^^^^^^
68+
69+
.. autosummary::
70+
:nosignatures:
71+
72+
~pgraph.PGraph.Vertex.name
73+
~pgraph.PGraph.Vertex.label
74+
~pgraph.PGraph.Vertex.x
75+
~pgraph.PGraph.Vertex.y
76+
~pgraph.PGraph.Vertex.z
77+
78+
Adjacent vertices
79+
^^^^^^^^^^^^^^^^^^
80+
3081
.. autosummary::
3182
:nosignatures:
3283

33-
~pgraph.PGraph.Vertex.edges
3484
~pgraph.PGraph.Vertex.adjacent
3585
~pgraph.PGraph.Vertex.isadjacent
86+
~pgraph.PGraph.Vertex.successors
87+
~pgraph.PGraph.Vertex.predecessors
88+
89+
.. note:: ``neighbours()`` and ``neighbors()`` are the same method as
90+
:meth:`~pgraph.PGraph.Vertex.adjacent`, and ``isneighbour()`` and
91+
``isneighbor()`` the same as :meth:`~pgraph.PGraph.Vertex.isadjacent`.
92+
They are spelling variants, not deprecated.
93+
94+
Incident edges
95+
^^^^^^^^^^^^^^^
96+
97+
.. autosummary::
98+
:nosignatures:
99+
100+
~pgraph.PGraph.Vertex.edges
101+
~pgraph.PGraph.Vertex.out_edges
102+
~pgraph.PGraph.Vertex.in_edges
36103
~pgraph.PGraph.Vertex.incidences
104+
~pgraph.PGraph.Vertex.edgeto
105+
~pgraph.PGraph.Vertex.edges_to
106+
107+
Degree
108+
^^^^^^^
109+
110+
.. autosummary::
111+
:nosignatures:
112+
37113
~pgraph.PGraph.Vertex.degree
38-
~pgraph.PGraph.Vertex.heuristic_distance
114+
~pgraph.PGraph.Vertex.in_degree
115+
~pgraph.PGraph.Vertex.out_degree
116+
117+
Distance
118+
^^^^^^^^^
119+
120+
.. autosummary::
121+
:nosignatures:
122+
39123
~pgraph.PGraph.Vertex.distance
40-
~pgraph.PGraph.Vertex.x
41-
~pgraph.PGraph.Vertex.y
42-
~pgraph.PGraph.Vertex.z
124+
~pgraph.PGraph.Vertex.heuristic_distance
125+
~pgraph.PGraph.Vertex.closest
126+
127+
Edge
128+
----
129+
130+
An :class:`~pgraph.PGraph.Edge` is described in full on :doc:`edges_vertices`. The
131+
attributes and methods used to query one are
132+
133+
.. autosummary::
134+
:nosignatures:
135+
136+
~pgraph.PGraph.Edge.v1
137+
~pgraph.PGraph.Edge.v2
138+
~pgraph.PGraph.Edge.endpoints
139+
~pgraph.PGraph.Edge.next
140+
141+
and every edge also has ``cost`` and ``data`` attributes.
43142

44143
Details
45144
-------
46145

47146
.. autoproperty:: pgraph.PGraph.Graph.n
48147
.. autoproperty:: pgraph.PGraph.Graph.ne
49148
.. autoproperty:: pgraph.PGraph.Graph.nc
149+
.. autoproperty:: pgraph.PGraph.Graph.directed
50150
.. automethod:: pgraph.PGraph.Graph.edges
51-
.. automethod:: pgraph.PGraph.Graph.average_degree
52151
.. automethod:: pgraph.PGraph.Graph.iscyclic
53-
.. automethod:: pgraph.PGraph.Graph.connectivity
54152
.. automethod:: pgraph.PGraph.Graph.component
55153
.. automethod:: pgraph.PGraph.Graph.samecomponent
154+
.. automethod:: pgraph.PGraph.Graph.connectivity
155+
.. automethod:: pgraph.PGraph.Graph.average_degree
56156
.. automethod:: pgraph.PGraph.Graph.closest
157+
.. automethod:: pgraph.PGraph.Graph.validate
57158

58-
.. automethod:: pgraph.PGraph.Vertex.edges
159+
.. autoproperty:: pgraph.PGraph.Vertex.name
160+
.. autoproperty:: pgraph.PGraph.Vertex.label
161+
.. autoproperty:: pgraph.PGraph.Vertex.x
162+
.. autoproperty:: pgraph.PGraph.Vertex.y
163+
.. autoproperty:: pgraph.PGraph.Vertex.z
59164
.. automethod:: pgraph.PGraph.Vertex.adjacent
60165
.. automethod:: pgraph.PGraph.Vertex.isadjacent
166+
.. automethod:: pgraph.PGraph.Vertex.successors
167+
.. automethod:: pgraph.PGraph.Vertex.predecessors
168+
.. automethod:: pgraph.PGraph.Vertex.edges
169+
.. automethod:: pgraph.PGraph.Vertex.out_edges
170+
.. automethod:: pgraph.PGraph.Vertex.in_edges
61171
.. automethod:: pgraph.PGraph.Vertex.incidences
172+
.. automethod:: pgraph.PGraph.Vertex.edgeto
173+
.. automethod:: pgraph.PGraph.Vertex.edges_to
62174
.. autoproperty:: pgraph.PGraph.Vertex.degree
63-
.. automethod:: pgraph.PGraph.Vertex.heuristic_distance
175+
.. autoproperty:: pgraph.PGraph.Vertex.in_degree
176+
.. autoproperty:: pgraph.PGraph.Vertex.out_degree
64177
.. automethod:: pgraph.PGraph.Vertex.distance
65-
.. autoproperty:: pgraph.PGraph.Vertex.x
66-
.. autoproperty:: pgraph.PGraph.Vertex.y
67-
.. autoproperty:: pgraph.PGraph.Vertex.z
178+
.. automethod:: pgraph.PGraph.Vertex.heuristic_distance
179+
.. automethod:: pgraph.PGraph.Vertex.closest

‎docs/source/common.rst‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,22 @@ Common methods
44
The package supports both directed (prefix ``D``) and undirected graphs (prefix ``U``), and the classes for these
55
share a common interface.
66

7-
The graph classes represent a single graph, either directed or undirected, and they share :class:`Graph`:
7+
The graph classes represent a single graph, either directed or undirected, and they share :class:`~pgraph.PGraph.Graph`:
88

99
.. inheritance-diagram:: pgraph.PGraph.UGraph pgraph.PGraph.DGraph
1010
:parts: 1
1111
:private-bases:
1212
:top-classes: pgraph.PGraph.Graph
1313

14-
The vertices of both kinds of graph are :class:`Vertex` objects: a vertex has
15-
no direction of its own, the graph it belongs to decides how an edge is
16-
recorded at its ends.
14+
The vertices of both kinds of graph are :class:`~pgraph.PGraph.Vertex` objects. A vertex has
15+
no direction of its own: the graph it belongs to decides how an edge is recorded
16+
in the edge lists of its vertices.
17+
Edges are represented by the :class:`~pgraph.PGraph.Edge` class, which is used by both directed and undirected graphs.
1718

1819
The graph classes share almost their entire interface, defined once on their
19-
common base class :class:`Graph`. This section documents that shared interface
20-
by task rather than by class; see :doc:`construction` for the :class:`DGraph`
21-
and :class:`UGraph` classes and :doc:`edges_vertices` for vertices and edges.
22-
23-
Edges are represented by the :class:`Edge` class, which is used by both directed and undirected graphs.
24-
25-
.. inheritance-diagram:: pgraph.PGraph.Edge
26-
:parts: 1
20+
common base class :class:`~pgraph.PGraph.Graph`. This section documents that shared interface
21+
by task rather than by class; see :doc:`construction` for the :class:`~pgraph.PGraph.DGraph`
22+
and :class:`~pgraph.PGraph.UGraph` classes and :doc:`edges_vertices` for vertices and edges.
2723

2824

2925

‎docs/source/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@
4545
]
4646

4747
autosummary_generate = True
48+
add_module_names = False # show Graph.n, not pgraph.PGraph.Graph.n
4849

4950
# copybutton configuration: strip >>> and ... prompts when copying
5051
copybutton_prompt_text = r">>> |\.\.\. "

‎docs/source/construction.rst‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
Construction and basic usage
22
=============================
33

4-
There are a number of ways to build a :class:`DGraph`/:class:`UGraph` (a plain constructor, or from
5-
a dictionary/adjacency matrix).
4+
There are a number of ways to build a :class:`~pgraph.PGraph.UGraph` (undirected) or :class:`~pgraph.PGraph.DGraph` (directed): a plain
5+
constructor, or from a dictionary or an adjacency matrix. :class:`~pgraph.PGraph.Graph` is their common base class,
6+
used in type hints, and ``Graph(directed=flag)`` chooses the kind from a value.
67

78
See :doc:`policy` for the rules around constructing vertices/edges
89
standalone, independent of a graph.
910

1011
.. autosummary::
1112
:nosignatures:
1213

14+
~pgraph.PGraph.Graph
1315
~pgraph.PGraph.DGraph
1416
~pgraph.PGraph.UGraph
1517
~pgraph.PGraph.Graph.Dict
@@ -36,4 +38,9 @@ Inherited methods for all graph types
3638
:members: copy, vertex_copy, metric, heuristic, show, vertex_class, edge_class
3739
:special-members: __init__, __str__, __repr__, __getitem__, __iter__, __contains__
3840

41+
Copying a vertex
42+
----------------
43+
44+
.. automethod:: pgraph.PGraph.Vertex.copy
45+
3946

‎docs/source/edge.rst‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

0 commit comments

Comments
 (0)