Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
75a20b6
initial vertical coordinate interpolator plumbing
wyatt-fluidnumerics Nov 4, 2026
4e98ebc
implement UxLinearNodeLinearZf and corresponding Vertical coord inter…
wyatt-fluidnumerics Nov 4, 2026
adc20eb
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 4, 2026
b00c9d1
Add xgrid interpolators and testing
wyatt-fluidnumerics Nov 9, 2026
7bebb28
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 9, 2026
a8a5de2
swap time indexing in uxinterpolators to be more compatable with wind…
wyatt-fluidnumerics Nov 10, 2026
dd5f01d
make all ux interpolators linear in time
wyatt-fluidnumerics Nov 10, 2026
c016552
Move vertical interpolator testing to its own file
wyatt-fluidnumerics Nov 10, 2026
3cc828e
Add default z interpolator and linear in time interpolation testing f…
wyatt-fluidnumerics Nov 10, 2026
2da08b7
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 10, 2026
6f5355e
Remove experimental warning on startup
wyatt-fluidnumerics Nov 10, 2026
3850d9e
Merge branch 'vertical-coordinate-interpolators' of github.com:Parcel…
wyatt-fluidnumerics Nov 10, 2026
24ecc04
Renamed tutorial and added vertical coord interpolator section
wyatt-fluidnumerics Nov 10, 2026
012c0fe
Clear notebook output
wyatt-fluidnumerics Nov 10, 2026
13aaeb3
minor changes
wyatt-fluidnumerics Nov 10, 2026
87e87c3
add py:obj to tutorial interpolators
wyatt-fluidnumerics Nov 10, 2026
71f206a
Merge branch 'main' into vertical-coordinate-interpolators
wyatt-fluidnumerics Nov 10, 2026
4a0b6cc
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 10, 2026
cb13494
Added chunked cache array default for dask backed time varying z
wyatt-fluidnumerics Nov 13, 2026
494f49f
Merge branch 'vertical-coordinate-interpolators' of github.com:Parcel…
wyatt-fluidnumerics Nov 13, 2026
940f400
Added dimension transpose functions for time varying z to xgrid and u…
wyatt-fluidnumerics Nov 17, 2026
401194b
More explicit error message on incorrect interpolator setting
wyatt-fluidnumerics Nov 17, 2026
533f9f6
Removed WIP comments and reordered _search_time_varying_z args
wyatt-fluidnumerics Nov 17, 2026
9c8e637
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 17, 2026
93fc6e0
Changed location of tutorial in toctree, changed relavent links in th…
wyatt-fluidnumerics Nov 17, 2026
8664333
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 17, 2026
fdde86e
Fix tutorial
wyatt-fluidnumerics Nov 17, 2026
ee169f8
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 17, 2026
97a0bda
Move interpolator repr functions to _repr_utils
wyatt-fluidnumerics Nov 17, 2026
4b6d64b
Merge branch 'vertical-coordinate-interpolators' of github.com:Parcel…
wyatt-fluidnumerics Nov 17, 2026
752fe0a
Add docstring comment padding comment to _position_between_cell_centres
wyatt-fluidnumerics Nov 17, 2026
7c88448
Add docstring to VerticalCoordinateInterpolator and x/uxgrid.z_inter_…
wyatt-fluidnumerics Nov 17, 2026
6bcc9ec
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 17, 2026
06cda90
Changed deleted particles to use X in final tutrorial animation
wyatt-fluidnumerics Nov 18, 2026
afbfad2
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 18, 2026
e09d71a
Fix typing
wyatt-fluidnumerics Nov 18, 2026
0d6493c
Merge branch 'main' into vertical-coordinate-interpolators
wyatt-fluidnumerics Nov 18, 2026
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
3 changes: 2 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@
"user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb": "user_guide/interpolation_peninsula_AvsCgrid.ipynb",
"user_guide/examples/tutorial_sampling.ipynb": "user_guide/kernels_sampling.ipynb",
"user_guide/examples/tutorial_schism.ipynb": "user_guide/convert_schism.ipynb",
"user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/fieldsets_sigma_coordinates.ipynb",
"user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/fieldsets_time_varying_z_coordinates.ipynb",
"user_guide/examples/tutorial_statuscodes.md": "user_guide/kernels_statuscodes.ipynb",
"user_guide/examples/tutorial_stuck_particles.ipynb": "user_guide/interpolation_stuck_particles.ipynb",
"user_guide/examples/tutorial_unstuck_Agrid.ipynb": "user_guide/interpolation_unstuck_Agrid.ipynb",
Expand All @@ -127,6 +127,7 @@
"user_guide/getting_started/installation.md": "user_guide/installation.md",
"user_guide/getting_started/tutorial_output.ipynb": "user_guide/gettingstarted_output.ipynb",
"user_guide/getting_started/tutorial_quickstart.md": "user_guide/gettingstarted_quickstart.md",
"user_guide/fieldsets_sigma_coordinates.ipynb": "user_guide/fieldsets_time_varying_z_coordinates.ipynb",
}

# Tell Jinja2 templates the build is running on Read the Docs
Expand Down
6 changes: 1 addition & 5 deletions docs/user_guide/fieldsets_grids.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -330,11 +330,7 @@
"cell_type": "markdown",
"id": "8",
"metadata": {},
"source": [
"### Vertical coordinates\n",
"\n",
"Lastly, a short note on vertical coordinates. Parcels can handle two styles of vertical coordinates; z-levels which define fixed depth levels in physical space, and sigma-levels which define varying depth levels in physical space as a function of the water column depth. As sigma-levels are effectively \"terrain-following\", the grid cell faces may no longer be orthogonal to the domain surface. The bottom row of Figure 1 visualises these differences, and Parcels handles this all under the hood. See the [Sigma Coordinate Vertical Grids tutorial](./fieldsets_sigma_coordinates.ipynb) for more details on the sigma-levels implementation.\n"
]
"source": "### Vertical coordinates\n\nLastly, a short note on vertical coordinates. Parcels can handle two styles of vertical coordinates; z-levels which define fixed depth levels in physical space, and sigma-levels which define varying depth levels in physical space as a function of the water column depth. As sigma-levels are effectively \"terrain-following\", the grid cell faces may no longer be orthogonal to the domain surface. The bottom row of Figure 1 visualises these differences, and Parcels handles this all under the hood. See the [time varying z coordinates tutorial](./fieldsets_time_varying_z_coordinates.ipynb) for more details on the sigma-levels implementation.\n"
}
],
"metadata": {
Expand Down

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't comment on individual lines, so below some comments on the notebook

  • rename the title to use lowercase `time varying'?
  • use the hide-input tag for the dataset creation cell, so that users don't get overwhelmed by it? It's not that relevant for most users how the dataset is created?
  • Type-o in coordiante
  • Is it expected that the particles don't move horizontally on the right panel of the last animation?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in fdde86e

It is expected that the particles don't move horizontally, the goal here is to show that when using a discontinuous interpolation scheme you can get spurious particle deletion for near surface particles when they grid moves around them. I changed the animations to change the color of the particles when they are deleted and then include a legend for the animation. Let me know what you think, it is possible that it is best to just remove the code blocks in the "Choosing how z is interpolated" section entirely.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I only now realise that these particles are deleted. Perhaps change them from a circle to a cross when they are deleted? Would that be even clearer?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, that's a good idea. Changed in 06cda90

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/user_guide/group_fieldsets.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
```{toctree}
:titlesonly:
fieldsets_grids.ipynb
fieldsets_sigma_coordinates.ipynb
fieldsets_time_varying_z_coordinates.ipynb
fieldsets_velocityconversion.ipynb
fieldsets_nestedgrids.ipynb
fieldsets_manipulating_field_data.ipynb
Expand Down
4 changes: 4 additions & 0 deletions src/parcels/_chunk_cached_array/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ def wrap_dataset(ds: xr.Dataset, max_cache_bytes: int) -> xr.Dataset:
# Load coordinates eagerly — they are small 1D arrays and keeping them
# as dask arrays causes expensive task-graph construction on every .isel().
for name in list(ds.coords):
# During grid construction dask backed time varying z data is backed by a ChunkCachedArray, time varying z
# coordinates can be large, so we don't load automatically
if isinstance(ds[name].variable._data, ChunkCachedArray):
continue
ds[name].load()
for name in ds.data_vars:
var = ds.variables[name]
Expand Down
13 changes: 11 additions & 2 deletions src/parcels/_core/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
from parcels._core.field import Field, VectorField
from parcels._core.mesh import FlatMesh, SphericalMesh, _infer_mesh_from_coordinates
from parcels._core.utils.time import TimeInterval
from parcels._core.uxgrid import UxGrid
from parcels._core.uxgrid import UxGrid, _transpose_uxfield_data
from parcels._core.xgrid import (
XGrid,
_transpose_xfield_data_to_tzyx,
Expand Down Expand Up @@ -164,6 +164,12 @@ def preprocess_sgrid_model_data(ds: xr.Dataset) -> xr.Dataset:
return ds


def preprocess_ugrid_model_data(ds: ux.UxDataset) -> ux.UxDataset:
for field_name in list(ds.data_vars):
ds[field_name] = _transpose_uxfield_data(ds[field_name])
return ds


def validate_field_data(ds: xr.Dataset) -> xr.Dataset:
return ds.fillna(0)

Expand Down Expand Up @@ -370,6 +376,8 @@ def __init__(self, data: ux.UxDataset, grid: UxGrid, vector_field_components: pt
if not isinstance(data, ux.UxDataset):
raise ValueError(f"Expected `data` to be an uxarray.UxDataset . Got {type(data)}")

data = preprocess_ugrid_model_data(data)

if not isinstance(grid, UxGrid):
raise ValueError(f"Expected `grid` to be a Parcels UxGrid object. Got {type(grid)}.")

Expand Down Expand Up @@ -413,6 +421,7 @@ def scalar_field_names(self) -> list[str]:
def from_ugrid_conventions(
cls, ds: ux.UxDataset, *, mesh: ptyping.TMesh | None = None, vector_fields: ptyping.VectorFields | NotSetType
):
ds = ds.copy()
ds_dims = list(ds.dims)
if not all(dim in ds_dims for dim in ["time", "zf", "zc"]):
raise ValueError(
Expand All @@ -424,7 +433,7 @@ def from_ugrid_conventions(

assert_vertical_dimensionality(ds, allowed_dimensionality=[1, 3])

grid = UxGrid(ds.uxgrid, z=ds.coords["zf"], mesh=mesh) # type: ignore[arg-type] # uxarray coords typed as DataArray instead of UxDataArray
grid = UxGrid(ds.uxgrid, z=ds.coords["zf"], mesh=mesh)
ds = _discover_ux_U_and_V(ds)

vector_fields = resolve_vector_fields(ds, vector_fields)
Expand Down
2 changes: 1 addition & 1 deletion src/parcels/_core/particleset.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ def __init__(
minz = None
for field in self.fieldset.fields.values():
has_time_varying_z = (isinstance(field.grid, UxGrid) and field.grid.z.ndim == 3) or (
isinstance(field.grid, XGrid) and "Z" in field.grid.axes and field.grid._ds["depth"].ndim == 4
isinstance(field.grid, XGrid) and field.grid.depth.ndim == 4
Comment thread
erikvansebille marked this conversation as resolved.
Resolved
)
if has_time_varying_z:
raise ValueError(
Expand Down
117 changes: 73 additions & 44 deletions src/parcels/_core/uxgrid.py
Original file line number Diff line number Diff line change
@@ -1,23 +1,36 @@
from __future__ import annotations

import warnings
from typing import TYPE_CHECKING, Literal

import numpy as np
import xarray as xr
from dask import is_dask_collection

from parcels._chunk_cached_array import ChunkCachedArray
from parcels._core.basegrid import BaseGrid
from parcels._core.index_search import GRID_SEARCH_ERROR, _search_1d_array, _search_1d_columns, uxgrid_point_in_cell
from parcels._core.mesh import BaseMesh, TMesh
from parcels._core.warnings import FieldSetWarning
from parcels.interpolators._base import VerticalCoordinateInterpolator
from parcels.interpolators._uxinterpolators import UxVerticalCoordinateConstantFace, UxVerticalCoordinateLinearNode

if TYPE_CHECKING:
import uxarray as ux

_UXGRID_AXES = Literal["Z", "FACE"]


def _transpose_uxfield_data(da: ux.UxDataArray) -> ux.UxDataArray:
"""Transpose a DataArray on a UxGrid to the order (time, vertical, lateral) that the Ux interpolators assume."""
dim_to_position = {"time": 0, "zf": 1, "zc": 1, "n_node": 2, "n_face": 2, "n_edge": 2}

dims_not_on_grid = set(da.dims) - set(dim_to_position)
if dims_not_on_grid:
raise ValueError(
f"DataArray {da.name!r} with dims {da.dims} has dimensions {dims_not_on_grid} that are not on a UxGrid."
)

return da.transpose(*sorted(da.dims, key=dim_to_position.__getitem__))


class UxGrid(BaseGrid):
"""
Extension of uxarray's Grid class that supports point-location search
Expand All @@ -35,7 +48,8 @@ def __init__(self, grid: ux.grid.Grid, z: ux.UxDataArray, mesh: TMesh) -> None:
z : ux.UxDataArray
Vertical coordinates (depths) of the layer interface heights (not the mid-layer depths). Either a 1D array,
constant in time and space (flat bottom topography, no moving vertical grid), or a 3D array with dims
("time", "zf", "n_node"), varying in time and across the mesh nodes.
("time", "zf", "n_node") or ("time", "zf", "n_face") in any order, varying in time and across the mesh nodes
or faces.
mesh : FlatMesh or SphericalMesh
The mesh of the grid, e.g. ``FlatMesh()`` or ``SphericalMesh(radius=...)``.
"""
Expand All @@ -50,24 +64,37 @@ def __init__(self, grid: ux.grid.Grid, z: ux.UxDataArray, mesh: TMesh) -> None:
raise TypeError("z must be an instance of ux.UxDataArray")
if z.ndim not in (1, 3):
raise ValueError(f"z must be a 1D or 3D array of vertical coordinates, got {z.ndim}D")
if z.ndim == 3 and z.dims != ("time", "zf", "n_node"):
raise ValueError(f"A 3D z must have dims ('time', 'zf', 'n_node'), got {z.dims}")
if z.ndim == 3:
warnings.warn(
"Time-varying (3D) z coordinates are experimental and may cause significant memory overhead that "
f"leads to OOM errors. This z coordinate has sizes {dict(z.sizes)} ({z.nbytes / 1e9:.3g} GB). "
"Assumptions: z is defined at the layer interfaces ('zf') on the mesh nodes ('n_node') and is strictly "
"increasing along 'zf'; each particle's z column is interpolated barycentrically from its face's "
"nodes and linearly in time between z snapshots.",
FieldSetWarning,
stacklevel=4,
)

self.z = z
self.mesh = mesh
self._spatialhash = None
self._z_interp_method = None
if z.ndim == 3:
self._init_time_varying_z()
if is_dask_collection(self.uxgrid.face_node_connectivity.data):
self.uxgrid.face_node_connectivity.load()

def _init_time_varying_z(self) -> None:
"""Checks the dims of a time-varying (3D) z and assigns its default z_interp_method."""
z = self.z

if set(z.dims) not in ({"time", "zf", "n_node"}, {"time", "zf", "n_face"}):
raise ValueError(
f"A 3D z must have dims ('time', 'zf', 'n_node') or ('time', 'zf', 'n_face'), in any order, "
f"got {z.dims}"
)

self.z = _transpose_uxfield_data(z)
z = self.z

if is_dask_collection(z.data):
z.variable._data = ChunkCachedArray(z.data, max_cache_bytes=600_000_000)

if z.dims[-1] == "n_node":
Comment thread
erikvansebille marked this conversation as resolved.
Resolved
self.z_interp_method = UxVerticalCoordinateLinearNode()
else:
self.z_interp_method = UxVerticalCoordinateConstantFace()

@property
def depth(self):
"""
Expand All @@ -76,16 +103,34 @@ def depth(self):
Included for compatibility with v3 codebase. May be removed in future.
TODO v4: Evaluate
"""
try:
_ = self.z.values
except KeyError:
return np.zeros(1)
# Load time varying z lazily
if self.z.ndim == 3:
return self.z
return self.z.values

@property
def axes(self) -> list[_UXGRID_AXES]:
return ["Z", "FACE"]

@property
def z_interp_method(self) -> VerticalCoordinateInterpolator | None:
"""The ``VerticalCoordinateInterpolator`` used during the particle search to build each particle's z column.
Unlike a field's ``interp_method``, it is shared by every field on this grid.
"""
return self._z_interp_method

@z_interp_method.setter
def z_interp_method(self, value: VerticalCoordinateInterpolator):
if not isinstance(value, VerticalCoordinateInterpolator):
raise ValueError(f"z_interp_method must be a `VerticalCoordinateInterpolator` object. Got {type(value)=!r}")
if self.depth.ndim != 3:
raise ValueError("z_interp_method can only be set on a grid with a time-varying (3D) z")
if isinstance(value, UxVerticalCoordinateLinearNode) and self.z.dims[-1] != "n_node":
raise ValueError(f"UxVerticalCoordinateLinearNode needs z on the mesh nodes, got dims {self.z.dims}")
if isinstance(value, UxVerticalCoordinateConstantFace) and self.z.dims[-1] != "n_face":
raise ValueError(f"UxVerticalCoordinateConstantFace needs z on the mesh faces, got dims {self.z.dims}")
self._z_interp_method = value

def get_axis_dim(self, axis: _UXGRID_AXES) -> int:
if axis not in self.axes:
raise ValueError(f"Axis {axis!r} is not part of this grid. Available axes: {self.axes}")
Expand Down Expand Up @@ -156,39 +201,23 @@ def search(self, z, y, x, ei=None, ti=None, tau=None, tol=1e-6):
fi[zero_indices] = face_ids_q

if self.z.ndim == 3:
zi, zeta = self._search_time_varying_z(z, fi, coords, ti, tau)
zi, zeta = self._search_time_varying_z(z, ti, tau, fi, coords)
else:
zi, zeta = _search_1d_array(self.z.values, z)

return {"Z": {"index": zi, "bcoord": zeta}, "FACE": {"index": fi, "bcoord": coords}}

def _search_time_varying_z(self, z, fi, coords, ti, tau):
"""Vertical search of each particle in the z column interpolated barycentrically from the nodes of its face,
using temporal linear interpolation between the snapshots ti and ti + 1.
"""
def _search_time_varying_z(self, z, ti, tau, fi, coords):
"""Vertical search of each particle in the z column built by the grid's z_interp_method."""
found = fi >= 0
cols_ti = self.z.isel(
time=xr.DataArray(np.broadcast_to(ti, fi.shape)[found], dims="points"),
n_node=xr.DataArray(self.uxgrid.face_node_connectivity[fi[found], :].values, dims=("points", "nodes")),
ignore_grid=True,
).compute()

if self.z.shape[0] == 1:
node_columns = cols_ti
else:
cols_tnext = self.z.isel(
time=xr.DataArray(np.broadcast_to(ti + 1, fi.shape)[found], dims="points"),
n_node=xr.DataArray(self.uxgrid.face_node_connectivity[fi[found], :].values, dims=("points", "nodes")),
ignore_grid=True,
).compute()

tau_points = xr.DataArray(np.broadcast_to(tau, fi.shape)[found], dims="points")
node_columns = (1 - tau_points) * cols_ti + tau_points * cols_tnext
grid_positions = {
"T": {"index": np.broadcast_to(ti, fi.shape)[found], "bcoord": np.broadcast_to(tau, fi.shape)[found]},
"FACE": {"index": fi[found], "bcoord": coords[found]},
}

bcoords = xr.DataArray(coords[found], dims=("points", "nodes"))
# Particles outside the mesh are given a NaN z column for vertical searching
columns = np.full((fi.size, self.z.sizes["zf"]), np.nan)
columns[found] = xr.dot(node_columns, bcoords, dim="nodes").values
columns[found] = self.z_interp_method.columns(grid_positions, self)
zi, zeta = _search_1d_columns(columns, z)

# Particles outside the mesh are given a 0 vertical index and a NaN vertical barycentric coordinate
Expand Down
Loading
Loading