gusto.time_discretisation package

Submodules

gusto.time_discretisation.explicit_runge_kutta module

Objects to describe explicit multi-stage (Runge-Kutta) discretisations.

class gusto.time_discretisation.explicit_runge_kutta.ExplicitRungeKutta(domain, butcher_matrix, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, increment_form=True, solver_parameters=None, limiter=None, options=None)

Bases: ExplicitTimeDiscretisation

A class for implementing general explicit multistage (Runge-Kutta) methods based on its Butcher tableau.

A Butcher tableau is formed in the following way for a s-th order explicit scheme:

All upper diagonal a_ij elements are zero for explicit methods.

There are three steps to move from the current solution, y^n, to the new one, y^{n+1}

For each i = 1, s in an s stage method we have the intermediate solutions:

y_i = y^n + dt*(a_i1*k_1 + a_i2*k_2 + … + a_i{i-1}*k_{i-1})

We compute the gradient at the intermediate location, k_i = F(y_i)

At the last stage, compute the new solution by: y^{n+1} = y^n + dt*(b_1*k_1 + b_2*k_2 + …. + b_s*k_s)

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• butcher_matrix (numpy array) – A matrix containing the coefficients of a butcher tableau defining a given Runge Kutta time discretisation.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• increment_form (bool, optional) – whether to write the RK scheme in “increment form”, solving for increments rather than updated fields. Defaults to True.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply_cycle(x_out, x_in)

Apply the time discretisation through a single sub-step.

Parameters:

• x_in (Function) – the input field.

• x_out (Function) – the output field to be computed.

lhs

Set up the discretisation’s left hand side (the time derivative).

property nStages

rhs

Set up the time discretisation’s right hand side.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solve_stage(x0, stage)

solver

class gusto.time_discretisation.explicit_runge_kutta.ForwardEuler(domain, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, increment_form=True, solver_parameters=None, limiter=None, options=None)

Bases: ExplicitRungeKutta

Implements the forward Euler timestepping scheme.

The forward Euler method for operator F is the most simple explicit scheme:

k0 = F[y^n]

y^(n+1) = y^n + dt*k0

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• increment_form (bool, optional) – whether to write the RK scheme in “increment form”, solving for increments rather than updated fields. Defaults to True.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.explicit_runge_kutta.Heun(domain, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, increment_form=True, solver_parameters=None, limiter=None, options=None)

Bases: ExplicitRungeKutta

Implements Heun’s method.

The 2-stage Runge-Kutta scheme known as Heun’s method,for solving ∂y/∂t = F(y). It can be written as:

y_1 = F[y^n]

y^(n+1) = (1/2)y^n + (1/2)F[y_1]

where superscripts indicate the time-level and subscripts indicate the stage number.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• increment_form (bool, optional) – whether to write the RK scheme in “increment form”, solving for increments rather than updated fields. Defaults to True.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.explicit_runge_kutta.RK4(domain, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, increment_form=True, solver_parameters=None, limiter=None, options=None)

Bases: ExplicitRungeKutta

Implements the classic 4-stage Runge-Kutta method.

The classic 4-stage Runge-Kutta method for solving ∂y/∂t = F(y). It can be written as:

k0 = F[y^n]

k1 = F[y^n + 1/2*dt*k1]

k2 = F[y^n + 1/2*dt*k2]

k3 = F[y^n + dt*k3]

y^(n+1) = y^n + (1/6) * dt * (k0 + 2*k1 + 2*k2 + k3)

where superscripts indicate the time-level.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• increment_form (bool, optional) – whether to write the RK scheme in “increment form”, solving for increments rather than updated fields. Defaults to True.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.explicit_runge_kutta.SSPRK3(domain, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, increment_form=True, solver_parameters=None, limiter=None, options=None)

Bases: ExplicitRungeKutta

Implements the 3-stage Strong-Stability-Preserving Runge-Kutta method for solving ∂y/∂t = F(y). It can be written as:

k0 = F[y^n]

k1 = F[y^n + dt*k1]

k2 = F[y^n + (1/4)*dt*(k0+k1)]

y^(n+1) = y^n + (1/6)*dt*(k0 + k1 + 4*k2)

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• increment_form (bool, optional) – whether to write the RK scheme in “increment form”, solving for increments rather than updated fields. Defaults to True.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

gusto.time_discretisation.imex_runge_kutta module

Implementations of IMEX Runge-Kutta time discretisations.

class gusto.time_discretisation.imex_runge_kutta.IMEXRungeKutta(domain, butcher_imp, butcher_exp, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: TimeDiscretisation

A class for implementing general IMEX multistage (Runge-Kutta) methods based on two Butcher tableaus, to solve

∂y/∂t = F(y) + S(y)

Where F are implicit fast terms, and S are explicit slow terms.

There are three steps to move from the current solution, y^n, to the new one, y^{n+1}

For each i = 1, s in an s stage method we compute the intermediate solutions:

y_i = y^n + dt*(a_i1*F(y_1) + a_i2*F(y_2)+ … + a_ii*F(y_i))

• dt*(d_i1*S(y_1) + d_i2*S(y_2)+ … + d_{i,i-1}*S(y_{i-1}))

At the last stage, compute the new solution by:

y^{n+1} = y^n + dt*(b_1*F(y_1) + b_2*F(y_2) + …. + b_s*F(y_s))

• dt*(e_1*S(y_1) + e_2*S(y_2) + …. + e_s*S(y_s))

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• butcher_imp (numpy.ndarray) – A matrix containing the coefficients of a butcher tableau defining a given implicit Runge Kutta time discretisation.

• butcher_exp (numpy.ndarray) – A matrix containing the coefficients of a butcher tableau defining a given explicit Runge Kutta time discretisation.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

property final_res

Set up the discretisation’s final residual.

final_solver

Set up a solver for the final solve to evaluate time level n+1.

lhs

Set up the discretisation’s left hand side (the time derivative).

res(stage)

Set up the discretisation’s residual for a given stage.

rhs

Set up the discretisation’s right hand side (the time derivative).

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solvers

Set up a list of solvers for each problem at a stage.

class gusto.time_discretisation.imex_runge_kutta.IMEX_ARK2(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: IMEXRungeKutta

Implements ARK2(2,3,2) two-stage IMEX Runge–Kutta method from RK IMEX for HEVI (Weller et al 2013). Where g = 1 - 1/sqrt(2), a = 1/6(3 + 2sqrt(2)), d = 1/2sqrt(2).

The method, for solving

∂y/∂t = F(y) + S(y), can be written as:

y_0 = y^n

y_1 = y^n + dt*(g*F[y_0]+g*F[y_1]) + 2*dt*g*S[y_0]

y_2 = y^n + dt*(d*F[y_0]+d*F[y_1]+g*F[y_2])

• dt*((1-a)*S[y_0]+a*S[y_1])

y^(n+1) = y^n + dt*(d*F[y_0]+d*F[y_1]+g*F[y_2])

• dt*(d*S[y_0]+d*S[y_1]+g*S[y_2])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.imex_runge_kutta.IMEX_ARS3(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: IMEXRungeKutta

Implements ARS3(2,3,3) two-stage IMEX Runge–Kutta method from RK IMEX for HEVI (Weller et al 2013). Where g = (3 + sqrt(3))/6.

The method, for solving

∂y/∂t = F(y) + S(y), can be written as:

y_0 = y^n

y_1 = y^n + dt*g*F[y_1] + dt*g*S[y_0]

y_2 = y^n + dt*((1-2g)*F[y_1]+g*F[y_2])

• dt*((g-1)*S[y_0]+2(g-1)*S[y_1])

y^(n+1) = y^n + dt*(g*F[y_1]+(1-g)*F[y_2])

• dt*(0.5*S[y_1]+0.5*S[y_2])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.imex_runge_kutta.IMEX_Euler(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: IMEXRungeKutta

Implements IMEX Euler one-stage method.

The method, for solving

∂y/∂t = F(y) + S(y), can be written as:

y_0 = y^n

y_1 = y^n + dt*F[y_1] + dt*S[y_0]

y^(n+1) = y^n + dt*F[y_1] + dt*S[y_0]

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.imex_runge_kutta.IMEX_SSP3(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: IMEXRungeKutta

Implements SSP3(3,3,2) three-stage IMEX Runge–Kutta method from RK IMEX for HEVI (Weller et al 2013).

Let g = 1 - 1/sqrt(2). The method, for solving

∂y/∂t = F(y) + S(y), can be written as:

y_1 = y^n + dt*g*F[y_1]

y_2 = y^n + dt*((1-2g)*F[y_1]+g*F[y_2]) + dt*S[y_1]

y_3 = y^n + dt*((0.5-g)*F[y_1]+g*F[y_3]) + dt*(0.25*S[y_1]+0.25*S[y_2])

y^(n+1) = y^n + dt*(1/6*F[y_1]+1/6*F[y_2]+2/3*F[y_3])

• dt*(1/6*S[y_1]+1/6*S[y_2]+2/3*S[y_3])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.imex_runge_kutta.IMEX_Trap2(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: IMEXRungeKutta

Implements Trap2(2+e,3,2) three-stage IMEX Runge–Kutta method from RK IMEX for HEVI (Weller et al 2013). For e = 1 or 0.

The method, for solving

∂y/∂t = F(y) + S(y), can be written as:

y_0 = y^n

y_1 = y^n + dt*e*F[y_0] + dt*S[y_0]

y_2 = y^n + dt*(0.5*F[y_0]+0.5*F[y_2]) + dt*(0.5*S[y_0]+0.5*S[y_1])

y_3 = y^n + dt*(0.5*F[y_0]+0.5*F[y_3]) + dt*(0.5*S[y_0]+0.5*S[y_2])

y^(n+1) = y^n + dt*(0.5*F[y_0]+0.5*F[y_3]) + dt*(0.5*S[y_0] + 0.5*S[y_2])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

gusto.time_discretisation.implicit_runge_kutta module

Objects to describe implicit multi-stage (Runge-Kutta) discretisations.

class gusto.time_discretisation.implicit_runge_kutta.ImplicitMidpoint(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: ImplicitRungeKutta

Implements the Implicit Midpoint method as a 1-stage Runge Kutta method.

The method, for solving ∂y/∂t = F(y), can be written as:

k0 = F[y^n + 0.5*dt*k0]

y^(n+1) = y^n + dt*k0

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

class gusto.time_discretisation.implicit_runge_kutta.ImplicitRungeKutta(domain, butcher_matrix, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: TimeDiscretisation

A class for implementing general diagonally implicit multistage (Runge-Kutta) methods based on its Butcher tableau.

Unlike the explicit method, all upper diagonal a_ij elements are non-zero for implicit methods.

There are three steps to move from the current solution, y^n, to the new one, y^{n+1}

For each i = 1, s in an s stage method we have the intermediate solutions:

y_i = y^n + dt*(a_i1*k_1 + a_i2*k_2 + … + a_ii*k_i)

We compute the gradient at the intermediate location, k_i = F(y_i)

At the last stage, compute the new solution by:

y^{n+1} = y^n + dt*(b_1*k_1 + b_2*k_2 + …. + b_s*k_s)

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• butcher_matrix (numpy array) – A matrix containing the coefficients of a butcher tableau defining a given Runge Kutta time discretisation.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

lhs()

Set up the discretisation’s left hand side (the time derivative).

rhs()

Set up the time discretisation’s right hand side.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solve_stage(x0, stage)

solver(stage)

Set up the problem and the solver.

solvers

class gusto.time_discretisation.implicit_runge_kutta.QinZhang(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: ImplicitRungeKutta

Implements Qin and Zhang’s two-stage, 2nd order, implicit Runge–Kutta method.

The method, for solving ∂y/∂t = F(y), can be written as:

k0 = F[y^n + 0.25*dt*k0]

k1 = F[y^n + 0.5*dt*k0 + 0.25*dt*k1]

y^(n+1) = y^n + 0.5*dt*(k0 + k1)

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

gusto.time_discretisation.multi_level_schemes module

Implements time discretisations with multiple time levels.

class gusto.time_discretisation.multi_level_schemes.AdamsBashforth(domain, order, field_name=None, solver_parameters=None, options=None)

Bases: MultilevelTimeDiscretisation

Implements the explicit multistep Adams-Bashforth timestepping method of general order up to 5.

The general AB timestepping method for operator F is written as:

y^(n+1) = y^n + dt*(b_0*F[y^(n)] + b_1*F[y^(n-1)] + b_2*F[y^(n-2)] + b_3*F[y^(n-3)] + b_4*F[y^(n-4)])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• order (float, optional) – order of scheme

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

Raises:

ValueError – if order is not provided, or is in incorrect range.

apply(x_out, *x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field(s).

property lhs

Set up the discretisation’s left hand side (the time derivative).

property nlevels

property rhs

Set up the discretisation’s right hand side for Adams Bashforth steps.

property rhs0

Set up the discretisation’s right hand side for initial forward euler step.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• apply_bcs (bool, optional) – whether to apply the equation’s boundary conditions. Defaults to True.

• *active_labels (Label) – labels indicating which terms of the equation to include.

property solver

Set up the problem and the solver for Adams Bashforth steps.

property solver0

Set up the problem and the solverfor initial forward euler step.

class gusto.time_discretisation.multi_level_schemes.AdamsMoulton(domain, order, field_name=None, solver_parameters=None, options=None)

Bases: MultilevelTimeDiscretisation

Implements the implicit multistep Adams-Moulton timestepping method of general order up to 5

The general AM timestepping method for operator F is written as

y^(n+1) = y^n + dt*(b_0*F[y^(n+1)] + b_1*F[y^(n)] + b_2*F[y^(n-1)] + b_3*F[y^(n-2)])

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• order (float, optional) – order of scheme

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

Raises:

ValueError – if order is not provided, or is in incorrect range.

apply(x_out, *x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field(s).

property lhs

Set up the time discretisation’s right hand side for Adams Moulton steps.

property lhs0

Set up the time discretisation’s right hand side for initial trapezoidal step.

property nlevels

property rhs

Set up the discretisation’s right hand side for Adams Moulton steps.

property rhs0

Set up the discretisation’s right hand side for initial trapezoidal step.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• apply_bcs (bool, optional) – whether to apply the equation’s boundary conditions. Defaults to True.

• *active_labels (Label) – labels indicating which terms of the equation to include.

property solver

Set up the problem and the solver for Adams Moulton steps.

property solver0

Set up the problem and the solver for initial trapezoidal step.

class gusto.time_discretisation.multi_level_schemes.BDF2(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: MultilevelTimeDiscretisation

Implements the implicit multistep BDF2 timestepping method.

The BDF2 timestepping method for operator F is written as:

y^(n+1) = (4/3)*y^n - (1/3)*y^(n-1) + (2/3)*dt*F[y^(n+1)]

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, *x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field(s).

property lhs

Set up the discretisation’s left hand side (the time derivative).

property lhs0

Set up the discretisation’s left hand side (the time derivative).

property nlevels

property rhs

Set up the time discretisation’s right hand side for BDF2 steps.

property rhs0

Set up the time discretisation’s right hand side for inital BDF step.

property solver

Set up the problem and the solver for BDF2 steps.

property solver0

Set up the problem and the solver for initial BDF step.

class gusto.time_discretisation.multi_level_schemes.Leapfrog(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: MultilevelTimeDiscretisation

Implements the multistep Leapfrog timestepping method.

The Leapfrog timestepping method for operator F is written as:

y^(n+1) = y^(n-1) + 2*dt*F[y^n]

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, *x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field(s).

property lhs

Set up the discretisation’s left hand side (the time derivative).

property nlevels

property rhs

Set up the discretisation’s right hand side for leapfrog steps.

property rhs0

Set up the discretisation’s right hand side for initial forward euler step.

property solver

Set up the problem and the solver for leapfrog steps.

property solver0

Set up the problem and the solver for initial forward euler step.

gusto.time_discretisation.sdc module

gusto.time_discretisation.time_discretisation module

Objects for discretising time derivatives.

Time discretisation objects discretise ∂y/∂t = F(y), for variable y, time t and operator F.

class gusto.time_discretisation.time_discretisation.BackwardEuler(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: TimeDiscretisation

Implements the backward Euler timestepping scheme.

The backward Euler method for operator F is the most simple implicit scheme:

y^(n+1) = y^n + dt*F[y^(n+1)].

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the number of sub-steps to perform. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods. Defaults to None.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

property lhs

Set up the discretisation’s left hand side (the time derivative).

property rhs

Set up the time discretisation’s right hand side.

class gusto.time_discretisation.time_discretisation.ExplicitTimeDiscretisation(domain, field_name=None, fixed_subcycles=None, subcycle_by_courant=None, solver_parameters=None, limiter=None, options=None)

Bases: TimeDiscretisation

Base class for explicit time discretisations.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• fixed_subcycles (int, optional) – the fixed number of sub-steps to perform. This option cannot be specified with the subcycle_by_courant argument. Defaults to None.

• subcycle_by_courant (float, optional) – specifying this option will make the scheme perform adaptive sub-cycling based on the Courant number. The specified argument is the maximum Courant for one sub-cycle. Defaults to None, in which case adaptive sub-cycling is not used. This option cannot be specified with the fixed_subcycles argument.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

abstract apply_cycle(x_out, x_in)

Apply the time discretisation through a single sub-step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

lhs

Set up the discretisation’s left hand side (the time derivative).

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• apply_bcs (bool, optional) – whether boundary conditions are to be applied. Defaults to True.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solver

Set up the problem and the solver.

class gusto.time_discretisation.time_discretisation.TR_BDF2(domain, gamma, field_name=None, solver_parameters=None, options=None)

Bases: TimeDiscretisation

Implements the two stage implicit TR-BDF2 time stepping method, with a trapezoidal stage (TR) followed by a second order backwards difference stage (BDF2).

The TR-BDF2 time stepping method for operator F is written as:

y^(n+g) = y^n + dt*g/2*F[y^n] + dt*g/2*F[y^(n+g)] (TR stage)

y^(n+1) = 1/(g(2-g))*y^(n+g) - (1-g)**2/(g(2-g))*y^(n) + (1-g)/(2-g)*dt*F[y^(n+1)] (BDF2 stage)

for an off-centring parameter g (gamma).

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• gamma (float) – the off-centring parameter

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

lhs

Set up the discretisation’s left hand side (the time derivative) for the TR stage.

lhs_bdf2

Set up the discretisation’s left hand side (the time derivative) for the BDF2 stage.

rhs

Set up the time discretisation’s right hand side for the TR stage.

rhs_bdf2

Set up the time discretisation’s right hand side for the BDF2 stage.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• apply_bcs (bool, optional) – whether to apply the equation’s boundary conditions. Defaults to True.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solver_bdf2

Set up the problem and the solver.

solver_tr

Set up the problem and the solver.

class gusto.time_discretisation.time_discretisation.ThetaMethod(domain, theta, field_name=None, solver_parameters=None, options=None)

Bases: TimeDiscretisation

Implements the theta implicit-explicit timestepping method, which can be thought as a generalised trapezium rule.

The theta implicit-explicit timestepping method for operator F is written as:

y^(n+1) = y^n + dt*(1-theta)*F[y^n] + dt*theta*F[y^(n+1)]

for off-centring parameter theta.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• theta (float) – the off-centring parameter. theta = 1 corresponds to a backward Euler method. Defaults to None.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

Raises:

ValueError – if theta is not provided.

apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

lhs

Set up the discretisation’s left hand side (the time derivative).

rhs

Set up the time discretisation’s right hand side.

class gusto.time_discretisation.time_discretisation.TimeDiscretisation(domain, field_name=None, solver_parameters=None, limiter=None, options=None)

Bases: object

Base class for time discretisation schemes.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• limiter (Limiter object, optional) – a limiter to apply to the evolving field to enforce monotonicity. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

abstract apply(x_out, x_in)

Apply the time discretisation to advance one whole time step.

Parameters:

• x_out (Function) – the output field to be computed.

• x_in (Function) – the input field.

abstract property lhs

Set up the discretisation’s left hand side (the time derivative).

property nlevels

abstract property rhs

Set up the time discretisation’s right hand side.

setup(equation, apply_bcs=True, *active_labels)

Set up the time discretisation based on the equation.

Parameters:

• equation (PrognosticEquation) – the model’s equation.

• apply_bcs (bool, optional) – whether to apply the equation’s boundary conditions. Defaults to True.

• *active_labels (Label) – labels indicating which terms of the equation to include.

solver

Set up the problem and the solver.

class gusto.time_discretisation.time_discretisation.TrapeziumRule(domain, field_name=None, solver_parameters=None, options=None)

Bases: ThetaMethod

Implements the trapezium rule timestepping method, also commonly known as Crank Nicholson.

The trapezium rule timestepping method for operator F is written as:

y^(n+1) = y^n + dt/2*F[y^n] + dt/2*F[y^(n+1)].

It is equivalent to the “theta” method with theta = 1/2.

Parameters:

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• field_name (str, optional) – name of the field to be evolved. Defaults to None.

• solver_parameters (dict, optional) – dictionary of parameters to pass to the underlying solver. Defaults to None.

• options (AdvectionOptions, optional) – an object containing options to either be passed to the spatial discretisation, or to control the “wrapper” methods, such as Embedded DG or a recovery method. Defaults to None.

gusto.time_discretisation.wrappers module

Wrappers are objects that wrap around particular time discretisations, applying some generic operation before and after a standard time discretisation is called.

class gusto.time_discretisation.wrappers.EmbeddedDGWrapper(time_discretisation, wrapper_options)

Bases: Wrapper

Wrapper for computing a time discretisation with the Embedded DG method, in which a field is converted to an embedding discontinuous space, then evolved using a method suitable for this space, before projecting the field back to the original space.

Parameters:

• time_discretisation (TimeDiscretisation) – the time discretisation that this wrapper is to be used with.

• wrapper_options (WrapperOptions) – configuration object holding the options specific to this Wrapper.

post_apply(x_out)

Extra post-apply steps for the embedded DG method. Projects the output field from the embedding space to the original space.

Parameters:

x_out (Function) – the output field in the original space.

pre_apply(x_in)

Extra pre-apply steps for the embedded DG method. Interpolates or projects x_in to the embedding space.

Parameters:

x_in (Function) – the original input field.

setup(original_space, post_apply_bcs)

Sets up function spaces and fields needed for this wrapper.

Parameters:

• original_space (FunctionSpace) – the space that the prognostic variable is defined on.

• post_apply_bcs (list of DirichletBC) – list of Dirichlet boundary condition objects to be passed to the projector used in the post-apply step.

class gusto.time_discretisation.wrappers.MixedFSWrapper

Bases: object

An object to hold a subwrapper dictionary with different wrappers for different tracers. This means that different tracers can be solved simultaneously using a CoupledTransportEquation, whilst being in different spaces and needing different implementation options.

post_apply(x_out)

Perform the post-applications for all fields with an associated subwrapper.

pre_apply(x_in)

Perform the pre-applications for all fields with an associated subwrapper.

setup()

Compute the new mixed function space from the subwrappers

class gusto.time_discretisation.wrappers.RecoveryWrapper(time_discretisation, wrapper_options)

Bases: Wrapper

Wrapper for computing a time discretisation with the “recovered” method, in which a field is converted to higher-order function space space. The field is then evolved in this higher-order function space to obtain an increased order of accuracy over evolving the field in the lower-order space. The field is then returned to the original space.

Parameters:

• time_discretisation (TimeDiscretisation) – the time discretisation that this wrapper is to be used with.

• wrapper_options (WrapperOptions) – configuration object holding the options specific to this Wrapper.

post_apply(x_out)

Extra post-apply steps for the recovered method. Projects the output field from the embedding space to the original space.

Parameters:

x_out (Function) – the output field in the original space.

pre_apply(x_in)

Extra pre-apply steps for the recovered method. Interpolates or projects x_in to the embedding space.

Parameters:

x_in (Function) – the original input field.

setup(original_space, post_apply_bcs)

Sets up function spaces and fields needed for this wrapper.

Parameters:

• original_space (FunctionSpace) – the space that the prognostic variable is defined on.

• post_apply_bcs (list of DirichletBC) – list of Dirichlet boundary condition objects to be passed to the projector used in the post-apply step.

class gusto.time_discretisation.wrappers.SUPGWrapper(time_discretisation, wrapper_options)

Bases: Wrapper

Wrapper for computing a time discretisation with SUPG, which adjusts the test function space that is used to solve the problem.

Parameters:

• time_discretisation (TimeDiscretisation) – the time discretisation that this wrapper is to be used with.

• wrapper_options (WrapperOptions) – configuration object holding the options specific to this Wrapper.

label_terms(residual)

A base method to allow labels to be updated or extra labels added to the form that will be used with the wrapper.

Parameters:

residual (LabelledForm) – the labelled form to update.

Returns:

the updated labelled form.

Return type:

LabelledForm

post_apply(x_out)

Does nothing for SUPG, just sets the output field.

Parameters:

x_out (Function) – the output field in the original space.

pre_apply(x_in)

Does nothing for SUPG, just sets the input field.

Parameters:

x_in (Function) – the original input field.

setup()

Sets up function spaces and fields needed for this wrapper.

Module contents