API

AtmosSimulation

A configured atmospheric simulation: an initialized time-stepping integrator together with the output bookkeeping needed to run it and write its diagnostics.

Build one with the keyword constructor AtmosSimulation{FT}(; ...) (or AtmosSimulation(; ...) for Float32), or from a configuration with AtmosSimulation(config). Run it with solve_atmos!.

Fields

• job_id: Run identifier, also used to name the output directory.
• output_dir: Directory that receives diagnostics, checkpoints, and logs.
• start_date: Calendar date corresponding to the simulation start.
• t_end: End time of the simulation [s].
• output_writers: Diagnostic writers, closed by solve_atmos! when the run finishes.
• integrator: The ClimaTimeSteppers integrator holding the state, cache, and callbacks.

AtmosSimulation{FT}(; kwargs...) where {FT}

Construct an atmospheric simulation with float type FT.

Builds (or restarts) the state, the cache, the callbacks, the diagnostics, and the time-stepping integrator, and resolves the output directory. This is the primary entry point for simulations written as scripts; configuration-driven runs go through get_simulation instead.

Keyword Arguments

• model = AtmosModel(): Physics and parameterization configuration.
• params = ClimaAtmosParameters(FT): Physical parameters.
• context = ClimaComms.context(): Communications context (device and MPI).
• grid = SphereGrid(FT; radius = CAP.planet_radius(params), context): Computational grid. Use ColumnGrid, BoxGrid, PlaneGrid, or SphereGrid.
• setup = Setups.DecayingProfile(; perturb = true, params): Setup defining the initial state, and, for single-column cases, the forcings. See Setups.
• dt = 600: Timestep [s], or a string such as "10mins".
• start_date = DateTime(2010, 1, 1): Calendar date of the simulation start.
• t_start = 0: Start time [s]. Ignored, with a warning, when restarting.
• t_end = 86400 * 10: End time [s], 10 days by default.
• ode_config: Time-stepping algorithm. Defaults to IMEXAlgorithm(ARS343(), NewtonsMethod(; max_iters = 1, update_j = UpdateEvery(NewNewtonIteration))).
• steady_state_velocity = nothing: Analytic steady-state velocity used by diagnostics, either a precomputed field or a callable (Y, params) -> velocity evaluated once Y exists.
• job_id = "atmos_sim": Run identifier, used in output directory naming.
• output_dir = nothing: Output directory. Defaults to output/<job_id>, or <job_id> when the CI environment variable is set.
• output_dir_style = "activelink": How the output directory is managed; "activelink" keeps numbered directories with a symlink to the active one, "removepreexisting" deletes previous output.
• restart_file = nothing: Restart file to resume from.
• detect_restart_file = false: Pick up the most recent restart file in the output directory structure; only available with output_dir_style = "activelink".
• aerosol_names = []: Prescribed aerosol species to read from file.
• time_varying_trace_gases = (): Trace gases read from a time-varying file.
• vertical_water_borrowing_species = nothing: Species the vertical water borrowing constraint may draw from.
• default_callbacks = true: Add the default model and common callbacks. When false, only callbacks is used.
• callbacks = (): User-provided callbacks, used only when default_callbacks is false.
• callback_kwargs = (): Extra keyword arguments forwarded to the default callbacks.
• diagnostics = DiagnosticsConfig(): Which diagnostics to produce and how to write them. See DiagnosticsConfig.
• jacobian = ManualSparseJacobian(; approximate_solve_iters = 1): Jacobian algorithm for the implicit solve. Use ManualSparseJacobian, AutoSparseJacobian, or AutoDenseJacobian.
• debug_jacobian = false: Print Jacobian diagnostics while solving.
• update_cache_every = "stage": When the cache is refreshed, "stage" or "step".
• update_constrain_state_every = "step": When state constraints are applied, "stage", "step", or "dss".
• checkpoint_frequency = Inf: How often to write restart checkpoints; a number of seconds, a time string, or "<N>months". Inf disables checkpointing.
• log_to_file = false: Send log output to a file in the output directory.
• verbose = false: Log progress while building the simulation (root process only).

Returns

An AtmosSimulation, ready to be passed to solve_atmos!.

Examples

import ClimaAtmos as CA

# Minimal: 1-day global simulation with defaults
simulation = CA.AtmosSimulation{Float64}(; t_end = 86400)
CA.solve_atmos!(simulation)

# Single-column BOMEX case
simulation = CA.AtmosSimulation{Float64}(;
    grid = CA.ColumnGrid(Float64; z_elem = 60, z_max = 3000.0),
    setup = CA.Setups.Bomex(),
    dt = 5,
    t_end = 3600 * 6,
)

AtmosSimulation(; kwargs...)

Construct an atmospheric simulation with the default float type Float32.

Equivalent to AtmosSimulation{Float32}(; kwargs...).

AtmosSimulation(config::AtmosConfig)

Construct a simulation from a configuration, with the float type taken from config.

Equivalent to get_simulation(config), which also writes the parameter manifest and config snapshot into the output directory.

AtmosConfig{FT, TD, PA, C, CF}

A fully resolved ClimaAtmos configuration, used to build an AtmosModel and AtmosSimulation.

Fields

• toml_dict: the merged ClimaParams TOML parameter dictionary (built by ClimaParams.create_toml_dict from the files listed under the toml config key). It holds the physical parameter values (with units and defaults) that the model reads, as opposed to parsed_args, which holds the run/model configuration options. eltype(toml_dict) determines the float type FT.
• parsed_args: the run configuration as a key => value dictionary, obtained by overriding default_config.yml with the user-supplied configuration.
• comms_ctx: the ClimaComms context (device and MPI information).
• config_files: the configuration files that were merged to build this config.
• job_id: a unique identifier for the run, used e.g. for the output directory.

AtmosConfig(config_file::String = default_config_file; job_id = nothing, comms_ctx = nothing)
AtmosConfig(config_files; job_id = nothing, comms_ctx = nothing)

Build an AtmosConfig from one or more YAML configuration files.

Each file is parsed into a Dict, and the results are merged (later files override earlier ones) on top of default_config.yml, which is prepended automatically when not already among config_files.

Keyword Arguments

• job_id = nothing: Run identifier. When nothing, it is taken from the job_id key in the merged configuration (if present), and otherwise derived from the config file names.
• comms_ctx = nothing: ClimaComms context. When nothing, it is inferred from the device config key (see get_comms_context).

Examples

import ClimaAtmos as CA
config = CA.AtmosConfig("config/model_configs/held_suarez.yml")

AtmosConfig(config::AbstractDict; comms_ctx = nothing, config_files = [default_config_file], job_id = nothing)
AtmosConfig(configs; comms_ctx = nothing, config_files = [default_config_file], job_id = nothing)

Build an AtmosConfig from one or more configuration Dicts.

The dicts are merged (later ones override earlier ones), and the result overrides the defaults from default_config.yml (see override_default_config). The float type FT is set by the FLOAT_TYPE key ("Float64" gives Float64; anything else gives Float32), the parameter files listed under the toml key are merged into the ClimaParams TOML dictionary, and artifact"name" strings in config values are resolved to local artifact paths.

Keyword Arguments

• comms_ctx = nothing: ClimaComms context. When nothing, it is inferred from the device config key (see get_comms_context).
• config_files = [default_config_file]: File names recorded in the resulting config, used for logging and for deriving job_id; the dicts themselves are the data source.
• job_id = nothing: Run identifier. Resolution order: this keyword if given, then the job_id key in the merged dicts, then a name derived from config_files.

solve_atmos!(simulation)

Run simulation to its end time and return an AtmosSolveResults with the solution, the return code (:success or :simulation_crashed), and the walltime [s].

The first step is taken outside the timed solve so that compilation is not counted, and the callbacks are precompiled. Failures are caught rather than rethrown, so that partial results can still be inspected: in a serial run the crashed state is written to the output directory first. The diagnostic writers are closed on every path.

Examples

import ClimaAtmos as CA
simulation = CA.AtmosSimulation{Float64}(; t_end = 86400)
results = CA.solve_atmos!(simulation)
results.ret_code == :success

get_simulation(config::AtmosConfig)

Build an AtmosSimulation from a configuration.

Resolves the parameters, setup, model, and grid from config and forwards them, along with the time, output, restart, numerics, callback, and diagnostics keys, to the AtmosSimulation{FT} keyword constructor. Config-driven runs are always verbose, and their parameter manifest and config snapshot are written into the resolved output directory by log_yaml_and_toml_manifests.

Examples

import ClimaAtmos as CA
config = CA.AtmosConfig("config/model_configs/baroclinic_wave.yml")
simulation = CA.get_simulation(config)
CA.solve_atmos!(simulation)

AtmosSolveResults

Outcome of solve_atmos!.

Fields

• sol: Solution object, or nothing if the simulation crashed.
• ret_code: :success or :simulation_crashed.
• walltime: Wall-clock duration of the solve [s], or nothing if it crashed.

dry(; kwargs...)

Dry atmosphere preset (microphysics_model = DryModel()). Keyword arguments are forwarded to AtmosModel, and override the preset.

Returns

An AtmosModel.

Examples

import ClimaAtmos as CA
model = CA.Presets.dry(; disable_surface_flux_tendency = true)

equil_moist_0m(; kwargs...)

Equilibrium-moisture preset with 0-moment microphysics, grid-scale cloud, prescribed zonally-symmetric SST, and idealized insolation. Keyword arguments are forwarded to AtmosModel, and override the preset.

Returns

An AtmosModel.

Examples

import ClimaAtmos as CA
model = CA.Presets.equil_moist_0m()

nonequil_moist_1m(; kwargs...)

Non-equilibrium-moisture preset with 1-moment microphysics, explicit microphysics tendency timestepping, grid-scale cloud, prescribed zonally-symmetric SST, and idealized insolation. Mirrors equil_moist_0m but with 1-moment non-equilibrium microphysics in place of 0-moment equilibrium. Keyword arguments are forwarded to AtmosModel, and override the preset.

Returns

An AtmosModel.

Examples

import ClimaAtmos as CA
model = CA.Presets.nonequil_moist_1m()

prognostic_edmf([FT = Float32]; area_fraction = FT(1e-5), n_updrafts = 1,
                prognostic_tke = true, kwargs...)

Equilibrium-moist model with the PrognosticEDMFX turbulence-convection scheme. This uses Generalized entrainment/detrainment, SGS mass & diffusive fluxes, and non-hydrostatic pressure drag. Also enables prognostic updraft vertical diffusion and the relaxation filter on negative updraft velocities (matches the canonical prognostic_edmfx_* configs). Mixing-length scales are blended with SmoothMinimumBlending, and the microphysics is 0-moment equilibrium with grid-scale cloud.

Arguments

• FT = Float32: Float type of the scheme's parameters.

Keyword Arguments

• area_fraction = FT(1e-5): "Small" updraft area threshold passed to PrognosticEDMFX [-].
• n_updrafts = 1: Number of updraft subdomains [-].
• prognostic_tke = true: Whether TKE is prognostic.
• kwargs...: Forwarded to AtmosModel, overriding the preset.

Returns

An AtmosModel.

Examples

import ClimaAtmos as CA
model = CA.Presets.prognostic_edmf(Float64; n_updrafts = 2)

prognostic_edmf_1m([FT = Float32]; kwargs...)

prognostic_edmf with 1-moment non-equilibrium microphysics and explicit microphysics tendency timestepping (matches the canonical prognostic_edmfx_* configs that use microphysics_model: "1M"). All keyword arguments are forwarded to prognostic_edmf and on to AtmosModel.

Returns

An AtmosModel.

Examples

import ClimaAtmos as CA
model = CA.Presets.prognostic_edmf_1m(Float32)

aquaplanet([FT = Float32]; kwargs...)

Aquaplanet simulation preset: global SphereGrid with equil_moist_0m physics (0M microphysics, prescribed zonally-symmetric SST, idealized insolation). Uses the default DecayingProfile initial condition from AtmosSimulation, which also sets dt = 600 s and t_end = 10 days. Keyword arguments are forwarded to AtmosSimulation, and override the preset.

Returns

An AtmosSimulation.

Examples

import ClimaAtmos as CA
simulation = CA.Presets.aquaplanet(Float32; t_end = "1days")

baroclinic_wave([FT = Float32]; kwargs...)

Dry baroclinic-wave simulation preset: global SphereGrid, DryBaroclinicWave setup, and a dry model with disable_surface_flux_tendency = true. For the moist variant, pass setup = Setups.MoistBaroclinicWave() and model = Presets.equil_moist_0m(; disable_surface_flux_tendency = true). Keyword arguments are forwarded to AtmosSimulation, and override the preset.

Returns

An AtmosSimulation.

Examples

import ClimaAtmos as CA
simulation = CA.Presets.baroclinic_wave(Float32; t_end = "2days")

bomex([FT = Float32]; kwargs...)

BOMEX shallow-cumulus single-column simulation preset: ColumnGrid (60 uniform levels, zmax = 3 km), Setups.Bomex setup, [`equilmoist0m](@ref) physics,dt = 10 s,tend = 6 h`.

No EDMF turbulence-convection scheme is enabled by default; pass model = Presets.prognostic_edmf(FT) to add one. Keyword arguments are forwarded to AtmosSimulation, and override the preset. params is resolved up front, because Setups.Bomex needs thermodynamic parameters at construction time.

Returns

An AtmosSimulation.

Examples

import ClimaAtmos as CA
simulation = CA.Presets.bomex(Float32; t_end = "10mins")

SphereGrid(::Type{FT}; kwargs...)

Create an ExtrudedCubedSphereGrid with topography support.

Arguments

• FT: the floating-point type [Float32, Float64]

Keyword Arguments

• context = ClimaComms.context(): the ClimaComms communications context
• z_elem = 10: the number of z-points
• z_max = 30000.0: the domain maximum along the z-direction
• z_stretch = true: whether to use vertical stretching
• dz_bottom = 500.0: bottom layer thickness for stretching
• z_mesh: Optionally provide a custom z-mesh, instead of z_elem, z_max, z_stretch
• radius = 6.371229e6: the radius of the cubed sphere
• h_elem = 6: the number of horizontal elements per side of every panel (6 panels in total)
• nh_poly = 3: the polynomial order. Note: The number of quadrature points in 1D within each horizontal element is then n_quad_points = nh_poly + 1
• bubble = false: enables the "bubble correction" for more accurate element areas when computing the spectral element space
• deep_atmosphere = true: use deep atmosphere equations and metric terms, otherwise assume columns are cylindrical (shallow atmosphere)
• topography = NoTopography(): topography type
• topography_damping_factor = 5.0: factor by which smallest resolved length-scale is to be damped
• mesh_warp_type = SLEVEWarp{FT}(): mesh warping type (SLEVEWarp or LinearWarp)
• topo_smoothing = false: apply topography smoothing

ColumnGrid(::Type{FT}; kwargs...)

Create a ColumnGrid.

Arguments

• FT: the floating-point type [Float32, Float64]

Keyword Arguments

• context = ClimaComms.context(): the ClimaComms communications context
• z_elem = 10: the number of z-points
• z_max = 30000.0: the domain maximum along the z-direction
• z_stretch = true: whether to use vertical stretching
• dz_bottom = 500.0: bottom layer thickness for stretching
• z_mesh: Optionally provide a custom z-mesh, instead of z_elem, z_max, z_stretch

BoxGrid(::Type{FT}; kwargs...)

Create a Box3DGrid with topography support.

Arguments

• FT: the floating-point type [Float32, Float64]

Keyword Arguments

• context = ClimaComms.context(): the ClimaComms communications context
• x_elem = 6: the number of x-points
• x_max = 300000.0: the domain maximum along the x-direction
• y_elem = 6: the number of y-points
• y_max = 300000.0: the domain maximum along the y-direction
• z_elem = 10: the number of z-points
• z_max = 30000.0: the domain maximum along the z-direction
• nh_poly = 3: the polynomial order. Note: The number of quadrature points in 1D within each horizontal element is then n_quad_points = nh_poly + 1
• z_stretch = true: whether to use vertical stretching
• dz_bottom = 500.0: bottom layer thickness for vertical stretching
• z_mesh: Optionally provide a custom z-mesh, instead of z_elem, z_max, z_stretch
• bubble = false: enables the "bubble correction" for more accurate element areas when computing the spectral element space.
• periodic_x = true: use periodic domain along x-direction
• periodic_y = true: use periodic domain along y-direction
• topography = NoTopography(): topography type
• topography_damping_factor = 5.0: factor by which smallest resolved length-scale is to be damped
• mesh_warp_type = LinearWarp(): mesh warping type (SLEVEWarp or LinearWarp)
• topo_smoothing = false: apply topography smoothing

PlaneGrid(::Type{FT}; kwargs...)

Create a SliceXZGrid with topography support.

Arguments

• FT: the floating-point type [Float32, Float64]

Keyword Arguments

• context = ClimaComms.context(): the ClimaComms communications context
• x_elem = 6: the number of x-points
• x_max = 300000.0: the domain maximum along the x-direction
• z_elem = 10: the number of z-points
• z_max = 30000.0: the domain maximum along the z-direction
• z_mesh: Optionally provide a custom z-mesh, instead of z_elem, z_max, z_stretch
• nh_poly = 3: the polynomial order. Note: The number of quadrature points in 1D within each horizontal element is then n_quad_points = nh_poly + 1
• z_stretch = true: whether to use vertical stretching
• dz_bottom = 500.0: bottom layer thickness for stretching
• periodic_x = true: use periodic domain along x-direction
• topography = NoTopography(): topography type
• topography_damping_factor = 5.0: factor by which smallest resolved length-scale is to be damped
• mesh_warp_type = LinearWarp(): mesh warping type (SLEVEWarp or LinearWarp)
• topo_smoothing = false: apply topography smoothing

AbstractTopography

Surface elevation profile used to warp the vertical grid.

Subtypes:

• NoTopography: flat surface; the grid is not warped.
• CosineTopography: periodic cosine hills, in 2D or 3D.
• AgnesiTopography: a single witch-of-Agnesi mountain, 2D.
• ScharTopography: a Gaussian envelope of cosine ridges, 2D.
• EarthTopography: Earth orography from the ETOPO2022 dataset.
• DCMIP200Topography: the DCMIP-2-0-0 mountain, on the sphere.
• Hughes2023Topography: the two-ridge mountain of Hughes and Jablonowski (2023), on the sphere.

Every analytic subtype extends topography_function(topography, coord), which returns the surface elevation [m] at coord. EarthTopography has no analytic form and is instead read from a file when the grid is built; NoTopography short-circuits grid warping entirely. The parameters live on the type rather than inside the elevation function so that the analytic steady-state solutions in steady_state_solutions.jl can reuse them.

NoTopography()

Flat lower boundary: the vertical grid is built without hypsography, so the mesh-warping choice has no effect.

EarthTopography()

Earth orography, regridded from the ETOPO2022 ice-surface elevation dataset.

Unlike the analytic profiles, this one has no topography_function: the elevation is read from the earth_orography artifact onto the horizontal space when the grid is built, then smoothed by horizontal diffusion (the number of iterations follows the topography_damping_factor configuration) and clipped at zero. See the Topography in ClimaAtmos page.

CosineTopography{D, FT}(; h_max = 25, λ = 25e3)

Periodic cosine hills in a 2D (D = 2) or 3D (D = 3) box.

The elevation is h_max cos(2πx/λ) in 2D and h_max cos(2πx/λ) cos(2πy/λ) in 3D, so the same wavelength is used along both horizontal directions. Steady-state solutions for this profile are available from steady_state_velocity.

Fields

• h_max = 25: Amplitude of the hills, the maximum elevation [m].
• λ = 25e3: Wavelength of the hills [m].

Examples

topography = CosineTopography{2, Float64}(; h_max = 100, λ = 20e3)

AgnesiTopography{FT}(; h_max = 25, x_center = 50e3, a = 5e3)

Witch-of-Agnesi mountain for 2D simulations.

The elevation is $h_{max} / (1 + ((x - x_c)/a)^2)$, the standard profile for mountain-wave tests. Steady-state solutions for this profile are available from steady_state_velocity.

Fields

• h_max = 25: Peak elevation [m].
• x_center = 50e3: Horizontal position of the peak [m].
• a = 5e3: Half-width of the mountain [m].

Examples

topography = AgnesiTopography{Float64}(; h_max = 400, a = 10e3)

ScharTopography{FT}(; h_max = 25, x_center = 50e3, λ = 4e3, a = 5e3)

Schär mountain for 2D simulations: cosine ridges of wavelength λ under a Gaussian envelope of half-width a.

The elevation is $h_{max} \exp(-((x - x_c)/a)^2) \cos^2(π (x - x_c)/λ)$, so the profile carries both a resolved-scale and a small-scale response. Steady-state solutions for this profile are available from steady_state_velocity.

Fields

• h_max = 25: Peak elevation [m].
• x_center = 50e3: Horizontal position of the central peak [m].
• λ = 4e3: Wavelength of the ridges [m].
• a = 5e3: Half-width of the Gaussian envelope [m].

Examples

topography = ScharTopography{Float64}(; h_max = 250, λ = 4e3, a = 5e3)

DCMIP200Topography()

Surface elevation for the DCMIP-2-0-0 test problem: a 2 km circular mountain centered on the equator at 270° longitude, on the sphere.

Inside a great-circle radius of 3π/4, the elevation is a cosine bell modulated by cosine ridges of half-width π/16; outside it is zero.

Hughes2023Topography()

Surface elevation for the baroclinic-wave test of Hughes and Jablonowski (2023): two 2 km ridges centered at 45°N, at 72° and 140° longitude, on the sphere.

Each ridge is a super-Gaussian in latitude and a Gaussian in longitude, with widths set so that the elevation falls to a tenth of its peak at 20° in latitude and 3.5° in longitude.

References

Hughes, O. K. and Jablonowski, C. (2023), "A Mountain-Induced Moist Baroclinic Wave Test Case for the Dynamical Cores of Atmospheric General Circulation Models", Mon. Wea. Rev.

MeshWarpType

Strategy for warping the vertical grid to follow the surface elevation.

Subtypes:

• LinearWarp: terrain following at the surface, decaying linearly to flat at the model top.
• SLEVEWarp: smooth-level vertical coordinate, decaying the small-scale terrain faster than the large-scale terrain.

Has no effect when the topography is NoTopography.

LinearWarp()

Terrain-following warping in which the terrain influence decays linearly with height, vanishing at the top of the domain.

SLEVEWarp(; eta = 0.7, s = 10.0)

Smooth Level Vertical (SLEVE) coordinate warping for terrain-following meshes.

The terrain influence decays like sinh((ηₕ - η) / (s ηₕ)) / sinh(1 / s) in the normalized height η = z / z_top, so levels relax to flat faster than the linear decay of LinearWarp.

Fields

• eta = 0.7: Normalized height ηₕ above which no warping is applied, i.e. levels with z / z_top > eta are flat [-].
• s = 10.0: Decay scale as a fraction of the domain height; smaller values confine the terrain influence closer to the surface [-]. Grid construction errors unless s * z_top exceeds the maximum surface elevation.

References

Schär et al. (2002), "A new terrain-following vertical coordinate formulation for atmospheric prediction models", Mon. Wea. Rev.

AtmosModel{W, SCM, R, TC, PF, GW, VD, SP, SU, NU, CM, COSP}

Complete description of the physics of an atmospheric simulation: which parameterizations are active and how each is configured.

Components are stored in grouped sub-structs to keep the number of type parameters manageable, but they can be read either way: atmos.water.cloud_model and atmos.cloud_model return the same object, because Base.getproperty is overloaded to forward a grouped property to its owning group (see GROUPED_PROPERTY_MAP). The keyword constructor accepts the same flattened names.

Fields

• water: An AtmosWater group (moisture, cloud, microphysics).
• scm_setup: An SCMSetup group (single-column forcings).
• radiation: An AtmosRadiation group (radiation mode, insolation).
• turbconv: An AtmosTurbconv group (EDMF and LES closures).
• prescribed_flow: nothing, or a PrescribedFlow replacing the dynamics.
• gravity_wave: An AtmosGravityWave group.
• vertical_diffusion: nothing, or an AbstractVerticalDiffusion.
• sponge: An AtmosSponge group.
• surface: An AtmosSurface group.
• numerics: An AtmosNumerics group.
• chemistry: An AtmosChem group.
• cosp: nothing, or a COSPModel for the satellite simulator.
• disable_surface_flux_tendency: Whether to skip applying the surface flux tendency, independently of whether surface conditions are computed.

See the keyword constructor AtmosModel(; kwargs...) below.

AtmosModel(; kwargs...)

Create an AtmosModel, defaulting to a minimal dry atmosphere.

Every keyword argument is either the name of an AtmosModel field (a whole group, vertical_diffusion, cosp, prescribed_flow, or disable_surface_flux_tendency) or the name of a field of one of the grouped sub-structs. Flattened names are routed to their owning group through GROUPED_PROPERTY_MAP, so

AtmosModel(; microphysics_model = EquilibriumMicrophysics0M())

is equivalent to passing water = AtmosWater(; microphysics_model = ...). Passing a complete group object wins: any flattened keywords belonging to that group are then ignored. Unknown keywords raise an error listing every valid name.

The resulting model can be read either way:

model = AtmosModel(; microphysics_model = EquilibriumMicrophysics0M())
model.microphysics_model        # forwarded access
model.water.microphysics_model  # grouped access

With no keyword arguments the model is a minimal dry atmosphere:

• Dry atmosphere: DryModel(), with QuadratureCloud() but no SGS quadrature.
• Surface: AnalyticTemperature with a zonally symmetric SST, fixed exchange coefficients, and a constant albedo of 0.07.
• IdealizedInsolation(), and no radiation, turbulence-convection, gravity wave, sponge, or forcing model.
• Numerics: Van Leer limited upwinding for ρe_tot, ρq_tot, and the tracers, Explicit() diffusion, and CAM-SE-like Float32 hyperdiffusion.

Keyword Arguments

Grouped into the sub-struct that owns each name; see that struct's docstring for the full list of admissible values.

• AtmosWater: microphysics_model, cloud_model, microphysics_tendency_timestepping, tracer_nonnegativity_method, sgs_quadrature, terminal_velocity_mode.
• SCMSetup: subsidence, external_forcing, ls_adv, advection_test, scm_coriolis. Normally supplied by a Setups case.
• AtmosRadiation: radiation_mode, insolation.
• AtmosTurbconv: edmfx_model, turbconv_model, smagorinsky_lilly, amd_les, constant_horizontal_diffusion.
• AtmosGravityWave: non_orographic_gravity_wave, orographic_gravity_wave.
• AtmosSponge: viscous_sponge, rayleigh_sponge.
• AtmosSurface: flux_scheme, temperature, boundary_overrides, surface_albedo.
• AtmosNumerics: the five *_upwinding options, test_dycore_consistency, reproducible_restart, limiter, diff_mode, hyperdiff.
• AtmosChem: chemistry_model.
• Ungrouped AtmosModel fields: vertical_diffusion, prescribed_flow, cosp, and disable_surface_flux_tendency.

Examples

# Minimal dry model
model = AtmosModel()

# Dry model with Held-Suarez forcing and custom hyperdiffusion
model = AtmosModel(;
    radiation_mode = HeldSuarezForcing(),
    hyperdiff = Hyperdiffusion(;
        ν₄_vorticity_coeff = 1e15,
        divergence_damping_factor = 1.0,
        prandtl_number = 1.0,
    ),
)

# Moist model with all-sky radiation
model = AtmosModel(;
    microphysics_model = EquilibriumMicrophysics0M(),
    radiation_mode = RRTMGPI.AllSkyRadiation(),
)

Default Configuration

The default AtmosModel provides:

• Dry atmosphere: DryModel()
• Basic surface: AnalyticTemperature (zonally-symmetric SST) with default exchange coefficients
• Cloud model: QuadratureCloud() with SGS quadrature
• Idealized insolation: IdealizedInsolation()
• Conservative numerics: First-order upwinding with Explicit() timestepping
• No advanced physics: No radiation, turbulence, or forcing by default

Available Structs

AtmosWater

• microphysics_model: DryModel(), EquilibriumMicrophysics0M(), NonEquilibriumMicrophysics1M(), NonEquilibriumMicrophysics2M(), NonEquilibriumMicrophysics2MP3()
• cloud_model: GridScaleCloud(), QuadratureCloud()
• microphysics_tendency_timestepping: Explicit(), Implicit()
• sgs_quadrature: nothing or SGSQuadrature (subgrid-scale quadrature for microphysics tendencies)
• terminal_velocity_liquid: FixedTerminalVelocity (default) or DiagnosticTerminalVelocity
• terminal_velocity_ice: FixedTerminalVelocity (default) or DiagnosticTerminalVelocity
• terminal_velocity_rain: FixedTerminalVelocity or DiagnosticTerminalVelocity (default)
• terminal_velocity_snow: FixedTerminalVelocity (default) or DiagnosticTerminalVelocity

SCMSetup (Single-Column Model & LES specific - accessed via model.subsidence, model.external_forcing, etc.)

Internal testing and calibration components for single-column setups:

• subsidence: nothing or Bomexsubsidence, Ricosubsidence, DYCOMS_subsidence, etc
• external_forcing: nothing or external forcing objects (GCMForcing, ExternalDrivenTVForcing, ISDACForcing)
• ls_adv: nothing or LargeScaleAdvection()
• advection_test: Bool
• scm_coriolis: nothing or NamedTuple (; prof_ug, prof_vg, coriolis_param)

AtmosRadiation

• radiation_mode: Radiation and atmospheric forcing modes

  • Global radiation: RRTMGPI.ClearSkyRadiation(), RRTMGPI.AllSkyRadiation()
  • Atmospheric forcing: HeldSuarezForcing() (for idealized dynamics)
  • SCM-specific: RadiationDYCOMS(), RadiationISDAC(), RadiationTRMM_LBA()

• insolation: IdealizedInsolation(), TimeVaryingInsolation(), etc.

AtmosTurbconv

• edmfx_model: EDMFXModel()
• turbconv_model: nothing, PrognosticEDMFX(), EDOnlyEDMFX()
• smagorinsky_lilly: nothing or SmagorinskyLilly()
• amd_les: nothing or AnisotropicMinimumDissipation()
• constant_horizontal_diffusion: nothing or ConstantHorizontalDiffusion()

AtmosGravityWave

• non_orographic_gravity_wave: nothing or NonOrographicGravityWave()
• orographic_gravity_wave: nothing or OrographicGravityWave()

AtmosSponge

• viscous_sponge: nothing or ViscousSponge()
• rayleigh_sponge: nothing or RayleighSponge()

AtmosSurface

• flux_scheme: SurfaceConditions.MoninObukhov, SurfaceConditions.ExchangeCoefficients, or a default marker (DefaultMoninObukhov/DefaultExchangeCoefficients), or nothing to disable.
• temperature: SurfaceConditions.AnalyticTemperature, ExternalTemperature, SlabOceanTemperature, or CoupledTemperature.
• boundary_overrides: SurfaceConditions.SurfaceBoundaryOverrides
• surface_albedo: ConstantAlbedo(), RegressionFunctionAlbedo(), CouplerAlbedo()

AtmosNumerics # Create grouped structs - use provided complete objects or create from individual fields

• energy_q_tot_upwinding, tracer_upwinding, edmfx_mse_q_tot_upwinding, edmfx_sgsflux_upwinding, edmfx_tracer_upwinding: Val() upwinding schemes
• test_dycore_consistency: nothing or TestDycoreConsistency() for debugging
• limiter: nothing or QuasiMonotoneLimiter()
• vertical_water_borrowing_species: internal value nothing (apply to all tracers; config default is ~), empty tuple (apply to none; config []), or Tuple{Symbol, ...} from config string/list (e.g. ["ρq_tot"]) to apply only to those tracers. See config vertical_water_borrowing_species in defaultconfig.yml for YAML options. (Note: The vertical water borrowing limiter is created in the cache based on `AtmosWaterModel.tracernonnegativity_method`)
• diff_mode: Explicit(), Implicit() timestepping mode for diffusion
• hyperdiff: nothing or Hyperdiffusion()

Top-level Options

• vertical_diffusion: nothing, VerticalDiffusion(), DecayWithHeightDiffusion()
• disable_surface_flux_tendency: Bool

AtmosWater{MM, CM, MTTS, TNM, SQ, TVM}(; microphysics_model = DryModel(), kwargs...)

Group of moisture, cloud, and microphysics choices inside an AtmosModel.

Fields

• microphysics_model: An AbstractMicrophysicsModel; DryModel() by default.
• cloud_model: An AbstractCloudModel; QuadratureCloud() by default.
• microphysics_tendency_timestepping: Explicit(), Implicit(), or nothing when there is no microphysics.
• tracer_nonnegativity_method: nothing, or a TracerNonnegativityMethod.
• sgs_quadrature: nothing, or an SGSQuadrature used to integrate cloud and microphysics quantities over the subgrid-scale distribution.
• terminal_velocity_mode: DiagnosticTerminalVelocity() (the default) or a FixedTerminalVelocity.

Examples

water = ClimaAtmos.AtmosWater(;
    microphysics_model = ClimaAtmos.EquilibriumMicrophysics0M(),
    cloud_model = ClimaAtmos.GridScaleCloud(),
)

AtmosTurbconv{EDMFX, TCM, SL, AMD, CHD}(; edmfx_model = nothing, turbconv_model = nothing, kwargs...)

Group of turbulence, convection, and LES closures inside an AtmosModel.

Fields

• edmfx_model: nothing, or an EDMFXModel holding the EDMF term switches.
• turbconv_model: nothing, PrognosticEDMFX(...), or EDOnlyEDMFX().
• smagorinsky_lilly: nothing, or a SmagorinskyLilly.
• amd_les: nothing, or an AnisotropicMinimumDissipation.
• constant_horizontal_diffusion: nothing, or a ConstantHorizontalDiffusion.

AtmosRadiation{RM, IN}(; radiation_mode = nothing, insolation = IdealizedInsolation())

Group of radiation choices inside an AtmosModel.

Fields

• radiation_mode: nothing, an RRTMGP mode (RRTMGPI.GrayRadiation, ClearSkyRadiation, AllSkyRadiation, AllSkyRadiationWithClearSkyDiagnostics), an idealized profile (RadiationDYCOMS, RadiationISDAC, RadiationTRMM_LBA), or HeldSuarezForcing().
• insolation: An AbstractInsolation; IdealizedInsolation() by default.

AtmosSurface{FS, ST, BO, AL}(; flux_scheme, temperature, boundary_overrides, surface_albedo)

Group of surface models inside an AtmosModel: the flux closure, the surface temperature, per-cell boundary overrides, and the albedo.

By default the surface uses fixed exchange coefficients (Cd = Ch = 0.0044), a zonally symmetric analytic SST, no boundary overrides, and a constant albedo of 0.07.

Fields

• flux_scheme: a SurfaceConditions.SurfaceParameterization describing the surface flux closure (MoninObukhov, ExchangeCoefficients; MoninObukhov may carry a time-varying fluxes callable), or nothing to skip atmos-side surface updates (e.g. when an external driver overwrites sfc_conditions). YAML configs may also use DefaultMoninObukhov/DefaultExchangeCoefficients markers, which the config-driven AtmosSurface constructor resolves against params eagerly.
• temperature: a SurfaceConditions.SurfaceTemperature (AnalyticTemperature, ExternalTemperature, SlabOceanTemperature, CoupledTemperature).
• boundary_overrides: a SurfaceConditions.SurfaceBoundaryOverrides carrying per-cell defaults for surface pressure / humidity / winds / gustiness / beta.
• surface_albedo: a SurfaceAlbedoModel (ConstantAlbedo, RegressionFunctionAlbedo, CouplerAlbedo).

Examples

surface = ClimaAtmos.AtmosSurface(;
    temperature = ClimaAtmos.SurfaceConditions.SlabOceanTemperature{Float32}(),
)

AtmosSponge{VS, RS}(; viscous_sponge = nothing, rayleigh_sponge = nothing)

Group of model-top sponge layers inside an AtmosModel.

Fields

• viscous_sponge: nothing, or a ViscousSponge.
• rayleigh_sponge: nothing, or a RayleighSponge.

AtmosGravityWave{NOGW, OGW}(; non_orographic_gravity_wave = nothing, orographic_gravity_wave = nothing)

Group of gravity-wave drag parameterizations inside an AtmosModel.

Fields

• non_orographic_gravity_wave: nothing, or a NonOrographicGravityWave.
• orographic_gravity_wave: nothing, or an OrographicGravityWave (FullOrographicGravityWave or LinearOrographicGravityWave).

AtmosChem{CM}(; chemistry_model = nothing)

Group of chemistry models inside an AtmosModel.

Fields

• chemistry_model: nothing, or an AbstractChemistryModel such as GasPhaseChem().

AtmosNumerics{EN_UP, TR_UP, ED_UP, SG_UP, ED_TR_UP, TDC, RR, LIM, DM, HD}

Numerical options of an AtmosModel: upwinding schemes, limiter, diffusion timestepping mode, hyperdiffusion, and debugging switches.

The upwinding fields hold Val symbols so that the scheme is a compile-time dispatch: Val(:none), Val(:first_order), Val(:third_order), or Val(:vanleer_limiter). Use the keyword constructor below to pass them as plain symbols or strings.

Fields

• energy_q_tot_upwinding: Upwinding for the vertical advection of ρe_tot and ρq_tot.
• tracer_upwinding: Upwinding for the vertical advection of the remaining grid-scale tracers.
• edmfx_mse_q_tot_upwinding: Upwinding for the EDMF subdomain mse, q_tot, and TKE advection.
• edmfx_sgsflux_upwinding: Upwinding for the EDMF subgrid-scale mass flux.
• edmfx_tracer_upwinding: Upwinding for the EDMF subdomain tracers.
• test_dycore_consistency: nothing, or TestDycoreConsistency to fill the cache with NaNs for debugging.
• reproducible_restart: nothing, or ReproducibleRestart to make restarts reproducible.
• limiter: nothing, or QuasiMonotoneLimiter for horizontal tracer transport.
• diff_mode: Explicit() or Implicit(), the timestepping mode for vertical diffusion.
• hyperdiff: nothing, or a Hyperdiffusion model.

AtmosNumerics(; energy_q_tot_upwinding = :vanleer_limiter, tracer_upwinding = :vanleer_limiter,
              edmfx_mse_q_tot_upwinding = :first_order, edmfx_sgsflux_upwinding = :none,
              edmfx_tracer_upwinding = :first_order, test_dycore_consistency = nothing,
              reproducible_restart = nothing, limiter = nothing, diff_mode = Explicit(),
              hyperdiff = Hyperdiffusion{Float32}(...), kwargs...)

Create an AtmosNumerics, converting the upwinding options to Val types for compile-time dispatch.

Keyword Arguments

• energy_q_tot_upwinding = :vanleer_limiter: Upwinding for ρe_tot and ρq_tot vertical advection. Valid values are :none, :first_order, :third_order, and :vanleer_limiter, given as a Symbol, a String, or an already-wrapped Val.
• tracer_upwinding = :vanleer_limiter: Upwinding for the other grid-scale tracers, same valid values.
• edmfx_mse_q_tot_upwinding = :first_order: Upwinding for the EDMF subdomain mse, q_tot, and TKE.
• edmfx_sgsflux_upwinding = :none: Upwinding for the EDMF subgrid-scale mass flux.
• edmfx_tracer_upwinding = :first_order: Upwinding for the EDMF subdomain tracers.
• test_dycore_consistency = nothing: Pass TestDycoreConsistency() to fill the cache with NaNs.
• reproducible_restart = nothing: Pass ReproducibleRestart() for reproducible restarts.
• limiter = nothing: Pass QuasiMonotoneLimiter() to limit horizontal tracer transport.
• diff_mode = Explicit(): Timestepping mode for vertical diffusion.
• hyperdiff: Hyperdiffusion model; defaults to a Float32 Hyperdiffusion with the CAM-SE vorticity coefficient, divergence_damping_factor = 5, and prandtl_number = 1.0. Pass nothing to disable hyperdiffusion.

Examples

numerics = ClimaAtmos.AtmosNumerics(; tracer_upwinding = :third_order, hyperdiff = nothing)

AbstractMicrophysicsModel

Water and microphysics representation carried by the model.

The choice fixes which water tracers are prognostic and which microphysical conversion rates are computed. Selected by the YAML key microphysics_model.

Subtypes:

• DryModel: no water at all (microphysics_model: "dry").
• EquilibriumMicrophysics0M: saturation-adjustment equilibrium with a 0-moment sink ("0M").
• NonEquilibriumMicrophysics1M: 1-moment non-equilibrium cloud and precipitation ("1M").
• NonEquilibriumMicrophysics2M: 2-moment warm-rain microphysics ("2M").
• NonEquilibriumMicrophysics2MP3: 2-moment warm rain with P3 ice ("2MP3").

DryModel

Dry dynamics: no water tracers, no latent heating, no microphysics.

Selected by microphysics_model: "dry".

EquilibriumMicrophysics0M

Equilibrium (saturation-adjustment) moisture with a 0-moment precipitation sink.

Only ρq_tot is prognostic; cloud liquid and ice are diagnosed by saturation adjustment, and condensate in excess of a threshold is removed instantaneously. Selected by microphysics_model: "0M". Requires use_sgs_quadrature: true.

NonEquilibriumMicrophysics1M(; n_substeps = 1, n_substeps_quad = 1)

Non-equilibrium 1-moment microphysics with prognostic cloud and precipitation mass.

Carries ρq_tot, ρq_lcl, ρq_icl, ρq_rai, and ρq_sno, with conversion rates from CloudMicrophysics.jl. Selected by microphysics_model: "1M".

The substep counts are handed to CloudMicrophysics' averaged tendency evaluation, which subdivides the dynamics step into substeps and returns the time-averaged rates; this keeps the explicit sources stable at large dt.

Fields

• n_substeps: Number of substeps used when the tendencies are evaluated at grid-mean conditions (no SGS quadrature) [-].
• n_substeps_quad: Number of substeps used when the tendencies are integrated over the SGS quadrature [-].

Examples

model = ClimaAtmos.NonEquilibriumMicrophysics1M(; n_substeps = 3, n_substeps_quad = 2)

NonEquilibriumMicrophysics2M

Two-moment warm-rain microphysics: prognostic mass and number concentrations.

Cloud liquid and rain carry both mass and number, so the droplet size distribution responds to aerosol and dynamical forcing. There are no ice processes. Selected by microphysics_model: "2M".

NonEquilibriumMicrophysics2MP3

Two-moment warm rain combined with the P3 predicted-particle-properties ice scheme.

Extends NonEquilibriumMicrophysics2M with prognostic ice mass, ice number, rime mass, and rime volume. Selected by microphysics_model: "2MP3".

AbstractTerminalVelocityMode

Strategy for setting the sedimentation velocity of the water species.

Subtypes:

• DiagnosticTerminalVelocity: velocity diagnosed by CloudMicrophysics from the local density and specific humidity.
• FixedTerminalVelocity: prescribed constant velocity per species.

DiagnosticTerminalVelocity <: AbstractTerminalVelocityMode

Diagnose the mass-weighted terminal velocity of each species from the local state using the CloudMicrophysics size distributions.

FixedTerminalVelocity{FT} <: AbstractTerminalVelocityMode

Prescribed, state-independent terminal velocity for each 1-moment species, used in idealized tests where the sedimentation rate is to be controlled directly.

Sign convention: the stored values are downward fall speeds and must be non-negative.

TracerNonnegativityMethod

Strategy for keeping the microphysical tracers nonnegative.

The constrained tracers are the condensate tracers carried by the microphysics model (ρq_lcl, ρq_icl, ρq_rai, ρq_sno); q_tot is included as well when the qtot type parameter is true.

Subtypes:

• TracerNonnegativityElementConstraint{qtot}: redistribute tracer mass instantaneously within a spectral element, i.e. horizontally.
• TracerNonnegativityVaporConstraint{qtot}: redistribute tracer mass instantaneously between vapor (q_vap = q_tot - q_cond) and each tracer.
• TracerNonnegativityVaporTendency: exchange mass between vapor and each tracer gradually, through a tendency.
• TracerNonnegativityVerticalWaterBorrowing: redistribute tracer mass vertically with ClimaCore's VerticalMassBorrowingLimiter. The qtot type parameter is fixed to false for this method.

qtot is true when q_tot is among the constrained tracers, false otherwise.

Constructor

TracerNonnegativityMethod(method::String; include_qtot = false)

Build the method selected by method.

Arguments

• method: One of
  • "elementwise_constraint" → TracerNonnegativityElementConstraint{include_qtot}(),
  • "vapor_constraint" → TracerNonnegativityVaporConstraint{include_qtot}(),
  • "vapor_tendency" → TracerNonnegativityVaporTendency(),
  • "vertical_water_borrowing" → TracerNonnegativityVerticalWaterBorrowing().

Keyword Arguments

• include_qtot = false: Whether q_tot is also constrained. Passing true with "vapor_tendency" or "vertical_water_borrowing" is an error, because those methods do not support it.

Notes

In YAML configs the equivalent key is tracer_nonnegativity_method, where the include_qtot = true variants are spelled by appending _qtot to the method name (e.g. vapor_constraint_qtot).

Examples

method = ClimaAtmos.TracerNonnegativityMethod("vapor_constraint"; include_qtot = true)

TracerNonnegativityElementConstraint{qtot}

Restore nonnegativity by redistributing tracer mass horizontally within each spectral element. See TracerNonnegativityMethod.

TracerNonnegativityVaporConstraint{qtot}

Restore nonnegativity by moving mass between water vapor and the offending tracer at the same point. See TracerNonnegativityMethod.

TracerNonnegativityVaporTendency

Restore nonnegativity gradually, through a relaxation tendency that exchanges mass between water vapor and each tracer. See TracerNonnegativityMethod.

TracerNonnegativityVerticalWaterBorrowing

Restore nonnegativity by borrowing tracer mass from the level below, using ClimaCore's VerticalMassBorrowingLimiter with a threshold of zero. See TracerNonnegativityMethod.

AbstractCloudModel

Strategy for diagnosing the cloud fraction. Selected by the YAML key cloud_model.

Subtypes:

• GridScaleCloud: cloud fraction from grid-mean conditions ("grid_scale").
• QuadratureCloud: cloud fraction from the hybrid quadrature-moment formula ("quadrature").
• MLCloud: cloud fraction from a neural network ("MLCloud").

GridScaleCloud

Diagnose the cloud fraction from grid-mean conditions: a grid box is either fully cloudy or fully clear. Selected by cloud_model: "grid_scale".

QuadratureCloud

Diagnose the cloud fraction with the hybrid quadrature-moment formula, which integrates saturation over an assumed subgrid-scale joint distribution of temperature and total water. Selected by cloud_model: "quadrature".

MLCloud{M}

Diagnose the cloud fraction with a machine-learning model.

M is the type of the wrapped network, which is made GPU-friendly by MLCloud_constructor. Selected by cloud_model: "MLCloud", whose weights are read from the cloud_fraction_nn artifact.

Fields

• model: The callable network mapping local thermodynamic inputs to a cloud fraction in [0, 1] [-].

AbstractSGSamplingType

Sampling strategy for the subgrid-scale distribution of temperature and total water when cloud fraction and microphysical tendencies are evaluated.

Subtypes:

• SGSMean: evaluate at the grid mean only.
• SGSQuadrature: integrate over the SGS distribution with Gauss-Hermite quadrature (see SGSQuadrature).

SGSMean

Evaluate subgrid-scale diagnostics at the grid-mean state, without sampling the SGS distribution.

SGSQuadrature{N, A, W, D, FT} <: AbstractSGSamplingType

Subgrid-scale quadrature configuration for integrating over thermodynamic fluctuations of (T, q_tot).

N is the quadrature order, A and W the node and weight SVector types, D the AbstractSGSDistribution subtype, and FT the floating-point type. The two-dimensional rule evaluates N² points.

Fields

• a::A: Quadrature nodes in standardized variables [-].
• w::W: Quadrature weights [-].
• dist::D: SGS distribution type.
• T_min::FT: Floor applied to sampled temperatures [K], which keeps extreme nodes out of the domain-error region of the thermodynamics routines. Set from the ClimaParams temperature_minimum.
• q_max::FT: Cap applied to sampled specific humidity [kg/kg], which keeps extreme supersaturation at a node from driving unphysically low temperatures through excessive latent heat. Set from the ClimaParams specific_humidity_maximum.

Constructor

SGSQuadrature(
    FT; quadrature_order = 3, distribution = GaussianSGS(),
    T_min = FT(150), q_max = FT(0.05),
)

Build the quadrature for floating-point type FT. GridMeanSGS always overrides quadrature_order to N = 1. The T-q correlation coefficient is deliberately not stored here; it is supplied per call via correlation_Tq(params).

AbstractSGSDistribution

Joint subgrid-scale distribution of (T, q) assumed by the quadrature.

The distribution type selects how specific humidity is sampled from the quadrature nodes; temperature is always Gaussian. Each subtype has a corresponding transform functor built by create_physical_transform.

Subtypes:

• GaussianSGS: correlated bivariate Gaussian.
• LogNormalSGS: log-normal q, Gaussian T.
• GridMeanSGS: degenerate, grid-mean-only.

GridMeanSGS <: AbstractSGSDistribution

Degenerate SGS distribution: all mass at the grid mean.

A single node at $(χ_1, χ_2) = (0, 0)$ with weight $\sqrt{\pi}$, chosen so that the $1/\pi$ normalization of the two-dimensional quadrature returns the integrand evaluated at the mean. This is the zeroth-order option, taking the same code path as full quadrature; use it when SGS fluctuations are to be ignored.

GaussianSGS <: AbstractSGSDistribution

Bivariate Gaussian SGS distribution of (T, q).

Humidity is sampled first, and temperature is drawn from its distribution conditional on the sampled humidity, which reproduces the requested correlation. Sampled q is clamped to [0, q_max] and sampled T is floored at T_min, so extreme nodes cannot leave the physical domain.

LogNormalSGS <: AbstractSGSDistribution

Log-normal SGS distribution for specific humidity, Gaussian for temperature.

Sampling q in log space makes it positive-definite by construction, so the lower-tail truncation of GaussianSGS does not arise. The T-q correlation is imposed with a Gaussian copula on the underlying normal variates. The log-normal parameters degenerate for a vanishing mean or variance, in which case sampling falls back to the mean humidity.

AbstractPhysicalPointTransform

Functor mapping a pair of standardized quadrature nodes (χ1, χ2) to a physical state (T_hat, q_hat) [K, kg/kg].

One transform is built per grid cell by create_physical_transform, which precomputes every loop-invariant constant so the N² inner evaluations avoid repeated sqrt, log, and division. Subtypes correspond one-to-one to the AbstractSGSDistribution subtypes: GaussianPhysicalPointTransform, LogNormalPhysicalPointTransform, and GridMeanPhysicalPointTransform.

GridMeanPhysicalPointTransform{FT} <: AbstractPhysicalPointTransform

Transform for GridMeanSGS: returns (μ_T, μ_q) [K, kg/kg] for any node, ignoring the quadrature variables. No clamping is needed, since the grid-mean state is already physical.

Fields

• μ_T: Mean temperature [K].
• μ_q: Mean specific humidity [kg/kg].

GaussianPhysicalPointTransform{FT} <: AbstractPhysicalPointTransform

Transform for GaussianSGS. Samples q from its marginal, then T from the conditional distribution given q.

Fields

• μ_T, μ_q: Means of temperature [K] and specific humidity [kg/kg].
• σ_q: Standard deviation of specific humidity [kg/kg].
• σ_c: Conditional standard deviation of temperature, $\sigma_T \sqrt{1 - \rho^2}$ [K].
• fac: Regression slope $\rho \sigma_T / \sigma_q$ of T on q [K kg/kg⁻¹].
• T_min, q_max: Sampling bounds [K] and [kg/kg].

LogNormalPhysicalPointTransform{FT} <: AbstractPhysicalPointTransform

Transform for LogNormalSGS. Samples q in log space and T from a Gaussian correlated with it through a copula.

Fields

• μ_T, μ_q: Means of temperature [K] and specific humidity [kg/kg].
• σ_T: Standard deviation of temperature [K].
• μ_ln, σ_ln: Location and scale of the underlying normal in log space, matched to μ_q and σ_q [log kg/kg].
• c1, c2: Copula coefficients $\rho$ and $\sqrt{1 - \rho^2}$ [-].
• use_lognormal: false where μ_q or σ_q is too small for the log-normal parameters to be meaningful; sampling then returns μ_q.
• T_min, q_max: Sampling bounds [K] and [kg/kg].

create_physical_transform(dist, μ_q, μ_T, σ_q, σ_T, corr, T_min, q_max)

Build the AbstractPhysicalPointTransform functor for SGS distribution dist.

All loop-invariant constants (conditional standard deviations, regression slopes, log-space parameters) are computed here, so the N² inner evaluations avoid repeated sqrt, log, and division. A functor rather than a closure is used to keep the quadrature allocation-free on GPU.

Arguments

• dist: SGS distribution, dispatched on.
• μ_q, μ_T: Means of specific humidity [kg/kg] and temperature [K].
• σ_q, σ_T: Corresponding standard deviations [kg/kg] and [K].
• corr: Correlation coefficient, already clamped to [-1, 1] [-].
• T_min, q_max: Sampling bounds [K] and [kg/kg].

Called from integrate_over_sgs.

integrate_over_sgs(f, quad, μ_q, μ_T, q′q′, T′T′, corr_Tq)

Integrate f(T, q) over the bivariate SGS distribution.

Converts the variances to standard deviations, builds the transform functor for quad.dist (see create_physical_transform), and evaluates the Gauss-Hermite rule. Temperature is always Gaussian; quad.dist determines only how specific humidity is sampled. μ_T and μ_q are promoted to a common type so that either may independently be a Dual under autodiff, when ρe_tot or ρq_tot is perturbed.

Arguments

• f: Point-wise function (T_hat, q_hat) -> result.
• quad: SGSQuadrature holding distribution type, nodes, and weights.
• μ_q, μ_T: Mean specific humidity [kg/kg] and temperature [K].
• q′q′, T′T′: Variances of q [(kg/kg)²] and T [K²].
• corr_Tq: Correlation coefficient corr(T′, q′) [-].

Returns

The weighted sum $\approx E[f(T, q)]$, of the same type as f(T_hat, q_hat).

integrate_over_sgs(f, ::GridMeanSGS, μ_q, μ_T, q′q′, T′T′, corr_Tq)

Evaluate f(μ_T, μ_q) directly, the grid-mean fast path.

Lets callers pass a bare GridMeanSGS() without wrapping it in an SGSQuadrature, which would require knowing FT from the space. The variances and correlation are accepted for signature compatibility and ignored.

AbstractEDMF

Eddy-diffusivity/mass-flux turbulence-convection scheme. Selected by the YAML key turbconv; ~ disables the scheme entirely.

Subtypes:

• EDOnlyEDMFX: eddy diffusivity only, no mass flux ("edonly_edmfx").
• PrognosticEDMFX: prognostic updraft subdomains plus the environment ("prognostic_edmfx").

EDOnlyEDMFX

Eddy-diffusivity-only "EDMF": the mass-flux subdomains are dropped, leaving TKE-based vertical diffusion. TKE is always prognostic. Selected by turbconv: "edonly_edmfx".

PrognosticEDMFX{N, TKE, FT}

Prognostic eddy-diffusivity/mass-flux scheme with N updraft subdomains and an implicitly defined environment.

Each updraft carries prognostic ρa, u₃, mse, q_tot, and the microphysics tracers, and exchanges mass with the environment through entrainment and detrainment. TKE is a boolean type parameter selecting prognostic (true) or diagnostic (false) turbulent kinetic energy.

Fields

• a_half: Area fraction at which the SGS weight function equals 0.5, i.e. the threshold below which subdomain values are smoothly blended toward the grid mean [-]. Only meant to be used through specific.

See the constructor PrognosticEDMFX(; n_updrafts, prognostic_tke, area_fraction).

PrognosticEDMFX(; n_updrafts = 1, prognostic_tke = false, area_fraction)

Create a PrognosticEDMFX scheme with the given number of updrafts, TKE treatment, and small-area threshold.

Keyword Arguments

• n_updrafts = 1: Number of updraft subdomains, which becomes the type parameter N [-].
• prognostic_tke = false: Whether TKE is prognostic (true) or diagnostic (false); becomes the type parameter TKE.
• area_fraction: "Small" area-fraction threshold, passed as a_half to sgs_weight_function. Required; the float type of the scheme is inferred from it [-].

Examples

turbconv = ClimaAtmos.PrognosticEDMFX(;
    n_updrafts = 1, prognostic_tke = true, area_fraction = 1.0f-5,
)

EDMFXModel{EEM, EDM, ESMF, ESDF, ENP, EVD, EF, SBM}

Switches and closures of the EDMF scheme, kept separate from the turbulence-convection model itself (PrognosticEDMFX or EDOnlyEDMFX) so that the individual terms can be enabled independently.

The boolean switches are stored as Val{true}/Val{false} (see ValTF) so that the disabled terms are compiled away; the keyword constructor below accepts plain Bools.

Fields

• entr_model: Entrainment closure, an AbstractEntrainmentModel or nothing.
• detr_model: Detrainment closure, an AbstractDetrainmentModel or nothing.
• sgs_mass_flux: Whether the subgrid-scale mass flux is applied to the grid-mean equations (edmfx_sgs_mass_flux).
• sgs_diffusive_flux: Whether the subgrid-scale diffusive flux is applied (edmfx_sgs_diffusive_flux).
• nh_pressure: Whether the non-hydrostatic pressure drag closure is applied; the buoyancy term of the pressure closure is always on (edmfx_nh_pressure).
• vertical_diffusion: Whether the prognostic updrafts are vertically diffused (edmfx_vertical_diffusion).
• filter: Whether negative updraft vertical velocities are relaxed away (edmfx_filter).
• scale_blending_method: AbstractScaleBlendingMethod used to blend the mixing-length scales (edmfx_scale_blending).

EDMFXModel(; entr_model = nothing, detr_model = nothing, sgs_mass_flux = false,
           sgs_diffusive_flux = false, nh_pressure = false, vertical_diffusion = false,
           filter = false, scale_blending_method, kwargs...)

Create an EDMFXModel, lifting the boolean switches to Val types.

Keyword Arguments

• entr_model = nothing: Entrainment closure, e.g. InvZEntrainment().
• detr_model = nothing: Detrainment closure, e.g. BuoyancyVelocityDetrainment().
• sgs_mass_flux = false: Enable the subgrid-scale mass flux.
• sgs_diffusive_flux = false: Enable the subgrid-scale diffusive flux.
• nh_pressure = false: Enable the non-hydrostatic pressure drag.
• vertical_diffusion = false: Enable vertical diffusion of the updrafts.
• filter = false: Enable relaxation of negative updraft velocities.
• scale_blending_method: Required; an AbstractScaleBlendingMethod.

Each boolean may also be given as an already-wrapped Val{true}/Val{false}. Unrecognized keyword arguments are absorbed by kwargs... and ignored.

Examples

edmfx_model = ClimaAtmos.EDMFXModel(;
    entr_model = ClimaAtmos.InvZEntrainment(),
    detr_model = ClimaAtmos.BuoyancyVelocityDetrainment(),
    sgs_mass_flux = true,
    sgs_diffusive_flux = true,
    scale_blending_method = ClimaAtmos.SmoothMinimumBlending(),
)

AbstractEntrainmentModel

Closure for the rate at which environmental air is entrained into an EDMF updraft. Selected by the YAML key edmfx_entr_model.

Subtypes:

• PiGroupsEntrainment: rate built from the nondimensional Π groups ("PiGroups").
• InvZEntrainment: rate proportional to 1/z above the surface ("Generalized").

Subtypes dispatch entrainment_velocity_scale; the area-bounding relaxation in area_bounding_entr_detr is applied on top and does not dispatch on the model.

PiGroupsEntrainment

Entrainment velocity scale built from a linear combination of the nondimensional Π groups of [11], divided by height above the surface and multiplied by the upper-area limiter. Selected by edmfx_entr_model: "PiGroups".

InvZEntrainment

Entrainment velocity scale entr_coeff / (z - z_sfc), multiplied by the upper-area limiter. Selected by edmfx_entr_model: "Generalized".

AbstractDetrainmentModel

Closure for the rate at which updraft air is detrained into the environment. Selected by the YAML key edmfx_detr_model.

Subtypes:

• BuoyancyVelocityDetrainment: rate from the inverse buoyancy time scale and the mass-flux divergence ("Generalized").

Subtypes dispatch detrainment_rate, whose fallback for the abstract type returns zero. Only BuoyancyVelocityDetrainment currently defines a method, so the other subtypes give no dynamical detrainment; the area-bounding relaxation in area_bounding_entr_detr is applied regardless of the model.

BuoyancyVelocityDetrainment

Detrainment rate combining the clipped inverse buoyancy time scale with the convergence of the updraft mass flux, multiplied by the lower-area limiter and clipped at zero. Selected by edmfx_detr_model: "Generalized".

AbstractEnvBuoyGradClosure

Closure used to convert environmental thermodynamic gradients into a buoyancy gradient for the EDMF mixing-length and TKE budgets.

BuoyGradMean is currently the only subtype: it evaluates the buoyancy gradient from the mean environmental state, weighting the dry and cloudy branches by the cloud fraction.

BuoyGradMean

Compute the environmental buoyancy gradient from the mean environmental state. See AbstractEnvBuoyGradClosure and buoyancy_gradients.

AbstractScaleBlendingMethod

Method used to combine the candidate EDMF mixing-length scales into a single master length scale in blend_scales. Selected by the YAML key edmfx_scale_blending.

Subtypes:

• SmoothMinimumBlending: Lamb smooth minimum ("SmoothMinimum").
• HardMinimumBlending: plain minimum ("HardMinimum").

SmoothMinimumBlending

Blend the mixing-length scales with the Lamb smooth minimum, a differentiable approximation to minimum controlled by the smin_ub and smin_rm parameters. Selected by edmfx_scale_blending: "SmoothMinimum".

HardMinimumBlending

Blend the mixing-length scales by taking their plain minimum. Selected by edmfx_scale_blending: "HardMinimum".

AbstractTendencyModel

Marker selecting which part of a tendency is applied, used to isolate the grid-scale and subgrid-scale contributions in debugging and testing.

Subtypes: UseAllTendency (both parts), NoGridScaleTendency (subgrid-scale only), and NoSubgridScaleTendency (grid-scale only).

UseAllTendency

Apply both the grid-scale and the subgrid-scale part of a tendency. See AbstractTendencyModel.

NoGridScaleTendency

Skip the grid-scale part of a tendency. See AbstractTendencyModel.

NoSubgridScaleTendency

Skip the subgrid-scale part of a tendency. See AbstractTendencyModel.

AbstractCloudInRadiation

Describe how cloud properties should be set in radiation.

This is only relevant for RRTMGP.

InteractiveCloudInRadiation

Use the cloud properties computed by the model, so that clouds and radiation interact. Selected by prescribe_clouds_in_radiation: false.

PrescribedCloudInRadiation

Use monthly-average cloud properties from ERA5 in the radiative transfer, so that the model's own clouds do not feed back on radiation. Selected by prescribe_clouds_in_radiation: true, and only honored for all-sky radiation.

RadiationDYCOMS{FT}(; divergence = 3.75e-6, alpha_z = 1.0, kappa = 85.0, F0 = 70.0, F1 = 22.0)

Idealized longwave radiation for the DYCOMS stratocumulus cases of [12] and [13].

The net upward flux is parameterized from the liquid-water path above and below each level, plus a free-tropospheric term above the inversion (located at the q_tot = 8 g/kg isoline) that represents cooling by large-scale divergence. Selected by rad: "DYCOMS".

Fields

• divergence: Large-scale horizontal divergence [1/s].
• alpha_z: Coefficient of the free-tropospheric term above the inversion [-].
• kappa: Mass absorption coefficient of cloud liquid water [m²/kg].
• F0: Cloud-top longwave cooling amplitude [W/m²].
• F1: Cloud-base longwave warming amplitude [W/m²].

RadiationISDAC{FT}(; F₀ = 72, F₁ = 15, κ = 170)

Idealized longwave radiation for the ISDAC mixed-phase Arctic stratocumulus case.

The net upward flux is F₀ exp(-κ (LWP_top - LWP_z)) + F₁ exp(-κ LWP_z), where LWP_z is the liquid water path integrated from the surface to z. Selected by rad: "ISDAC".

Fields

• F₀: Cloud-top longwave cooling amplitude [W/m²].
• F₁: Cloud-base longwave warming amplitude [W/m²].
• κ: Mass absorption coefficient of cloud liquid water [m²/kg].

RadiationTRMM_LBA(::Type{FT})

Prescribed radiative heating profile for the TRMM-LBA deep-convection case, taken from AtmosphericProfilesLibrary.

The stored profile is evaluated as rad_profile(t, z) to give a temperature tendency [K/s], which is converted to an energy tendency. Selected by rad: "TRMM_LBA".

Fields

• rad_profile: Callable (t, z) returning the radiative heating rate [K/s].

AbstractInsolation

Source of the top-of-atmosphere solar flux and cosine of the solar zenith angle used by the radiative transfer solver. Selected by the YAML key insolation.

Subtypes:

• IdealizedInsolation: annual-mean insolation without a diurnal cycle ("idealized").
• TimeVaryingInsolation: orbital insolation evaluated at the current date ("timevarying").
• RCEMIPIIInsolation: the fixed RCEMIP-II values ("rcemipii").
• GCMDrivenInsolation: values read from the GCM-driven external forcing ("gcmdriven").
• ExternalTVInsolation: time-varying values read from a column forcing file ("externaldriventv").
• Larcform1Insolation: polar night, i.e. no incoming solar flux ("larcform1").

IdealizedInsolation

Annual-mean insolation without a diurnal cycle, following the approximation of [8]: a uniform TOA flux of 680 W/m² and a latitude-dependent cosine of the zenith angle μ = (1 + 0.3 (1 - 3 sin²ϕ)) / 2. Flat-space geometries are treated as being on the equator.

TimeVaryingInsolation(; start_date = nothing, latitude = nothing, longitude = nothing)

Compute insolation from the orbital parameters at the current simulation date.

When latitude/longitude are nothing, lat/lon are taken from the grid for LatLongZPoint coordinates and fall back to (0, 0) for flat-space columns (the default global behavior). When provided, the explicit lat/lon are used instead — useful for single-column setups whose coordinate system doesn't carry lat/lon (e.g. ARM VARANAL).

Fields

• start_date: DateTime used to convert a non-ITime simulation time t into a date; unused when t isa ITime. nothing when not needed.
• latitude: Latitude override [degrees], or nothing to use the grid.
• longitude: Longitude override [degrees], or nothing to use the grid.

Examples

insolation = ClimaAtmos.TimeVaryingInsolation(; latitude = 36.6, longitude = -97.5)

RCEMIPIIInsolation

Uniform, time-invariant insolation prescribed by the RCEMIP-II protocol [14]: a TOA flux of 551.58 W/m² with a solar zenith angle of 42.05°.

GCMDrivenInsolation

Take the cosine of the zenith angle and the TOA flux from the GCM-driven external forcing (p.external_forcing.cos_zenith and .toa_flux).

ExternalTVInsolation

Take time-varying coszen and downwelling shortwave rsdt from a column forcing file; the TOA flux is reconstructed as rsdt / coszen.

Larcform1Insolation

Polar-night insolation for the LARCFORM-1 setup: zero TOA flux, with the cosine of the zenith angle set to eps(FT) because RRTMGP requires a positive value.

SurfaceParameterization

Abstract supertype for surface flux closures. Concrete subtypes (MoninObukhov, ExchangeCoefficients) determine how surface_state_to_conditions turns the air–surface state difference into the turbulent surface fluxes.

MoninObukhov(; z0, z0m, z0b, fluxes, shf, lhf, θ_flux, q_flux, ustar)

Monin–Obukhov similarity theory (MOST) surface flux closure, the default SurfaceParameterization. See the SurfaceFluxes.jl MOST documentation for the theory.

Keyword Arguments

Roughness (required):

• z0: Roughness length, sets both z0m and z0b [m].
• z0m, z0b: Roughness lengths for momentum and scalars [m]. Specify both, or use z0.

Prescribed fluxes (optional) — specify via one of:

• fluxes: A HeatFluxes/θAndQFluxes struct, or a callable (t, FT) -> HeatFluxes/θAndQFluxes for time-varying fluxes (resolved once per surface update by resolve_flux_scheme, before the per-cell broadcast).
• shf, lhf: Sensible/latent heat fluxes [W/m²] — constructs HeatFluxes.
• θ_flux, q_flux: θ and q kinematic fluxes [K m/s], [kg/kg m/s] — constructs θAndQFluxes.

Other (optional):

• ustar: Friction velocity [m/s].

Valid combinations: roughness alone, or roughness with any of fluxes, ustar, or both.

ExchangeCoefficients(; Cd, Ch)
ExchangeCoefficients(C)

Bulk-aerodynamic surface flux closure with fixed, dimensionless exchange coefficients — a SurfaceParameterization alternative to MoninObukhov in which the turbulent fluxes scale linearly with the near-surface wind speed and the air–surface differences (rather than being derived from Monin–Obukhov stability).

Fields

• Cd: Momentum (drag) exchange coefficient [-].
• Ch: Thermal/scalar (heat and moisture) exchange coefficient [-].

The single-argument form ExchangeCoefficients(C) sets Cd = Ch = C.

HeatFluxes(; shf, lhf = nothing)

Prescribed surface turbulent energy fluxes, used as the fluxes field of a MoninObukhov closure. Both use the sign convention that positive is upward (directed from the surface into the atmosphere).

Fields

• shf: Sensible heat flux [W/m²].
• lhf: Latent heat flux [W/m²]. Optional — nothing is treated as zero, and lhf must be left unset for a DryModel (specifying it with a dry model is an error).

θAndQFluxes(; θ_flux, q_flux = nothing)

Prescribed surface kinematic fluxes of potential temperature and total specific humidity, used as the fluxes field of a MoninObukhov closure. They are converted per surface point into the sensible/latent heat fluxes actually applied, via shf = θ_flux * ρ_sfc * cp_m and lhf = q_flux * ρ_sfc * Lᵥ. Positive is upward (surface into atmosphere).

Fields

• θ_flux: Potential-temperature flux [K m/s].
• q_flux: Total-specific-humidity flux [kg/kg m/s]. Optional — nothing is treated as zero, and q_flux must be left unset for a DryModel.

DefaultMoninObukhov()

Callable that builds a MoninObukhov closure with roughness length z0 = 1e-5 m and no prescribed fluxes.

Calling DefaultMoninObukhov()(params) returns the closure at the float type of params; the indirection lets the configuration name a flux scheme before the parameter set exists.

DefaultExchangeCoefficients()

Callable that builds an ExchangeCoefficients closure with Cd = Ch = params.C_H, the exchange coefficient from the parameter set.

SurfaceTemperature

Abstract supertype for the sources of the surface temperature T_sfc [K] used when computing surface conditions.

Subtypes:

• AnalyticTemperature: a function (coordinates, params, t) -> T_sfc. A spatially and temporally constant T_sfc is constructed as AnalyticTemperature(Returns(T_sfc)).
• ExternalTemperature: a time-varying input read from a cached Field.
• SlabOceanTemperature: prognostic, reads Y.sfc.T; carries the slab parameters.
• CoupledTemperature: a Field owned by an external driver (the coupler).

Each subtype extends surface_temperature(temperature, Y, p, t_time), which returns the value that update_surface_conditions! broadcasts across the surface: either a DataLayout of per-cell temperatures, or the temperature object itself when it must be evaluated per coordinate (see resolve_T_sfc).

AnalyticTemperature(f)

A surface temperature given by f(coordinates, surface_temp_params, t) [K].

Used for the analytic SST formulas (zonally symmetric, RCEMIPII), time-varying setups (e.g. GABLS), and spatially uniform constants (AnalyticTemperature(Returns(T))). f is evaluated per coordinate inside the surface-update broadcast, so it must be GPU-compatible; if the formula does not depend on time, ignore the t argument.

Fields

• f: Callable (coordinates, surface_temp_params, t) -> T_sfc [K].

Examples

temperature = AnalyticTemperature(Returns(300.0))

SlabOceanTemperature{FT}(; depth_ocean, ρ_ocean, cp_ocean, q_flux, Q₀, ϕ₀)

Prognostic slab-ocean surface temperature, read from Y.sfc.T [K].

The only SurfaceTemperature that adds surface prognostic state (Y.sfc.T and Y.sfc.water); its fields are the slab parameters used by surface_temp_tendency! and by the conservation diagnostics. The optional Q-flux is an idealized meridional profile of ocean heat-flux divergence.

Fields

• depth_ocean = 40: Ocean mixed-layer depth [m].
• ρ_ocean = 1020: Ocean density [kg/m³].
• cp_ocean = 4184: Ocean specific heat capacity [J/kg/K].
• q_flux = false: Whether to apply the idealized Q-flux [-].
• Q₀ = -20: Q-flux amplitude [W/m²].
• ϕ₀ = 16: Q-flux meridional scale [degrees].

ExternalTemperature()

A surface temperature read from a time-varying external input [K].

surface_temperature(::ExternalTemperature, Y, p, t_time) evaluates p.external_forcing.surface_timevaryinginputs.ts into p.external_forcing.surface_fields.ts, so this temperature requires a setup that populates external_forcing.surface_fields from a file carrying the ts variable (e.g. ForcingFromFile).

CoupledTemperature(field)

A surface temperature owned by an external driver (the coupler) [K].

The driver writes into field between steps; ClimaAtmos only reads from it.

Fields

• field: Surface Field of temperatures [K].

SurfaceBoundaryOverrides(; p, q_vap, u, v, gustiness, beta)

Per-point overrides for surface boundary values consumed by surface_state_to_conditions. Fields default to nothing, in which case a default is used.

Fields

• q_vap: Surface specific humidity [kg/kg]. Default: saturation specific humidity over liquid water at T_sfc and the surface density.
• u, v: Surface horizontal wind components [m/s]. Default: 0.
• gustiness: Additional gustiness wind speed [m/s]. Default: 1.
• p, beta: Stored but currently not applied: surface_state_to_conditions only reads q_vap, u, v, and gustiness. The surface pressure/density always come from SurfaceFluxes.surface_density, and no moisture-availability factor is applied. These fields exist for interface compatibility.

For the coupler use case, a Fields.Field{<:SurfaceBoundaryOverrides} may be stored on the cache (p.sfc_setup) so that an external driver can set per-cell values; see update_surface_conditions!.

SurfaceAlbedoModel

Strategy for setting the direct and diffuse shortwave surface reflectivities seen by the radiation scheme (via set_surface_albedo!).

Subtypes:

• ConstantAlbedo: a single constant albedo for idealized experiments.
• RegressionFunctionAlbedo: the ocean-albedo regression of [9].
• CouplerAlbedo: albedo supplied externally by the coupler.

ConstantAlbedo{FT} <: SurfaceAlbedoModel

Spatially and temporally constant surface albedo, used for idealized experiments.

The same value is applied to the direct and diffuse shortwave albedos. The field has no default: the Julia-API default in AtmosModel is ConstantAlbedo(; α = 0.07), while the YAML configuration path constructs it from the ClimaParams parameter idealized_ocean_albedo (0.38, from O'Gorman and Schneider, 2008).

Fields

• α: Surface albedo for both direct and diffuse shortwave radiation [-].

RegressionFunctionAlbedo{FT}(; n, n0, p, q_clear, q_cloud, wave_slope)

Ocean surface albedo from the regression functions of [9] (J11), with direct and diffuse components computed separately. Volume reflectance (foam and subsurface scattering) is currently ignored.

Fields

• n: Relative refractive index of water and air, n = n_w/n_a [-].
• n0: Refractive index of water for visible light [-].
• p: Regression coefficients for the direct albedo (J11 eq. 4) [-].
• q_clear: Regression coefficients for the clear-sky diffuse albedo (J11 eq. 5a) [-].
• q_cloud: Regression coefficients for the cloudy-sky diffuse albedo (J11 eq. 5b) [-].
• wave_slope: Function of wind speed returning the mean wave-slope distribution width of the Cox-Munk model (J11 eq. 2) [-].

Constructor

The keyword constructor supplies the J11 regression coefficients as defaults, so RegressionFunctionAlbedo{FT}() is the standard usage.

CouplerAlbedo()

Surface albedo supplied by an external driver (the coupler), which writes the direct/diffuse shortwave albedos into the radiation cache. ClimaAtmos performs no albedo computation of its own in this mode.

AbstractVerticalDiffusion

Prescribed (non-EDMF) vertical diffusion closure for the boundary layer. Selected by the YAML key vert_diff; ~ disables vertical diffusion.

Subtypes:

• VerticalDiffusion: surface-driven diffusivity that decays above the boundary layer ("VerticalDiffusion").
• DecayWithHeightDiffusion: diffusivity decaying exponentially with height ("DecayWithHeightDiffusion").

Both are parameterized by a boolean DM selecting whether momentum diffusion is switched off; query it with disable_momentum_vertical_diffusion.

VerticalDiffusion{DM, FT}(; C_E)
VerticalDiffusion{FT}(; disable_momentum_vertical_diffusion, C_E)

Boundary-layer diffusion with a surface-driven eddy diffusivity.

The diffusivity is K_E = C_E ‖u_a‖ z_a below 850 hPa, where ‖u_a‖ and z_a are the wind speed and height of the lowest model level, and it decays as K_E exp(-((p_pbl - p) / p_strato)²) above, with p_pbl = 850 hPa and p_strato = 100 hPa.

DM is a boolean type parameter: when true, the closure diffuses scalars only and leaves momentum untouched.

Fields

• C_E: Dimensionless coefficient scaling the surface-driven diffusivity [-].

DecayWithHeightDiffusion{DM, FT}(; H, D₀)
DecayWithHeightDiffusion{FT}(; disable_momentum_vertical_diffusion, H, D₀)

Vertical diffusion with a diffusivity that decays exponentially with height above the surface, K = D₀ exp(-(z - z_sfc) / H).

DM is a boolean type parameter: when true, the closure diffuses scalars only and leaves momentum untouched.

Fields

• H: Decay scale height of the diffusivity [m].
• D₀: Diffusivity at the surface [m²/s].

EddyViscosityModel

Large-eddy-simulation closure providing a subgrid-scale eddy viscosity and diffusivity, used instead of (or alongside) the EDMF turbulence-convection schemes at LES resolutions.

Subtypes:

• SmagorinskyLilly: Smagorinsky-Lilly closure, selected by the YAML key smagorinsky_lilly.
• AnisotropicMinimumDissipation: AMD closure, selected by amd_les: true.
• ConstantHorizontalDiffusion: spatially uniform horizontal scalar diffusivity, selected by constant_horizontal_diffusion: true.

SmagorinskyLilly{AXES}

Smagorinsky-Lilly eddy viscosity model.

AXES is a symbol indicating along which axes the model is applied. It can be

• :UVW (all axes)
• :UV (horizontal axes)
• :W (vertical axis)
• :UV_W (horizontal and vertical axes treated separately).

Examples

Construct a model instance by passing the selected axes as a keyword argument:

smagorinsky_lilly = SmagorinskyLilly(; axes = :UV_W)

AnisotropicMinimumDissipation{FT}(; c_amd)

Anisotropic Minimum Dissipation (AMD) subgrid-scale closure of [3].

The eddy viscosity and diffusivity are built from velocity and scalar gradients scaled by the anisotropic filter widths, and are clipped at zero so the closure is purely dissipative. Enabled by amd_les: true.

Fields

• c_amd: Poincaré coefficient multiplying the AMD viscosity and diffusivity [-].

Examples

les = ClimaAtmos.AnisotropicMinimumDissipation{Float32}(; c_amd = 0.3)

ConstantHorizontalDiffusion{FT}(; D)

Horizontal diffusion of total energy and grid-scale tracers with a spatially uniform diffusivity. Momentum is not diffused. Enabled by constant_horizontal_diffusion: true, with D taken from the constant_horizontal_diffusion_D parameter.

Fields

• D: Horizontal diffusivity applied to energy and tracers [m²/s].

SpongeModel

Absorbing layer near the model top, used to prevent spurious reflection of vertically propagating waves off the rigid lid.

Subtypes:

• ViscousSponge: damp the horizontal Laplacian of the prognostic fields.
• RayleighSponge: damp the fields themselves.

Both are switched on by the YAML keys viscous_sponge and rayleigh_sponge, which take their coefficients from the model parameters.

RayleighSponge{FT}(; zd, α_uₕ = 0, α_w = 1, α_tracer = 0)

Rayleigh sponge model; damp variables in proportion to their own value.

Above the damping height zd, the sponge adds the tendency

\[∂χ/∂t = -β χ, z > zd\]

where β = α_χ ζ and the damping function is

\[ζ(z) = sin²(π (z - zd) / (2 (zmax - zd)))\]

with zmax the domain top height. The damped variables are the horizontal velocity uₕ (rate α_uₕ), the vertical velocity u₃ (rate α_w), and, when they are prognostic, ρtke and the PrognosticEDMFX subdomain scalars mseʲ, q_totʲ, and the subdomain microphysics and passive tracers (rate α_tracer). Subdomain scalars are relaxed toward their grid-mean value rather than toward zero, so only the subgrid-scale departure is damped.

By default only the vertical velocity is damped (α_uₕ = 0, α_w = 1, α_tracer = 0).

Fields

• zd: Lower damping height; the sponge is inactive below it [m].
• α_uₕ: Damping rate for the horizontal velocity, 0 by default [1/s].
• α_w: Damping rate for the vertical velocity, 1 by default [1/s].
• α_tracer: Damping rate for ρtke and the subdomain scalars, 0 by default [1/s].

Examples

# Apply damping to vertical velocity above 20 km
sponge = ClimaAtmos.RayleighSponge{Float32}(; zd = 20_000)

RayleighSponge(params)

Build a RayleighSponge from the model parameters, reading zd_rayleigh, alpha_rayleigh_uh, alpha_rayleigh_w, and alpha_rayleigh_tracer. Used when the config sets rayleigh_sponge: true.

ViscousSponge{FT}(; zd, κ₂)

Viscous sponge model; damp variables in proportion to their horizontal Laplacian.

Above the damping height zd, the sponge adds the tendency

\[∂χ/∂t = β ∇ₕ·(∇ₕ χ), z > zd\]

where β = κ₂ ζ and χ ∈ {uₕ, u₃, ρe_tot, GS_TRACERS}. The grid-scale tracers GS_TRACERS depend on the microphysics model and may include ρq_tot, ρq_lcl, ρq_icl, and so on; energy is diffused through the total specific enthalpy. With PrognosticEDMFX the sponge is additionally applied to the updraft vertical velocities u₃ʲ. The damping function is

\[ζ(z) = sin²(π (z - zd) / (2 (zmax - zd)))\]

with zmax the domain top height, so that damping ramps up smoothly from zd.

Fields

• zd: Lower damping height; the sponge is inactive below it [m].
• κ₂: Damping coefficient [m²/s].

Examples

# Apply damping above 20 km with κ₂ = 10⁶ m²/s
sponge = ClimaAtmos.ViscousSponge{Float32}(; zd = 20_000, κ₂ = 1e6)

ViscousSponge(params)

Build a ViscousSponge from the model parameters, reading zd_viscous and kappa_2_sponge. Used when the config sets viscous_sponge: true.

AbstractGravityWave

Parameterized drag exerted by unresolved gravity waves.

Subtypes:

• NonOrographicGravityWave: convectively and frontally generated wave spectrum, switched on by non_orographic_gravity_wave: true.
• OrographicGravityWave: waves generated by flow over unresolved topography, switched on by the orographic_gravity_wave key.

NonOrographicGravityWave{FT, BS}(; source_pressure, damp_pressure, ..., beres_source = nothing)

Non-orographic gravity-wave drag with the launch spectrum of [4].

A spectrum of waves is launched at a fixed source level and propagates vertically until it breaks; the resulting momentum-flux divergence is applied to the horizontal velocity. The launch amplitude varies with latitude so that the tropics can be treated separately from the extratropics. Switched on by non_orographic_gravity_wave: true, with the parameters taken from params.non_orographic_gravity_wave_params.

BS is the type of the optional convective source: nothing gives the background spectrum only, while a BeresSourceParams adds the Beres convective source on top of it wherever the EDMF scheme convects.

Fields

• source_pressure: Pressure of the launch level, used on spherical grids [Pa].
• damp_pressure: Pressure above which the waves are damped [Pa].
• source_height: Height of the launch level, used on single columns [m].
• Bw: Amplitude of the broad (westward) part of the launch spectrum [m²/s²].
• Bn: Amplitude of the narrow part of the launch spectrum [m²/s²].
• dc: Phase-speed grid spacing [m/s].
• cmax: Largest resolved phase speed; the grid spans -cmax:dc:cmax [m/s].
• c0: Reference phase speed about which the spectrum is centered [m/s].
• nk: Number of horizontal wave bands [-].
• cw: Phase-speed half-width of the broad spectrum outside the tropics [m/s].
• cw_tropics: Phase-speed half-width of the broad spectrum in the tropics [m/s].
• cn: Phase-speed half-width of the narrow spectrum [m/s].
• Bt_0: Background total source momentum flux [Pa].
• Bt_n: Additional source momentum flux in the northern hemisphere [Pa].
• Bt_s: Additional source momentum flux in the southern hemisphere [Pa].
• Bt_eq: Source momentum flux at the equator [Pa].
• ϕ0_n: Central latitude of the northern-hemisphere transition [degrees].
• ϕ0_s: Central latitude of the southern-hemisphere transition [degrees].
• dϕ_n: Northern edge of the tropical band [degrees].
• dϕ_s: Southern edge of the tropical band [degrees].
• beres_source: nothing, or a BeresSourceParams adding the convective source of [6].

OrographicGravityWave

Drag exerted by gravity waves generated by flow over unresolved topography.

Subtypes:

• FullOrographicGravityWave: the propagating plus blocked drag of [7], selected by orographic_gravity_wave: "raw_topo" or "gfdl_restart".
• LinearOrographicGravityWave: idealized variant with a user-supplied drag input, selected by orographic_gravity_wave: "linear".

Every subtype carries a topo_info field, a Val that selects how the subgrid orographic drag tensor is obtained (see get_topo_info).

FullOrographicGravityWave{FT, S, T}(; γ, ϵ, β, h_frac, ρscale, L0, a0, a1, Fr_crit, topo_info, topography)

Orographic gravity-wave drag following [7], combining the drag of vertically propagating waves with the drag of low-level blocked flow.

The subgrid obstacle distribution is summarized by the orographic tensor and the effective obstacle heights supplied through topo_info. Selected by orographic_gravity_wave: "raw_topo" or "gfdl_restart", with the shape parameters taken from params.orographic_gravity_wave_params.

Fields

• γ: Exponent relating obstacle width to height, L ∝ h^γ [-].
• ϵ: Exponent of the obstacle number density, n(h) ∝ h^(-ϵ) [-].
• β: Obstacle shape exponent in L(z) = L_b (1 - z/h)^β; β = 1 is triangular, β < 1 blunt, and β > 1 pointy [-].
• h_frac: Fraction setting the blocking threshold, h_crit = h_frac · V/N [-].
• ρscale: Reference density used to make the drag dimensional [kg/m³].
• L0: Reference obstacle width [m].
• a0: Coefficient of the propagating-wave drag [-].
• a1: Coefficient of the non-propagating (blocked) drag [-].
• Fr_crit: Critical Froude number separating the two regimes [-].
• topo_info: Val(:raw_topo) or Val(:gfdl_restart), selecting how the orographic drag tensor is built (see get_topo_info).
• topography: Val of the configured topography key, used when the drag tensor is computed on the fly.

LinearOrographicGravityWave{S}(; topo_info = Val(:linear))

Orographic gravity-wave drag driven by an analytical drag input, for idealized tests. Selected by orographic_gravity_wave: "linear".

Fields

• topo_info: Val(:linear), selecting the analytical drag input in get_topo_info.

AbstractForcing

Prescribed large-scale forcing imposed on a column or limited-area domain.

LargeScaleSubsidence is currently the only subtype; the other forcing objects in this file (LargeScaleAdvection, GCMForcing, ExternalDrivenTVForcing, ISDACForcing, HeldSuarezForcing) are dispatched on directly and are not part of this hierarchy.

LargeScaleSubsidence{T}

Prescribed large-scale subsidence, advecting scalars vertically with a specified subsidence velocity profile.

Total enthalpy and ρq_tot are subsided, as are ρq_lcl and ρq_icl for non-equilibrium microphysics; rain and snow are not. The profile is supplied by the setup (e.g. Setups.Bomex), not by a YAML key.

Fields

• prof: Callable prof(z) returning the subsidence velocity, negative for descent [m/s].

LargeScaleAdvection{PT, PQ}

Prescribed large-scale horizontal advective tendencies of temperature and total water, used in single-column setups. Supplied by the setup through Setups.large_scale_advection_forcing.

Fields

• prof_dTdt: Callable prof_dTdt(thermo_params, p, t, z) returning the large-scale temperature tendency, typically a cooling [K/s].
• prof_dqtdt: Callable prof_dqtdt(thermo_params, p, t, z) returning the large-scale total-water tendency, typically a drying [kg/kg/s].

HeldSuarezForcing

Held-Suarez idealized forcing: Newtonian relaxation of temperature toward a prescribed radiative-equilibrium profile plus Rayleigh friction on the low-level winds.

It is passed through the radiation_mode slot rather than as a forcing, because it replaces radiation in the dry dynamical-core benchmark. Selected by rad: "held_suarez".

GCMForcing{FT}(external_forcing_file, cfsite_number)

Forcing and nudging profiles extracted from a GCM simulation at a single CFMIP (cfSite) location.

FT is the float type of the fields built from the file. Selected by external_forcing: "GCM", which reads external_forcing_file and cfsite_number from the config.

Fields

• external_forcing_file: Path to the NetCDF file holding the GCM profiles.
• cfsite_number: Identifier of the cfSite column within that file, e.g. "07".

ISDACForcing

Analytic large-scale forcing for the ISDAC mixed-phase Arctic stratocumulus case. Selected by external_forcing: "ISDAC", and supplied automatically by Setups.ISDAC.

PrescribedFlow{FT}

Prescribed velocity field that replaces the solved dynamics, used by kinematic test cases. Selected by the YAML key prescribed_flow, which requires flat topography and the explicit solver.

ShipwayHill2012VelocityProfile is currently the only subtype. Subtypes are callable as flow(z, t) and must also define get_ρu₃qₜ_surface.

ShipwayHill2012VelocityProfile{FT}

Prescribed vertical velocity of the kinematic driver of [15]. Selected by prescribed_flow: "ShipwayHill2012".

The instance is callable; see the call method below.

AbstractChemistryModel

Atmospheric chemistry treatment. Selected by the YAML key chemistry_model; ~ disables chemistry.

GasPhaseChem is currently the only subtype.

GasPhaseChem

Carry a single passive gas-phase tracer q_gas_A, used to exercise the tracer infrastructure. Selected by chemistry_model: "passive".

AbstractTimesteppingMode

Whether a process is integrated explicitly or implicitly.

Subtypes: Explicit and Implicit. Used for the diff_mode numerics option (config key implicit_diffusion) and for microphysics_tendency_timestepping (config key implicit_microphysics).

Explicit

Integrate the process explicitly, as part of the remaining tendency.

Implicit

Integrate the process implicitly, as part of the Newton solve, which requires a corresponding Jacobian block.

Hyperdiffusion{FT}(; ν₄_vorticity_coeff, divergence_damping_factor, prandtl_number)

Fourth-order horizontal hyperdiffusion applied to velocity and scalars.

The coefficients are resolution-aware: the hyperviscosity is ν₄_vorticity = ν₄_vorticity_coeff * h³, where h is the mean nodal distance of the horizontal grid, and the scalar hyperdiffusivity is ν₄_scalar = ν₄_vorticity / prandtl_number (see ν₄).

Fields

• ν₄_vorticity_coeff: Resolution-independent vorticity hyperviscosity coefficient [m/s].
• divergence_damping_factor: Multiplier on the divergent part of the momentum hyperdiffusion relative to the rotational part [-].
• prandtl_number: Ratio of the vorticity hyperviscosity to the scalar hyperdiffusivity [-].

Examples

hyperdiff = ClimaAtmos.Hyperdiffusion{Float32}(;
    ν₄_vorticity_coeff = 0.150,
    divergence_damping_factor = 5,
    prandtl_number = 1.0,
)

Selected by hyperdiff: "Hyperdiffusion", whose coefficients come from the vorticity_hyperdiffusion_coefficient, divergence_damping_factor, and hyperdiffusion_prandtl_number config keys. See also cam_se_hyperdiffusion.

QuasiMonotoneLimiter

Marker selecting ClimaCore's QuasiMonotoneLimiter for horizontal tracer transport, which clips element-wise tracer extrema to those of the upwind neighborhood. Selected by apply_sem_quasimonotone_limiter: true.

Jacobian(alg, Y, atmos; [verbose])

Wrapper for a JacobianAlgorithm and its cache, which it uses to update and invert the Jacobian. ClimaTimeSteppers.jl interacts with it through update_jacobian! (before each linear solve) and LinearAlgebra.ldiv! (each linear solve). The optional verbose flag specifies whether debugging information should be printed during initialization.

JacobianAlgorithm

Strategy for computing the matrix $∂R/∂Y$, where $R(Y)$ denotes the residual of an implicit step with the state $Y$.

Subtypes:

• ManualSparseJacobian: sparse blocks from analytically derived tendency derivatives.
• AutoDenseJacobian: dense column matrices from forward-mode automatic differentiation.
• AutoSparseJacobian: sparse blocks from forward-mode automatic differentiation with matrix coloring.

Concrete implementations of this abstract type should define 3 methods:

• jacobian_cache(alg::JacobianAlgorithm, Y, atmos; [verbose]): allocate the cache used to store and invert the Jacobian.
• update_jacobian!(alg::JacobianAlgorithm, cache, Y, p, dtγ, t): update the cached entries of $∂R/∂Y = dtγ⋅∂Yₜ/∂Y − I$.
• invert_jacobian!(alg::JacobianAlgorithm, cache, ΔY, R): solve $(∂R/∂Y)⋅ΔY = R$ for $ΔY$.

To facilitate debugging, concrete implementations should also define first_column_block_arrays(alg::JacobianAlgorithm, Y, p, dtγ, t).

See Implicit Solver for additional background information.

ManualSparseJacobian(; approximate_solve_iters = 1)

A JacobianAlgorithm that approximates the Jacobian using analytically derived tendency derivatives and inverts it using a specialized nested linear solver.

Which derivative blocks are computed is determined automatically from the AtmosModel (topography, diffusion mode, and the prognostic variables in Y) when the cache is built — users do not configure them directly. The blocks are assembled from per-process builders and updated by per-process update functions; see the implicit Jacobian section of Implicit Solver.

Keyword Arguments

• approximate_solve_iters = 1: Number of iterations to take for the approximate linear solve required when grid-scale diffusion is treated implicitly [-].

Fields

• approximate_solve_iters: As above [-].

AutoDenseJacobian([max_simultaneous_derivatives])

A JacobianAlgorithm that computes the Jacobian using forward-mode automatic differentiation, without making any assumptions about sparsity structure. After the dense matrix for each spatial column is updated, parallel_lu_factorize! computes its LU factorization in parallel across all columns. The linear solver is also run in parallel with parallel_lu_solve!.

To automatically compute the derivative of implicit_tendency! with respect to Y, we first create copies of Y, p.precomputed, and p.scratch in which every floating-point number is replaced by a dual number from ForwardDiff.jl. A dual number can be expressed as $Xᴰ = X + ε₁x₁ + ε₂x₂ + ... + εₙxₙ$, where $X$ and $xᵢ$ are floating-point numbers, and where $εᵢ$ is a hyperreal number that satisfies $εᵢεⱼ = 0$. If the $i$-th value in dual column state $Yᴰ$ is set to $Yᴰᵢ = Yᵢ + 1εᵢ$, where $Yᵢ$ is the $i$-th value in the column state $Y$, then evaluating the implicit tendency of the dual column state generates a dense representation of the Jacobian matrix $∂T/∂Y$. Specifically, the $i$-th value in the dual column tendency $Tᴰ = T(Yᴰ)$ is $Tᴰᵢ = Tᵢ + (∂Tᵢ/∂Y₁)ε₁ + ... + (∂Tᵢ/∂Yₙ)εₙ$, where $Tᵢ$ is the $i$-th value in the column tendency $T(Y)$, and where $n$ is the number of values in $Y$. In other words, the entry in the $i$-th row and $j$-th column of the matrix $∂T/∂Y$ is the coefficient of $εⱼ$ in $Tᴰᵢ$. The size of the dense matrix scales as $O(n^2)$, leading to very large memory requirements at higher vertical resolutions.

When the number of values in each column is very large, computing the entire dense matrix in a single evaluation of implicit_tendency! can be too expensive to compile and run. So, the dual number components are split into partitions with a maximum size of max_simultaneous_derivatives, and we call implicit_tendency! once for each partition. That is, if the partition size is $s$, then the first partition evaluates the coefficients of $ε₁$ through $εₛ$, the second evaluates the coefficients of $εₛ₊₁$ through $ε₂ₛ$, and so on until $εₙ$. The default partition size is 32.

Arguments

• max_simultaneous_derivatives = 32: Number of dual number components per evaluation of implicit_tendency!, stored as the type parameter S [-].

AutoSparseJacobian(sparse_jacobian_alg, [padding_bands_per_block])

A JacobianAlgorithm that computes the Jacobian using forward-mode automatic differentiation, assuming that the Jacobian's sparsity structure is given by sparse_jacobian_alg.

Only entries that are expected to be nonzero according to the sparsity structure are updated, but any other entries that are nonzero can introduce errors to the updated entries. This issue can be avoided by adding padding bands to blocks that are likely to introduce errors. In cases where the default padding bands are insufficient, padding_bands_per_block can be specified to add a fixed number of padding bands to every block.

The sparsity structure is colored with SparseMatrixColorings, so that one evaluation of implicit_tendency! per color suffices to fill every block. The same sparse_jacobian_alg also supplies the linear solver used by invert_jacobian!.

Fields

• sparse_jacobian_alg: The SparseJacobian algorithm whose sparsity structure and linear solver are reused.
• padding_bands_per_block: Number of padding bands added to every block, or nothing to use the per-block defaults [-].

For more information about this algorithm, see Implicit Solver.

AutoSparseJacobian(; approximate_solve_iters = 1, padding_bands_per_block = nothing)

Construct an AutoSparseJacobian that reuses the sparsity structure of an inner ManualSparseJacobian built from approximate_solve_iters.

AutoSparseJacobian(sparse_jacobian_alg, [padding_bands_per_block = nothing])

Construct an AutoSparseJacobian that reuses the sparsity structure of the given sparse_jacobian_alg.

DiagnosticsConfig(; default = true, additional = (),
                  interpolation_num_points = nothing, output_at_levels = true)

Specify which diagnostics a simulation produces and how their NetCDF output is shaped.

A single DiagnosticsConfig value is passed to AtmosSimulation through its diagnostics keyword argument. A simulation produces no diagnostics when default = false, debug_tendency = false, and additional is empty. The type parameter A is the type of the additional collection.

Fields

• default::Bool = true: Whether to include the built-in ClimaAtmos diagnostic set for the chosen AtmosModel, as returned by default_diagnostics.
• additional::A = (): Extra user-supplied diagnostics. Mixed collections are allowed; each entry is normalized by normalize_diag_entry and can be:
  • a ClimaDiagnostics.ScheduledDiagnostic, used as-is for full control;
  • a Pair of short name to options, e.g. "ua" => (; period = "30mins", reduction = "average");
  • a NamedTuple with at least short_name and period, e.g. (; short_name = "ts", period = "1hours");
  • a YAML-style Dict{String, Any}, the shape produced by the diagnostics: YAML key.
• interpolation_num_points = nothing: Override for the NetCDF remap grid, e.g. (180, 90, 10). When nothing, the default for the underlying space is used.
• output_at_levels::Bool = true: Whether to write on model levels, applying no vertical interpolation. Set to false to interpolate to pressure levels instead.
• debug_tendency::Bool = false: include the column-integrated per-process tendency diagnostics (short names of the form <field>_tend_<process>_colint). Debug-only; each sample allocates a full Y-sized FieldVector and runs one extra tendency evaluation.

A simulation produces no diagnostics when default = false, debug_tendency = false, and additional is empty.

Examples

import ClimaAtmos as CA

# Defaults only.
config = CA.DiagnosticsConfig()

# Defaults plus half-hourly mean zonal wind and hourly instantaneous surface temperature.
config = CA.DiagnosticsConfig(;
    additional = (
        "ua" => (; period = "30mins", reduction = "average"),
        (; short_name = "ts", period = "1hours"),
    ),
)

simulation = CA.AtmosSimulation{Float64}(; diagnostics = config)

update_surface_conditions!(Y, p, t)

Fill p.precomputed.sfc_conditions from the current state Y and time t.

Called once per explicit precomputed-quantity update, from set_explicit_precomputed_quantities!. Returns nothing early, leaving sfc_conditions untouched, when atmos.surface.flux_scheme is nothing (the coupler-handoff case, in which an external driver writes the surface fields).

The surface temperature and the flux scheme are resolved once here — not per cell — and the boundary overrides are wrapped so that both a scalar SurfaceBoundaryOverrides and a coupler-provided Fields.Field{<:SurfaceBoundaryOverrides} broadcast correctly. The per-point work is done by surface_state_to_conditions, broadcast over DataLayouts (rather than Fields) because it mixes surface and first-interior values.

See the Surface Conditions page for the user-facing guide and the Surface Conditions Internals page for the data flow.

surface_state_to_conditions(
    overrides, parameterization, T_sfc_in, surface_local_geometry,
    T_int, ρ_int, q_tot_int, q_liq_int, q_ice_int, u_int, v_int, z_int,
    thermo_params, surface_fluxes_params, surface_temp_params, atmos, t_time,
)

Compute the surface conditions at one surface point.

Broadcast over the surface by update_surface_conditions!. The surface density comes from SurfaceFluxes.surface_density (extrapolated from the first interior level), and, for a moist model, the surface air is assumed saturated over liquid water unless overrides.q_vap says otherwise. The parameterization selects how SurfaceFluxes.surface_fluxes is configured: ExchangeCoefficients supplies fixed Cd/Ch, while MoninObukhov supplies roughness lengths (and gustiness) when no fluxes are prescribed, or the prescribed shf/lhf and ustar when they are. A θAndQFluxes closure is converted here to shf/lhf using the local ρ_sfc, cp_m, and latent heat of vaporization.

Arguments

• overrides: Per-point SurfaceBoundaryOverrides; only q_vap, u, v, and gustiness are consumed.
• parameterization: The SurfaceParameterization flux closure, with any time-varying fluxes already resolved by resolve_flux_scheme.
• T_sfc_in: A scalar or per-cell surface temperature [K], or an AnalyticTemperature to evaluate at this point (see resolve_T_sfc).
• surface_local_geometry: Local geometry at the surface, supplying the coordinates and the surface normal.
• T_int, ρ_int, q_tot_int, q_liq_int, q_ice_int, u_int, v_int, z_int: First-interior-level temperature [K], density [kg/m³], specific humidities [kg/kg], horizontal velocity components [m/s], and height [m].
• thermo_params, surface_fluxes_params, surface_temp_params: Parameter sets for thermodynamics, SurfaceFluxes, and the analytic surface temperature.
• atmos: The AtmosModel, used here to detect a DryModel.
• t_time: Simulation time, passed to an AnalyticTemperature [s].

Returns

The NamedTuple built by atmos_surface_conditions, whose type is given by surface_conditions_type.

Errors when overrides.q_vap, lhf, or q_flux is specified for a DryModel.

atmos_surface_conditions(
    surface_fluxes_params, surface_conditions, ρ_sfc, surface_local_geometry,
)

Convert a SurfaceFluxes.SurfaceFluxConditions struct into the NamedTuple of surface values and covariant flux vectors used by ClimaAtmos.

The scalar fluxes returned by SurfaceFluxes are given a direction here: the energy and moisture fluxes are projected onto the surface normal, and the momentum fluxes ρτxz, ρτyz are assembled into a tensor. Only the horizontal part of the momentum flux is kept (ρ_flux_uₕ). The buoyancy flux is computed from shf, lhf, and ρ_sfc.

Returns

(; T_sfc, q_vap_sfc, ustar, obukhov_length, buoyancy_flux, ρ_flux_uₕ, ρ_flux_h_tot, ρ_flux_q_tot), with temperature [K], specific humidity [kg/kg], friction velocity [m/s], Obukhov length [m], buoyancy flux [m²/s³], and the energy [W/m²] and moisture [kg/m²/s] fluxes as C3 vectors, positive upward. ρ_flux_q_tot is always present, even for a DryModel.

ColumnDataset(path; format = nothing, options...)

Handle to one column forcing file.

Construction runs the format's validate method and then probes, once, which canonical variables the file carries, so that a non-conforming or incomplete file errors here rather than mid-simulation.

Fields

• format: The AbstractColumnFormat of the file; the native ClimaColumnFile unless the format keyword says otherwise.
• path: Path to the file.
• options: Format-specific options passed through as keywords at construction.
• column_vars, surface_vars: The canonical column and surface variables the file actually carries.

open_dataset(f, format, path, options)
open_dataset(f, cd::ColumnDataset)

Open the file and apply f to the format-resolved NCDataset, closing it afterwards. A format whose data lives in a subgroup rather than at the root overrides this to pass the group to f instead.

has_variable(format, ds, name::Symbol)

Whether the canonical variable name is available from this file. Formats with derived variables override this alongside the corresponding read_* method.

read_profile(format, ds, name::Symbol, time_index)

The vertical profile of canonical variable name at one time index, in the file's level order, with preprocess applied.

read_series(format, ds, name::Symbol)

The full time series of the surface variable name, with preprocess applied.

read_initial_profiles(cd, ds, start_date)

The initial-condition profiles at the file time closest to start_date.

Returns

(; z, ta, ua, va, hus, rho): the height coordinate [m] and the CANONICAL_IC_VARS profiles, all sorted ascending in z. Errors, naming what is absent, when the file lacks a variable needed to build an initial condition.

read_surface_series(cd, names, start_date)

Read the surface variables names in a single file open.

The data layer that both surface_timevaryinginputs and data-backed surface components, such as a prescribed-flux scheme, build on.

Returns

(; times, name₁ = series₁, ...), where times is the simulation time axis in seconds with t = 0 at start_date, and each series has preprocess applied.

height_profile(format, ds, options)

The heights of the file's column levels, in the file's storage order [m].

This is where a format absorbs its vertical convention, e.g. dividing a geopotential by g or converting pressure levels to height.

site_location(format, ds)
site_location(cd::ColumnDataset)

Return a NamedTuple (; latitude, longitude) of the column site in degrees. Consumed by whoever constructs behavior that needs the location (e.g. an astronomical insolation model). The default is an informative error.

dates(format, ds)

The file's time axis as a vector of DateTimes. The default requires a CF-decodable time variable; formats with nonstandard time conventions (e.g. base_time offsets) override this.

file_time_span(cd, start_date)

The time in seconds from start_date to the file's last time. A simulation longer than this runs past the end of the file's data.

simulation_times(format, ds, start_date)

The file's time axis as simulation time in seconds, with t = 0 at start_date.

time_index_closest(format, ds, date)

Index of the file time closest to date.

wraps_periodically(method)

Whether a TimeVaryingInput method repeats its data past the file's time range (a PeriodicCalendar boundary) instead of erroring out of range.

column_timevaryinginputs(cd, names, target_space, start_date; method)

A NamedTuple of TimeVaryingInputs, one per requested column variable, targeting target_space, the model's center column space.

The default builds file-backed inputs, applying the format's extrapolation_bc and preprocess hooks. A format whose on-disk layout the file readers cannot consume directly — a grouped file, or a non-height vertical coordinate — overrides this to build in-memory inputs instead.

surface_timevaryinginputs(cd, names, target_space, start_date; method)

A NamedTuple of TimeVaryingInputs, one per requested surface variable, read into in-memory inputs on the simulation time axis (t = 0 at start_date) from a single file open.

time_interpolation_method(format)

Return the method for this format's TimeVaryingInputs, which fixes the time-interpolation and the out-of-range extrapolation policy. The default is plain LinearInterpolation(): it interpolates linearly within the file's time span and errors out of range, so a finite campaign cannot fabricate forcing by wrapping around. A case whose file stores one repeating period (e.g. the monthly-averaged-diurnal ERA5 file, one day) overrides this with periodic_calendar_method.

periodic_calendar_method()

The TimeVaryingInput method that repeats a file's time axis periodically, for a file that stores exactly one period. Passed as an ExternalDrivenTVForcing time_interpolation_method by the monthly-averaged-diurnal ERA5 case, whose file stores a single day.

extrapolation_bc(format)

Extrapolation setting for file-backed TimeVaryingInputs of this format, matching the dimensionality of its stored variables.

preprocess(format, name::Symbol)

Elementwise function applied to every value of the canonical variable name read from this format (unit conversions, fill-value handling). Applied both by the direct read_* methods and, through the file reader's preprocess_func hook, by file-backed TimeVaryingInputs.

CANONICAL_COLUMN_VARS

The canonical column (z, time) forcing variables, named after their CMIP short names and stored in SI units. A file-driven forcing requires only the subset needed by the terms it composes.

CANONICAL_SURFACE_VARS

The canonical surface (time,) forcing variables, named after their CMIP short names and stored in SI units.

CANONICAL_IC_VARS

The canonical variables a file must carry for read_initial_profiles to build a column initial condition: temperature, both wind components, specific humidity, and density.

missing_forcing_variables(cd, column_vars, surface_vars)
missing_forcing_variables(cd)

The requested forcing variables absent from the file: those in the given column_vars/surface_vars, or (single-argument form) the full canonical vocabulary.

require_forcing_variables(cd, column_vars, surface_vars)

Error, naming what is absent, unless the file carries every variable in column_vars (needed by the composed forcing terms) and surface_vars (needed by the resolved model).

validate(::ClimaColumnFile, path)

Check that path follows the ClimaColumn schema and throw a descriptive error otherwise. Checks the (z, time) layout, a strictly ascending z coordinate with at least two levels, a CF-decodable time coordinate, exact canonical SI units on all recognized data variables, and the site location attributes.

validate(format, path)

Check path against the format's specification, throwing a descriptive error listing all violations. The default is a no-op for formats without a formal specification.

AbstractColumnFormat

Supertype of the column forcing-file formats. A format is a singleton subtype that teaches the generic machinery how to read one on-disk layout: it extends format_name, format_variable_name, and height_profile (plus optional hooks), and is passed via the format keyword of ColumnDataset. The native format is ClimaColumnFiles.ClimaColumnFile.

format_name(format)

The display name of the format, used in error messages.

format_variable_name(format, name::Symbol)

The file variable name for the canonical variable name, or nothing when the format cannot represent it directly (e.g. a derived variable, handled by a read_* override instead).

ClimaColumnFile()

Format singleton for files following the ClimaColumn schema, and the default format of a ColumnDataset.

Canonical variable names are used verbatim as file variable names, the height coordinate is read directly from z, and the site location comes from the site_latitude/site_longitude global attributes.

CANONICAL_UNITS

SI units of the canonical variables, written as each variable's units attribute by write_column_forcing_file and required exactly by validate.

is_conforming(path)

Whether path is a file that fully conforms to the ClimaColumn schema, i.e. validate passes (native (z, time) layout, strictly-ascending z, canonical SI units, site attributes). Returns false rather than throwing, so this can gate cache reuse: a file left by an older writer in a stale layout — or a structurally-native file that fails validation (e.g. unsorted z) — is treated as non-conforming and regenerated instead of read (which would fail loudly in ColumnDataset).

write_column_forcing_file(path, FT;
    z, time, time_attrib, column_vars, surface_vars,
    site_latitude, site_longitude)

Write a ClimaColumn schema file at path with element type FT, and return path.

The single producer implementation, shared by the ERA5 generator and every converter. Each variable name must have its units registered in CANONICAL_UNITS; an unregistered name is an error rather than a file that later fails validate.

Keyword Arguments

• z: Strictly ascending heights of the column levels [m].
• time: Vector of DateTimes, written with time_attrib.
• time_attrib: Attributes of the time variable, giving the CF units and calendar.
• column_vars: Pairs name => matrix, each matrix of shape (z, time).
• surface_vars: Pairs name => vector, each vector over time.
• site_latitude, site_longitude: Site coordinates [degrees].

to_climacolumn(path; thermo_params, dir = dirname(path), overwrite = false)

Read the ARM VARANAL file path, write an equivalent ClimaColumn file into dir, and return the written path.

The written file carries the canonical (z, time) column variables ta, hus, ua, va, wa, rho, tntha, and tnhusha, the (time,) surface variables ts plus hfls/hfss when the source has them, and the site_latitude/site_longitude global attributes. VARANAL's vertical-advection tendencies (T_adv_v, q_adv_v) are deliberately dropped: vertical transport instead comes from the subsidence term acting on the model's evolving profiles.

Arguments

• path: Path to the source ARM VARANAL file.

Keyword Arguments

• thermo_params: Thermodynamics parameter set, supplying the g, R_d, and R_v used to map pressure levels to geometric height, convert omega to a subsidence velocity, and derive density.
• dir = dirname(path): Output directory. The default keeps the converted file next to the source so that it is reused across runs; pass a writable dir when the source directory is read-only.
• overwrite = false: Whether to rewrite the file even when a conforming one already sits at the target path.

ClimaAtmos

The atmosphere model of the CliMA Earth system model.

ClimaAtmos solves the fully compressible equations of motion for a deep atmosphere in a coordinate-independent formulation, with the same equation set in Cartesian geometries, for large-eddy and cloud-resolving simulation, and on the sphere, for global weather and climate simulation. Energy, air mass, and water are conserved to floating-point precision, and the model runs on CPUs and GPUs from one code base.

A simulation is described by an AtmosSimulation, which bundles a grid, an AtmosModel, a parameter set, and an integrator. Constructing one sets everything up; solve_atmos! advances it to t_end. Common configurations are available as one-line presets in the Presets submodule. See the Your First Simulation, Governing Equations, and API pages of the documentation.

Examples

import ClimaAtmos as CA
simulation = CA.AtmosSimulation{Float32}(; t_end = "1days")
CA.solve_atmos!(simulation)

Parameters

Parameter structs for ClimaAtmos and accessors for their values.

The top-level container is ClimaAtmosParameters, which holds the parameters that ClimaAtmos owns directly, together with the parameter sets of the packages it calls (Thermodynamics, CloudMicrophysics, SurfaceFluxes, RRTMGP, and Insolation). The structs here are plain, immutable, isbits value types, so they can be captured by GPU kernels; they are built from a ClimaParams TOML dictionary by the constructors in create_parameters.jl.

Every parameter is read through an accessor function of one argument, e.g. CAP.planet_radius(params), rather than by field access. The accessors are generated by @eval loops at the bottom of this module, one loop per parameter set, and they all take an AbstractClimaAtmosParameters. Three patterns appear:

• Fields of ClimaAtmosParameters itself, forwarded as ps.$var.
• Fields of a sub-parameter set, forwarded through the accessor of that set, e.g. max_area(ps) = max_area(turbconv_params(ps)).
• Parameters owned by another package, forwarded to that package's accessor, e.g. R_d(ps) = TD.Parameters.R_d(thermodynamics_params(ps)).

The uniform one-argument interface is what lets a tendency ask for a parameter without knowing which package defines it, and lets parameter sets be swapped (for calibration, or for a reduced set) without touching call sites.

ClimaAtmos.Diagnostics

Definitions of the diagnostic variables ClimaAtmos knows how to compute.

Each variable is registered with add_diagnostic_variable!, which records its metadata and a compute function of (state, cache, time), and is looked up by short name with get_diagnostic_variable. default_diagnostics assembles the per-model defaults, the helpers in standard_diagnostic_frequencies.jl wrap them in reductions over calendar periods, and DiagnosticsConfig is the user-facing entry point that selects them for a simulation.

Scheduling, accumulation, and output are handled by ClimaDiagnostics.

RRTMGPInterface

Wrapper around RRTMGP.jl that builds and feeds an RRTMGP.RRTMGPSolver from ClimaAtmos fields.

The module owns the ClimaAtmos-facing radiation modes (AbstractRRTMGPMode and its subtypes), the solver constructor rrtmgp_solver, and the per-callback input updates in update_inputs.jl. The radiative transfer itself, and the derivations behind it, belong to RRTMGP.jl; see also the radiation docs page, docs/src/radiation.md.

AtmosArtifacts

Paths to the input datasets that ClimaAtmos reads from CliMA artifacts.

Each function returns the path of one file (or directory) inside its artifact, downloading the artifact on first use. Several datasets ship in a high- and a low-resolution version; res_file_path prefers the high-resolution one and falls back to the low-resolution one, which can always be downloaded.

All functions take an optional context keyword, the ClimaComms context, which lazy artifacts need in MPI runs so that only one rank downloads.

ColumnDatasets

Data access for single-column (SCM) forcing files.

The file format is a singleton type (ClimaColumnFile, the native ClimaColumn schema) whose module extends a small interface: canonical variable names to file names, the file layout (profile, surface series, height coordinate), and per-variable unit/derivation hooks. Generic machinery (the ColumnDataset handle, TimeVaryingInput builders, initial-profile reads) consumes it through that interface.

Adding a format

Define a singleton subtype of AbstractColumnFormat in a new module under src/column_datasets/, extend the three required methods (format_name, format_variable_name, height_profile) plus any optional ones (open_dataset, preprocess, dates, read_profile, read_series, extrapolation_bc, time_interpolation_method, site_location, validate), and pass it via the format keyword of ColumnDataset.

ClimaColumnFiles

The native CliMA column forcing format: pure 1D (z, time) column variables plus (time,) surface variables, canonical CMIP short names with SI units attributes, a strictly ascending height coordinate z [m], CF time, and the global attributes site_latitude and site_longitude. Files are recognized by this structure, so any file in the right shape works without special markers.

VaranalFiles

Converter from the ARM VARANAL (Variational Analysis) product to the native ClimaColumn schema. VARANAL files store the column state and forcing tendencies on pressure levels, with non-CMIP names, mixed units (K/hr, g/kg, hPa/hr, degC), -9999 fill values, and a base_time time axis that the ClimaColumn reader does not consume directly.

to_climacolumn reads a VARANAL file once and writes an equivalent ClimaColumn file via ClimaColumnFiles.write_column_forcing_file, which the standard ColumnDataset path then reads like any other ClimaColumn file. Same pattern as the ERA5 generator: one converter per source.

parallel_lu_factorize!(device, matrices, ::Val{N})

Run a parallel LU factorization algorithm on the specified device. If each slice matrices[1:N, 1:N, i] represents a matrix $Mᵢ$, this function overwrites it with the lower triangular matrix $Lᵢ$ and the upper triangular matrix $Uᵢ$, where $Mᵢ = Lᵢ * Uᵢ$. The value of N must be wrapped in a Val to ensure that it is statically inferrable, which allows the LU factorization to avoid dynamic local memory allocations.

No pivoting is performed: a zero or NaN pivot throws an error rather than being reordered away. The runtime of this algorithm scales as $O(N^3)$.

See also parallel_lu_solve!.

parallel_lu_solve!(device, vectors, matrices, ::Val{N})

Run a parallel LU solver algorithm on the specified device. If each slice vectors[1:N, i] represents a vector $vᵢ$, and if each slice matrices[1:N, 1:N, i] represents a matrix $Lᵢ * Uᵢ$ that was factorized by parallel_lu_factorize!, this function overwrites the slice vectors[1:N, i] with $(Lᵢ * Uᵢ)⁻¹ * vᵢ$. The value of N must be wrapped in a Val to ensure that it is statically inferrable, which allows the LU solver to avoid dynamic local memory allocations.

The runtime of this algorithm scales as $O(N^2)$.