Timestepping

TimeStepper objects use time derivatives from Prognostic objects to step a model state forward in time. They are initialized using a list of Prognostic objects.

from sympl import AdamsBashforth
time_stepper = AdamsBashforth([MyPrognostic(), MyOtherPrognostic()])

Once initialized, a TimeStepper object has a very similar interface to the Implicit object.

from datetime import timedelta
time_stepper = AdamsBashforth([MyPrognostic()])
timestep = timedelta(minutes=10)
diagnostics, next_state = time_stepper(state, timestep)
state.update(diagnostics)

The returned diagnostics dictionary contains diagnostic quantities from the timestep of the input state, while next_state is the state dictionary for the next timestep. It is possible that some of the arrays in diagnostics may be the same arrays as were given in the input state, and that they have been modified. In other words, state may be modified by this call. For instance, the time filtering necessary when using Leapfrog time stepping means the current model state has to be modified by the filter.

It is only after calling the TimeStepper and getting the diagnostics that you will have a complete state with all diagnostic quantities. This means you will sometimes want to pass state to your Monitor objects after calling the TimeStepper and getting next_state.

Warning

TimeStepper objects do not, and should not, update ‘time’ in the model state.

Keep in mind that for split-time models, multiple TimeStepper objects might be called in in a single pass of the main loop. If each one updated state['time'], the time would be moved forward more than it should. For that reason, TimeStepper objects do not update state['time'].

There are also Implicit objects which evolve the state forward in time without the use of Prognostic objects. These function exactly the same as a TimeStepper once they are created, but do not accept Prognostic objects when you create them. One example might be a component that condenses all supersaturated moisture over some time period. Implicit objects are generally used for parameterizations that work by determining the target model state in some way, or involve limiters, and cannot be represented as a Prognostic.

class sympl.TimeStepper(prognostic_list, **kwargs)

An object which integrates model state forward in time.

It uses Prognostic and Diagnostic objects to update the current model state with diagnostics, and to return the model state at the next timestep.

inputs

tuple of str – The quantities required in the state when the object is called.

diagnostics

tuple of str – The quantities for which values for the old state are returned when the object is called.

outputs

tuple of str – The quantities for which values for the new state are returned when the object is called.

__call__(state, timestep)

Retrieves any diagnostics and returns a new state corresponding to the next timestep.

Parameters:

• state (dict) – The current model state.
• timestep (timedelta) – The amount of time to step forward.

Returns:

• diagnostics (dict) – Diagnostics from the timestep of the input state.
• new_state (dict) – The model state at the next timestep.

__init__(prognostic_list, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__repr__()

Return repr(self).

__str__()

Return str(self).

class sympl.AdamsBashforth(prognostic_list, order=3)

A TimeStepper using the Adams-Bashforth scheme.

__call__(state, timestep)

Updates the input state dictionary and returns a new state corresponding to the next timestep.

Parameters:

• state (dict) – The current model state. Will be updated in-place by the call with any diagnostics from the current timestep.
• timestep (timedelta) – The amount of time to step forward.

Returns:

• diagnostics (dict) – Diagnostics from the timestep of the input state.
• new_state (dict) – The model state at the next timestep.

Raises:

ValueError – If the timestep is not the same as the last time step() was called on this instance of this object.

__init__(prognostic_list, order=3)

Initialize an Adams-Bashforth time stepper.

Parameters:

• prognostic_list (iterable of Prognostic) – Objects used to get tendencies for time stepping.
• order (int, optional) – The order of accuracy to use. Must be between 1 and 4. 1 is the same as the Euler method. Default is 3.

class sympl.Leapfrog(prognostic_list, asselin_strength=0.05, alpha=0.5)

A TimeStepper using the Leapfrog scheme.

This scheme calculates the values at time $t_{n+1}$ using the derivatives at $t_{n}$ and values at $t_{n-1}$. Following the step, an Asselin filter is applied to damp the computational mode that results from the scheme and maintain stability. The Asselin filter brings the values at $t_{n}$ (and optionally the values at $t_{n+1}$, according to Williams (2009)) closer to the mean of the values at $t_{n-1}$ and $t_{n+1}$.

__call__(state, timestep)

Updates the input state dictionary and returns a new state corresponding to the next timestep.

Parameters:

• state (dict) – The current model state. Will be updated in-place by the call due to the Robert-Asselin-Williams filter.
• timestep (timedelta) – The amount of time to step forward.

Returns:

• diagnostics (dict) – Diagnostics from the timestep of the input state.
• new_state (dict) – The model state at the next timestep.

Raises:

• SharedKeyError – If a Diagnostic object has an output that is already in the state at the start of the timestep.
• ValueError – If the timestep is not the same as the last time step() was called on this instance of this object.

__init__(prognostic_list, asselin_strength=0.05, alpha=0.5)

Initialize a Leapfrog time stepper.

Parameters:

• prognostic_list (iterable of Prognostic) – Objects used to get tendencies for time stepping.
• asselin_strength (float, optional) – The filter parameter used to determine the strength of the Asselin filter. Default is 0.05.
• alpha (float, optional) – Constant from Williams (2009), where the midpoint is shifted by alpha*influence, and the right point is shifted by (1-alpha)*influence. If alpha is 1 then the behavior is that of the classic Robert-Asselin time filter, while if it is 0.5 the filter will conserve the three-point mean. Default is 0.5.

References

Williams, P., 2009: A Proposed Modification to the Robert-Asselin Time Filter. Mon. Wea. Rev., 137, 2538–2546, doi: 10.1175/2009MWR2724.1.