Frequently Asked Questions (FAQ)

This page lists a few common-occurring user questions in relation to Parcels. This includes questions on pre-processing, file handling, fieldsets, kernels and kernel functions, post-processing, plotting and data reuse. For each questions, we provide a short answer and a list to the related code snipped (here in this repository) or example and tutorial (in the main Parcels page) that answers the questions and demonstrates in code how to approach the problem.

Pre-Processing

• How can I convert irregular-gridded fields (e.g. curvilinear grids) into regular-gridded fields (e.g. A-grid) ?

  The basic idea to do it is either to use `scipy.spatial` and SciPy's nD-interpolation routines, or to use parcels.

  The Parcel's way is similar to field sampling on the webpage. More extensive examples to do this, and also doing this with SciPy, are soon gonna come.

• How can I calculate the distance to land cells (i.e. distance to coastline) ?

  Here is a Python example to compute distance to land.

FieldSets

• How can I use fieldsets outside the pre-defined norm (i.e. CMEMS, NEMO or POP) ?
• How can I create and use my own matrix data as fields ?
• How can I use GIS products (e.g. river data; country indicators; 5-mile zones) in Parcels ?
• How can I get a mask of coastal cells from hydrodynamic data ?
• How can I enable the automatic use of Dask's chunking and dynamic loading for FieldSets in Parcels ?

ParticleSet

• How can I release x particles per field-input grid cell ?

• How can I periodically release M particles in a particle set with initially N particles ?

• (How) can I dynamically add particles during runtime ?

  There are different use cases. First, there is in Parcels the built-in possibility to (re-)release the initially-created particles of a particle set anew. This is controlled by the releasedt parameter in Fieldset.execute(...). This method is an unconditional release, purely based on a periodic timer, and releases all particles initially created again. A tutorial is found on the oceanparcels website for delayed particle release.

  In order to steer the release of particles, one needs to perform the time integration and release of particles outside the Particles.execute(...) loop. A code example on it is provided by Victor Onink in the parcels_contributions repository.

Kernels

• How can I add uniform diffusion (simple Brownian motion) to any Parcels simulation ?

  Parcels has a built-in `DiffusionUniformKh` kernel for this. To use it, you must first add the uniform horizontal diffusivities to your fieldset:

  fieldset.add_constant_field("Kh_zonal", 1, mesh="flat")
  fieldset.add_constant_field("Kh_meridional", 1, mesh="flat")

  Make sure to set mesh to "flat" or "spherical" depending on your setup. The value should be given in m^2/s, as Parcels automatically takes care of unit conversion. In practice, Kh_meridional and Kh_zonal are often equal, but they are passed separately as this is not always the case.

  You can add the DiffusionUniformKh on top of one of the advection kernels, such as AdvectionRK4 by chaining the kernels together using the + operator.

  Parcels also supports spatially varying diffusivities. In that case, more complicated Kernels should be used. See the diffusion tutorial for more information.

• How do I set up spatially varying diffusion ?

  In the case that you have spatially varying diffusivities as model output, you can use advection-diffusion kernels that take this into account. We support the Euler-Maruyama and first order Milstein (Milstein-1) advection-diffusion schemes. Information on how to use these is found in the diffusion tutorial.

  In brief, you can load in your diffusivity fields as regular parcels Fields, and use the AdvectionDiffusionEM and AdvectionDiffusionM1 kernels. These kernels include both (Euler-like) advection and diffusion. Gradients in the diffusivity field are taken into account.

Post-Processing

• How can I read the Parcels trajectory output outside Parcels, in Python ?

  A basic tutorial of loading and analyzing Parcels output with Python (using xarray or netCDF4) is available here

• What's the structure and meaning of all the trajectory entries in a Parcels output file ?

  An explanation of the structure of the trajectory entries can be found in this tutorial.

• How can I (efficiently) bin my continuous trajectory data in discrete cells ?

• How can I calculate the histogram of a single flow variable (i.e. trajectory attribute) ?

• How can I calculate the joint histogram of two independent variables ?

• How can I simply interpolate non-gridded trajectory data on a target regular grid ?

• How can I reinterpolate regular-gridded fields on new grids with common Python packages ?

  A snipped illustrates how to efficiently re-interpolate field data using SciPy, NumPy etc. without the need for a full-scale particle-based resample, which is more time consuming for those simple use cases.

• How can I use Parcels to convert a curvilinear hydrodynamic field into a regular-gridded field ?

  A snippet of how Parcels can be used to fully resample an arbitrarily (i.e. A/B/C-)gridded hydrodynamic model into a regular-rectangular gridded model (i.e. A-grid) is located as a snippet in the parcels_contributions repository.

Plotting

• How can I plot the positions of certain particles with a landmass-bound visual context ?
• Where can I find inspiration on hydrodynamic visualisation and plotting scripts ?
• (How) can I visualize Parcels trajectories in GIS software packages ?
• (How) can I visualize Parcels trajectories other Python packages (e.g. Plotly) ?
• (How) can I visualize Parcels trajectories in ParaView ?

External Parcels Usage

• (How) can I use Parcels trajectory data outside of Parcels ?
• (How) can I use Parcels trajectories in e.g. scikits-learn ?
• (How) can I use Parcels trajectories in deep learning ?

Parallelization & High-Performance Computing (HPC)

(to come)