Update docs and README with multi-backend pathfinding support

Add backend support table to docstring and user guide notebook,
dask out-of-core example, and CPU-fallback symbol in README matrix.

Author: brendancol

README.md

@@ -131,6 +131,8 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 
 #### Supported Spatial Functions with Supported Inputs
 
+✅ = native backend    🔄 = accepted (CPU fallback)
+
 -------
 
 ### **Classification**
@@ -183,7 +185,7 @@ In the GIS world, rasters are used for representing continuous phenomena (e.g. e
 
 | Name | Description | NumPy xr.DataArray | Dask xr.DataArray | CuPy GPU xr.DataArray | Dask GPU xr.DataArray |
 |:----------:|:------------|:----------------------:|:--------------------:|:-------------------:|:------:|
-| [A* Pathfinding](xrspatial/pathfinding.py) | Finds the least-cost path between two cells on a cost surface | ✅️ |  | | |
+| [A* Pathfinding](xrspatial/pathfinding.py) | Finds the least-cost path between two cells on a cost surface | ✅️ | ✅ | 🔄 | 🔄 |
 
 ----------
 

docs/source/user_guide/pathfinding.ipynb

@@ -3,17 +3,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "## Pathfinding\n",
-    "\n",
-    "Xarray-spatial provides A\\* pathfinding for finding optimal routes through raster surfaces.\n",
-    "Paths can be computed using geometric distance alone (unweighted) or weighted by a\n",
-    "friction/cost surface, which makes the algorithm find the *least-cost* path rather\n",
-    "than the geometrically shortest one.\n",
-    "\n",
-    "- [Unweighted A\\*](#Unweighted-A*): find the shortest geometric path through a line network\n",
-    "- [Weighted A\\*](#Weighted-A*): find the least-cost path through a friction surface"
-   ]
+   "source": "## Pathfinding\n\nXarray-spatial provides A\\* pathfinding for finding optimal routes through raster surfaces.\nPaths can be computed using geometric distance alone (unweighted) or weighted by a\nfriction/cost surface, which makes the algorithm find the *least-cost* path rather\nthan the geometrically shortest one.\n\nAll four backends are supported:\n\n| Backend | Strategy |\n|---------|----------|\n| **NumPy** | Numba-jitted kernel (fast, in-memory) |\n| **Dask** | Sparse Python A\\* with LRU chunk cache — loads chunks on demand so the full grid never needs to fit in RAM |\n| **CuPy** | CPU fallback (transfers to numpy, runs the numba kernel, transfers back) |\n| **Dask+CuPy** | Same sparse A\\* as Dask, with automatic cupy-to-numpy chunk conversion |\n\n**Note:** `snap_start` and `snap_goal` are not supported with Dask-backed arrays\nbecause the brute-force nearest-pixel scan is O(h*w). Ensure the start and goal\npixels are valid before calling `a_star_search`.\n\n- [Unweighted A\\*](#Unweighted-A*): find the shortest geometric path through a line network\n- [Weighted A\\*](#Weighted-A*): find the least-cost path through a friction surface\n- [Dask (out-of-core)](#Dask-(out-of-core)): pathfinding on datasets that don't fit in RAM"
   },
   {
    "cell_type": "markdown",
@@ -272,6 +262,18 @@
     "- Red Blob Games — A\\* implementation: https://www.redblobgames.com/pathfinding/a-star/implementation.html\n",
     "- Cost distance (weighted proximity): `xrspatial.cost_distance`"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": "### Dask (out-of-core)\n\nFor rasters that don't fit in memory, wrap your data in a Dask array.\nA\\* explores only the pixels it needs (typically O(path_length) to\nO(path_length^2)), loading chunks on demand through an LRU cache.\nThe output is a lazy Dask array of the same chunk structure.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "source": "import dask.array as da\n\n# Re-use the terrain and friction from above, but as dask arrays\nterrain_dask = terrain.copy()\nterrain_dask.data = da.from_array(terrain.data, chunks=(200, 300))\n\nfriction_dask = friction.copy()\nfriction_dask.data = da.from_array(friction.data, chunks=(200, 300))\n\n# Run A* — chunks are loaded on demand, not all at once\npath_dask = a_star_search(terrain_dask, start_coord, goal_coord, friction=friction_dask)\nprint(f\"Result type: {type(path_dask.data)}\")\nprint(f\"Chunks: {path_dask.data.chunks}\")\n\n# Compute to verify it matches the in-memory result\ndask_cost = float(path_dask.values[gpy, gpx])\nprint(f\"Dask A* cost at goal:   {dask_cost:.4f}\")\nprint(f\"NumPy A* cost at goal:  {astar_val:.4f}\")\nprint(f\"Match: {np.isclose(dask_cost, astar_val, rtol=1e-5)}\")",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
   }
  ],
  "metadata": {

xrspatial/pathfinding.py

@@ -514,6 +514,22 @@ def a_star_search(surface: xr.DataArray,
     The output is an equal-sized ``xr.DataArray`` with NaN for non-path
     pixels and the accumulated cost at each path pixel.
 
+    **Backend support**
+
+    =============  ===========================================================
+    Backend        Strategy
+    =============  ===========================================================
+    NumPy          Numba-jitted kernel (fast, in-memory)
+    Dask           Sparse Python A* with LRU chunk cache — loads chunks on
+                   demand so the full grid never needs to fit in RAM
+    CuPy           CPU fallback (transfers to numpy, runs numba kernel,
+                   transfers back)
+    Dask + CuPy    Same sparse A* as Dask, with cupy→numpy chunk conversion
+    =============  ===========================================================
+
+    ``snap_start`` and ``snap_goal`` are not supported with Dask-backed
+    arrays (raises ``ValueError``).
+
     Parameters
     ----------
     surface : xr.DataArray