uxarray 2026.9.0__tar.gz → 2026.10.0__tar.gz

{uxarray-2026.9.0 → uxarray-2026.10.0}/MANIFEST.in

@@ -2,6 +2,7 @@ include LICENSE
 include README.md
 
 recursive-include uxarray *.py
+include uxarray/py.typed
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 exclude .gitignore

{uxarray-2026.9.0 → uxarray-2026.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uxarray
-Version: 2026.9.0
+Version: 2026.10.0
 Summary: Xarray extension for unstructured climate and global weather data analysis and visualization.
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -220,38 +220,41 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: antimeridian
-Requires-Dist: cartopy
-Requires-Dist: dask[dataframe]
-Requires-Dist: datashader
-Requires-Dist: geoviews
-Requires-Dist: holoviews
-Requires-Dist: matplotlib<3.11
-Requires-Dist: matplotlib-inline
-Requires-Dist: netcdf4
+Requires-Dist: antimeridian>=0.3.0
+Requires-Dist: dask[dataframe]>=2024.12.0
+Requires-Dist: netcdf4>=1.7.0
 Requires-Dist: numba>=0.63
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: pyarrow
-Requires-Dist: requests
-Requires-Dist: scikit-learn
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: scikit-learn>=1.4.2
 Requires-Dist: scipy
-Requires-Dist: shapely
-Requires-Dist: spatialpandas
-Requires-Dist: geopandas>=1.0
-Requires-Dist: xarray
-Requires-Dist: hvplot
-Requires-Dist: healpix
-Requires-Dist: polars
-Requires-Dist: pyproj
+Requires-Dist: shapely>=2.0.6
+Requires-Dist: xarray>=2024.10.0
+Requires-Dist: polars>=0.20.4
+Provides-Extra: all
+Requires-Dist: uxarray[dev,geo,viz]; extra == "all"
 Provides-Extra: complete
-Requires-Dist: uxarray[dev]; extra == "complete"
+Requires-Dist: uxarray[dev,geo,viz]; extra == "complete"
 Provides-Extra: dev
+Requires-Dist: asv; extra == "dev"
+Requires-Dist: pooch; extra == "dev"
 Requires-Dist: pre_commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
-Requires-Dist: asv; extra == "dev"
+Provides-Extra: geo
+Requires-Dist: cartopy>=0.23; extra == "geo"
+Requires-Dist: geopandas>=1.0; extra == "geo"
+Requires-Dist: healpix>=2024.2; extra == "geo"
+Requires-Dist: pyproj; extra == "geo"
+Requires-Dist: spatialpandas>=0.4.10; extra == "geo"
+Provides-Extra: viz
+Requires-Dist: cartopy<0.26,>=0.23; extra == "viz"
+Requires-Dist: datashader; extra == "viz"
+Requires-Dist: matplotlib<3.11,>=3.8.4; extra == "viz"
+Requires-Dist: geoviews>=1.11.0; extra == "viz"
+Requires-Dist: holoviews>=1.19.0; extra == "viz"
+Requires-Dist: hvplot>=0.8.3; extra == "viz"
 Dynamic: license-file
 
 

uxarray-2026.10.0/pyproject.toml

@@ -0,0 +1,117 @@
+[project]
+classifiers=[
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+dynamic = ["version"]
+keywords = ["unstructured grids", "xarray", "ugrid", "mpas", "exodus", "scrip", "fesom", "icon", "esmf"]
+description = "Xarray extension for unstructured climate and global weather data analysis and visualization."
+license = {file = "LICENSE"}
+name = "uxarray"
+readme = "README.md"
+requires-python = ">=3.11"
+
+# minimal dependencies start
+# Lower bounds are added only for a known failure with an older release; the
+# comment on each says what breaks.  The "Minimum Dependencies" CI workflow
+# tests the oldest versions these bounds allow and opens an issue when they
+# fail, which is how new bounds get found.
+dependencies = [
+  "antimeridian>=0.3.0",  # fix_polygon(fix_winding=...) is new in 0.3.0.
+  "dask[dataframe]>=2024.12.0",  # older dd.from_dask_array() fails on empty arrays (empty SCRIP grids).
+  "netcdf4>=1.7.0",  # older releases are built against numpy 1 and fail to import under numpy 2.
+  "numba>=0.63",  # 0.63 is the first release supporting Python 3.14 (3.10 <= py < 3.15). See #1561.
+  "numpy>=2.0",  # np.asin() is new in 2.0.
+  "pandas>=2.2.2",  # older releases without a numpy<2 cap fail to import under numpy 2.
+  "scikit-learn>=1.4.2",  # older releases without a numpy<2 cap fail to import under numpy 2.
+  "scipy",
+  "shapely>=2.0.6",  # 2.0 API (shapely.polygons()); older 2.0.x fail in create_collection under numpy 2.
+  "xarray>=2024.10.0",  # older releases break resample() and dask-backed weighted_mean().
+  "polars>=0.20.4",  # DataFrame.with_row_index() is new in 0.20.4.
+]
+# minimal dependencies end
+
+[project.optional-dependencies]
+all = ["uxarray[dev,geo,viz]"]
+complete = ["uxarray[dev,geo,viz]"]  # alias to "all"
+dev = [
+    'asv',
+    'pooch',
+    'pre_commit',
+    'pytest',
+    'pytest-cov',
+    'ruff',
+]
+geo = [
+    "cartopy>=0.23",  # in both geo and viz because it is needed by to_geodataframe() and by plotting routines.
+    # (0.23 is the first release that works with numpy 2.)
+    "geopandas>=1.0",  # 1.0 is the first release requiring pyogrio, the file-IO backend read_file needs. See #1693.
+    "healpix>=2024.2",  # older releases are built against numpy 1 and fail to import under numpy 2.
+    "pyproj",
+    "spatialpandas>=0.4.10",  # PolygonArray.from_exterior_coords() is new in 0.4.10.
+]
+viz = [
+    "cartopy>=0.23,<0.26",  # cartopy 0.26.0 breaks some geoviews plots; see issue #1780.
+    # (cartopy pin intentionally here but not in "geo" extras because geoviews is only in "viz".)
+    "datashader",
+    "matplotlib>=3.8.4,<3.11",  # 3.11.0 breaks some plots (see issue #1542); older releases without a numpy<2 cap fail under numpy 2.
+    "geoviews>=1.11.0",  # older releases use np.NaN, removed in numpy 2. No upper pin; newer should support any cartopy; see holoviz/geoviews#884.
+    "holoviews>=1.19.0",  # older releases import panel.depends.param_value_if_widget, which current panel removed.
+    "hvplot>=0.8.3",  # older releases use param's .params(), removed in param 2.
+]
+
+[project.urls]
+Documentation = "https://uxarray.readthedocs.io/"
+Source = "https://github.com/UXARRAY/uxarray"
+Tracker = "https://github.com/UXARRAY/uxarray/issues"
+# please keep [project.urls] immediately after [project.optional-dependencies],
+# or, if rearranging sections, make sure to edit installation.rst accordingly.
+
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=60",
+  "setuptools-scm>=8",
+]
+
+[tool.setuptools]
+packages = ["uxarray"]
+
+[tool.setuptools.package-data]
+# PEP 561 marker. setuptools >= 69.0 adds py.typed to a wheel on its own
+# (_IMPLICIT_DATA_FILES in setuptools/command/build_py.py), but the build
+# requirement below is setuptools >= 60, and on 68.2.2 the marker is dropped
+# from the wheel unless it is declared here. Keep this until that floor is
+# raised past 69.
+uxarray = ["py.typed"]
+
+[tool.setuptools_scm]
+fallback_version = "9999"
+
+[tool.ruff]
+extend-exclude = ["test","benchmarks"]
+
+[tool.ruff.lint]
+extend-select = ["I"]
+extend-ignore = ["E731"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["uxarray"]
+
+[tool.ruff.lint.per-file-ignores]
+"docs/*" = ["E402", "F401"]
+"uxarray/plot/*" = ["E402", "F401"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+testpaths = ["test"]  # (intentionally excludes test_optional_deps)

{uxarray-2026.9.0 → uxarray-2026.10.0}/uxarray/core/accessors.py

@@ -119,7 +119,9 @@ class BaseAccessor:
 
     def _process_result(self, result):
         """Process method results to preserve uxgrid. To be overridden by subclasses."""
-        raise NotImplementedError("Subclasses must implement _process_result")
+        raise NotImplementedError(
+            f"_process_result, for BaseAccessor subclass {type(self)}"
+        )
 
     # Delegation for common dunder methods
     def __iter__(self):

{uxarray-2026.9.0 → uxarray-2026.10.0}/uxarray/core/aggregation.py

@@ -25,8 +25,8 @@ def _uxda_grid_aggregate(uxda, destination, aggregation, **kwargs):
     UxDataArray."""
     if destination is None:
         raise ValueError(
-            "Attempting to perform a topological aggregation, but no destination was provided."
-        )
+            f"Missing destination (got destination=None) in topological_{aggregation})."
+        )  # e.g. aggregation will be something like "mean", "min", "any", ...
 
     if uxda._node_centered():
         # aggregation of a node-centered data variable
@@ -36,8 +36,8 @@ def _uxda_grid_aggregate(uxda, destination, aggregation, **kwargs):
             return _node_to_edge_aggregation(uxda, aggregation, kwargs)
         else:
             raise DataCenteringError(
-                f"Invalid destination for a node-centered data variable. Expected"
-                f"one of ['face', 'edge' but received {destination}"
+                f"Node-centered data requires destination='face' or 'edge'; "
+                f"got destination={destination!r}, during topological_{aggregation}."
             )
 
     elif uxda._edge_centered():
@@ -45,29 +45,17 @@ def _uxda_grid_aggregate(uxda, destination, aggregation, **kwargs):
         raise NotImplementedError(
             "Aggregation of edge-centered data variables is not yet supported."
         )
-        # if destination == "node":
-        #     pass
-        # elif destination == "face":
-        #     pass
-        # else:
-        #     raise ValueError("TODO: )
 
     elif uxda._face_centered():
         # aggregation of a face-centered data variable
         raise NotImplementedError(
             "Aggregation of face-centered data variables is not yet supported."
         )
-        # if destination == "node":
-        #     pass
-        # elif destination == "edge":
-        #     pass
-        # else:
-        #     raise ValueError("TODO: ")
 
     else:
         raise DataCenteringError(
-            "Invalid data mapping. Data variable is expected to be mapped to either the "
-            "nodes, faces, or edges of the source grid."
+            f"topological_{aggregation} expected data mapped to nodes, edges, or faces; "
+            f"got array with array.data_mapping={uxda.data_mapping!r} and array.dims={uxda.dims!r}."
         )
 
 
@@ -77,8 +65,8 @@ def _node_to_face_aggregation(uxda, aggregation, aggregation_func_kwargs):
 
     if not uxda._node_centered():
         raise DataCenteringError(
-            f"Data Variable must be mapped to the corner nodes of each face, with dimension "
-            f"{uxda.uxgrid.n_face}."
+            f"Expected node-centered data; got array with array.data_mapping={uxda.data_mapping!r} "
+            f"and array.dims={uxda.dims!r}, during node-to-face aggregation."
         )
 
     if isinstance(uxda.data, np.ndarray):
@@ -92,7 +80,9 @@ def _node_to_face_aggregation(uxda, aggregation, aggregation_func_kwargs):
             uxda, NUMPY_AGGREGATIONS[aggregation], aggregation_func_kwargs
         )
     else:
-        raise TypeError
+        raise TypeError(
+            f"Expected numpy or dask array; got type(uxda.data)={type(uxda.data)}."
+        )
 
 
 def _node_to_face_kernel(
@@ -206,8 +196,8 @@ def _node_to_edge_aggregation(uxda, aggregation, aggregation_func_kwargs):
 
     if not uxda._node_centered():
         raise DataCenteringError(
-            f"Data Variable must be mapped to the corner nodes of each face, with dimension "
-            f"{uxda.uxgrid.n_face}."
+            f"Expected node-centered data; got array with array.data_mapping={uxda.data_mapping!r} "
+            f"and array.dims={uxda.dims!r}, during node-to-edge aggregation."
         )
 
     aggregation_func = NUMPY_AGGREGATIONS[aggregation]
@@ -223,7 +213,9 @@ def _node_to_edge_aggregation(uxda, aggregation, aggregation_func_kwargs):
             uxda, aggregation_func, aggregation_func_kwargs
         )
     else:
-        raise TypeError
+        raise TypeError(
+            f"Expected numpy or dask array; got type(uxda.data)={type(uxda.data)}."
+        )
 
 
 def _node_to_edge_kernel(

{uxarray-2026.9.0 → uxarray-2026.10.0}/uxarray/core/api.py

@@ -108,8 +108,14 @@ def open_grid(
         if os.path.isfile(nod2d_path) and os.path.isfile(elem2d_path):
             grid = Grid.from_dataset(grid_filename_or_obj)
         else:
+            _missing = []
+            if not os.path.isfile(nod2d_path):
+                _missing.append("'nod2d.out'")
+            if not os.path.isfile(elem2d_path):
+                _missing.append("'elem2d.out'")
             raise FileNotFoundError(
-                f"The directory '{grid_filename_or_obj}' must contain both 'nod2d.out' and 'elem2d.out'."
+                "open_grid(directory) expects FESOM2 ASCII dataset with 'nod2d.out' and 'elem2d.out' files, but "
+                f"got directory={os.path.abspath(grid_filename_or_obj)!r}, which is missing {' and '.join(_missing)}."
             )
 
     elif isinstance(grid_filename_or_obj, dict):
@@ -190,6 +196,12 @@ def open_multigrid(
             mask_ds = xr.open_dataset(mask_filename)
             mask_ds_opened = True
 
+    # human-readable str telling what was provided to open_multigrid(). Useful for error messages.
+    if isinstance(grid_filename_or_obj, (str, os.PathLike)):
+        _provided_input_str = f"file, {os.path.abspath(grid_filename_or_obj)!r}"
+    else:
+        _provided_input_str = type(grid_filename_or_obj).__name__
+
     try:
         active_value_map: Mapping[str, MaskValue] | None = (
             mask_active_value if isinstance(mask_active_value, Mapping) else None
@@ -238,8 +250,8 @@ def open_multigrid(
         if format_type == "single_scrip":
             if gridnames is not None and "grid" not in gridnames:
                 raise ValueError(
-                    f"Requested grids {gridnames} not found. "
-                    "This file contains a single grid named 'grid'."
+                    f"Requested grids (gridnames={gridnames}) not found in the provided {_provided_input_str}, "
+                    "in open_multigrid(). Only 'grid' is available in single-grid SCRIP files."
                 )
             grid_ds_ugrid, source_dims_dict = _read_scrip(grid_ds)
             return {
@@ -251,7 +263,9 @@ def open_multigrid(
             }
 
         if not grids_dict:
-            raise GridInvalidError(f"No grids detected in file: {grid_filename_or_obj}")
+            raise GridInvalidError(
+                f"Failed to detect any grids in the provided {_provided_input_str}, in open_multigrid()."
+            )
 
         available_grids = list(grids_dict.keys())
 
@@ -267,7 +281,8 @@ def open_multigrid(
             for name in requested:
                 if name not in grids_dict:
                     raise ValueError(
-                        f"Grid '{name}' not found. Available grids: {available_grids}"
+                        f"open_multigrid() grid '{name}' not found in the provided {_provided_input_str}, "
+                        f"in open_multigrid(). Available grids: {available_grids}"
                     )
                 grids_to_load.append(name)
 
@@ -295,9 +310,14 @@ def open_multigrid(
                     active_indices = np.flatnonzero(active_mask)
                     grid = grid.isel(n_face=active_indices)
                 else:
+                    _provided_mask_str = (
+                        f"file, {os.path.abspath(mask_filename)!r}"
+                        if isinstance(mask_filename, (str, os.PathLike))
+                        else type(mask_filename).__name__
+                    )
                     warn(
-                        f"Mask variable '{mask_var}' not found in mask file; "
-                        f"grid '{grid_name}' will be returned without masking."
+                        f"Mask variable {mask_var!r} not found in the provided mask {_provided_mask_str}. "
+                        f"Grid {grid_name!r} will be returned without masking."
                     )
 
             loaded_grids[grid_name] = grid
@@ -428,7 +448,8 @@ def open_dataset(
         if isinstance(grid_filename_or_obj, (str, os.PathLike)):
             if os.path.isdir(grid_filename_or_obj):
                 raise ValueError(
-                    "ux.open_dataset() with a single directory argument is not supported. "
+                    "ux.open_dataset(arg0) with no other arguments and arg0 a single directory is not supported, "
+                    f"but got arg0 indicating path to directory: {os.path.abspath(grid_filename_or_obj)!r}."
                     "Supply a path to a grid file instead. Directory-based grids (e.g. a "
                     "FESOM2 ASCII grid) are only recognized when a separate data file is "
                     "also provided, i.e. ux.open_dataset(grid_directory, data_file)."
@@ -442,8 +463,10 @@ def open_dataset(
         elif isinstance(grid_filename_or_obj, xr.Dataset):
             ds = grid_filename_or_obj
         else:
-            raise ValueError(
-                "If filename_or_obj is omitted, grid_filename_or_obj must be a file path or xarray.Dataset."
+            raise TypeError(
+                "Expected grid_filename_or_obj to be a file path or xarray.Dataset when filename_or_obj "
+                f"is not provided, but got type(grid_filename_or_obj)={type(grid_filename_or_obj)}, "
+                "in ux.open_dataset(grid_filename_or_obj, filename_or_obj=None)."
             )
 
         uxgrid, _ = _get_grid(ds, chunks, chunk_grid, use_dual, grid_kwargs, **kwargs)

uxarray-2026.10.0/uxarray/core/arithmetic.py

@@ -0,0 +1,258 @@
+"""
+Purpose: ensures arithmetic for uxarray objects behaves as expected,
+e.g. checks for compatible uxgrids (if more than one input has a uxgrid),
+and ensure appropriate result types (e.g. xr.DataArray + UxDataArray --> UxDataArray).
+
+Includes solutions for issues #1685, #1695, #1718:
+(1685) Uxarray types dropped during ufuncs
+    Solved by appropriately defining __array_ufunc__.
+(1695) Uxarray types dropped during math with xarrays, depending on order of operations
+    Solved by explicitly overriding dunder methods like __mul__,
+    so Python's default behavior for dunder methods and subclasses triggers
+    (which just requires `uxarray_obj.__mul__ is not xarray_obj.__mul__`)
+    and dispatches to uxarray's methods instead of xarray's methods.
+    (The overridden methods just call super()'s method, because they go to _binary_op,
+    which goes to uxarray's _binary_op(), which handles types appropriately.
+    _binary_op() already handles types appropriately because it uses
+    _replace() for DataArrays, which UxDataArray already overrides, and it uses
+    _calculate_binary_op() for Datasets, which UxDataset overrides.)
+(1718) Math with multiple uxarray objects with different grids silently succeeds,
+when data dims are otherwise compatible
+    Solved by comparing uxgrids during _binary_op() if both inputs have a uxgrid,
+    and by comparing uxgrids of all inputs during __array_ufunc__,
+    if multiple inputs to __array_ufunc__ have a "uxgrid" attr.
+    (The former fixes, e.g., objA + objB; the latter fixes, e.g., np.add(objA, objB))
+
+Note:
+    Grids with n_face==1 are intentionally excluded from automatic comparisons,
+    because including them would breaks workflows operating on single faces, like:
+        arr.isel(n_face=0) < arr.isel(n_face=7)
+    The downside of not fixing this, though, is that the result's grid will match n_face==0,
+    silently dropping the n_face==7 information (as in issue #1718).
+    If isel() is ever updated to drop n_face dimension from arr.isel(n_face=0) instead,
+    should update the relevant code inside _binary_op and __array_ufunc__ below.
+"""
+
+import operator
+
+import xarray as xr
+
+from uxarray.errors import GridsMismatchError
+
+
+class UxSupportsArithmetic:
+    """Handles arithmetic overrides for uxarray objects as needed,
+    to ensure they behave as expected. E.g.:
+
+    - check for compatible uxgrids (if more than one input has a uxgrid),
+    - ensure appropriate result types (e.g. xr.DataArray + UxDataArray --> UxDataArray).
+
+
+    Expects to be placed in inheritance order *before* xarray classes,
+        e.g. UxDataArray(UxSupportsArithmetic, xr.DataArray),
+        not xr.DataArray(UxSupportsArithmetic, UxDataArray),
+    so that super() will resolve to methods from xarray.
+    """
+
+    # If strict type-checking gets turned on, it might complain about super() calls here.
+    # The fix would probably be to define a typing.Protocol parent class to inherit from.
+
+    __slots__ = ()
+
+    @property
+    def uxgrid(self):
+        """(UxSupportsArithmetic expects subclasses to implement uxgrid)"""
+        raise NotImplementedError(f"{type(self).__name__}.uxgrid")
+        # below, checks for "has a uxgrid" are written as `isinstance(obj, UxSupportsArithmetic)`,
+        # rather than checking for a uxgrid attribute, because the latter would be too permissive,
+        # e.g. hasattr(xr.DataArray(7, coords={"uxgrid": "anything"}), "uxgrid") is True.
+
+    def _binary_op(self, other, f, reflexive=False, **kw_super):
+        """returns f(self, other) (or f(other, self), if `reflexive`) for f a binary operation,
+        such as adding or multiplying. Like super()._binary_op, except that
+        if `other` has a uxgrid, first ensure it is compatible with self.uxgrid.
+        """
+        self._raise_if_grids_incompatible_during(other, f)
+        return super()._binary_op(other, f, reflexive=reflexive, **kw_super)
+
+    def _inplace_binary_op(self, other, f):
+        """returns f(self, other) for f a binary in-place operation,
+        such as A+=B. Like super()._inplace_binary_op, except that
+        if `other` has a uxgrid, first ensure it is compatible with self.uxgrid.
+        """
+        self._raise_if_grids_incompatible_during(other, f)
+        return super()._inplace_binary_op(other, f)
+
+    def _raise_if_grids_incompatible_during(self, other, f):
+        """raise GridsMismatchError if other has a uxgrid which is incompatible with self.
+        f is only used for error message, as f.__name__.
+
+        Grids are considered "compatible" here if they compare as equal,
+        OR if either grid has n_face==1 (to avoid breaking "scalar-like" workflows,
+        because isel(n_face=int) maybe should provide scalar, but currently doesn't).
+        """
+        if isinstance(other, UxSupportsArithmetic):
+            if (
+                (self.uxgrid.n_face > 1)
+                and (other.uxgrid.n_face > 1)
+                and (self.uxgrid != other.uxgrid)
+            ):
+                raise GridsMismatchError(
+                    f"A.uxgrid != B.uxgrid during binary operation {f.__name__!r}, "
+                    f"with type(A)={type(self).__name__}, type(B)={type(other).__name__}. "
+                    f"(Got A.uxgrid.sizes={self.uxgrid.sizes}; B.uxgrid.sizes={other.uxgrid.sizes}.)"
+                )
+
+    def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+        """Like super().__array_ufunc__, except that if multiple inputs have a uxgrid,
+        ensure they are all compatible, and if any outputs are xr.DataArray or xr.Dataset,
+        convert to the appropriate uxarray type (UxDataArray or UxDataset).
+
+        Grids are considered "compatible" here if they compare as equal,
+        OR if they have n_face==1 (to avoid breaking "scalar-like" workflows,
+        because isel(n_face=int) maybe should provide scalar, but currently doesn't).
+        """
+        from uxarray.core.dataarray import UxDataArray
+        from uxarray.core.dataset import UxDataset
+
+        uxgrids = [
+            (i, obj.uxgrid)
+            for i, obj in enumerate(inputs)
+            if isinstance(obj, UxSupportsArithmetic)
+        ]
+
+        # when checking for equality, and when deciding which grid to attach to result,
+        # will pretend that any grids with n_face==1 are scalars (see above).
+        nonscalar_grids = [(i, grid) for i, grid in uxgrids if grid.n_face > 1]
+
+        if len(nonscalar_grids) == 0:
+            # no nonscalar grids; keep first grid.
+            # At least one input is guaranteed to have a uxgrid, otherwise numpy
+            # would not have delegated to this method during the ufunc call.
+            j_ref, grid_ref = uxgrids[0]
+        else:
+            # At least one nonscalar grid; output grid should match it.
+            j_ref, grid_ref = nonscalar_grids[0]
+            # check that all nonscalar uxgrids are compatible:
+            if len(nonscalar_grids) > 1:
+                for j, grid in nonscalar_grids[1:]:
+                    if grid != grid_ref:
+                        raise GridsMismatchError(
+                            f"Multiple inputs to {ufunc.__name__!r} have incompatible uxgrids. "
+                            f"Got inputs[{j}].uxgrid != inputs[{j_ref}].uxgrid, for inputs "
+                            f"with types: type(inputs[{j}])={type(inputs[j])}, "
+                            f"type(inputs[{j_ref}])={type(inputs[j_ref])}."
+                        )
+        result = super().__array_ufunc__(ufunc, method, *inputs, **kwargs)
+
+        # convert any xr.DataArray / xr.Dataset outputs to appropriate uxarray type:
+        _was_tuple = isinstance(result, tuple)
+        result = list(result) if _was_tuple else [result]
+        for i, obj in enumerate(result):
+            if isinstance(obj, xr.DataArray):
+                result[i] = UxDataArray(obj, uxgrid=grid_ref)
+            elif isinstance(obj, xr.Dataset):
+                result[i] = UxDataset(obj, uxgrid=grid_ref)
+        result = tuple(result) if _was_tuple else result[0]
+        return result
+
+    # shadow dunder methods to ensure that, in case of ops with both uxarray and xarray,
+    # Python's default behavior for dunder methods and subclasses triggers.
+    # E.g., shadowing __add__ & __radd__ ensures that xarr + uxarr goes to uxarr.__radd__(xarr),
+    # instead of xarr.__add__(uxarr), so the result can actually be a UxAarray.
+    # (Just calling super()'s method is sufficient because it goes to self._binary_op,
+    # which goes to uxarray's _binary_op because self will be the uxarray object.)
+
+    def __add__(self, other):
+        return super().__add__(other)
+
+    def __radd__(self, other):
+        return super().__radd__(other)
+
+    def __sub__(self, other):
+        return super().__sub__(other)
+
+    def __rsub__(self, other):
+        return super().__rsub__(other)
+
+    def __mul__(self, other):
+        return super().__mul__(other)
+
+    def __rmul__(self, other):
+        return super().__rmul__(other)
+
+    def __pow__(self, other):
+        return super().__pow__(other)
+
+    def __rpow__(self, other):
+        return super().__rpow__(other)
+
+    def __truediv__(self, other):
+        return super().__truediv__(other)
+
+    def __rtruediv__(self, other):
+        return super().__rtruediv__(other)
+
+    def __floordiv__(self, other):
+        return super().__floordiv__(other)
+
+    def __rfloordiv__(self, other):
+        return super().__rfloordiv__(other)
+
+    def __mod__(self, other):
+        return super().__mod__(other)
+
+    def __rmod__(self, other):
+        return super().__rmod__(other)
+
+    def __and__(self, other):
+        return super().__and__(other)
+
+    def __rand__(self, other):
+        return super().__rand__(other)
+
+    def __or__(self, other):
+        return super().__or__(other)
+
+    def __ror__(self, other):
+        return super().__ror__(other)
+
+    def __xor__(self, other):
+        return super().__xor__(other)
+
+    def __rxor__(self, other):
+        return super().__rxor__(other)
+
+    def __lshift__(self, other):
+        return super().__lshift__(other)
+
+    def __rlshift__(self, other):
+        # (this isn't in super() for some reason, so use _binary_op directly)
+        return self._binary_op(other, operator.lshift, reflexive=True)
+
+    def __rshift__(self, other):
+        return super().__rshift__(other)
+
+    def __rrshift__(self, other):
+        # (this isn't in super() for some reason, so use _binary_op directly)
+        return self._binary_op(other, operator.rshift, reflexive=True)
+
+    # comparisons
+
+    def __lt__(self, other):
+        return super().__lt__(other)
+
+    def __le__(self, other):
+        return super().__le__(other)
+
+    def __gt__(self, other):
+        return super().__gt__(other)
+
+    def __ge__(self, other):
+        return super().__ge__(other)
+
+    def __eq__(self, other):
+        return super().__eq__(other)
+
+    def __ne__(self, other):
+        return super().__ne__(other)