Rename rasterize() use_cuda to gpu with a deprecation shim (#3089)

[brendancol]

Closes #3089

rasterize() was the only public function spelling the GPU opt-in use_cuda; open_geotiff() and the accessor use gpu. Both names were live in the public API for the identical concept, so anyone moving between the two functions hit a TypeError.

• Rename the parameter to gpu. It keeps use_cuda's position in the signature, so positional callers see no change.
• use_cuda stays as a keyword alias appended at the end: it emits a DeprecationWarning pointing at gpu= and maps onto it. Passing both raises TypeError.
• Docstring, the custom-merge GPU warning, the CuPy ImportError message, and polygon_clip.py's internal dask+cupy call now use gpu. The polygon_clip path is guarded so a legacy use_cuda passed via rasterize_kw keeps working instead of colliding with the new default.
• All rasterize test call sites migrated to gpu=.

Backend coverage: numpy, cupy, dask+numpy, and dask+cupy entry points all verified on a CUDA host; values match across backends with identical kwargs.

Test plan (new file test_rasterize_gpu_alias_3089.py):

• gpu occupies the old use_cuda slot; alias is the last parameter
• default call emits no DeprecationWarning
• use_cuda=True/False warns and behaves like gpu=
• gpu=True + use_cuda=... raises TypeError
• cupy and dask+cupy results match numpy
• clip_polygon on a dask+cupy raster emits no DeprecationWarning
• full rasterize suite (649 passed) and polygon_clip suite (23 passed)

[brendancol]

PR Review: Rename rasterize() use_cuda to gpu with a deprecation shim (#3089)

Blockers (must fix before merge)

• None.

Suggestions (should fix, not blocking)

• benchmarks/benchmarks/rasterize.py (lines 100-125, 145) still calls rasterize(..., use_cuda=...). The benchmarks will emit a DeprecationWarning on every run and keep the old spelling alive in repo code. Migrate them to gpu= in this PR since the rename is the whole point.

Nits (optional improvements)

• xrspatial/rasterize.py:3300 uses .. deprecated:: 0.11, but the repo is at 0.10.7.dev with a 1.0.0 milestone open, so the named version may never exist. Either use the actual next release or drop the version number and say it in prose.

What looks good

• The new gpu parameter occupies use_cuda's old slot, so positional callers are untouched; the alias is appended last. The slot is pinned by a test.
• Shim semantics are the same as the focal/zonal renames: warn on the alias, TypeError when both are passed, stacklevel=2.
• polygon_clip.py guards against the case where a caller passes use_cuda through rasterize_kw; without the guard the internal gpu default would collide with it and raise.
• Test migration was checked for sed damage (_xs_mask, _run helpers read correctly; no stray use_cuda names remain in tests).
• All four entry points (numpy, cupy, dask+numpy, dask+cupy) verified on a CUDA host with identical kwargs and matching values; 649 rasterize tests plus 23 polygon_clip tests pass.

Checklist

• Algorithm matches reference (n/a -- API rename, no numerics touched)
• All implemented backends produce consistent results
• NaN handling is correct (untouched)
• Edge cases covered (both-args TypeError, alias=False, no-warning default)
• Dask chunk boundaries handled correctly (untouched)
• No premature materialization or unnecessary copies
• Benchmark exists but still uses the deprecated kwarg (see suggestion)
• README feature matrix: no change needed
• Docstrings present and accurate (modulo the version nit)

[brendancol]

Follow-up review after 1104382:

• Benchmarks suggestion: fixed. All six benchmark classes in benchmarks/benchmarks/rasterize.py now set self.gpu and call rasterize(..., gpu=...); no use_cuda remains outside the shim itself and its regression tests.
• Version nit: fixed. The alias docstring entry now states the deprecation in prose instead of naming a release that may never exist.

Re-checked the shim, tests (11 passed across the alias and annotation suites), and lint on the touched files. The two flake8 F401s in the benchmark file predate this PR. No new findings.