Skip to content

Update migration guide #2742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
erikvansebille wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Update migration guide #2742

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e755e98
Update migration guide to a tabular format format
erikvansebille Jul 10, 2026
19e4281
Update v4-migration.md
erikvansebille Jul 10, 2026
f45414a
Removing column with numbering
erikvansebille Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/user_guide/examples/tutorial_delaystart.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
{
Expand Down
91 changes: 54 additions & 37 deletions docs/user_guide/v4-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,80 @@
---
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 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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

@erikvansebille erikvansebille Jul 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will also need to add information here on the sgrid conventions and the workflow xr.open_dataset -> convert to Sgrid compliant -> create 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 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `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

- `Particle.add_variables()` has been replaced by `Particle.add_variable()`, which now 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

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

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

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

- `GridSet` is now a list, so 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

- 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 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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") |