Merge branch 'main' into perf/closest-vectorized

Author: petercorke

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
           pytest --cov=pgraph --cov-report=xml:coverage.xml
           coverage report
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v7
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5  # v7.1.1
         with:
           files: ./coverage.xml
           verbose: true

.github/workflows/dependabot-auto-merge.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v3
+        uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98  # v3.1.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
 

.gitignore

@@ -1,3 +1,4 @@
+build/
 docs/build
 dist/
 *.code-workspace

docs/llms_intro.md

@@ -1,5 +1,11 @@
 pgraph is a pure-Python package of graph classes: directed and undirected graphs of vertices connected by edges, with edge costs and path planning (breadth-first, uniform-cost and A*). Vertices can be *embedded*, given a coordinate in a space of any dimension; edge costs then come from a distance metric (L2, L1, SE2 or your own), and the graph can be queried spatially, plotted and exported. Self-loops and parallel edges are allowed. It requires Python 3.9 or later and depends on NumPy, Matplotlib and spatialmath-python. Install with `pip install pgraph-python`; import it as `pgraph`.
 
+## When to use it
+
+Reach for pgraph when a program needs a **small, explicit graph with path planning**: vertices with optional coordinates, directed or undirected edges with costs, and breadth-first, uniform-cost or A* search, plus nearest-vertex queries, plotting and export. It suits roadmaps, grid and lattice planners, pose graphs and teaching examples where you want the vertex and edge objects themselves, not just an adjacency structure. `import pgraph` loads only NumPy.
+
+It is not a large-scale graph analytics package (use `networkx` for centrality, community detection or hundreds of algorithms; `igraph` or `graph-tool` for very large graphs), and it has no weighted-matching or flow algorithms.
+
 ## Quick start
 
 ```python
@@ -18,6 +24,16 @@ g.plot()
 g.highlight_path(path)
 ```
 
+## Recipes
+
+- **Shortest path between two named places**: build a `UGraph`, `add_vertex` for each place with its coordinate and `name=`, `add_edge` between neighbours, then `path, length, _ = g.path_Astar("start", "goal")`.
+- **Plan on a grid**: add one vertex per cell and an edge to each neighbour, with `cost=` if the cells differ; `path_BFS` gives the fewest steps, `path_Astar` the cheapest.
+- **Find the vertex nearest a point**: `v, dist = g.closest(point)`; `g.near(point, radius)` for all within a radius.
+- **Check whether two places are connected**: `g.samecomponent(v1, v2)`, or `g.nc` for the number of components.
+- **Get the adjacency or Laplacian matrix**: `g.adjacency()`, `g.laplacian()`, as NumPy arrays.
+- **Draw the graph and the route**: `g.plot()`, then `g.highlight_path(path)`.
+- **Export for GraphViz or Mermaid**: `g.export("graph.dot")` or `g.export("graph.mmd")`.
+
 ## Key points
 
 - **Classes.** `UGraph` (undirected) and `DGraph` (directed) share the base class `Graph`, which is concrete: `Graph(directed=True)` is a `DGraph`. There is one `Vertex` class for both and one `Edge` class. `UVertex` and `DVertex` are deprecated aliases of `Vertex`. Constructor arguments are keyword-only: `UGraph(dim=2, metric="L2", heuristic=None, vertex_class=None, edge_class=None, verbose=False)`; `UGraph(2)` is a `TypeError`.

examples/create_json.py

@@ -15,10 +15,7 @@
     del info['y']
     del info['dbne']
     del info['utmzone']
-    try:
-        del info['dgoal']
-    except:
-        pass
+    info.pop('dgoal', None)  # not every place has one
     info['utm'] = [info['utm'][0] / 1000, info['utm'][1] / 1000]
 
 routes = []

examples/roads.ipynb

@@ -187,35 +187,35 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Edge{[Camooweal] -- [Mount Isa], cost=188}\n",
-      "Edge{[Mount Isa] -- [Cloncurry], cost=118}\n",
-      "Edge{[Cloncurry] -- [Hughenden], cost=401}\n",
-      "Edge{[Cloncurry] -- [Winton], cost=350}\n",
-      "Edge{[Hughenden] -- [Charters Towers], cost=248}\n",
-      "Edge{[Charters Towers] -- [Townsville], cost=135}\n",
-      "Edge{[Townsville] -- [Mackay], cost=388}\n",
-      "Edge{[Mackay] -- [Rockhampton], cost=334}\n",
-      "Edge{[Mackay] -- [Emerald], cost=384}\n",
-      "Edge{[Rockhampton] -- [Brisbane], cost=682}\n",
-      "Edge{[Rockhampton] -- [Emerald], cost=270}\n",
-      "Edge{[Brisbane] -- [Roma], cost=482}\n",
-      "Edge{[Roma] -- [Charleville], cost=266}\n",
-      "Edge{[Charleville] -- [Blackall], cost=305}\n",
-      "Edge{[Blackall] -- [Barcaldine], cost=106}\n",
-      "Edge{[Blackall] -- [Windorah], cost=530}\n",
-      "Edge{[Barcaldine] -- [Emerald], cost=307}\n",
-      "Edge{[Barcaldine] -- [Hughenden], cost=500}\n",
-      "Edge{[Barcaldine] -- [Longreach], cost=106}\n",
-      "Edge{[Longreach] -- [Windorah], cost=311}\n",
-      "Edge{[Longreach] -- [Winton], cost=180}\n",
-      "Edge{[Winton] -- [Hughenden], cost=216}\n",
-      "Edge{[Winton] -- [Boulia], cost=363}\n",
-      "Edge{[Winton] -- [Windorah], cost=487}\n",
-      "Edge{[Boulia] -- [Mount Isa], cost=304}\n",
-      "Edge{[Boulia] -- [Bedourie], cost=194}\n",
-      "Edge{[Bedourie] -- [Birdsville], cost=193}\n",
-      "Edge{[Birdsville] -- [Windorah], cost=380}\n",
-      "Edge{[Bedourie] -- [Windorah], cost=411}\n"
+      "Edge{[Camooweal] ↔ [Mount Isa], cost=188}\n",
+      "Edge{[Mount Isa] ↔ [Cloncurry], cost=118}\n",
+      "Edge{[Cloncurry] ↔ [Hughenden], cost=401}\n",
+      "Edge{[Cloncurry] ↔ [Winton], cost=350}\n",
+      "Edge{[Hughenden] ↔ [Charters Towers], cost=248}\n",
+      "Edge{[Charters Towers] ↔ [Townsville], cost=135}\n",
+      "Edge{[Townsville] ↔ [Mackay], cost=388}\n",
+      "Edge{[Mackay] ↔ [Rockhampton], cost=334}\n",
+      "Edge{[Mackay] ↔ [Emerald], cost=384}\n",
+      "Edge{[Rockhampton] ↔ [Brisbane], cost=682}\n",
+      "Edge{[Rockhampton] ↔ [Emerald], cost=270}\n",
+      "Edge{[Brisbane] ↔ [Roma], cost=482}\n",
+      "Edge{[Roma] ↔ [Charleville], cost=266}\n",
+      "Edge{[Charleville] ↔ [Blackall], cost=305}\n",
+      "Edge{[Blackall] ↔ [Barcaldine], cost=106}\n",
+      "Edge{[Blackall] ↔ [Windorah], cost=530}\n",
+      "Edge{[Barcaldine] ↔ [Emerald], cost=307}\n",
+      "Edge{[Barcaldine] ↔ [Hughenden], cost=500}\n",
+      "Edge{[Barcaldine] ↔ [Longreach], cost=106}\n",
+      "Edge{[Longreach] ↔ [Windorah], cost=311}\n",
+      "Edge{[Longreach] ↔ [Winton], cost=180}\n",
+      "Edge{[Winton] ↔ [Hughenden], cost=216}\n",
+      "Edge{[Winton] ↔ [Boulia], cost=363}\n",
+      "Edge{[Winton] ↔ [Windorah], cost=487}\n",
+      "Edge{[Boulia] ↔ [Mount Isa], cost=304}\n",
+      "Edge{[Boulia] ↔ [Bedourie], cost=194}\n",
+      "Edge{[Bedourie] ↔ [Birdsville], cost=193}\n",
+      "Edge{[Birdsville] ↔ [Windorah], cost=380}\n",
+      "Edge{[Bedourie] ↔ [Windorah], cost=411}\n"
      ]
     }
    ],

posegraph.py

@@ -39,6 +39,7 @@ dependencies = ["spatialmath-python", "numpy>=2.0", "matplotlib"]
 "Homepage" = "https://github.com/petercorke/pgraph-python"
 "Bug Tracker" = "https://github.com/petercorke/pgraph-python/issues"
 "Documentation" = "https://petercorke.github.io/pgraph-python"
+"llms.txt" = "https://petercorke.github.io/pgraph-python/llms.txt"
 "GitHub Source" = "https://github.com/petercorke/pgraph-python"
 "Changelog" = "https://github.com/petercorke/pgraph-python/blob/main/CHANGELOG.md"
 "Coverage" = "https://codecov.io/gh/petercorke/pgraph-python"