diff --git a/docs/conf.py b/docs/conf.py index dc1dcf1fc..40f9783dc 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -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", @@ -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 diff --git a/docs/user_guide/fieldsets_grids.ipynb b/docs/user_guide/fieldsets_grids.ipynb index fb2ebed10..35b5e7fa6 100644 --- a/docs/user_guide/fieldsets_grids.ipynb +++ b/docs/user_guide/fieldsets_grids.ipynb @@ -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": { diff --git a/docs/user_guide/fieldsets_sigma_coordinates.ipynb b/docs/user_guide/fieldsets_time_varying_z_coordinates.ipynb similarity index 60% rename from docs/user_guide/fieldsets_sigma_coordinates.ipynb rename to docs/user_guide/fieldsets_time_varying_z_coordinates.ipynb index b8720d435..0b25aa853 100644 --- a/docs/user_guide/fieldsets_sigma_coordinates.ipynb +++ b/docs/user_guide/fieldsets_time_varying_z_coordinates.ipynb @@ -4,13 +4,20 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# 🖥️ Sigma Coordinate Vertical Grids" + "# 🖥️ Datasets with time varying z coordinates" ] }, { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "outputs": [], "source": [ "import matplotlib.pyplot as plt\n", @@ -29,17 +36,34 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Building the Dataset\n", "\n", - "For this tutorial, we construct our dataset using the parcels built in `simple_UV_sigma_dataset`, which makes a structured horizontally gridded dataset that uses a linear vertical $\\sigma$ grid. Its horizontal grid is a flat square that spans from -1000 km to 1000 km in both $x$ and $y$. Here, we assume $\\frac{\\partial \\sigma}{\\partial z}$ to be constant, so for any given z coordinate, the equivalent $\\sigma$ coordinate is a dimensionless fraction of column height, i.e. $\\sigma = \\frac{z + \\eta}{H +\\eta}$, where $H$ is the depth of the water column, and $\\eta$ is the sea surface height. It is common in $\\sigma$ coordinate models to use more advanced vertical grids for which $\\frac{\\partial \\sigma}{\\partial z}$ is not constant, this allows the concentration of vertical layers near the surface. Nonetheless, our simple example allows for a vertical coordinate system that adapts to changes in bathymetry and variations in sea surface height. We will demonstrate this shortly but begin by constructing the dataset itself. At the end of the tutorial, we show the same setup on an unstructured grid." + "For this tutorial, we construct our dataset using the parcels built in `simple_UV_sigma_dataset`, which makes a structured horizontally gridded dataset that uses a linear vertical $\\sigma$ grid. Its horizontal grid is a flat square that spans from -1000 km to 1000 km in both $x$ and $y$. Here, we assume $\\frac{\\partial \\sigma}{\\partial z}$ to be constant, so for any given z coordinate, the equivalent $\\sigma$ coordinate is a dimensionless fraction of column height, i.e. $\\sigma = \\frac{z + \\eta}{H +\\eta}$, where $H$ is the depth of the water column, and $\\eta$ is the sea surface height. It is common in $\\sigma$ coordinate models to use more advanced vertical grids for which $\\frac{\\partial \\sigma}{\\partial z}$ is not constant, this allows the concentration of vertical layers near the surface. Nonetheless, our simple example allows for a vertical coordinate system that adapts to changes in bathymetry and variations in sea surface height. We will demonstrate this shortly but begin by constructing the dataset itself. At the end of the tutorial, we show the same setup on an unstructured grid, and how to modify the interpolation method used on the multi-dimensional z coordinate." ] }, { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "hide-input", + "hide-output" + ] + }, "outputs": [], "source": [ "n_days = 10\n", @@ -86,15 +110,31 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ - "We can now compare the evolution of the vertical grid in $\\sigma$ space to the vertical grid in z space. In z space, the vertical grid spacing is much smaller in the shallow west than in the deep east, this demonstrates the strength of a terrain following vertical grid. We can also see that the vertical grid has time dependency in z space. Currently, for structured grids, Parcels uses piecewise constant horizontal interpolation of z values for time-varying z." + "We can now compare the evolution of the vertical grid in $\\sigma$ space to the vertical grid in z space. In z space, the vertical grid spacing is much smaller in the shallow west than in the deep east, this demonstrates the strength of a terrain following vertical grid. We can also see that the vertical grid has time dependency in z space. The z coordinate is defined at the cell centres, and by default Parcels interpolates time-varying z bilinearly in space between the surrounding cell centres, so along a row of cells the layer interfaces are straight lines between the cell centres." ] }, { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "hide-input" + ] + }, "outputs": [], "source": [ "time = ds[\"time\"].values.astype(\"datetime64[s]\")\n", @@ -109,9 +149,7 @@ "ax_sigma.set_ylabel(r\"$\\sigma$\")\n", "ax_sigma.set_title(r\"Layer interfaces in $\\sigma$ space\")\n", "\n", - "z_lines = ax_z.plot(\n", - " xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8, drawstyle=\"steps-mid\"\n", - ")\n", + "z_lines = ax_z.plot(xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8)\n", "ax_z.set_ylabel(\"depth [m]\")\n", "z_title = ax_z.set_title(f\"Layer interfaces in z space at {time[0]}\")\n", "\n", @@ -136,13 +174,20 @@ }, { "cell_type": "markdown", - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [] + }, "source": [ "## Building the `FieldSet`\n", "\n", "We prescribe a uniform velocity of $u_0 = 1$ m/s in the $x$ direction, with $v = w = 0$. All three components sit on the grid nodes at the layer interfaces (`depth`), so Parcels interpolates them linearly in all three directions.\n", "\n", - "To advect the particles on a sigma grid, for which the z grid varies in time, we use a 4D `depth` coordinate with dimensions of `(time, depth, YC, XC)`. For each particle, Parcels takes the column of the cell that the particle is in, interpolates it linearly in time between the two surrounding snapshots, and then searches that column for the particle's layer. We pass `mesh=\"flat\"` because the coordinates are Cartesian meters." + "To advect the particles on a sigma grid, for which the z grid varies in time, we use a 4D `depth` coordinate with dimensions of `(time, depth, Y, X)`. For each particle, Parcels builds a z column by interpolating the columns at the surrounding cell centres bilinearly in space and linearly in time between the two surrounding snapshots, and then searches that column for the particle's layer." ] }, { @@ -204,12 +249,9 @@ "source": [ "H = z_moving[0, -1, centre_row]\n", "eta = -z_moving[:, 0, centre_row]\n", - "cell = np.searchsorted(\n", - " lon, x0\n", - ") # index of the cell centre whose z column Parcels uses for each particle\n", - "sigma0 = (z0 + eta[0, cell]) / (\n", - " H[cell] + eta[0, cell]\n", - ") # initial sigma coordinate of each particle\n", + "# initial sigma coordinate of each particle, using its z column interpolated linearly in x between the cell centres\n", + "eta0 = np.interp(x0, x_centres, eta[0])\n", + "sigma0 = (z0 + eta0) / (np.interp(x0, x_centres, H) + eta0)\n", "\n", "colors = [f\"C{p}\" for p in range(n_particles)]\n", "\n", @@ -219,7 +261,7 @@ "ax_sigma.set_ylabel(r\"$\\sigma$\")\n", "ax_sigma.set_title(r\"Initial particle positions in $\\sigma$ space\")\n", "\n", - "ax_z.plot(xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8, drawstyle=\"steps-mid\")\n", + "ax_z.plot(xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8)\n", "ax_z.scatter(x0 / 1e3, z0, color=colors, zorder=3)\n", "ax_z.set_ylabel(\"depth [m]\")\n", "ax_z.set_title(f\"Initial particle positions in z space at {time[0]}\")\n", @@ -259,6 +301,7 @@ " runtime=np.timedelta64(n_days, \"D\"),\n", " dt=np.timedelta64(30, \"m\"),\n", " output_file=outputfile,\n", + " verbose_progress=False,\n", ")" ] }, @@ -274,19 +317,19 @@ "px = df[\"x\"].to_numpy().reshape(n_frames, n_particles)\n", "pz = df[\"z\"].to_numpy().reshape(n_frames, n_particles)\n", "\n", - "# calculate the sigma coordinate of every particle at every output time, using the z column of its cell\n", + "# calculate the sigma coordinate of every particle at every output time, using its z column interpolated linearly in x\n", + "# between the cell centres\n", "snapshots = np.searchsorted(time, output_times.to_numpy(), side=\"right\") - 1\n", - "cells = np.searchsorted(lon, px)\n", - "eta_p = eta[snapshots[:, np.newaxis], cells]\n", - "psigma = (pz + eta_p) / (H[cells] + eta_p)\n", + "psigma = np.empty_like(pz)\n", + "for frame, snapshot in enumerate(snapshots):\n", + " eta_p = np.interp(px[frame], x_centres, eta[snapshot])\n", + " psigma[frame] = (pz[frame] + eta_p) / (np.interp(px[frame], x_centres, H) + eta_p)\n", "\n", "colors = [f\"C{p}\" for p in range(n_particles)]\n", "\n", "fig, (ax_sigma, ax_z) = plt.subplots(1, 2, figsize=(12, 4), sharex=True)\n", "ax_sigma.plot(xs, np.broadcast_to(sigma, (xs.size, sigma.size)), \"k\", linewidth=0.8)\n", - "z_lines = ax_z.plot(\n", - " xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8, drawstyle=\"steps-mid\"\n", - ")\n", + "z_lines = ax_z.plot(xs, z_moving[0][:, centre_row].T, \"k\", linewidth=0.8)\n", "sigma_trails = [ax_sigma.plot([], [], color=c, linewidth=1.5)[0] for c in colors]\n", "z_trails = [ax_z.plot([], [], color=c, linewidth=1.5)[0] for c in colors]\n", "sigma_dots = ax_sigma.scatter(px[0] / 1e3, psigma[0], c=colors, zorder=3)\n", @@ -334,7 +377,7 @@ "source": [ "## Sigma coordinates on unstructured grids\n", "\n", - "The same approach works on unstructured grids. On an unstructured grid, z is a 3D `zf` coordinate with dimensions `(time, zf, n_node)`, defined on the corners (nodes) of the triangular faces, rather than a 4D `depth` coordinate with dimensions `(time, depth, YC, XC)` defined on the cell centres. For each particle, Parcels interpolates the z columns of the three corners of its triangle barycentrically in space and linearly in time, so on unstructured grids the z grid varies continuously in space instead of being constant across each cell.\n", + "The same approach works on unstructured grids. On an unstructured grid, z is a 3D `zf` coordinate with dimensions `(time, zf, n_node/n_face)`, rather than a 4D `depth` coordinate with dimensions `(time, depth, Y, X)`. \n", "\n", "Below we build the same basin on a triangulated lattice with `sigma_coordinate_lattice_dataset`, evaluating the bathymetry and sea surface height at the lattice nodes, and compare the two z coordinates." ] @@ -342,7 +385,16 @@ { "cell_type": "code", "execution_count": null, - "metadata": {}, + "metadata": { + "deletable": true, + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "hide-input" + ] + }, "outputs": [], "source": [ "n_lattice_nodes = (\n", @@ -421,6 +473,7 @@ " runtime=np.timedelta64(n_days, \"D\"),\n", " dt=np.timedelta64(30, \"m\"),\n", " output_file=ux_outputfile,\n", + " verbose_progress=False,\n", ")" ] }, @@ -494,13 +547,191 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "As on the structured grid, the particles keep their exact height in z space while crossing the terrain following depth levels. On the unstructured grid, however, the layer interfaces vary continuously between the nodes rather than being constant across each grid cell." + "As on the structured grid, the particles keep their exact height in z space while crossing the terrain following depth levels." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Choosing how z is interpolated\n", + "\n", + "With a 4d z coordinate, in order to find a particle z value at some time, we must interpolate the current z grid at that time onto the particle position. This reduces the 4d z coordinate to a 1d z coordinate where each entry is an interface depth at the particle's exact position in space. For more details on interpolation in general, see the [interpolation tutorial](./interpolation_tutorial.ipynb). There are currently a number of built in interpolators for vertical coordinates:\n", + "\n", + "- {py:obj}`parcels.interpolators.XVerticalCoordinateLinear` (structured grids, z on the cell centres or corners): bilinear interpolation between the surrounding columns, so z is continuous in space.\n", + "- {py:obj}`parcels.interpolators.XVerticalCoordinateNearest` (structured grids, z on the cell centres or corners): piecewise constant interpolation based on whatever cell is closest to the particle.\n", + "- {py:obj}`parcels.interpolators.XVerticalCoordinateConstant` (structured grids, z on the cell centres): piecewise constant interpolation based on whatever cell the particle is in. \n", + "- {py:obj}`parcels.interpolators.UxVerticalCoordinateLinearNode` (unstructured grids, z on the nodes): barycentric interpolation from the three corners of the particle's triangle.\n", + "- {py:obj}`parcels.interpolators.UxVerticalCoordinateConstantFace` (unstructured grids, z on the faces): piecewise constant interpolation based on whatever cell the particle is in. \n", + "\n", + "All of them interpolate z linearly in time between the two surrounding snapshots.\n", + "\n", + "The effect of selecting different vertical coordinate interpolators can be seen by investigating what happens to particles near the surface:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# the same basin as above on a coarser grid with 200 km wide cells, so that the difference between the interpolators is\n", + "# easy to see\n", + "coarse_nx = 11\n", + "coarse_lon = np.linspace(lon[0], lon[-1], coarse_nx)\n", + "coarse_x_centres = coarse_lon - 0.5 * (coarse_lon[1] - coarse_lon[0])\n", + "# the first cell centre lies west of the domain, where the depth profile is held at its western value of 100 m\n", + "coarse_bottom_depth = 100 + 900 * np.log10(\n", + " 1 + 9 * np.clip(coarse_x_centres - lon[0], 0.0, None) / domain_length\n", + ")\n", + "coarse_wave = amplitude * np.sin(\n", + " 2.0\n", + " * np.pi\n", + " * (coarse_x_centres[np.newaxis, :] / wavelength - t[:, np.newaxis] / wave_period)\n", + ")\n", + "coarse_ds = simple_UV_sigma_dataset(\n", + " n_times=n_snapshots,\n", + " nz=n_vertical_layers + 1,\n", + " ny=ny,\n", + " nx=coarse_nx,\n", + " bottom_depth=np.broadcast_to(coarse_bottom_depth, (ny, coarse_nx)),\n", + " eta=np.broadcast_to(coarse_wave[:, np.newaxis, :], (n_snapshots, ny, coarse_nx)),\n", + ")\n", + "coarse_ds[\"U\"].values[:] = u0\n", + "coarse_fieldset = parcels.FieldSet.from_sgrid_conventions(coarse_ds)\n", + "\n", + "\n", + "def DeleteParticle(particles, fieldset):\n", + " any_error = particles.state >= 50 # e.g. particles that are above the sea surface\n", + " particles[any_error].state = parcels.StatusCode.Delete\n", + "\n", + "\n", + "# release particles near the surface, 15 km west of the cell edge at x = -400 km, where the sea surface of the next\n", + "# cell is lower than in the cell they start in, and advect them for one day with each interpolator\n", + "surface_z0 = np.linspace(22.0, 31.0, 4) # depths in m\n", + "z_interp_methods = {\n", + " \"XVerticalCoordinateLinear\": parcels.interpolators.XVerticalCoordinateLinear(),\n", + " \"XVerticalCoordinateConstant\": parcels.interpolators.XVerticalCoordinateConstant(),\n", + "}\n", + "for name, z_interp_method in z_interp_methods.items():\n", + " coarse_fieldset.U.grid.z_interp_method = z_interp_method\n", + " surface_pset = parcels.ParticleSet(\n", + " fieldset=coarse_fieldset,\n", + " pclass=parcels.Particle,\n", + " t=np.full(surface_z0.size, time[0]),\n", + " z=surface_z0,\n", + " y=np.zeros(surface_z0.size),\n", + " x=np.full(surface_z0.size, -415e3),\n", + " )\n", + " surface_outputfile = parcels.ParticleFile(\n", + " path=f\"{name}_particles.parquet\", outputdt=np.timedelta64(1, \"h\"), mode=\"w\"\n", + " )\n", + " surface_pset.execute(\n", + " [parcels.kernels.AdvectionRK2, DeleteParticle],\n", + " runtime=np.timedelta64(1, \"D\"),\n", + " dt=np.timedelta64(30, \"m\"),\n", + " output_file=surface_outputfile,\n", + " verbose_progress=False,\n", + " )" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "n_surface_frames = 25 # hourly outputs from hour 0 to hour 24\n", + "surface_px = {}\n", + "deleted = {}\n", + "for name in z_interp_methods:\n", + " surface_df = parcels.read_particlefile(f\"{name}_particles.parquet\")\n", + " frames = (surface_df[\"t\"].to_numpy() - time[0]) // np.timedelta64(1, \"h\")\n", + " surface_px[name] = np.full((n_surface_frames, surface_z0.size), np.nan)\n", + " surface_px[name][frames, surface_df[\"particle_id\"].to_numpy()] = surface_df[\"x\"]\n", + " # a particle that has left the water is deleted and has no more output, so it is drawn at its last position\n", + " deleted[name] = np.isnan(surface_px[name])\n", + " for frame in range(1, n_surface_frames):\n", + " left_the_water = deleted[name][frame]\n", + " surface_px[name][frame, left_the_water] = surface_px[name][\n", + " frame - 1, left_the_water\n", + " ]\n", + "\n", + "coarse_z = coarse_ds[\"depth\"].values[\n", + " :, :, centre_row\n", + "] # interface depths, shape (time, depth, x)\n", + "surface_colors = [f\"C{p}\" for p in range(surface_z0.size)]\n", + "\n", + "fig, axes = plt.subplots(1, 2, figsize=(12, 4), sharey=True)\n", + "panels = []\n", + "for ax, name, drawstyle in zip(\n", + " axes, z_interp_methods, [\"default\", \"steps-mid\"], strict=True\n", + "):\n", + " lines = ax.plot(\n", + " coarse_x_centres / 1e3, coarse_z[0].T, \"k\", linewidth=0.8, drawstyle=drawstyle\n", + " )\n", + " dots = ax.scatter(surface_px[name][0] / 1e3, surface_z0, c=surface_colors, zorder=3)\n", + " crosses = ax.scatter(\n", + " surface_px[name][0] / 1e3,\n", + " surface_z0,\n", + " c=surface_colors,\n", + " marker=\"x\",\n", + " s=100,\n", + " zorder=3,\n", + " )\n", + " ax.scatter([], [], c=\"k\", marker=\"x\", label=\"deleted after leaving the water\")\n", + " ax.legend(loc=\"lower right\")\n", + " ax.set_title(name)\n", + " ax.set_xlim(-800, 0)\n", + " ax.set_xlabel(\"x [km]\")\n", + " panels.append((name, lines, dots, crosses))\n", + "axes[0].set_ylim(\n", + " 300, -75\n", + ") # the upper part of the water column, with depth increasing downwards\n", + "axes[0].set_ylabel(\"depth [m]\")\n", + "suptitle = fig.suptitle(f\"Particles near the surface at {time[0]}\")\n", + "plt.tight_layout()\n", + "\n", + "\n", + "def animate(frame):\n", + " for name, lines, dots, crosses in panels:\n", + " for line, interface_depths in zip(lines, coarse_z[frame], strict=True):\n", + " line.set_ydata(interface_depths)\n", + " x_km = surface_px[name][frame] / 1e3\n", + " dots.set_offsets(\n", + " np.c_[np.where(deleted[name][frame], np.nan, x_km), surface_z0]\n", + " )\n", + " crosses.set_offsets(\n", + " np.c_[np.where(deleted[name][frame], x_km, np.nan), surface_z0]\n", + " )\n", + " suptitle.set_text(f\"Particles near the surface at {time[frame]}\")\n", + "\n", + "\n", + "animate(0)\n", + "anim = FuncAnimation(fig, animate, frames=n_surface_frames, interval=300)\n", + "plt.close()\n", + "anim" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "With {py:obj}`parcels.interpolators.XVerticalCoordinateLinear`, the sea surface and the layer interfaces vary smoothly between the cell centres, while with {py:obj}`parcels.interpolators.XVerticalCoordinateConstant` they jump at every cell edge. The discontinuity of piecewise constant vertical coordinate interpolators can cause particles to spuriously leave the domain, as shown above. \n", + "\n", + "By default, Parcels uses `XVerticalCoordinateLinear` for time-varying z on structured grids, {py:obj}`parcels.interpolators.UxVerticalCoordinateLinearNode` for z on the nodes of an unstructured grid, and {py:obj}`parcels.interpolators.UxVerticalCoordinateConstantFace` for z on the faces of an unstructured grid. To use a different interpolator, set the `z_interp_method` of the grid after building the {py:obj}`parcels.FieldSet`, which changes it for every field on that grid:\n", + "\n", + "```python\n", + "fieldset.U.grid.z_interp_method = parcels.interpolators.XVerticalCoordinateConstant()\n", + "```\n", + "\n", + "Parcels raises an error when the interpolator does not fit where z is defined, for example `XVerticalCoordinateConstant` with z on the cell corners." ] } ], "metadata": { "kernelspec": { - "display_name": "Parcels:default (3.14.8)", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -514,7 +745,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.8" + "version": "3.14.6" }, "mystnb": { "execution_in_temp": true diff --git a/docs/user_guide/group_fieldsets.md b/docs/user_guide/group_fieldsets.md index f3c351169..e4664ac35 100644 --- a/docs/user_guide/group_fieldsets.md +++ b/docs/user_guide/group_fieldsets.md @@ -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 diff --git a/src/parcels/_chunk_cached_array/core.py b/src/parcels/_chunk_cached_array/core.py index e155989e4..1d2ae436b 100644 --- a/src/parcels/_chunk_cached_array/core.py +++ b/src/parcels/_chunk_cached_array/core.py @@ -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] diff --git a/src/parcels/_core/model.py b/src/parcels/_core/model.py index 714e444ca..74b919f7d 100644 --- a/src/parcels/_core/model.py +++ b/src/parcels/_core/model.py @@ -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, @@ -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) @@ -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)}.") @@ -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( @@ -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) diff --git a/src/parcels/_core/particleset.py b/src/parcels/_core/particleset.py index 96a167256..760d94a56 100644 --- a/src/parcels/_core/particleset.py +++ b/src/parcels/_core/particleset.py @@ -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 ) if has_time_varying_z: raise ValueError( diff --git a/src/parcels/_core/uxgrid.py b/src/parcels/_core/uxgrid.py index 3927a8cea..2e1ef180b 100644 --- a/src/parcels/_core/uxgrid.py +++ b/src/parcels/_core/uxgrid.py @@ -1,16 +1,16 @@ 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 @@ -18,6 +18,19 @@ _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 @@ -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=...)``. """ @@ -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": + self.z_interp_method = UxVerticalCoordinateLinearNode() + else: + self.z_interp_method = UxVerticalCoordinateConstantFace() + @property def depth(self): """ @@ -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}") @@ -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 diff --git a/src/parcels/_core/xgrid.py b/src/parcels/_core/xgrid.py index c96fee26b..322a1d83c 100644 --- a/src/parcels/_core/xgrid.py +++ b/src/parcels/_core/xgrid.py @@ -1,4 +1,3 @@ -import warnings from collections.abc import Hashable, Sequence from functools import cached_property from typing import Literal, cast @@ -10,12 +9,13 @@ import parcels._sgrid as sgrid import parcels._typing as ptyping +from parcels._chunk_cached_array import ChunkCachedArray from parcels._core.basegrid import BaseGrid from parcels._core.index_search import _search_1d_array, _search_1d_columns, _search_indices_curvilinear_2d from parcels._core.mesh import BaseMesh -from parcels._core.warnings import FieldSetWarning from parcels._sgrid.accessor import _get_dim_to_axis_mapping, get_dim_position -from parcels.interpolators._xinterpolators import _get_offsets_dictionary +from parcels.interpolators._base import VerticalCoordinateInterpolator +from parcels.interpolators._xinterpolators import XVerticalCoordinateConstant, XVerticalCoordinateLinear _FIELD_DATA_ORDERING: Sequence[ptyping.XgcmAxisDirection] = "TZYX" _XGRID_AXES_ORDERING: Sequence[ptyping.XgridAxis] = "ZYX" @@ -129,6 +129,7 @@ def __init__(self, model_data: xr.Dataset, mesh: ptyping.TMesh): self._ds = model_data self.mesh = mesh self._spatialhash = None + self._z_interp_method = None ds = model_data axes = self.axes @@ -144,31 +145,41 @@ def __init__(self, model_data: xr.Dataset, mesh: ptyping.TMesh): ds = ds.set_coords([x_coordinate_name, y_coordinate_name]) assert_valid_lat_lon(ds[y_coordinate_name], ds[x_coordinate_name], self.sgrid_metadata) + self._ds = ds + if "Z" in axes: depth = ds["depth"] if depth.ndim not in (1, 4): raise ValueError(f"depth must be a 1D or 4D array of vertical coordinates, got {depth.ndim}D") if depth.ndim == 4: - assert self.sgrid_metadata.vertical_dimensions is not None - vertical_dim = self.sgrid_metadata.vertical_dimensions[0].node - fnp_x, fnp_y = self.sgrid_metadata.face_dimensions - expected_dims = ("time", vertical_dim, fnp_y.face, fnp_x.face) - if depth.dims != expected_dims: - raise ValueError(f"A 4D depth must have dims {expected_dims}, got {depth.dims}") - warnings.warn( - "Time-varying (4D) z coordinates are experimental and may cause significant memory overhead that " - f"leads to OOM errors. This z coordinate has sizes {dict(depth.sizes)} ({depth.nbytes / 1e9:.3g} GB). " - f"Assumptions: z has dims {expected_dims}, i.e. it is " - f"defined at the layer interfaces on the cell centres, and is strictly increasing along " - f"{vertical_dim!r}; each particle uses the z column at the centre of its grid cell, so z is constant " - "within a cell and jumps between cells, it is linearly interpolated in time between z snapshots.", - FieldSetWarning, - stacklevel=5, - ) + self._init_time_varying_depth() else: assert_valid_depth(depth) - self._ds = ds + def _init_time_varying_depth(self) -> None: + """Checks the dims of a time-varying (4D) depth and assigns its default z_interp_method.""" + depth = self.depth + + assert self.sgrid_metadata.vertical_dimensions is not None + vertical_dim = self.sgrid_metadata.vertical_dimensions[0].node + + fnp_x, fnp_y = self.sgrid_metadata.face_dimensions + face_registered_dims = ("time", vertical_dim, fnp_y.face, fnp_x.face) + node_registered_dims = ("time", vertical_dim, fnp_y.node, fnp_x.node) + + if set(depth.dims) not in (set(face_registered_dims), set(node_registered_dims)): + raise ValueError( + f"A 4D depth must have dims {face_registered_dims} (cell centres) or {node_registered_dims} " + f"(cell corners), in any order, got {depth.dims}" + ) + + self._ds.coords["depth"] = _transpose_xfield_data_to_tzyx(depth, self.sgrid_metadata) + depth = self.depth + + if is_dask_collection(depth.data): + depth.variable._data = ChunkCachedArray(depth.data, max_cache_bytes=600_000_000) + + self.z_interp_method = XVerticalCoordinateLinear() # def __repr__(self): # return xgrid_repr(self) @@ -177,6 +188,27 @@ def __init__(self, model_data: xr.Dataset, mesh: ptyping.TMesh): def axes(self) -> list[ptyping.XgridAxis]: return _get_xgrid_axes(self.sgrid_metadata, set(self._ds.dims)) + @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 != 4: + raise ValueError("z_interp_method can only be set on a grid with a time-varying (4D) depth") + fnp_x, fnp_y = self.sgrid_metadata.face_dimensions + cell_centre_dims = (fnp_y.face, fnp_x.face) + if isinstance(value, XVerticalCoordinateConstant) and self.depth.dims[-2:] != cell_centre_dims: + raise ValueError( + f"XVerticalCoordinateConstant needs depth on the cell centres {cell_centre_dims}, got dims {self.depth.dims}" + ) + self._z_interp_method = value + @property def lon(self): """ @@ -219,6 +251,9 @@ def depth(self): """ if "Z" not in self.axes: return np.zeros(1) + # Load time varying z lazily + if self._ds["depth"].ndim == 4: + return self._ds["depth"] return self._ds["depth"].values @property @@ -379,7 +414,7 @@ def search(self, z, y, x, ei=None, ti=None, tau=None): raise NotImplementedError("Searching in >2D lon/lat arrays is not implemented yet.") if "Z" in self.axes and ds.depth.ndim == 4: - zi, zeta = self._search_time_varying_depth(z, yi, xi, ti, tau) + zi, zeta = self._search_time_varying_depth(z, ti, tau, yi, eta, xi, xsi) elif "Z" in self.axes: zi, zeta = _search_1d_array(ds.depth.values, z) else: @@ -391,35 +426,18 @@ def search(self, z, y, x, ei=None, ti=None, tau=None): "X": {"index": xi, "bcoord": xsi}, } - def _search_time_varying_depth(self, z, yi, xi, ti, tau): - """Vertical search of each particle in the z column at the centre of its cell using temporal linear - interpolation between the snapshots ti and ti + 1. - """ + def _search_time_varying_depth(self, z, ti, tau, yi, eta, xi, xsi): + """Vertical search of each particle in the z column built by the grid's z_interp_method.""" found = (yi >= 0) & (xi >= 0) - offsets = _get_offsets_dictionary(self) - yi_centre = yi[found] + offsets["Y"] - xi_centre = xi[found] + offsets["X"] - - depth = self._ds["depth"] - fnp_x, fnp_y = self.sgrid_metadata.face_dimensions - cell_centres = { - fnp_y.face: xr.DataArray(yi_centre, dims="points"), - fnp_x.face: xr.DataArray(xi_centre, dims="points"), + grid_positions = { + "T": {"index": np.broadcast_to(ti, yi.shape)[found], "bcoord": np.broadcast_to(tau, yi.shape)[found]}, + "Y": {"index": yi[found], "bcoord": eta[found]}, + "X": {"index": xi[found], "bcoord": xsi[found]}, } - ti_found = np.broadcast_to(ti, yi.shape)[found] - columns_ti = depth.isel({"time": xr.DataArray(ti_found, dims="points"), **cell_centres}) - - if depth.sizes["time"] == 1: - cell_columns = columns_ti - else: - columns_tnext = depth.isel({"time": xr.DataArray(ti_found + 1, dims="points"), **cell_centres}) - tau_found = xr.DataArray(np.broadcast_to(tau, yi.shape)[found], dims="points") - cell_columns = (1 - tau_found) * columns_ti + tau_found * columns_tnext - # Particles outside the grid are given a NaN z column for vertical searching - columns = np.full((yi.size, cell_columns.shape[1]), np.nan) - columns[found] = cell_columns.values + columns = np.full((yi.size, self.depth.shape[1]), np.nan) + columns[found] = self.z_interp_method.columns(grid_positions, self) zi, zeta = _search_1d_columns(columns, z) # Particles outside the grid are given a 0 vertical index and a NaN vertical barycentric coordinate diff --git a/src/parcels/_repr_utils.py b/src/parcels/_repr_utils.py index 4ca3888eb..d76a745be 100644 --- a/src/parcels/_repr_utils.py +++ b/src/parcels/_repr_utils.py @@ -130,6 +130,11 @@ def timeinterval_repr(ti: Any) -> str: return f"TimeInterval(left={ti.left!r}, right={ti.right!r})" +def interpolator_repr(interp: Any) -> str: + """Return a pretty repr for scalar, vector and vertical coordinate interpolators""" + return f"{type(interp).__name__}(...)" + + def particlefile_repr(pfile: Any) -> str: """Return a pretty repr for ParticleFile""" out = f"""<{type(pfile).__name__}> diff --git a/src/parcels/interpolators/__init__.py b/src/parcels/interpolators/__init__.py index 2f131c546..752a51965 100644 --- a/src/parcels/interpolators/__init__.py +++ b/src/parcels/interpolators/__init__.py @@ -6,6 +6,8 @@ UxConstantFaceLinearZF, UxLinearNodeConstantZC, UxLinearNodeLinearZF, + UxVerticalCoordinateConstantFace, + UxVerticalCoordinateLinearNode, ) from ._xinterpolators import ( CGrid_Tracer, @@ -17,6 +19,9 @@ XLinearInvdistLandTracer, XNearest, XPartialslip, + XVerticalCoordinateConstant, + XVerticalCoordinateLinear, + XVerticalCoordinateNearest, ) __all__ = [ # noqa: RUF022 @@ -30,6 +35,9 @@ "XLinear_Velocity", "XNearest", "XPartialslip", + "XVerticalCoordinateConstant", + "XVerticalCoordinateLinear", + "XVerticalCoordinateNearest", # uxinterpolators "Ux_Velocity", "UxConstantFaceConstantZC", @@ -38,4 +46,6 @@ "UxConstantEdgeLinearZF", "UxLinearNodeConstantZC", "UxLinearNodeLinearZF", + "UxVerticalCoordinateConstantFace", + "UxVerticalCoordinateLinearNode", ] diff --git a/src/parcels/interpolators/_base.py b/src/parcels/interpolators/_base.py index 6a550b240..a41e4c236 100644 --- a/src/parcels/interpolators/_base.py +++ b/src/parcels/interpolators/_base.py @@ -1,20 +1,63 @@ from abc import ABC, abstractmethod +from types import SimpleNamespace from typing import Any +import numpy as np + +from parcels._repr_utils import interpolator_repr + class ScalarInterpolator(ABC): @abstractmethod - def interp(self, particle_positions, grid_positions, field) -> Any: #! API a WIP - ... + def interp(self, particle_positions, grid_positions, field) -> Any: ... def __repr__(self): - return f"{self.__class__.__name__}(...)" + return interpolator_repr(self) class VectorInterpolator(ABC): @abstractmethod - def interp(self, particle_positions, grid_positions, vectorfield) -> Any: #! API a WIP + def interp(self, particle_positions, grid_positions, vectorfield) -> Any: ... + + def __repr__(self): + return interpolator_repr(self) + + +class VerticalCoordinateInterpolator(ABC): + """Base class for the interpolators that build each particle's z column on a grid with a time-varying z. + + Unlike ScalarInterpolator and VectorInterpolator, which interpolate a field's values onto the particle positions, + these interpolators are part of the particle search. They interpolate the grid's z coordinate horizontally and in + time to give each particle a column of layer interface depths, which is then searched for the particle's vertical + index. They are therefore set on the grid (``grid.z_interp_method``) rather than on a field. + """ + + @abstractmethod + def columns(self, grid_positions, grid) -> np.ndarray: + """Returns each particle's z column as an (npart, n_interfaces) array.""" ... + def _columns_from_scalar(self, interp: ScalarInterpolator, grid_positions, grid) -> np.ndarray: + """Evaluates a scalar interpolator on the grid's time-varying depth at every vertical level, giving each + particle's z column as an (npart, nlev) array. This is effectively only a horizontal and temporal interpolation, any + input vertical position or barycentric coordinate is ignored. + """ + nlev = grid.depth.shape[1] + npart = next(np.shape(pos["index"])[0] for axis, pos in grid_positions.items() if axis != "T") + + def repeat(a): + a = np.broadcast_to(a, (npart, *np.shape(a)[1:])) + return np.repeat(a, nlev, axis=0) + + level_positions = { + axis: {"index": repeat(pos["index"]), "bcoord": repeat(pos["bcoord"])} + for axis, pos in grid_positions.items() + } + level_positions["Z"] = {"index": np.tile(np.arange(nlev), npart), "bcoord": np.zeros(npart * nlev)} + + # Scalar interpolators only use ``field.data`` and ``field.grid``, so a lightweight stand-in for the depth works + depth_field = SimpleNamespace(data=grid.depth, grid=grid) + return np.asarray(interp.interp({}, level_positions, depth_field)).reshape(npart, nlev) + def __repr__(self): - return f"{self.__class__.__name__}(...)" + return interpolator_repr(self) diff --git a/src/parcels/interpolators/_uxinterpolators.py b/src/parcels/interpolators/_uxinterpolators.py index 6db1000eb..752d3f23b 100644 --- a/src/parcels/interpolators/_uxinterpolators.py +++ b/src/parcels/interpolators/_uxinterpolators.py @@ -8,11 +8,11 @@ import xarray as xr from dask import is_dask_collection -from parcels.interpolators._base import ScalarInterpolator, VectorInterpolator +from parcels.interpolators._base import ScalarInterpolator, VectorInterpolator, VerticalCoordinateInterpolator if TYPE_CHECKING: from parcels._core.field import Field, VectorField - from parcels._core.uxgrid import _UXGRID_AXES + from parcels._core.uxgrid import _UXGRID_AXES, UxGrid class UxConstantFaceConstantZC(ScalarInterpolator): @@ -25,17 +25,29 @@ def interp( field: Field, ): # Broadcast the per-axis indices to a common (npart,) shape (``ti`` may be scalar for time-constant fields) - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) tdim, zdim, fdim = field.data.dims + + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(zi, dims="points"), fdim: xr.DataArray(fi, dims="points"), } - value = field.data.isel(selection_dict, ignore_grid=True).data + face_data = field.data.isel(selection_dict, ignore_grid=True) + + # Linear interpolation in time between the snapshots ti and ti + 1 + value = (face_data * xr.DataArray(t_weights, dims=("tlevels", "points"))).sum("tlevels").data return value.compute() if is_dask_collection(value) else value @@ -51,28 +63,41 @@ def interp( grid_positions: dict[_UXGRID_AXES, dict[str, int | float | np.ndarray]], field: Field, ): - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) zeta = grid_positions["Z"]["bcoord"] tdim, zdim, fdim = field.data.dims - def _zsample(z_index): - """Pointwise ``isel`` of the face values at a single vertical interface level.""" + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) + time_weights = xr.DataArray(t_weights, dims=("tlevels", "points")) + + def _z_and_t_sample(z_index): + """Pointwise ``isel`` of the face values at a single vertical interface level, linear in time between the + snapshots ti and ti + 1. + """ selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(z_index, dims="points"), fdim: xr.DataArray(fi, dims="points"), } - value = field.data.isel(selection_dict, ignore_grid=True).data + face_data = field.data.isel(selection_dict, ignore_grid=True) + value = (face_data * time_weights).sum("tlevels").data return value.compute() if is_dask_collection(value) else value # The zi refers to the vertical layer index. The field in this routine are assumed to be defined at the vertical interface levels. # For interface zi, the interface indices are [zi, zi+1], so we need to use the values at zi and zi+1. # First, do barycentric interpolation in the lateral direction for each interface level - fzk = _zsample(zi) - fzkp1 = _zsample(zi + 1) + fzk = _z_and_t_sample(zi) + fzkp1 = _z_and_t_sample(zi + 1) # Then, do piecewise linear interpolation in the vertical direction return fzk * (1 - zeta) + fzkp1 * zeta @@ -92,21 +117,32 @@ def interp( Effectively, it applies barycentric interpolation in the lateral direction and piecewise constant interpolation in the vertical direction. """ - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) bcoords = xr.DataArray(grid_positions["FACE"]["bcoord"], dims=("points", "nodes")) node_ids = field.grid.uxgrid.face_node_connectivity[fi, :].values tdim, zdim, ndim = field.data.dims + + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(zi, dims="points"), ndim: xr.DataArray(node_ids, dims=("points", "nodes")), } node_data = field.data.isel(selection_dict, ignore_grid=True) - value = (node_data * bcoords).sum("nodes").data # Barycentric interpolation in the lateral direction + # Barycentric interpolation in the lateral direction and linear interpolation in time + weights = bcoords * xr.DataArray(t_weights, dims=("tlevels", "points")) + value = (node_data * weights).sum(("nodes", "tlevels")).data return value.compute() if is_dask_collection(value) else value @@ -124,8 +160,11 @@ def interp( Effectively, it applies barycentric interpolation in the lateral direction and piecewise linear interpolation in the vertical direction. """ - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) zeta = grid_positions["Z"]["bcoord"] bcoords = xr.DataArray(grid_positions["FACE"]["bcoord"], dims=("points", "nodes")) @@ -133,22 +172,32 @@ def interp( tdim, zdim, ndim = field.data.dims - def _zsample(z_index): - """Barycentric (lateral) interpolation of the node values at a single vertical interface level.""" + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) + # Barycentric weights in the lateral direction combined with linear weights in time + weights = bcoords * xr.DataArray(t_weights, dims=("tlevels", "points")) + + def _z_and_t_sample(z_index): + """Barycentric (lateral) interpolation of the node values at a single vertical interface level, linear in + time between the snapshots ti and ti + 1. + """ selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(z_index, dims="points"), ndim: xr.DataArray(node_ids, dims=("points", "nodes")), } - # Reduce over the "nodes" dimension by name so the result is independent of ``isel`` dim order. + # Reduce over the "nodes" and "tlevels" dimensions by name so the result is independent of ``isel`` dim order. node_data = field.data.isel(selection_dict, ignore_grid=True) - return (node_data * bcoords).sum("nodes").data + return (node_data * weights).sum(("nodes", "tlevels")).data # The zi refers to the vertical layer index. The field in this routine are assumed to be defined at the vertical interface levels. # For interface zi, the interface indices are [zi, zi+1], so we need to use the values at zi and zi+1. # First, do barycentric interpolation in the lateral direction for each interface level - fzk = _zsample(zi) - fzkp1 = _zsample(zi + 1) + fzk = _z_and_t_sample(zi) + fzkp1 = _z_and_t_sample(zi + 1) # Then, do piecewise linear interpolation in the vertical direction value = fzk * (1 - zeta) + fzkp1 * zeta @@ -168,19 +217,31 @@ def interp( field: Field, ): # Broadcast the per-axis indices to a common (npart,) shape (``ti`` may be scalar for time-constant fields) - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) edge_ids = field.grid.uxgrid.face_edge_connectivity[fi, :].values tdim, zdim, edim = field.data.dims + + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(zi, dims="points"), edim: xr.DataArray(edge_ids, dims=("points", "edges")), } edge_data = field.data.isel(selection_dict, ignore_grid=True) - value = edge_data.mean("edges").data # Face value is the mean of its surrounding edges + face_data = edge_data.mean("edges") # Face value is the mean of its surrounding edges + + # Linear interpolation in time between the snapshots ti and ti + 1 + value = (face_data * xr.DataArray(t_weights, dims=("tlevels", "points"))).sum("tlevels").data return value.compute() if is_dask_collection(value) else value @@ -198,27 +259,39 @@ def interp( field: Field, ): # Broadcast the per-axis indices to a common (npart,) shape (``ti`` may be scalar for time-constant fields) - ti, zi, fi = np.broadcast_arrays( - grid_positions["T"]["index"], grid_positions["Z"]["index"], grid_positions["FACE"]["index"] + ti, tau, zi, fi = np.broadcast_arrays( + grid_positions["T"]["index"], + grid_positions["T"]["bcoord"], + grid_positions["Z"]["index"], + grid_positions["FACE"]["index"], ) zeta = grid_positions["Z"]["bcoord"] edge_ids = field.grid.uxgrid.face_edge_connectivity[fi, :].values tdim, zdim, edim = field.data.dims - def _zsample(z_index): - """Mean of the edge values surrounding each face at a single vertical interface level.""" + if np.any(tau > 0): + t_levels = np.stack([ti, np.clip(ti + 1, 0, field.data.sizes[tdim] - 1)]) + t_weights = np.stack([1 - tau, tau]) + else: + t_levels, t_weights = ti[np.newaxis], np.ones((1, ti.size)) + time_weights = xr.DataArray(t_weights, dims=("tlevels", "points")) + + def _z_and_t_sample(z_index): + """Mean of the edge values surrounding each face at a single vertical interface level, linear in time + between the snapshots ti and ti + 1. + """ selection_dict = { - tdim: xr.DataArray(ti, dims="points"), + tdim: xr.DataArray(t_levels, dims=("tlevels", "points")), zdim: xr.DataArray(z_index, dims="points"), edim: xr.DataArray(edge_ids, dims=("points", "edges")), } edge_data = field.data.isel(selection_dict, ignore_grid=True) - return edge_data.mean("edges").data + return (edge_data.mean("edges") * time_weights).sum("tlevels").data # zi is the vertical layer index, bounded by the interface levels zi and zi + 1 - fzk = _zsample(zi) - fzkp1 = _zsample(zi + 1) + fzk = _z_and_t_sample(zi) + fzkp1 = _z_and_t_sample(zi + 1) value = fzk * (1 - zeta) + fzkp1 * zeta return value.compute() if is_dask_collection(value) else value @@ -243,3 +316,21 @@ def interp( else: w = np.zeros_like(u) return u, v, w + + +class UxVerticalCoordinateConstantFace(VerticalCoordinateInterpolator): + """Piecewise constant over the face (face registered z), linear in time.""" + + def columns( + self, grid_positions: dict[_UXGRID_AXES, dict[str, int | float | np.ndarray]], grid: UxGrid + ) -> np.ndarray: + return self._columns_from_scalar(UxConstantFaceConstantZC(), grid_positions, grid) + + +class UxVerticalCoordinateLinearNode(VerticalCoordinateInterpolator): + """Barycentric from the face's nodes (node registered z), linear in time.""" + + def columns( + self, grid_positions: dict[_UXGRID_AXES, dict[str, int | float | np.ndarray]], grid: UxGrid + ) -> np.ndarray: + return self._columns_from_scalar(UxLinearNodeConstantZC(), grid_positions, grid) diff --git a/src/parcels/interpolators/_xinterpolators.py b/src/parcels/interpolators/_xinterpolators.py index ae32932cc..4e98181c2 100644 --- a/src/parcels/interpolators/_xinterpolators.py +++ b/src/parcels/interpolators/_xinterpolators.py @@ -11,7 +11,8 @@ import parcels._core.utils.interpolation as i_u import parcels._sgrid as sgrid import parcels._typing as ptyping -from parcels.interpolators._base import ScalarInterpolator, VectorInterpolator +from parcels._sgrid.accessor import get_dim_position +from parcels.interpolators._base import ScalarInterpolator, VectorInterpolator, VerticalCoordinateInterpolator if TYPE_CHECKING: from parcels._core._windowed_array import WindowedArray @@ -635,3 +636,82 @@ def interp( values[exact_particles] = exact_vals[exact_particles] return values.compute() if is_dask_collection(values) else values + + +class XVerticalCoordinateConstant(VerticalCoordinateInterpolator): + """Piecewise constant over the grid cell (face registered z), linear in time. + + Each particle uses the z column at the centre of its cell, so z is discontinuous between cells. + """ + + def columns( + self, grid_positions: dict[ptyping.XgridAxis, dict[str, int | float | np.ndarray]], grid: XGrid + ) -> np.ndarray: + # Search indices are cells (indexed by their lower node). Point each particle exactly (bcoord 0) at its cell's + # face, so XNearest picks that single column. + offsets = _get_offsets_dictionary(grid) + yi, xi = grid_positions["Y"]["index"], grid_positions["X"]["index"] + cell_centre_positions = { + "T": grid_positions["T"], + "Y": {"index": yi + offsets["Y"], "bcoord": np.zeros(np.shape(yi))}, + "X": {"index": xi + offsets["X"], "bcoord": np.zeros(np.shape(xi))}, + } + return self._columns_from_scalar(XNearest(), cell_centre_positions, grid) + + +def _position_between_cell_centres(face_index: np.ndarray, bcoord: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + """Moves an index/barycentric coordinate combination back by half a cell in index space. + + The grid search gives positions relative to the nodes, but face registered data lives at the cell centres, half a + cell further along. Shifting back by half a cell gives the position relative to the cell centres, so node based + interpolators (e.g. XLinear) can interpolate face registered data. Positions before the first cell centre are + clamped onto it. ``face_index`` is the particle's cell in face indices, i.e. the search index plus the padding + offset from ``_get_offsets_dictionary``. + """ + upper_half = bcoord >= 0.5 + lower_face = np.where(upper_half, face_index, face_index - 1) + centre_bcoord = np.where(upper_half, bcoord - 0.5, bcoord + 0.5) + below_first_centre = lower_face < 0 + return np.where(below_first_centre, 0, lower_face), np.where(below_first_centre, 0.0, centre_bcoord) + + +class XVerticalCoordinateLinear(VerticalCoordinateInterpolator): + """Bilinear between the surrounding z columns (face or node registered z), linear in time. + + Node registered z is interpolated from the corners of the particle's cell. Face registered z is interpolated from + the four cell centres around the particle. Both are continuous in space. Beyond the outermost cell centres z is + constant. + """ + + def columns( + self, grid_positions: dict[ptyping.XgridAxis, dict[str, int | float | np.ndarray]], grid: XGrid + ) -> np.ndarray: + if get_dim_position(grid.sgrid_metadata, grid.depth.dims[-1]) == "face": + offsets = _get_offsets_dictionary(grid) + yi, eta = _position_between_cell_centres( + grid_positions["Y"]["index"] + offsets["Y"], grid_positions["Y"]["bcoord"] + ) + xi, xsi = _position_between_cell_centres( + grid_positions["X"]["index"] + offsets["X"], grid_positions["X"]["bcoord"] + ) + grid_positions = { + "T": grid_positions["T"], + "Y": {"index": yi, "bcoord": eta}, + "X": {"index": xi, "bcoord": xsi}, + } + return self._columns_from_scalar(XLinear(), grid_positions, grid) + + +class XVerticalCoordinateNearest(VerticalCoordinateInterpolator): + """Nearest z column (face or node registered z), linear in time. + + For node registered z this is the nearest corner of the particle's cell. For face registered z the nearest cell + centre is the particle's own cell, so this is the same as XVerticalCoordinateConstant. + """ + + def columns( + self, grid_positions: dict[ptyping.XgridAxis, dict[str, int | float | np.ndarray]], grid: XGrid + ) -> np.ndarray: + if get_dim_position(grid.sgrid_metadata, grid.depth.dims[-1]) == "face": + return XVerticalCoordinateConstant().columns(grid_positions, grid) + return self._columns_from_scalar(XNearest(), grid_positions, grid) diff --git a/tests/test_advection.py b/tests/test_advection.py index e12b05b4b..84c843a09 100644 --- a/tests/test_advection.py +++ b/tests/test_advection.py @@ -577,7 +577,6 @@ def test_mitgcm(): np.testing.assert_allclose(pset.y, lat_v3, atol=1) -@pytest.mark.filterwarnings("ignore:Time-varying \\(4D\\) z coordinates are experimental") def test_advection_on_moving_sigma_grid_keeps_depth(): """With uniform u and w = 0, particles keep their depth while the sigma levels move past them.""" n_snapshots, nz, ny, nx = 3, 6, 5, 5 diff --git a/tests/test_fieldset.py b/tests/test_fieldset.py index a8f9ff059..488b812a7 100644 --- a/tests/test_fieldset.py +++ b/tests/test_fieldset.py @@ -727,7 +727,6 @@ def test_fieldset_describe_backends(tmp_path): # TODO: Add test for the ChunkedArray backend (can also refactor this test at the same time) -@pytest.mark.filterwarnings("ignore:Time-varying \\(4D\\) z coordinates are experimental") @pytest.mark.parametrize( "n_snapshots", [ diff --git a/tests/test_uxadvection.py b/tests/test_uxadvection.py index 9d7babd18..e0eeccb2d 100644 --- a/tests/test_uxadvection.py +++ b/tests/test_uxadvection.py @@ -30,7 +30,6 @@ def test_ux_constant_flow_face_centered_2D(integrator, tmp_parquet): np.testing.assert_allclose(df["x"].iloc[-1], expected_lon, atol=1e-5) -@pytest.mark.filterwarnings("ignore:Time-varying \\(3D\\) z coordinates are experimental") def test_ux_advection_on_moving_sigma_grid_keeps_depth(): """With uniform u and w = 0, particles keep their depth while the sigma levels move past them.""" nx, nz = 5, 6 diff --git a/tests/test_uxarray_fieldset.py b/tests/test_uxarray_fieldset.py index b8a748f37..3573b9096 100644 --- a/tests/test_uxarray_fieldset.py +++ b/tests/test_uxarray_fieldset.py @@ -11,6 +11,7 @@ UxGrid, convert, ) +from parcels._chunk_cached_array import ChunkCachedArray from parcels._core.mesh import FlatMesh, SphericalMesh from parcels._core.model import UnstructuredModelData from parcels._datasets.unstructured.generated import sigma_coordinate_lattice_dataset, simple_small_delaunay @@ -206,6 +207,41 @@ def test_from_ugrid_conventions_selects_correct_interpolator(): assert isinstance(getattr(fieldset, f"{lateral_dim}_{vertical_dim}").interp_method, expected_interpolator) +def test_ux_interpolators_are_linear_in_time(): + """The default interpolator of every registration is linear in time between snapshots (fields uniform in space).""" + ds = convert.icon_to_ugrid(datasets_unstructured["icon_square_delaunay_uniform_z_coordinate"].copy(deep=True)) + rng = np.random.default_rng(0) + value_at_snapshots = rng.random(ds.sizes["time"]) + registrations = [ + ("zc", "n_face"), + ("zf", "n_face"), + ("zc", "n_node"), + ("zf", "n_node"), + ("zc", "n_edge"), + ("zf", "n_edge"), + ] + for vertical_dim, lateral_dim in registrations: + shape = (ds.sizes["time"], ds.sizes[vertical_dim], getattr(ds.uxgrid, lateral_dim)) + ds[f"{lateral_dim}_{vertical_dim}"] = ux.UxDataArray( + np.broadcast_to(value_at_snapshots[:, np.newaxis, np.newaxis], shape), + dims=["time", vertical_dim, lateral_dim], + coords={"time": ds.time, vertical_dim: ds[vertical_dim]}, + uxgrid=ds.uxgrid, + ) + fieldset = FieldSet.from_ugrid_conventions(ds) + + # One particle at each face centre, at a random time (in seconds since the first snapshot) + xc, yc = ds.uxgrid.face_lon.values, ds.uxgrid.face_lat.values + zq = np.full(xc.shape, 300.0) + snapshot_times = (ds.time.values - ds.time.values[0]) / np.timedelta64(1, "s") + tq = rng.uniform(snapshot_times[0], snapshot_times[-1], xc.size) + + expected = np.interp(tq, snapshot_times, value_at_snapshots) + for vertical_dim, lateral_dim in registrations: + values = getattr(fieldset, f"{lateral_dim}_{vertical_dim}").eval(t=tq, z=zq, y=yc, x=xc) + np.testing.assert_allclose(values, expected, err_msg=f"{lateral_dim}_{vertical_dim}") + + _NESTEDGRIDS_NODES = np.array( [ [10.0, 15.0], @@ -264,7 +300,6 @@ def test_nestedgrids_triangulation_spherical_search(): RISING_ETA = np.broadcast_to(np.linspace(-1.0, 1.0, 3)[:, np.newaxis, np.newaxis], (3, 5, 5)) -@pytest.mark.filterwarnings("ignore:Time-varying \\(3D\\) z coordinates are experimental") @pytest.mark.parametrize( "eta, expected_n_snapshots", [ @@ -284,7 +319,15 @@ def test_fieldset_from_sigma_coordinate_dataset(eta, expected_n_snapshots): assert isinstance(field.interp_method, UxLinearNodeLinearZF) -@pytest.mark.filterwarnings("ignore:Time-varying \\(3D\\) z coordinates are experimental") +def test_uxgrid_dask_time_varying_z_is_chunk_cached(): + ds = sigma_coordinate_lattice_dataset(5, (0.0, 4e3), (0.0, 4e3), 4, SLOPING_BOTTOM_DEPTH, RISING_ETA) + ds = ds.chunk({"time": 1}) + + grid = FieldSet.from_ugrid_conventions(ds).U.grid + + assert isinstance(grid.z.variable._data, ChunkCachedArray) + + def test_unstructured_model_data_rejects_z_with_different_time_coordinate(): ds = sigma_coordinate_lattice_dataset(5, (0.0, 4e3), (0.0, 4e3), 4, SLOPING_BOTTOM_DEPTH, RISING_ETA) ds_one_day_later = sigma_coordinate_lattice_dataset( diff --git a/tests/test_vertical_coordinate_interpolators.py b/tests/test_vertical_coordinate_interpolators.py new file mode 100644 index 000000000..01b67bdba --- /dev/null +++ b/tests/test_vertical_coordinate_interpolators.py @@ -0,0 +1,216 @@ +from types import SimpleNamespace + +import numpy as np +import pytest +import uxarray as ux + +from parcels import FieldSet, UxGrid +from parcels._core.mesh import FlatMesh +from parcels._datasets.structured.generated import simple_UV_sigma_dataset +from parcels._datasets.unstructured.generated import sigma_coordinate_lattice_dataset +from parcels.interpolators import ( + UxConstantFaceConstantZC, + UxVerticalCoordinateConstantFace, + UxVerticalCoordinateLinearNode, + XLinear, + XVerticalCoordinateConstant, + XVerticalCoordinateLinear, + XVerticalCoordinateNearest, +) +from parcels.interpolators._base import ScalarInterpolator +from parcels.interpolators._xinterpolators import _get_offsets_dictionary, _position_between_cell_centres + +# Time-varying depth used to test the vertical coordinate interpolators. It is linear in level, lateral index and time, +# so the expected z column of each interpolator can be written down exactly, and strictly increasing along the levels. +SIGMA_SHAPE = {"n_times": 3, "nz": 5, "ny": 8, "nx": 8} +DEPTH_PER_LEVEL, DEPTH_PER_Y, DEPTH_PER_X, DEPTH_PER_TIME = 10.0, 0.3, 0.2, 0.1 + + +def _linear_depth(level, y, x, t): + return DEPTH_PER_LEVEL * level + DEPTH_PER_Y * y + DEPTH_PER_X * x + DEPTH_PER_TIME * t + + +def _sigma_grid(registration): + """XGrid with a time-varying depth on the cell centres ("face") or on the cell corners ("node").""" + ds = simple_UV_sigma_dataset(**SIGMA_SHAPE) + lateral_dims = ("YC", "XC") if registration == "face" else ("YG", "XG") + t, level, y, x = np.meshgrid(*(np.arange(n) for n in SIGMA_SHAPE.values()), indexing="ij") + ds = ds.assign_coords(depth=(("time", "ZF", *lateral_dims), _linear_depth(level, y, x, t), {"axis": "Z"})) + return FieldSet.from_sgrid_conventions(ds).U.grid + + +def _random_grid_positions(npart, seed=0): + """Positions in the interior of the grid, away from the edges where the face registered columns are clamped.""" + rng = np.random.default_rng(seed) + return { + "T": {"index": rng.integers(0, SIGMA_SHAPE["n_times"] - 1, npart), "bcoord": rng.random(npart)}, + "Y": {"index": rng.integers(1, SIGMA_SHAPE["ny"] - 3, npart), "bcoord": rng.random(npart)}, + "X": {"index": rng.integers(1, SIGMA_SHAPE["nx"] - 3, npart), "bcoord": rng.random(npart)}, + } + + +# Expected lateral position of a particle's z column, from its search index (i), barycentric coordinate (b) and the +# padding offset between cell and face indices (o), measured in the indices of the registration's depth +def _cell_centre(i, b, o): + return i + o + + +def _nearest_corner(i, b, o): + return i + (b > 0.5) + + +def _position_in_face_indices(i, b, o): + return i + o + b - 0.5 + + +def _position_in_node_indices(i, b, o): + return i + b + + +@pytest.mark.parametrize( + ("z_interp_method", "registration", "expected_y", "expected_x"), + [ + # Columns at the particle's cell centre (face indices are the cell indices plus the padding offset) + pytest.param(XVerticalCoordinateConstant(), "face", _cell_centre, _cell_centre, id="constant-face"), + pytest.param(XVerticalCoordinateNearest(), "face", _cell_centre, _cell_centre, id="nearest-face"), + # Column at the nearest corner of the particle's cell + pytest.param(XVerticalCoordinateNearest(), "node", _nearest_corner, _nearest_corner, id="nearest-node"), + # Bilinear interpolation reproduces the linear depth at the particle's position, measured in face or node indices + pytest.param( + XVerticalCoordinateLinear(), "face", _position_in_face_indices, _position_in_face_indices, id="linear-face" + ), + pytest.param( + XVerticalCoordinateLinear(), "node", _position_in_node_indices, _position_in_node_indices, id="linear-node" + ), + ], +) +@pytest.mark.parametrize("time_varying", [True, False]) +def test_vertical_coordinate_columns(z_interp_method, registration, expected_y, expected_x, time_varying): + grid = _sigma_grid(registration) + grid.z_interp_method = z_interp_method + offsets = _get_offsets_dictionary(grid) + grid_positions = _random_grid_positions(npart=200) + if not time_varying: + grid_positions["T"] = {"index": 1, "bcoord": 0.0} # scalar time position, as on a time-constant grid + + columns = grid.z_interp_method.columns(grid_positions, grid) + + expected = _linear_depth( + np.arange(SIGMA_SHAPE["nz"])[np.newaxis, :], + expected_y(grid_positions["Y"]["index"], grid_positions["Y"]["bcoord"], offsets["Y"])[:, np.newaxis], + expected_x(grid_positions["X"]["index"], grid_positions["X"]["bcoord"], offsets["X"])[:, np.newaxis], + np.add(grid_positions["T"]["index"], grid_positions["T"]["bcoord"])[..., np.newaxis] if time_varying else 1.0, + ) + assert columns.shape == (200, SIGMA_SHAPE["nz"]) + np.testing.assert_allclose(columns, expected) + + +@pytest.mark.parametrize("registration", ["face", "node"]) +def test_vertical_coordinate_linear_is_continuous(registration): + """z is continuous across cell edges, and across the cell centre (where face registered z changes the bracketing + cell centres it interpolates between).""" + ds = simple_UV_sigma_dataset(**SIGMA_SHAPE) + lateral_dims = ("YC", "XC") if registration == "face" else ("YG", "XG") + rng = np.random.default_rng(1) + depth = ds["depth"].values + rng.random(ds["depth"].shape) * 0.01 # non-linear depth, unlike _sigma_grid + ds = ds.assign_coords(depth=(("time", "ZF", *lateral_dims), depth, {"axis": "Z"})) + grid = FieldSet.from_sgrid_conventions(ds).U.grid + grid_positions = _random_grid_positions(npart=100) + yi, npart = grid_positions["Y"]["index"], len(grid_positions["Y"]["index"]) + + def columns_at(y_index, y_bcoord): + return grid.z_interp_method.columns( + {**grid_positions, "Y": {"index": y_index, "bcoord": np.full(npart, y_bcoord)}}, grid + ) + + np.testing.assert_allclose(columns_at(yi, 1.0), columns_at(yi + 1, 0.0)) + np.testing.assert_allclose(columns_at(yi, 0.5 - 1e-12), columns_at(yi, 0.5)) + + +@pytest.mark.parametrize( + ("face_index", "bcoord", "expected_index", "expected_bcoord"), + [ + pytest.param(3, 0.75, 3, 0.25, id="upper-half-of-cell"), + pytest.param(3, 0.5, 3, 0.0, id="at-cell-centre"), + pytest.param(3, 0.25, 2, 0.75, id="lower-half-of-cell"), + pytest.param(0, 0.25, 0, 0.0, id="clamped-before-first-cell-centre"), + ], +) +def test_position_between_cell_centres(face_index, bcoord, expected_index, expected_bcoord): + index, centre_bcoord = _position_between_cell_centres(np.array([face_index]), np.array([bcoord])) + assert index[0] == expected_index + np.testing.assert_allclose(centre_bcoord[0], expected_bcoord) + + +def test_z_interp_method_defaults_and_validation(): + face_grid, node_grid = _sigma_grid("face"), _sigma_grid("node") + assert isinstance(face_grid.z_interp_method, XVerticalCoordinateLinear) + assert isinstance(node_grid.z_interp_method, XVerticalCoordinateLinear) + + with pytest.raises(ValueError, match="needs depth on the cell centres"): + node_grid.z_interp_method = XVerticalCoordinateConstant() + with pytest.raises(ValueError, match="must be a `VerticalCoordinateInterpolator`"): + face_grid.z_interp_method = XLinear() + + +class _EchoInterpolator(ScalarInterpolator): + """Records the grid positions it is evaluated at, and returns 100 * time index + 10 * face index + level index.""" + + def interp(self, particle_positions, grid_positions, field): + self.grid_positions = grid_positions + return 100 * grid_positions["T"]["index"] + 10 * grid_positions["FACE"]["index"] + grid_positions["Z"]["index"] + + +@pytest.mark.parametrize("time_varying", [True, False]) +def test_columns_from_scalar(time_varying): + npart, nlev = 4, 3 + grid = SimpleNamespace(depth=np.zeros((2, nlev, 5))) # only the number of levels of depth is used + fi, face_bcoords = np.array([4, 0, 2, 3]), np.arange(npart * 3).reshape(npart, 3) / 10 + ti, tau = (np.array([0, 1, 1, 0]), np.array([0.1, 0.2, 0.3, 0.4])) if time_varying else (1, 0.0) + grid_positions = {"T": {"index": ti, "bcoord": tau}, "FACE": {"index": fi, "bcoord": face_bcoords}} + echo = _EchoInterpolator() + + columns = UxVerticalCoordinateLinearNode()._columns_from_scalar(echo, grid_positions, grid) + + np.testing.assert_array_equal(columns, 100 * np.reshape(ti, (-1, 1)) + 10 * fi[:, np.newaxis] + np.arange(nlev)) + + # Each level is evaluated exactly on the level, at its particle's face and time barycentric coordinates + recorded = echo.grid_positions + np.testing.assert_array_equal(recorded["Z"]["bcoord"], 0.0) + np.testing.assert_array_equal( + recorded["FACE"]["bcoord"].reshape(npart, nlev, 3), + np.broadcast_to(face_bcoords[:, np.newaxis], (npart, nlev, 3)), + ) + np.testing.assert_array_equal( + recorded["T"]["bcoord"].reshape(npart, nlev), + np.broadcast_to(np.reshape(tau, (-1, 1)), (npart, nlev)), + ) + + +def _time_varying_uxgrid(lateral_dim): + """UxGrid on a small lattice with a time-varying z, increasing along the levels, on the given lateral dimension.""" + uxgrid = sigma_coordinate_lattice_dataset(3, (0.0, 1.0), (0.0, 1.0), 4, bottom_depth=1.0).uxgrid + z = np.broadcast_to(np.arange(4.0)[:, np.newaxis], (2, 4, getattr(uxgrid, lateral_dim))) + return UxGrid(uxgrid, z=ux.UxDataArray(z, dims=("time", "zf", lateral_dim), uxgrid=uxgrid), mesh=FlatMesh()) + + +def test_ux_z_interp_method_defaults_and_validation(): + face_grid, node_grid = _time_varying_uxgrid("n_face"), _time_varying_uxgrid("n_node") + assert isinstance(face_grid.z_interp_method, UxVerticalCoordinateConstantFace) + assert isinstance(node_grid.z_interp_method, UxVerticalCoordinateLinearNode) + + with pytest.raises(ValueError, match="needs z on the mesh faces"): + node_grid.z_interp_method = UxVerticalCoordinateConstantFace() + with pytest.raises(ValueError, match="needs z on the mesh nodes"): + face_grid.z_interp_method = UxVerticalCoordinateLinearNode() + with pytest.raises(ValueError, match="must be a `VerticalCoordinateInterpolator`"): + face_grid.z_interp_method = UxConstantFaceConstantZC() + + z_1d = ux.UxDataArray(np.arange(4.0), dims=("zf",), uxgrid=face_grid.uxgrid) + grid_with_1d_z = UxGrid(face_grid.uxgrid, z=z_1d, mesh=FlatMesh()) + assert grid_with_1d_z.z_interp_method is None + with pytest.raises(ValueError, match="can only be set on a grid with a time-varying"): + grid_with_1d_z.z_interp_method = UxVerticalCoordinateLinearNode() + + with pytest.raises(ValueError, match="A 3D z must have dims"): + _time_varying_uxgrid("n_edge") diff --git a/tests/test_xgrid.py b/tests/test_xgrid.py index 430682314..e83b98dc0 100644 --- a/tests/test_xgrid.py +++ b/tests/test_xgrid.py @@ -8,6 +8,7 @@ from re_assert import Matches from parcels import FieldSet +from parcels._chunk_cached_array import ChunkCachedArray from parcels._core.index_search import ( LEFT_OUT_OF_BOUNDS, RIGHT_OUT_OF_BOUNDS, @@ -20,6 +21,7 @@ XGrid, _transpose_xfield_data_to_tzyx, ) +from parcels._datasets.structured.generated import simple_UV_sigma_dataset from parcels._datasets.structured.generic import X, Y, Z, datasets, datasets_sgrid from parcels._sgrid.accessor import SGridDatasetInconsistency from tests import utils @@ -123,6 +125,29 @@ def test_transpose_xfield_data_to_tzyx(ds): utils.assert_valid_field_data(da_test, grid) +def test_xgrid_time_varying_depth_in_any_dim_order(): + ny, nx = 5, 6 + rng = np.random.default_rng(0) + ds = simple_UV_sigma_dataset( + n_times=3, nz=4, ny=ny, nx=nx, bottom_depth=rng.uniform(10.0, 50.0, (ny, nx)), eta=rng.random((3, ny, nx)) + ) + canonical_depth = ds["depth"] + ds = ds.assign_coords(depth=canonical_depth.transpose("XC", "ZF", "time", "YC")) + + grid = FieldSet.from_sgrid_conventions(ds).U.grid + + assert grid.depth.dims == canonical_depth.dims + np.testing.assert_array_equal(grid.depth.values, canonical_depth.values) + + +def test_xgrid_dask_time_varying_depth_is_chunk_cached(): + ds = simple_UV_sigma_dataset(n_times=3, nz=4, ny=5, nx=6).chunk({"time": 1}) + + grid = FieldSet.from_sgrid_conventions(ds).U.grid + + assert isinstance(grid.depth.variable._data, ChunkCachedArray) + + def test_xgrid_get_axis_dim(fieldset): grid = fieldset.U.grid assert grid.get_axis_dim("Z") == Z - 1