parcels

Submodules

• parcels.convert
• parcels.interpolators
• parcels.kernels
• parcels.tutorial

Attributes

Particle	The default Particle used in Parcels simulations.
AllParcelsErrorCodes
logger

Exceptions

FieldInterpolationError	Utility error class to propagate NaN field interpolation.
FieldOutOfBoundError	Utility error class to propagate out-of-bound field sampling.
FieldSamplingError	Utility error class to propagate field sampling errors.
KernelError	General particles kernel error with optional custom message.
OutsideTimeInterval	Utility error class to propagate erroneous time extrapolation sampling.
FieldSetWarning	Warning that is raised when there are issues in the construction of the FieldSet or its Grid.
FileWarning	Warning that is raised when there are issues with input or output files.
KernelWarning	Warning that is raised when there are issues with the Kernel.
ParticleSetWarning	Warning that is raised when there are issues in the construction of the ParticleSet.
FieldEvalWarning	Warning that is raised when there are issues during the evaluation of a Field.
KernelValidationError	Raised when a kernel function has errors that make it incompatible with Parcels v4.

Classes

FieldSet	FieldSet class that holds hydrodynamic data needed to execute particles.
ParticleSet	Class for storing particles and executing kernel over them.
ParticleFile	Initialise trajectory output.
Variable	Descriptor class that delegates data access to particle data.
ParticleClass	Define a class of particles. This is used to generate the particle data which is then used in the simulation.
Field	The Field class that holds scalar field data.
VectorField	VectorField class that holds vector field data needed to execute particles.
BaseGrid	Base class for parcels.XGrid and parcels.UxGrid defining common methods and properties
UxGrid	Extension of uxarray's Grid class that supports point-location search
XGrid	Class to represent a structured grid in Parcels.
SphericalMesh	Spherical mesh object with configurable planetary radius.
StatusCode	Class defining the status codes for particles.state.

Functions

open_raw_zarr(store)	Open a Zarr dataset in an Xarray dataset, bypassing Dask.
read_particlefile(path[, decode_times])	Read a Parcels particlefile (Parquet format) into a pandas DataFrame.
particlefile_to_v3_zarr(from_parquet, to_zarr)	Convert a v4 particle file (parquet) to v3-style zarr output.
validate_kernel(func)	Decorator that validates a Parcels v4 kernel function.

Package Contents

parcels.open_raw_zarr(store)

Open a Zarr dataset in an Xarray dataset, bypassing Dask.

parcels.read_particlefile(path, decode_times=True)

Read a Parcels particlefile (Parquet format) into a pandas DataFrame.

Parameters:

• path (PathLike) – Path to the .parquet particlefile.

• decode_times (bool, optional) – If True (default), use Xarray to decode the numeric t column from CF conventions into datetime or cftime.datetime values using the units stored in the column metadata. If False, the raw numeric values are returned unchanged.

Returns:

DataFrame containing the particle data. When decode_times is True, the t column contains datetime-like values; otherwise it contains the original numeric representation.

Return type:

pd.DataFrame

Notes

For larger datasets, consider using Polars directly, e.g. polars.read_parquet(path), which offers better performance and lower memory usage than pandas for large Parquet files.

parcels.particlefile_to_v3_zarr(from_parquet, to_zarr)

Convert a v4 particle file (parquet) to v3-style zarr output.

Reads the parquet file, renames columns to v3 conventions (particle_id -> trajectory, t -> time, x -> lon, y -> lat), and reshapes the data into a 2D (trajectory, obs) zarr store.

Parameters:

• from_parquet (Path) – Path to the input parquet file.

• to_zarr (Path) – Path to the output zarr store. Must have a .zarr suffix.

Raises:

ValueError – If to_zarr does not have a .zarr suffix.

Notes

This is not a lazy operation — the entire parquet file is read into memory and pivoted before writing to zarr. For large particle files this may require significant memory. Performance improvements are welcome via PRs.

parcels.Particle

The default Particle used in Parcels simulations.

parcels.AllParcelsErrorCodes: dict[type[Exception], int]

parcels.validate_kernel(func)

Decorator that validates a Parcels v4 kernel function.

Errors (raises KernelValidationError): - Kernel signature is not def ...(particles, fieldset) - particle.delete() or particles.delete() calls

Warning

• References to deprecated particle.lon, .lat, .depth (use .x, .y, .z)

• References to deprecated particle_dlon, particle_dlat, particle_ddepth

• Direct assignment to particle location attributes (x/y/z/lon/lat/depth)

• Sampling particle.ei (ordering concern)

parcels.logger