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.


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.

Parcels v0.9 manuscript and code

The manuscript detailing this first release of Parcels, version 0.9, has been published in Geoscientific Model Development and can be cited as

Lange, M. and E van Sebille (2017) Parcels v0.9: prototyping a Lagrangian Ocean Analysis framework for the petascale age. Geoscientific Model Development, 10, 4175-4186. doi:10.5194/gmd-2017-167

The code is available at https://github.com/OceanParcels/parcels. Anyone is welcome to comment on the manuscript through the Geoscientific Model Development portal.

Parcels development status

The current release of Parcels, version 0.9, is 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

Major features

Experimental features

The features below are implemented, but not yet thoroughly tested. Please use with caution

  • Ability to run particles in any vertical coordinate system: z-level, sigma-level (terrain-following), or rho-level (density-following).

Future development goals

  • 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 on Linux and macOS

Parcels depends on a working Python installation, a netCDF installation, a C compiler, and various Python packages.

The simplest way to install Parcels is to use Anaconda and Conda-Forge for all requirements. This is the “batteries-included” solution probably suitable for most users. Note that if you already have an existing Python setup that you wish to use for Parcels, you should follow the instructions at the bottom of this section.

The five steps below are the installation instructions for Linux and macOS. Note that for Windows, steps 2 and 5 are slightly different, see Installing Parcels on Windows below.

  1. Install Anaconda’s Miniconda following the steps at https://conda.io/docs/user-guide/install/. All the code below assumes that you download the Python-2 version.

  2. Download Parcels’ environment.yml file, navigate to the directory where you saved that file, and run:

    source $HOME/miniconda2/bin/activate root
    conda env create -f environment.yml -n py2_parcels
    source $HOME/miniconda2/bin/activate py2_parcels
    pip install git+https://github.com/OceanParcels/parcels.git@master
  3. Validate the installation by downloading the example_peninsula.py file, navigate to the directory where you saved that file, and then run:

    python example_peninsula.py --fieldset 100 100
  4. Optionally, if you want to run all the examples and tutorials, you can get tutorials and example data by running:

    parcels_get_examples parcels_examples
    cd parcels_examples
    jupyter notebook
  5. The next time you start a terminal and want to work with Parcels, activate the environment with:

    source $HOME/miniconda2/bin/activate py2_parcels

An alternative, more advanced option is to use an existing netCDF installation and C compiler, git clone the master branch of Parcels and pip install the dependencies in the environment.yml file.

Installing Parcels on Windows

The installation process and usage of Parcels is much the same as under Installing Parcels on Linux and macOS above. However, steps 2 and 5 will be different, as detailed below:

  1. Download Parcels’ environment_win.yml file from the main Parcels’ directory, start the Anaconda Prompt from the Windows start menu, navigate to the directory where you saved that file, and then run:

    activate root
    conda env create -f environment_win.yml -n py2_parcels
    activate py2_parcels
    pip install git+https://github.com/OceanParcels/parcels.git@master
  1. The next time you start the Anaconda Prompt and want to work with Parcels, activate the environment with:

    activate py2_parcels

Getting involved

Parcels development is supported by Utrecht University and 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


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. the Adding-a-custom-behaviour-kernel 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

    • Simple print statements, such as:

      print("Some print")
      print("particle id: %d" % particle.id)
      print("lon: %f, lat: %f" % (particle.lon, particle.lat))
  • Local variables can be used in Kernels, and these variables will be accessible in all concatenated Kernels. Note that these local variables are not shared between particles, and also not between time steps.

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:


Indices and tables