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.
Parcels 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 latest version of the code is available at https://github.com/OceanParcels/parcels.
Parcels development status¶
The current release of Parcels, version 1.0, 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
- Advection of particles in 2D using inbuilt kernels for Runge-Kutta4, Runge-Kutta45 and Euler Forward and in 3D using the inbuilt kernel for Runge-Kutta4_3D (see
- Simple horizontal diffusion of particles using inbuilt Brownian Motion kernel (see
- Ability to define and execute custom kernels (see the Adding-a-custom-behaviour-kernel part of the Tutorial)
- Ability to add custom Variables to Particles (see the Sampling-a-Field-with-Particles part of the Tutorial)
- Ability to add and remove Particles (see
- Ability to run in both Scipy and JIT (Just-In-Time compilation) mode. The former is easier to debug, but the latter can be a factor 1,000 faster (see the JIT-vs-Scipy tutorial)
- Ability to read in hydrodynamic field in NetCDF format from a suite of models (see the Reading-in-data-from-arbritrary-NetCDF-files part of the Tutorial). Parcels currently supports Rectilinear and Curvilinear grids in the horizontal (see also the NEMO curvilinear grids tutorial).
- Output particles in NetCDF format (see
- Basic plotting of particles, both on the fly and from netcdf output files (see the plotting tutorial)
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
- More types of diffusion of particles using suite of inbuilt kernels
- Support for unstructured grids
- Implementation of parallel execution using tiling of the domain
- Faster and more efficient code
- Advanced control of particles near land boundaries
The best way to get started with Parcels is to have a look at the Jupyter notebooks below:
- Parcels tutorial for a general introduction and overview into the main features of Parcels
- Periodic boundaries tutorial for a tutorial on how to implement periodic boundary conditions
- NEMO curvilinear grids tutorial for a tutorial on how to run Parcels on curvilinear grids such as those of the NEMO models
- FieldSet.advancetime() tutorial for a tutorial on how to use Parcels with datasets that have a large number of time snapshots.
- Delayed start of particles tutorial for a tutorial on how to add particles to a ParticleSet during runtime, so that not all particles are released on the start of the run.
- JIT-vs-Scipy tutorial for a tutorial showing how JIT and Scipy mode compare.
- Argo float tutorial for a tutorial on how to write a Kernel that mimics the vertical movement of Argo floats
- Animated Gif tutorial for a tutorial on how to created the Agulhas region animated gif on the top of this page. This tutorial also features a brief explanation of how to handle OutOfBounds errors.
- Plotting tutorial for further explanation on the plotting capabilities of Parcels
This is the “batteries-included” solution probably suitable for most users.
The simplest way to install Parcels 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 installaion of Parcels.
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.
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.
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 Basemap package:
source $HOME/miniconda2/bin/activate root # Linux / macOS activate root # Windows conda create -n py2_parcels -c conda-forge parcels jupyter basemap basemap-data-hires
Activate the newly created Parcels environment, get a copy of the the Parcels tutorials and examples, and run the simplest of the examples to validate that you have a working Parcels setup:
source $HOME/miniconda2/bin/activate py2_parcels # Linux / macOS activate py2_parcels # Windows parcels_get_examples parcels_examples cd parcels_examples python example_peninsula.py --fieldset 100 100
Optionally, if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks:
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, 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
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
pip install all packages lister under
dependencies in the environment files
Then, install Parcels in an editable way by running:
pip install -e .
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¶
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 (
whileloops, as well as
breakstatements. Note that
for-loops are not supported in JIT mode
Interpolation of a
fieldsetat 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
mathsstandard library and from the custom
print("Some print") print(particle.lon) 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.
Note that one has to be careful with writing kernels for vector fields on Curvilinear grids. While Parcels automatically rotates the U and V field when necessary, this is not the case for for example wind data. In that case, one will have to write their own rotation function.
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.
The following peer-reviewed articles have used Parcels
- McAdam R and E van Sebille (2018) Surface connectivity and inter-ocean exchanges from drifter-based transition matrices. Journal of Geophysical Research, in press. doi:10.1002/2017JC013363
- van Sebille, E, SM Griffies, R Abernathey, TP Adams, P Berloff, A Biastoch, B Blanke, EP Chassignet, Y Cheng, CJ Cotter, E Deleersnijder, K Döös, HF Drake, S Drijfhout, SF Gary, AW Heemink, J Kjellsson, IM Koszalka, M Lange, C Lique, GA MacGilchrist, R Marsh, CG Mayorga Adame, R McAdam, F Nencioli, CB Paris, MD Piggott, JA Polton, S Rühs, SHAM Shah, MD Thomas, J Wang, PJ Wolfram, L Zanna, and JD Zika (2018) Lagrangian ocean analysis: fundamentals and practices. Ocean Modelling, 121, 49-75. doi:10.1016/j.ocemod.2017.11.008
- 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
Parcels funding and support¶
Parcels development has been supported by the following organisations:
- The European Research Council under the H2020 Starting Grant TOPIOS (grant agreement No 715386).
- Imperial College London and specifically the Grantham Institute.
- Utrecht University and specifically the Institute for Marine and Atmospheric Research.
- The EPSRC through an Institutional Sponsorship grant to Erik van Sebille under reference number EP/N50869X/1.
See below for the technical documentation on the different Parcels modules
- Parcels documentation
- parcels.particleset module
- parcels.fieldset module
- parcels.field module
- parcels.gridset module
- parcels.grid module
- parcels.particle module
- parcels.kernels.advection module
- parcels.kernels.error module
- parcels.codegenerator module
- parcels.compiler module
- parcels.kernel module
- parcels.particlefile module
- parcels.rng module
- parcels.loggers module
- scripts.plotParticles module
- scripts.get_examples module