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
- 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