Updating the list of breaking changes in v3 to v4 API

Author: erikvansebille

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.

v3to4-breaking-changes.md

@@ -1,15 +1,18 @@
-Kernels:
+## Kernels:
 
-- `particle.delete()` is no longer valid. Have to do `particle.state = StatusCode.Delete`
-- Sharing state between kernels must be done via the particle data (as now the kernels are not combined under the hood).
-- dt is a np.timedelta64 object
+- 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.
+- `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.
 
-FieldSet
+## FieldSet
 
-- `interp_method` has to be an Interpolation function, instead of a string
+- `interp_method` has to be an Interpolation function, instead of a string.
 
-ParticleSet
+## ParticleSet
 
-- ParticleSet init had `repeatdt` and `lonlatdepth_dtype` removed
-- ParticleSet.execute() expects `numpy.datetime64`/`numpy.timedelta.64` for `runtime`, `endtime` and `dt`
-- `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` has been removed
+- `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.