Drivers

PrescribedAtmosphere{FT, CA, DT} <: AbstractAtmosphericDrivers{FT}

Container for holding prescribed atmospheric drivers and other information needed for computing turbulent surface fluxes when driving land models in standalone mode.

The default CO2 concentration is a constant as a function of time, equal to 4.2e-4 mol/mol.

Since not all models require co2 concentration, the default for that is nothing.

• liquid_precip: Precipitation (m/s) function of time: positive by definition

• snow_precip: Snow precipitation (m/s) function of time: positive by definition

• T: Prescribed atmospheric temperature (function of time) at the reference height (K)

• u: Prescribed wind speed (function of time) at the reference height (m/s)

• q: Prescribed specific humidity (function of time) at the reference height (_)

• P: Prescribed air pressure (function of time) at the reference height (Pa)

• c_co2: CO2 concentration in atmosphere (mol/mol)

• start_date: Start date - the datetime corresponding to t=0 for the simulation

• h: Reference height (m), relative to surface elevation

• gustiness: Minimum wind speed (gustiness; m/s)

• thermo_params: Thermodynamic parameters

PrescribedPrecipitation{FT, LP} <: AbstractAtmosphericDrivers{FT}

Container for holding prescribed precipitation driver for models which only require precipitation (RichardsModel).

• liquid_precip: Precipitation (m/s) function of time: positive by definition

PrescribedRadiativeFluxes{FT, SW, LW, DT, T, TP} <: AbstractRadiativeDrivers{FT}

Container for the prescribed radiation functions needed to drive land models in standalone mode.

Note that some models require the zenith angle AND diffuse fraction. The diffuse fraction may be provided directly (of type TimeVaryingInput), or it may be computed empirically. In the latter case, it requires the thermodynamic parameters as well to compute.

Therefore, the allowed combinations are:

1. Zenith angle and diffuse fraction not needed: zenith angle=nothing, thermo_params=nothing, diffuse fraction=nothing
2. Zenith angle provided and diffuse fraction computed empirically: thermo params used, diffuse fraction=nothing
3. Zenith angle provided and diffuse fraction provided: thermo_params not used, diffuse fraction TimeVaryingInput

• SW_d: Downward shortwave radiation function of time (W/m^2): positive indicates towards surface

• frac_diff: Diffuse Fraction of shortwave radiation (unitless, [0,1])

• LW_d: Downward longwave radiation function of time (W/m^2): positive indicates towards surface

• start_date: Start date - the datetime corresponding to t=0 for the simulation

• θs: Sun zenith angle, in radians

• thermo_params: Thermodynamic parameters

 PrescribedSoilOrganicCarbon{FT}

A type for prescribing soil organic carbon.

• soc: Soil organic carbon, function of time and space: kg C/m^3

CoupledAtmosphere{FT} <: AbstractAtmosphericDrivers{FT}

To be used when coupling to an atmosphere model. Contains fields that are used to compute surface fluxes in the coupled setup.

When constructed without a space, the struct doesn't contain anything, but it still acts as a flag that fluxes have been updated by the coupler and don't need to be recomputed. When constructed with a space, the struct contains the fields needed to compute surface fluxes in the coupled setup, which are accessed by ClimaCoupler.

CoupledRadiativeFluxes{
    FT,
    F <: Union{Function, Nothing},
    T,
} <: AbstractRadiativeDrivers{FT}

To be used when coupling to an atmosphere model. Either both θs and start_date must be nothing, or both must not be nothing`.

During the driver update, cosθs is unchanged if θs is nothing. This behavior differs from the PrescribedRadiativeFluxes where cosθs set to NaN if θs is nothing. Otherwise, θs recieves the following arguments: (timefromstart, start_date), and is expected to return zenith angle at the given time.

• θs: Function that fills a climacore field with the zenith angle given the following arguments: (timefromstart, start_date)

• start_date: Start date - the datetime corresponding to t=0 for the simulation

 AbstractAtmosphericDrivers{FT}

An abstract type of atmospheric drivers of land models.

 AbstractRadiativeDrivers{FT}

An abstract type of radiative drivers of land models.

turbulent_fluxes!(dest,
                  atmos::PrescribedAtmosphere,
                  model::AbstractModel,
                  Y::ClimaCore.Fields.FieldVector,
                  p::NamedTuple,
                  t
                  )

Computes the turbulent surface flux terms at the ground for a standalone simulation, including turbulent energy fluxes as well as the water vapor flux (in units of m^3/m^2/s of water). Positive fluxes indicate flow from the ground to the atmosphere.

It solves for these given atmospheric conditions, stored in atmos, model parameters, and the surface conditions.

turbulent_fluxes!(dest,
                atmos::CoupledAtmosphere,
                model::AbstractModel,
                Y,
                p,
                t)

Computes the turbulent surface fluxes terms at the ground for a coupled simulation. In this case, the coupler has already computed turbulent fluxes and updated them in each of the component models, so this function does nothing.

function ClimaLand.turbulent_fluxes!(
    dest,
    atmos::PrescribedAtmosphere,
    model::CanopyModel,
    Y::ClimaCore.Fields.FieldVector,
    p::NamedTuple,
    t,
)

A canopy specific function for compute turbulent fluxes with the atmosphere; returns the latent heat flux, sensible heat flux, vapor flux, and aerodynamic resistance.

We cannot use the default version in src/shared_utilities/drivers.jl because the canopy requires a different resistance for vapor and sensible heat fluxes, and the resistances depend on ustar, which we must compute using SurfaceFluxes before adjusting to account for these resistances.

turbulent_fluxes_at_a_point(return_extra_fluxes, args...)

This is a wrapper function that allows us to dispatch on the type of return_extra_fluxes as we compute the turbulent fluxes pointwise. This is needed because space for the extra fluxes is only allocated in the cache when running with a CoupledAtmosphere. The function compute_turbulent_fluxes_at_a_point does the actual flux computation.

The return_extra_fluxes argument indicates whether to return the following:

• momentum fluxes (ρτxz, ρτyz)
• buoyancy flux (buoy_flux)

set_atmos_ts!(ts_in, atmos::PrescribedAtmosphere{FT}, p)

Fill the pre-allocated ts_in Field with a thermodynamic state computed from the atmosphere.

ClimaLand.surface_air_density(
                atmos::CoupledAtmosphere,
                model::BucketModel,
                Y,
                p,
                _...,
            )

Returns the air density at the surface in the case of a coupled simulation.

This requires the field ρ_sfc to be present in the cache p under the name of the model.

surface_air_density(
                    atmos::PrescribedAtmosphere,
                    model::AbstractModel,
                    Y,
                    p,
                    t,
                    T_sfc,
                    )

A helper function which returns the surface air density; this assumes that the model has a property called parameters containing earth_param_set.

We additionally include the atmos type as an argument because the surface air density computation will change between a coupled simulation and a prescibed atmos simulation.

Extending this function for your model is only necessary if you need to compute the air density in a different way.

surface_air_density(
                    atmos::CoupledAtmosphere,
                    model::AbstractModel,
                    Y,
                    p,
                    t,
                    T_sfc,
                    )

A helper function which returns the surface air density; this assumes that the model has a property called parameters containing earth_param_set.

This method is similar to the general method above, except in this case we get the thermodynamic parameters from the atmos object. This is used when running with a coupled atmosphere.

ClimaLand.surface_temperature(
    model::EnergyHydrology{FT},
    Y,
    p,
    t,
) where {FT}

Returns the surface temperature field of the EnergyHydrology soil model.

The assumption is that the soil surface temperature is the same as the temperature at the center of the first soil layer.

ClimaLand.surface_temperature(model::SnowModel, Y, p)

a helper function which returns the surface temperature for the snow model, which is stored in the aux state.

ClimaLand.surface_temperature(model::BucketModel, Y, p)

a helper function which returns the surface temperature for the bucket model, which is stored in the aux state.

surface_temperature(model::AbstractModel, Y, p, t)

A helper function which returns the surface temperature for a given model, needed because different models compute and store surface temperature in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

ClimaLand.surface_temperature(model::CanopyModel, Y, p, t)

A helper function which returns the temperature for the canopy model.

surface_resistance(model::AbstractModel, Y, p, t)

A helper function which returns the surface resistance for a given model, needed because different models compute and store surface resistance in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

The default is 0, which is no additional resistance aside from the usual aerodynamic resistance from MOST.

ClimaLand.surface_resistance(
    model::CanopyModel{FT},
    Y,
    p,
    t,
) where {FT}

Returns the stomatal resistance field of the CanopyModel canopy.

ClimaLand.surface_specific_humidity(atmos::PrescribedAtmosphere, model::SnowModel, Y, p, _...)

Returns the precomputed specific humidity over snow as a weighted fraction of the saturated specific humidity over liquid and frozen water.

In the case of a PrescibedAtmoshere, the atmosphere thermal state is accessed from the drivers in the cache.

ClimaLand.surface_specific_humidity(atmos::CoupledAtmosphere, model::SnowModel, Y, p, _...)

Returns the precomputed specific humidity over snow as a weighted fraction of the saturated specific humidity over liquid and frozen water.

In the case of a CoupledAtmoshere, the atmosphere thermal state is accessed from the atmosphere object.

ClimaLand.surface_specific_humidity(atmos, model::BucketModel, Y, p)

a helper function which returns the surface specific humidity for the bucket model, which is stored in the aux state.

surface_specific_humidity(atmos, model::AbstractModel, Y, p, T_sfc, ρ_sfc)

A helper function which returns the surface specific humidity for a given model, needed because different models compute and store q_sfc in different ways and places.

Extending this function for your model is only necessary if you need to compute surface fluxes and radiative fluxes at the surface using the functions in this file.

default_zenith_angle(
    t::T,
    start_date::Dates.DateTime;
    latitude::LT,
    longitude::LT,
    insol_params::Insolation.Parameters.InsolationParameters{FT},
)

Calculate zenith angle with Insolation for the given start date, insolation parameters, latitude, and longitude.

latitude and longitude can be a collections or a Number.

 prescribed_forcing_era5(era5_ncdata_path,
                         surface_space,
                         start_date,
                         earth_param_set,
                         FT;
                         gustiness=1,
                         max_wind_speed = nothing,
                         c_co2 = TimeVaryingInput((t) -> 4.2e-4),
                         time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
                         regridder_type = :InterpolationsRegridder,
                         interpolation_method = Interpolations.Constant(),)

A helper function which constructs the PrescribedAtmosphere and PrescribedRadiativeFluxes from a file path pointing to the ERA5 data in a netcdf file, the surfacespace, the start date, and the earthparam_set.

The argument era5_ncdata_path is either a list of nc files, each with all of the variables required, but with different time intervals in the different files, or else it is a single file with all the variables.

The ClimaLand default is to use nearest neighbor interpolation, but linear interpolation is supported by passing interpolation_method = Interpolations.Linear().

########## WARNING ##########

High wind speed anomalies (10-100x increase and decrease over a period of a several hours) appear in the ERA5 reanalysis data. These generate very large surface fluxes (due to wind speeds up to 300 m/s), which lead to instability. The kwarg maxwindspeed, with a value give in m/s, is used to clip these if it is not nothing. See: https://confluence.ecmwf.int/display/CKB/ERA5%3A+large+10m+winds