FieldExchanger

This module contains general functions for the exchange of fields between the atmospheric and surface component models.

The main function of the FieldExchanger is exchange!, which does the following:

imports atmospheric fields into the coupler fields, via import_atmos_fields!
imports area fraction-weighted surface fields into the coupler fields, via import_combined_surface_fields!
updates all component models with the newly-updated coupler fields, via update_model_sims!

The specific fields that are exchanged depend on the requirements of the component models:

The fields imported from the atmosphere to the coupler are specified by extending FieldExchanger.import_atmos_fields! The default import_atmos_fields! imports radiative fluxes, liquid precipitation, and snow precipitation.

The fields of a component model that get updated by the coupler are specified by extending FieldExchanger.update_sim! The default update_sim! for an atmosphere model updates the direct and diffuse surface albedos, the surface temperature, and the turbulent fluxes. The default update_sim! for a surface model updates the air density, radiative fluxes, liquid precipitation, and snow precipitation. These updates are done via the update_field! function, which must be extended for the particular variable and component model. If an update_field! function is not defined for a particular component model, it will be ignored.

FieldExchanger API

ClimaCoupler.FieldExchanger.update_sim! — Function

update_sim!(atmos_sim::Interfacer.AtmosModelSimulation, csf)

Updates the surface fields for temperature, roughness length, albedo, and specific humidity.

Arguments

atmos_sim: [Interfacer.AtmosModelSimulation] containing an atmospheric model simulation object.
csf: [NamedTuple] containing coupler fields.

source

update_sim!(sim::SurfaceModelSimulation, csf, area_fraction)

Updates the surface component model cache with the current coupler fields besides turbulent fluxes.

Arguments

sim: [Interfacer.SurfaceModelSimulation] containing a surface model simulation object.
csf: [NamedTuple] containing coupler fields.

source

ClimaCoupler.FieldExchanger.step_model_sims! — Function

step_model_sims!(model_sims, t)
step_model_sims!(cs::CoupledSimulation)

Iterates step! over all component model simulations saved in cs.model_sims.

Arguments

model_sims: [NamedTuple] containing ComponentModelSimulations.
t: [AbstractFloat or ITime] denoting the simulation time.

source

ClimaCoupler.FieldExchanger.update_surface_fractions! — Function

update_surface_fractions!(cs::Interfacer.CoupledSimulation)

Updates dynamically changing area fractions. Maintains the invariant that the sum of area fractions is 1 at all points. Area fractions are expected to be defined on the boundary space of the coupled simulation, since they are used by the coupler.

If a surface model is not present, the area fraction is set to 0.

Arguments

cs: [Interfacer.CoupledSimulation] containing area fraction information.

source

ClimaCoupler.FieldExchanger.exchange! — Function

exchange!(cs::Interfacer.CoupledSimulation)

Exchange fields between the surface and atmosphere models. This is done in 2 steps:

Import the atmosphere fields and surface fields into the coupler.
Update the component model simulations with the coupler fields.

The order of these steps is important, as importing the surface fields requires the atmosphere fields to be updated so that surface humidity can be computed.

source

ClimaCoupler.FieldExchanger.set_caches! — Function

set_caches!(cs::Interfacer.CoupledSimulation)

Perform any initialization of the component model caches that cannot be done before the initial exchange. This is useful in handling cache interdependencies between component models.

For example, the radiation callback in the atmosphere model needs to be initialized with the surface temperatures, which are only available after the initial exchange. The integrated land, in turn, requires its drivers in the cache to be filled with the initial radiation fluxes, so that it can propagate these to the rest of its cache (e.g. in canopy radative transfer).

source

FieldExchanger Internal Functions

ClimaCoupler.FieldExchanger.combine_surfaces! — Function

combine_surfaces!(combined_field::CC.Fields.Field, sims, field_name::Val)

Sums the fields, specified by field_name, weighted by the respective area fractions of all surface simulations. THe result is saved in combined_field.

Arguments

combined_field: [CC.Fields.Field] output object containing weighted values.
sims: [NamedTuple] containing simulations .
field_name: [Val] containing the name Symbol of the field t be extracted by the Interfacer.get_field functions.

Example

combine_surfaces!(temp_field, cs.model_sims, Val(:surface_temperature))

source