Column Datasets

Adding a new externally-driven column case in a supported format requires no source code: point the config at the file and the ForcingFromFile setup builds the case (initial condition, external forcing, surface temperature, and insolation) from it.

initial_condition: "ForcingFromFile"
external_forcing_file: /path/to/my_case_forcing.nc
start_date: "20200101"
config: "column"

To use a forcing file with a different (analytic) initial condition, set external_forcing: "ForcingFromFile" instead and keep your initial_condition. When the file supplies the initial condition, it must contain the ta, ua, va, hus, and rho profiles in addition to the forcing variables.

The reader uses one format: the native ClimaColumn schema (below), written by the ERA5 generator and the target for hand-made case files. A file that is not a conforming ClimaColumn file is a loud error at construction. A stale cached file (e.g. an ERA5 forcing file written by an older version in a different on-disk layout) is regenerated on demand from the source rather than read.

The forcing is composed from explicit per-process terms (HorizontalAdvection, VerticalFluctuation, Nudging, Subsidence). The default composition is all four. A runscript can narrow or reshape it without any YAML option:

forcing = ClimaAtmos.ExternalDrivenTVForcing(
    forcing_file;
    forcing = (ClimaAtmos.HorizontalAdvection(),),   # advection only
)
model = ClimaAtmos.AtmosModel(; external_forcing = forcing)
simulation = ClimaAtmos.AtmosSimulation{Float64}(; model, setup, grid)

When the same file also supplies the initial condition, pass the terms to the setup's forcing slot: ForcingFromFile(...; forcing = (...,)).

Per-variable relaxation timescales and height-dependent masks compose as multiple Nudging terms (Nudging(:ta; timescale, mask = z -> ...)).

Surface-temperature and insolation inputs are required only when the model uses them (ExternalTemperature needs ts; ExternalTVInsolation needs coszen/rsdt), so runscripts need not track those separately.

The built-in file-driven cases wire these defaults (a runscript can override any slot):

Case	Large-scale forcing (default)	Surface / insolation (default)
`ForcingFromFile`, `ReanalysisTimeVarying` (ERA5 time-varying)	`default_forcing_terms()`: HAdv + VertFluc + Nudge(`ta`,`hus`) + Nudge(`ua`,`va`) + Subsidence	MO (`z0 = 1e-4`); `ExternalTemperature` (file `ts`); `ExternalTVInsolation` (file `coszen`/`rsdt`)
`ReanalysisMonthlyAveragedDiurnal` (ERA5 monthly, set via `external_forcing`)	same terms, but periodic time interpolation (repeats the one-day file)	MO (`z0 = 1e-4`); `ExternalTemperature`; `ExternalTVInsolation`
`ARMVARANAL`	HAdv + Nudge(`ta`,`hus`) + Nudge(`ua`,`va`) + Subsidence (no VertFluc)	MO (`z0 = 0.05`, `ustar = 0.28`) + `FileHeatFluxes` when `hfls`/`hfss` present; `ExternalTemperature`; `TimeVaryingInsolation` (site lat/lon)
`GCM` (cfsite, see below)	`default_forcing_terms()`, steady in time	MO (`z0 = 1e-4`); `ExternalTemperature` (mean `ts`); `ExternalTVInsolation` (constant `coszen`/`rsdt`)

ClimaAtmos.ExternalDrivenTVForcing — Type

ExternalDrivenTVForcing{CD, F, M}

Generic time-varying forcing read from column forcing data through the ColumnDatasets interface (an on-disk ClimaColumn file or an in-memory source). 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 = (...,)).

source

ClimaAtmos.AbstractForcingTerm — Type

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.

source

ClimaAtmos.HorizontalAdvection — Type

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

source

ClimaAtmos.VerticalFluctuation — Type

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

source

ClimaAtmos.Subsidence — Type

Subsidence()

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

source

ClimaAtmos.Nudging — Type

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

source

GCM-driven (cfsite) runs

A GCM-driven column is configured with initial_condition: "GCM", the cfsite forcing file, and the site group inside it:

initial_condition: "GCM"
external_forcing_file: artifact"cfsite_gcm_forcing"/HadGEM2-A_amip.2004-2008.07.nc
cfsite_number: "site23"
config: "column"

Nothing else selects the case: the setup supplies the forcing, the surface, and the insolation. external_forcing: "GCM" and insolation: "gcmdriven" no longer exist and are errors.

GCMColumnData.read_cfsite reads the cfsite subgroup into in-memory time-mean profiles, which then run through the same ForcingFromFile setup and per-term composition as any other column source, so a runscript can reshape it the same way:

data = ClimaAtmos.ColumnDatasets.GCMColumnData.read_cfsite(
    forcing_file, "site23"; thermo_params,
)
setup = ClimaAtmos.Setups.ForcingFromFile(
    data, "20040701"; forcing = (ClimaAtmos.HorizontalAdvection(),),
)

The profiles are time means, so the forcing is constant in time and does not limit the run length.

Behavior change: the eddy vertical fluctuation

The vertical-fluctuation term is tntva + w̄ ∂T̄/∂z (likewise for hus). The gradient is now differenced on the GCM grid, while the previous GCMForcing cache interpolated to the model grid first and differenced there. The new way is more accurate, but it shifts the forcing wherever the two grids differ, most at sharp gradients such as the trade inversion.

The ClimaColumn schema

A ClimaColumn file is self-describing, so the reader needs no per-file exceptions.

Global attributes: site_latitude / site_longitude in degrees.
Dimensions: column variables are pure 1D (z, time) and surface variables are (time,). z is height in meters, strictly ascending, with at least two levels. time is a CF time coordinate (units plus calendar).
Variables use CMIP short names with SI units attributes. Column: ta [K], hus [kg kg⁻¹], ua/va/wa [m s⁻¹], rho [kg m⁻³], tntha/tntva [K s⁻¹], tnhusha/tnhusva [kg kg⁻¹ s⁻¹]. Surface: ts [K], hfls/hfss [W m⁻², upward positive], coszen [1], rsdt [W m⁻²].

Constructing a ColumnDataset validates a native file against this schema, including exact canonical SI unit strings, and reports all violations. ColumnDatasets.validate(ColumnDatasets.ClimaColumnFile(), path) performs the same check explicitly; ClimaColumnFiles.write_column_forcing_file is the one producer implementation, used by the ERA5 generator.

To extend this machinery (nonstandard forcing from a runscript, generating ERA5 forcing files, or a reader for a new file format), see Adding a Column Dataset in the Developer Guide.