# Timestepping¶

TendencyStepper objects use time derivatives from TendencyComponent objects to step a model state forward in time. They are initialized using any number of TendencyComponent objects.

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


Once initialized, a TendencyStepper object has a very similar interface to the Stepper 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 TendencyStepper 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 TendencyStepper and getting next_state.

Warning

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

Keep in mind that for split-time models, multiple TendencyStepper 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, TendencyStepper objects do not update state['time'].

There are also Stepper objects which evolve the state forward in time without the use of TendencyComponent objects. These function exactly the same as a TendencyStepper once they are created, but do not accept TendencyComponent objects when you create them. One example might be a component that condenses all supersaturated moisture over some time period. Stepper 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 TendencyComponent.

class sympl.TendencyStepper(*args, **kwargs)[source]

An object which integrates model state forward in time.

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

diagnostic_properties

A dictionary whose keys are quantities for which values for the old state are returned when the object is called, and values are dictionaries which indicate ‘dims’ and ‘units’.

Type: dict
output_properties

A dictionary whose keys are quantities for which values for the new state are returned when the object is called, and values are dictionaries which indicate ‘dims’ and ‘units’.

Type: dict
prognostic

A composite of the TendencyComponent and ImplicitPrognostic objects used by the TendencyStepper.

Type: ImplicitTendencyComponentComposite
prognostic_list

A list of TendencyComponent objects called by the TendencyStepper. These should be referenced when determining what inputs are necessary for the TendencyStepper.

Type: list of TendencyComponent and ImplicitPrognosticComponent
tendencies_in_diagnostics

A boolean indicating whether this object will put tendencies of quantities in its diagnostic output.

Type: bool
time_unit_name

The unit to use for time differencing when putting tendencies in diagnostics.

Type: str
time_unit_timedelta

A timedelta corresponding to a single time unit as used for time differencing when putting tendencies in diagnostics.

Type: timedelta
name

A label to be used for this object, for example as would be used for Y in the name “X_tendency_from_Y”.

Type: string
__call__(state, timestep)[source]

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. diagnostics (dict) – Diagnostics from the timestep of the input state. new_state (dict) – The model state at the next timestep.
__init__(*args, **kwargs)[source]

Initialize the TendencyStepper.

Parameters: *args (TendencyComponent or ImplicitTendencyComponent) – Objects to call for tendencies when doing time stepping. tendencies_in_diagnostics (bool, optional) – A boolean indicating whether this object will put tendencies of quantities in its diagnostic output. Default is False. If set to True, you probably want to give a name also. name (str) – A label to be used for this object, for example as would be used for Y in the name “X_tendency_from_Y”. By default the class name is used.
__repr__()[source]

Return repr(self).

__str__()[source]

Return str(self).

array_call(state, timestep)[source]

Gets diagnostics from the current model state and steps the state forward in time according to the timestep.

Parameters: state (dict) – A numpy array state dictionary. Instead of data arrays, should include numpy arrays that satisfy the input_properties of this object. timestep (timedelta) – The amount of time to step forward. diagnostics (dict) – Diagnostics from the timestep of the input state, as numpy arrays. new_state (dict) – A dictionary whose keys are strings indicating state quantities and values are the value of those quantities at the timestep after input state, as numpy arrays.
class sympl.AdamsBashforth(*args, **kwargs)[source]

A TendencyStepper using the Adams-Bashforth scheme.

__init__(*args, **kwargs)[source]

Initialize an Adams-Bashforth time stepper.

Parameters: *args (TendencyComponent or ImplicitTendencyComponent) – Objects to call for tendencies when doing 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(*args, **kwargs)[source]

A TendencyStepper 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}$.

__init__(*args, **kwargs)[source]

Initialize a Leapfrog time stepper.

Parameters: *args (TendencyComponent or ImplicitTendencyComponent) – Objects to call for tendencies when doing 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.