How to create a new compset

Creating a new ACME compset is a relatively straightforward process in most cases. This page will walk you through the process so that you can create compsets for your model configurations as needed.

Why create a compset for your model configuration?

It makes it easier to provide your configuration to others: A compset creates an unambiguously defined incarnation of your configuration, any changes to which will be documented within the version control system (i.e. git repository).
It's more robust: Defining your configuration as a compset reduces the potential for user error, because fewer options (namelist settings, configuration options) are specified via runscript or command-line options.
Protect your configuration from getting broken: Allows automated testing (optionally including nightly regression testing) to be performed for your configuration.

Prerequisites and needed information

Before you begin, please check that you have met the following prerequisites:

Everything necessary to specify your configuration can be specified via a compile-time option or a namelist option. Also make sure that you know the values you will specify for these options.
All needed input files (initial conditions, boundary conditions, etc.) are present in the ACME svn repository (see /wiki/spaces/WORKFLOW/pages/7998629)

Locations of important files

ACME/cime/scripts/Tools/config_compsets.xml : most of the specification of the compset is done in this file.

ACME/components/cam/bld/build-namelist : This script builds that atm_in namelist. Its actions depend on the model configuration, so it may need to be edited when adding a new capability.

ACME/components/cam/bld/namelist files/namelist_defaults_cam.xml : Contains defaults for namelist variables depending on the model configuration, including resolution.

ACME/components/cam/bld/namelist files/namelist_definition.xml : Contains the definitions of namelist variables, including a description and allowable values.

ACME/components/cam/bld/namelist_files/use_cases/ : location of atmosphere model use-case definitions (a use-case is a specification of default name-list values for a particular compset or compsets). Analogous locations exist for the use-case files of other model components (land, ocean, etc.)

... <others> ...

How to add a compset, step-by-step

Identify a compset similar to your desired new compset, which will be your starting point for making changes.
Collect a list of all non-default namelist options, input files, and compile options that are needed to fully specify your configuration. These will include any changes relative to your baseline compset identified in the previous step.
1. Note: if your configuration requires a user-provided atmospheric chemistry mechanism, please run the stand-alone chemistry pre-processor and add the auto-generated code to the model first before adding a compset. The reason for doing this is that the chemistry pre-processor does not build smoothly on all systems, which will prevent your compset from running smoothly on many systems.
Create a feature branch to begin work on your new compset.
1. If you don't know how to do this, please refer to the Development Getting Started Guide.

Edit the file ACME/cime/scripts/Tools/config_compsets.xml

Note that only the final step below is needed for every new definition of a compset alias. The other steps may or may not be needed, depending on the particular modifications you are making.
Specify new set of compile-time options (CAM_CONFIG_OPTS) (optional):
1. If your configuration requires providing a new set of compile-time options to CAM (specified via CAM_CONFIG_OPTS), create a new CAM_CONFIG_OPTS specification for a regular expression matching your new compset (unless already exists for your configuration), e.g.:
  <CAM_CONFIG_OPTS compset="_CAM5%ATMMOD" >-clubb_sgs -microphys mg2 -chem linoz_mam4_resus_mom -rain_evap_to_coarse_aero</CAM_CONFIG_OPTS>
  Note that CAM_CONFIG_OPTS are additive, meaning that the options from all matched regular expressions will be used.
2. analogously set any needed configuration options for other model components
Specify new set of namelist options via use-case (optional):
1. If needed, create a new use-case namelist specifying all non-default namelist options for the atmosphere model. The use-case namelists reside in ACME/components/cam/bld/namelist_files/use_cases/ (and analogous locations for other model components). In most cases, it's probably easiest to start with an example similar to what you want, and modify it according to your needs.
2. Specify the name of the namelist in config_compsets.xml, e.g.: <CAM_NML_USE_CASE compset="2000_CAM5.*ATMMOD*">2000_cam5_atmmod</CAM_NML_USE_CASE>
3. analogously create and specify any needed use-cases options for other model components
Add a brief compset "description" matching any new regular expressions in your compset name (optional):
1. E.g.: <desc compset="_CAM5.*ATMMOD">CAM with all ACME atmosphere mods:</desc>

Create a definition of the compset's full name, short name and alias (required):

Follow an example in config_compsets.xml to configure the compset name, short name, and alias :
<COMPSET sname="F_2000_CAM5_ATMMOD" alias="FC5ATMMOD" >2000_CAM5%ATMMOD_CLM45%BC_CICE%PRES_DOCN%DOM_RTM_SGLC_SWAV</COMPSET>

Note that the complete compset definition is a long string specifying the version of each component used. The syntax is:

TIME_ATM[%phys]_LND[%phys]_ICE[%phys]_OCN[%phys]_ROF[%phys]_GLC[%phys]_WAV[%phys][_BGC%phys]

TIME = Time period (e.g. 2000, 20TR, RCP8...)
ATM  = [CAM4, CAM5, DATM, SATM, XATM]
LND  = [CLM40, CLM45, DLND, SLND, XLND]
ICE  = [CICE, DICE, SICE, SICE]
OCN  = [POP2, DOCN, SOCN, XOCN,AQUAP]
ROF  = [RTM, DROF, SROF, XROF]
GLC  = [CISM1, SGLC, XGLC]
WAV  = [SWAV, XWAV]
BGC  = optional BGC scenario

See the CESM 1.2 User's Guide for more details on adding new user-defined compsets.

A few quick pointers in interpreting compset names
1. DOCN, DATM, etc. : "data" version of component
2. SOCN, SATM, etc. : "stub" version of component
3. strings following "%" are modifications to the component name that specify a particular configuration of that component, especially a set of compile-time configuration options (XXX_CONFIG_OPTS)
4. ALL the possible %phys choices for each component can be listed with the -list command for create_newcase.

Add and commit your changes (see Development Getting Started Guide and Commit message template).
Test your new compset.
1. The simplest workflow to do this is (on an ACME supported machine):
  1. Ensure you are using at least python 2.7 (e.g., on some machines you may need to do "module load python")
  2. cd ACME/cime/scripts-acme
  3. ./create_test test_type_D.grid_name.compset_name
    1. test_type may be SMS (smoke test), ERS (exact restart from startup) or one of the other supported Test Types. A smoke test (SMS) is a good place to start; it runs a five-day initialization test. An ERS test runs a 6 day + 5 day simulation and compares with an 11-day simulation.
    2. _D is an optional modifier to build the model in "debug" mode
    3. grid_name may be, e.g., ne16_ne16 (low-resolution test with spectral element core for both atmosphere and model grid)
    4. compset_name is the name of your new compset
2. For more information on ACME testing tools, see Testing and Running the tests
Once you have confirmed that your new compset builds and runs successfully on at least one supported system, submit a Pull Request (PR) for your branch containing the new compset (see Development Getting Started Guide and Development Reference). Be sure to assign an integrator (see Integrator Guide for a list of ACME integrators) and add the "compset" label and any other applicable labels to your PR.

Links to more information

CESM documentation on "How to customize the configuration for a case with CLM"
Others?