Expose multi_stop_search on the .xrs DataArray and Dataset accessors

[brendancol]

Closes #3563

Exposes multi_stop_search on the .xrs accessor, alongside the existing a_star_search method, so multi-waypoint routing is reachable as raster.xrs.multi_stop_search(waypoints, ...) without dropping to the module-level function.

• DataArray accessor: new delegation method under the Pathfinding banner in XrsSpatialDataArrayAccessor. waypoints is positional, everything else forwards as keyword args.
• Dataset accessor: multi_stop_search is decorated with @supports_dataset, matching cost_distance and proximity, so ds.xrs.multi_stop_search(...) routes each data variable through the same waypoints and returns a Dataset of per-variable results.
• Added multi_stop_search to the pathfinding reference docs, which previously listed only a_star_search.

a_star_search stays DataArray-only (it is not @supports_dataset and was not requested here).

Backend coverage: the accessor is a thin delegate, so backend support is whatever multi_stop_search already provides (numpy, cupy, dask+numpy, dask+cupy). No change to the routing implementation.

Test plan:

• test_da_multi_stop_search: DataArray accessor matches the direct call
• test_da_multi_stop_search_kwargs: keyword forwarding (optimize_order=True)
• test_ds_multi_stop_search: Dataset accessor matches the direct call, per-variable
• test_da_a_star_search: functional parity test for the sibling method
• presence checks updated for both accessors
• test_accessor.py (90) and test_pathfinding.py (51) pass

[brendancol]

PR Review: Expose multi_stop_search on the .xrs DataArray accessor

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

None.

Nits (optional improvements)

None.

What looks good

• The accessor method (xrspatial/accessor.py:1213) mirrors the sibling a_star_search delegate: waypoints positional, the rest forwarded as **kwargs. The lazy from .pathfinding import matches every other method in the class, so it costs nothing at import time.
• DataArray-only placement is right. a_star_search is also absent from the Dataset accessor, and multi_stop_search is a DataArray operation (it builds a single cost surface).
• The tests check the real contract: accessor output is assert_identical to the direct call, including the optimize_order=True keyword path. The new test_da_a_star_search closes a gap, since the sibling previously had only a presence check.
• The method sits under the existing # ---- Pathfinding ---- banner, so it appears in the accessor repr and passes the category-banner guard test.
• The docs RST gets a matching entry, and the section underline length is correct, so Sphinx stays quiet.

Notes

• No README change needed. multi_stop_search is already in the feature matrix and exported from __init__. No new algorithm, so no benchmark or user-guide notebook.
• Backend coverage is inherited from multi_stop_search unchanged (numpy, cupy, dask+numpy, dask+cupy).

Checklist

• Algorithm matches reference/paper (no algorithm change; pure delegation)
• All implemented backends produce consistent results (inherited)
• NaN handling is correct (unchanged)
• Edge cases are covered by tests (delegation parity tested)
• Dask chunk boundaries handled correctly (unchanged)
• No premature materialization or unnecessary copies
• Benchmark exists or is not needed (not needed)
• README feature matrix updated (already present)
• Docstrings present and accurate (delegate inherits documentation)

[brendancol]

PR Review (follow-up): Dataset accessor support for multi_stop_search

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

None.

Nits (optional improvements)

None.

What looks good

• @supports_dataset on multi_stop_search (xrspatial/pathfinding.py:1328) is the same mechanism cost_distance and proximity already use, so the Dataset accessor delegate (xrspatial/accessor.py:1952) forwards directly with no special-casing.
• The decorator only injects name when the wrapped function has a name parameter. multi_stop_search has none, so the wrapper calls func(da, waypoints, **kwargs) per variable without passing an unsupported kwarg. Confirmed name is absent from the signature.
• The DataArray path keeps its old behavior: the wrapper passes a DataArray straight through. The 51 pathfinding tests still pass, so the decorator did not regress single-array routing.
• test_ds_multi_stop_search checks the real contract: assert_identical against the direct multi_stop_search(ds, ...) call, plus a per-variable data_vars assertion. Both accessor presence lists are updated.
• Docstring extended to xr.DataArray or xr.Dataset in Parameters and Returns, matching how cost_distance documents the same decorator.

Notes

• a_star_search stays DataArray-only by design. It is not @supports_dataset and was out of scope here. The asymmetry is intentional and called out in the PR body.
• The unused import has_dask_array (pathfinding.py:21) is already on main, unrelated to this change, left as-is.
• Dataset application iterates every data variable, so a Dataset carrying a non-2D variable would raise on that variable. That matches the existing behavior of cost_distance/proximity on Datasets, so it is not a new sharp edge.

Checklist

• Algorithm matches reference/paper (no algorithm change; delegation + decorator)
• All implemented backends produce consistent results (inherited)
• NaN handling is correct (unchanged)
• Edge cases are covered by tests (DataArray and Dataset parity tested)
• Dask chunk boundaries handled correctly (unchanged)
• No premature materialization or unnecessary copies
• Benchmark exists or is not needed (thin delegation; not needed)
• README feature matrix updated (already present)
• Docstrings present and accurate (updated for Dataset input)