Merge branch 'v4-dev' into croco-support

Author: erikvansebille

.github/ci/min_deps_check.py

@@ -60,8 +60,8 @@ def parse_requirements(fname) -> Iterator[tuple[str, int, int, int | None]]:
 
         try:
             version_tup = tuple(int(x) for x in version.split("."))
-        except ValueError:
-            raise ValueError("non-numerical version: " + row)
+        except ValueError as e:
+            raise ValueError("non-numerical version: " + row) from e
 
         if len(version_tup) == 2:
             yield (pkg, *version_tup, None)  # type: ignore[misc]
@@ -193,7 +193,7 @@ def main() -> None:
         print("\nErrors:")
         print("-------")
         for i, e in enumerate(errors):
-            print(f"{i+1}. {e}")
+            print(f"{i + 1}. {e}")
         sys.exit(1)
 
 

.github/workflows/pypi-release.yml

@@ -90,10 +90,6 @@ jobs:
           path: dist
       - name: Publish package to PyPI
         uses: pypa/gh-action-pypi-publish@v1.12.4
-        with:
-          user: __token__
-          password: ${{ secrets.PARCELS_PYPI_PROD_TOKEN }}
-          verbose: true
 
   test-pypi-release:
     needs: upload-to-pypi

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
         types: [text]
         files: \.(json|ipynb)$
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.6
+    rev: v0.12.5
     hooks:
       - id: ruff
         name: ruff lint (.py)
@@ -23,13 +23,13 @@ repos:
       - id: ruff-format
         types_or: [python, jupyter]
   - repo: https://github.com/rbubley/mirrors-prettier # Update mirror as official mirror is deprecated
-    rev: v3.4.2
+    rev: v3.6.2
     hooks:
       - id: prettier
 
   # Ruff doesn't have full coverage of pydoclint https://github.com/astral-sh/ruff/issues/12434
   - repo: https://github.com/PyCQA/flake8
-    rev: 7.1.1
+    rev: 7.3.0
     hooks:
       - id: flake8
         name: pydoclint

README.md

@@ -3,7 +3,8 @@
 [![Anaconda-release](https://anaconda.org/conda-forge/parcels/badges/version.svg)](https://anaconda.org/conda-forge/parcels/)
 [![Anaconda-date](https://anaconda.org/conda-forge/parcels/badges/latest_release_date.svg)](https://anaconda.org/conda-forge/parcels/)
 [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.823561.svg)](https://doi.org/10.5281/zenodo.823561)
-[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
+[![Xarray](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydata/xarray/refs/heads/main/doc/badge.json)](https://xarray.dev)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![unit-tests](https://github.com/OceanParcels/parcels/actions/workflows/ci.yml/badge.svg)](https://github.com/OceanParcels/parcels/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/OceanParcels/parcels/branch/main/graph/badge.svg)](https://codecov.io/gh/OceanParcels/parcels)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5353/badge)](https://bestpractices.coreinfrastructure.org/projects/5353)

docs/community/index.rst

@@ -10,6 +10,8 @@ See the sections in the primary sidebar and below to explore.
 
     contributing
     Versioning and Deprecation Policies <policies>
+    Release Notes <https://github.com/OceanParcels/Parcels/releases>
+    Parcels v4.0 Migration Guide <v4-migration>
 
 
 

docs/community/v4-migration.md

@@ -0,0 +1,29 @@
+# Parcels v4 migration guide
+
+```{warning}
+Version 4 of Parcels is unreleased at the moment. The information in this migration guide is a work in progress, and is subject to change. If you would like to provide feedback on this migration guide (or generally on the development of v4) please [submit an issue](https://github.com/OceanParcels/Parcels/issues/new/choose).
+```
+
+## Kernels
+
+- The Kernel loop has been 'vectorized', so that the input of a Kernel is not one particle anymore, but a collection of particles. This means that `if`-statements in Kernels don't work anymore. Replace `if`-statements with `numpy.where` statements.
+- `particle.delete()` is no longer valid. Instead, use `particle.state = StatusCode.Delete`.
+- Sharing state between kernels must be done via the particle data (as the kernels are not combined under the hood anymore).
+- `particl_dlon`, `particle_dlat` etc have been renamed to `particle.dlon` and `particle.dlat`.
+- `particle.dt` is a np.timedelta64 object; be careful when multiplying `particle.dt` with a velocity, as its value may be cast to nanoseconds.
+- The `time` argument in the Kernel signature is now standard `None` (and may be removed in the Kernel API before release of v4), so can't be used. Use `particle.time` instead.
+- `math` functions should be replaced with array compatible equivalents (e.g., `math.sin` -> `np.sin`). Instead of `ParcelsRandom` you should use numpy's random functions.
+
+## FieldSet
+
+- `interp_method` has to be an Interpolation function, instead of a string.
+
+## ParticleSet
+
+- `repeatdt` and `lonlatdepth_dtype` have been removed from the ParticleSet.
+- ParticleSet.execute() expects `numpy.datetime64`/`numpy.timedelta.64` for `runtime`, `endtime` and `dt`.
+- `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` have been removed.
+
+## ParticleFile
+
+- Particlefiles should be created by `ParticleFile(...)` instead of `pset.ParticleFile(...)`

docs/examples/example_globcurrent.py

@@ -196,7 +196,7 @@ def test_globcurrent_particle_independence(rundays=5):
     time0 = fieldset.U.grid.time[0]
 
     def DeleteP0(particle, fieldset, time):  # pragma: no cover
-        if particle.id == 0:
+        if particle.trajectory == 0:
             particle.delete()
 
     pset0 = parcels.ParticleSet(
@@ -244,7 +244,7 @@ def test_globcurrent_pset_fromfile(dt, pid_offset, tmpdir):
     pset.execute(parcels.AdvectionRK4, runtime=timedelta(days=1), dt=dt)
     pset_new.execute(parcels.AdvectionRK4, runtime=timedelta(days=1), dt=dt)
 
-    for var in ["lon", "lat", "depth", "time", "id"]:
+    for var in ["lon", "lat", "depth", "time", "trajectory"]:
         assert np.allclose(
             [getattr(p, var) for p in pset], [getattr(p, var) for p in pset_new]
         )

docs/examples/example_mitgcm.py

@@ -27,9 +27,9 @@ def run_mitgcm_zonally_reentrant(path: Path):
 
     def periodicBC(particle, fieldset, time):  # pragma: no cover
         if particle.lon < 0:
-            particle_dlon += fieldset.domain_width  # noqa
+            particle.dlon += fieldset.domain_width
         elif particle.lon > fieldset.domain_width:
-            particle_dlon -= fieldset.domain_width
+            particle.dlon -= fieldset.domain_width
 
     # Release particles 5 cells away from the Eastern boundary
     pset = parcels.ParticleSet.from_line(

docs/examples/example_moving_eddies.py

@@ -272,17 +272,17 @@ def test_periodic_and_computeTimeChunk_eddies():
 
     def periodicBC(particle, fieldset, time):  # pragma: no cover
         if particle.lon < fieldset.halo_west:
-            particle_dlon += fieldset.halo_east - fieldset.halo_west  # noqa
+            particle.dlon += fieldset.halo_east - fieldset.halo_west
         elif particle.lon > fieldset.halo_east:
-            particle_dlon -= fieldset.halo_east - fieldset.halo_west
+            particle.dlon -= fieldset.halo_east - fieldset.halo_west
         if particle.lat < fieldset.halo_south:
-            particle_dlat += fieldset.halo_north - fieldset.halo_south  # noqa
+            particle.dlat += fieldset.halo_north - fieldset.halo_south
         elif particle.lat > fieldset.halo_north:
-            particle_dlat -= fieldset.halo_north - fieldset.halo_south
+            particle.dlat -= fieldset.halo_north - fieldset.halo_south
 
     def slowlySouthWestward(particle, fieldset, time):  # pragma: no cover
-        particle_dlon -= 5 * particle.dt / 1e5  # noqa
-        particle_dlat -= 3 * particle.dt / 1e5  # noqa
+        particle.dlon -= 5 * particle.dt / 1e5
+        particle.dlat -= 3 * particle.dt / 1e5
 
     kernels = pset.Kernel(parcels.AdvectionRK4) + slowlySouthWestward + periodicBC
     pset.execute(kernels, runtime=timedelta(days=6), dt=timedelta(hours=1))

docs/examples/example_nemo_curvilinear.py

@@ -43,7 +43,7 @@ def run_nemo_curvilinear(outfile, advtype="RK4"):
 
     def periodicBC(particle, fieldSet, time):  # pragma: no cover
         if particle.lon > 180:
-            particle_dlon -= 360  # noqa
+            particle.dlon -= 360
 
     pset = parcels.ParticleSet.from_list(fieldset, parcels.Particle, lon=lonp, lat=latp)
     pfile = parcels.ParticleFile(outfile, pset, outputdt=timedelta(days=1))