uxarray 2026.4.0__tar.gz → 2026.6.0__tar.gz

{uxarray-2026.4.0 → uxarray-2026.6.0}/PKG-INFO

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

{uxarray-2026.4.0 → uxarray-2026.6.0}/uxarray/__init__.py

@@ -1,3 +1,4 @@
+from . import tutorial
 from .constants import INT_DTYPE, INT_FILL_VALUE
 from .core.api import (
     concat,
@@ -30,6 +31,7 @@ __all__ = (
     "open_multigrid",
     "list_grid_names",
     "concat",
+    "tutorial",
     "UxDataset",
     "UxDataArray",
     "INT_DTYPE",

{uxarray-2026.4.0 → uxarray-2026.6.0}/uxarray/core/dataarray.py

@@ -24,6 +24,7 @@ from uxarray.core.utils import _map_dims_to_ugrid
 from uxarray.core.zonal import (
     _compute_conservative_zonal_mean_bands,
     _compute_non_conservative_zonal_mean,
+    _compute_zonal_anomaly,
 )
 from uxarray.cross_sections import UxDataArrayCrossSectionAccessor
 from uxarray.formatting_html import array_repr
@@ -465,12 +466,7 @@ class UxDataArray(xr.DataArray):
         else:
 
             def _is_default_extent() -> bool:
-                # Default extents are indicated by xlim/ylim being (0, 1)
-                # when autoscale is still on (no extent has been explicitly set)
-                if not ax.get_autoscale_on():
-                    return False
-                xlim, ylim = ax.get_xlim(), ax.get_ylim()
-                return np.allclose(xlim, (0.0, 1.0)) and np.allclose(ylim, (0.0, 1.0))
+                return ax.get_autoscale_on()
 
             if _is_default_extent():
                 try:
@@ -772,6 +768,70 @@ class UxDataArray(xr.DataArray):
         """Alias of zonal_mean; prefer `zonal_mean` for primary API."""
         return self.zonal_mean(lat=lat, conservative=conservative, **kwargs)
 
+    def zonal_anomaly(self, lat=(-90, 90, 10), conservative: bool = False):
+        """Compute the zonal anomaly: each face value minus the mean of its latitude band.
+
+        Returns a new ``UxDataArray`` with the same dimensions as the input,
+        where each face holds its original value minus the zonal mean of the
+        latitude band it belongs to.
+
+        Parameters
+        ----------
+        lat : tuple or array-like, default=(-90, 90, 10)
+            Latitude band specification:
+                - tuple (start, end, step): band edges via np.linspace(start, end, n)
+                - array-like: explicit band edges in degrees
+        conservative : bool, default=False
+            If True, uses area-weighted band means and blends across bands for
+            faces that straddle a band boundary, reusing the face-band weight
+            matrix computed for zonal_mean so no geometry is duplicated.
+            If False, assigns each face to a band by its centroid latitude.
+
+        Returns
+        -------
+        UxDataArray
+            Same dimensions as input with per-face band mean subtracted.
+
+        Examples
+        --------
+        >>> uxds["var"].zonal_anomaly()
+        >>> uxds["var"].zonal_anomaly(lat=(-60, 60, 5), conservative=True)
+        """
+        if not self._face_centered():
+            raise ValueError(
+                "Zonal anomaly is only supported for face-centered data variables."
+            )
+
+        if isinstance(lat, tuple):
+            start, end, step = lat
+            if step <= 0:
+                raise ValueError("Step size must be positive.")
+            num_points = int(round((end - start) / step)) + 1
+            edges = np.linspace(start, end, num_points)
+            edges = np.clip(edges, -90, 90)
+        elif isinstance(lat, (list, np.ndarray)):
+            edges = np.asarray(lat, dtype=float)
+        else:
+            raise ValueError(
+                "Invalid value for 'lat'. Must be a tuple (start, end, step) or array-like band edges."
+            )
+
+        if edges.ndim != 1 or edges.size < 2:
+            raise ValueError("Band edges must be 1D with at least two values.")
+
+        res = _compute_zonal_anomaly(self, edges, conservative=conservative)
+
+        return UxDataArray(
+            res,
+            dims=self.dims,
+            coords=self.coords,
+            name=self.name + "_zonal_anomaly"
+            if self.name is not None
+            else "zonal_anomaly",
+            attrs={"zonal_anomaly": True, "conservative": conservative},
+            uxgrid=self.uxgrid,
+        )
+
     def azimuthal_mean(
         self,
         center_coord,
@@ -1416,10 +1476,15 @@ class UxDataArray(xr.DataArray):
         """
         return _uxda_grid_aggregate(self, destination, "any", **kwargs)
 
-    def gradient(self, **kwargs) -> UxDataset:
+    def gradient(self, scale_by_radius: bool = True, **kwargs) -> UxDataset:
         """
         Computes the gradient of a data variable.
 
+        Parameters
+        ----------
+        scale_by_radius : bool, default=True
+            Divide unit-sphere derivatives by ``uxgrid.sphere_radius``.
+
         Returns
         -------
         gradient: UxDataset
@@ -1446,7 +1511,9 @@ class UxDataArray(xr.DataArray):
             )
 
         # Compute the zonal and meridional gradient components of the stored data variable
-        grad_zonal_da, grad_meridional_da = _compute_gradient(self)
+        grad_zonal_da, grad_meridional_da = _compute_gradient(
+            self, scale_by_radius=scale_by_radius
+        )
 
         # Create a dataset containing both gradient components
         return UxDataset(
@@ -1459,7 +1526,9 @@ class UxDataArray(xr.DataArray):
             coords=self.coords,
         )
 
-    def curl(self, other: "UxDataArray", **kwargs) -> "UxDataArray":
+    def curl(
+        self, other: "UxDataArray", scale_by_radius: bool = True, **kwargs
+    ) -> "UxDataArray":
         """
         Computes the curl of a vector field.
 
@@ -1469,6 +1538,8 @@ class UxDataArray(xr.DataArray):
             The second component of the vector field. This UxDataArray should
             represent the meridional (v) component, while self represents the
             zonal (u) component.
+        scale_by_radius : bool, default=True
+            Divide unit-sphere derivatives by ``uxgrid.sphere_radius``.
         **kwargs : dict
             Additional keyword arguments (currently unused, reserved for future extensions).
 
@@ -1519,21 +1590,30 @@ class UxDataArray(xr.DataArray):
             )
 
         # Compute gradients of both components
-        grad_u_zonal, grad_u_meridional = _compute_gradient(self)
-        grad_v_zonal, grad_v_meridional = _compute_gradient(other)
+        grad_u_zonal, grad_u_meridional = _compute_gradient(
+            self, scale_by_radius=scale_by_radius
+        )
+        grad_v_zonal, grad_v_meridional = _compute_gradient(
+            other, scale_by_radius=scale_by_radius
+        )
 
         # Compute curl = ∂v/∂x - ∂u/∂y
         curl_values = grad_v_zonal.values - grad_u_meridional.values
 
+        u_units = self.attrs.get("units", "")
+        has_sphere_radius = "sphere_radius" in self.uxgrid._ds.attrs
+        if scale_by_radius and has_sphere_radius:
+            curl_units = f"({u_units})/m" if u_units else "1/s"
+        else:
+            curl_units = f"({u_units})/rad" if u_units else "1/rad"
+
         # Create the result UxDataArray
         curl_da = UxDataArray(
             curl_values,
             dims=self.dims,
             attrs={
                 "long_name": f"Curl of ({self.name}, {other.name})",
-                "units": "1/s"
-                if "units" not in self.attrs
-                else f"({self.attrs.get('units', '1')})/m",
+                "units": curl_units,
                 "description": "Curl of vector field computed as ∂v/∂x - ∂u/∂y",
             },
             uxgrid=self.uxgrid,
@@ -1619,6 +1699,65 @@ class UxDataArray(xr.DataArray):
 
         return divergence_da
 
+    def scalardotgradient(self, v: "UxDataArray", q: "UxDataArray") -> "UxDataArray":
+        """
+        Compute the dot product between a vector field and the gradient of a scalar field.
+
+        Parameters
+        ----------
+        v : UxDataArray
+            The meridional component of the vector field. ``self`` is treated as
+            the zonal component.
+        q : UxDataArray
+            Scalar field whose gradient is dotted with the vector field.
+
+        Returns
+        -------
+        scalar_dot_gradient : UxDataArray
+            Dot product ``self * dq/dx + v * dq/dy``.
+        """
+        if not isinstance(v, UxDataArray):
+            raise TypeError("v must be a UxDataArray")
+
+        if not isinstance(q, UxDataArray):
+            raise TypeError("q must be a UxDataArray")
+
+        if self.uxgrid != v.uxgrid or self.uxgrid != q.uxgrid:
+            raise ValueError("All UxDataArrays must have the same grid")
+
+        if self.dims != v.dims or self.dims != q.dims:
+            raise ValueError("All UxDataArrays must have the same dimensions")
+
+        if self.ndim > 1:
+            raise ValueError(
+                "Scalar dot gradient currently requires 1D face-centered data. "
+                "Consider selecting a single slice before computing."
+            )
+
+        if not (self._face_centered() and v._face_centered() and q._face_centered()):
+            raise ValueError(
+                "Computing the scalar dot gradient is only supported for face-centered data variables."
+            )
+
+        # Validate coordinate alignment up-front so a misaligned input fails
+        # before the (potentially expensive) gradient call.
+        u_aligned, v_aligned, q_aligned = xr.align(self, v, q, join="exact", copy=False)
+
+        q_gradient = q_aligned.gradient()
+        q_zonal = q_gradient["zonal_gradient"]
+        q_meridional = q_gradient["meridional_gradient"]
+
+        scalar_dot_gradient = (u_aligned * q_zonal) + (v_aligned * q_meridional)
+        scalar_dot_gradient.name = "scalar_dot_gradient"
+        scalar_dot_gradient.attrs.update(
+            {
+                "long_name": "scalar dot gradient",
+                "description": "Dot product u * (dq/dx) + v * (dq/dy).",
+            }
+        )
+
+        return UxDataArray(scalar_dot_gradient, uxgrid=self.uxgrid)
+
     def difference(self, destination: str | None = "edge"):
         """Computes the absolute difference of a data variable.
 

{uxarray-2026.4.0 → uxarray-2026.6.0}/uxarray/core/dataset.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import os
 import sys
 from html import escape
-from typing import IO, Any, Mapping
+from typing import IO, Any, Hashable, Mapping
 from warnings import warn
 
 import numpy as np
@@ -621,11 +621,32 @@ class UxDataset(xr.Dataset):
 
         return integral
 
-    def to_array(self) -> UxDataArray:
-        """Override to make the result an instance of
-        ``uxarray.UxDataArray``."""
+    def to_array(
+        self,
+        dim: Hashable = "variable",
+        name: Hashable = None,
+    ) -> UxDataArray:
+        """Convert this ``uxarray.UxDataset`` into a ``uxarray.UxDataArray``,
+        attaching this UxDataset's uxgrid to the result.
+
+        Similarly to xarray.Dataset.to_array(), the data variables will be
+        broadcast against each other and stacked along the first axis of
+        the new array. All coordinates of this dataset will remain coordinates.
+
+        Parameters
+        ----------
+        dim : Hashable, optional
+            Name of the new dimension. Defaults to "variable"
+        name : Hashable or None, optional
+            Name of the new data array.
+
+        Returns
+        -------
+        UxDataArray
+            The ``uxarray.UxDataset`` represented as a ``uxarray.UxDataArray``
+        """
 
-        xarr = super().to_array()
+        xarr = super().to_array(dim=dim, name=name)
         return UxDataArray(xarr, uxgrid=self.uxgrid)
 
     def to_xarray(self, grid_format: str = "UGRID") -> xr.Dataset:

{uxarray-2026.4.0 → uxarray-2026.6.0}/uxarray/core/gradient.py

@@ -1,3 +1,5 @@
+import warnings
+
 import numpy as np
 from numba import njit, prange
 
@@ -88,7 +90,7 @@ def _check_node_on_boundary_and_gather_node_neighbors(
     return bool_bdy, node_neighbors[0:num_node_neighbors]
 
 
-def _compute_gradient(data):
+def _compute_gradient(data, scale_by_radius=True):
     from uxarray import UxDataArray
 
     uxgrid = data.uxgrid
@@ -186,15 +188,38 @@ def _compute_gradient(data):
             "Computing the gradient is only supported for face-centered data variables."
         )
 
+    has_sphere_radius = "sphere_radius" in uxgrid._ds.attrs
+    if scale_by_radius:
+        if has_sphere_radius:
+            radius = uxgrid.sphere_radius
+            grad_zonal = grad_zonal / radius
+            grad_meridional = grad_meridional / radius
+        else:
+            warnings.warn(
+                "scale_by_radius=True but the grid has no 'sphere_radius' "
+                "attribute; result is left on the unit sphere. Set "
+                "uxgrid.sphere_radius or pass scale_by_radius=False.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    base_units = data.attrs.get("units", "")
+    if scale_by_radius and has_sphere_radius:
+        grad_units = f"{base_units}/m" if base_units else "1/m"
+    else:
+        grad_units = f"{base_units}/rad" if base_units else "1/rad"
+
     # Zonal
     grad_zonal_da = UxDataArray(
         data=grad_zonal, name="zonal_gradient", dims=data.dims, uxgrid=uxgrid
     )
+    grad_zonal_da.attrs["units"] = grad_units
 
     # Meridional
     grad_meridional_da = UxDataArray(
         data=grad_meridional, name="meridional_gradient", dims=data.dims, uxgrid=uxgrid
     )
+    grad_meridional_da.attrs["units"] = grad_units
 
     return grad_zonal_da, grad_meridional_da