Features

Main Features

• Ability to calculate tracks of millions of particles in hours in unstructured grids.

• Reads hydrodynamic model output from Schism, FVCOM, plus support for ROMS structured grid output.

• Calculate particle statistics one the fly, eliminating need to store and wade though large volumes of particle track output.

• Flexible parameter file driven particle tracking,

• Computational pipeline built fom given parameters, eg. add particle properties, add to modifies particle trajectories, calculates statistics etc, to the pipe line.

• Flexible particle releases, from multiple points or polygons.

• Forwards and backwards in time particle tracking.

• Run multiple cases in parallel, to reduce run time.

• Post run plotting and animation.

• Flexible python code, with key computational code using Numba, running at C code speeds.

Useful Features

• Numerics

  • Fast native grid particle tracking for both S-layer,plus and Schism’s LSC vertical grids

  • Loglayer vertical interpolation of water velocity for particles in bottom layer, giving more realistic behaviour, eg. resuspension.

  • Linear horizontal interpolation within triangles, and depth cell except for velocity in bottom cell.

• Particle behaviour

  • Resuspension from the bottom based on critical friction velocity.

  • Shoreline stranding/re-floating of particles by the tide based on dry cells.

  • “InPolygon” particle property which notes which of a set of polygons they lies within. Useful for polygon based statistics and changing behaviour inside polygons.

  • Split particles, to give two child particles at given frequency and probability

• Particle release

  • add multiple “release_groups”, particles release at same locations and times

  • set different release time, dates, duration for release, plus maximum age.

  • choose whether to release particles in cells which are dry due to the tide

  • release depth can be random within water column, or given depth range.

  • random release with arbitrary polygons, in areas which dont overlap land.

• Computational-pipeline abstraction

  • Abstracts the details of working with vectors, 2D or 3D variables away from user

  • add multiple velocity modifiers, trajectory modifiers to the pipeline

  • dead particles culled from computation and particle buffers, speeding run, eg. those older than given maximum age.

• Output

  • netCDF files, with json files containing other useful information

  • calculation of on-the-fly statistics as gridded heat maps or polygon connectivity writen to netcdf. Separate statistics for each release group.

  • track plotting and animation code

  • events class output, which only writes output when events occur, eg. a particle entering or exiting given polygons

• Internal automation

  • Automatically interpolates user fields named by the user to the particle locations, and writes this particle property to the output file.

  • Splits quad cells into triangles on the fly

  • automates management of particle property buffers, expanding as more are released, culling from computation when there are significant numbers of dead particles

  • Reads netcdf hydrodynamic model output detecting format at automatically determining whether 2D or 3D

  • Flexible reader with user configurable mapping file variable names to consistent internal variable names.

  • Sorts all hindcast files found in a dir and its sub-dirs into time order, based on time variable in the file. Avoiding need to use file name structure to load files in date order.

  • Internal buffers for particle properties automatically expand as more particles are released needed.

• Other

  • If no particles active, will freerun until some are released, allows particles to be released for one season per year, with a max age, and run will skip between years

Architecture

• Fully driven by parameters in JSON/YAML file or in code from dictionary

• Highly flexible architecture enabling:

  • user implemented approaches to core classes, core classes can be replaced via string name in parameter dictionary, eg. user spatial interpolator

  • adding user developed:

    • custom particle properties derived from other properties though inheritance

    • augment particle velocity given by water_velocity read from hindcast, eg. particle fall velocity

    • modify particle trajectories, eg. resuspension.

• Automated processes to add user developed particle proprieties, velocity, trajectory modifiers, etc , to calculation and output chain. Eg Requesting a file variable “temperature” from hindcast file by adding to the readers “field_variables” list, will automatically:

  • create a feild of this name

  • interpolate this field to the particle locations at each time step

  • write this particle property to the output file along with the particle location etc.

• All core and optional classes can be changed or added to list as parameter string using class_name as a string, eg optional particle distance travelled property.

• Reduce memory requirement in ‘compact_mode’, which only retains active particles, eg. those young enough to be of interest.

• Written in python with numba package for fast in-place operations on particle properties and hindcast’s fields based on set of indices arrays.