pylag.numerics module

Numerical and iterative methods for computing changes in particle positions. The following distinction is made between numerical methods and iterative methods: iterative methods are any iterative process which computes changes in a particle’s position (e.g. a simple Euler scheme) during a single time step; while numerical methods are algorithms which combine the results of one or more iterative schemes to compute the final change in a particles position. The split between the two was introduced in order to make it possible to implement some form of operator splitting in which advection and diffusion are handled separately with potentially different time steps for each.

Note

numerics is implemented in Cython. Only a small portion of the API is exposed in Python with accompanying documentation.

class pylag.numerics.AdvDiffMilstein1DItMethod(config)

Bases: ItMethod

Milstein 1D iterative method

In this class the contributions of both advection and diffusion are accounted for.

Parameters:: config (ConfigParser)

class pylag.numerics.AdvDiffMilstein3DItMethod(config)

Bases: ItMethod

Milstein 3D iterative method

In this class the contributions of both advection and diffusion are accounted for.

Parameters:: config (ConfigParser)

class pylag.numerics.AdvRK42DItMethod(config)

Bases: ItMethod

2D deterministic Fourth Order Runge-Kutta iterative method

Parameters:: config (ConfigParser) – Configuration object
Variables:: _horiz_bc_calculator (HorizBoundaryConditionCalculator) – The method used for computing horizontal boundary conditions.

class pylag.numerics.AdvRK43DItMethod(config)

Bases: ItMethod

3D deterministic Fourth Order Runge-Kutta iterative method

Parameters:

config (ConfigParser) – Configuration object

Variables:

_horiz_bc_calculator (HorizBoundaryConditionCalculator) – The method used for computing horizontal boundary conditions.
_vert_bc_calculator (VertBoundaryConditionCalculator) – The method used for computing vertical boundary conditions.

class pylag.numerics.DiffConst2DItMethod(config)

Bases: ItMethod

Stochastic Constant 2D iterative method

Parameters:: config (ConfigParser)
Variables:: _Ah (float) – Horizontal eddy diffusivity constant

class pylag.numerics.DiffEuler1DItMethod(config)

Bases: ItMethod

Stochastic Euler 1D iterative method

Parameters:: config (ConfigParser)

class pylag.numerics.DiffMilstein1DItMethod(config)

Bases: ItMethod

Stochastic Milstein 1D iterative method

This scheme was highlighted by Grawe (2012) as being more accurate than the Euler or Visser schemes, but still computationally efficient.

Parameters:: config (ConfigParser)

class pylag.numerics.DiffMilstein2DItMethod(config)

Bases: ItMethod

Stochastic Milstein 2D iterative method

This method is a 2D implementation of the Milstein scheme.

Parameters:: config (ConfigParser)

class pylag.numerics.DiffMilstein3DItMethod(config)

Bases: ItMethod

Stochastic Milstein 3D iterative method

This method is a 3D implementation of the Milstein scheme.

Parameters:: config (ConfigParser)

class pylag.numerics.DiffNaive1DItMethod(config)

Bases: ItMethod

Stochastic Naive Euler 1D iterative method

Parameters:: config (ConfigParser)

class pylag.numerics.DiffNaive2DItMethod(config)

Bases: ItMethod

Stochastic Naive Euler 2D iterative method

This method is very similar to that implemented in DiffConst2DItMethod with the difference being the eddy diffusivity is provided by DataReader. As in the 1D case, this method should not be used when the eddy diffusivity field is inhomogeneous.

Parameters:: config (ConfigParser)

class pylag.numerics.DiffVisser1DItMethod(config)

Bases: ItMethod

Stochastic Visser 1D iterative method

The scheme includes a deterministic advective term that counteracts the tendency for particles to accumulate in regions of low diffusivity (c.f. the NaiveEuler scheme). In this scheme, the vertical eddy diffusivity is computed at a position that lies roughly half way between the particle’s current position and the position it would be advected too. Vertical boundary conditions are invoked if the computed offset is outside of the model grid. See Visser (1997).

Parameters:: config (ConfigParser)
Variables:: _vert_bc_calculator (VertBoundaryConditionCalculator) – The method used for computing vertical boundary conditions.

class pylag.numerics.EulerParticleStateNumMethod(config)

Bases: object

Euler particle state numerical method

Particle states are updated using a simple euler scheme.

Variables:: _time_step (float) – Time step to be used in the intergration

class pylag.numerics.ItMethod

Bases: object

An abstract base class for iterative methods

The following method(s) should be implemented in the derived class:

meth:

step

Variables:

_time_step (float) – Time step to be used by the iterative method
_time_direction (float) – Multiplier indicating the integration direction (forward or reverse)

class pylag.numerics.NumMethod

Bases: object

An abstract base class for numerical integration schemes

The following method(s) should be implemented in the derived class:

meth:

step

step_wrapper(self, DataReader data_reader, DTYPE_FLOAT_t time, ParticleSmartPtr particle): Python friendly wrapper for step()

class pylag.numerics.OS0NumMethod(config)

Bases: NumMethod

Numerical method that employs operator splitting

The numerical method should be used when the effects of advection and diffusion are combined using a form of operator splitting in which first the advection step is computed, then n diffusion steps. The two processes can use different time steps - typically, the time step used for diffusion will be smaller than that used for advection - which has the potential to significantly reduce run times. Note the advection time step, which must be set in the supplied config, should be an exact multiple of the diffusion time step; if it isn’t, an exception will be raised.

Parameters:

config (ConfigParser) – Configuration object

Variables:

_adv_time_step (float) – Time step used for advection
_diff_time_step (float) – Time step used for diffusion
_n_sub_time_steps (int) – The number of diffusion time steps for each advection step
_adv_iterative_method (_ItMethod) – The iterative method used for advection (e.g. Euler etc)
_diff_iterative_method (_ItMethod) – The iterative method used for diffusion (e.g. Euler etc)
_horiz_bc_calculator (HorizBoundaryConditionCalculator) – The method used for computing horizontal boundary conditions.
_vert_bc_calculator (VertBoundaryConditionCalculator) – The method used for computing vertical boundary conditions.

class pylag.numerics.OS1NumMethod(config)

Bases: NumMethod

Numerical method that employs strang splitting

The numerical method should be used when the effects of advection and diffusion are combined using a form of operator splitting in which first a half diffusion step is computed, then a full advection step, then a half diffusion step.

Parameters:

config (ConfigParser) – Configuration object

Variables:

_adv_time_step (float) – Time step used for advection
_diff_time_step (float) – Time step used for diffusion
_adv_iterative_method (_ItMethod) – The iterative method used for advection (e.g. Euler etc)
_diff_iterative_method (_ItMethod) – The iterative method used for diffusion (e.g. Euler etc)
_horiz_bc_calculator (HorizBoundaryConditionCalculator) – The method used for computing horizontal boundary conditions.
_vert_bc_calculator (VertBoundaryConditionCalculator) – The method used for computing vertical boundary conditions.

class pylag.numerics.ParticleStateNumMethod

Bases: object

An abstract base class for particle state numerical methods

The following method(s) should be implemented in the derived class:

meth:

step

Variables:: _time_step (float) – Time step to be used by the iterative method

class pylag.numerics.StdNumMethod(config)

Bases: NumMethod

Standard numerical method

The method can be used for cases in which pure advection, pure diffusion or advection and diffusion are modelled. In the case of the latter, the deterministic and stochastic components of particle movement share the same time step. If you would prefer to use some form of operator splitting (e.g. to reduce simulation times) use the methods OS1NumMethod or OS2NumMethod instead.

Parameters:

config (ConfigParser) – Configuration object

Variables:

_time_step (float) – Time step to be used by the iterative method
_iterative_method (_ItMethod) – The iterative method used (e.g. Euler etc)
_horiz_bc_calculator (HorizBoundaryConditionCalculator) – The method used for computing horizontal boundary conditions.
_vert_bc_calculator (VertBoundaryConditionCalculator) – The method used for computing vertical boundary conditions.

class pylag.numerics.TestNumMethod

Bases: NumMethod

Test iterative method

Class to assist in testing other parts of the code that may require an object of type NumMethod to exist, but which does nothing.

pylag.numerics.get_adv_iterative_method(config)

Factory method for iterative methods that handle advection only

The type of iterative method to be constructed is read from an object of type ConfigParser which is passed in as a function argument. The method will only create types that handle pure advection.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_bio_time_step(config)

Return the bio time step

At the current time, this is pinned to the global time step - bio sub-stepping is not permitted. A check is put in place to ensure the bio time step is equal to the global time step. See below for information on how the global time step is set.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_diff_iterative_method(config)

Factory method for iterative methods that handle diffusion only

The type of iterative method to be constructed is read from an object of type ConfigParser which is passed in as a function argument. The method will only create types that handle pure diffusion.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_global_time_step(config)

Return the global time step

This is a utility function that returns the global time step adopted within the model. It is included to ensure clients have a robust method of calculating the global time step that takes into account the fact that different NumMethod and ItMethod objects can use different time steps (or combinations of time steps if separate iterative methods are used for advection and diffusion).

The rules are: 1) Return the advection time step if operator splitting is being used 2) Return the advection time step if operator splitting isn’t being used and the iterative method is for advection only. 3) Return the diffusion tim step if operator splitting isn’t being used, and the iterative method is for diffusion only or advection+diffusion.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_iterative_method(config)

Factory method for iterative methods

The type of iterative method to be constructed is read from an object of type ConfigParser which is passed in as a function argument. All types of ItMethod object are supported.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_num_method(config)

Factory method for constructing NumMethod objects

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_particle_state_num_method(config)

Factory method for particle state num methods

The type of method to be constructed is read from an object of type ConfigParser which is passed in as a function argument.

Parameters:: config (ConfigParser) – Object of type ConfigParser.

pylag.numerics.get_time_direction(config)

Get time direction

Parameters:: config (configparser.ConfigParser) – Configuration object
Returns:: Flag signifying whether forward or reverse tracking is being used.
Return type:: int