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.
Returns: - 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.
-
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.
Returns: - 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.
-