From e755e98e56f183947529de062c342920c7beeab1 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Fri, 10 Jul 2026 15:06:00 +0200 Subject: [PATCH 1/6] Update migration guide to a tabular format format --- .../examples/tutorial_delaystart.ipynb | 2 +- docs/user_guide/v4-migration.md | 92 +++++++++++-------- 2 files changed, 56 insertions(+), 38 deletions(-) diff --git a/docs/user_guide/examples/tutorial_delaystart.ipynb b/docs/user_guide/examples/tutorial_delaystart.ipynb index 6ec8bb296..0cb94ef89 100644 --- a/docs/user_guide/examples/tutorial_delaystart.ipynb +++ b/docs/user_guide/examples/tutorial_delaystart.ipynb @@ -175,7 +175,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Release particles repeatedly at a set frequency using `np.broadcast_to`\n" + "## Release particles repeatedly\n" ] }, { diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 323667f21..cc3a1c8f6 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -1,63 +1,81 @@ +--- +html_theme.sidebar_primary.remove: true +html_theme.sidebar_secondary.remove: true +--- + # 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/Parcels-code/Parcels/issues/new/choose). -``` +This migration guide gives some tips if you want to migrate your Parcels v3 code to Parcels v4. The biggest changes are in the [Kernel API](#kernels) and the way that [FieldSets are created](#fieldset). The other changes are mostly small and should be easy to fix. ## 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`. -- The `time` argument in the Kernel signature has been removed in the Kernel API, so can't be used. Use `particle.t` instead. -- The `particle` argument in the Kernel signature has been renamed to `particles`. -- `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. -- `particle.depth` has been changed to `particles.z` to be consistent with the [CF conventions for trajectory data](https://cfconventions.org/cf-conventions/cf-conventions.html#trajectory-data), and to make Parcels also generalizable to atmospheric contexts. -- The `InteractionKernel` class has been removed. Since normal Kernels now have access to _all_ particles, particle-particle interaction can be performed within normal Kernels. -- Users need to explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with CROCO data, as the automatic conversion from depth to sigma grids under the hood has been removed. -- We added a new AdvectionRK2 Kernel. The AdvectionRK4 kernel is still available, but RK2 is now the recommended default advection scheme as it is faster while the accuracy is comparable for most applications. See also the Choosing an integration method tutorial. -- Functions shouldn't be converted to Kernels before adding to a pset.execute() call. Instead, simply pass the function(s) as a list to pset.execute(). -- Kernel variables `time`, `lat` and `lon` have been renamed to `t`, `y` and `x`, and `dlat` and `dlon` have been renamed to `dy` and `dx`. These changes are also reflected on the ParticleSet as well as the ParticleFile output. +| # | Description of change | How to migrate | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | The Kernel loop has been 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or boolean indexing | +| 2 | Functions that work on particles should be vectorized, i.e. they should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | +| 3 | The `time` argument in the Kernel signature has been removed | Use `particle.t` | +| 4 | `particle.lon`, `particle.lat` and `particle.depth` have been renamed | Use `particles.x`, `particles.y` and `particles.z` | +| 5 | `particle_dlon` `particle_dlat` and `particle_ddepth` have been renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | +| 6 | The `particle` argument in the Kernel signature has been renamed to `particles` | Change the argument name in your Kernel signature to `particles` | +| 7 | `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | +| 8 | Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | +| 9 | The `InteractionKernel` class has been removed. Since normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | +| 10 | Automatic conversion from depth to sigma grids under the hood has been removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | +| 11 | The default advection scheme has been changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | ## FieldSet -- `interp_method` has to be an Interpolation function, instead of a string. -- `.add_constant` has been renamed to `.add_context` to reflect that this value no longer has to be constant +| # | Description of change | How to migrate | +| --- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| 12 | `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | +| 13 | `FieldSet.add_constant` has been removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | ## Particle -- `Particle.add_variables()` has been replaced by `Particle.add_variable()`, which now also takes a list of `Variables`. +| # | Description of change | How to migrate | +| --- | ------------------------------------------ | ----------------------------------------------------------------- | +| 14 | `Particle.add_variable()` has been removed | Use `Particle.add_variables()`, which takes a list of `Variables` | ## ParticleSet -- `repeatdt` and `lonlatdepth_dtype` have been removed from the ParticleSet. -- ParticleSet.execute() expects `numpy.datetime64`/`numpy.timedelta.64` for `endtime`. While floats are supported for `runtime` and `dt`, using `numpy.datetime64`/`numpy.timedelta.64` for these arguments too is encouraged. -- `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` have been removed. +| # | Description of change | How to migrate | +| --- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 15 | pset.execute() does not require Kernel objects | Simply pass the function(s) as a list to pset.execute() | +| 16 | `repeatdt` has been removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | +| 17 | `lonlatdepth_dtype` has been removed | Remove it from your code | +| 18 | ParticleSet.execute() expects `datatime`, `numpy.datetime64` or `numpy.timedelta.64` for `runtime` and `endtime` | Update `runtime` and `endtime` to use `numpy.datetime64` or `numpy.timedelta.64` | +| 19 | `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` have been removed | Use `ParticleSet` constructor directly | ## ParticleFile -- ParticleFiles output is now written in parquet format by default, instead of zarr. This means that ParticleFiles can now be read with `polars.read_parquet`. We also provide a helper function `parcels.read_particlefile` to read ParticleFiles, which automatically converts the cftime. -- Particlefiles should be created by `ParticleFile(...)` instead of `pset.ParticleFile(...)` -- `ParticleFile` writing behaviour now errors out if there's existing output (this be being further discussed in https://github.com/Parcels-code/Parcels/issues/2593 ) -- A utility to read in ParticleFile output is now available. `parcels.read_particlefile()` -- "trajectory" is now called "particle_id" in the particle file output -- The `name` argument in `ParticleFile` has been replaced by `path` and can now be a string or a Path. -- The `chunks` argument in `ParticleFile` has been removed. -- The `to_write="once"`option has been removed. A variable can now only be either written at every output time step, or not written at all. -- Particles are not written when they are deleted. You can use the functionality to call `ParticleFile.write()` inside a kernel to write out deleted particles if you want to keep track of them. +| # | Description of change | How to migrate | +| --- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| 20 | ParticleFiles output is now written in parquet format by default, instead of zarr | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | +| 21 | `ParticleFile` is not a method of the `ParticleSet` class anymore | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | +| 22 | `ParticleFile` writing behaviour errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | +| 23 | The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | +| 24 | `ParticleFile` does not have a `name` attribute anymore | Use `ParticleFile.path`, which can be a string or a Path | +| 25 | `ParticleFile` does not have a `chunks` argument anymore | Remove the `chunks` argument from your code | +| 26 | `ParticleFile` does not have a `to_write` argument anymore | Remove the `to_write` argument from your code | +| 27 | Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | ## Field -- `Field.eval()` returns an array of floats instead of a single float (related to the vectorization) -- `Field.eval()` does not throw OutOfBounds or other errors -- The `NestedField` class has been removed. See the Nested Grids how-to guide for how to set up Nested Grids in v4. -- `applyConversion` has been removed. Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels. +| # | Description of change | How to migrate | +| --- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 28 | Calling `Field.eval()` directly only warns if any values are out of bounds, instead of throwing an error | Use `Field.eval()` as before, but check for warnings | +| 29 | `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | +| 30 | The `NestedField` class has been removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | +| 31 | `applyConversion` has been removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels. | ## GridSet -- `GridSet` is now a list, so change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]`. +| # | Description of change | How to migrate | +| --- | ----------------------- | ----------------------------------------------------------- | +| 32 | `GridSet` is now a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | ## UnitConverters -- UnitConverters have been removed. Instead, Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat"). +| # | Description of change | How to migrate | +| --- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 33 | The `UnitConverter` class has been removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | From 19e4281ce8e9301d1d12f83ddb1eb4dc60121ea7 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Fri, 10 Jul 2026 16:51:34 +0200 Subject: [PATCH 2/6] Update v4-migration.md --- docs/user_guide/v4-migration.md | 91 ++++++++++++++++----------------- 1 file changed, 45 insertions(+), 46 deletions(-) diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index cc3a1c8f6..c4eded5c1 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -1,5 +1,4 @@ --- -html_theme.sidebar_primary.remove: true html_theme.sidebar_secondary.remove: true --- @@ -9,73 +8,73 @@ This migration guide gives some tips if you want to migrate your Parcels v3 code ## Kernels -| # | Description of change | How to migrate | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | The Kernel loop has been 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or boolean indexing | -| 2 | Functions that work on particles should be vectorized, i.e. they should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | -| 3 | The `time` argument in the Kernel signature has been removed | Use `particle.t` | -| 4 | `particle.lon`, `particle.lat` and `particle.depth` have been renamed | Use `particles.x`, `particles.y` and `particles.z` | -| 5 | `particle_dlon` `particle_dlat` and `particle_ddepth` have been renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | -| 6 | The `particle` argument in the Kernel signature has been renamed to `particles` | Change the argument name in your Kernel signature to `particles` | -| 7 | `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | -| 8 | Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | -| 9 | The `InteractionKernel` class has been removed. Since normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | -| 10 | Automatic conversion from depth to sigma grids under the hood has been removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | -| 11 | The default advection scheme has been changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | +| # | Description of change | How to migrate | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or [boolean indexing](examples/tutorial_Argofloats) | +| 2 | Functions should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | +| 3 | The `time` argument in the Kernel signature is removed | Use `particle.t` | +| 4 | `particle.lon`, `particle.lat` and `particle.depth` are renamed | Use `particles.x`, `particles.y` and `particles.z` | +| 5 | `particle_dlon` `particle_dlat` and `particle_ddepth` are renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | +| 6 | The `particle` argument in the Kernel signature is renamed to `particles` | Change the argument name in your Kernel signature to `particles` | +| 7 | `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | +| 8 | Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | +| 9 | The `InteractionKernel` class is removed as normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | +| 10 | Automatic conversion from depth to sigma grids under the hood is removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | +| 11 | The default advection scheme is changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | ## FieldSet -| # | Description of change | How to migrate | -| --- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| 12 | `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | -| 13 | `FieldSet.add_constant` has been removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | +| # | Description of change | How to migrate | +| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| 12 | `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | +| 13 | `FieldSet.add_constant` is removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | ## Particle -| # | Description of change | How to migrate | -| --- | ------------------------------------------ | ----------------------------------------------------------------- | -| 14 | `Particle.add_variable()` has been removed | Use `Particle.add_variables()`, which takes a list of `Variables` | +| # | Description of change | How to migrate | +| --- | ------------------------------------ | ---------------------------------------------------------------------- | +| 14 | `Particle.add_variable()` is removed | Use `Particle.add_variables()`, which also takes a list of `Variables` | ## ParticleSet | # | Description of change | How to migrate | | --- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 15 | pset.execute() does not require Kernel objects | Simply pass the function(s) as a list to pset.execute() | -| 16 | `repeatdt` has been removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | -| 17 | `lonlatdepth_dtype` has been removed | Remove it from your code | +| 16 | `repeatdt` is removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | +| 17 | `lonlatdepth_dtype` is removed | Set the dtype of your particle variables directly | | 18 | ParticleSet.execute() expects `datatime`, `numpy.datetime64` or `numpy.timedelta.64` for `runtime` and `endtime` | Update `runtime` and `endtime` to use `numpy.datetime64` or `numpy.timedelta.64` | -| 19 | `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` have been removed | Use `ParticleSet` constructor directly | +| 19 | `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` are removed | Use [`ParticleSet` constructor](examples/tutorial_delaystart)directly | ## ParticleFile -| # | Description of change | How to migrate | -| --- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| 20 | ParticleFiles output is now written in parquet format by default, instead of zarr | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | -| 21 | `ParticleFile` is not a method of the `ParticleSet` class anymore | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | -| 22 | `ParticleFile` writing behaviour errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | -| 23 | The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | -| 24 | `ParticleFile` does not have a `name` attribute anymore | Use `ParticleFile.path`, which can be a string or a Path | -| 25 | `ParticleFile` does not have a `chunks` argument anymore | Remove the `chunks` argument from your code | -| 26 | `ParticleFile` does not have a `to_write` argument anymore | Remove the `to_write` argument from your code | -| 27 | Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | +| # | Description of change | How to migrate | +| --- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| 20 | ParticleFiles output is in [parquet format](getting_started/tutorial_output) | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | +| 21 | `ParticleFile` is not a method of the `ParticleSet` class | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | +| 22 | `ParticleFile` errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | +| 23 | The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | +| 24 | `ParticleFile` does not have a `name` attribute | Use `ParticleFile.path`, which can be a string or a Path | +| 25 | `ParticleFile` does not have a `chunks` argument | Remove the `chunks` argument from your code | +| 26 | `ParticleFile` does not have a `to_write` argument | Remove the `to_write` argument from your code | +| 27 | Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | ## Field -| # | Description of change | How to migrate | -| --- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 28 | Calling `Field.eval()` directly only warns if any values are out of bounds, instead of throwing an error | Use `Field.eval()` as before, but check for warnings | -| 29 | `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | -| 30 | The `NestedField` class has been removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | -| 31 | `applyConversion` has been removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels. | +| # | Description of change | How to migrate | +| --- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 28 | Calling `Field.eval()` directly gives a warning if any values are out of bounds | Use `Field.eval()` as before, but check for warnings | +| 29 | `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | +| 30 | The `NestedField` class is removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | +| 31 | `applyConversion` is removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels | ## GridSet -| # | Description of change | How to migrate | -| --- | ----------------------- | ----------------------------------------------------------- | -| 32 | `GridSet` is now a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | +| # | Description of change | How to migrate | +| --- | --------------------- | ----------------------------------------------------------- | +| 32 | `GridSet` is a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | ## UnitConverters -| # | Description of change | How to migrate | -| --- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 33 | The `UnitConverter` class has been removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | +| # | Description of change | How to migrate | +| --- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 33 | The `UnitConverter` class is removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | From f45414a027026aacd35d619d2ac5c6aa09f5b001 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Fri, 10 Jul 2026 17:05:39 +0200 Subject: [PATCH 3/6] Removing column with numbering --- docs/user_guide/v4-migration.md | 98 ++++++++++++++++----------------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index c4eded5c1..9e110444f 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -8,73 +8,73 @@ This migration guide gives some tips if you want to migrate your Parcels v3 code ## Kernels -| # | Description of change | How to migrate | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or [boolean indexing](examples/tutorial_Argofloats) | -| 2 | Functions should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | -| 3 | The `time` argument in the Kernel signature is removed | Use `particle.t` | -| 4 | `particle.lon`, `particle.lat` and `particle.depth` are renamed | Use `particles.x`, `particles.y` and `particles.z` | -| 5 | `particle_dlon` `particle_dlat` and `particle_ddepth` are renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | -| 6 | The `particle` argument in the Kernel signature is renamed to `particles` | Change the argument name in your Kernel signature to `particles` | -| 7 | `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | -| 8 | Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | -| 9 | The `InteractionKernel` class is removed as normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | -| 10 | Automatic conversion from depth to sigma grids under the hood is removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | -| 11 | The default advection scheme is changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | +| Description of change | How to migrate | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or [boolean indexing](examples/tutorial_Argofloats) | +| Functions should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | +| The `time` argument in the Kernel signature is removed | Use `particle.t` | +| `particle.lon`, `particle.lat` and `particle.depth` are renamed | Use `particles.x`, `particles.y` and `particles.z` | +| `particle_dlon` `particle_dlat` and `particle_ddepth` are renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | +| The `particle` argument in the Kernel signature is renamed to `particles` | Change the argument name in your Kernel signature to `particles` | +| `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | +| Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | +| The `InteractionKernel` class is removed as normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | +| Automatic conversion from depth to sigma grids under the hood is removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | +| The default advection scheme is changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | ## FieldSet -| # | Description of change | How to migrate | -| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| 12 | `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | -| 13 | `FieldSet.add_constant` is removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | +| Description of change | How to migrate | +| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | +| `FieldSet.add_constant` is removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | ## Particle -| # | Description of change | How to migrate | -| --- | ------------------------------------ | ---------------------------------------------------------------------- | -| 14 | `Particle.add_variable()` is removed | Use `Particle.add_variables()`, which also takes a list of `Variables` | +| Description of change | How to migrate | +| ------------------------------------ | ---------------------------------------------------------------------- | +| `Particle.add_variable()` is removed | Use `Particle.add_variables()`, which also takes a list of `Variables` | ## ParticleSet -| # | Description of change | How to migrate | -| --- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 15 | pset.execute() does not require Kernel objects | Simply pass the function(s) as a list to pset.execute() | -| 16 | `repeatdt` is removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | -| 17 | `lonlatdepth_dtype` is removed | Set the dtype of your particle variables directly | -| 18 | ParticleSet.execute() expects `datatime`, `numpy.datetime64` or `numpy.timedelta.64` for `runtime` and `endtime` | Update `runtime` and `endtime` to use `numpy.datetime64` or `numpy.timedelta.64` | -| 19 | `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` are removed | Use [`ParticleSet` constructor](examples/tutorial_delaystart)directly | +| Description of change | How to migrate | +| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| pset.execute() does not require Kernel objects | Simply pass the function(s) as a list to pset.execute() | +| `repeatdt` is removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | +| `lonlatdepth_dtype` is removed | Set the dtype of your particle variables directly | +| ParticleSet.execute() expects `datatime`, `numpy.datetime64` or `numpy.timedelta.64` for `runtime` and `endtime` | Update `runtime` and `endtime` to use `numpy.datetime64` or `numpy.timedelta.64` | +| `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` are removed | Use [`ParticleSet` constructor](examples/tutorial_delaystart)directly | ## ParticleFile -| # | Description of change | How to migrate | -| --- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| 20 | ParticleFiles output is in [parquet format](getting_started/tutorial_output) | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | -| 21 | `ParticleFile` is not a method of the `ParticleSet` class | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | -| 22 | `ParticleFile` errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | -| 23 | The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | -| 24 | `ParticleFile` does not have a `name` attribute | Use `ParticleFile.path`, which can be a string or a Path | -| 25 | `ParticleFile` does not have a `chunks` argument | Remove the `chunks` argument from your code | -| 26 | `ParticleFile` does not have a `to_write` argument | Remove the `to_write` argument from your code | -| 27 | Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | +| Description of change | How to migrate | +| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| ParticleFiles output is in [parquet format](getting_started/tutorial_output) | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | +| `ParticleFile` is not a method of the `ParticleSet` class | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | +| `ParticleFile` errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | +| The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | +| `ParticleFile` does not have a `name` attribute | Use `ParticleFile.path`, which can be a string or a Path | +| `ParticleFile` does not have a `chunks` argument | Remove the `chunks` argument from your code | +| `ParticleFile` does not have a `to_write` argument | Remove the `to_write` argument from your code | +| Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | ## Field -| # | Description of change | How to migrate | -| --- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 28 | Calling `Field.eval()` directly gives a warning if any values are out of bounds | Use `Field.eval()` as before, but check for warnings | -| 29 | `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | -| 30 | The `NestedField` class is removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | -| 31 | `applyConversion` is removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels | +| Description of change | How to migrate | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Calling `Field.eval()` directly gives a warning if any values are out of bounds | Use `Field.eval()` as before, but check for warnings | +| `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | +| The `NestedField` class is removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | +| `applyConversion` is removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels | ## GridSet -| # | Description of change | How to migrate | -| --- | --------------------- | ----------------------------------------------------------- | -| 32 | `GridSet` is a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | +| Description of change | How to migrate | +| --------------------- | ----------------------------------------------------------- | +| `GridSet` is a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | ## UnitConverters -| # | Description of change | How to migrate | -| --- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 33 | The `UnitConverter` class is removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | +| Description of change | How to migrate | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| The `UnitConverter` class is removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | From c1428fa508329c87c450e884a98514ca84692277 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 13 Jul 2026 09:48:46 +0200 Subject: [PATCH 4/6] Changing migration guide to be chat-like --- docs/user_guide/v4-migration.md | 414 ++++++++++++++++++++++++++++---- 1 file changed, 365 insertions(+), 49 deletions(-) diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 9e110444f..855ce95c5 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -6,75 +6,391 @@ html_theme.sidebar_secondary.remove: true This migration guide gives some tips if you want to migrate your Parcels v3 code to Parcels v4. The biggest changes are in the [Kernel API](#kernels) and the way that [FieldSets are created](#fieldset). The other changes are mostly small and should be easy to fix. + + +
+ +
+Description of change +
+
+How to migrate +
+ +
+ ## Kernels -| Description of change | How to migrate | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles | Replace `if`-statements with `numpy.where` statements or [boolean indexing](examples/tutorial_Argofloats) | -| Functions should work on a collection of particles instead of a single particle | Use `numpy` functions instead of `math` functions | -| The `time` argument in the Kernel signature is removed | Use `particle.t` | -| `particle.lon`, `particle.lat` and `particle.depth` are renamed | Use `particles.x`, `particles.y` and `particles.z` | -| `particle_dlon` `particle_dlat` and `particle_ddepth` are renamed | Use `particles.dx`, `particles.dy` and `particles.dz` | -| The `particle` argument in the Kernel signature is renamed to `particles` | Change the argument name in your Kernel signature to `particles` | -| `particle.delete()` is no longer valid | Use `particle.state = StatusCode.Delete` | -| Kernels are not concatenated under the hood, so can't access each others variables or states | Use fieldset.context or particle data to share information between kernels | -| The `InteractionKernel` class is removed as normal Kernels now have access to _all_ particles | Particle-particle interaction can be [performed within normal Kernels](examples/tutorial_interaction) | -| Automatic conversion from depth to sigma grids under the hood is removed | Explicitly use `convert_z_to_sigma_croco` in sampling kernels (such as the `AdvectionRK4_3D_CROCO` or `SampleOMegaCroco` kernels) when working with [CROCO data](examples/tutorial_croco_3D) | -| The default advection scheme is changed from RK4 to RK2 as it is [faster while the accuracy is comparable for most applications](examples/tutorial_dt_integrators) | Use `pset.execute(parcels.AdvectionRK2)` for advection | +
+ +
+The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles +
+
+Replace if-statements with numpy.where statements or boolean indexing +
+
+ +
+Functions should work on a collection of particles instead of a single particle +
+
+Use numpy functions instead of math functions +
+
+ +
+The time argument in the Kernel signature is removed +
+
+Use particle.t +
+
+ +
+particle.lon, particle.lat and particle.depth are renamed +
+
+Use particles.x, particles.y and particles.z +
+
+ +
+particle_dlon particle_dlat and particle_ddepth are renamed +
+
+Use particles.dx, particles.dy and particles.dz +
+
+ +
+The particle argument in the Kernel signature is renamed to particles +
+
+Change the argument name in your Kernel signature to particles +
+
+ +
+particle.delete() is no longer valid +
+
+Use particle.state = StatusCode.Delete +
+
+ +
+Kernels are not concatenated under the hood, so can't access each others variables or states +
+
+Use fieldset.context or particle data to share information between kernels +
+
+ +
+The InteractionKernel class is removed as normal Kernels now have access to all particles +
+
+Particle-particle interaction can be performed within normal Kernels +
+
+ +
+Automatic conversion from depth to sigma grids under the hood is removed +
+
+Explicitly use convert_z_to_sigma_croco in sampling kernels (such as the AdvectionRK4_3D_CROCO or SampleOMegaCroco kernels) when working with CROCO data +
+
+ +
+The default advection scheme is changed from RK4 to RK2 as it is faster while the accuracy is comparable for most applications +
+
+Use pset.execute(parcels.AdvectionRK2) for advection +
+
+ +
## FieldSet -| Description of change | How to migrate | -| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| `FieldSet.interp_method` doesn't accept a string (e.g. `"linear"` or `"nearest"`) | Use an Interpolation function such as `parcels.interpolators.Linear` or `parcels.interpolators.Nearest` | -| `FieldSet.add_constant` is removed to reflect that this value no longer has to be constant | Use `FieldSet.add_context` to add a context variable to the FieldSet | +
+ +
+FieldSet.interp_method doesn't accept a string (e.g. "linear" or "nearest") +
+
+Use an Interpolation function such as parcels.interpolators.Linear or parcels.interpolators.Nearest +
+
+ +
+FieldSet.add_constant is removed to reflect that this value no longer has to be constant +
+
+Use FieldSet.add_context to add a context variable to the FieldSet +
+
+ +
## Particle -| Description of change | How to migrate | -| ------------------------------------ | ---------------------------------------------------------------------- | -| `Particle.add_variable()` is removed | Use `Particle.add_variables()`, which also takes a list of `Variables` | +
+ +
+Particle.add_variable() is removed +
+
+Use Particle.add_variables(), which also takes a list of Variables +
+
+ +
## ParticleSet -| Description of change | How to migrate | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| pset.execute() does not require Kernel objects | Simply pass the function(s) as a list to pset.execute() | -| `repeatdt` is removed | See the [Delayed starts tutorial](examples/tutorial_delaystart.ipynb#release-particles-repeatedly) for how to implement repeated releases of particles | -| `lonlatdepth_dtype` is removed | Set the dtype of your particle variables directly | -| ParticleSet.execute() expects `datatime`, `numpy.datetime64` or `numpy.timedelta.64` for `runtime` and `endtime` | Update `runtime` and `endtime` to use `numpy.datetime64` or `numpy.timedelta.64` | -| `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` are removed | Use [`ParticleSet` constructor](examples/tutorial_delaystart)directly | +
+ +
+pset.execute() does not require Kernel objects +
+
+Simply pass the function(s) as a list to pset.execute() +
+
+ +
+repeatdt is removed +
+
+See the Delayed starts tutorial for how to implement repeated releases of particles +
+
+ +
+lonlatdepth_dtype is removed +
+
+Set the dtype of your particle variables directly +
+
+ +
+ParticleSet.execute() expects datatime, numpy.datetime64 or numpy.timedelta.64 for runtime and endtime +
+
+Update runtime and endtime to use numpy.datetime64 or numpy.timedelta.64 +
+
+ +
+ParticleSet.from_field(), ParticleSet.from_line(), ParticleSet.from_list() are removed +
+
+Use the ParticleSet constructor directly +
+
+ +
## ParticleFile -| Description of change | How to migrate | -| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| ParticleFiles output is in [parquet format](getting_started/tutorial_output) | Read the output with `polars.read_parquet` or (to automatically handle cftime) `parcels.read_particlefile` | -| `ParticleFile` is not a method of the `ParticleSet` class | Use `ParticleFile(...)` instead of `pset.ParticleFile(...)` | -| `ParticleFile` errors out if there's existing output | Remove the existing output file or add `mode="w"` to overwrite | -| The output file does not have a `trajectory` dimension | Use `particle_id` instead of `trajectory` in your code | -| `ParticleFile` does not have a `name` attribute | Use `ParticleFile.path`, which can be a string or a Path | -| `ParticleFile` does not have a `chunks` argument | Remove the `chunks` argument from your code | -| `ParticleFile` does not have a `to_write` argument | Remove the `to_write` argument from your code | -| Particles are not written when they are deleted | Call `ParticleFile.write()` [inside a kernel to write out](examples/tutorial_write_in_kernel.ipynb#writing-on-particle-deletion) deleted particles | +
+ +
+ParticleFiles output is in parquet format +
+
+Read the output with polars.read_parquet or (to automatically handle cftime) parcels.read_particlefile +
+
+ +
+ParticleFile is not a method of the ParticleSet class +
+
+Use ParticleFile(...) instead of pset.ParticleFile(...) +
+
+ +
+ParticleFile errors out if there's existing output +
+
+Remove the existing output file or add mode="w" to overwrite +
+
+ +
+The output file does not have a trajectory dimension +
+
+Use particle_id instead of trajectory in your code +
+
+ +
+ParticleFile does not have a name attribute +
+
+Use ParticleFile.path, which can be a string or a Path +
+
+ +
+ParticleFile does not have a chunks argument +
+
+Remove the chunks argument from your code +
+
+ +
+ParticleFile does not have a to_write argument +
+
+Remove the to_write argument from your code +
+
+ +
+Particles are not written when they are deleted +
+
+Call ParticleFile.write() inside a kernel to write out deleted particles +
+
+ +
## Field -| Description of change | How to migrate | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Calling `Field.eval()` directly gives a warning if any values are out of bounds | Use `Field.eval()` as before, but check for warnings | -| `Field.eval()` returns an array of floats (related to the vectorization) | Use `Field.eval()` as before, but expect an array of floats instead of a single float | -| The `NestedField` class is removed | See the [Nested Grids tutorial](examples/tutorial_nestedgrids) for how to set up Nested Grids in v4 | -| `applyConversion` is removed | Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels | +
+ +
+Calling Field.eval() directly gives a warning if any values are out of bounds +
+
+Use Field.eval() as before, but check for warnings +
+
+ +
+Field.eval() returns an array of floats (related to the vectorization) +
+
+Use Field.eval() as before, but expect an array of floats instead of a single float +
+
+ +
+The NestedField class is removed +
+
+See the Nested Grids tutorial for how to set up Nested Grids in v4 +
+
+ +
+applyConversion is removed +
+
+Interpolation on VectorFields automatically converts from m/s to degrees/s for spherical meshes. Other conversion of units should be handled in Interpolators or Kernels +
+
+ +
## GridSet -| Description of change | How to migrate | -| --------------------- | ----------------------------------------------------------- | -| `GridSet` is a list | Change `fieldset.gridset.grids[0]` to `fieldset.gridset[0]` | +
+ +
+GridSet is a list +
+
+Change fieldset.gridset.grids[0] to fieldset.gridset[0] +
+
+ +
## UnitConverters -| Description of change | How to migrate | -| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| The `UnitConverter` class is removed | Remove any `UnitConverter` usage from your code and Interpolation functions should handle unit conversion internally, based on the value of `grid._mesh` ("spherical" or "flat") | +
+ +
+The UnitConverter class is removed +
+
+Remove any UnitConverter usage from your code and Interpolation functions should handle unit conversion internally, based on the value of grid._mesh ("spherical" or "flat") +
+
+ +
From 27f10628537e115b4f8b392a58ffb4c6b82cf247 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 13 Jul 2026 10:36:05 +0200 Subject: [PATCH 5/6] Adding fieldset convert migration --- docs/user_guide/v4-migration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 855ce95c5..2fc1d6d80 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -181,6 +181,14 @@ Use pset.execute(parcels.AdvectionRK2) for advection
+
+FieldSet.from_<modelname>() is removed +
+
+Convert the model data first to SGrid (for example with a parcels.covert_<MODEL>_to_sgrid() function) and then use FieldSet.from_sgrid_conventions(), as also described in the Quickstart tutorial +
+
+
FieldSet.interp_method doesn't accept a string (e.g. "linear" or "nearest")
From 42fcf2df9f9912bdbf000552146bc878187ef3ee Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Tue, 14 Jul 2026 17:42:17 +0200 Subject: [PATCH 6/6] =?UTF-8?q?Adding=20=F0=9F=8E=93=20to=20v3=20to=20v4?= =?UTF-8?q?=20migration=20guide=20titles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For consistency with rest of docs --- docs/user_guide/index.md | 9 ++++++--- docs/user_guide/v4-migration.md | 2 +- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 6f2138de1..f982332f7 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -16,7 +16,7 @@ getting_started/installation.md ``` ```{note} -If you have code that uses Parcels v3, you can migrate to Parcels v4 using [this migration guide](v4-migration.md) +If you have code that uses Parcels v3, you can migrate to Parcels v4 using [🎓 the v3 to v4 migration guide](v4-migration.md) ``` ## Getting started @@ -125,9 +125,12 @@ examples/tutorial_interaction.ipynb +## Other + ```{toctree} -:hidden: :caption: Other -v3 to v4 migration guide +:name: other +:titlesonly: +🎓 v3 to v4 migration guide Example scripts ``` diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 2fc1d6d80..d62887ff4 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -2,7 +2,7 @@ html_theme.sidebar_secondary.remove: true --- -# Parcels v4 migration guide +# 🎓 Parcels v4 migration guide This migration guide gives some tips if you want to migrate your Parcels v3 code to Parcels v4. The biggest changes are in the [Kernel API](#kernels) and the way that [FieldSets are created](#fieldset). The other changes are mostly small and should be easy to fix.