repository·main·Indexed 43 days ago
https://github.com/parcels-code/parcelsA Python-based framework for Lagrangian tracking of virtual ocean particles. Parcels simulates the movement of passive and active particulates, such as water, plankton, plastic, and fish, using gridded output from ocean circulation models.
Parcels is a Python framework designed for creating customizable particle tracking simulations. It uses gridded output from (ocean) circulation models to track both passive and active particulates, such as water, plankton, plastic, and fish.
Key features include:
Parcels is a Python-based framework designed for creating customizable particle tracking simulations. It uses gridded output from (ocean) circulation models to advect particles. It is suitable for tracking both passive and active particulates, including:
The index search process used for field interpolation follows a two-stage optimization to minimize expensive hash table lookups:
yi, xi) is available from the previous time step, the system first attempts curvilinear_point_in_cell at those indices. If the particle hasn't moved enough to leave its cell, it is resolved immediately.grid.get_spatial_hash().query(y, x).The SpatialHash object is lazily constructed on its first call and is cached on the grid object for subsequent use.
This pattern ensures high performance for particles that remain in the same cell between time steps.
parcels._core.index_search._search_indices_curvilinear_2dWhen you call pset.execute(), Parcels enters a Kernel loop that iterates through time and executes the provided list of Kernels for all particles.
To ensure that multiple Kernels (e.g., combining currents and winds) are commutable—meaning the order of execution does not change the final displacement—Parcels does not update particle positions (particles.x, particles.y, particles.z) directly within the Kernels. Instead, Kernels must update a displacement variable (particles.dx, particles.dy, particles.dz).
The Kernel loop lifecycle:
particles.dx = 0 (and similarly for dy, dz).particles.x += particles.dx.
b. Update time: particles.t += particles.dt.
c. Reset displacement: particles.dx = 0.
d. For each Kernel in the list:
i. Execute the Kernel.
ii. Accumulate the change: particles.dx += change_in_x.
e. If the output interval is met, write the current state to the output file.This mechanism ensures that field sampling (e.g., fieldset.Var[particles.t, particles.z, particles.y, particles.x]) uses a consistent particle location throughout the entire loop and matches the location recorded in the output files.
Parcels uses Intended Effort Versioning (EffVer), which follows a MACRO.MESO.MICRO format. This scheme communicates the level of effort required for you to upgrade to a new version:
When backward incompatible changes occur, Parcels will provide instructions via changelogs, migration guides, or informative error messages.
A Parcels simulation is built using four core components that work together in a specific lifecycle:
FieldSet. Each particle must have initial values for t (time), z (depth), y (latitude), and x (longitude).ParticleFile.Morton encoding converts 3-D floating-point coordinates into a single unsigned 32-bit integer that preserves spatial locality. This is implemented in src/parcels/_core/spatialhash.py through three steps:
quantize_coordinates): Maps each axis from its range [min, max] to an integer in [0, bitwidth]. The default bitwidth is 1023 (10 bits per axis), allowing 3 axes to fit into a 30-bit uint32._dilate_bits): Spreads the 10 bits of each integer so that there are two zero bits between each active bit. This prepares the bits for interleaving._encode_quantized_morton3d): Combines the three dilated axes by OR-ing them together. The resulting bit layout follows the pattern: x0, y0, z0, x1, y1, z1, ..., x9, y9, z9.The combined function _encode_morton3d performs all three steps during queries.
Interpolation is used to evaluate the state of particles within an environmental field (e.g., temperature or velocity) at their specific real-time and spatial positions (t, z, y, x).
In Parcels, you can evaluate a field at particle positions using square bracket notation. This is a shorthand that provides the grid search algorithm with the particles' current positions as a 'first guess' for element indices, making the operation efficient.
If you need to sample at locations or times that are not necessarily close to the particles' current positions, you can pass specific coordinates, but note that this may be slower for curvilinear or unstructured grids as it requires a full grid search.
# Efficiently evaluate field at particle positions
particles.temperature = fieldset.temperature[particles]
# Shorthand for:
# particles.temperature = fieldset.temperature[particles.t, particles.z, particles.y, particles.x, particles]
# Sample at arbitrary locations (potentially slower for complex grids)
particles.temperature = fieldset.temperature[t, z, y, x]When writing custom Kernels, do not update particles.x, particles.y, or particles.z directly. Doing so will interfere with the Kernel loop and trigger a warning.
Instead, calculate the intended change in position and add it to the particles.dx, particles.dy, or particles.dz variables. This allows Parcels to sum the displacements from all Kernels before applying them to the actual particle coordinates, ensuring the simulation remains order-independent (commutable).
def my_custom_kernel(particles, fieldset):
# Do NOT do: particles.x += 10
# DO: update the displacement variable
particles.dx += 10Parcels uses a StatusCode system to capture and manage errors during the Kernel loop. When an error occurs (such as a Field Interpolation error or a FieldOutOfBoundSurfaceError), the particles.state attribute is updated to a specific status code.
Developers can write custom Kernels that inspect particles.state to handle these errors programmatically. Common workflows include:
particles.state = parcels.StatusCode.Delete for particles in an error state.z, dx, or dy) to resolve the error and then resetting the state to parcels.StatusCode.Evaluate so the simulation can continue.Important: Kernels that manage particles.state should typically be placed at the end of the kernel list passed to pset.execute() to prevent subsequent kernels from overwriting the state or particle displacements.
import parcels
# Inspect available status codes
for statuscode, val in parcels.StatusCode.__dict__.items():
if statuscode.startswith("__"):
continue
print(f"{statuscode} = {val}")When using SpatialHash for index searching, be aware of the following design characteristics: