GitHub

Initialization

Overview

Model and process types in Terrarium are stateless and immutable; i.e. they only specify parameters and model configuration. To allocate state variables for a model or process, we need to use the initialize method:

Terrarium.initialize — Method
initialize(
    model::Terrarium.AbstractModel{NF, Grid} where Grid<:(Terrarium.AbstractLandGrid{NF});
    clock,
    input_variables,
    boundary_conditions,
    initializers,
    fields
) -> StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType<:(Clock{_A, Float64, Int64, Int64} where _A)}

Initialize a StateVariables data structure containing Fields for all variables defined by model defined on its associated grid. The clock specifies the initial simulation time and is mutated on each time step. User-specified boundary_conditions and initializers can be provided as NamedTuples with keys corresponding to the names of state variables to which they should be applied. If the state variables are defined within namespaces, the given NamedTuple must follow the same structure. The fields argument allows for manual preconstruction of Fields for the named state variables.

source
Terrarium.initialize — Method
initialize(
    process::Terrarium.AbstractProcess{NF},
    grid::Terrarium.AbstractLandGrid{NF};
    clock,
    input_variables,
    boundary_conditions,
    initializers,
    fields
) -> StateVariables{NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType} where {NF, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, ClockType<:(Clock{_A, Float64, Int64, Int64} where _A)}

Initialize a StateVariables data structure containing Fields defined on the given grid for all variables defined by process. Any predefined boundary_conditions and fields will be passed through to initialize for each variable.

source

which will create and return a StateVariables structure containing all of the initialized Fields corresponding to state variables defined by the model/process.

Terrarium.StateVariables — Type
struct StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, ClockType} <: Terrarium.AbstractStateVariables

Container type for all Fields corresponding to state variables defined by a model. StateVariables partitions the fields into three categories: prognostic, tendencies, and auxiliary. Prognostic variables are those which characterize the state of the system and are assigned tendencies to be integrated by the timestepper. Auxiliary fields are additional state variables derived from the prognostic state variables but which are conditionally independent of their values at the previous time step given the current prognostic state. It is worth noting that tendencies are also treated internally as auxiliary variables; however, they are assigned their own category here since they need to be handled separately by the timestepping scheme.

source

By default, Fields will be initialized with zeros. Some state variable types, such as input variables, allow for the specification of alternative default values.

Of course, very few models can do anything useful or interesting starting from (literally) zero. Terrarium provides three complementary mechanisms through which initialization routines for model/process state variables can be defined:

  • Direct initialization via the initializers keyword argument of initialize
  • AbstractInitializer types specified in models encapsulate a sequence of initialization routines
  • Model and process specific dispatches of initialize!

As a general rule, these initializers are invoked in the order that they are listed above. Implementations of initialize! should generally assume that the prognostic state has already been initialized by corresponding Field or model initializers.

Direct initialization of Fields

The keyword argument must be a NamedTuple where the keys correspond to the name of the state variable and the values are either scalars, arrays matching the size of the model grid, or functions of the form f(coords...) where coords are the non-Flat dimensions of grid. For column-based grids, this is generally f(x,z) with x corresponding to a column index.

Model initializers

These Initializer types can be supplied to subtypes of AbstractModel during construction. Models can/should typically define corresponding AbstractInitializer types that represent common initialization strategies appropriate for the processes included in that model; e.g. the SoilModel defines SoilInitializer with process-specific initialization types like QuasiThermalSteadyState and SaturationWaterTable.

Built-in initialization routines

Model/process specific dispatches of initialize! can be defined for process initialization logic that should be run regardless of the choice of prognostic state variable initialization.