Fixed vertical positioning

In some studies, it is useful to be able to fix the vertical position of particles in the water column. Examples include the simulation of buoyant particles (for example, certain types of marine plastic pollution) that sit on the ocean’s surface, ocean drifters that sit a fixed depth below the ocean’s surface, or larvae that reside close to the sea floor. In this notebook, we demonstrate how to fix the vertical position of particles in the water column when performing PyLag particle tracking simulations.

PyLag configuration options

Controlling a particle’s vertical position

In PyLag, particles have four attributes that can be used to control their vertical position:

  • restore_to_fixed_depth - If this attribute is set to True, the particle will be restored to a fixed depth below the ocean’s surface.

  • fixed_depth - The depth below the ocean’s surface to which the particle will be restored if restore_to_fixed_depth is True.

  • restore_to_fixed_height - If this attribute is set to True, the particle will be restored to a fixed height above the ocean’s floor.

  • fixed_height - The height above the ocean’s floor to which the particle will be restored if restore_to_fixed_height is True.

The parameters are set in PyLag’s run configuration file, in the section titled SIMULATION:

[SIMULATION]

# Keep particles at a fixed depth below the surface by restoring to a fixed depth each time step
depth_restoring = True

# The fixed depth below the surface that particles are held at if `depth_restoring' is True. A value
# 0f 0.0 corresponds to the sea surface; a value of -1.0 to 1 m below the free surface.
fixed_depth = 0.0

# Keep particles at a fixed height above the ocean floor by restoring to a fixed height each time step
fixed_height = False

# The fixed height above the ocean floor that particles are held at if `fixed_height' is True. A value
# of 0.0 corresponds to the ocean floor; a value of 1.0 to 1 m above the ocean floor.
fixed_height = 0.0

Note: The options restore_to_fixed_depth and restore_to_fixed_height are mutually exclusive; PyLag will raise a runtime exception if both are set to True.

Surface only simulations

In some situations, one may only have access surface fields. For example, those derived from satellite observations of sea surface height. Or, if doing surface only simulations with 3D velocity fields, one may wish to save on time by not reading in the full velocity field which takes time to read in and process. In these cases, there is a second option for controlling the vertical position of particles, which involves the configuration option surface_only. If this option is set to True, PyLag will only read in the surface fields from the input files, and will not read in the full 3D velocity field (if it is available). This can save a significant amount of time when reading in large velocity fields. The parameters is set in PyLag’s run configuration file, in the section titled SIMULATION:

[SIMULATION]

# Flag for surface only transport. If set to True, PyLag will only read
# surface fields. In this case, initial vertical positions should be
# set to 0.0 m below the free surface. Depth and height restoring should
# be set to False for efficiency reasons.
surface_only = False

As specified in the comment, depth and height restoring should be set to False if surface_only is set to True.