What is OceanParcels?

The OceanParcels project develops Parcels (Probably A Really Computationally Efficient Lagrangian Simulator), a set of Python classes and methods to create customisable particle tracking simulations using output from Ocean Circulation models. Parcels can be used to track passive and active particulates such as water, plankton, plastic and fish.

The code from the OceanParcels project is licensed under an open source MIT license and can be downloaded from https://github.com/OceanParcels/parcels. The manuscript detailing this first release of Parcels, version 0.9, has been published in Geoscientific Model Development and can be cited as

As ocean general circulation models (OGCMs) move into the petascale age, where the output of single simulations exceeds petabytes of storage space, tools to analyse the output of these models will need to scale up too. Lagrangian ocean analysis, where virtual particles are tracked through hydrodynamic fields, is an increasingly popular way to analyse OGCM output, by mapping pathways and connectivity of biotic and abiotic particulates. However, the current software stack of Lagrangian ocean analysis codes is not dynamic enough to cope with the increasing complexity, scale and need for customization of use-cases. Furthermore, most community codes are developed for stand-alone use, making it a nontrivial task to integrate virtual particles at runtime of the OGCM. Here, we introduce the new Parcels code, which was designed from the ground up to be sufficiently scalable to cope with petascale computing. We highlight its API design that combines flexibility and customization with the ability to optimize for HPC workflows, following the paradigm of domain-specific languages. Parcels is primarily written in Python, utilizing the wide range of tools available in the scientific Python ecosystem, while generating low-level C code and using just-in-time compilation for performance-critical computation. We show a worked-out example of its API, and validate the accuracy of the code against seven idealized test cases. This version 0.9 of Parcels is focused on laying out the API, with future work concentrating on support for curvilinear grids, optimization, efficiency and at-runtime coupling with OGCMs.

Installing Parcels

The simplest way to install the Parcels code is to use Anaconda and the Parcels Conda-Forge package with the latest release of Parcels. This package will automatically install (almost) all the requirements for a fully functional installation of Parcels. This is the “batteries-included” solution probably suitable for most users.

The steps below are the installation instructions for Linux / macOS and for Windows. If the commands for Linux / macOS and Windows differ, this is indicated with a comment at the end of the line.

  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, although Parcels also works with Python-3. If you're on Linux / macOS, it also assumes that you installed Miniconda-2 to your home directory.
  2. Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the root (or base) environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, and the nice-to-have Jupyter and cartopy package:
    source $HOME/miniconda2/bin/activate root  # Linux / macOS
    activate root                              # Windows
    
    conda create -n py2_parcels -c conda-forge python=2.7 parcels jupyter cartopy
  3. Activate the newly created Parcels environment.
    source $HOME/miniconda2/bin/activate py2_parcels  # Linux / macOS
    activate py2_parcels                              # Windows
  4. Get a copy of the Parcels tutorials and examples, and run the simplest of the examples to validate that you have a working Parcels setup:
    parcels_get_examples parcels_examples
    cd parcels_examples
    
    python example_peninsula.py --fieldset 100 100
  5. *Note that if you are on macOS and get a compilation error, you may need to accept the Apple xcode license (xcode-select --install). If this does not solve the compilation error, you may want to try running export CC=gcc.

  6. Optionally, if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks:
    jupyter notebook
  7. The next time you start a terminal and want to work with Parcels, activate the environment with:
    source $HOME/miniconda2/bin/activate py2_parcels  # Linux / macOS
    activate py2_parcels                              # Windows

Installing a non-released version of Parcels

There might be cases where you want to install a version of Parcels that has not been released yet. (Perhaps, if you want to use a bleeding-edge feature which already is included on Github, but not in the conda-forge package.) Then, just after step 2 of Installing Parcels above, use the following commands to remove the conda-forge package again, and use pip to install Parcels from Github:
source $HOME/miniconda2/bin/activate py2_parcels  # Linux / macOS
activate py2_parcels                              # Windows

conda remove parcels
pip install git+https://github.com/OceanParcels/parcels.git@master
python setup.py install

Installation for developers

Parcels depends on a working Python installation, a netCDF installation, a C compiler, and various Python packages. If you prefer to maintain your own Python installation providing all this, git clone the master branch of Parcels and manually install all packages listed under dependencies in the environment files (environment_py2_linux.yml for Linux, environment_py2_osx.yml for OSX and environment_py2_win.yml for Windows), before running python setup.py install.

Parcels tutorials

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

Parcels tutorial

The Parcels tutorial provides an overview of the main features of Parcels and is therefore a good starting point for new users

Periodic boundaries tutorial

A tutorial to explain how to implement periodic (east-west or north-south) boundaries in Parcels

Curvilinear grid tutorial

A tutorial to explain how to use Parcels with hydrodynamic models that use curvilinear grids, such as NEMO

Delay start tutorial

A tutorial on how to release particles after the start of a run

SummedFields tutorial

A tutorial on how to combine different Fields for advection

Argo sampling Kernel tutorial

A tutorial on how to create a custom Kernel that mimics sampling of Argo floats

Plotting tutorial

A tutorial on how to plot particle trajectories


Parcels development status

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

Future development goals


Frequently Asked Questions and further support

See the FAQ page for further information on using and developing Parcels. This includes information on the Parcels design overview, tips on construction of FieldSet objects, support for writing custom Kernels and an explanation of the NetCDF output format.

There is also an extensive documentation of all methods and classes in Parcels.

Peer-reviewed articles using Parcels

The distribution of marine species is often modeled using Eulerian approaches, in which changes to population density or abundance are calculated at fixed locations in space. Conversely, Lagrangian, or individual-based, models simulate the movement of individual particles moving in continuous space, with broader-scale patterns such as distribution being an emergent property of many, potentially adaptive, individuals. These models offer advantages in examining dynamics across spatiotemporal scales and making comparisons with observations from individual-scale data.
Here, we introduce and describe such a model, the Individual-based Kinesis, Advection and Movement of Ocean ANimAls model (Ikamoana), which we use to replicate the movement processes of an existing Eulerian model for marine predators (the Spatial Ecosystem and Population Dynamics Model, SEAPODYM). Ikamoana simulates the movement of either individual or groups of animals by physical ocean currents, habitat- dependent stochastic movements (kinesis), and taxis movements representing active searching behaviours.
Applying our model to Pacific skipjack tuna (Katsuwonus pelamis), we show that it accurately replicates the evolution of density distribution simulated by SEAPODYM with low time-mean error and a spatial correlation of density that exceeds 0.96 at all times. We demonstrate how the Lagrangian approach permits easy tracking of individuals’ trajectories for examining connectivity between different regions, and show how the model can provide independent estimates of transfer rates between commonly used assessment regions. In particular, we find that retention rates in most assessment regions are considerably smaller (up to a factor of 2) than those estimated by this populations primary assessment model. Moreover, these rates are sensitive to ocean state (e.g. El Nino vs La Nina) and so assuming fixed transfer rates between regions may lead to spurious stock estimates. A novel feature of the Lagrangian approach is that individual schools can be tracked through time, and we demonstrate that movement between two assessment regions at broad temporal scales includes extended transits through other regions.
Finally, we discuss the utility of this modeling framework for the management of marine reserves, designing effective monitoring programmes, and exploring hypotheses regarding the behaviour of hard-to-observe oceanic animals.

In this study, we assess the accuracy of a combined geostrophic and Ekman current product (GlobCurrent) that estimates ocean currents at 15 m depth, by coupling it to a synthetic particle tracking tool and comparing the virtual trajectories to those of surface drifting buoys drogued at 15 m in the Greater Agulhas Current Region. The velocities from a total of 1,041 drifters are compared and evaluated to the synthetic particle-derived velocities for the period 1993–2015. On average the GlobCurrent underestimates the velocity in the Greater Agulhas Current by approximately 27%. The underestimation ranges from 4–64% in different regions, with the smallest error found in the Agulhas retroflection region, and the highest in the Benguela Upwelling System. Furthermore, we compare the time taken for the separation between the virtual and real drifters to reach 35 km. The mean separation time was found to be 78 hours, with the shortest time (35 hours) found in the Agulhas Current and the longest time (116 hours) located in the Agulhas Return Current. Deploying 10,000 virtual drifters in a 1degree x 1degree box within the southern Agulhas Current shows a convergence of trajectories towards the core of the current, while higher divergence is evident in the Agulhas retroflection. To evaluate the utility of this synthetic particle tracking tool coupled with GlobCurrent in open ocean search and rescue operations, two test cases are examined: (1) a capsized catamaran spotted south of Cape Recife and recovered 5 days later south of Cape Agulhas; and (2) a drifter trajectory in the same region. The comparison suggests that the GlobCurrent forced synthetic particle tracking tool is not appropriate for predicting the trajectory of a capsized catamaran that does not have the same drift characteristics as a surface drifting buoy drogued to 15 m.

Global surface transport in the ocean can be represented by using the observed trajectories of drifters to calculate probability distribution functions. The oceanographic applications of the Markov Chain approach to modelling include tracking of floating debris and water masses, globally and on yearly-to-centennial timescales. Here, we analyse the error inherent with mapping trajectories onto a grid and the consequences for ocean transport modelling and detection of accumulation structures. A sensitivity analysis of Markov Chain parameters is performed in an idealised Stommel gyre and western boundary current as well as with observed ocean drifters, complementing previous studies on widespread floating debris accumulation. Focusing on two key areas of inter-ocean exchange - the Agulhas System and the North Atlantic intergyre transport barrier - we assess the capacity of the Markov Chain methodology to detect surface connectivity and dynamic transport barriers. Finally, we extend the methodology's functionality to separate the geostrophic and non-geostrophic contributions to inter-ocean exchange in these key regions.

Lagrangian analysis is a powerful way to analyse the output of ocean circulation models and other ocean velocity data such as from altimetry. In the Lagrangian approach, large sets of virtual particles are integrated within the three-dimensional, time-evolving velocity fields. Over several decades, a variety of tools and methods for this purpose have emerged. Here, we review the state of the art in the field of Lagrangian analysis of ocean velocity data, starting from a fundamental kinematic framework and with a focus on large-scale open ocean applications. Beyond the use of explicit velocity fields, we consider the influence of unresolved physics and dynamics on particle trajectories. We comprehensively list and discuss the tools currently available for tracking virtual particles. We then showcase some of the innovative applications of trajectory data, and conclude with some open questions and an outlook. The overall goal of this review paper is to reconcile some of the different techniques and methods in Lagrangian ocean analysis, while recognising the rich diversity of codes that have and continue to emerge, and the challenges of the coming age of petascale computing.

As ocean general circulation models (OGCMs) move into the petascale age, where the output of single simulations exceeds petabytes of storage space, tools to analyse the output of these models will need to scale up too. Lagrangian ocean analysis, where virtual particles are tracked through hydrodynamic fields, is an increasingly popular way to analyse OGCM output, by mapping pathways and connectivity of biotic and abiotic particulates. However, the current software stack of Lagrangian ocean analysis codes is not dynamic enough to cope with the increasing complexity, scale and need for customization of use-cases. Furthermore, most community codes are developed for stand-alone use, making it a nontrivial task to integrate virtual particles at runtime of the OGCM. Here, we introduce the new Parcels code, which was designed from the ground up to be sufficiently scalable to cope with petascale computing. We highlight its API design that combines flexibility and customization with the ability to optimize for HPC workflows, following the paradigm of domain-specific languages. Parcels is primarily written in Python, utilizing the wide range of tools available in the scientific Python ecosystem, while generating low-level C code and using just-in-time compilation for performance-critical computation. We show a worked-out example of its API, and validate the accuracy of the code against seven idealized test cases. This version 0.9 of Parcels is focused on laying out the API, with future work concentrating on support for curvilinear grids, optimization, efficiency and at-runtime coupling with OGCMs.

Parcels funding and support

Parcels development has been supported by the following organisations: