This modules contains abstract types and functions to calculate surface fluxes in the coupler, or to call flux calculating functions from the component models.

Fluxes over a heterogeneous surface (e.g., from a gridpoint where atmospheric cell is overlying both land and ocean) can be handled in two different ways:

  1. Combined fluxes (called with CombinedStateFluxes())
  • these are calculated by averaging the surface properties for each gridpoint (e.g., land and ocean temperatures, albedos and roughness lengths are averaged, based on their respective area fractions), so the flux is calculated only once per gridpoint of the grid where we calculate fluxes. This is computationally faster, but it makes the fluxes on surface boundaries more diffuse. Currently, we use this method for calculating radiative fluxes in the atmosphere, and turbulent fluxes in the coupler (on the atmospheric grid). The fluxes are calculated in the atmospheric (host) model's cache, which can be setup to avoid allocating coupler fields.
  1. Partitioned fluxes (called with PartitionedStateFluxes())
  • these are calculated separately for each surface type. It is then the fluxes (rather than the surface states) that are combined and passed to the atmospheric model as a boundary condition. This method ensures that each surface model receives fluxes that correspond to its state properties, resulting in a more accurate model evolution. However, it is more computationally expensive, and requires more communication between the component models.

FluxCalculator API

PartitionedStateFluxes <: TurbulentFluxPartition

A flag indicating that the turbulent fluxes should be partitioned and calculated over each surface model and then combined. This is calculated on the coupler grid.

CombinedStateFluxes <: TurbulentFluxPartition

A flag indicating that the turbulent fluxes (e.g. sensible and latent heat fluxes, drag and moisture fluxes) are to be calculated on the Atmos grid, and saved in Atmos cache.

combined_turbulent_fluxes!(model_sims, csf, turbulent_fluxes::TurbulentFluxPartition)

Calls the method(s) which calculate turbulent surface fluxes from combined surface states in coupler fields, csf.


  • model_sims: [NamedTuple] containing ComponentModelSimulations.
  • csf: [NamedTuple] containing coupler fields.
  • turbulent_fluxes: [TurbulentFluxPartition] denotes a flag for turbulent flux calculation.
atmos_turbulent_fluxes!(sim::Interfacer.ComponentModelSimulation, csf)

A function to calculate turbulent surface fluxes using the combined surface states. It is required that a method is defined for the given sim and that the fluxes are saved in that sim's cache. csf refers to the coupler fields.


  • sim: [Interfacer.ComponentModelSimulation] object containing the component model simulation.
  • csf: [NamedTuple] containing coupler fields.


function atmos_turbulent_fluxes!(atmos_sim::ClimaAtmosSimulation, csf)
    atmos_sim.cache.flux .= atmos_sim.c .* (csf.T_S .- atmos_sim.temperature)
surface_inputs(scheme::AbstractSurfaceFluxScheme, thermo_state_sfc, thermo_state_int, uₕ_int, z_int, z_sfc, z0b, z0m, Ch, Cd, beta, gustiness)

Returns the inputs for the surface model simulation sim.


Returns the surface parameters of type SF.Parameters.SurfaceFluxesParameters.

TODO: in the future this may not need to depend on the atmos sim, but here retaining the dependency until we know how EDMF boundary conditions will be handled (for consistency of parameters).

partitioned_turbulent_fluxes!(model_sims::NamedTuple, fields::NamedTuple, boundary_space::CC.Spaces.AbstractSpace, surface_scheme, thermo_params::TD.Parameters.ThermodynamicsParameters)

The current setup calculates the aerodynamic fluxes in the coupler (assuming no regridding is needed) using adapter function get_surface_fluxes_point!, which calls SurfaceFluxes.jl. The coupler saves the area-weighted sums of the fluxes.


  • model_sims: [NamedTuple] containing ComponentModelSimulations.
  • fields: [NamedTuple] containing coupler fields.
  • boundary_space: [CC.Spaces.AbstractSpace] the space of the coupler surface.
  • surface_scheme: [AbstractSurfaceFluxScheme] the surface flux scheme.
  • thermo_params: [TD.Parameters.ThermodynamicsParameters] the thermodynamic parameters.


  • generalize interface for regridding and take land state out of atmos's integrator.p
  • add flux accumulation
  • add flux bounds

(NB: Radiation surface fluxes are calculated by the atmosphere.)

get_surface_fluxes_point!(inputs, surface_params::SF.Parameters.SurfaceFluxesParameters)

Uses SurfaceFluxes.jl to calculate turbulent surface fluxes. It should be atmos model agnostic, and columnwise.

surface_thermo_state(sim::Interfacer.SurfaceModelSimulation, thermo_params::TD.Parameters.ThermodynamicsParameters, thermo_state_int, colidx::CC.Fields.ColumnIndex)

Returns the surface parameters for the surface model simulation sim. The default is assuming saturated surfaces, unless an extension is defined for the given SurfaceModelSimulation.

water_albedo_from_atmosphere!(cs::Interfacer.CoupledSimulation, _)

Callback to calculate the water albedo from atmospheric state. This is a placeholder for the full radiation callback.

water_albedo_from_atmosphere!(atmos_sim::Interfacer.AtmosModelSimulation, ::CC.Fields.Field, ::CC.Fields.Field)

Placeholder for the water albedo calculation from the atmosphere. It returns an error if not extended.

FieldExchanger Internal Functions

get_scheme_properties(scheme::AbstractSurfaceFluxScheme, sim::Interfacer.SurfaceModelSimulation, colidx::CC.Fields.ColumnIndex)

Returns the scheme-specific properties for the surface model simulation sim.