Vertical Coordinate Interpolators by wyatt-fluidnumerics · Pull Request #3037 · Parcels-code/Parcels

wyatt-fluidnumerics · 2026-11-04T22:07:48Z

Description

This PR addresses the need for more complex interpolation methods for time varying z dimensions, while maintaining flexibility for users and alignment with the current interpolator API.

The key change is the introduction of a VerticalCoordinateInterpolator abstract class that sits at the same level as the Vector and Scalar interpolator classes. At its core, the VerticalCoordinateInterpolator class enables any existing or user madeScalarInterpolator to be used to interpolate the vertical coordinate. This is done through its base method _columns_from_scalar, which takes in a scalar interpolator and uses it to run a horizontal interpolation on every vertical interface at each particle's horizontal position. These interfaces are then used to reconstruct the vertical columns at each particle position, which can be used for the vertical grid search.

For time varying z coordinate datasets, a vertical coordinate interpolator is set during Fieldset creation, and can be overwritten by the user.

This PR also adjusts all UxInterpolators to perform linear in time interpolation for data that falls between two model snapshots. This is required to avoid large temporal jump discontinuities in time varying vertical grids.

Checklist

Tests added
This PR targets the correct branch (main for normal development, v3-support for v3 support)

AI Disclosure

This PR contains AI-generated content.
- I have tested any AI-generated content in my PR.
- I take responsibility for any AI-generated content in my PR.
- Describe how you used it (e.g., by pasting your prompt): I guided claude opus 5.5 through the implementation. I have thoroughly reviewed all code, and made edits where needed.

…polator

for more information, see https://pre-commit.ci

…owed array

…or UxGrid

for more information, see https://pre-commit.ci

…s-code/Parcels into vertical-coordinate-interpolators

for more information, see https://pre-commit.ci

erikvansebille

Looks good! Some comments below

erikvansebille · 2026-11-05T05:59:52Z

            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


Why was this change necessary? Why did the old code not work? Or was it simply superfluous because a 4-D grid always has a Z dimension?

erikvansebille · 2026-11-05T06:16:41Z

+        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). "
+            f"Assumptions: z has dims {z.dims}, i.e. it is defined at the layer interfaces ('zf') on the mesh "
+            "nodes or faces, and is strictly increasing along 'zf'; each particle's z column is interpolated with "
+            "the grid's `z_interp_method` (by default barycentrically from its face's nodes for node z, or "
+            "constant over its face for face z), and linearly in time between z snapshots.",
+            FieldSetWarning,
+            stacklevel=5,


But I thought this warning may not be necessary anymore because the 4D depth fields can use the ChunkCachedArray or WindowedArray backend?

erikvansebille · 2026-11-05T06:17:59Z

+                f"A 3D z must have dims ('time', 'zf', 'n_node') or ('time', 'zf', 'n_face'), got {z.dims}"
+            )
+
+        if z.dims[-1] == "n_node":


Do we also need to check that the dimension order of z is such that the last is n_node or n_face? Or is that done somewhere else?

erikvansebille · 2026-11-05T06:27:53Z

+            isinstance(value, XVerticalCoordinateConstant)
+            and get_dim_position(self.sgrid_metadata, depth_dims[-1]) != "face"
+        ):
+            raise ValueError(f"XVerticalCoordinateConstant needs depth on the cell centres, got dims {depth_dims}")


Can we be more explicit here what the cell centres are called in this dataset? Would we know that?

erikvansebille · 2026-11-05T06:29:31Z


        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, yi, eta, xi, xsi, ti, tau)


I only realise this now, but would it not make more sense to use the order ti, tau, yi, eta, xi, xsi for the position here - in order to harmonise dimensionality throughout the codebase?

erikvansebille · 2026-11-11T07:33:52Z

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?

erikvansebille · 2026-11-11T07:36:48Z

        self._ds = model_data
        self.mesh = mesh
        self._spatialhash = None
+        self._z_interp_method = None


The _interp_method is set on the Field. Why is the _z_interp_method then set on the grid? Can different Fields on the same grid not have different interpolation methods?

erikvansebille · 2026-11-11T07:37:48Z

        self._ds = model_data
        self.mesh = mesh
        self._spatialhash = None
+        self._z_interp_method = None


Should we now rename interp_method to h_interp_method or something similar to make explicit that these are horizontal interpolation methods? Or should/could that be done in another pR?

erikvansebille · 2026-11-11T07:40:43Z

+    def __repr__(self):
+        return f"{self.__class__.__name__}(...)"


Should we move this interpolators.__repr__ to the repr_utils.py file, so they are all in one place

erikvansebille · 2026-11-11T07:43:37Z

+    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)


Should we use the offsets here? Because some models are indexed by the upper-right corner and others by the lower-left corner. Or is that not relevant here?

wyatt-fluidnumerics added 2 commits November 4, 2026 21:34

initial vertical coordinate interpolator plumbing

75a20b6

implement UxLinearNodeLinearZf and corresponding Vertical coord inter…

4e98ebc

…polator

github-project-automation Bot added this to Parcels development Nov 4, 2026

github-project-automation Bot moved this to Backlog in Parcels development Nov 4, 2026

pre-commit-ci Bot and others added 16 commits November 4, 2026 22:08

[pre-commit.ci] auto fixes from pre-commit.com hooks

adc20eb

for more information, see https://pre-commit.ci

Add xgrid interpolators and testing

b00c9d1

[pre-commit.ci] auto fixes from pre-commit.com hooks

7bebb28

for more information, see https://pre-commit.ci

swap time indexing in uxinterpolators to be more compatable with wind…

a8a5de2

…owed array

make all ux interpolators linear in time

dd5f01d

Move vertical interpolator testing to its own file

c016552

Add default z interpolator and linear in time interpolation testing f…

3cc828e

…or UxGrid

[pre-commit.ci] auto fixes from pre-commit.com hooks

2da08b7

for more information, see https://pre-commit.ci

Remove experimental warning on startup

6f5355e

Merge branch 'vertical-coordinate-interpolators' of github.com:Parcel…

3850d9e

…s-code/Parcels into vertical-coordinate-interpolators

Renamed tutorial and added vertical coord interpolator section

24ecc04

Clear notebook output

012c0fe

minor changes

13aaeb3

add py:obj to tutorial interpolators

87e87c3

Merge branch 'main' into vertical-coordinate-interpolators

71f206a

[pre-commit.ci] auto fixes from pre-commit.com hooks

4a0b6cc

for more information, see https://pre-commit.ci

wyatt-fluidnumerics marked this pull request as ready for review November 10, 2026 20:33

wyatt-fluidnumerics requested review from erikvansebille and fluidnumericsJoe November 10, 2026 20:33

erikvansebille reviewed Nov 11, 2026

View reviewed changes

Navigation Menu

Repository navigation

Vertical Coordinate Interpolators - #3037

Vertical Coordinate Interpolators#3037
wyatt-fluidnumerics wants to merge 18 commits into
mainfrom
vertical-coordinate-interpolators

wyatt-fluidnumerics commented Nov 4, 2026 •

edited

Loading

Uh oh!

erikvansebille left a comment

Uh oh!

erikvansebille Nov 5, 2026

Uh oh!

erikvansebille Nov 5, 2026

Uh oh!

erikvansebille Nov 5, 2026

Uh oh!

erikvansebille Nov 5, 2026

Uh oh!

erikvansebille Nov 5, 2026

Uh oh!

erikvansebille Nov 11, 2026

Uh oh!

erikvansebille Nov 11, 2026

Uh oh!

erikvansebille Nov 11, 2026

Uh oh!

erikvansebille Nov 11, 2026

Uh oh!

erikvansebille Nov 11, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

wyatt-fluidnumerics commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

AI Disclosure

Uh oh!

erikvansebille left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wyatt-fluidnumerics commented Nov 4, 2026 •

edited

Loading