uxarray 2026.3.0__tar.gz → 2026.4.1__tar.gz

{uxarray-2026.3.0 → uxarray-2026.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uxarray
-Version: 2026.3.0
+Version: 2026.4.1
 Summary: Xarray extension for unstructured climate and global weather data analysis and visualization.
 License:                                  Apache License
                                    Version 2.0, January 2004

{uxarray-2026.3.0 → uxarray-2026.4.1}/uxarray/core/dataset.py

@@ -90,6 +90,24 @@ class UxDataset(xr.Dataset):
         else:
             self._uxgrid = uxgrid
 
+        # As of xarray's 2026.4.0, `xr.Dataset(xr.Dataset)` is prohibited;
+        # hence this check, i.e. if we get `xr.Dataset` as input, use its `data_vars`
+        # as `dict` and handle `coords` and `attrs` properly as well
+        if args and isinstance(args[0], xr.Dataset):
+            ds = args[0]
+            # Replacee only args[0], `ds`, with `ds.data_vars` as `dict`
+            args = (dict(ds.data_vars),) + args[1:]
+            # coords not passed positionally
+            if len(args) < 2:
+                kwargs.setdefault(
+                    "coords", dict(ds.coords)
+                )  # Set it as kwarg only if not explicitly provided
+            # attrs not passed positionally
+            if len(args) < 3:
+                kwargs.setdefault(
+                    "attrs", ds.attrs
+                )  # Set it as kwarg only if not explicitly provided
+
         super().__init__(*args, **kwargs)
 
     # declare plotting accessor
@@ -627,9 +645,9 @@ class UxDataset(xr.Dataset):
         """
         if grid_format == "HEALPix":
             ds = self.rename_dims({"n_face": "cell"})
-            return xr.Dataset(ds)
+            return xr.Dataset(ds.data_vars, coords=ds.coords, attrs=ds.attrs)
 
-        return xr.Dataset(self)
+        return xr.Dataset(self.data_vars, coords=self.coords, attrs=self.attrs)
 
     def get_dual(self):
         """Compute the dual mesh for a dataset, returns a new dataset object.

{uxarray-2026.3.0 → uxarray-2026.4.1}/uxarray/io/utils.py

@@ -7,51 +7,114 @@ from uxarray.io._mpas import _mpas_to_ugrid_dims
 from uxarray.io._ugrid import _is_ugrid, _read_ugrid
 
 
+def _is_exodus(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like an Exodus mesh."""
+    has_packed_coords = "coord" in dataset
+    has_split_coords = {"coordx", "coordy"}.issubset(dataset.variables)
+    has_connectivity = any(
+        name.startswith("connect") for name in dataset.variables
+    ) or any("num_nod_per_el" in dim for dim in dataset.dims)
+
+    return has_connectivity and (has_packed_coords or has_split_coords)
+
+
+def _is_scrip(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like an unstructured SCRIP grid."""
+    required_vars = {
+        "grid_center_lon",
+        "grid_center_lat",
+        "grid_corner_lon",
+        "grid_corner_lat",
+    }
+    unstructured_markers = {"grid_imask", "grid_rank", "grid_area"}
+
+    return required_vars.issubset(dataset.variables) and any(
+        marker in dataset for marker in unstructured_markers
+    )
+
+
+def _is_mpas(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like an MPAS grid."""
+    if "verticesOnCell" not in dataset:
+        return False
+
+    companion_groups = (
+        {"nEdgesOnCell"},
+        {"latCell", "lonCell"},
+        {"latVertex", "lonVertex"},
+        {"xCell", "yCell", "zCell"},
+        {"xVertex", "yVertex", "zVertex"},
+    )
+
+    return any(group.issubset(dataset.variables) for group in companion_groups)
+
+
+def _is_esmf(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like an ESMF mesh."""
+    return "maxNodePElement" in dataset.dims and "elementConn" in dataset
+
+
+def _is_geos_cs(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like a GEOS cube-sphere grid."""
+    required_dims = {"nf", "YCdim", "XCdim"}
+    required_vars = {"corner_lons", "corner_lats"}
+
+    return required_dims.issubset(dataset.sizes) and required_vars.issubset(
+        dataset.variables
+    )
+
+
+def _is_icon(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like an ICON grid."""
+    required_vars = {"vertex_of_cell", "clon", "clat", "vlon", "vlat"}
+    return required_vars.issubset(dataset.variables)
+
+
+def _is_fesom2(dataset: xr.Dataset) -> bool:
+    """Check whether a dataset looks like a FESOM2 grid."""
+    return "triag_nodes" in dataset
+
+
 def _parse_grid_type(dataset):
-    """Checks input and contents to determine grid type. Supports detection of
-    UGrid, SCRIP, Exodus, ESMF, and shape file.
+    """Determine the grid type represented by an input dataset.
 
     Parameters
     ----------
     dataset : Xarray dataset
-       Xarray dataset of the grid
+        Xarray dataset containing grid topology information.
 
     Returns
     -------
-    mesh_type : str
-        File type of the file, ug, exo, scrip or shp
+    tuple[str, str | None, str | None]
+        A 3-tuple of ``(mesh_type, lon_name, lat_name)``. ``mesh_type`` is one
+        of ``"Exodus"``, ``"Scrip"``, ``"UGRID"``, ``"MPAS"``, ``"ESMF"``,
+        ``"GEOS-CS"``, ``"ICON"``, ``"FESOM2"``, or ``"Structured"``. The
+        longitude and latitude coordinate names are only returned for structured
+        grids and are otherwise ``None``.
 
     Raises
     ------
     RuntimeError
-            If invalid file type
-    ValueError
-        If file is not in UGRID format
+        If the dataset format cannot be recognized.
     """
 
     _structured, lon_name, lat_name = _is_structured(dataset)
 
-    if "coord" in dataset:
-        # exodus with coord or coordx
-        mesh_type = "Exodus"
-    elif "coordx" in dataset:
+    if _is_exodus(dataset):
         mesh_type = "Exodus"
-    elif "grid_center_lon" in dataset:
-        # scrip with grid_center_lon
+    elif _is_scrip(dataset):
         mesh_type = "Scrip"
     elif _is_ugrid(dataset):
-        # ugrid topology is present
         mesh_type = "UGRID"
-    elif "verticesOnCell" in dataset:
+    elif _is_mpas(dataset):
         mesh_type = "MPAS"
-    elif "maxNodePElement" in dataset.dims:
+    elif _is_esmf(dataset):
         mesh_type = "ESMF"
-    elif all(key in dataset.sizes for key in ["nf", "YCdim", "XCdim"]):
-        # expected dimensions for a GEOS cube sphere grid
+    elif _is_geos_cs(dataset):
         mesh_type = "GEOS-CS"
-    elif "vertex_of_cell" in dataset:
+    elif _is_icon(dataset):
         mesh_type = "ICON"
-    elif "triag_nodes" in dataset:
+    elif _is_fesom2(dataset):
         mesh_type = "FESOM2"
     elif _structured:
         mesh_type = "Structured"

uxarray-2026.4.1/uxarray/remap/accessor.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from uxarray.core.dataarray import UxDataArray
+    from uxarray.core.dataset import UxDataset
+    from uxarray.grid.grid import Grid
+
+from uxarray.remap.bilinear import _bilinear
+from uxarray.remap.inverse_distance_weighted import _inverse_distance_weighted_remap
+from uxarray.remap.nearest_neighbor import _nearest_neighbor_remap
+
+_VALID_BACKENDS = ("uxarray", "yac")
+
+
+def _validate_backend(backend: str) -> None:
+    if backend not in _VALID_BACKENDS:
+        raise ValueError(
+            f"Invalid backend '{backend}'. Expected one of {_VALID_BACKENDS}."
+        )
+
+
+class RemapAccessor:
+    """Expose remapping methods on UxDataArray and UxDataset objects."""
+
+    def __init__(self, ux_obj: UxDataArray | UxDataset):
+        self.ux_obj = ux_obj
+
+    def __repr__(self) -> str:
+        prefix = f"<{type(self.ux_obj).__name__}.remap>\n"
+        return (
+            prefix
+            + "Supported methods:\n"
+            + "  • nearest_neighbor(destination_grid, remap_to='faces')\n"
+            + "  • inverse_distance_weighted(destination_grid, remap_to='faces', power=2, k=8)\n"
+        )
+
+    def __call__(
+        self,
+        *args,
+        backend: str = "uxarray",
+        yac_method: str | None = None,
+        yac_options: dict | None = None,
+        **kwargs,
+    ) -> UxDataArray | UxDataset:
+        """
+        Shortcut for nearest-neighbor remapping.
+
+        Calling `.remap(...)` with no explicit method will invoke
+        `nearest_neighbor(...)`.
+
+        When ``backend="yac"``, this generic entrypoint can also be used to
+        select a YAC-specific interpolation method through ``yac_method``.
+        """
+        nn_kwargs: dict = {"backend": backend, "yac_options": yac_options}
+        if yac_method is not None:
+            nn_kwargs["yac_method"] = yac_method
+        return self.nearest_neighbor(*args, **nn_kwargs, **kwargs)
+
+    def nearest_neighbor(
+        self,
+        destination_grid: Grid,
+        remap_to: str = "faces",
+        backend: str = "uxarray",
+        yac_method: str | None = "nnn",
+        yac_options: dict | None = None,
+        **kwargs,
+    ) -> UxDataArray | UxDataset:
+        """
+        Perform nearest-neighbor remapping.
+
+        Each destination point takes the value of its closest source point.
+
+        Parameters
+        ----------
+        destination_grid : Grid
+            The UXarray grid to which data will be interpolated.
+        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
+            Which grid element receives the remapped values.
+
+        backend : {'uxarray', 'yac'}, default='uxarray'
+            Remapping backend to use. When set to 'yac', requires YAC to be
+            available on PYTHONPATH.
+        yac_method : {'nnn', 'average', 'conservative'}, optional
+            YAC interpolation method. Defaults to 'nnn' when backend='yac'.
+        yac_options : dict, optional
+            YAC interpolation configuration options.
+
+        Returns
+        -------
+        UxDataArray or UxDataset
+            A new object with data mapped onto `destination_grid`.
+
+        Notes
+        -----
+        When ``backend="yac"``, remapping uses YAC's low-level ``yac.core``
+        Python bindings. See the YAC documentation and installation guide:
+
+        - https://dkrz-sw.gitlab-pages.dkrz.de/yac/
+        - https://dkrz-sw.gitlab-pages.dkrz.de/yac/d1/d9f/installing_yac.html
+        """
+
+        _validate_backend(backend)
+        if backend == "yac":
+            from uxarray.remap.yac import _yac_remap
+
+            yac_kwargs = yac_options or {}
+            return _yac_remap(
+                self.ux_obj, destination_grid, remap_to, yac_method, yac_kwargs
+            )
+        return _nearest_neighbor_remap(self.ux_obj, destination_grid, remap_to)
+
+    def inverse_distance_weighted(
+        self,
+        destination_grid: Grid,
+        remap_to: str = "faces",
+        power=2,
+        k=8,
+        backend: str = "uxarray",
+        yac_method: str | None = None,
+        yac_options: dict | None = None,
+        **kwargs,
+    ) -> UxDataArray | UxDataset:
+        """
+        Perform inverse-distance-weighted (IDW) remapping.
+
+        Each destination point is a weighted average of nearby source points,
+        with weights proportional to 1/(distance**power).
+
+        Parameters
+        ----------
+        destination_grid : Grid
+            The UXarray grid to which data will be interpolated.
+        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
+            Which grid element receives the remapped values.
+        power : int, default=2
+            Exponent controlling distance decay. Larger values make the
+            interpolation more local.
+        k : int, default=8
+            Number of nearest source points to include in the weighted average.
+
+        backend : {'uxarray', 'yac'}, default='uxarray'
+            Remapping backend to use. When set to 'yac', requires YAC to be
+            available on PYTHONPATH.
+        yac_method : {'nnn', 'conservative'}, optional
+            YAC interpolation method. Required when backend='yac'.
+        yac_options : dict, optional
+            YAC interpolation configuration options.
+
+        Returns
+        -------
+        UxDataArray or UxDataset
+            A new object with data mapped onto `destination_grid`.
+
+        Notes
+        -----
+        When ``backend="yac"``, this method delegates to YAC's ``average``
+        interpolation method through the low-level ``yac.core`` Python
+        bindings. See the YAC documentation and installation guide:
+
+        - https://dkrz-sw.gitlab-pages.dkrz.de/yac/
+        - https://dkrz-sw.gitlab-pages.dkrz.de/yac/d1/d9f/installing_yac.html
+        """
+
+        _validate_backend(backend)
+        if backend == "yac":
+            raise NotImplementedError(
+                "inverse_distance_weighted with backend='yac' is not currently "
+                "exposed through the UXarray YAC accessor. "
+                "Use backend='uxarray' for IDW, or use the YAC backend through "
+                ".remap(..., backend='yac', yac_method=..., yac_options=...)."
+            )
+        return _inverse_distance_weighted_remap(
+            self.ux_obj, destination_grid, remap_to, power, k
+        )
+
+    def bilinear(
+        self,
+        destination_grid: Grid,
+        remap_to: str = "faces",
+        backend: str = "uxarray",
+        yac_method: str | None = "average",
+        yac_options: dict | None = None,
+        **kwargs,
+    ) -> UxDataArray | UxDataset:
+        """
+        Perform bilinear remapping.
+
+        Parameters
+        ---------
+        destination_grid : Grid
+            Destination Grid for remapping
+        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
+            Which grid element receives the remapped values.
+
+        backend : {'uxarray', 'yac'}, default='uxarray'
+            Remapping backend to use. When set to 'yac', bilinear remapping is
+            routed through YAC's average interpolation.
+        yac_method : {'average'}, optional
+            YAC interpolation method for the bilinear convenience wrapper.
+            Only ``'average'`` is supported here.
+        yac_options : dict, optional
+            YAC interpolation configuration options for the average method.
+
+        Returns
+        -------
+        UxDataArray or UxDataset
+            A new object with data mapped onto `destination_grid`.
+        """
+
+        _validate_backend(backend)
+        if backend == "yac":
+            from uxarray.remap.yac import _yac_remap
+
+            if yac_method not in (None, "average"):
+                raise ValueError(
+                    "bilinear with backend='yac' only supports yac_method='average'. "
+                    "Use .remap(..., backend='yac', yac_method=...) for other YAC methods."
+                )
+            yac_kwargs = yac_options or {}
+            return _yac_remap(
+                self.ux_obj,
+                destination_grid,
+                remap_to,
+                yac_method or "average",
+                yac_kwargs,
+            )
+        return _bilinear(self.ux_obj, destination_grid, remap_to)

uxarray-2026.4.1/uxarray/remap/yac.py

@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+from uuid import uuid4
+
+import numpy as np
+
+import uxarray.core.dataarray
+from uxarray.remap.utils import (
+    LABEL_TO_COORD,
+    _assert_dimension,
+    _construct_remapped_ds,
+    _get_remap_dims,
+    _to_dataset,
+)
+
+
+class YacNotAvailableError(RuntimeError):
+    """Raised when the YAC backend is requested but unavailable."""
+
+
+@dataclass
+class _YacOptions:
+    method: str
+    kwargs: dict[str, Any]
+
+
+def _load_yac_core_from_file() -> ModuleType | None:
+    if "yac.core" in sys.modules:
+        return sys.modules["yac.core"]
+
+    for path_entry in sys.path:
+        pkg_dir = Path(path_entry) / "yac"
+        if not pkg_dir.is_dir():
+            continue
+
+        matches = sorted(pkg_dir.glob("core*.so"))
+        if not matches:
+            matches = sorted(pkg_dir.glob("core*.pyd"))
+        if not matches:
+            continue
+
+        pkg = sys.modules.get("yac")
+        if pkg is None:
+            pkg = ModuleType("yac")
+            sys.modules["yac"] = pkg
+        pkg.__path__ = [str(pkg_dir)]
+
+        spec = importlib.util.spec_from_file_location("yac.core", matches[0])
+        if spec is None or spec.loader is None:
+            continue
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules["yac.core"] = module
+        spec.loader.exec_module(module)
+        setattr(pkg, "core", module)
+        return module
+
+    return None
+
+
+def _import_yac():
+    module = _load_yac_core_from_file()
+    if module is not None:
+        return module
+
+    try:
+        return importlib.import_module("yac.core")
+    except Exception as exc:  # pragma: no cover - fallback depends on local install
+        raise YacNotAvailableError(
+            "YAC backend requested but 'yac.core' is not available. "
+            "Build YAC with Python bindings and ensure its site-packages and "
+            "shared libraries are discoverable."
+        ) from exc
+
+
+def _normalize_yac_method(yac_method: str | None) -> _YacOptions:
+    if not yac_method:
+        raise ValueError(
+            "backend='yac' requires yac_method to be set to 'nnn', 'average', or 'conservative'."
+        )
+    method = yac_method.lower()
+    if method not in {"nnn", "average", "conservative"}:
+        raise ValueError(f"Unsupported YAC method: {yac_method!r}")
+    return _YacOptions(method=method, kwargs={})
+
+
+def _get_location(yac_core, dim: str):
+    mapping = {
+        "n_face": yac_core.yac_location.YAC_LOC_CELL,
+        "n_node": yac_core.yac_location.YAC_LOC_CORNER,
+        "n_edge": yac_core.yac_location.YAC_LOC_EDGE,
+    }
+    try:
+        return mapping[dim]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported remap dimension for YAC: {dim!r}") from exc
+
+
+def _get_lon_lat(grid, dim: str) -> tuple[np.ndarray, np.ndarray]:
+    attr_map = {
+        "n_face": ("face_lon", "face_lat"),
+        "n_node": ("node_lon", "node_lat"),
+        "n_edge": ("edge_lon", "edge_lat"),
+    }
+    try:
+        lon_attr, lat_attr = attr_map[dim]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported remap dimension for YAC: {dim!r}") from exc
+
+    lon = getattr(grid, lon_attr, None)
+    lat = getattr(grid, lat_attr, None)
+    if lon is None or lat is None:
+        raise ValueError(
+            f"Grid does not provide {lon_attr}/{lat_attr} required for YAC remapping."
+        )
+    return np.deg2rad(np.asarray(lon.values, dtype=np.float64)), np.deg2rad(
+        np.asarray(lat.values, dtype=np.float64)
+    )
+
+
+def _coerce_enum(enum_type, value: Any):
+    if not isinstance(value, str):
+        return value
+
+    normalized = value.upper()
+    for member in enum_type:
+        if member.name == normalized or member.name.endswith(f"_{normalized}"):
+            return member
+
+    raise ValueError(f"Unsupported value {value!r} for enum {enum_type.__name__}.")
+
+
+class _YacRemapper:
+    """Build and reuse YAC interpolation weights for one source dimension.
+
+    Each instance owns the YAC source/target field registration for a single
+    source location type (faces, nodes, or edges) and one requested YAC method.
+    The resulting weights can then be applied repeatedly to batches of values
+    that share the same source dimension.
+    """
+
+    def __init__(
+        self,
+        src_grid,
+        tgt_grid,
+        src_dim: str,
+        tgt_dim: str,
+        yac_method: str,
+        yac_kwargs: dict[str, Any],
+    ):
+        yac_core = _import_yac()
+        self._frac_mask_fallback_value = yac_kwargs.get("frac_mask_fallback_value")
+        self._src_location = _get_location(yac_core, src_dim)
+        self._tgt_location = _get_location(yac_core, tgt_dim)
+
+        define_edges = "n_edge" in (src_dim, tgt_dim)
+        unique = uuid4().hex
+        self._src_grid = yac_core.BasicGrid.from_uxgrid(
+            f"uxarray_src_{unique}",
+            src_grid,
+            def_edges=define_edges,
+        )
+        self._tgt_grid = yac_core.BasicGrid.from_uxgrid(
+            f"uxarray_tgt_{unique}",
+            tgt_grid,
+            def_edges=define_edges,
+        )
+        src_lon, src_lat = _get_lon_lat(src_grid, src_dim)
+        tgt_lon, tgt_lat = _get_lon_lat(tgt_grid, tgt_dim)
+
+        self._src_field = yac_core.InterpField(
+            self._src_grid.add_coordinates(self._src_location, src_lon, src_lat)
+        )
+        self._tgt_field = yac_core.InterpField(
+            self._tgt_grid.add_coordinates(self._tgt_location, tgt_lon, tgt_lat)
+        )
+
+        stack = yac_core.InterpolationStack()
+        if yac_method == "nnn":
+            weight_type = _coerce_enum(
+                yac_core.yac_interp_nnn_weight_type,
+                yac_kwargs.get("reduction_type", yac_kwargs.get("nnn_type")),
+            )
+            if weight_type is None:
+                weight_type = yac_core.yac_interp_nnn_weight_type.YAC_INTERP_NNN_AVG
+            stack.add_nnn(
+                nnn_type=weight_type,
+                n=yac_kwargs.get("n", 1),
+                max_search_distance=yac_kwargs.get("max_search_distance", 0.0),
+                scale=yac_kwargs.get("scale", 1.0),
+            )
+        elif yac_method == "average":
+            reduction_type = _coerce_enum(
+                yac_core.yac_interp_avg_weight_type,
+                yac_kwargs.get("reduction_type", yac_kwargs.get("weight_type")),
+            )
+            if reduction_type is None:
+                reduction_type = (
+                    yac_core.yac_interp_avg_weight_type.YAC_INTERP_AVG_ARITHMETIC
+                )
+            stack.add_average(
+                reduction_type=reduction_type,
+                partial_coverage=yac_kwargs.get("partial_coverage", False),
+            )
+        elif yac_method == "conservative":
+            normalisation = _coerce_enum(
+                yac_core.yac_interp_method_conserv_normalisation,
+                yac_kwargs.get("normalisation"),
+            )
+            if normalisation is None:
+                normalisation = yac_core.yac_interp_method_conserv_normalisation.YAC_INTERP_CONSERV_DESTAREA
+            stack.add_conservative(
+                order=yac_kwargs.get("order", 1),
+                enforced_conserv=yac_kwargs.get("enforced_conserv", False),
+                partial_coverage=yac_kwargs.get("partial_coverage", False),
+                normalisation=normalisation,
+            )
+            fixed_value = yac_kwargs.get("fixed_value", 0.0)
+            if fixed_value is not None:
+                stack.add_fixed(float(fixed_value))
+
+        self._weights = yac_core.compute_weights(
+            stack,
+            self._src_field,
+            self._tgt_field,
+        )
+        self._interpolations: dict[int, Any] = {}
+        self._src_size = self._src_grid.get_data_size(self._src_location)
+        self._tgt_size = self._tgt_grid.get_data_size(self._tgt_location)
+
+    def apply(
+        self, values: np.ndarray, frac_mask: np.ndarray | None = None
+    ) -> np.ndarray:
+        """Apply the pre-computed interpolation weights to *values*.
+
+        The interpolation method (NNN or conservative) is determined by
+        *yac_method* passed to the constructor and is fixed for the lifetime of
+        this remapper instance.  This method simply executes the weight
+        application; it does not select or alter the interpolation algorithm.
+
+        Parameters
+        ----------
+        values : np.ndarray
+            1-D or 2-D array of source-grid values. The trailing dimension must
+            equal the number of source points registered with YAC
+            (``self._src_size``). When 2-D, the leading dimension is treated as
+            the YAC collection size and is remapped in one batched call.
+        frac_mask : np.ndarray, optional
+            Optional fractional source mask with the same shape as ``values``.
+            When provided, it is forwarded to YAC's interpolation call.
+
+        Returns
+        -------
+        np.ndarray
+            Array of remapped values on the destination grid with the same
+            number of leading collections as the input.
+        """
+        values = np.ascontiguousarray(values, dtype=np.float64)
+        if values.ndim == 1:
+            values = values.reshape(1, -1)
+        elif values.ndim != 2:
+            raise ValueError(
+                f"YAC remap expects a 1-D or 2-D array, got {values.ndim}-D input."
+            )
+        if values.shape[1] != self._src_size:
+            raise ValueError(
+                f"YAC remap expects {self._src_size} values, got {values.shape[1]}."
+            )
+
+        if frac_mask is not None:
+            frac_mask = np.ascontiguousarray(frac_mask, dtype=np.float64)
+            if frac_mask.ndim == 1:
+                frac_mask = frac_mask.reshape(1, -1)
+            elif frac_mask.ndim != 2:
+                raise ValueError(
+                    "YAC fractional mask expects a 1-D or 2-D array, "
+                    f"got {frac_mask.ndim}-D input."
+                )
+            if frac_mask.shape != values.shape:
+                raise ValueError(
+                    "YAC fractional mask must match remap input shape. "
+                    f"Got mask shape {frac_mask.shape} and value shape {values.shape}."
+                )
+
+        collection_size = values.shape[0]
+        interpolation = self._interpolations.get(collection_size)
+        if interpolation is None:
+            interpolation = self._weights.get_interpolation(
+                collection_size=collection_size,
+                frac_mask_fallback_value=self._frac_mask_fallback_value,
+            )
+            self._interpolations[collection_size] = interpolation
+
+        out = (
+            interpolation(values, frac_mask=frac_mask)
+            if frac_mask is not None
+            else interpolation(values)
+        )
+        return np.asarray(out, dtype=np.float64)
+
+
+def _prepare_frac_mask(frac_mask, da_t, src_values, src_dim: str) -> np.ndarray:
+    """Normalize a fractional mask to the flattened shape expected by YAC."""
+    if hasattr(frac_mask, "dims"):
+        other_dims = [d for d in da_t.dims if d != src_dim]
+        frac_mask_values = np.asarray(frac_mask.transpose(*other_dims, src_dim).values)
+    else:
+        frac_mask_values = np.asarray(frac_mask)
+
+    if frac_mask_values.shape != src_values.shape:
+        raise ValueError(
+            "YAC fractional mask must match the remapped source variable shape. "
+            f"Got mask shape {frac_mask_values.shape} and source shape {src_values.shape}."
+        )
+    return frac_mask_values.reshape(-1, frac_mask_values.shape[-1])
+
+
+def _yac_remap(source, destination_grid, remap_to: str, yac_method: str, yac_kwargs):
+    """Remap a UXarray object through YAC and reconstruct the UXarray result.
+
+    This is the main integration boundary between the public UXarray remap
+    accessor and the lower-level ``yac.core`` bindings. It normalizes the
+    requested YAC method, validates method-specific constraints, batches each
+    remapped variable by its source dimension, and returns a remapped
+    ``UxDataArray`` or ``UxDataset`` with UXarray metadata preserved.
+    """
+    _assert_dimension(remap_to)
+    destination_dim = LABEL_TO_COORD[remap_to]
+    options = _normalize_yac_method(yac_method)
+    options.kwargs.update(yac_kwargs or {})
+    ds, is_da, name = _to_dataset(source)
+    dims_to_remap = _get_remap_dims(ds)
+
+    if options.method == "conservative":
+        if destination_dim != "n_face":
+            raise ValueError(
+                "YAC conservative remapping requires the destination to be "
+                "face-centered (remap_to='faces'). "
+                f"Got remap_to={remap_to!r} which maps to dimension {destination_dim!r}."
+            )
+        non_face_src = dims_to_remap - {"n_face"}
+        if non_face_src:
+            raise ValueError(
+                "YAC conservative remapping requires all source data to be "
+                f"face-centered (dimension 'n_face'). "
+                f"Found non-face source dimension(s): {non_face_src}. "
+                "Use yac_method='nnn' for node- or edge-centered data."
+            )
+    remappers: dict[str, _YacRemapper] = {}
+    remapped_vars = {}
+
+    for src_dim in dims_to_remap:
+        remappers[src_dim] = _YacRemapper(
+            ds.uxgrid,
+            destination_grid,
+            src_dim,
+            destination_dim,
+            options.method,
+            options.kwargs,
+        )
+
+    for var_name, da in ds.data_vars.items():
+        src_dim = next((d for d in da.dims if d in dims_to_remap), None)
+        if src_dim is None:
+            remapped_vars[var_name] = da
+            continue
+
+        other_dims = [d for d in da.dims if d != src_dim]
+        da_t = da.transpose(*other_dims, src_dim)
+        src_values = np.asarray(da_t.values)
+        flat_src = src_values.reshape(-1, src_values.shape[-1])
+        frac_masks = yac_kwargs.get("frac_masks")
+        frac_mask = (
+            frac_masks.get(var_name)
+            if isinstance(frac_masks, dict) and var_name in frac_masks
+            else yac_kwargs.get("frac_mask")
+        )
+        flat_frac_mask = None
+        if frac_mask is not None:
+            flat_frac_mask = _prepare_frac_mask(frac_mask, da_t, src_values, src_dim)
+        remapper = remappers[src_dim]
+        out_flat = remapper.apply(flat_src, frac_mask=flat_frac_mask)
+
+        out_shape = src_values.shape[:-1] + (remapper._tgt_size,)
+        out_values = out_flat.reshape(out_shape)
+        coords = {dim: da.coords[dim] for dim in other_dims if dim in da.coords}
+        da_out = uxarray.core.dataarray.UxDataArray(
+            out_values,
+            dims=other_dims + [destination_dim],
+            coords=coords,
+            name=da.name,
+            attrs=da.attrs,
+            uxgrid=destination_grid,
+        )
+        remapped_vars[var_name] = da_out
+
+    ds_remapped = _construct_remapped_ds(
+        source, remapped_vars, destination_grid, remap_to
+    )
+    return ds_remapped[name] if is_da else ds_remapped

{uxarray-2026.3.0 → uxarray-2026.4.1}/uxarray.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uxarray
-Version: 2026.3.0
+Version: 2026.4.1
 Summary: Xarray extension for unstructured climate and global weather data analysis and visualization.
 License:                                  Apache License
                                    Version 2.0, January 2004

{uxarray-2026.3.0 → uxarray-2026.4.1}/uxarray.egg-info/SOURCES.txt

@@ -80,6 +80,7 @@ uxarray/remap/inverse_distance_weighted.py
 uxarray/remap/nearest_neighbor.py
 uxarray/remap/spatial_coords_remap.py
 uxarray/remap/utils.py
+uxarray/remap/yac.py
 uxarray/subset/__init__.py
 uxarray/subset/dataarray_accessor.py
 uxarray/subset/grid_accessor.py

uxarray-2026.3.0/uxarray/remap/accessor.py

@@ -1,112 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from uxarray.core.dataarray import UxDataArray
-    from uxarray.core.dataset import UxDataset
-    from uxarray.grid.grid import Grid
-
-from uxarray.remap.bilinear import _bilinear
-from uxarray.remap.inverse_distance_weighted import _inverse_distance_weighted_remap
-from uxarray.remap.nearest_neighbor import _nearest_neighbor_remap
-
-
-class RemapAccessor:
-    """Expose remapping methods on UxDataArray and UxDataset objects."""
-
-    def __init__(self, ux_obj: UxDataArray | UxDataset):
-        self.ux_obj = ux_obj
-
-    def __repr__(self) -> str:
-        prefix = f"<{type(self.ux_obj).__name__}.remap>\n"
-        return (
-            prefix
-            + "Supported methods:\n"
-            + "  • nearest_neighbor(destination_grid, remap_to='faces')\n"
-            + "  • inverse_distance_weighted(destination_grid, remap_to='faces', power=2, k=8)\n"
-        )
-
-    def __call__(self, *args, **kwargs) -> UxDataArray | UxDataset:
-        """
-        Shortcut for nearest-neighbor remapping.
-
-        Calling `.remap(...)` with no explicit method will invoke
-        `nearest_neighbor(...)`.
-        """
-        return self.nearest_neighbor(*args, **kwargs)
-
-    def nearest_neighbor(
-        self, destination_grid: Grid, remap_to: str = "faces", **kwargs
-    ) -> UxDataArray | UxDataset:
-        """
-        Perform nearest-neighbor remapping.
-
-        Each destination point takes the value of its closest source point.
-
-        Parameters
-        ----------
-        destination_grid : Grid
-            The UXarray grid to which data will be interpolated.
-        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
-            Which grid element receives the remapped values.
-
-        Returns
-        -------
-        UxDataArray or UxDataset
-            A new object with data mapped onto `destination_grid`.
-        """
-
-        return _nearest_neighbor_remap(self.ux_obj, destination_grid, remap_to)
-
-    def inverse_distance_weighted(
-        self, destination_grid: Grid, remap_to: str = "faces", power=2, k=8, **kwargs
-    ) -> UxDataArray | UxDataset:
-        """
-        Perform inverse-distance-weighted (IDW) remapping.
-
-        Each destination point is a weighted average of nearby source points,
-        with weights proportional to 1/(distance**power).
-
-        Parameters
-        ----------
-        destination_grid : Grid
-            The UXarray grid to which data will be interpolated.
-        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
-            Which grid element receives the remapped values.
-        power : int, default=2
-            Exponent controlling distance decay. Larger values make the
-            interpolation more local.
-        k : int, default=8
-            Number of nearest source points to include in the weighted average.
-
-        Returns
-        -------
-        UxDataArray or UxDataset
-            A new object with data mapped onto `destination_grid`.
-        """
-
-        return _inverse_distance_weighted_remap(
-            self.ux_obj, destination_grid, remap_to, power, k
-        )
-
-    def bilinear(
-        self, destination_grid: Grid, remap_to: str = "faces", **kwargs
-    ) -> UxDataArray | UxDataset:
-        """
-        Perform bilinear remapping.
-
-        Parameters
-        ---------
-        destination_grid : Grid
-            Destination Grid for remapping
-        remap_to : {'nodes', 'edges', 'faces'}, default='faces'
-            Which grid element receives the remapped values.
-
-        Returns
-        -------
-        UxDataArray or UxDataset
-            A new object with data mapped onto `destination_grid`.
-        """
-
-        return _bilinear(self.ux_obj, destination_grid, remap_to)