Merge branch 'v4-dev' into time_loading_after_morton

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]

.github/workflows/pypi-release.yml

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

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/index.rst

@@ -22,6 +22,5 @@ If you need more help with Parcels, try the `Discussions page on GitHub <https:/
    Installation <installation>
    Tutorials & Documentation <documentation/index>
    API reference <reference>
-   Release Notes <https://github.com/OceanParcels/Parcels/releases>
-   Contributing <community/index>
+   Contributing, Release Notes and more <community/index>
    OceanParcels website <https://oceanparcels.org/>

docs/v4/index.md

@@ -7,7 +7,7 @@ The key goals of this update are
 1. to support `Fields` on unstructured grids;
 2. to allow for user-defined interpolation methods (somewhat similar to user-defined kernels);
 3. to make the codebase more modular, easier to extend, and more maintainable;
-4. to align Parcels more with other tools in the [Pangeo ecosystemand](https://www.pangeo.io/#ecosystem), particularly by leveraging `xarray` more; and
+4. to align Parcels more with other tools in the [Pangeo ecosystem](https://www.pangeo.io/#ecosystem), particularly by leveraging `xarray` more; and
 5. to improve the performance of Parcels.
 
 The timeline for the release of Parcels v4 is not yet fixed, but we are aiming for a release of an 'alpha' version in September 2025. This v4-alpha will have support for unstructured grids and user-defined interpolation methods, but is not yet performance-optimised.
@@ -22,4 +22,5 @@ api
 nojit
 TODO
 Parcels v4 Project Board <https://github.com/orgs/OceanParcels/projects/5>
+Parcels v4 migration guide <../community/v4-migration>
 ```

parcels/_core/utils/time.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timedelta
 from typing import TYPE_CHECKING, TypeVar
 
 import cftime
@@ -118,3 +118,29 @@ def get_datetime_type_calendar(
         # datetime isn't a cftime datetime object
         pass
     return type(example_datetime), calendar
+
+
+_TD_PRECISION_GETTER_FOR_UNIT = (
+    (lambda dt: dt.days, "D"),
+    (lambda dt: dt.seconds, "s"),
+    (lambda dt: dt.microseconds, "us"),
+)
+
+
+def maybe_convert_python_timedelta_to_numpy(dt: timedelta | np.timedelta64) -> np.timedelta64:
+    if isinstance(dt, np.timedelta64):
+        return dt
+
+    try:
+        dts = []
+        for get_value_for_unit, np_unit in _TD_PRECISION_GETTER_FOR_UNIT:
+            value = get_value_for_unit(dt)
+            if value != 0:
+                dts.append(np.timedelta64(value, np_unit))
+
+        if dts:
+            return sum(dts)
+        else:
+            return np.timedelta64(0, "s")
+    except Exception as e:
+        raise ValueError(f"Could not convert {dt!r} to np.timedelta64.") from e