Feature/from icon #2454

fluidnumerics-joe · 2026-01-07T22:53:13Z

This PR adds FieldSet.from_icon to support easy loading of data from the ICON model. Resolves #2425
In the process of adding this support, the following additional changes were made

Unstructured grid Interpolation scheme naming convention has been updated to follow Ux<lateral type><face|node|edge><vertical type><ZF | ZC> where <lateral type> is the type of interpolation applied in the lateral directions (e.g. "Constant" or "Linear") and <vertical type> is the type of interpolation applied in the vertical direction . The choice of face, node, or edge indicates where data is registered laterally and the choice of ZF or ZC indicates where data is registered vertically.
Additional default interpolation schemes were added to support the data placement in the sample provided by a Parcels community member mentioned in Add support for ICON model output #2425
Add correctness tests for additional interpolation kernels. This will be accomplished using constant, bilinear, and trilinear functions to prove exactness of the provided interpolation methods (no convergence testing will be conducted in this PR).
Changed the 2d triangle area to a signed area to prevent false positives that were found in new tests with generic icon data
Changed unstructured generic data types to fp64 to reduce floating point errors in barycentric interpolation for assessing exactness of interpolation schemes
Updated relevant notebooks with information on new interpolation methods.

`zc` refers to the vertical center and `zf` refers to the vertical interface I've also relaxed the requirement that the Conventions attribute be defined; having this convention defined in the uxdataarray doesn't imply compliance with a given convention..

New interpolator naming convention for unstructured grids will follow Ux<lateral type><face|node|edge><vertical type><ZF | ZC> where lateral type is the type of interpolation applied in the lateral directions (e.g. "Constant" or "Linear") and vertical type is the type of interpolation applied in the vertical direction . The choice of face, node, or edge indicates where data is registered laterally and the choice of ZF or ZC indicates where data is registered vertically.

Still sorting out an issue with the linear node constant z interpolator

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

Also adjusted the test function for barycentric interpolation to an affine function of lat and lon (f=a*lon + b*lat); Affine functions are exact for barycentric interpolation while product (f=a*lon*lat) are not exact since the second derivative (the leading truncation error) is non-zero.

Signed areas in 2-D help ensure that we don't have false positives. Since uxarray ensures consistent winding direction among elements, this is a safe change to make that also helps prevent edge cases of finding points in a cell that are not actually in the cell.

…nto feature/from_icon

…utorial

…efinitions of other included interpolators

…nto feature/from_icon

I suspect a library under the hood (a uxarray dependency) changed causing a change in the output of the delaunay triangulation. Note that delaunay triangulations are not unique (there is more than one possible triangulation possible).

erikvansebille

Very nice PR; looks great! A few small comments/suggestions below

erikvansebille · 2026-01-09T07:09:47Z

src/parcels/_core/fieldset.py


-    def from_fesom2(ds: ux.UxDataset):
-        """Create a FieldSet from a FESOM2 uxarray.UxDataset.
+    def from_uxdataset(ds: ux.UxDataset, mesh: str = "spherical"):


Should we call this from_ux_conventions(), to stay aligned with the from_sgrid_conventions() for Xgrid?

I'll leave that up to you and @VeckoTheGecko what you want to call this.

When writing this, I chose this name because a UxDataset object is used to create the fieldset. Aside from vertical grid variable names (which are not part of UGrid convention), a UxDataset implicitly abides by the UGrid conventions.

erikvansebille · 2026-01-09T07:10:38Z

src/parcels/_core/fieldset.py


        return FieldSet(list(fields.values()))

+    def from_fesom2(ds: ux.UxDataset, mesh: str = "spherical"):


Fine for now, but this code could;d later be moved to the convert class, when @VeckoTheGecko is done with his PR?

Yes, agreed

erikvansebille · 2026-01-09T07:11:14Z

src/parcels/_core/fieldset.py

+
+        return FieldSet.from_uxdataset(ds, mesh=mesh)
+
+    def from_icon(ds: ux.UxDataset, mesh: str = "spherical"):


This could also go to the convert class?

Agreed. I think a follow up PR here would be useful. I'm going to look at metadata, per @VeckoTheGecko 's suggestion. I have thoughts on this after reading through the UGrid conventions, but I'll save that for another issue

erikvansebille · 2026-01-09T07:16:06Z

src/parcels/_core/fieldset.py

+    logger.warning(
+        f"Interpolator not found for UxDataArray {da.name} with spatial dimensions {da_spatial_dims}. Setting default interpolator to ZeroInterpolator"
+    )


I don't think I like this choice of ZeroInterpolator as default. If users don't pay attention to this warning, they will end up with zeros for all the fields, which will surprise them a lot

What about simply raising an error when we can't select an Interpolator? With some suggestions how users could fix it?

I thought about this too.

There's another set of possible field placements that we don't currently have default interpolators for. If folks are using ICON on native locations the lateral velocity field components would be on edge centers (and would be oriented across edge normals).

I would want to allow folks who want to start there to be able to use the from_icon method and not error out. Perhaps they're looking to provide their own interpolator.

If users don't pay attention to warnings, then I suppose it's part of the learning process?

OK, fair enough that a warning is apt. But would the original return None then not be a better solution, since that will at least break any pset.execute()? Or does returning None here already throw errors in the fieldset creation?

src/parcels/_datasets/unstructured/generic.py

erikvansebille · 2026-01-09T07:19:49Z

src/parcels/interpolators.py



-def UxPiecewiseConstantFace(
+def UxConstantFaceConstantZC(


Maybe not in this PR< but should we soon(ish) start to separate all the interpolators into multiple files? (under a directory interpolators/)

Because this file will become very large...

I think so.

erikvansebille · 2026-01-09T07:21:11Z

src/parcels/interpolators.py

-    "UxPiecewiseConstantFace",
-    "UxPiecewiseLinearNode",
+    "UxConstantFaceConstantZC",
+    "UxLinearNodeLinearZF",


Also include the two others? SO that you have all four Ux* interpolators here?

erikvansebille · 2026-01-09T07:22:29Z

tests/test_field.py

+    ds = ds.rename(
+        {
+            "nz": "zf",  # Vertical Interface
+            "nz1": "zc",  # Vertical Center
+        }
+    ).set_index(zf="zf", zc="zc")


Can't this be done in the datasets_unstructured["fesom2_square_delaunay_uniform_z_coordinate"] itself? is there a reason to change these dimensions here in the test?

The point is to mimic what it would look like coming from fesom2 in the generic dataset

Alternatively, I could have one of the generic datasets come in with the expected vertical grid names, and have separate equivalents for FESOM2 and ICON. In the test_field.py tests, we could just use the generic dataset that uses the expected vertical coordinate names

This would then not use any of the fesom or icon data in test_field.. the model specific generics would then be tested in the relevant field set and particleset tests we have

erikvansebille · 2026-01-09T07:22:41Z

tests/test_field.py

+    ds = datasets_unstructured["stommel_gyre_delaunay"].copy(deep=True)
+    ds = ds.rename(
+        {
+            "nz": "zf",  # Vertical Interface
+            "nz1": "zc",  # Vertical Center
+        }
+    ).set_index(zf="zf", zc="zc")
+    grid = UxGrid(ds.uxgrid, z=ds.coords["zf"], mesh="flat")


Same as comment above

Same response as above

fluidnumerics-joe added 6 commits January 6, 2026 12:30

Change nz,nz1 -> zf, zc

b35fcbe

Fix broken tests and dim/coord renaming and indexing

6b03fc0

Add test for icon data and default to zeroInterpolator when not found

1daca5e

Add interpolators to complete the [face,node]x[zc,zf] placements

97d95a5

github-project-automation bot added this to Parcels development Jan 7, 2026

github-project-automation bot moved this to Backlog in Parcels development Jan 7, 2026

fluidnumerics-joe and others added 11 commits January 8, 2026 14:33

Add exactness tests

ae64500

Still sorting out an issue with the linear node constant z interpolator

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

f0d3f51

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

Merge branch 'feature/from_icon' of github.com:OceanParcels/Parcels i…

62df2d4

…nto feature/from_icon

Fix abandoned merge block

4a2f048

Fix vertical coordinate name to match new convention in nestedgrids t…

914f54b

…utorial

Update tutorials to use new vertical grid naming convention and add d…

7c33272

…efinitions of other included interpolators

Assign appropriate interpolator to p field

cab7b61

Merge branch 'feature/from_icon' of github.com:OceanParcels/Parcels i…

717eabd

…nto feature/from_icon

Change number of faces in check

8254c0c

I suspect a library under the hood (a uxarray dependency) changed causing a change in the output of the delaunay triangulation. Note that delaunay triangulations are not unique (there is more than one possible triangulation possible).

fluidnumerics-joe changed the title ~~[DRAFT] Feature/from icon~~ Feature/from icon Jan 9, 2026

fluidnumerics-joe marked this pull request as ready for review January 9, 2026 00:49

fluidnumerics-joe requested review from VeckoTheGecko and erikvansebille January 9, 2026 00:49

erikvansebille reviewed Jan 9, 2026

View reviewed changes


		return FieldSet(list(fields.values()))

		def from_fesom2(ds: ux.UxDataset, mesh: str = "spherical"):


		return FieldSet.from_uxdataset(ds, mesh=mesh)

		def from_icon(ds: ux.UxDataset, mesh: str = "spherical"):

Feature/from icon #2454

Are you sure you want to change the base?

Feature/from icon #2454

Uh oh!

Conversation

fluidnumerics-joe commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

fluidnumerics-joe Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fluidnumerics-joe commented Jan 7, 2026 •

edited

Loading

fluidnumerics-joe Jan 9, 2026 •

edited

Loading