1616from 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+
1949class 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
0 commit comments