Merge branch 'main' into gradient

Author: philipc2

test/test_grid.py

@@ -885,3 +885,22 @@ def test_from_topology():
         face_node_connectivity=face_node_connectivity,
         fill_value=-1,
     )
+
+
+def test_sphere_radius_mpas_ocean():
+    """Test sphere radius functionality with MPAS ocean mesh."""
+    # Test with MPAS ocean mesh file
+    mpas_ocean_file = current_path / "meshfiles" / "mpas" / "QU" / "oQU480.231010.nc"
+    grid = ux.open_grid(mpas_ocean_file)
+
+    # Check that MPAS sphere radius is preserved (Earth's radius)
+    assert np.isclose(grid.sphere_radius, 6371229.0, rtol=1e-10)
+
+    # Test setting a new radius
+    new_radius = 1000.0
+    grid.sphere_radius = new_radius
+    assert np.isclose(grid.sphere_radius, new_radius, rtol=1e-10)
+
+    # Test invalid radius
+    with pytest.raises(ValueError, match="Sphere radius must be positive"):
+        grid.sphere_radius = -1.0

uxarray/grid/grid.py

@@ -113,6 +113,10 @@ class Grid:
     For constructing a grid from non-UGRID datasets or other types of supported data, see our ``ux.open_grid`` method or
     specific class methods (``Grid.from_dataset``, ``Grid.from_face_verticies``, etc.)
 
+    Note on Sphere Radius:
+        All internal calculations use a unit sphere (radius=1.0). The physical sphere radius
+        from the source grid is preserved in the ``sphere_radius`` property for scaling results.
+
 
     Parameters
     ----------
@@ -2030,6 +2034,39 @@ def normalize_cartesian_coordinates(self):
             self._ds[f"{prefix}_y"] = dy / norm
             self._ds[f"{prefix}_z"] = dz / norm
 
+    @property
+    def sphere_radius(self) -> float:
+        """Physical sphere radius from the source grid (e.g., Earth's radius for MPAS ocean grids).
+
+        Internally, all calculations use a unit sphere. This property stores the original
+        radius for scaling results back to physical units.
+
+        Returns
+        -------
+        sphere_radius : float
+            The physical sphere radius. Defaults to 1.0 if not set.
+        """
+        return self._ds.attrs.get("sphere_radius", 1.0)
+
+    @sphere_radius.setter
+    def sphere_radius(self, radius: float) -> None:
+        """Set the sphere radius for the grid.
+
+        Parameters
+        ----------
+        radius : float
+            The sphere radius to set. Must be positive.
+
+        Raises
+        ------
+        ValueError
+            If radius is not positive.
+        """
+        if radius <= 0:
+            raise ValueError(f"Sphere radius must be positive, got {radius}")
+
+        self._ds.attrs["sphere_radius"] = radius
+
     def to_xarray(self, grid_format: Optional[str] = "ugrid"):
         """Returns an ``xarray.Dataset`` with the variables stored under the
         ``Grid`` encoded in a specific grid format.