Welcome to Parcels

Parcels (Probably A Really Computationally Efficient Lagrangian Simulator) is an experimental prototype code aimed at exploring novel approaches for Lagrangian tracking of virtual ocean particles in the petascale age.

Its code is licensed under an open source MIT license and can be downloaded from https://github.com/OceanPARCELS/parcels.

http://oceanparcels.org/animated-gifs/globcurrent_fullyseeded.gif

Animation of virtual particles carried by ocean surface flow in the Agulhas Current off South Africa. The particles are advected with Parcels in data from the GlobCurrent Project. See this tutorial for the Parcels code behind this animated gif.

Postdoc and PhD positions available in Parcels development

Through the “Tracking Of Plastic In Our Seas”, funded by the European Research Council, we are currently advertising two positions to further develop and work with Parcels. Application deadline for both positions is 14 April 2017.

We are looking for a postdoc with very strong programming skills to further develop the Parcels framework, and help apply it to the dispersion of plastic in the ocean. See here for a more detailed description.

We are looking for a PhD candidate to develop code and parameterisations to make the particles from the Parcels framework behave like plastic. See here for a more detailed description. de

Parcels development status

Parcels is currently close to what we will release at version 0.9. This v0.9 will be a fully-functional, feature-complete code for offline Lagrangian ocean analysis. See below for a list of features, or keep an eye on the Github Development Timeline page

Currently implemented

Major developed goals beyond v0.9

  • Diffusion of particles using suite of inbuilt kernels
  • Support for non-rectangular grids, including unstructured meshes
  • Implementation of parallel execution using tiling of the domain
  • Faster and more efficient code
  • Advanced control of particles near land boundaries

Parcels Tutorials

The best way to get started with Parcels is to have a look at the Jupyter notebooks below:

Installing Parcels

The latest version of Parcels, including tests and examples, can be obtained directly from github via:

git clone https://github.com/OceanPARCELS/parcels.git
cd parcels; pip install -r requirements.txt
python scripts/pull_data.py
export PYTHONPATH="$PYTHONPATH:$PWD"

In order for Parcels to work from any directory, add the following line to your ~/.bash_profile:

export PYTHONPATH="$PYTHONPATH:$PWD"

Note that a functional NetCDF install is required.

Getting involved

Parcels development is supported by Imperial College London, with contributions from the people listed on the Contributors page.

If you want to help out with developing, testing or get involved in another way, please join the mailing list.

Python design overview

_images/ParcelsDesign.png

The figure above gives a brief overview of how the most important classes and methods in Parcels are related.

See below for links to the full documentation of the python code for Parcels

Writing Parcels Kernels

One of the most powerful features of Parcels is the ability to write custom Kernels (see e.g. this part of the Tutorial). These Kernels are little snippets of code that get executed by Parcels, giving the ability to add ‘behaviour’ to particles.

However, there are some key limitations to the Kernels that everyone who wants to write their own should be aware of:

  • Every Kernel must be a function with the following (and only those) arguments: (particle, fieldset, time, dt)

  • In order to run successfully in JIT mode, Kernel definitions can only contain the following types of commands:

    • Basic arithmetical operators (+, -, *, /) and assignments (=).

    • Basic logical operators (<, ==, >, &, |)

    • if and while loops, as well as break statements. Note that for-loops are not supported in JIT mode

    • Interpolation of a Field from the fieldset at a (time, lon, lat, depth) point, using using square brackets notation. For example, to interpolate the zonal velocity (U) field at the particle location, use the following statement:

      value = fieldset.U[time, particle.lon, particle.lat, particle.depth]
      
    • Functions from the maths standard library and from the custom random library at parcels.rng

    • print statements. Note however that in JIT mode these only work well for variables that are either floats or any of the inbuilt Particle properties

All other functions and methods are not supported yet in Parcels Kernels. If there is a functionality that can not be programmed with this limited set of commands, please create an Issue ticket.

Parcels funding and support

Parcels development has been supported by the following organisations:

_images/funderlogos.png

Indices and tables