gusto.timestepping package

Submodules

gusto.timestepping.semi_implicit_quasi_newton module

The Semi-Implicit Quasi-Newton timestepper used by the Met Office’s ENDGame and GungHo dynamical cores.

class gusto.timestepping.semi_implicit_quasi_newton.SemiImplicitQuasiNewton(equation_set, io, transport_schemes, spatial_methods, auxiliary_equations_and_schemes=None, linear_solver=None, diffusion_schemes=None, physics_schemes=None, slow_physics_schemes=None, fast_physics_schemes=None, alpha=0.5, off_centred_u=False, num_outer=2, num_inner=2, accelerator=False, predictor=None, reference_update_freq=None, spinup_steps=0)

Bases: BaseTimestepper

Implements a semi-implicit quasi-Newton discretisation, with Strang splitting and auxiliary semi-Lagrangian transport.

The timestep consists of an outer loop applying the transport and an inner loop to perform the quasi-Newton interations for the fast-wave terms.

Parameters:

• equation_set (PrognosticEquationSet) – the prognostic equation set to be solved

• io (IO) – the model’s object for controlling input/output.

• transport_schemes – iterable of (field_name, scheme) pairs indicating the name of the field (str) to transport, and the TimeDiscretisation to use

• spatial_methods (iter) – a list of objects describing the spatial discretisations of transport or diffusion terms to be used.

• auxiliary_equations_and_schemes – iterable of (equation, scheme) pairs indicating any additional equations to be solved and the scheme to use to solve them. Defaults to None.

• linear_solver (TimesteppingSolver, optional) – the object to use for the linear solve. Defaults to None.

• diffusion_schemes (iter, optional) – iterable of pairs of the form (field_name, scheme) indicating the fields to diffuse, and the TimeDiscretisation to use. Defaults to None.

• physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation), pairing physics parametrisations and timestepping schemes to use for each. Timestepping schemes for physics must be explicit. These schemes are all evaluated at the end of the time step. Defaults to None.

• slow_physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation). These schemes are all evaluated at the start of the time step. Defaults to None.

• fast_physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation). These schemes are evaluated within the outer loop. Defaults to None.

• alpha (`float, optional) – the semi-implicit off-centering parameter. A value of 1 corresponds to fully implicit, while 0 corresponds to fully explicit. Defaults to 0.5.

• off_centred_u (bool, optional) – option to offcentre the transporting velocity. Defaults to False, in which case transporting velocity is centred. If True offcentring uses value of alpha.

• num_outer (int, optional) – number of outer iterations in the semi- implicit algorithm. The outer loop includes transport and any fast physics schemes. Defaults to 2. Note that default used by the Met Office’s ENDGame and GungHo models is 2.

• num_inner (int, optional) – number of inner iterations in the semi- implicit algorithm. The inner loop includes the evaluation of implicit forcing (pressure gradient and Coriolis) terms, and the linear solve. Defaults to 2. Note that default used by the Met Office’s ENDGame and GungHo models is 2.

• accelerator (bool, optional) – Whether to zero non-wind implicit forcings for transport terms in order to speed up solver convergence. Defaults to False.

• predictor (str, optional) – a single string corresponding to the name of a variable to transport using the divergence predictor. This pre-multiplies that variable by (1 - beta*dt*div(u)) before the transport step, and calculates its transport increment from the transport of this variable. This can improve the stability of the time stepper at large time steps, when not using an advective-then-flux formulation. This is only suitable for the use on the conservative variable (e.g. depth or density). Defaults to None, in which case no predictor is used.

• reference_update_freq (float, optional) – frequency with which to update the reference profile with the n-th time level state fields. This variable corresponds to time in seconds, and setting this to zero will update the reference profiles every time step. Setting it to None turns off the update, and reference profiles will remain at their initial values. Defaults to None.

• spinup_steps (int, optional) – the number of steps to run the model in “spin-up” mode, where the alpha parameter is set to 1.0. Defaults to 0, which corresponds to no spin-up.

copy_active_tracers(x_in, x_out)

Copies active tracers from one set of fields to another, if those fields are not included in the linear solver. This is determined by whether the time derivative term for that tracer has a linearisation.

Parameters:

• x_in – The input set of fields

• x_out – The output set of fields

finish_spinup()

Finishes the spin-up period, returning the off-centering parameter to its original value.

run(t, tmax, pick_up=False)

Runs the model for the specified time, from t to tmax.

Parameters:

• t (float) – the start time of the run

• tmax (float) – the end time of the run

• pick_up – (bool): specify whether to pick_up from a previous run

setup_fields()

Sets up time levels n, star, p and np1

setup_scheme()

Sets up transport, diffusion and physics schemes

start_spinup()

Initialises the spin-up period, so that the scheme is implicit by setting the off-centering parameter alpha to be 1.

timestep()

Defines the timestep

transport_fields(outer, xstar, xp)

Transports all fields in xstar with a transport scheme and places the result in xp.

Parameters:

• outer (int) – the outer loop iteration number

• xstar (Fields) – the collection of state fields to be transported.

• xp (Fields) – the collection of state fields resulting from the transport.

property transporting_velocity

Computes ubar=(1-alpha)*un + alpha*unp1

update_reference_profiles()

Updates the reference profiles and if required also updates them in the linear solver.

gusto.timestepping.split_timestepper module

Split timestepping methods for generically solving terms separately.

class gusto.timestepping.split_timestepper.SplitPhysicsTimestepper(equation, scheme, io, spatial_methods=None, physics_schemes=None)

Bases: Timestepper

Implements a timeloop by applying schemes separately to the physics and dynamics. This ‘splits’ the physics from the dynamics and allows a different scheme to be applied to the physics terms than the prognostic equation.

Parameters:

• equation (PrognosticEquation) – the prognostic equation

• scheme (TimeDiscretisation) – the scheme to use to timestep the prognostic equation

• io (IO) – the model’s object for controlling input/output.

• spatial_methods (iter,optional) – a list of objects describing the methods to use for discretising transport or diffusion terms for each transported/diffused variable. Defaults to None, in which case the terms follow the original discretisation in the equation.

• physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation), pairing physics parametrisations and timestepping schemes to use for each. Timestepping schemes for physics must be explicit. Defaults to None.

setup_scheme()

Set up required scheme(s). Must be implemented in child classes

timestep()

Implement the timestep

property transporting_velocity

class gusto.timestepping.split_timestepper.SplitPrescribedTransport(equation, scheme, io, prescribed_transporting_velocity, spatial_methods=None, physics_schemes=None)

Bases: Timestepper

Implements a timeloop where the physics terms are solved separately from the dynamics, like with SplitPhysicsTimestepper, but here we define a prescribed transporting velocity, as opposed to having the velocity as a prognostic variable.

Parameters:

• equation (PrognosticEquation) – the prognostic equation

• scheme (TimeDiscretisation) – the scheme to use to timestep the prognostic equation

• io (IO) – the model’s object for controlling input/output.

• prescribed_transporting_velocity – (bool): Whether a time-varying transporting velocity will be defined. If True, this will require the transporting velocity to be setup by calling either the setup_prescribed_expr or setup_prescribed_apply methods.

• spatial_methods (iter,optional) – a list of objects describing the methods to use for discretising transport or diffusion terms for each transported/diffused variable. Defaults to None, in which case the terms follow the original discretisation in the equation.

• physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation), pairing physics parametrisations and timestepping schemes to use for each. Timestepping schemes for physics can be explicit or implicit. Defaults to None.

• prescribed_transporting_velocity – (field, optional): A known velocity field that is used for the transport of tracers. This can be made time-varying by defining a python function that uses time as an argument. Defaults to None.

run(t, tmax, pick_up=False)

Runs the model for the specified time, from t to tmax :param t: the start time of the run :type t: float :param tmax: the end time of the run :type tmax: float :param pick_up: (bool): specify whether to pick_up from a previous run

setup_prescribed_apply(apply_method)

Sets up the prescribed transporting velocity, through a python function which has time as an argument. This function will perform the evaluation of the transporting velocity.

Parameters:

expr_func (func) – a python function with a single argument that represents the model time, and performs the evaluation of the transporting velocity.

setup_prescribed_expr(expr_func)

Sets up the prescribed transporting velocity, through a python function which has time as an argument, and returns a ufl.Expr. This allows the velocity to be updated with time.

Parameters:

expr_func (func) – a python function with a single argument that represents the model time, and returns a ufl.Expr.

setup_scheme()

Set up required scheme(s). Must be implemented in child classes

timestep()

Implement the timestep

property transporting_velocity

class gusto.timestepping.split_timestepper.SplitTimestepper(equation, term_splitting, dynamics_schemes, io, weights=None, spatial_methods=None, physics_schemes=None)

Bases: BaseTimestepper

Implements a timeloop by applying separate schemes to different terms, e.g, physics and individual dynamics components in a user-defined order. This allows a different time discretisation to be applied to each defined component. Different terms can be substepped by specifying weights; this enables Strang-Splitting to be applied.

Parameters:

• equation (PrognosticEquation) – the prognostic equation

• term_splitting (list) – a list of labels specifying the terms that should be solved separately and the order to do so.

• dynamics_schemes – (TimeDiscretisation) A list of time discretisations for the dynamics schemes. A scheme must be provided for each non-physics label that is provided in the term_splitting list.

• io (IO) – the model’s object for controlling input/output. weights (array, optional): An array of weights for substepping of any dynamics or physics scheme. The sum of weights for each distinct label in term_splitting must be 1.

• spatial_methods (iter,optional) – a list of objects describing the methods to use for discretising transport or diffusion terms for each transported/diffused variable. Defaults to None, in which case the terms follow the original discretisation in the equation.

• physics_schemes – (list, optional): a list of tuples of the form (PhysicsParametrisation, TimeDiscretisation), pairing physics parametrisations and timestepping schemes to use for each. Timestepping schemes for physics must be explicit. Defaults to None.

setup_fields()

Set up required fields. Must be implemented in child classes

setup_scheme()

Sets up transport, diffusion and physics schemes

timestep()

Defines the timestep. Must be implemented in child classes

property transporting_velocity

gusto.timestepping.timestepper module

Defines the basic timestepper objects.

class gusto.timestepping.timestepper.BaseTimestepper(equation, io)

Bases: object

Base class for timesteppers.

Parameters:

• equation (PrognosticEquation) – the prognostic equation.

• io (IO) – the model’s object for controlling input/output.

get_initial_timesteps()

Gets the number of initial time steps from a multi-level scheme.

log_field_stats()

Logs some field stats, which can be useful for debugging.

log_timestep()

Logs the start of a time step.

run(t, tmax, pick_up=False)

Runs the model for the specified time, from t to tmax

Parameters:

• t (float) – the start time of the run

• tmax (float) – the end time of the run

• pick_up – (bool): specify whether to pick_up from a previous run

set_initial_timesteps(num_steps)

Sets the number of initial time steps for a multi-level scheme.

set_reference_profiles(reference_profiles, last_ref_update_time=None)

Initialise the model’s reference profiles.

reference_profiles (list): an iterable of pairs: (field_name, expr),

where ‘field_name’ is the string giving the name of the reference profile field expr is the ufl.Expr whose value is used to set the reference field.

last_ref_update_time (float, optional): the last time that the reference

profiles were updated. Defaults to None.

setup_equation(equation)

Sets up the spatial methods for an equation, by the setting the forms used for transport/diffusion in the equation.

Parameters:

equation (PrognosticEquation) – the equation that the transport method is to be applied to.

abstractmethod setup_fields()

Set up required fields. Must be implemented in child classes

abstractmethod setup_scheme()

Set up required scheme(s). Must be implemented in child classes

setup_transporting_velocity(scheme)

Set up the time discretisation by replacing the transporting velocity used by the appropriate one for this time loop.

Parameters:

scheme (TimeDiscretisation) – the time discretisation whose transport term should be replaced with the transport term of this discretisation.

abstractmethod timestep()

Defines the timestep. Must be implemented in child classes

abstract property transporting_velocity

class gusto.timestepping.timestepper.PrescribedTransport(equation, scheme, io, prescribed_transporting_velocity, transport_method, physics_parametrisations=None)

Bases: Timestepper

Implements a timeloop with a prescibed transporting velocity.

Parameters:

• equation (PrognosticEquation) – the prognostic equation

• scheme (TimeDiscretisation) – the scheme to use to timestep the prognostic equation.

• io (IO) – the model’s object for controlling input/output.

• prescribed_transporting_velocity – (bool): Whether a time-varying transporting velocity will be defined. If True, this will require the transporting velocity to be setup by calling either the setup_prescribed_expr or setup_prescribed_apply methods.

• transport_method (TransportMethod) – describes the method used for discretising the transport term.

• physics_parametrisations – (iter, optional): an iterable of PhysicsParametrisation objects that describe physical parametrisations to be included to add to the equation. They can only be used when the time discretisation scheme is explicit. Defaults to None.

run(t, tmax, pick_up=False)

Runs the model for the specified time, from t to tmax :param t: the start time of the run :type t: float :param tmax: the end time of the run :type tmax: float :param pick_up: (bool): specify whether to pick_up from a previous run

setup_fields()

Set up required fields. Must be implemented in child classes

setup_prescribed_apply(apply_method)

Sets up the prescribed transporting velocity, through a python function which has time as an argument. This function will perform the evaluation of the transporting velocity.

Parameters:

expr_func (func) – a python function with a single argument that represents the model time, and performs the evaluation of the transporting velocity.

setup_prescribed_expr(expr_func)

Sets up the prescribed transporting velocity, through a python function which has time as an argument, and returns a ufl.Expr. This allows the velocity to be updated with time.

Parameters:

expr_func (func) – a python function with a single argument that represents the model time, and returns a ufl.Expr.

timestep()

Implements the time step, which possibly involves evaluation of the prescribed transporting velocity.

property transporting_velocity

class gusto.timestepping.timestepper.Timestepper(equation, scheme, io, spatial_methods=None, physics_parametrisations=None)

Bases: BaseTimestepper

Implements a timeloop by applying a scheme to a prognostic equation.

Parameters:

• equation (PrognosticEquation) – the prognostic equation

• scheme (TimeDiscretisation) – the scheme to use to timestep the prognostic equation

• io (IO) – the model’s object for controlling input/output.

• spatial_methods (iter, optional) – a list of objects describing the methods to use for discretising transport or diffusion terms for each transported/diffused variable. Defaults to None, in which case the terms follow the original discretisation in the equation.

• physics_parametrisations – (iter, optional): an iterable of PhysicsParametrisation objects that describe physical parametrisations to be included to add to the equation. They can only be used when the time discretisation scheme is explicit. Defaults to None.

setup_fields()

Set up required fields. Must be implemented in child classes

setup_scheme()

Set up required scheme(s). Must be implemented in child classes

timestep()

Implement the timestep

property transporting_velocity

Module contents