Skip to content

Simpler Models User's Guide

Jump to bottom
Peter Hjort Lauritzen edited this page Sep 22, 2026 · 3 revisions
image

Running FKESSLER (and other simpler-model tests) with CAM-SIMA

This page describes how to check out CAM-SIMA and run the FKESSLER test case — the moist baroclinic wave of Ullrich et al. (2014) with Kessler (1969) warm-rain microphysics, from the DCMIP-2016 test suite — with both the SE-CSLAM and MPAS dynamical cores. It also summarizes the main differences a user will notice compared to running the same case with CAM (cam_development branch of ESCOMP/CAM), which is documented on the CESM simpler models FKESSLER page.

Full developer documentation: https://escomp.github.io/CAM-SIMA-docs/

1. Checking out the code

git clone https://github.com/ESCOMP/CAM-SIMA.git
cd CAM-SIMA
git checkout development
./bin/git-fleximod update

bin/git-fleximod update populates the external components (CIME, CCPP framework, atmospheric_physics, MPAS, share code, etc.). Run it again whenever you switch branches/tags.

2. FKESSLER at ~1° with the SE/CSLAM dycore (ne30pg3)

From the CAM-SIMA checkout, on Derecho:

cd cime/scripts

./create_newcase \
  --case /glade/derecho/scratch/$USER/fkessler_ne30pg3 \
  --compset FKESSLER \
  --res ne30pg3_ne30pg3_mg17 \
  --project <PROJECT_KEY> \
  --run-unsupported

cd /glade/derecho/scratch/$USER/fkessler_ne30pg3
./case.setup

# baroclinic wave develops over ~12 days; turn off short-term archiving
./xmlchange STOP_OPTION=ndays,STOP_N=12,DOUT_S=FALSE
# default wallclock time is 12h. Change to 30m
./xmlchange JOB_WALLCLOCK_TIME=00:30:00

./case.build
./case.submit

Notes:

  • FKESSLER is the alias for 2000_CAM%KESSLER_SLND_SICE_SOCN_SROF_SGLC_SWAV (all surface components are stubs). It automatically sets CAM_CONFIG_OPTS = "--physics-suites kessler --analytic-ic" — check with ./xmlquery CAM_CONFIG_OPTS.
  • The dycore is selected from the resolution string: ne* grids give the SE dycore (ne30pg3 = ne30 dynamics with CSLAM tracer transport and physics on the 3×3 finite-volume physics grid); mpasa* grids give the MPAS dycore.
  • Because the case uses analytic initial conditions, no resolution-specific initial-data file is needed: the default ncdata is a horizontal-grid-independent vertical-coordinate file (e.g. atm/cam/inic/cam_vcoords_L30_c180105.nc for the default 30 levels), and the baroclinic-wave state is generated on the fly. Any SE resolution (ne5, ne16, ne30pg3, ne120pg3, …) works without providing new input data.
  • --compiler is optional on derecho (intel default; gnu and nvhpc also available).

History output

CAM-SIMA history is configured entirely at runtime in user_nl_cam (syntax differs from CAM's fincl/nhtfrq — see history docs). For 6-hourly instantaneous output of the baroclinic-wave fields:

hist_add_inst_fields;h1: T, Q, U, V, PS
hist_output_frequency;h1: 6*nhours
hist_max_frames;h1: 100
hist_write_nstep0;h1: .true.

3. FKESSLER at 120 km with the MPAS dycore (mpasa120)

Identical workflow — only the resolution changes:

cd cime/scripts

./create_newcase \
  --case /glade/derecho/scratch/$USER/fkessler_mpasa120 \
  --compset FKESSLER \
  --res mpasa120_mpasa120 \
  --project <PROJECT_KEY> \
  --run-unsupported
cd /glade/derecho/scratch/$USER/fkessler_mpasa120
./case.setup
./xmlchange STOP_OPTION=ndays,STOP_N=12,DOUT_S=FALSE
./case.build
./case.submit

Notes:

  • The mpasa120 grid selects the MPAS dycore automatically, and the MPAS library is added to the link line automatically (CAM_LINKED_LIBS = -lmpas) — no manual configuration needed.
  • With analytic initial conditions the default ncdata is a coordinate-only file (atm/cam/inic/mpas/mpasa120_L32_notopo_coords_c240507.nc) that supplies the MPAS mesh; the model state is generated analytically. Default is 32 levels for MPAS analytic-IC runs.
  • Coordinate files are available out of the box for mpasa480, mpasa120, mpasa60 and mpasa30, so the same executable/setup runs from 480 km to 30 km by changing only --res.
  • Lower-resolution smoke tests use --res mpasa480_mpasa480 (this is what CAM-SIMA regression testing runs for FKESSLER on MPAS).

Changing the number of vertical levels — no recompile

The number of levels is a namelist variable in CAM-SIMA. In user_nl_cam:

pver = 58

This automatically switches ncdata to the matching vertical-coordinate file (L26/L32/L58/L93 files exist for MPAS; L30/L32 for the grid-independent SE vcoord files). In CAM this required configure --nlev and a full rebuild.

4. Other simpler-model compsets in CAM-SIMA

All follow the same recipe — only --compset changes:

Alias Physics (CCPP suite) CAM_CONFIG_OPTS default
FADIAB adiabatic (no physics) --physics-suites adiabatic
FHS94 Held & Suarez (1994) forcing --physics-suites held_suarez_1994 --analytic-ic
FTJ16 Thatcher & Jablonowski (2016) moist idealized physics --physics-suites tj2016 --analytic-ic
FKESSLER Kessler warm-rain microphysics --physics-suites kessler --analytic-ic
FPHYStest physics testbed (no dycore; driven by snapshot files) --dyn none --physics-suites adiabatic
QPC4 CAM4 aquaplanet --physics-suites cam4

The full list is in $CAM-SIMA/cime_config/config_compsets.xml; grid aliases are in ccs_config/modelgrid_aliases_nuopc.xml. Regression-test configurations (compset/grid/testmods combinations known to work) are in cime_config/testdefs/testlist_cam.xml.

5. What is different from CAM (cam_development)?

The CIME workflow (create_newcase → case.setup → case.build → case.submit) is unchanged, and the same FKESSLER compset exists in both models (CAM version documented for CESM2). The differences are in how much is decided at compile time versus at runtime:

CAM (cam_development) CAM-SIMA
Horizontal resolution Grid information enters the build via configure; changing resolution means reconfiguring and recompiling Executable contains no grid information; resolution is set at runtime (namelist + input files). The same build runs mpasa480 … mpasa30, or any SE resolution
Vertical levels Compile-time (configure --nlev) Runtime namelist variable pver in user_nl_cam
Number of tracers / constituents Compile-time parameter (PCNST); adding tracers or changing the chemistry mechanism forces a rebuild Constituents are registered at runtime through the CCPP constituents object; schemes can even declare constituents dynamically during the register phase (e.g. MICM chemistry reads its species list from a configuration file at initialization). No rebuild needed
Physics selection One physics configuration per build (-phys, -chem, -microphys, …) One or more CCPP suites compiled in (--physics-suites kessler;tj2016); if more than one is built, the active suite is chosen at runtime via the physics_suite namelist variable
Configuration machinery configure + perl build-namelist with many build options Small python ConfigCAM (essentially just --physics-suites, --dyn, --analytic-ic, --dyn-kind, --phys-kind); namelist-reading Fortran is auto-generated from XML, and each scheme carries its own namelist, combined into atm_in
History/output fincl1..10, nhtfrq, mfilt, avgflag_pertape Runtime hist_config block per file: hist_add_inst_fields;h1: …, hist_output_frequency;h1: 6*nhours, hist_max_frames, hist_precision, etc.
Initial-data checking Missing fields on ncdata handled ad hoc by each parameterization Before running, the CCPP framework queries the suite for all required input fields; anything not initialized is read from ncdata, and genuinely missing fields produce a clear runtime error listing the field names
Offline physics testing SCAM / PORT Built-in null dycore (--dyn none, FPHYStest compset): runs the physics on any number of columns, driven by snapshot files, without gridded input
Precision Fixed --dyn-kind / --phys-kind select REAL32/REAL64 independently for dycore and physics

Practical upshot: with CAM-SIMA a single executable can be reused across horizontal resolutions, vertical grids, tracer configurations, and (if multiple suites are compiled) physics suites — the rebuild-per-configuration cycle familiar from CAM largely disappears, and what remains build-time is only the choice of dycore and the set of compiled CCPP suites.

References

Clone this wiki locally