Support reusing an existing Grid when opening datasets

[sunxiuguo]

Closes #1818

Overview

Allow open_dataset(existing_grid, data) and open_mfdataset(existing_grid, paths) to reuse the same Grid, its topology and cached properties without reconstructing it or sending it to a file backend.

The Grid's existing chunking and source-dimension mapping are preserved. Data chunks are mapped without mutating the caller's dictionary. The mapping boundary also preserves canonical dimensions when node/face counts coincide and avoids re-flattening already-standardized structured members.

Grid-construction options use_dual=True and nonempty grid_kwargs raise actionable errors for an existing Grid. chunk_grid applies when constructing grids; callers can explicitly call Grid.chunk beforehand. For unflattened structured data, use original spatial dimension names for chunking, or rechunk after flattening.

Expected Usage

import uxarray as ux

grid = ux.open_grid("grid.nc")
member_a = ux.open_dataset(grid, "member_a.nc", chunks={"n_face": 1000})
member_b = ux.open_dataset(grid, "member_b.nc", chunks={"n_face": 1000})
assert member_a.uxgrid is member_b.uxgrid is grid

In-memory xarray Dataset members and multi-file data are covered as well.

Validation

• Reproduced the reported netCDF TypeError on unchanged base for both filename and Dataset members.
• 266 tests + 28 subtests passed: API, Dask, Dataset, inheritance, indexing and all I/O tests.
• python -m unittest test.core.test_grid_reuse: 15 tests passed.
• All applicable changed-file pre-commit hooks passed; git diff --check passed.
• Independent review: 56 tests + 28 subtests and six benchmark smoke cases passed.
• New synthetic ASV benchmark ran all six grid/data input combinations. On its tiny two-face fixture, reusing a Grid took about 1.01 ms for a data file and 172 us for a Dataset. These are local fixture timings, not production performance claims.

Linux, Python 3.12.14; xarray 2026.9.0, Dask 2026.8.0, NumPy 2.5.4. The full test-suite attempt was killed with exit 137 after 47 passing progress dots; it did not complete. The final relevant suite above passed. The complete upstream CI matrix and full ASV suite have not run locally.

Existing UxDataset close-callback behavior and mixed native/flattened structured representations are not refactored by this patch.

PR Checklist

General

• An issue is created and linked
• [N/A] Added appropriate labels (no label changes requested)
• Filled out Overview and Expected Usage

Testing & Benchmarking

• Added regression coverage
• Ran the new synthetic ASV benchmark; scope and limitations stated above

Documentation and Examples

• Updated public API docstrings and added helper/benchmark docstrings
• [N/A] No new public function
• [N/A] No notebooks changed

AI Disclosure

AI Usage: OpenAI Codex assisted with investigation, implementation, synthetic tests, benchmarking, and independent code review.

• I have tested and take responsibility for all AI-generated content in my PR.