Merge branch 'v4-dev' into reprs_for_v4

Author: erikvansebille

docs/user_guide/examples/tutorial_diffusion.ipynb

@@ -192,7 +192,7 @@
    "source": [
     "from parcels._datasets.structured.generated import simple_UV_dataset\n",
     "\n",
-    "ds = simple_UV_dataset(dims=(1, 1, Ny, 1), mesh=\"flat\").isel(time=0, depth=0)\n",
+    "ds = simple_UV_dataset(dims=(1, 1, Ny, 1), mesh=\"flat\")\n",
     "ds[\"lat\"][:] = np.linspace(-0.01, 1.01, Ny)\n",
     "ds[\"lon\"][:] = np.ones(len(ds.XG))\n",
     "ds[\"Kh_meridional\"] = ([\"YG\", \"XG\"], Kh_meridional[:, None])\n",
@@ -205,20 +205,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "grid = parcels.XGrid.from_dataset(ds, mesh=\"flat\")\n",
-    "U = parcels.Field(\"U\", ds[\"U\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "V = parcels.Field(\"V\", ds[\"V\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "UV = parcels.VectorField(\"UV\", U, V)\n",
-    "\n",
-    "Kh_meridional_field = parcels.Field(\n",
-    "    \"Kh_meridional\",\n",
-    "    ds[\"Kh_meridional\"],\n",
-    "    grid,\n",
-    "    interp_method=parcels.interpolators.XLinear,\n",
-    ")\n",
-    "fieldset = parcels.FieldSet([U, V, UV, Kh_meridional_field])\n",
+    "fieldset = parcels.FieldSet.from_sgrid_conventions(ds, mesh=\"flat\")\n",
     "fieldset.add_constant_field(\"Kh_zonal\", 1, mesh=\"flat\")\n",
-    "\n",
     "fieldset.add_constant(\"dres\", 0.00005)"
    ]
   },

docs/user_guide/examples/tutorial_interpolation.ipynb

@@ -46,20 +46,20 @@
    "source": [
     "from parcels._datasets.structured.generated import simple_UV_dataset\n",
     "\n",
-    "ds = simple_UV_dataset(dims=(1, 1, 5, 4), mesh=\"flat\").isel(time=0, depth=0)\n",
+    "ds = simple_UV_dataset(dims=(1, 1, 5, 4), mesh=\"flat\")\n",
     "ds[\"lat\"][:] = np.linspace(0.0, 1.0, len(ds.YG))\n",
     "ds[\"lon\"][:] = np.linspace(0.0, 1.0, len(ds.XG))\n",
     "dx, dy = 1.0 / len(ds.XG), 1.0 / len(ds.YG)\n",
     "ds[\"P\"] = ds[\"U\"] + np.random.rand(5, 4) + 0.1\n",
-    "ds[\"P\"][1, 1] = 0\n",
+    "ds[\"P\"][:, :, 1, 1] = 0\n",
     "ds"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "From this dataset we create a {py:obj}`parcels.FieldSet`. Parcels requires an interpolation method to be set for each {py:obj}`parcels.Field`, which we will later adapt to see the effects of the different interpolators. A common interpolator for fields on structured grids is (tri)linear, implemented in {py:obj}`parcels.interpolators.XLinear`."
+    "From this dataset we create a {py:obj}`parcels.FieldSet` using the {py:meth}`parcels.FieldSet.from_sgrid_conventions` constructor, which automatically sets up the grid and fields according to Parcels' s-grid conventions."
    ]
   },
   {
@@ -68,12 +68,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "grid = parcels.XGrid.from_dataset(ds, mesh=\"flat\")\n",
-    "U = parcels.Field(\"U\", ds[\"U\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "V = parcels.Field(\"V\", ds[\"V\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "UV = parcels.VectorField(\"UV\", U, V)\n",
-    "P = parcels.Field(\"P\", ds[\"P\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "fieldset = parcels.FieldSet([U, V, UV, P])"
+    "fieldset = parcels.FieldSet.from_sgrid_conventions(ds, mesh=\"flat\")"
    ]
   },
   {

docs/user_guide/examples/tutorial_nemo_curvilinear.ipynb

@@ -152,7 +152,7 @@
    "outputs": [],
    "source": [
     "u, v = fieldset.UV.eval(\n",
-    "    np.array([0]), np.array([0]), np.array([20]), np.array([50]), applyConversion=False\n",
+    "    np.array([0]), np.array([0]), np.array([20]), np.array([50]), apply_conversion=False\n",
     ")  # do not convert m/s to deg/s\n",
     "print(f\"(u, v) = ({u[0]:.3f}, {v[0]:.3f})\")\n",
     "assert np.isclose(u, 1.0, atol=1e-3)"
@@ -298,7 +298,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "test-notebooks",
+   "display_name": "default",
    "language": "python",
    "name": "python3"
   },
@@ -312,7 +312,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

docs/user_guide/examples/tutorial_nestedgrids.ipynb

@@ -440,12 +440,7 @@
    "source": [
     "fields = [GridID]\n",
     "for i, ds in enumerate(ds_in):\n",
-    "    # TODO : use FieldSet.from_sgrid_convetion here once #2437 is merged\n",
-    "    grid = parcels.XGrid.from_dataset(ds, mesh=\"spherical\")\n",
-    "    U = parcels.Field(\"U\", ds[\"U\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "    V = parcels.Field(\"V\", ds[\"V\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "    UV = parcels.VectorField(\"UV\", U, V)\n",
-    "    fset = parcels.FieldSet([U, V, UV])\n",
+    "    fset = parcels.FieldSet.from_sgrid_conventions(ds, mesh=\"spherical\")\n",
     "\n",
     "    for fld in fset.fields.values():\n",
     "        fld.name = f\"{fld.name}{i}\"\n",
@@ -469,32 +464,19 @@
    "outputs": [],
    "source": [
     "def AdvectEE_NestedGrids(particles, fieldset):\n",
-    "    particles.gridID = fieldset.GridID[particles]\n",
-    "\n",
-    "    # TODO because of KernelParticle bug (GH #2143), we need to copy lon/lat/time to local variables\n",
-    "    time = particles.time\n",
-    "    z = particles.z\n",
-    "    lat = particles.lat\n",
-    "    lon = particles.lon\n",
     "    u = np.zeros_like(particles.lon)\n",
     "    v = np.zeros_like(particles.lat)\n",
     "\n",
+    "    particles.gridID = fieldset.GridID[particles]\n",
     "    unique_ids = np.unique(particles.gridID)\n",
     "    for gid in unique_ids:\n",
     "        mask = particles.gridID == gid\n",
     "        UVField = getattr(fieldset, f\"UV{gid}\")\n",
-    "        (u[mask], v[mask]) = UVField[time[mask], z[mask], lat[mask], lon[mask]]\n",
+    "        (u[mask], v[mask]) = UVField[particles[mask]]\n",
     "\n",
     "    particles.dlon += u * particles.dt\n",
     "    particles.dlat += v * particles.dt\n",
     "\n",
-    "    # TODO particle states have to be updated manually because UVField is not called with `particles` argument (becaise of GH #2143)\n",
-    "    particles.state = np.where(\n",
-    "        np.isnan(u) | np.isnan(v),\n",
-    "        parcels.StatusCode.ErrorInterpolation,\n",
-    "        particles.state,\n",
-    "    )\n",
-    "\n",
     "\n",
     "lat = np.linspace(-17, 35, 10)\n",
     "lon = np.full(len(lat), -5)\n",

docs/user_guide/examples/tutorial_statuscodes.md

@@ -63,19 +63,14 @@ Let's add the `KeepInOcean` Kernel to an particle simulation where particles mov
 import numpy as np
 from parcels._datasets.structured.generated import simple_UV_dataset
 
-ds = simple_UV_dataset(dims=(1, 2, 5, 4), mesh="flat").isel(time=0)
+ds = simple_UV_dataset(dims=(1, 2, 5, 4), mesh="flat")
 
 dx, dy = 1.0 / len(ds.XG), 1.0 / len(ds.YG)
 
 # Add W velocity that pushes through surface
 ds["W"] = ds["U"] - 0.1 # 0.1 m/s towards the surface
 
-grid = parcels.XGrid.from_dataset(ds, mesh="flat")
-U = parcels.Field("U", ds["U"], grid, interp_method=parcels.interpolators.XLinear)
-V = parcels.Field("V", ds["V"], grid, interp_method=parcels.interpolators.XLinear)
-W = parcels.Field("W", ds["W"], grid, interp_method=parcels.interpolators.XLinear)
-UVW = parcels.VectorField("UVW", U, V, W)
-fieldset = parcels.FieldSet([U, V, W, UVW])
+fieldset = parcels.FieldSet.from_sgrid_conventions(ds, mesh="flat")
 ```
 
 If we advect particles with the `AdvectionRK2_3D` kernel, Parcels will raise a `FieldOutOfBoundSurfaceError`:

docs/user_guide/examples/tutorial_unitconverters.ipynb

@@ -49,7 +49,7 @@
     "\n",
     "nlat = 10\n",
     "nlon = 18\n",
-    "ds = simple_UV_dataset(dims=(1, 1, nlat, nlon), mesh=\"spherical\").isel(time=0, depth=0)\n",
+    "ds = simple_UV_dataset(dims=(1, 1, nlat, nlon), mesh=\"spherical\")\n",
     "ds[\"temperature\"] = ds[\"U\"] + 20  # add temperature field of 20 deg\n",
     "ds[\"U\"].data[:] = 1.0  # set U to 1 m/s\n",
     "ds[\"V\"].data[:] = 1.0  # set V to 1 m/s\n",
@@ -61,7 +61,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To create a `parcels.FieldSet` object, we define the `parcels.Field`s and the structured grid (`parcels.XGrid`) the fields are defined on. We add the argument `mesh='spherical'` to the `parcels.XGrid` to signal that all longitudes and latitudes are in degrees.\n",
+    "To create a `parcels.FieldSet` object, we use the `parcels.FieldSet.from_sgrid_conventions` constructor. We add the argument `mesh='spherical'` to signal that all longitudes and latitudes are in degrees.\n",
     "\n",
     "```{note}\n",
     "When using a `FieldSet` method for a specific dataset, such as `from_copernicusmarine()`, the grid information is known and parsed by Parcels, so we do not have to add the `mesh` argument.\n",
@@ -76,14 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "grid = parcels.XGrid.from_dataset(ds, mesh=\"spherical\")\n",
-    "U = parcels.Field(\"U\", ds[\"U\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "V = parcels.Field(\"V\", ds[\"V\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "UV = parcels.VectorField(\"UV\", U, V)\n",
-    "temperature = parcels.Field(\n",
-    "    \"temperature\", ds[\"temperature\"], grid, interp_method=parcels.interpolators.XLinear\n",
-    ")\n",
-    "fieldset = parcels.FieldSet([U, V, UV, temperature])\n",
+    "fieldset = parcels.FieldSet.from_sgrid_conventions(ds, mesh=\"spherical\")\n",
     "\n",
     "plt.pcolormesh(\n",
     "    fieldset.U.grid.lon,\n",
@@ -166,7 +159,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note that you can also interpolate the Field without a unit conversion, by using the `eval()` method and setting `applyConversion=False`, as below\n"
+    "Note that you can also interpolate the Field without a unit conversion, by using the `eval()` method and setting `apply_conversion=False`, as below\n"
    ]
   },
   {
@@ -181,7 +174,7 @@
     "        z,\n",
     "        lat,\n",
     "        lon,\n",
-    "        applyConversion=False,\n",
+    "        apply_conversion=False,\n",
     "    )\n",
     ")"
    ]
@@ -199,7 +192,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If longitudes and latitudes are given in meters, rather than degrees, simply add `mesh='flat'` when creating the XGrid object.\n"
+    "If longitudes and latitudes are given in meters, rather than degrees, simply add `mesh='flat'` when creating the `FieldSet` object.\n"
    ]
   },
   {
@@ -208,21 +201,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ds_flat = simple_UV_dataset(dims=(1, 1, nlat, nlon), mesh=\"flat\").isel(time=0, depth=0)\n",
+    "ds_flat = simple_UV_dataset(dims=(1, 1, nlat, nlon), mesh=\"flat\")\n",
     "ds_flat[\"temperature\"] = ds_flat[\"U\"] + 20  # add temperature field of 20 deg\n",
     "ds_flat[\"U\"].data[:] = 1.0  # set U to 1 m/s\n",
     "ds_flat[\"V\"].data[:] = 1.0  # set V to 1 m/s\n",
-    "grid = parcels.XGrid.from_dataset(ds_flat, mesh=\"flat\")\n",
-    "U = parcels.Field(\"U\", ds_flat[\"U\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "V = parcels.Field(\"V\", ds_flat[\"V\"], grid, interp_method=parcels.interpolators.XLinear)\n",
-    "UV = parcels.VectorField(\"UV\", U, V)\n",
-    "temperature = parcels.Field(\n",
-    "    \"temperature\",\n",
-    "    ds_flat[\"temperature\"],\n",
-    "    grid,\n",
-    "    interp_method=parcels.interpolators.XLinear,\n",
-    ")\n",
-    "fieldset_flat = parcels.FieldSet([U, V, UV, temperature])\n",
+    "fieldset_flat = parcels.FieldSet.from_sgrid_conventions(ds_flat, mesh=\"flat\")\n",
     "\n",
     "plt.pcolormesh(\n",
     "    fieldset_flat.U.grid.lon,\n",

pyproject.toml

@@ -85,8 +85,15 @@ select = [
   "ISC001", # single-line-implicit-string-concatenation
   "TID", # flake8-tidy-imports
   "T100", # Checks for the presence of debugger calls and imports
+  "N", # pep8 naming conventions
+  "PGH004", # ensures no blanket noqa's are used
 ]
 
+exclude = [
+  "tests-v3/**",
+  'docs/user_guide/examples_v3/**',
+] # TODO v4: Remove once folders are gone
+
 ignore = [
   # line too long (82 > 79 characters)
   "E501",
@@ -104,6 +111,13 @@ ignore = [
   "RUF043",
   "RUF046", # Value being cast to `int` is already an integer
 
+  # Parcels specific deviations from PEP8 naming
+  'N802', # We use function names that are camelcased to denote functions
+  'N806', # We use capitalized variable names within functions in Parcels to denote fields, as well as multidimensional arrays
+  'N811', # Well, this just seems like a bad rule O_o
+  'N816', # TODO: Enable for `src` and consider disabling for notebooks
+  'N818', # Not all Parcels exceptions should have an "Error" suffix
+
   # TODO: Move this ignore so that it only applies in the tests folder. Do in conjunction with any doc related rules
   "RUF059", # Unpacked variable `coords` is never used
 

src/parcels/_core/field.py

@@ -204,7 +204,7 @@ def _check_velocitysampling(self):
                 stacklevel=2,
             )
 
-    def eval(self, time: datetime, z, y, x, particles=None, applyConversion=True):
+    def eval(self, time: datetime, z, y, x, particles=None, apply_conversion=True):
         """Interpolate field values in space and time.
 
         We interpolate linearly in time and apply implicit unit
@@ -225,7 +225,7 @@ def eval(self, time: datetime, z, y, x, particles=None, applyConversion=True):
 
         _update_particle_states_interp_value(particles, value)
 
-        if applyConversion:
+        if apply_conversion:
             value = self.units.to_target(value, z, y, x)
         return value
 
@@ -244,7 +244,12 @@ class VectorField:
     """VectorField class that holds vector field data needed to execute particles."""
 
     def __init__(
-        self, name: str, U: Field, V: Field, W: Field | None = None, vector_interp_method: Callable | None = None
+        self,
+        name: str,
+        U: Field,  # noqa: N803
+        V: Field,  # noqa: N803
+        W: Field | None = None,  # noqa: N803
+        vector_interp_method: Callable | None = None,
     ):
         _assert_str_and_python_varname(name)
 
@@ -286,7 +291,7 @@ def vector_interp_method(self, method: Callable):
         assert_same_function_signature(method, ref=ZeroInterpolator_Vector, context="Interpolation")
         self._vector_interp_method = method
 
-    def eval(self, time: datetime, z, y, x, particles=None, applyConversion=True):
+    def eval(self, time: datetime, z, y, x, particles=None, apply_conversion=True):
         """Interpolate field values in space and time.
 
         We interpolate linearly in time and apply implicit unit
@@ -313,7 +318,7 @@ def eval(self, time: datetime, z, y, x, particles=None, applyConversion=True):
         else:
             (u, v, w) = self._vector_interp_method(particle_positions, grid_positions, self)
 
-        if applyConversion:
+        if apply_conversion:
             u = self.U.units.to_target(u, z, y, x)
             v = self.V.units.to_target(v, z, y, x)
             if "3D" in self.vector_type:

src/parcels/_core/fieldset.py

@@ -186,7 +186,8 @@ def gridset(self) -> list[BaseGrid]:
                 grids.append(field.grid)
         return grids
 
-    def from_copernicusmarine(ds: xr.Dataset):
+    @classmethod
+    def from_copernicusmarine(cls, ds: xr.Dataset):
         """Create a FieldSet from a Copernicus Marine Service xarray.Dataset.
 
         Parameters
@@ -241,9 +242,10 @@ def from_copernicusmarine(ds: xr.Dataset):
                 vertical_dimensions=(sgrid.DimDimPadding("z_center", "depth", sgrid.Padding.LOW),),
             ).to_attrs(),
         )
-        return FieldSet.from_sgrid_conventions(ds, mesh="spherical")
+        return cls.from_sgrid_conventions(ds, mesh="spherical")
 
-    def from_fesom2(ds: ux.UxDataset):
+    @classmethod
+    def from_fesom2(cls, ds: ux.UxDataset):
         """Create a FieldSet from a FESOM2 uxarray.UxDataset.
 
         Parameters
@@ -279,10 +281,11 @@ def from_fesom2(ds: ux.UxDataset):
         for varname in set(ds.data_vars) - set(fields.keys()):
             fields[varname] = Field(varname, ds[varname], grid, _select_uxinterpolator(ds[varname]))
 
-        return FieldSet(list(fields.values()))
+        return cls(list(fields.values()))
 
+    @classmethod
     def from_sgrid_conventions(
-        ds: xr.Dataset, mesh: Mesh
+        cls, ds: xr.Dataset, mesh: Mesh
     ):  # TODO: Update mesh to be discovered from the dataset metadata
         """Create a FieldSet from a dataset using SGRID convention metadata.
 
@@ -355,17 +358,16 @@ def from_sgrid_conventions(
         if "U" in ds.data_vars and "V" in ds.data_vars:
             fields["U"] = Field("U", ds["U"], grid, XLinear)
             fields["V"] = Field("V", ds["V"], grid, XLinear)
+            fields["UV"] = VectorField("UV", fields["U"], fields["V"])
 
             if "W" in ds.data_vars:
                 fields["W"] = Field("W", ds["W"], grid, XLinear)
                 fields["UVW"] = VectorField("UVW", fields["U"], fields["V"], fields["W"])
-            else:
-                fields["UV"] = VectorField("UV", fields["U"], fields["V"])
 
         for varname in set(ds.data_vars) - set(fields.keys()) - skip_vars:
             fields[varname] = Field(varname, ds[varname], grid, XLinear)
 
-        return FieldSet(list(fields.values()))
+        return cls(list(fields.values()))
 
 
 class CalendarError(Exception):  # TODO: Move to a parcels errors module

src/parcels/_core/index_search.py

@@ -276,7 +276,7 @@ def uxgrid_point_in_cell(grid, y: np.ndarray, x: np.ndarray, yi: np.ndarray, xi:
     return is_in_cell, coords
 
 
-def _triangle_area(A, B, C):
+def _triangle_area(A, B, C):  # noqa: N803
     """Compute the area of a triangle given by three points."""
     d1 = B - A
     d2 = C - A