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 use the StateVariables constructor:

Terrarium.StateVariables — Method
StateVariables(
    model::Terrarium.AbstractModel{NF};
    ...
) where NF -> StateVariables
StateVariables(
    model::Terrarium.AbstractModel{NF},
    params;
    clock,
    input_variables,
    boundary_conditions,
    initializers,
    fields
) where NF -> StateVariables

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. The time stepper cache is allocated from the model's timestepper.

source
StateVariables(
    process::Terrarium.AbstractProcess{NF},
    grid::Oceananigans.Grids.AbstractGrid{NF};
    ...
) where NF
StateVariables(
    process::Terrarium.AbstractProcess{NF},
    grid::Oceananigans.Grids.AbstractGrid{NF},
    params;
    clock,
    input_variables,
    timestepper,
    boundary_conditions,
    initializers,
    fields
) where NF

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.

The grid may be either a land grid or an ordinary spatial discretization; fields are allocated on whichever is given. AbstractLandGrids resolve variables' VarDomains to a their respective vertical discretization; on an ordinary grid the domain is ignored.

source
StateVariables(
    vars::Terrarium.Variables,
    grid::Oceananigans.Grids.AbstractGrid{NF};
    clock::Clock,
    timestepper,
    model,
    boundary_conditions,
    initializers,
    fields
) where NF -> StateVariables{NF, <:Any, <:Any, <:Any, <:Any, <:Any, ProgFields, TendFields, AuxFields, InputFields, <:Any, Cache, Clock{Float64, Float64, Float64, Int64, Int64}} where {NF, ProgFields<:Tuple, TendFields<:Tuple, AuxFields<:Tuple, InputFields<:Tuple, Cache<:Terrarium.EmptyCache}

Initialize a StateVariables data structure containing Fields defined on the given grid for all variables in vars. Any predefined boundary_conditions and fields will be passed through to initialize for each variable. The timestepper's cache is allocated via initialize(timestepper, state, progvars).

The grid may be either a land grid or an ordinary spatial discretization; fields are allocated on whichever is given. Only an AbstractLandGrid resolves a variable's VarDomain to a per-domain discretization; on an ordinary grid the domain is ignored.

source
Terrarium.StateVariables — Method
StateVariables(
    process::Terrarium.AbstractProcess{NF},
    grid::Oceananigans.Grids.AbstractGrid{NF};
    ...
) where NF
StateVariables(
    process::Terrarium.AbstractProcess{NF},
    grid::Oceananigans.Grids.AbstractGrid{NF},
    params;
    clock,
    input_variables,
    timestepper,
    boundary_conditions,
    initializers,
    fields
) where NF

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.

The grid may be either a land grid or an ordinary spatial discretization; fields are allocated on whichever is given. AbstractLandGrids resolve variables' VarDomains to a their respective vertical discretization; on an ordinary grid the domain is ignored.

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
mutable struct StateVariables{NF, prognames, closurenames, auxnames, inputnames, nsnames, ProgFields, TendFields, AuxFields, InputFields, Namespaces, Cache, 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.

Field initializers

Reusable, parameterized initializers of a single Field subtype AbstractFieldInitializer. They are accepted everywhere a set!-compatible value is: in the initializers keyword argument, as the default of an input variable, or as a parameter of a model initializer. In the latter case, their @param fields become parameters of the model.

Terrarium.AbstractFieldInitializer — Type

Base type for reusable initializers of a single Field. Implementations should provide a dispatch of initialize!(field, grid, init::AbstractFieldInitializer). The default evaluates init as a callable at the node coordinates of field, i.e. init(coords...), via set!.

A field initializer is accepted everywhere a set!-compatible value is: as the default of an input variable, as an entry of the initializers keyword argument of initialize, or as a parameter of a model AbstractInitializer. In the latter case it may declare @param fields, which are then exposed as model parameters.

source
Terrarium.LatitudinalClimatology — Type
struct LatitudinalClimatology{NF} <: Terrarium.AbstractFieldInitializer

Latitude-dependent surface temperature climatology (°C):

T(φ) = T_equator - |ΔT sin φ|

where φ is the latitude in degrees. Supported on a ColumnRingGrid, where it is evaluated on the host at the latitude of each active column, and on a LatitudeLongitudeGrid, where it is evaluated at the latitude of each node.

Properties:

  • T_equator::Any: Mean annual surface temperature at the equator (°C)

  • ΔT::Any: Temperature difference between the equator and the poles (°C)

source

Field initializers that depend on geographic position can use λnodes and φnodes, which return longitudes and latitudes (degrees) on both an Oceananigans LatitudeLongitudeGrid and a ColumnRingGrid. On the latter, they are indexed by active column.

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.

Model initializers may also implement variables to declare input variables for their parameters. These are collected by variables(model) alongside the process variables, which allows initial values to vary in space and to be supplied by InputSources.

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.