Running Single-Column Cases

Idealized cases

ClimaAtmos.jl supports several canonical test cases, run in a single-column model, that check how well PROPHET reproduces each convective regime. They include variants of bomex, dycoms, rico, soares, gabls, and trmm, and live in the config/model_configs directory. The table below summarizes what each one probes:

Abbreviation	Long Name	Cloud Regime	Reference
BOMEX	Barbados Oceanographic and Meteorological Experiment	Marine Cumulus	Siebesma et al. (2003)
DYCOMS	Dynamics and Chemistry of Marine Stratocumulus	Marine Stratocumulus	Stevens et al. (2005), Ackerman et al. (2009)
RICO	Rain in Cumulus over the Ocean	Rainy Cumulus	Rauber et al. (2007)
SOARES	Shallow Cumulus Convection	Shallow Cumulus	Soares et al. (2004)
GABLS	GEWEX Atmospheric Boundary Layer Study	Stable Boundary Layer	Beare et al. (2006)
TRMM	Tropical Rainfall Measuring Mission	Deep Convection	Grabowski et al. (2006)

These are the canonical intercomparison cases; the Setups reference page lists all available setups, including further idealized columns.

To run the BOMEX test case from the configuration file, start Julia in the project root (julia --project) and execute the following:

import ClimaAtmos as CA

# get the configuration arguments
config = CA.AtmosConfig(
    "config/model_configs/prognostic_edmfx_bomex_column.yml";
    job_id = "bomex",
)
simulation = CA.AtmosSimulation(config)
sol_res = CA.solve_atmos!(simulation) # run the simulation

These lines run each case on this page; only the configuration file changes. CI runs these cases with a common diagnostics file prepended (e.g. config/common_configs/diagnostics_column_progedmf_1M.yml); see Creating custom configurations for combining configuration files.

Externally driven single-column models

ClimaAtmos.jl currently supports several externally driven single-column setups: GCM driven, ReanalysisTimeVarying, ReanalysisMonthlyAveragedDiurnal, and ARM VARANAL. Externally driven means that the model is initialized and forced with data from a different simulation or analysis product, rather than from steady or prescribed functional forcing as in BOMEX or SOARES. These setups were developed for model calibration and testing, by recreating statistics close to either LES (for the GCM driven case only) or observations.

GCM-driven case

For the GCM driven case, run the configuration file config/model_configs/prognostic_edmfx_gcmdriven_column.yml. In the config, the following settings are important:

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

Setting initial_condition to GCM selects the GCM-driven setup, which takes the external forcing, surface treatment, and insolation from the external file. The external_forcing_file and cfsite_number together determine the temperature, specific humidity, and wind, as well as the horizontal and vertical advection profiles that drive the simulation; external_forcing_file can point to a local file instead of the artifact. Radiation and surface temperature are specified there too. The forcing file, an example of which is stored in the artifact, holds one group per cfsite. See Shen et al. 2022 for more information.

ARM VARANAL case (SGP)

The ARM VARANAL setup drives a single column at the SGP Central Facility with time-varying profiles and tendencies from the ARM Variational Analysis product (sgp60varanarucC1.c1). Forcing includes horizontal advection, large-scale subsidence (from omega), nudging toward observed temperatures, humidities, and winds, prescribed surface latent and sensible heat fluxes, and time-varying skin temperature. Monthly files are available from the ARM Data Center. Run the configuration file config/model_configs/prognostic_edmfx_armvaranal_column.yml.

Key config entries (edit external_forcing_file, start_date, and t_end to pick a sub-period within the monthly file):

initial_condition: "ARMVARANAL"
external_forcing_file: artifact"arm_sgp_varanal_forcing"/sgp60varanarucC1.c1.20100901.000000.cdf
start_date: "20100918"
t_end: "4days"

The VARANAL file is converted to the ClimaColumn schema and run through the generic ForcingFromFile path (see Column Datasets); the forcing, prescribed surface fluxes, and insolation come from the setup, so external_forcing is left unset.

The default period (Sep 18–22, 2010) spans a clear-to-convective transition with a cold-front passage, a good diurnal-cycle test. To run another period, set external_forcing_file to that month's VARANAL .cdf file.

Reanalysis-driven case

Matched ERA5 trajectory

The ReanalysisTimeVarying case extends the GCM driven case to single-column simulations that resolve the diurnal cycle, can be run at any site on the globe, and are driven by reanalysis. That makes it possible to calibrate PROPHET against Earth system observations in the single-column setting. A set of configuration arguments can be:

initial_condition: "ReanalysisTimeVarying"
start_date: "20070701"
site_latitude: 17.0
site_longitude: -149.0

The case runs the configuration file config/model_configs/prognostic_edmfx_tv_era5driven_column.yml. The ReanalysisTimeVarying initial condition generates a column forcing file for the requested site and dates (regridded from the global ERA5 archive, stored through ClimaArtifacts for reproducibility) and hands it to the generic ForcingFromFile setup, which takes the initial condition, external forcing, surface skin temperature, and insolation from that one file (surface fluxes are computed interactively by Monin–Obukhov similarity theory). You give the site and dates directly rather than a file path because the file is generated on demand: start_date is YYYYMMDD, site_latitude in degrees (-90...90), and site_longitude in (-180...180). Artifact-backed ERA5 data is currently available only for the tropical Pacific in the first 5 days of July 2007, and only on the clima and Caltech HPC servers.

Note

Depending on the amount of smoothing and the data resolution, points near the boundaries can throw index errors. With default settings, stay at least 5 points away from the poles (1° for ERA5 data): 4 points for smoothing and one more for gradients.

Monthly averaged forcing

Following a matched ERA5 trajectory is data intensive, since it needs a download for each simulated day. A second dispatch avoids that by cycling a single day of forcing indefinitely.

The day it cycles is not a calendar day. ERA5 is averaged over the month separately at each hour of the day, which gives one composite day carrying that month's mean diurnal cycle; the file stores that day, and a periodic calendar repeats it for as long as the simulation runs. Forcing the column with it therefore drives the month's mean conditions and mean diurnal cycle without following any particular day's weather, which makes it suited to calibrating against monthly statistics.

The configuration is as above, with external_forcing set to request the composite day:

initial_condition: "ReanalysisTimeVarying"
external_forcing: "ReanalysisMonthlyAveragedDiurnal"
start_date: "20070701"
site_latitude: 17.0
site_longitude: -149.0

The corresponding configuration file is config/model_configs/prognostic_edmfx_diurnal_scm_imp.yml.

Running the reanalysis-driven cases at other times and locations requires downloading and naming the raw ERA5 files for the processing script; see Generating ERA5 forcing data in the Developer Guide.

Column forcing datasets

To drive a case from a custom forcing file, see the Column Datasets reference page. To define nonstandard forcing in a runscript, generate ERA5 forcing files, or write your own datasets, see Adding a Column Dataset in the Developer Guide.