Skip to content

Commit 9fe9d61

Browse files
authored
Merge pull request #44 from petercorke/feat/graph-pickle
feat: a graph can be pickled, and copy() works for graphs of any size
2 parents b63389f + 9059faa commit 9fe9d61

3 files changed

Lines changed: 443 additions & 27 deletions

File tree

‎src/pgraph/PGraph.py‎

Lines changed: 174 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,36 @@
1616
from spatialmath.base.graphics import axes_logic
1717

1818

19+
def _L1(v: NDArray) -> float:
20+
"""L1 (Manhattan) norm, the built-in ``"L1"`` metric"""
21+
return float(np.linalg.norm(v, 1))
22+
23+
24+
def _L2(v: NDArray) -> float:
25+
"""L2 (Euclidean) norm, the built-in ``"L2"`` metric"""
26+
return float(np.linalg.norm(v))
27+
28+
29+
def _SE2(v: NDArray) -> float:
30+
"""Mixed norm for (x, y, theta), the built-in ``"SE2"`` metric"""
31+
if len(v) != 3:
32+
raise ValueError(
33+
f"SE2 metric requires a 3-element (x, y, theta) vector, got length {len(v)}"
34+
)
35+
# wrap angle to range [-pi, pi)
36+
v[2] = (v[2] + np.pi) % (2 * np.pi) - np.pi
37+
return float(np.linalg.norm(v))
38+
39+
40+
#: the built-in metrics by name. They are module level, and pickled by name,
41+
#: so that a graph using one can be pickled.
42+
_METRICS: dict[str, Callable[[NDArray], float]] = {
43+
"L1": _L1,
44+
"L2": _L2,
45+
"SE2": _SE2,
46+
}
47+
48+
1949
class BaseGraph(ABC):
2050

2151
#: concrete vertex type for this graph kind, provided by :class:`UGraph`
@@ -509,6 +539,34 @@ def copy(self) -> BaseGraph:
509539
:return: deep copy
510540
:rtype: BaseGraph
511541
542+
The copy has its own vertices and edges, which keep their class, name,
543+
coordinate, cost and any attributes the user has added, and in the
544+
same order, so it can be modified without affecting the original.
545+
546+
A graph can also be pickled, and copied with :func:`copy.deepcopy`,
547+
which this method calls. Both work for a graph of any size. A
548+
vertex or an edge cannot be pickled or copied on its own, since it has
549+
no meaning apart from its graph: a :exc:`TypeError` is raised, and the
550+
graph should be copied instead.
551+
552+
.. note::
553+
554+
- A metric or heuristic given by name (``"L1"``, ``"L2"``,
555+
``"SE2"``) is pickled by name. A function you supply must be
556+
importable at module level to be pickled; a ``lambda`` or a
557+
function defined inside another function can be copied but not
558+
pickled.
559+
- Attributes that you add to vertices or edges must not refer to
560+
other vertices or edges of the graph, since those cannot be
561+
pickled on their own.
562+
- A pickle is not a long-term storage format. Use :meth:`export`
563+
for that.
564+
565+
.. versionchanged:: 1.0
566+
Pickling a graph works, and copying one no longer fails with a
567+
``RecursionError`` for a graph with a path of about a hundred
568+
vertices.
569+
512570
.. runblock:: pycon
513571
514572
>>> from pgraph import UGraph
@@ -517,9 +575,98 @@ def copy(self) -> BaseGraph:
517575
>>> g2 = g.copy()
518576
>>> g2 is g
519577
>>> g2[0] is g[0]
578+
579+
:seealso: :meth:`vertex_copy` :meth:`export`
520580
"""
521581
return copy.deepcopy(self)
522582

583+
# pickling and copying
584+
585+
#: the graph's own containers, which are saved as a flat description
586+
_STRUCTURE = ("_vertexlist", "_vertexdict", "_edges")
587+
588+
#: the references a vertex holds, which are rebuilt rather than saved
589+
_VERTEX_LINKS = ("_edgelist", "_inlist", "_graph")
590+
591+
def __getstate__(self) -> dict[str, Any]:
592+
"""
593+
State for pickling and deep copying (private method)
594+
595+
The vertices and edges form a web of references, and following them
596+
recursively overflows the stack for a graph with a path of a hundred
597+
or so vertices. Instead the graph is described flatly: a list of
598+
vertices, and a list of edges that refer to their end vertices by
599+
index. The edges are listed in the order they were added, so
600+
replaying them rebuilds each vertex's edge lists in their original
601+
order. A built-in metric is saved by name.
602+
"""
603+
state = {k: v for k, v in self.__dict__.items() if k not in self._STRUCTURE}
604+
for key in ("_metric", "_heuristic"):
605+
for name, func in _METRICS.items():
606+
if state[key] is func:
607+
state[key] = ("builtin", name)
608+
index = {id(v): i for i, v in enumerate(self._vertexlist)}
609+
state["_flat"] = {
610+
"version": 1,
611+
"vertices": [
612+
(
613+
type(v),
614+
{k: x for k, x in v.__dict__.items() if k not in self._VERTEX_LINKS},
615+
)
616+
for v in self._vertexlist
617+
],
618+
"edges": [
619+
(
620+
type(e),
621+
index[id(e.v1)],
622+
index[id(e.v2)],
623+
{k: x for k, x in e.__dict__.items() if k not in ("_v1", "_v2")},
624+
)
625+
for e in self._edges
626+
],
627+
}
628+
return state
629+
630+
def __setstate__(self, state: dict[str, Any]) -> None:
631+
"""
632+
Rebuild the graph from its flat description (private method)
633+
634+
The vertex and edge objects are made without calling ``__init__``, so
635+
subclasses with their own constructor signature are restored as they
636+
were. Each edge is attached with the vertex's own hook, exactly as
637+
:meth:`BaseVertex.connect` does.
638+
"""
639+
state = dict(state)
640+
flat = state.pop("_flat")
641+
if flat["version"] != 1:
642+
raise ValueError(f"unknown pickled graph version {flat['version']!r}")
643+
for key in ("_metric", "_heuristic"):
644+
value = state[key]
645+
if isinstance(value, tuple) and value[0] == "builtin":
646+
state[key] = _METRICS[value[1]]
647+
self.__dict__.update(state)
648+
649+
self._vertexlist = []
650+
self._vertexdict = {}
651+
for cls, attrs in flat["vertices"]:
652+
v = cls.__new__(cls)
653+
v.__dict__.update(attrs)
654+
v._edgelist = []
655+
v._inlist = []
656+
v._graph = self
657+
self._vertexlist.append(v)
658+
if v._name is not None:
659+
self._vertexdict[v._name] = v
660+
661+
self._edges = {}
662+
for cls, i, j, attrs in flat["edges"]:
663+
e = cls.__new__(cls)
664+
e.__dict__.update(attrs)
665+
v1, v2 = self._vertexlist[i], self._vertexlist[j]
666+
e._set_endpoints(v1, v2)
667+
self._edges[e] = None
668+
v1._attach(e, v2)
669+
523670
def add_vertex(
524671
self, coord: ArrayLike | BaseVertex | None = None, name: str | None = None
525672
) -> BaseVertex:
@@ -1063,30 +1210,11 @@ def _metricfunc(self, metric: Callable[[NDArray], float] | str) -> Callable[[NDA
10631210
:seealso: :meth:`metric` :meth:`heuristic`
10641211
"""
10651212

1066-
def L1(v):
1067-
return np.linalg.norm(v, 1)
1068-
1069-
def L2(v):
1070-
return np.linalg.norm(v)
1071-
1072-
def SE2(v):
1073-
if len(v) != 3:
1074-
raise ValueError(
1075-
f"SE2 metric requires a 3-element (x, y, theta) vector, got length {len(v)}"
1076-
)
1077-
# wrap angle to range [-pi, pi)
1078-
v[2] = (v[2] + np.pi) % (2 * np.pi) - np.pi
1079-
return np.linalg.norm(v)
1080-
10811213
if callable(metric):
10821214
return metric
10831215
elif isinstance(metric, str):
1084-
if metric == "L1":
1085-
return L1
1086-
elif metric == "L2":
1087-
return L2
1088-
elif metric == "SE2":
1089-
return SE2
1216+
if metric in _METRICS:
1217+
return _METRICS[metric]
10901218
else:
10911219
raise ValueError(f"unknown metric {metric!r}")
10921220
else:
@@ -3030,11 +3158,23 @@ def _set_endpoints(self, v1: BaseVertex | None, v2: BaseVertex | None) -> None:
30303158
30313159
Only the library calls this: the constructor's own assignment, then
30323160
:meth:`connect`, :meth:`BaseVertex.connect` for an edge built without
3033-
vertices, and :meth:`_BaseGraph.remove_edge`, which clears them.
3161+
vertices, and :meth:`BaseGraph.remove_edge`, which clears them.
30343162
"""
30353163
self._v1 = v1
30363164
self._v2 = v2
30373165

3166+
def __reduce__(self) -> Any:
3167+
"""
3168+
Refuse to pickle or copy an edge on its own
3169+
3170+
An edge is held by its vertices and its graph, so it has no meaning
3171+
apart from them. Pickle or copy the graph instead.
3172+
"""
3173+
raise TypeError(
3174+
"an Edge cannot be pickled or copied on its own, "
3175+
"pickle or copy its graph instead"
3176+
)
3177+
30383178
def __repr__(self) -> str:
30393179
"""
30403180
Detailed representation of the edge
@@ -3291,6 +3431,18 @@ def __init__(self, coord: ArrayLike | None = None, name: str | None = None):
32913431
self._graph: BaseGraph | None = None # reference to owning graph
32923432
# print('BaseVertex init', type(self))
32933433

3434+
def __reduce__(self) -> Any:
3435+
"""
3436+
Refuse to pickle or copy a vertex on its own
3437+
3438+
A vertex is held by its graph and by its edges, so it has no meaning
3439+
apart from them. Pickle or copy the graph instead.
3440+
"""
3441+
raise TypeError(
3442+
"a vertex cannot be pickled or copied on its own, "
3443+
"pickle or copy its graph instead"
3444+
)
3445+
32943446
def __str__(self) -> str:
32953447
"""
32963448
Compact representation of the vertex

‎tests/test_edge_endpoints.py‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -106,15 +106,18 @@ def __init__(self, v1, v2, uv):
106106
a.connect(b, edge=o)
107107
self.assertEqual((o.v1, o.v2, o.uv), (a, b, (1, 2)))
108108

109-
def test_repr_and_copies_keep_the_endpoints(self):
109+
def test_repr_shows_the_endpoints_and_an_edge_alone_is_not_copied(self):
110110
g = UGraph()
111111
a, b = g.add_vertex(name="a"), g.add_vertex(name="b")
112112
e = a.connect(b, cost=2)
113113
self.assertIn("a", str(e))
114-
for dup in (copy.copy(e), copy.deepcopy(e)):
115-
self.assertEqual(dup.cost, 2)
116-
self.assertIsNotNone(dup.v1)
117-
self.assertIsNotNone(dup.v2)
114+
# an edge has no meaning apart from its graph: copy the graph instead
115+
for f in (copy.copy, copy.deepcopy):
116+
with self.assertRaises(TypeError):
117+
f(e)
118+
dup = g.copy().edges()[0]
119+
self.assertEqual(dup.cost, 2)
120+
self.assertEqual((dup.v1.name, dup.v2.name), ("a", "b"))
118121

119122

120123
if __name__ == "__main__":

0 commit comments

Comments
 (0)