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

• cosθs: Sun zenith angle, in radians

• thermo_params: Thermodynamic parameters

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 cosθs and start_date must be nothing, or both must not be nothing`.

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

• cosθ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

 PrescribedGroundConditions <: AbstractGroundConditions

A container for holding prescribed ground conditions needed by the canopy model when running the canopy in standalone mode, including the surface temperature, albedo, and emissivity, and soil water content, porosity, residual water fraction, and hydrology closure model.

Note that internally we enforce that the soil water content θ must be within the range (θ\_r, ν].

• θ: Prescribed soil water content (m^3/m^3) in the root zone as a function of time

• T: Prescribed ground surface temperature (K) as a function of time

• α_PAR: Ground albedo for PAR

• α_NIR: Ground albedo for NIR

• ϵ: Ground emissivity

• ν: Soil porosity (m^3/m^3

• θ_r: The soil residual water fraction (m^3/m^3)

• hydrology_cm: The soil hydrology closure model: van Genuchten or Brooks and Corey

 PrognosticGroundConditions <: Canopy.AbstractGroundConditions

A type of AbstractGroundConditions to use when running the CanopyModel as part of an integrated model, i.e. with a prognostic EnergyHydrology soil model and either with or without a snow model.

Note that this struct is linked with the EnergyHydrology/SnowModel models. If we ever had a different soil model, we might need to construct a different PrognosticGroundConditions because the fields may be stored in different places.

 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::AbstractAtmosphericDrivers,
                  model::AbstractModel,
                  Y,
                  p,
                  t
                  )

Computes the turbulent surface flux terms at the ground, 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, model parameters, and the surface conditions.

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 momentum fluxes (ρτxz, ρτyz) and the bouyancy flux.

ClimaLand.component_temperature(
    model::EnergyHydrology{FT},
    Y,
    p,
) 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.component_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.component_temperature(model::BucketModel, Y, p)

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

component_temperature(model::AbstractModel, Y, p)

A helper function which returns the component temperature for a given model. This is used in the turbulent_fluxes! function as the value of surface temperature and used to compute long wave radiative fluxes.

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. If your model uses different temperatures to compute turbulent fluxes vs long wave radiative fluxes, please see the documentation for an update function in the turbulent_fluxes! call.

ClimaLand.component_temperature(model::CanopyModel, Y, p)

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

ClimaLand.component_specific_humidity(model::EnergyHydrology, Y, p)

a helper function which returns the surface specific humidity for the canopy model.

ClimaLand.component_specific_humidity(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.

This uses the atmospheric T, P, q from p.drivers.

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

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

component_specific_humidity(model::AbstractModel, Y, p)

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 using the functions in this file. Please see the documentation for an update function in the turbulent_fluxes! call.

ClimaLand.component_specific_humidity(model::CanopyModel, Y, p)

a helper function which returns the surface specific humidity for the canopy model.

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

a helper function which returns the surface roughness model for the snow model.

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

a helper function which returns the surface roughness model for the bucket model.

surface_roughness_model(model::AbstractModel, Y, p)

Returns the SurfaceFluxes roughness model for model.

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

ClimaLand.surface_roughness_model(model::CanopyModel, Y, p)

a helper function which returns the surface roughness model for the canopy model.

surface_roughness_model(model::AbstractModel, Y, p)

Returns the displacement height for model.

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

ClimaLand.surface_displacement_height(model::CanopyModel, Y, p)

a helper function which returns the displacement height for the canopy model.

get_update_surface_temperature_function(model::AbstractModel, Y, p)

Returns the SurfaceFluxes update_T_sfc function for model.

This is only required if the output of component_temperature does not coincide with the temperature that should be used to compute turbulent fluxes.

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

ClimaLand.get_update_surface_temperature_function(model::CanopyModel, Y, p)

a helper function which computes and returns the function which updates the guess for surface temperature to the actual value, for the canopy model.

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

a helper function which creates and returns a function which modifies q_sfc given the evaporative scaling factor β and the air humidity.

get_update_surface_specific_humidity_function(model::AbstractModel, Y, p)

Returns the SurfaceFluxes update_T_sfc function for model.

This is only required if the output of component_temperature does not coincide with the temperature that should be used to compute turbulent fluxes.

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

ClimaLand.get_update_surface_humidity_function(model::CanopyModel, Y, p)

a helper function which computes and returns the function which updates the guess for surface specific humidity to the actual value, for the canopy model.

get_∂T_sfc∂T_function(model::AbstractModel, Y, p)

Returns a function which computes the partial derivative of the surface temperature using in turbulentfluxes! with respect to the component temperature. The expected arguments are (ustar, gh, earthparam_set).

This is only required if the output of component_temperature does not coincide with the temperature that should be used to compute turbulent fluxes, and if your model requires derivatives of the fluxes with respect to the component temperature.

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

ClimaLand.get_∂T_sfc∂T_function(model::CanopyModel, Y, p)

a helper function which creates and returns the function which computes the partial derivative of the surface temperature with respect to the canopy temperature.

get_∂q_sfc∂T_function(model::AbstractModel, Y, p)

Returns a function which computes the partial derivative of the surface humidity using in turbulentfluxes! with respect to the component temperature. The expected arguments are (ustar, gh, Tsfc, Psfc, earthparam_set).

This is only required if the output of component_specific_humidity does not coincide with the humidity that should be used to compute turbulent fluxes, and if your model requires derivatives of the fluxes with respect to the component temperature.

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

ClimaLand.get_∂q_sfc∂T_function(model::CanopyModel, Y, p)

a helper function which creates and returns the function which computes the partial derivative of the surface specific humididity with respect to the canopy temperature.

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

Calculate cosine of the zenith angle with Insolation for the given start date, insolation parameters, latitude, and longitude. Note that Insolation.jl returns 0 for the cosine when the sun is below the horizon.

latitude and longitude can be a collections or a Number.

prescribed_forcing_era5(start_date,
                        stop_date,
                        surface_space,
                        toml_dict::CP.ParamDict,
                        FT;
                        use_lowres_forcing = false,
                        gustiness=1,
                        max_wind_speed = nothing,
                        c_co2 = TimeVaryingInput((t) -> 4.2e-4),
                        time_interpolation_method = LinearInterpolation(PeriodicCalendar()),
                        regridder_type = :InterpolationsRegridder,
                        context = nothing,
                        )

A helper function which constructs the PrescribedAtmosphere and PrescribedRadiativeFluxes from ERA5 data stored in NetCDF files.

There are two versions of the ERA5 data available through ClimaLand:

• a high resolution version (1° x 1°) available for the years 1979-2024
• a low resolution version (8° x 8°) available only for the year 2008

The high resolution version will be used if use_lowres_forcing = false (the default). This artifact is used for global runs on compute clusters, but is too large to be used for local testing, and requires you to have acquired the data in advance. The low resolution version will be used if use_lowres_forcing = true. If the simulation dates are outside of 2008, the 2008 data will be reused for each year of simulation. This artifact is recommended for local testing or quick runs where accuracy is less critical.

The method for temporal interpolation is controlled via the time_interpolation_method kwarg. We suggest LinearInterpolation(PeriodicCalendar()), which implies linear interpolation in time; the inner argument implies how extrapolation outside the bounds of the data is handled. For example, the ERA5 forcing data we use is hourly, which implies Dec 31 of the last year of the data, at midnight, is not in the data. With the PeriodicCalendar() option, the interpolated value in the data at Jan 1 at timestamp 00 of the first year of the simulation will be used. For the low-resolution forcing data, which only exists for 2008, multi-year runs will repeat the forcing. If this behavior is not what you want, you can change the extrapolation argument to error LinearInterpolation(Throw()) or extrapolate by using the last value `LinearInterpolation(Flat()). More information is available in the ClimaUtilities documentation: https://clima.github.io/ClimaUtilities.jl/dev/inputs/#Extrapolation-boundary-conditions.

The ClimaLand default is to use nearest neighbor spatial interpolation for low resolution forcing, and linear spatial interpolation for high resolution forcing.

prescribed_perturbed_temperature_era5(era5_ncdata_path,
                         surface_space,
                         start_date,
                         toml_dict::CP.ParamDict,
                         ΔT,
                         FT;
                         gustiness=1,
                         max_wind_speed = nothing,
                         c_co2 = TimeVaryingInput((t) -> 4.2e-4),
                         time_interpolation_method = LinearInterpolation(PeriodicCalendar(Dates.Year(1), DateTime(Dates.year(stop_date)))),
                         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 `tomldict`, applying a change in the instantaneous temperature at each point of ΔT, while keeping the relative humidity fixed. The LWd shifts as LWd -> LW_d + aΔT, with a= 2W/m^2/K a surface climate sensitivity parameter.

Please see the documentation for prescribed_forcing_era5 for more information.

 prescribed_perturbed_rh_era5(era5_ncdata_path,
                         surface_space,
                         start_date,
                         toml_dict::CP.ParamDict,
                         Δrh,
                         FT;
                         gustiness=1,
                         max_wind_speed = nothing,
                         c_co2 = TimeVaryingInput((t) -> 4.2e-4),
                         time_interpolation_method = LinearInterpolation(PeriodicCalendar(Dates.Year(1), DateTime(Dates.year(stop_date)))),
                         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 `tomldict`, applying a change in the instantaneous change to relative humidity at each point of Δrh. The perturbed rh is clipped to be within the range (0,1].

Please see the documentation for prescribed_forcing_era5 for more information.

 prescribed_analytic_forcing(FT = Float32;
                             toml_dict::CP.ParamDict,
                             start_date = DateTime(2005),
                             SW_d = (t) -> 0,
                             LW_d = (t) -> 5.67e-8 * 280.0^4.0,
                             precip = (t) -> 0, # no precipitation
                             T_atmos = (t) -> 280.0,
                             u_atmos = (t) -> 1.0,
                             q_atmos = (t) -> 0.0, # no atmos water
                             h_atmos = FT(1e-8),
                             P_atmos = (t) -> 101325,
                             atmos = PrescribedAtmosphere(
                                 TimeVaryingInput(precip),
                                 TimeVaryingInput(precip),
                                 TimeVaryingInput(T_atmos),
                                 TimeVaryingInput(u_atmos),
                                 TimeVaryingInput(q_atmos),
                                 TimeVaryingInput(P_atmos),
                                 start_date,
                                 h_atmos,
                                 LP.LandParameters(toml_dict),
                             ),
                             radiation = PrescribedRadiativeFluxes(
                                 FT,
                                 TimeVaryingInput(SW_d),
                                 TimeVaryingInput(LW_d),
                                 start_date,
                             ),
                         )

A helper function which constructs the PrescribedAtmosphere and PrescribedRadiativeFluxes for a simple analytic case.

net_radiation!(dest::ClimaCore.Fields.Field,
               radiation::PrescribedRadiativeFluxes{FT},
               model::AbstractModel{FT},
               Y::ClimaCore.Fields.FieldVector,
               p::NamedTuple,
               t,
               ) where {FT}

Computes net radiative fluxes for a prescribed incoming longwave and shortwave radiation.

net_radiation!(dest,
              radiation::CoupledRadiativeFluxes,
              model::AbstractModel,
              Y,
              p,
              t)

Computes the net radiative flux at the ground for a coupled simulation. Your model cache must contain the field R_n.

ClimaLand.get_drivers(model::RichardsModel)

Returns the driver variable symbols for the RichardsModel; these depend on the boundary condition type and currently only are required for the RichardsAtmosDrivenFluxBC, which is driven by a prescribed time and space varying precipitation.

ClimaLand.get_drivers(model::SnowModel)

Returns the driver variable symbols for the SnowModel.

get_drivers(model::AbstractModel)

Returns the driver objects for the model - atmospheric and radiative forcing, etc - as a tuple (atmos, radiation, ...). If no drivers are needed by a model, an empty tuple should be returned

ClimaLand.get_drivers(model::LandModel)

Returns the "drivers", or forcing variables, for the LandModel.

These consist of atmospheric and radiative forcing.

make_update_drivers(::AbstractClimaLandDrivers)

Creates and returns a function which updates the driver variables in the default case of no drivers. More generally, this should return a function which updates the driver fields stored in p.drivers.

make_update_drivers(driver_tuple)

Creates and returns a function which updates the forcing variables ("drivers"). If no drivers are being used, driver_tuple is empty, and the update function does nothing.

make_update_drivers(a::PrescribedGroundConditions{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedGroundConditions.

make_update_drivers(a::PrescribedAtmosphere{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedAtmosphere.

make_update_drivers(a::PrescribedPrecipitation{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedPrecipitation.

make_update_drivers(r::CoupledRadiativeFluxes{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a CoupledRadiativeFluxes.

When r.cosθs is nothing, the cosine zenith angle not changed, and should be updated by the coupler. This differs from the behavior of PrescribedRadiativeFluxes, where the cosine zenith angle is set to NaN if cosθs is nothing.

Otherwise, the cosine zenith angle is computed using r.cosθs(t, r.start_date).

make_update_drivers(r::PrescribedRadiativeFluxes{FT}) where {FT}

Creates and returns a function which updates the driver variables in the case of a PrescribedRadiativeFluxes.