Change UX->Ux interpolators prefix for unstructured grid interpolators

Note also that changes in test assertions were needed for unstructured
grid pset.execute tests that use spherical mesh types. This arises due
to the fact that we now alter the particle locations by removing the
component of the spherical coordinate transformation that is not in the
element plane; this changes the resulting barycentric coordinates and
thus interpolated values for particle advection.

Author: fluidnumericsJoe

docs/user_guide/examples/tutorial_interpolation.ipynb

@@ -258,8 +258,8 @@
    "source": [
     "## Interpolation on unstructured grids\n",
     "Parcels v4 supports the use of general circulation model output that is defined on unstructured grids. We include basic interpolators to help you get started, including\n",
-    "- `UXPiecewiseConstantFace` - this interpolator implements piecewise constant interpolation and is appropriate for data that is registered to the face centers of the unstructured grid\n",
-    "- `UXPiecewiseLinearNode` - this interpolator implements barycentric interpolation and is appropriate for data that is registered to the corner vertices of the unstructured grid faces\n",
+    "- `UxPiecewiseConstantFace` - this interpolator implements piecewise constant interpolation and is appropriate for data that is registered to the face centers of the unstructured grid\n",
+    "- `UxPiecewiseLinearNode` - this interpolator implements barycentric interpolation and is appropriate for data that is registered to the corner vertices of the unstructured grid faces\n",
     "\n",
     "To get started, we use a very simple generated `UxArray.UxDataset` that is included with Parcels."
    ]
@@ -280,7 +280,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, we create the `Field` and `Fieldset` objects that will be used later in advancing particles. When creating a `Field` or `VectorField` object for unstructured grid data, we attach a `parcels.UxGrid` object and attach an `interp_method` to each object. For data that is defined on face centers, we use the `UXPiecewiseConstantFace` interpolator and for data that is defined on the face vertices, we use the `UXPiecewiseLinearNode` interpolator. In this example, we  will look specifically at interpolating a tracer field that is defined by the same underlying analytical function, but is defined on both faces and vertices as separate fields."
+    "Next, we create the `Field` and `Fieldset` objects that will be used later in advancing particles. When creating a `Field` or `VectorField` object for unstructured grid data, we attach a `parcels.UxGrid` object and attach an `interp_method` to each object. For data that is defined on face centers, we use the `UxPiecewiseConstantFace` interpolator and for data that is defined on the face vertices, we use the `UxPiecewiseLinearNode` interpolator. In this example, we  will look specifically at interpolating a tracer field that is defined by the same underlying analytical function, but is defined on both faces and vertices as separate fields."
    ]
   },
   {
@@ -299,13 +299,13 @@
     "    \"T_node\",\n",
     "    ds[\"T_node\"],\n",
     "    grid,\n",
-    "    interp_method=parcels.interpolators.UXPiecewiseLinearNode,\n",
+    "    interp_method=parcels.interpolators.UxPiecewiseLinearNode,\n",
     ")\n",
     "Tface = parcels.Field(\n",
     "    \"T_face\",\n",
     "    ds[\"T_face\"],\n",
     "    grid,\n",
-    "    interp_method=parcels.interpolators.UXPiecewiseConstantFace,\n",
+    "    interp_method=parcels.interpolators.UxPiecewiseConstantFace,\n",
     ")\n",
     "fieldset = parcels.FieldSet([Tnode, Tface])"
    ]
@@ -340,7 +340,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, we can create a `ParticleSet` for each interpolation experiment. In one of the `ParticleSet` objects we use the `SampleTracer_Node` kernel to showcase interpolating with the `UXPiecewiseLinearNode` interpolator for node-registered data. In the other, we use the `SampleTracer_Face` to showcase interpolating with the `UxPiecewiseConstantFace` interpolator for face-registered data."
+    "Now, we can create a `ParticleSet` for each interpolation experiment. In one of the `ParticleSet` objects we use the `SampleTracer_Node` kernel to showcase interpolating with the `UxPiecewiseLinearNode` interpolator for node-registered data. In the other, we use the `SampleTracer_Face` to showcase interpolating with the `UxPiecewiseConstantFace` interpolator for face-registered data."
    ]
   },
   {

docs/user_guide/examples_v3/tutorial_stommel_uxarray.ipynb

@@ -112,7 +112,7 @@
     "\n",
     "In Parcels, grid searching is conducted with respect to the faces. In other words, when a grid index `ei` is provided to an interpolation method, this refers the face index `fi` at vertical layer `zi` (when unraveled). Within the interpolation method, the `field.grid.uxgrid.face_node_connectivity` attribute can be used to obtain the node indices that surround the face. Using these connectivity tables is necessary for properly indexing node registered data.\n",
     "\n",
-    "For the example Stommel gyre dataset in this tutorial, the `u` and `v` velocity components are face registered (similar to FESOM). Parcels includes a nearest neighbor interpolator for face registered unstructured grid data through `Parcels.application_kernels.interpolation.UXPiecewiseConstantFace`. Below, we create the `Field`s `U` and `V` and associate them with the `UxGrid` we created previously and this interpolation method."
+    "For the example Stommel gyre dataset in this tutorial, the `u` and `v` velocity components are face registered (similar to FESOM). Parcels includes a nearest neighbor interpolator for face registered unstructured grid data through `Parcels.application_kernels.interpolation.UxPiecewiseConstantFace`. Below, we create the `Field`s `U` and `V` and associate them with the `UxGrid` we created previously and this interpolation method."
    ]
   },
   {
@@ -121,26 +121,26 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from parcels.application_kernels.interpolation import UXPiecewiseConstantFace\n",
+    "from parcels.application_kernels.interpolation import UxPiecewiseConstantFace\n",
     "from parcels.field import Field\n",
     "\n",
     "U = Field(\n",
     "    name=\"U\",\n",
     "    data=ds.U,\n",
     "    grid=grid,\n",
-    "    interp_method=UXPiecewiseConstantFace,\n",
+    "    interp_method=UxPiecewiseConstantFace,\n",
     ")\n",
     "V = Field(\n",
     "    name=\"V\",\n",
     "    data=ds.V,\n",
     "    grid=grid,\n",
-    "    interp_method=UXPiecewiseConstantFace,\n",
+    "    interp_method=UxPiecewiseConstantFace,\n",
     ")\n",
     "P = Field(\n",
     "    name=\"P\",\n",
     "    data=ds.p,\n",
     "    grid=grid,\n",
-    "    interp_method=UXPiecewiseConstantFace,\n",
+    "    interp_method=UxPiecewiseConstantFace,\n",
     ")"
    ]
   },

src/parcels/_core/fieldset.py

@@ -18,7 +18,7 @@
 from parcels._core.xgrid import _DEFAULT_XGCM_KWARGS, XGrid
 from parcels._logger import logger
 from parcels._typing import Mesh
-from parcels.interpolators import UXPiecewiseConstantFace, UXPiecewiseLinearNode, XConstantField, XLinear
+from parcels.interpolators import UxPiecewiseConstantFace, UxPiecewiseLinearNode, XConstantField, XLinear
 
 if TYPE_CHECKING:
     from parcels._core.basegrid import BaseGrid
@@ -459,9 +459,9 @@ def _select_uxinterpolator(da: ux.UxDataArray):
     """Selects the appropriate uxarray interpolator for a given uxarray UxDataArray"""
     supported_uxinterp_mapping = {
         # (nz1,n_face): face-center laterally, layer centers vertically — piecewise constant
-        "nz1,n_face": UXPiecewiseConstantFace,
+        "nz1,n_face": UxPiecewiseConstantFace,
         # (nz,n_node): node/corner laterally, layer interfaces vertically — barycentric lateral & linear vertical
-        "nz,n_node": UXPiecewiseLinearNode,
+        "nz,n_node": UxPiecewiseLinearNode,
     }
     # Extract only spatial dimensions, neglecting time
     da_spatial_dims = tuple(d for d in da.dims if d not in ("time",))

src/parcels/interpolators.py

@@ -18,8 +18,8 @@
 __all__ = [
     "CGrid_Tracer",
     "CGrid_Velocity",
-    "UXPiecewiseConstantFace",
-    "UXPiecewiseLinearNode",
+    "UxPiecewiseConstantFace",
+    "UxPiecewiseLinearNode",
     "XConstantField",
     "XFreeslip",
     "XLinear",
@@ -641,7 +641,7 @@ def XLinearInvdistLandTracer(
     return values.compute() if is_dask_collection(values) else values
 
 
-def UXPiecewiseConstantFace(
+def UxPiecewiseConstantFace(
     particle_positions: dict[str, float | np.ndarray],
     grid_positions: dict[_UXGRID_AXES, dict[str, int | float | np.ndarray]],
     field: Field,
@@ -656,7 +656,7 @@ def UXPiecewiseConstantFace(
     ]
 
 
-def UXPiecewiseLinearNode(
+def UxPiecewiseLinearNode(
     particle_positions: dict[str, float | np.ndarray],
     grid_positions: dict[_UXGRID_AXES, dict[str, int | float | np.ndarray]],
     field: Field,

tests/test_field.py

@@ -9,7 +9,7 @@
 from parcels._datasets.structured.generic import T as T_structured
 from parcels._datasets.structured.generic import datasets as datasets_structured
 from parcels._datasets.unstructured.generic import datasets as datasets_unstructured
-from parcels.interpolators import UXPiecewiseConstantFace, UXPiecewiseLinearNode, XLinear
+from parcels.interpolators import UxPiecewiseConstantFace, UxPiecewiseLinearNode, XLinear
 
 
 def test_field_init_param_types():
@@ -197,7 +197,7 @@ def test_field_unstructured_z_linear():
 
     grid = UxGrid(ds.uxgrid, z=ds.coords["nz"], mesh="flat")
     # Note that the vertical coordinate is required to be the position of the layer interfaces ("nz"), not the mid-layers ("nz1")
-    P = Field(name="p", data=ds.p, grid=grid, interp_method=UXPiecewiseConstantFace)
+    P = Field(name="p", data=ds.p, grid=grid, interp_method=UxPiecewiseConstantFace)
 
     # Test above first cell center - for piecewise constant, should return the depth of the first cell center
     assert np.isclose(
@@ -215,7 +215,7 @@ def test_field_unstructured_z_linear():
         944.44445801,
     )
 
-    W = Field(name="W", data=ds.W, grid=grid, interp_method=UXPiecewiseLinearNode)
+    W = Field(name="W", data=ds.W, grid=grid, interp_method=UxPiecewiseLinearNode)
     assert np.isclose(
         W.eval(time=ds.time[0].values, z=[10.0], y=[30.0], x=[30.0], applyConversion=False),
         10.0,
@@ -235,7 +235,7 @@ def test_field_constant_in_time():
     ds = datasets_unstructured["stommel_gyre_delaunay"]
     grid = UxGrid(ds.uxgrid, z=ds.coords["nz"], mesh="flat")
     # Note that the vertical coordinate is required to be the position of the layer interfaces ("nz"), not the mid-layers ("nz1")
-    P = Field(name="p", data=ds.p, grid=grid, interp_method=UXPiecewiseConstantFace)
+    P = Field(name="p", data=ds.p, grid=grid, interp_method=UxPiecewiseConstantFace)
 
     # Assert that the field can be evaluated at any time, and returns the same value
     time = np.datetime64("2000-01-01T00:00:00")

tests/test_particleset_execute.py

@@ -22,7 +22,7 @@
 from parcels._datasets.structured.generated import simple_UV_dataset
 from parcels._datasets.structured.generic import datasets as datasets_structured
 from parcels._datasets.unstructured.generic import datasets as datasets_unstructured
-from parcels.interpolators import UXPiecewiseConstantFace, UXPiecewiseLinearNode, XLinear
+from parcels.interpolators import UxPiecewiseConstantFace, UxPiecewiseLinearNode, XLinear
 from parcels.kernels import AdvectionEE, AdvectionRK2, AdvectionRK4, AdvectionRK4_3D, AdvectionRK45
 from tests.common_kernels import DoNothing
 
@@ -502,19 +502,19 @@ def test_uxstommelgyre_pset_execute():
         name="U",
         data=ds.U,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     V = Field(
         name="V",
         data=ds.V,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     P = Field(
         name="P",
         data=ds.p,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     UV = VectorField(name="UV", U=U, V=V)
     fieldset = FieldSet([UV, UV.U, UV.V, P])
@@ -531,8 +531,8 @@ def test_uxstommelgyre_pset_execute():
         runtime=np.timedelta64(10, "m"),
         dt=np.timedelta64(60, "s"),
     )
-    np.testing.assert_allclose(pset[0].lon, 30.001259, atol=1e-3)
-    np.testing.assert_allclose(pset[0].lat, 4.9962664, atol=1e-3)
+    np.testing.assert_allclose(pset[0].lon, 29.997387, atol=1e-3)
+    np.testing.assert_allclose(pset[0].lat, 4.998546, atol=1e-3)
 
 
 def test_uxstommelgyre_multiparticle_pset_execute():
@@ -542,25 +542,25 @@ def test_uxstommelgyre_multiparticle_pset_execute():
         name="U",
         data=ds.U,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     V = Field(
         name="V",
         data=ds.V,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     W = Field(
         name="W",
         data=ds.W,
         grid=grid,
-        interp_method=UXPiecewiseLinearNode,
+        interp_method=UxPiecewiseLinearNode,
     )
     P = Field(
         name="P",
         data=ds.p,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     UVW = VectorField(name="UVW", U=U, V=V, W=W)
     fieldset = FieldSet([UVW, UVW.U, UVW.V, UVW.W, P])
@@ -587,19 +587,19 @@ def test_uxstommelgyre_pset_execute_output():
         name="U",
         data=ds.U,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     V = Field(
         name="V",
         data=ds.V,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     P = Field(
         name="P",
         data=ds.p,
         grid=grid,
-        interp_method=UXPiecewiseConstantFace,
+        interp_method=UxPiecewiseConstantFace,
     )
     UV = VectorField(name="UV", U=U, V=V)
     fieldset = FieldSet([UV, UV.U, UV.V, P])

tests/test_uxarray_fieldset.py

@@ -13,8 +13,8 @@
 )
 from parcels._datasets.unstructured.generic import datasets as datasets_unstructured
 from parcels.interpolators import (
-    UXPiecewiseConstantFace,
-    UXPiecewiseLinearNode,
+    UxPiecewiseConstantFace,
+    UxPiecewiseLinearNode,
 )
 
 
@@ -39,13 +39,13 @@ def uv_fesom_channel(ds_fesom_channel) -> VectorField:
             name="U",
             data=ds_fesom_channel.U,
             grid=UxGrid(ds_fesom_channel.uxgrid, z=ds_fesom_channel.coords["nz"], mesh="flat"),
-            interp_method=UXPiecewiseConstantFace,
+            interp_method=UxPiecewiseConstantFace,
         ),
         V=Field(
             name="V",
             data=ds_fesom_channel.V,
             grid=UxGrid(ds_fesom_channel.uxgrid, z=ds_fesom_channel.coords["nz"], mesh="flat"),
-            interp_method=UXPiecewiseConstantFace,
+            interp_method=UxPiecewiseConstantFace,
         ),
     )
     return UV
@@ -59,19 +59,19 @@ def uvw_fesom_channel(ds_fesom_channel) -> VectorField:
             name="U",
             data=ds_fesom_channel.U,
             grid=UxGrid(ds_fesom_channel.uxgrid, z=ds_fesom_channel.coords["nz"], mesh="flat"),
-            interp_method=UXPiecewiseConstantFace,
+            interp_method=UxPiecewiseConstantFace,
         ),
         V=Field(
             name="V",
             data=ds_fesom_channel.V,
             grid=UxGrid(ds_fesom_channel.uxgrid, z=ds_fesom_channel.coords["nz"], mesh="flat"),
-            interp_method=UXPiecewiseConstantFace,
+            interp_method=UxPiecewiseConstantFace,
         ),
         W=Field(
             name="W",
             data=ds_fesom_channel.W,
             grid=UxGrid(ds_fesom_channel.uxgrid, z=ds_fesom_channel.coords["nz"], mesh="flat"),
-            interp_method=UXPiecewiseLinearNode,
+            interp_method=UxPiecewiseLinearNode,
         ),
     )
     return UVW
@@ -101,8 +101,8 @@ def test_set_interp_methods(ds_fesom_channel, uv_fesom_channel):
     assert (fieldset.V.data == ds_fesom_channel.V).all()
 
     # Set the interpolation method for each field
-    fieldset.U.interp_method = UXPiecewiseConstantFace
-    fieldset.V.interp_method = UXPiecewiseConstantFace
+    fieldset.U.interp_method = UxPiecewiseConstantFace
+    fieldset.V.interp_method = UxPiecewiseConstantFace
 
 
 def test_fesom2_square_delaunay_uniform_z_coordinate_eval():
@@ -115,17 +115,37 @@ def test_fesom2_square_delaunay_uniform_z_coordinate_eval():
     grid = UxGrid(ds.uxgrid, z=ds.coords["nz"], mesh="flat")
     UVW = VectorField(
         name="UVW",
-        U=Field(name="U", data=ds.U, grid=grid, interp_method=UXPiecewiseConstantFace),
-        V=Field(name="V", data=ds.V, grid=grid, interp_method=UXPiecewiseConstantFace),
-        W=Field(name="W", data=ds.W, grid=grid, interp_method=UXPiecewiseLinearNode),
+        U=Field(name="U", data=ds.U, grid=grid, interp_method=UxPiecewiseConstantFace),
+        V=Field(name="V", data=ds.V, grid=grid, interp_method=UxPiecewiseConstantFace),
+        W=Field(name="W", data=ds.W, grid=grid, interp_method=UxPiecewiseLinearNode),
     )
-    P = Field(name="p", data=ds.p, grid=grid, interp_method=UXPiecewiseLinearNode)
+    P = Field(name="p", data=ds.p, grid=grid, interp_method=UxPiecewiseLinearNode)
     fieldset = FieldSet([UVW, P, UVW.U, UVW.V, UVW.W])
 
-    assert fieldset.U.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False) == 1.0
-    assert fieldset.V.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False) == 1.0
-    assert fieldset.W.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False) == 0.0
-    assert fieldset.p.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False) == 1.0
+    assert np.isclose(
+        fieldset.U.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False),
+        1.0,
+        rtol=1e-3,
+        atol=1e-6,
+    )
+    assert np.isclose(
+        fieldset.V.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False),
+        1.0,
+        rtol=1e-3,
+        atol=1e-6,
+    )
+    assert np.isclose(
+        fieldset.W.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False),
+        0.0,
+        rtol=1e-3,
+        atol=1e-6,
+    )
+    assert np.isclose(
+        fieldset.p.eval(time=ds.time[0].values, z=[1.0], y=[30.0], x=[30.0], applyConversion=False),
+        1.0,
+        rtol=1e-3,
+        atol=1e-6,
+    )
 
 
 def test_fesom2_square_delaunay_antimeridian_eval():
@@ -139,7 +159,7 @@ def test_fesom2_square_delaunay_antimeridian_eval():
         name="p",
         data=ds.p,
         grid=UxGrid(ds.uxgrid, z=ds.coords["nz"], mesh="spherical"),
-        interp_method=UXPiecewiseLinearNode,
+        interp_method=UxPiecewiseLinearNode,
     )
     fieldset = FieldSet([P])