Simulations

LandSimulation{
    M <: ClimaLand.AbstractModel,
    T <: ClimaTimeSteppers.TimeSteppingAlgorithm,
    UC,
    DI,
    RC,
    CA <: ClimaTimeSteppers.CallbackSet,
    I <: ClimaTimeSteppers.TimeStepperIntegrator,
}

the ClimaLand LandSimulation struct, which specifies

• the discrete set of equations to solve (defined by the model);
• the timestepping algorithm;
• user callbacks (passed as a tuple) to be executed at specific times in the simulations;
• the diagnostics to output (optional).

User callbacks are optional: examples currently include callbacks that estimate the time to solution and SYPD of the simulation as it runs, checkpoint the state, or check the solution for NaNs. Others can be added here.

Diagnostics are implemented as callbacks, and are also optional. However, a default is provided. diagnostics is expected to be a list of ClimaDiagnostics.ScheduledDiagnostics.

Finally, the private field requiredcallbacks consists of callbacks that are required for the simulation to run correctly. Currently, this includes the callbacks which update the atmospheric forcing and update the LAI using prescribed data.

step!(landsim::LandSimulation)

Advances the land simulation landsim forward in time by one step, updating landsim in place.

solve!(landsim::LandSimulation)

Advances the land simulation landsim forward from the initial to final time, updating landsim in place.

make_set_initial_state_from_file(ic_path, land::LandModel{FT}; enforce_constraints=false) where {FT}

Returns a function which takes (Y,p,t0,land) as arguments, and updates the state Y in place with initial conditions from ic_path, a netCDF file. Fields in the cache p are used as pre-allocated memory and are updated as well, but this does not mean that the cache state is consitent with Y and t entirely.

Currently only tested and used for global simulations, but the same returned function should work for column simulations.

The returned function is a closure for ic_path. It could also be for land, as many other ClimaLand functions are, but we wish to preserve the argument land in set_ic! for users who wish to define their own initial condition function, which may require parameters, etc, stored in land.

If enforce_constraints = true, we ensure the soil water content is between porosity and the residual value, and that the temperature is bounded to be within the extrema of the air temperature at the surface.

It is assumed that in CoupledAtmosphere simulations that p.drivers has been updated already.

make_set_initial_state_from_file(ic_path, land::SoilCanopyModel{FT}; enforce_constraints = false) where {FT}

Returns a function which takes (Y,p,t0,land) as arguments, and updates the state Y in place with initial conditions from ic_path, a netCDF file. Fields in the cache p are used as pre-allocated memory and are updated as well, but this does not mean that the cache state is consitent with Y and t entirely.

Currently only tested and used for global simulations, but the same returned function should work for column simulations.

The returned function is a closure for ic_path. It could also be for land, as many other ClimaLand functions are, but we wish to preserve the argument land in set_ic! for users who wish to define their own initial condition function, which may require parameters, etc, stored in land.

If enforce_constraints = true, we ensure the soil water content is between porosity and the residual value, and that the temperature is bounded to be within the extrema of the air temperature at the surface.

It is assumed that in CoupledAtmosphere simulations that p.drivers has been updated already.

make_set_initial_state_from_file(ic_path, model::ClimaLand.Soil.EnergyHydrology{FT}; enforce_constraints = false) where {FT}

Returns a function which takes (Y,p,t0,model) as arguments, and updates the state Y in place with initial conditions from ic_path, a netCDF file. Fields in the cache p are used as pre-allocated memory and are updated as well, but this does not mean that the cache state is consitent with Y and t entirely.

Currently only tested and used for global simulations, but the same returned function should work for column simulations.

The returned function is a closure for ic_path. It could also be for model, as many other ClimaLand functions are, but we wish to preserve the argument model in set_ic! for users who wish to define their own initial condition function, which may require parameters, etc, stored in model.

If enforce_constraints = true, we ensure the soil water content is between porosity and the residual value, and that the temperature is bounded to be within the extrema of the air temperature at the surface.

It is assumed that in CoupledAtmosphere simulations that p.drivers.T has been updated already.

make_set_initial_state_from_file(ic_path, model::ClimaLand.Bucket.BucketModel)

Returns a function which takes (Y,p,t0,model) as arguments, and updates the state Y of the BucketModel in place with initial conditions from ic_path, a path to a netCDF file with variables W, Ws, T, and S.

The returned function is a closure for ic_path and model.

make_set_subseasonal_initial_conditions(ic_path)

Creates and returns a function set_ic!(Y,p,t,model) which updates Y in place with the subseasonal initial conditions from the file ic_path. These initial conditions are analytical for some variables and read in from file for others.

The input file ic_path is expected to contain the following variables:

• "tsn": snow temperature
• "swe": snow water equivalent
• "skt": skin temperature of the land surface
• "swvl": soil total water content
• "stl": soil temperature

make_set_initial_state_from_atmos_and_parameters(
           land::ClimaLand.Bucket.BucketModel
)

Returns a function setic!(Y,p,t0,bucket) which sets the bucket initial conditions like: Y.bucket.W .= bucket.parameters.Wf Y.bucket.Ws .= 0 Y.bucket.σS .= 0 Y.bucket.T .= p.drivers.T # at every level

It is assumed that in CoupledAtmosphere simulations that p.drivers.T has been updated already.

make_set_initial_state_from_atmos_and_parameters(land::LandModel{FT}) where {FT}

Returns a function which takes (Y,p,t0,land) as arguments, and updates the state Y in place with initial conditions from parameter values and the atmospheric temperature.

It is assumed that in CoupledAtmosphere simulations that p.drivers.T has been updated already.

set_canopy_component_initial_conditions!(Y, p, model::ClimaLand.Canopy.AbstractCanopyComponent, canopy)

Sets the initial state of the canopy component in Y.

set_canopy_component_initial_conditions!(Y, p, model::ClimaLand.Canopy.BigLeafEnergyModel, canopy)

Sets the initial state of the canopy energy component in Y using the air temperature.

set_canopy_component_initial_conditions!(
    Y,
    p,
    model::ClimaLand.Canopy.ZhouOptimalLAIModel{FT},
    canopy,
    ic_path = ClimaLand.Artifacts.optimal_lai_initial_conditions_path(;
        context = ClimaComms.context(axes(Y.canopy.biomass.LAI)),
    ),
) where {FT}

Sets the optimal-LAI prognostic state — the leaf area index LAI and the trailing potential-GPP and precipitation totals A0_daily, A0_annual, precip_annual, stored in Y.canopy.biomass — using the values in the netCDF file at ic_path, which must contain the variables lai_init, a0_annual and precip_annual on a (lon, lat) grid.

With the default IC path, LAI starts from the MODIS observation, which reduces spin-up relative to the model equilibrium and matches observed vegetation patterns. The annual totals start at their climatological values, which are their steady state and are independent of the smoothing timescale tau_long_term; A0_daily, a one-day total, starts at the corresponding daily share of the annual total.

set_canopy_component_initial_conditions!(
    Y,
    p,
    model::ClimaLand.Canopy.PModel{FT},
    canopy,
) where {FT}

Sets the PModel initial conditions: the acclimated capacities are those optimal for the initial atmospheric state under a nominal midday light level, rather than under the instantaneous one, so that a simulation starting at night does not begin with zero capacities and spend ~1 month (two e-folding timescales of α) climbing out of them.

The capacities are canopy-level and linear in absorbed light, so the nominal light level is scaled by the vegetated fraction of the column: over an inland water cell, where the canopy area indices are masked to zero, the acclimated capacities start at zero as well, and no phantom canopy respiration is carried into the run.

An alternative to this approach is to initialize the initial optimal values to some reasonable values based on a spun-up simulation.