Boundary conditions

During a simulation some particles will inevitably come into contact with a model boundary. There are several different types of boundary, including the sea surface and sea floor boundaries; land boundaries; and open boundaries, for regional or local model domains. It is desirable to have a high level of flexibility with respect to how particles behave near to and at model boundaries, in both the vertical and horizontal dimensions. To this end, PyLag includes two abstract base classes: one for handling particle dynamics at vertical boundaries, called VertBoundaryConditionCalculator, and one for handling particle dynamics at horizontal boundaries, called HorizBoundaryConditionCalculator. Together, these facilitate running the model with different types of boundary condition, depending on the type of particle being simulated and the nature of the experiment being run. The two abstract base classes also facilitate extending the model to new problem classes.

Vertical boundary condition calculators

Currently, PyLag includes the following vertical boundary condition calculators:

  1. RefVertBoundaryConditionCalculator - particles are reflected back into the model domain when they cross either a surface or bottom boundary.

  2. AbsBotVertBoundaryConditionCalculator - particles are reflected back into the model domain when they cross the surface boundary, but are absorbed into the sediments if they cross the bottom boundary, resulting in them being removed from the domain.

The choice of vertical boundary condition to run with is made in the run configuration file using the option vert_bound_cond:

[BOUNDARY_CONDITIONS]

vert_bound_cond = reflecting

The above setting would result in a run that uses a reflecting boundary condition at the surface and bottom. The second type of boundary condition can be selected using the configuration setting absorbing_bottom.

Horizontal boundary condition calculators

Currently, PyLag includes the following horizontal boundary condition calculators:

  1. RefHorizCartesianBoundaryConditionCalculator - particles are reflected back into the model domain when they cross a land boundary. A particle is flagged as having left the domain when it crosses an open boundary. This type of calculator is instantiated when the model is run using inputs defined on a Cartesian grid.

  2. RefHorizGeographicBoundaryConditionCalculator - particles are reflected back into the model domain when they cross a land boundary. A particle is flagged as having left the domain when it crosses an open boundary. This type of calculator is instantiated when the model is run using inputs defined on a Geographic latitude-longitude grid.

  3. RestoringHorizCartesianBoundaryConditionCalculator - the particle’s position is restored to its last known valid position inside the model domain when it crosses a land boundary. A particle is flagged as having left the domain when it crosses an open boundary. This type of calculator is instantiated when the model is run using inputs defined on a Cartesian grid.

  4. RestoringHorizGeographicBoundaryConditionCalculator - the particle’s position is restored to its last known valid position inside the model domain when it crosses a land boundary. A particle is flagged as having left the domain when it crosses an open boundary. This type of calculator is instantiated when the model is run using inputs defined on a Geographic latitude-longitude grid.

The choice of horizontal boundary condition to run with is made in the run configuration file using the option horiz_bound_cond:

[BOUNDARY_CONDITIONS]

horiz_bound_cond = reflecting

The above setting would result in a run that uses a reflecting horizontal boundary condition, whereby particles are reflected back into the model domain should they cross a land boundary. A restoring horizontal boundary condition calculator can be selected using the configuration setting restoring. Note it is not necessary to specify the type or coordiante system used when selecting a horizontal boundary condition calculator. The selection is guided by the configuration setting coordinate_system, in the configuration section SIMULATION, which can take a value of either cartesian or geographic

Developing PyLag: Adding new boundary condition calculators

The process of adding new vertical or horizontal boundary condition calculators has three main steps:

  1. Subclass VertBoundaryConditionCalculator or HorizBoundaryConditionCalculator in the module boundary_conditions.pyx

  2. Add the new boundary condition calculator to the correct factory method in boundary_conditions.pyx.

  3. Add associated configuration options to the run configuration file.