Setups

initial_state(setup, params, atmos_model, center_space, face_space)

Construct the prognostic state vector Y (a Fields.FieldVector) for setup.

Two layers, applied pointwise at every grid point:

1. center_initial_condition and face_initial_condition give the physical state — thermodynamic and kinematic variables, with no knowledge of the model configuration.
2. center_prognostic_variables and face_prognostic_variables convert it into the prognostic variables that atmos_model requires.

Surface prognostic variables are added only for a SlabOceanTemperature surface. File-based setups then overwrite fields through overwrite_initial_state!, which the caller invokes separately.

Arguments

• setup: A setup instance, e.g. Bomex, Rico, or GCMDriven.
• params: The ClimaAtmos parameter set.
• atmos_model: The AtmosModel, whose component models select the prognostic variables.
• center_space: The center extruded finite-difference space.
• face_space: The face extruded finite-difference space.

physical_state(;
    T, p = NaN, ρ = NaN, u = 0, v = 0, q_tot = 0, q_liq = 0, q_ice = 0,
    tke = 0, draft_area = 0, q_rai = 0, q_sno = 0, n_liq = 0, n_rai = 0,
    n_ice = 0, q_rim = 0, b_rim = 0, q_gas_A = 0,
)

Construct the physical state at one grid point.

The return value of every setup's center_initial_condition: the thermodynamic and kinematic state, with no knowledge of the model configuration. The assembly layer in prognostic_variables.jl selects from it the prognostic variables a given AtmosModel needs, so a setup may set fields that the model ignores. The keyword list is closed — an unrecognized name is a method error rather than a silently dropped field.

p and ρ default to NaN sentinels rather than nothing so that every field has the same concrete float type; air_density fills in whichever was left unset. Placeholder states with T = NaN (used by setups that overwrite the state from a file) skip validation.

Keyword Arguments

• T: Temperature, required [K].
• p = NaN: Pressure [Pa]. At least one of p and ρ is required.
• ρ = NaN: Density [kg/m³].
• u, v: Zonal and meridional velocity [m/s].
• q_tot, q_liq, q_ice: Total, cloud liquid, and cloud ice specific humidities [kg/kg].
• tke: Specific turbulent kinetic energy [m²/s²].
• draft_area: Total EDMF draft area fraction, split evenly across the subdomains [-].
• q_rai, q_sno: Rain and snow specific humidities [kg/kg].
• n_liq, n_rai: Cloud droplet and raindrop number concentrations, for two-moment microphysics [1/kg].
• n_ice, q_rim, b_rim: Ice number concentration [1/kg], rime specific content [kg/kg], and rime specific volume [m³/kg], for P3 microphysics.
• q_gas_A: Passive gas tracer specific concentration [kg/kg].

Examples

state = physical_state(; T = 300.0, p = 101500.0, q_tot = 0.017)

face_initial_condition(setup, local_geometry, params)

Return the face (vertical interface) state of setup at one grid point.

Called pointwise by initial_state, which converts the result into face prognostic variables. The default is a state at rest.

Returns

(; w, w_draft), the grid-mean vertical velocity and the EDMF draft vertical velocity [m/s]. The default is (; w = 0, w_draft = 0); w_draft is used only by a prognostic-EDMF configuration.

surface_condition(setup, params)

Return the surface pieces prescribed by setup.

Consumed by AtmosSurface(::AtmosConfig, params, FT; setup_type), where a non-nothing field takes precedence over the corresponding config key. Only setups with case-specific surface properties (roughness, prescribed fluxes, a case SST) need to extend this.

Returns

(; flux_scheme, temperature, overrides): a SurfaceConditions.SurfaceParameterization, a SurfaceConditions.SurfaceTemperature, and a SurfaceConditions.SurfaceBoundaryOverrides. Each defaults to nothing, falling through to the configuration. Note that temperature is used only when prognostic_surface is "PrescribedSST".

overwrite_initial_state!(setup, Y, thermo_params)

Overwrite the initial state Y in place after it has been constructed, and return nothing.

The extension point for file-based setups (e.g. GCMDriven, WeatherModel), which regrid whole fields rather than working pointwise. Called by the simulation setup after initial_state. The default is a no-op.

subsidence_forcing(setup, ::Type{FT})

Return the large-scale subsidence profile z -> w_subsidence [m/s] prescribed by setup, or nothing for no subsidence (the default).

The model construction layer wraps a non-nothing profile in a LargeScaleSubsidence and stores it as atmos.subsidence. There is no config key for subsidence: it is owned by the setup.

large_scale_advection_forcing(setup, ::Type{FT})

Return the prescribed large-scale advective tendencies of setup, or nothing for none (the default).

Returns

(; prof_dTdt, prof_dqtdt), the raw profile functions of the AtmosphericProfilesLibrary form (exner, z) -> dTdt [K/s] and z -> dqtdt [kg/kg/s]. The model construction layer adapts their argument lists and wraps them in a LargeScaleAdvection stored as atmos.ls_adv; there is no config key for them.

coriolis_forcing(setup, ::Type{FT})

Return the single-column Coriolis forcing of setup, or nothing for none (the default).

Returns

(; prof_ug, prof_vg, coriolis_param), the geostrophic-wind profiles z -> u_g, z -> v_g [m/s] and the Coriolis parameter [1/s]. Stored as atmos.scm_coriolis by the model construction layer; there is no config key for it.

external_forcing(setup, ::Type{FT})

Return the external (large-scale) forcing model of setup, e.g. a GCMForcing, ISDACForcing, or ExternalDrivenTVForcing.

Defaults to nothing, in which case the model construction layer falls back to the external_forcing config key.

insolation_model(setup)

Return the insolation model of setup, e.g. a GCMDrivenInsolation, ExternalTVInsolation, or RCEMIPIIInsolation.

Defaults to nothing, in which case the insolation config key is used.

surface_temperature_model(setup)

Return the default SurfaceConditions.SurfaceTemperature of setup.

Used when prognostic_surface == "PrescribedSST" and surface_condition supplies no temperature. Unlike the other model methods, the default is not nothing but an AnalyticTemperature wrapping zonally_symmetric_temperature.

prescribed_flow_model(setup, ::Type{FT})

Return the prescribed velocity profile of setup, which replaces the prognostic momentum solution (e.g. ShipwayHill2012VelocityProfile).

Defaults to nothing, in which case the prescribed_flow config key is used.

radiation_model(setup, ::Type{FT})

Return the case-specific radiation model of setup, e.g. RadiationDYCOMS, RadiationTRMM_LBA, or RadiationISDAC.

Defaults to nothing. It is also ignored when the rad config key is set explicitly, so a configuration can always override the setup's radiation.

Bomex

The Bomex setup described in [16], with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

The profiles field stores precomputed atmospheric profile functions (computed at construction time before broadcasting).

Examples

setup = Bomex()                       # Float32 defaults
setup = Bomex(Float64)                # specify floating-point type
setup = Bomex(; prognostic_tke = false)

To use thermodynamics parameters from a non-default ClimaAtmosParameters, pass them explicitly via thermo_params.

Rico

The RICO (Rain In Cumulus over the Ocean) setup described in [17], with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

The profiles field stores precomputed atmospheric profile functions (computed at construction time before broadcasting).

Examples

import Thermodynamics as TD
import ClimaParams as CP
FT = Float64
toml_dict = CP.create_toml_dict(FT)
thermo_params = TD.Parameters.ThermodynamicsParameters(toml_dict)
setup = Rico(; prognostic_tke = true, thermo_params)

Soares

The Soares setup described in [18], with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

Examples

setup = Soares(; prognostic_tke = true, thermo_params)

GABLS

The GABLS setup described in [19], with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

Surface temperature is time-varying: T = 265 - 0.25t/3600.

Examples

setup = GABLS(; prognostic_tke = true, thermo_params)

GATE_III

The GATE_III setup described in [20], with a hydrostatically balanced pressure profile. Uses T (not θ) for hydrostatic integration. Profiles are sourced from AtmosphericProfilesLibrary.

Examples

setup = GATE_III(; prognostic_tke = true, thermo_params)

DYCOMS{P, FT}

Unified struct for DYCOMSRF01 ([12]) and DYCOMSRF02 ([13]), with hydrostatically balanced pressure profiles sourced from AtmosphericProfilesLibrary.

The two variants differ only in APL profiles, surface heat fluxes, and geostrophic wind. Construct via DYCOMS_RF01(; ...) or DYCOMS_RF02(; ...).

Examples

setup = DYCOMS_RF01(; prognostic_tke = true, thermo_params)
setup = DYCOMS_RF02(; prognostic_tke = true, thermo_params)

TRMM_LBA

The TRMM_LBA setup described in [21], with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

Surface fluxes are time-varying: shf and lhf follow a cosine ramp over the first 5.25 hours.

Examples

setup = TRMM_LBA(; prognostic_tke = true, thermo_params)

ISDAC

The ISDAC (Indirect and Semi-Direct Aerosol Campaign) setup, with a hydrostatically balanced pressure profile. Profiles are sourced from AtmosphericProfilesLibrary.

When perturb is true, Gaussian perturbations with a standard deviation of 0.1 K are added to the liquid-ice potential temperature below 825 m.

Examples

setup = ISDAC(; prognostic_tke = true, perturb = false, thermo_params)

Larcform1

Single-column model setup for the Larcform1 arctic boundary layer case, based on Pithan et al. (2016) — SCM intercomparison for the Arctic winter boundary layer.

Canonical conditions (Pithan 2016, Section 2):

• Location: 80°N
• Start date: 1 January (zero solar insolation)
• Initial surface temperature: 250 K (sea ice)
• Sea ice: 1 m thick, 100% concentration
• Geostrophic wind: 5 m/s throughout troposphere

Profiles are sourced from AtmosphericProfilesLibrary. RH is specified with respect to liquid water (Pithan 2016, Table 1). The humidity profile is split at the tropopause: RH-derived qtot below, fixed qtop above.

TKE is initialized to zero regardless of prognostic_tke, unlike the other single-column setups, which fall back to a prescribed TKE profile when TKE is not prognostic.

Examples

setup = Larcform1(; prognostic_tke = true, thermo_params)

SimplePlume(; prognostic_tke = false)

A simple plume setup using a DryAdiabaticProfile with Tsurface=310K and Tmin=290K. No moisture. Used for testing EDMFX plume dynamics.

Examples

setup = SimplePlume(; prognostic_tke = true)

PrecipitatingColumn

A 1-dimensional precipitating column test using Rico-based profiles with prescribed precipitation fields. Profiles are precomputed at construction time.

ShipwayHill2012

The initial condition described in [15], with a hydrostatically balanced pressure profile.

B. J. Shipway and A. A. Hill. Diagnosis of systematic differences between multiple parametrizations of warm rain microphysics using a kinematic framework. Quarterly Journal of the Royal Meteorological Society 138, 2196-2211 (2012).

RCEMIPIIProfile(temperature, humidity)

An initial condition following the RCEMIP-II sounding of [14].

Fields

• temperature: Surface temperature of the sounding [K].
• humidity: Surface specific humidity of the sounding [kg/kg].

Three convenience constructors give the protocol's three SSTs:

• RCEMIPIIProfile_295(): 295 K.
• RCEMIPIIProfile_300(): 300 K.
• RCEMIPIIProfile_305(): 305 K.

DecayingProfile(; perturb = true, thermo_params = nothing, params = nothing)

A setup with a decaying temperature profile, optionally perturbed.

Uses the DecayingTemperatureProfile of Thermodynamics.jl, with a surface temperature of 290 K, a minimum temperature of 220 K, and a scale height of 8 km.

Keyword Arguments

• perturb = true: Whether to add a temperature perturbation.
• thermo_params = nothing: Thermodynamics parameter set.
• params = nothing: A full ClimaAtmosParameters set, from which the thermodynamics parameters are taken; takes precedence over thermo_params.

Examples

setup = DecayingProfile(; perturb = false, thermo_params)

IsothermalProfile(; temperature = 300)

A setup with a uniform temperature and barometric pressure profile.

Examples

setup = IsothermalProfile(; temperature = 300)

ConstantBuoyancyFrequencyProfile()

A setup with a constant Brunt-Väisälä frequency (N = 0.01 s⁻¹), a surface temperature of 288 K, and a uniform horizontal wind of 10 m/s. The temperature is capped by an isothermal layer to avoid unreasonable values at high altitudes.

Used for topography test cases.

Examples

setup = ConstantBuoyancyFrequencyProfile()

DryBaroclinicWave(; perturb = true, deep_atmosphere = false)

A setup with a dry baroclinic wave initial condition, following the test case described in Ullrich et al. (2014).

When perturb is true, a localized perturbation is applied to the horizontal velocity field to trigger baroclinic instability.

MoistBaroclinicWave(; perturb = true, deep_atmosphere = false)

A moist baroclinic wave setup. Uses the same dynamical core as DryBaroclinicWave, but adds a moisture profile and converts virtual temperature to temperature.

Examples

setup = MoistBaroclinicWave(; perturb = true, deep_atmosphere = false)

MoistBaroclinicWaveWithEDMF(; perturb = true, deep_atmosphere = false)

The same setup as MoistBaroclinicWave, but with an initial TKE of 0 and an initial draft area fraction of 0.2.

Examples

setup = MoistBaroclinicWaveWithEDMF(; perturb = true, deep_atmosphere = false)

DryDensityCurrentProfile()

A dry density current (cold bubble) setup. A cosine-shaped negative potential temperature perturbation is centered at (x=25600, z=2000) m, producing a negatively buoyant region that drives a density current.

Handles both 2D (XZ) and 3D (XYZ) domains automatically.

Examples

setup = DryDensityCurrentProfile()

RisingThermalBubbleProfile()

A rising thermal bubble setup. A cosine-shaped positive potential temperature perturbation is centered at (x=500, z=350) m, producing a positively buoyant region that rises.

Handles both 2D (XZ) and 3D (XYZ) domains automatically.

Examples

setup = RisingThermalBubbleProfile()

MoistAdiabaticProfileEDMFX(; perturb = false)

A moist adiabatic profile for testing EDMFX advection. Uses a DryAdiabaticProfile with Tsurface=330K and Tmin=200K, combined with Gaussian moisture and draft area profiles centered at z=4km.

The face initial condition sets w_draft = 1.0 (non-zero updraft velocity).

Examples

setup = MoistAdiabaticProfileEDMFX(; perturb = true)

GCMDriven{P, FT}

Single-column setup driven by GCM forcing data.

Time-averaged vertical profiles are read once from a GCM forcing NetCDF file and turned into 1D interpolators, which center_initial_condition evaluates at each grid height. The surface temperature comes from the same file.

Fields

• external_forcing_file: Path to the GCM forcing NetCDF file.
• cfsite_number: Site identifier within the file, e.g. "site23".
• profiles: ColumnProfiles of interpolators in T, u, v, q_tot, and ρ.
• T_sfc: Time-mean surface temperature from the file [K].

Examples

setup = GCMDriven("path/to/HadGEM2-A_amip.2004-2008.07.nc", "site23")

GCMDriven(external_forcing_file, cfsite_number)

Construct a GCMDriven setup by reading time-averaged profiles from a GCM forcing file and building 1D vertical interpolators.

ForcingFromFile

Generic file-driven single-column setup: initial condition, external forcing, surface temperature, and insolation are sourced from one column forcing file, read through the ColumnDatasets interface so any registered dataset format works.

The initial condition reads vertical profiles (ta, ua, va, hus, rho) at the file time closest to start_date and builds 1D interpolators via ColumnProfiles. The forcing, surface, and insolation are composition slots, each defaulting to the ERA5-case behavior:

• forcing: a tuple of AbstractForcingTerms (or a built ExternalDrivenTVForcing). Default: default_forcing_terms().
• flux_scheme: the surface flux scheme. Default (nothing): interactive Monin-Obukhov. For prescribed fluxes pass e.g. MoninObukhov(; z0, ustar, fluxes = SurfaceConditions.FileHeatFluxes(data, start_date)).
• surface_temperature: default ExternalTemperature() (the file's ts).
• insolation: default ExternalTVInsolation() (the file's coszen/rsdt). Pass TimeVaryingInsolation(; latitude, longitude, start_date) for astronomically-computed insolation.

Examples

setup = ForcingFromFile("path/to/era5_forcing.nc", "20070701")

# horizontal advection only
setup = ForcingFromFile(
    "path/to/forcing.nc",
    "20070701";
    forcing = (HorizontalAdvection(),),
)

MoistFromFile(file_path)

File-based initial condition that reads thermodynamic and kinematic state from a NetCDF file and regrids it onto the model grid.

Assigns NaN placeholders during pointwise construction, then overwrites the full prognostic state with data regridded from the given file via overwrite_from_file!.

Fields

• file_path: Path to the NetCDF file holding the initial condition.

Notes

The file is expected to carry:

• p: Surface pressure, 2D and broadcast in z [Pa].
• t: Temperature, 3D [K].
• q: Specific humidity, 3D [kg/kg].
• u, v, w: Velocity components, 3D [m/s].
• cswc, crwc: Snow and rain water contents, optional [kg/kg].
• z_sfc: Surface altitude, optional; enables the topographic pressure correction [m].

WeatherModel(start_date, era5_initial_condition_dir = nothing;
             use_full_pressure = false)

ERA5-derived initial condition for weather and forecast simulations.

The pointwise construction assigns NaN placeholders; overwrite_initial_state! then overwrites the whole prognostic state with ERA5 data located by weather_model_data_path.

Arguments

• start_date: Date string in the format "yyyymmdd" or "yyyymmdd-HHMM".
• era5_initial_condition_dir = nothing: Directory of pre-processed ERA5 files. When nothing, the wxquest_initial_conditions ClimaArtifact is used. It is stashed in the module-level _ERA5_IC_DIR rather than stored on the struct, because a captured string cannot be adapted to the GPU.

Keyword Arguments

• use_full_pressure = false: Whether to read the 3D pressure from the file instead of integrating it hydrostatically.

Fields

• start_date: The parsed DateTime.
• use_full_pressure: As above [-].

AMIPFromERA5(start_date)

AMIP initial condition from an instantaneous ERA5 reanalysis snapshot.

The pointwise construction assigns NaN placeholders; overwrite_initial_state! then overwrites the whole prognostic state through overwrite_from_file!, reading the 00:00 UTC snapshot of start_date from the era5_inst_model_levels ClimaArtifact, at era5_init_processed_internal_YYYYMMDD_0000.nc. Only the date part of start_date selects the file, so any time of day other than 00:00 is ignored.

Fields

• start_date: DateTime parsed from a "yyyymmdd" or "yyyymmdd-HHMM" string.