WIP: Changes to speed up BoundaryForcing calls

[kthyng]

This PR introduces a source-fill and regrid-engine API for BoundaryForcing, and deprecates the apply_2d_horizontal_fill boolean flag. Users can now explicitly control source-side filling (prefill: None (default), "2d_lateral_fill", "inverse_dist", "nearest_s2d", "nearest_neighbor") and choose the horizontal regrid engine independently (regrid_method: "auto" (default = xESMF if installed, else scipy), "xesmf", "scipy"). The default path is xESMF masked-bilinear interpolation with inverse-distance-weighted destination extrapolation when available, with a nearest-neighbor source pre-fill + scipy interp fallback on Windows/pip installs. When a prefill is set, the source is pre-filled so that nan's are not present (matching the legacy AMG precedent) before per-boundary regridding with plain bilinear, making extrap_method irrelevant. The deprecated apply_2d_horizontal_fill=True/False still works with a clear DeprecationWarning, mapping to the equivalent prefill values for backward compatibility.

Scope and testing: Changes are confined to BoundaryForcing only; InitialConditions, SurfaceForcing, Topography, and TidalForcing are intentionally unchanged and produce numerically equivalent output to pre-change. Shared validation helpers (validate_prefill, validate_extrap, resolve_regrid_engine) and an apply_prefill dispatcher on the dataset class enable forward-compatible rollout to other classes later. Comprehensive test coverage includes deprecation mapping, conflict detection, xESMF-availability gating, YAML round-trip compat (old and new formats), per-prefill-method NaN-free assertions, and cross-engine tolerances. All boundary/fill/prefill tests pass; 135 untouched-class tests pass. The physics boundary forcing regression fixture reflects the new xESMF default; BGC fixtures are pinned to regrid_method="scipy" for byte-reproducibility with pre-v4 outputs.

• Closes Out of memory when creating boundary forcing with 2D fill #368
• Tests added
• Passes pre-commit run --all-files
• Changes are documented in docs/releases.md
• New functions/methods are listed in docs/api.rst
• New functionality has documentation

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB