GitHub

Setups

A setup defines the initial conditions for a simulation case. At its core, a setup is a struct that implements center_initial_condition, which returns a physical state NamedTuple at each grid point. The physical state describes the thermodynamic and kinematic state through temperature, pressure or density, moisture, velocity and is converted into prognostic variables automatically based on the model configuration.

center_initial_condition

Every setup must implement this method. It is called pointwise over the grid and returns a ClimaAtmos.Setups.physical_state NamedTuple. Only T and one of p or ρ are required; all other fields default to zero.

For example, a minimal setup:

struct MySetup end

function Setups.center_initial_condition(::MySetup, local_geometry, params)
    z = local_geometry.coordinates.z
    FT = typeof(z)
    return physical_state(; T = FT(300), p = FT(101500))
end
ClimaAtmos.Setups.physical_state — Function
physical_state(; T, p=NaN, ρ=NaN, kwargs...)

Construct a NamedTuple representing the physical state at a grid point. This is the return type of center_initial_condition — it describes the thermodynamic and kinematic state without any knowledge of the atmos model.

The assembly layer (prognostic_variables.jl) converts this into model-specific prognostic variables.

Required arguments

  • T: Temperature (K)
  • At least one of p (pressure, Pa) or ρ (density, kg/m³). If only one is provided, the assembly layer computes the other via Thermodynamics.

Optional arguments (default to zero)

  • u, v: Zonal and meridional velocity (m/s)
  • q_tot, q_liq, q_ice: Specific humidities
  • tke: Turbulent kinetic energy (specific)
  • draft_area: EDMF draft area fraction
  • q_rai, q_sno: Precipitation specific humidities
  • n_liq, n_rai: Number densities (2-moment microphysics)
  • n_ice, q_rim, b_rim: P3 microphysics fields
source

face_initial_condition

Returns face (vertical interface) state variables. Must include w (vertical velocity); may also include w_draft for EDMF updraft initialization. Defaults to zero vertical velocity.

ClimaAtmos.Setups.face_initial_condition — Function
face_initial_condition(setup, local_geometry, params)

Return a NamedTuple of face state variables:

  • w: Vertical velocity (m/s)
  • w_draft: EDMF draft vertical velocity (m/s)

Default

Returns (; w = 0, w_draft = 0).

source

surface_condition

Returns surface boundary data for the setup. The return value can be:

  • A SurfaceConditions.SurfaceState (static surface conditions)
  • A callable (surface_coordinates, interior_z, t) -> SurfaceState (time-varying)
  • nothing (falls through to config-based surface setup)

Not all setups need this — only those that prescribe case-specific surface properties (e.g., roughness length, surface fluxes, surface temperature).

ClimaAtmos.Setups.surface_condition — Function
surface_condition(setup, params)

Return the surface state for this setup, or nothing.

The return value may be:

  • A SurfaceState (static surface conditions)
  • A callable (surface_coordinates, interior_z, t) -> SurfaceState (time-varying)
  • nothing (falls through to config-based surface condition)

Default: nothing.

source

overwrite_initial_state!

For file-based setups (e.g., ERA5, GCM-driven) that operate on the full prognostic state Y rather than pointwise. Called after the standard pointwise initialization and overwrites fields in-place with regridded file data. Defaults to a no-op.

ClimaAtmos.Setups.overwrite_initial_state! — Function
overwrite_initial_state!(setup, Y, thermo_params)

Optionally overwrite the initial state Y after construction. Used by file-based setups that operate at the field level rather than pointwise.

Default: no-op.

source

SCM Forcing Methods

Single-column setups can provide forcing profiles that replace the corresponding YAML config keys. When a method returns nothing (the default), the config key is used instead.

ClimaAtmos.Setups.subsidence_forcing — Function
subsidence_forcing(setup, FT)

Return a subsidence profile function z -> w_subsidence, or nothing. When non-nothing, the returned profile is wrapped in a Subsidence struct by the model construction layer, replacing the subsidence config key.

source
ClimaAtmos.Setups.large_scale_advection_forcing — Function
large_scale_advection_forcing(setup, FT)

Return (; prof_dTdt, prof_dqtdt) as raw APL profile functions, or nothing. The model construction layer wraps these into a LargeScaleAdvection struct, replacing the ls_adv config key.

source

Model Methods

Setups can return model objects directly. When a method returns nothing (the default), the model construction layer falls through to config-based dispatch.

Adding a New Setup

To add a new setup (e.g. MyCase), you need three things:

1. Create the setup file

Create src/setups/MyCase.jl with a struct and a center_initial_condition method:

"""
    MyCase

Description of the case and citation.
"""
struct MyCase end

function center_initial_condition(::MyCase, local_geometry, params)
    FT = eltype(params)
    (; z) = local_geometry.coordinates
    T = FT(300) - FT(0.01) * z
    p = FT(101500)
    return physical_state(; T, p)
end

Optionally implement any of the other interface methods detailed above.

2. Include the file in Setups.jl

Add an include("MyCase.jl") line in src/setups/Setups.jl under the setup implementations section.

3. Wire the setup in get_setup_type

Add a branch in get_setup_type in src/solver/type_getters.jl that maps the initial_condition config string to your setup constructor:

elseif ic_name == "MyCase"
    return Setups.MyCase()

Then set initial_condition: "MyCase" in your YAML config file to use it.

Available Setups

SCM Cases

ClimaAtmos.Setups.Bomex — Type
Bomex

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

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

Example

import Thermodynamics as TD
import ClimaParams as CP
FT = Float64
toml_dict = CP.create_toml_dict(FT)
thermo_params = TD.Parameters.ThermodynamicsParameters(toml_dict)
setup = Bomex(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.Rico — Type
Rico

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

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

Example

import Thermodynamics as TD
import ClimaParams as CP
FT = Float64
toml_dict = CP.create_toml_dict(FT)
thermo_params = TD.Parameters.ThermodynamicsParameters(toml_dict)
setup = Rico(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.Soares — Type
Soares

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

Example

setup = Soares(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.GABLS — Type
GABLS

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

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

Example

setup = GABLS(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.GATE_III — Type
GATE_III

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

Example

setup = GATE_III(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.DYCOMS — Type
DYCOMS{P, FT}

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

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

Example

setup = DYCOMS_RF01(; prognostic_tke = true, thermo_params)
setup = DYCOMS_RF02(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.TRMM_LBA — Type
TRMM_LBA

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

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

Example

setup = TRMM_LBA(; prognostic_tke = true, thermo_params)
source
ClimaAtmos.Setups.ISDAC — Type
ISDAC

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

When perturb is true, applies pseudorandom temperature perturbations of amplitude 0.1 K below 825 m.

Example

setup = ISDAC(; prognostic_tke = true, perturb = false, thermo_params)
source
ClimaAtmos.Setups.SimplePlume — Type
SimplePlume(; prognostic_tke = false)

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

Example

setup = SimplePlume(; prognostic_tke = true)
source
ClimaAtmos.Setups.PrecipitatingColumn — Type
PrecipitatingColumn

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

source
ClimaAtmos.Setups.ShipwayHill2012 — Type
ShipwayHill2012

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

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

source
ClimaAtmos.Setups.RCEMIPIIProfile — Type
RCEMIPIIProfile(temperature, humidity)

An initial condition following the sounding for RCEMIPII as described by Wing et al. (2018) (https://doi.org/10.5194/gmd-11-793-2018).

Three convenience constructors are provided:

  • RCEMIPIIProfile_295() — SST = 295 K
  • RCEMIPIIProfile_300() — SST = 300 K
  • RCEMIPIIProfile_305() — SST = 305 K

Note: this should be used for RCEsmall and NOT RCElarge — RCElarge must be initialized with the final state of RCEsmall.

source

Global Cases

ClimaAtmos.Setups.DecayingProfile — Type
DecayingProfile(; perturb = true, params)

A setup with a decaying temperature profile (from Thermodynamics.jl), with an optional perturbation to the temperature field.

Uses DecayingTemperatureProfile with Tsurface=290K, Tmin=220K, z_scale=8km.

source
ClimaAtmos.Setups.IsothermalProfile — Type
IsothermalProfile(; temperature = 300)

A setup with a uniform temperature and barometric pressure profile.

Example

setup = IsothermalProfile(; temperature = 300)
source
ClimaAtmos.Setups.ConstantBuoyancyFrequencyProfile — Type
ConstantBuoyancyFrequencyProfile()

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

Used for topography test cases.

Example

setup = ConstantBuoyancyFrequencyProfile()
source
ClimaAtmos.Setups.DryBaroclinicWave — Type
DryBaroclinicWave(; perturb = true, deep_atmosphere = false)

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

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

source
ClimaAtmos.Setups.MoistBaroclinicWave — Type
MoistBaroclinicWave(; perturb = true, deep_atmosphere = false)

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

Example

setup = MoistBaroclinicWave(; perturb = true, deep_atmosphere = false)
source
ClimaAtmos.Setups.DryDensityCurrentProfile — Type
DryDensityCurrentProfile()

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

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

Example

setup = DryDensityCurrentProfile()
source
ClimaAtmos.Setups.RisingThermalBubbleProfile — Type
RisingThermalBubbleProfile()

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

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

Example

setup = RisingThermalBubbleProfile()
source
ClimaAtmos.Setups.MoistAdiabaticProfileEDMFX — Type
MoistAdiabaticProfileEDMFX(; perturb = false)

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

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

Example

setup = MoistAdiabaticProfileEDMFX(; perturb = true)
source

Data-Driven

ClimaAtmos.Setups.GCMDriven — Type
GCMDriven{FT}

Pointwise column IC driven by GCM forcing NetCDF data.

Fields

  • external_forcing_file: Path to the GCM forcing NetCDF file.
  • cfsite_number: Site identifier within the NetCDF file (e.g., "site23").
  • profiles: ColumnProfiles of 1D interpolators (T, u, v, q_tot, ρ).
  • T_sfc: Mean surface temperature from the forcing file.

Example

setup = GCMDriven("path/to/HadGEM2-A_amip.2004-2008.07.nc", "site23")
source
ClimaAtmos.Setups.InterpolatedColumnProfile — Type
InterpolatedColumnProfile

Reads vertical profiles from a time-varying external forcing NetCDF file at a specific time index and builds 1D interpolators via ColumnProfiles.

This setup is used for single-column simulations initialized from ERA5 reanalysis data with time-varying external forcing (e.g., "ReanalysisTimeVarying").

Example

setup = InterpolatedColumnProfile("path/to/era5_forcing.nc", "20070701")
source
ClimaAtmos.Setups.MoistFromFile — Type
MoistFromFile(file_path)

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

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

Fields

  • file_path: Path to the NetCDF file containing initial condition data.

Expected variables in the file

  • p: pressure (2D surface, broadcast in z)
  • t: temperature (3D)
  • q: specific humidity (3D)
  • u, v, w: velocity (3D)
  • cswc, crwc: snow and rain water content (optional)
  • z_sfc: surface altitude (optional, for topographic pressure correction)
source
ClimaAtmos.Setups.WeatherModel — Type
WeatherModel

ERA5-derived initial condition for weather/forecast simulations.

Assigns NaN placeholders during pointwise construction, then overwrites the full prognostic state with ERA5 data obtained via weather_model_data_path.

Fields

  • start_date: DateTime parsed from a date string in format "yyyymmdd" or "yyyymmdd-HHMM".
  • era5_initial_condition_dir: Optional directory with pre-processed ERA5 files. When nothing, uses the weather_model_ic ClimaArtifact.
  • use_full_pressure: If true, attempt to read 3D pressure from the file rather than computing it hydrostatically. Defaults to false.
source
ClimaAtmos.Setups.AMIPFromERA5 — Type
AMIPFromERA5(start_date)

AMIP initial condition using ERA5 monthly reanalysis data.

Assigns NaN placeholders during pointwise construction, then overwrites the full prognostic state with ERA5 data from the era5_inst_model_levels ClimaArtifact, delegating to overwrite_from_file!.

Fields

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

Expected artifact structure

era5_inst_model_levels/era5_init_processed_internal_YYYYMMDD_0000.nc

source