Column Datasets

ExternalDrivenTVForcing{CD, F, M}

Generic time-varying forcing read from a column forcing file through the ColumnDatasets interface (the native ClimaColumn schema). Its forcing is a tuple of composed AbstractForcingTerms (horizontal advection, vertical fluctuation, nudging, subsidence). Only data required by the composed terms is loaded, and missing data for a composed term is a loud error.

time_interpolation_method sets how the file's TimeVaryingInputs behave in time; it defaults to the dataset format's method (plain LinearInterpolation, which errors out of range so a finite campaign cannot fabricate forcing). A case whose file stores one repeating period passes ColumnDatasets.periodic_calendar_method() instead.

Surface-temperature and insolation requirements are derived from the resolved AtmosModel during cache construction rather than from the forcing terms.

Fields

• dataset: The ColumnDatasets.ColumnDataset handle for the forcing file.
• forcing: Tuple of composed forcing terms, validated at construction.
• time_interpolation_method: Time-interpolation method handed to the file's TimeVaryingInputs.

Constructor

ExternalDrivenTVForcing(dataset::ColumnDatasets.ColumnDataset; forcing, time_interpolation_method)
ExternalDrivenTVForcing(path::String; kwargs...)

The path method opens the file as a ColumnDataset and forwards the keyword arguments. forcing defaults to default_forcing_terms() and time_interpolation_method to the dataset format's own method. Runscripts typically call ExternalDrivenTVForcing(path; forcing = (...,)).

AbstractForcingTerm

Supertype of the file-driven forcing terms composed into an ExternalDrivenTVForcing, one per physical process.

Subtypes:

• HorizontalAdvection: prescribed large-scale horizontal advection.
• VerticalFluctuation: prescribed vertical eddy fluctuation.
• Nudging: relaxation toward the file's profiles.
• Subsidence: large-scale subsidence.

Each term declares its data requirements through required_column_variables here; its cache, per-step refresh, and tendency contribution are defined by forcing_term_cache, update_forcing_term!, accumulate_Tq_tendency!, and apply_direct_forcing! in external_forcing.jl.

HorizontalAdvection()

Prescribed large-scale horizontal-advection tendencies of temperature and total specific humidity, read from the canonical file variables tntha [K/s] and tnhusha [1/s].

VerticalFluctuation()

Prescribed vertical eddy-fluctuation tendencies of temperature and total specific humidity, read from the canonical file variables tntva [K/s] and tnhusva [1/s].

Subsidence()

Large-scale subsidence of total energy and total water, driven by the vertical velocity read from the canonical file variable wa [m/s].

Nudging(variables...; timescale = DefaultTimescale(), mask = nothing)

Relax the listed prognostic variables (a subset of (:ta, :hus, :ua, :va)) toward the file's profiles.

Compose several Nudging terms to give different groups different timescales or masks, e.g. per-variable relaxation. :ua and :va share one horizontal-momentum vector, so they must appear in the same term. A DefaultTimescale has no single value across a mixed scalar/momentum group, so such a group must pass an explicit timescale or be split into separate terms; both rules are enforced by the constructor.

Fields

• variables: Tuple of nudged variable names, a subset of (:ta, :hus, :ua, :va).
• timescale: DefaultTimescale(), a Number giving a constant relaxation timescale τ [s], or a function z -> τ [s].
• mask: nothing, a Number, a function z -> weight, or a Field, multiplied into the inverse timescale and materialized once at cache build [-]. Use the function form for height-dependent masks, e.g. to relax only above an inversion.

Examples

forcing = (
    ClimaAtmos.Nudging(:ta, :hus; timescale = 6 * 3600),
    ClimaAtmos.Nudging(:ua, :va; mask = z -> z > 2000 ? 1.0 : 0.0),
)