Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions benchmarks/mpas_ocean.py
Original file line number Diff line number Diff line change
Expand Up @@ -326,6 +326,21 @@ def time_zonal_average(self, resolution):
self.uxds['bottomDepth'].zonal_mean(lat=(-45, 45, lat_step))


class AzimuthalAverage(DatasetBenchmark):
def setup(self, resolution, *args, **kwargs):
super().setup(resolution, *args, **kwargs)
# Grid caches, so only the per-ring reduction is timed
_ = self.uxds.uxgrid.face_areas
_ = self.uxds.uxgrid._get_scipy_kd_tree()

def time_azimuthal_average(self, resolution):
# 61 rings around an equatorial Atlantic point, ocean on every oQU mesh.
# Wide enough that the ring faces, not per-call overhead, set the cost.
self.uxds[data_var].azimuthal_mean(
center_coord=(-30, 0), outer_radius=60, radius_step=1
)


class ZonalAveragePeakMem:
"""Peak memory of a cold-start non-conservative zonal-mean sweep.
Uses a fresh interpreter per sample."""
Expand Down
104 changes: 104 additions & 0 deletions docs/user-guide/azimuthal-average.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -309,6 +309,110 @@
"plt.ylabel(\"Pressure [hPa]\")\n",
"plt.colorbar(label=\"T anomaly [K]\")"
]
},
{
"cell_type": "markdown",
"id": "c7dedfd2-4b78-4295-b82b-6e745dad5401",
"metadata": {},
"source": [
"## 3. Chunked (lazy) azimuthal means\n",
"Opening a dataset with `chunks` backs its variables with Dask, and `azimuthal_mean()` then returns a lazy result. The ring that each face falls in is found from the grid right away, but no data is read or averaged until the result is materialized with `.compute()`, etc.\n",
"\n",
"### Step 3.1: Build the lazy azimuthal mean\n",
"Below, the tropical cyclone fields are split into two chunks of 13 pressure levels and into chunks of 500 faces."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1eaab170-0bde-40d1-bc0f-f532eb6ae74e",
"metadata": {},
"outputs": [],
"source": [
"tcds_chunked = ux.tutorial.open_dataset(\n",
" \"ne120-tcsubset\", chunks={\"plev\": 13, \"n_face\": 500}\n",
").squeeze()\n",
"\n",
"azim_mean_T_lazy, hits_T = tcds_chunked[\"T\"].azimuthal_mean(\n",
" *args, return_hit_counts=True\n",
")\n",
"azim_mean_T_lazy"
]
},
{
"cell_type": "markdown",
"id": "aecf52fc-b85d-423b-925e-b0c266ebd840",
"metadata": {},
"source": [
"The result keeps the input's `plev` chunks and holds every radius in a single chunk. The hit counts depend only on the grid, so they are returned as a NumPy-backed array.\n",
"\n",
"### Step 3.2: Compute the result\n",
"Computing the lazy mean gives the same profile as the in-memory calculation in Step 2.2."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "26d96040-dae1-46a2-a963-edc036ba315a",
"metadata": {},
"outputs": [],
"source": [
"azim_mean_T_lazy = azim_mean_T_lazy.compute()\n",
"np.testing.assert_allclose(azim_mean_T_lazy, azim_mean_T)"
]
},
{
"cell_type": "markdown",
"id": "73a981b1-44ec-46e2-9c5c-96457b3124a1",
"metadata": {},
"source": [
"### Step 3.3: Estimate the memory of a task\n",
"Each input `n_face` chunk is reduced to partial ring sums on its own, and the partial sums are then added up. So no task holds more than one input chunk, or one set of partial sums: a float64 value per radius for each chunk of the other dimensions."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "89a01550-12f7-4be9-901c-8ff56bdce419",
"metadata": {},
"outputs": [],
"source": [
"face_chunk = max(tcds_chunked[\"T\"].chunksizes[\"n_face\"])\n",
"plev_chunk = max(tcds_chunked[\"T\"].chunksizes[\"plev\"])\n",
"n_radius = azim_mean_T_lazy.sizes[\"radius\"]\n",
"chunk_bytes = face_chunk * plev_chunk * tcds_chunked[\"T\"].dtype.itemsize\n",
"sums_bytes = n_radius * plev_chunk * 8\n",
"print(\n",
" f\"input chunk: {face_chunk} faces x {plev_chunk} levels = {chunk_bytes / 1e3:.1f} kB\"\n",
")\n",
"print(\n",
" f\"partial sums: {n_radius} radii x {plev_chunk} levels = {sums_bytes / 1e3:.1f} kB\"\n",
")"
]
},
{
"cell_type": "markdown",
"id": "588099b7-2665-40a1-9b63-c49cc635c9a0",
"metadata": {},
"source": [
"### Notes on lazy execution and memory\n",
"- **Dask-backed data** (opened with `chunks=`, or after `.chunk()`): `azimuthal_mean()` builds a task graph and returns immediately. When it is computed, only the input `n_face` chunks that contain a face within `outer_radius` are read, and each of those is read in full, so smaller `n_face` chunks read less data around a small ring.\n",
"- **Lazily loaded data without Dask** (the default for `ux.open_dataset()`): the faces within `outer_radius` are read when `azimuthal_mean()` is called, for every time step and level. They are read as a few contiguous slices that cover at most twice as many faces as were selected, and the result is held in memory.\n",
"- **In-memory data**: the result is computed immediately.\n",
"- The grid's face centers and face areas are always loaded to find the rings; only the data variable is lazy.\n",
"- **Memory**: each input `n_face` chunk is reduced to partial ring sums separately, and the partial sums are added up in a tree, so a task holds at most one input chunk or one set of partial sums (Step 3.3), however large `outer_radius` is. Smaller chunks, along `n_face` or the other dimensions, lower that bound, at the cost of more tasks.\n",
"\n",
"### Numerical and boundary behavior\n",
"- Faces are binned by the straight-line (chord) distance $d$ from the center point to their face center, compared in float64: a face is in the ring at radius $r_i$ when $r_{i-1} < d \\le r_i$. A face center that lies on a ring boundary counts toward the inner ring. Earlier releases found each ring with a separate kd-tree query, whose rounding could put such a face in the neighboring ring or leave it out at `outer_radius`, so hit counts and means can differ slightly for rings with faces on their boundaries.\n",
"- Away from ring boundaries, the means agree with earlier releases to floating-point rounding (about $10^{-7}$ and $10^{-15}$ relative for single and double precision, respectively), since each ring's weighted sum is now added up in a different order. Chunked inputs add up a partial sum per `n_face` chunk, so their means can differ from in-memory ones by floating-point rounding. The result is float64, including for float32 data.\n",
"- The ring at radius 0 only holds a face whose center coincides with the center point, so it is usually empty. Empty rings, and radii past 180°, where the rings shrink back toward the antipode, have a hit count of 0 and a mean of NaN.\n",
"- NaN values add nothing to a ring's weighted sum, but their face areas still count toward the ring's area. Missing values therefore pull a ring's mean toward 0, and a ring with only NaN values has a mean of 0. To average only the valid faces, divide by the mean of a validity mask:\n",
"\n",
"```python\n",
"valid = ux.UxDataArray(field.notnull(), uxgrid=field.uxgrid)\n",
"nan_aware = field.fillna(0).azimuthal_mean(*args) / valid.azimuthal_mean(*args)\n",
"```"
]
}
],
"metadata": {
Expand Down
225 changes: 182 additions & 43 deletions test/core/test_azimuthal.py
Original file line number Diff line number Diff line change
@@ -1,68 +1,207 @@
import pytest
import uxarray as ux
import dask.array as da
import numpy as np
import pytest
import xarray as xr
from dask.callbacks import Callback
from xarray.core import indexing

import uxarray as ux
from uxarray.core.azimuthal import _ring_membership
from uxarray.grid.coordinates import _lonlat_rad_to_xyz


def test_gaussian(gridpath, datasetpath):
uxds = ux.open_dataset(
@pytest.fixture
def uxds(gridpath, datasetpath):
return ux.open_dataset(
gridpath("mpas", "dyamond-30km", "gradient_grid_subset.nc"),
datasetpath("mpas", "dyamond-30km", "gradient_data_subset.nc")
datasetpath("mpas", "dyamond-30km", "gradient_data_subset.nc"),
)

res = uxds['gaussian'].azimuthal_mean(center_coord=(45, 0), outer_radius=2, radius_step=0.5)

# Expects decreasing values from center
valid_vals = res[1:]
def _center_xyz(lon, lat):
return np.array(_lonlat_rad_to_xyz(np.deg2rad(lon), np.deg2rad(lat)))

np.testing.assert_array_less(
valid_vals.diff("radius").values, 1e-12
)

def _chords(outer_radius, radius_step):
radii = np.arange(0.0, outer_radius + radius_step, radius_step)
return 2.0 * np.sin(np.deg2rad(radii) / 2.0)


def test_inverse_gaussian(gridpath, datasetpath):
def _reference_rings(points, center_xyz, chord_radii):
"""Brute-force ring of each point: the first i with d <= r_i, or -1."""
dist2 = ((points - center_xyz) ** 2).sum(axis=1)
ring_of = np.full(len(points), -1)
# squared as an array, as a numpy scalar's ** can round differently
for i, bound in reversed(list(enumerate(chord_radii**2))):
ring_of[dist2 <= bound] = i
return ring_of

uxds = ux.open_dataset(
gridpath("mpas", "dyamond-30km", "gradient_grid_subset.nc"),
datasetpath("mpas", "dyamond-30km", "gradient_data_subset.nc")

@pytest.mark.parametrize("name, sign", [("gaussian", -1), ("inverse_gaussian", 1)])
def test_monotone_profile(uxds, name, sign):
res = uxds[name].azimuthal_mean(
center_coord=(45, 0), outer_radius=2, radius_step=0.5
)

res = uxds['inverse_gaussian'].azimuthal_mean(center_coord=(45, 0), outer_radius=2, radius_step=0.5)
# gaussian decreases away from the center, inverse_gaussian increases. Only
# the empty ring at radius 0 is NaN, so any other NaN fails the comparison.
np.testing.assert_array_less(-1e-12, sign * res[1:].diff("radius").values)

# Expects increasing values from center
atol = 1e-12
diffs = res[1:].diff("radius").values
diffs = diffs[np.isfinite(diffs)]
np.testing.assert_array_less(-atol, diffs)

def test_non_zero_hit_counts(gridpath, datasetpath):
uxds = ux.open_dataset(
gridpath("mpas", "dyamond-30km", "gradient_grid_subset.nc"),
datasetpath("mpas", "dyamond-30km", "gradient_data_subset.nc")
@pytest.mark.parametrize("chunks", [None, {"n_face": 50, "time": 1}])
@pytest.mark.parametrize("center", [(45, 0), (-45, 0)]) # in and outside the subset
def test_matches_reference(uxds, center, chunks):
# (n_face, time) data with the grid dim first and a few NaNs
stacked = (
xr.concat([uxds["gaussian"], uxds["inverse_gaussian"]], dim="time")
.transpose("n_face", "time")
.copy()
)
stacked[[3, 50, 120], 1] = np.nan
uxda = ux.UxDataArray(stacked.assign_coords(time=[10, 20]), uxgrid=uxds.uxgrid)
if chunks:
uxda = uxda.chunk(chunks)

res, hit_counts = uxds['inverse_gaussian'].azimuthal_mean(center_coord=(45, 0), outer_radius=2, radius_step=0.5, return_hit_counts=True)

# At least one hit after the first circle
assert np.all(hit_counts[1:] > 1)
res, hits = uxda.azimuthal_mean(
center_coord=center, outer_radius=2, radius_step=0.25, return_hit_counts=True
)

assert 'radius' in hit_counts.dims
assert hit_counts.sizes['radius'] == res.sizes['radius']
assert res.dims == ("radius", "time")
assert hits.dims == ("radius",) and hits.sizes["radius"] == res.sizes["radius"]
np.testing.assert_array_equal(res["time"], [10, 20])
if chunks:
assert isinstance(res.data, da.Array)
assert res.chunks[1] == (1, 1)

def test_zero_hit_counts(gridpath, datasetpath):
uxds = ux.open_dataset(
gridpath("mpas", "dyamond-30km", "gradient_grid_subset.nc"),
datasetpath("mpas", "dyamond-30km", "gradient_data_subset.nc")
# Per-ring float64 oracle: nansum(x * area) / sum(area)
ring_of = _reference_rings(
uxda.uxgrid._get_scipy_kd_tree().data, _center_xyz(*center), _chords(2, 0.25)
)
areas = uxda.uxgrid.face_areas.values.astype(np.float64)
values = uxda.values.astype(np.float64)
expected = np.full(res.shape, np.nan)
expected_hits = np.zeros(res.sizes["radius"], dtype=int)
for i in range(res.sizes["radius"]):
ring = ring_of == i
expected_hits[i] = ring.sum()
if ring.any():
weighted = np.nansum(values[ring] * areas[ring, None], axis=0)
expected[i] = weighted / areas[ring].sum()

np.testing.assert_array_equal(hits, expected_hits)
np.testing.assert_allclose(res.values, expected, rtol=1e-12, equal_nan=True)
if center == (45, 0):
assert np.all(hits[1:] > 1)
else:
assert np.all(hits == 0)


def test_dask_holds_one_input_chunk_at_a_time(uxds):
# (time, n_face) data in 50-face chunks, with every face within outer_radius
data = ux.UxDataArray(
xr.concat([uxds["gaussian"], uxds["inverse_gaussian"]] * 2, dim="time"),
uxgrid=uxds.uxgrid,
).chunk({"n_face": 50})
res, hits = data.azimuthal_mean(
center_coord=(45, 0), outer_radius=2, radius_step=0.25, return_hit_counts=True
)
assert hits.sum() == data.sizes["n_face"]

# The size of every intermediate result, from input chunks to ring sums.
# Unoptimized, as task fusion would hide a gathered block inside one task.
result_nbytes = []
with Callback(
posttask=lambda key, result, *_: result_nbytes.append(
getattr(result, "nbytes", 0)
)
):
res.compute(scheduler="synchronous", optimize_graph=False)

# no task gathers the ring faces of several input chunks
assert max(result_nbytes) <= data.isel(n_face=slice(0, 50)).nbytes


class _CountingBackendArray(xr.backends.BackendArray):
"""Serves an in-memory array the way a file engine (e.g. netCDF4) does,
recording the shape of each read."""

def __init__(self, array):
self.array, self.shape, self.dtype = array, array.shape, array.dtype
self.read_shapes = []

def __getitem__(self, key):
return indexing.explicit_indexing_adapter(
key, self.shape, indexing.IndexingSupport.OUTER, self._read
)

def _read(self, key):
# numpy matches outer indexing here, as at most one axis is fancy indexed
array = self.array[key]
self.read_shapes.append(array.shape)
return array


# (center, outer_radius): 12 faces scattered over a span of 133, every face,
# and none
@pytest.mark.parametrize(
"center, outer_radius", [((45, 0), 0.5), ((45, 0), 2), ((-45, 0), 2)]
)
def test_file_backed_reads_are_bounded(uxds, center, outer_radius):
data = ux.UxDataArray(
xr.concat([uxds["gaussian"], uxds["inverse_gaussian"]] * 2, dim="time"),
uxgrid=uxds.uxgrid,
)
# (time, n_face) data loaded lazily without dask, as a file engine serves it
backend = _CountingBackendArray(data.values)
lazy = ux.UxDataArray(
xr.Variable(data.dims, indexing.LazilyIndexedArray(backend)),
uxgrid=uxds.uxgrid,
)

# Outside of grid domain
res, hit_counts = uxds['inverse_gaussian'].azimuthal_mean(center_coord=(-45, 0), outer_radius=2, radius_step=0.5, return_hit_counts=True)

assert 'radius' in hit_counts.dims
assert hit_counts.sizes['radius'] == res.sizes['radius']
res, hits = lazy.azimuthal_mean(
center_coord=center,
outer_radius=outer_radius,
radius_step=0.25,
return_hit_counts=True,
)

# No hits
assert np.all(hit_counts == 0)
# every time step is read for each face, but at most twice the selected faces
n_selected = int(hits.sum())
assert all(shape[0] == data.sizes["time"] for shape in backend.read_shapes)
assert sum(shape[1] for shape in backend.read_shapes) <= 2 * n_selected
if center == (45, 0) and outer_radius == 0.5:
assert n_selected == 12 # spread over 133 faces of the array

print(res)
expected = data.azimuthal_mean(
center_coord=center, outer_radius=outer_radius, radius_step=0.25
)
np.testing.assert_array_equal(res.values, expected.values)


def _ring_edge_cases(kdtree, n_cases=200):
"""Radii exactly at face distances, so faces sit on ring edges, where the
kd-tree's own rounding can disagree with d <= r."""
rng = np.random.default_rng(0)
for _ in range(n_cases):
center = kdtree.data[rng.integers(kdtree.n)] + rng.normal(scale=1e-3, size=3)
offsets = kdtree.data[rng.integers(kdtree.n, size=5)] - center
yield center, np.sort(np.append(np.sqrt((offsets**2).sum(axis=1)), 0.0))


# (outer_radius, radius_step), past 180 degrees too, or None for ring-edge ties
@pytest.mark.parametrize("radii", [(2, 0.1), (60, 1), (250, 10), (360, 3), None])
def test_ring_membership(gridpath, radii):
kdtree = ux.open_grid(
gridpath("mpas", "dyamond-30km", "gradient_grid_subset.nc")
)._get_scipy_kd_tree()
if radii is None:
cases = _ring_edge_cases(kdtree)
else:
chords = _chords(*radii)
cases = [(_center_xyz(*c), chords) for c in [(45, 0), (44.7, 0.6), (-45, 0)]]

for center, chords in cases:
ring_of = _reference_rings(kdtree.data, center, chords)
faces, ring_ids = _ring_membership(kdtree, center, chords)
np.testing.assert_array_equal(faces, np.flatnonzero(ring_of >= 0))
np.testing.assert_array_equal(ring_ids, ring_of[faces])
Loading
Loading