DOC: Add page for v4-migration guide

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

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