FluxCalculator

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:

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.

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

ClimaCoupler.FluxCalculator.TurbulentFluxPartition — Type

TurbulentFluxPartition

Abstract type for flags that denote where and how to calculate tubulent fluxes.

ClimaCoupler.FluxCalculator.PartitionedStateFluxes — Type

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.

ClimaCoupler.FluxCalculator.CombinedStateFluxes — Type

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.

ClimaCoupler.FluxCalculator.combined_turbulent_fluxes! — Function

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.

Arguments

model_sims: [NamedTuple] containing ComponentModelSimulations.
csf: [NamedTuple] containing coupler fields.
turbulent_fluxes: [TurbulentFluxPartition] denotes a flag for turbulent flux calculation.

ClimaCoupler.FluxCalculator.atmos_turbulent_fluxes! — Function

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.

Arguments

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

Example:

function atmos_turbulent_fluxes!(atmos_sim::ClimaAtmosSimulation, csf)
    atmos_sim.cache.flux .= atmos_sim.c .* (csf.T_S .- atmos_sim.temperature)
end

ClimaCoupler.FluxCalculator.surface_inputs — Function

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.

ClimaCoupler.FluxCalculator.calculate_surface_air_density — Function

calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_S::CC.Fields.Field)

Extension for this to to calculate surface density.

ClimaCoupler.FluxCalculator.get_surface_params — Function

get_surface_params(atmos_sim::Interfacer.AtmosModelSimulation)

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).

ClimaCoupler.FluxCalculator.partitioned_turbulent_fluxes! — Function

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.

Args:

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.

TODO:

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.)

ClimaCoupler.FluxCalculator.differentiate_turbulent_fluxes! — Function

differentiate_turbulent_fluxes!(sim::Interfacer.SurfaceModelSimulation, args)

This function provides a placeholder for differentiating fluxes with respect to surface temperature in surface energy balance calculations.

ClimaCoupler.FluxCalculator.get_surface_fluxes_point! — Function

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.

ClimaCoupler.FluxCalculator.update_turbulent_fluxes_point! — Function

update_turbulent_fluxes_point!(sim::Interfacer.SurfaceModelSimulation, fields::NamedTuple, colidx::CC.Fields.ColumnIndex)

Updates the fluxes in the surface model simulation sim with the fluxes in fields.

ClimaCoupler.FluxCalculator.extrapolate_ρ_to_sfc — Function

extrapolate_ρ_to_sfc(thermo_params, ts_int, T_sfc)

Uses the ideal gas law and hydrostatic balance to extrapolate for surface density.

ClimaCoupler.FluxCalculator.surface_thermo_state — Function

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.

ClimaCoupler.FluxCalculator.water_albedo_from_atmosphere! — Function

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

ClimaCoupler.FluxCalculator.get_scheme_properties — Function

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

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