diff --git a/docs/community/index.rst b/docs/community/index.rst index 3121d6cab9..857152b5c4 100644 --- a/docs/community/index.rst +++ b/docs/community/index.rst @@ -10,6 +10,8 @@ See the sections in the primary sidebar and below to explore. contributing Versioning and Deprecation Policies + Release Notes + Parcels v4.0 Migration Guide diff --git a/v3to4-breaking-changes.md b/docs/community/v4-migration.md similarity index 61% rename from v3to4-breaking-changes.md rename to docs/community/v4-migration.md index f913a0d33e..3635d88a01 100644 --- a/v3to4-breaking-changes.md +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 1f2a4c97e8..0961a73b5b 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,6 +22,5 @@ If you need more help with Parcels, try the `Discussions page on GitHub Tutorials & Documentation API reference - Release Notes - Contributing + Contributing, Release Notes and more OceanParcels website diff --git a/docs/v4/index.md b/docs/v4/index.md index d3f8157a20..dadf187655 100644 --- a/docs/v4/index.md +++ b/docs/v4/index.md @@ -22,4 +22,5 @@ api nojit TODO Parcels v4 Project Board +Parcels v4 migration guide <../community/v4-migration> ```