Skip to content

Vertical Coordinate Interpolators - #3037

Merged
wyatt-fluidnumerics merged 37 commits into
mainfrom
vertical-coordinate-interpolators
Nov 18, 2026
Merged

wyatt-fluidnumerics merged 37 commits into
mainfrom
vertical-coordinate-interpolators

Conversation

@wyatt-fluidnumerics

@wyatt-fluidnumerics wyatt-fluidnumerics commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

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.

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

@erikvansebille erikvansebille left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks good! Some comments below

Comment thread src/parcels/_core/particleset.py Resolved
Comment thread src/parcels/_core/uxgrid.py Outdated
Comment on lines +78 to +86
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,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This is true, I had kept it because we currently don't set it to be ChunkCachedArray or WindowedArray explicitly, but we should probably do this in _init_time_varying_z and then remove the warning.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Added in cb13494

Comment thread src/parcels/_core/uxgrid.py Resolved
Comment thread src/parcels/_core/xgrid.py Outdated
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}")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes we can be more explicit. Fixed in 401194b

Comment thread src/parcels/_core/xgrid.py Outdated

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)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I 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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 533f9f6

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in fdde86e

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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

Comment thread src/parcels/_core/xgrid.py Resolved
Comment thread src/parcels/_core/xgrid.py Resolved
Comment thread src/parcels/interpolators/_base.py Outdated
Comment on lines +55 to +56
def __repr__(self):
return f"{self.__class__.__name__}(...)"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

@wyatt-fluidnumerics wyatt-fluidnumerics Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

That makes sense, this way ScalarInterpolator, VectorInterpolator, and VerticalCoordinateInterpolator are also guaranteed to have the same format. Changed in 4b6d64b

@erikvansebille erikvansebille left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Besides the suggestion above on perhaps using a cross x instead of a circle for deleted particles in the final animation of the notebook, I think this PR is good to go!

@wyatt-fluidnumerics

Copy link
Copy Markdown
Contributor Author

Great! I'll wait for CI and then merge!

@wyatt-fluidnumerics
wyatt-fluidnumerics merged commit 6cf8a20 into main Nov 18, 2026
24 checks passed
@wyatt-fluidnumerics
wyatt-fluidnumerics deleted the vertical-coordinate-interpolators branch November 18, 2026 19:13
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Parcels development Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants