merge commit

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>
 
 
 

v3to4-breaking-changes.md docs/community/v4-migration.mdv3to4-breaking-changes.md renamed to docs/community/v4-migration.md

@@ -1,11 +1,18 @@
-## Kernels:
+# Parcels v4 migration guide
 
-- The Kernel loop has been 'vectorized', so that the input of a Kernel is not one particle anymore, but a list of particles. This means that `if`-statements in Kernels don't work anymore. Replace `if`-statements with `numpy.where` statements.
+```{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
 
@@ -16,3 +23,7 @@
 - `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

@@ -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

parcels/_index_search.py

@@ -83,14 +83,16 @@ def _search_indices_curvilinear_2d(
         cc = a[1] * b[0] - a[0] * b[1] + x * b[1] - y * a[1]
 
         det2 = bb * bb - 4 * aa * cc
-        det = np.where(det2 > 0, np.sqrt(det2), eta)
-        eta = np.where(abs(aa) < 1e-12, -cc / bb, np.where(det2 > 0, (-bb + det) / (2 * aa), eta))
-
-        xsi = np.where(
-            abs(a[1] + a[3] * eta) < 1e-12,
-            ((y - py[0]) / (py[1] - py[0]) + (y - py[3]) / (py[2] - py[3])) * 0.5,
-            (x - a[0] - a[2] * eta) / (a[1] + a[3] * eta),
-        )
+        with np.errstate(divide="ignore", invalid="ignore"):
+            det = np.where(det2 > 0, np.sqrt(det2), eta)
+
+            eta = np.where(abs(aa) < 1e-12, -cc / bb, np.where(det2 > 0, (-bb + det) / (2 * aa), eta))
+
+            xsi = np.where(
+                abs(a[1] + a[3] * eta) < 1e-12,
+                ((y - py[0]) / (py[1] - py[0]) + (y - py[3]) / (py[2] - py[3])) * 0.5,
+                (x - a[0] - a[2] * eta) / (a[1] + a[3] * eta),
+            )
 
         xi = np.where(xsi < -tol, xi - 1, np.where(xsi > 1 + tol, xi + 1, xi))
         yi = np.where(eta < -tol, yi - 1, np.where(eta > 1 + tol, yi + 1, yi))