COMPSETS_SPEC_FILE

Overview

A compset is defined by multiple components, that are targeted to their model development needs.

Each component supports a set of compset longnames that are used in testing and supported in out of the box configurations.

To determined valid compset names CIME will look in config_files.xml for COMPSETS_SPEC_FILE in order to determine which components are defined by the compset.

Entry

The following is an example for COMPSETS_SPEC_FILE in config_files.xml. Each value corresponds to the compsets provided by each component.

<entry id="COMPSETS_SPEC_FILE">
  <type>char</type>
  <default_value>unset</default_value>
  <values>
    <value component="allactive">$SRCROOT/cime_config/allactive/config_compsets.xml</value>
    <value component="drv"      >$COMP_ROOT_DIR_CPL/cime_config/config_compsets.xml</value>
    <value component="eam"      >$COMP_ROOT_DIR_ATM/cime_config/config_compsets.xml</value>
    <value component="scream"   >$COMP_ROOT_DIR_ATM/cime_config/config_compsets.xml</value>
    <value component="elm"      >$COMP_ROOT_DIR_LND/cime_config/config_compsets.xml</value>
    <value component="cice"     >$COMP_ROOT_DIR_ICE/cime_config/config_compsets.xml</value>
    <value component="mpaso"    >$COMP_ROOT_DIR_OCN/cime_config/config_compsets.xml</value>
    <value component="mali"     >$COMP_ROOT_DIR_GLC/cime_config/config_compsets.xml</value>
    <value component="mpassi"   >$COMP_ROOT_DIR_ICE/cime_config/config_compsets.xml</value>
    <value component="mosart"   >$COMP_ROOT_DIR_ROF/cime_config/config_compsets.xml</value>
    <value component="ww3"      >$COMP_ROOT_DIR_WAV/cime_config/config_compsets.xml</value>
  </values>
  <group>case_last</group>
  <file>env_case.xml</file>
  <desc>file containing specification of all compsets for primary component (for documentation only - DO NOT EDIT)</desc>
  <schema>$CIMEROOT/CIME/data/config/xml_schemas/config_compsets.xsd</schema>
</entry>

Every file listed in COMPSETS_SPEC_FILE will be searched to compile possible compsets to call create_newcase with.

CIME will note which component’s config_compsets.xml had the matching compset name and that component will be treated as the primary component As an example, the primary component for a compset that has a prognostic atmosphere, land and cice (in prescribed mode) and a data ocean is the atmosphere component (for cesm this is CAM) because the compset is defined, using the above example, in $SRCROOT/components/cam/cime_config/config_compsets.xml In a compset where all components are prognostic, the primary component will be allactive.

Schema Definition

Element/Attribute	Description
help	Help text.
alias	Alias for the compset.
lname	Longname for the compset.
science_support	Whether the compset supports science.
entry	XML variable provided by compsets.
id	Name of the variable.
values	Values for the variable.
match	Method used to determine which value to use.
value	The value of the variable.
compset	Specific compset that the variable is set for.
grid	Specific grid that the variable is set for.

<!-- Generated with doc/generate_xmlschema.py CIME/data/config/xml_schemas/config_compsets.xsd compsets on 2025-02-06 -->

<!-- Attributes 'version' is required-->
<!-- Occurences min: 1 max: 1-->
<compsets version="">
    <!-- Occurences min: 1 max: 1-->
    <help></help>
    <!-- Occurences min: 1 max: Unlimited-->
    <compset>
        <!-- Occurences min: 1 max: 1-->
        <alias></alias>
        <!-- Occurences min: 1 max: 1-->
        <lname></lname>
        <!-- Attributes 'None' is None-->
        <!-- Occurences min: 0 max: Unlimited-->
        <science_support None="">
        </science_support>
    </compset>
    <!-- Occurences min: 0 max: 1-->
    <entries>
        <!-- Attributes 'id' is required-->
        <!-- Occurences min: 1 max: Unlimited-->
        <entry id="">
            <!-- Attributes 'match' is optional-->
            <!-- Occurences min: 1 max: 1-->
            <values match="">
                <!-- Attributes 'compset' is optional,'grid' is optional-->
                <!-- Occurences min: 1 max: Unlimited-->
                <value compset="" grid=""></value>
            </values>
        </entry>
    </entries>
</compsets>

Compset longname

Each config_compsets.xml file has a list of allowed component sets in the form of a longname and an alias.

A compset longname has this form:

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

Supported values for each element of the longname:

TIME = model time period (e.g. 1850, 2000, 20TR, SSP585...)

CIME supports the following values for ATM,LND,ICE,OCN,ROF,GLC,WAV and ESP.
ATM  = [DATM, SATM, XATM]
LND  = [DLND, SLND, XLND]
ICE  = [DICE, SICE, SICE]
OCN  = [DOCN, SOCN, XOCN]
ROF  = [DROF, SROF, XROF]
GLC  = [SGLC, XGLC]
WAV  = [SWAV, XWAV]
ESP  = [SESP]

A CIME-driven model may have other options available. Use query_config to determine the available options.

The OPTIONAL %phys attributes specify sub-modes of the given system. For example, DOCN%DOM is the DOCN data ocean (rather than slab-ocean) mode. All the possible %phys choices for each component are listed by calling query_config –compsets. All data models have a %phys option that corresponds to the data model mode.

Creating New Compsets

A description of how CIME interprets a compset name is given in the section Compset longname .

To create a new compset, you will at a minimum have to:

1. edit the approprite config_components.xml file(s) to add your new requirements

2. edit associate namelist_definitions_xxx.xml in the associated cime_config directories. (e.g. if a change is made to the the config_components.xml for DOCN then namelist_definitions_docn.xml file will also need to be modified).

It is important to point out, that you will need expertise in the target component(s) you are trying to modify in order to add new compset functionality for that particular component. We provide a few examples below that outline this process for a few simple cases.

Say you want to add a new mode, FOO, to the data ocean model, DOCN. Lets call this mode, FOO. This would imply when parsing the compset longname, CIME would need to be able to recognize the string _DOCN%FOO_. To enable this, you will need to do the following:

Note

The $DOCNROOT is depenedent on the model.

1. Edit $DOCNROOT/cime_config/config_component.xml (see the FOO additions below). * add an entry to the <description modifier_mode="1"> block as shown below

   <description modifier_mode="1">
      <desc ocn="DOCN...[%FOO]">DOCN </desc>
      ...
      <desc option="FOO"> new  mode</desc>
      ....
   </description>
   

   • add an entry to the <entry id="DOCN_MODE"> block as shown below:

     <entry id="DOCN_MODE">
        ....
        <values match="last">
        ....
        <value compset="_DOCN%FOO_" >prescribed</value>
        ...
     </entry>
     

   • modify any of the other xml entries that need a new dependence on FOO

2. edit $DOCNROOT/cime_config/namelist_definition_docn.xml (see the FOO additions below).

   • add an entry to the datamode block as shown below.

     <entry id="datamode">
        ....
        <valid_values>...FOO</valid_values>
        ...
     </entry>
     

   • add additional changes to namelist_definition_docn.xml for the new mode

Todo

Add additional examples for creating a case