EXPERTS: How do I create my own component set?

Numerous component sets (i.e. compsetes) are provided "out-of-the-box" with CESM1.1 release. You can also call create_newcase giving it the -compset_file argument to point to your own customized component set. In CESM1.1, the component set definition file, $CCSMROOT/scripts/ccsm_utils/Case.template/config_compsets.xml has been redefined to be hierarchical. The following documents the rules involved for generating a compset from the hierarchy.


 ===============================================================
 REQUIREMENTS
 ===============================================================
    - The NAME of the compset must appear in config_compsets.xml.

 ===============================================================
 ATTRIBUTE DESCRIPTIONS: 
 ===============================================================

 BEG_COMPSET_MATCH 
    - Matching rule for the beginning of a component set

    - The entire file is scanned in order (by create_newcase) and 
      all BEG_COMPSET_MATCH matches are evaluated.

    - Assume there are two matches - e.g. B_ and B_2000, with B_ appearing first.
      Any identical attribute values in B_2000 will overwrite the values in B_
      As a general rule, there should not be repeated attribute values in 
      BEG_COMPSET_MATCH  matches that overwrite each other.

 GEN_COMPSET_MATCH
    - General matching rules that can appear anywhere in the compset

    - The entire file is scanned in order and all GEN_COMPSET_MATCH matches 
      are evaluated.

    - Attributes containing _CONFIG_OPTS and _NAMELIST_OPTS are 
      contained in GEN_COMPSET_MATCH.
      - These attributes are additive.
      - New values are added to the end of the string UNLESS there is already 
        a match.
      - As an example:
           If initially CAM_CONFIG_OPTS is "-phys cam4 -chem none" 
           and a new value of CAM_CONFIG_OPTS is matched that 
           has CAM_CONFIG_OPTS set to "-phys cam5" 
           then the final CAM_CONFIG_OPTS  will be "-phys cam5 -chem none"

    - GEN_COMPSET_MATCH is used to set default options for that compset. 
           This includes values like the cam physics, etc.    
           This includes valid component set resolutions (if there are limitations).

 SSTICE_COMPSET_MATCH && GRID_MATCH
    - Provide reference cases and reference dates for certain compsets/resolution 
      configuration matches
    
 RES_COMPSET_MATCH && GRID_MATCH
    - Provide reference cases and reference dates for certain compsets/resolution 
      configuration matches - must match compset longname exactly
    
 NAME
    - *** required currently ***
    - Provides exact match
    - Any attribute settings in the NAME attribute list will OVERRIDE any 
      other attribute setting that has been specified

 ===============================================================
 HIERARCHY
 ===============================================================
 
 Search hierarchy of search is the following

   1) BEG_COMPSET_MATCH                                 
   2) GEN_COMPSET_MATCH                                 
   3) RES_COMPSET_MATCH && GRID_MATCH                   
   4) NAME (exactly)                                    

 ===============================================================
 CONVENTIONS: 
 ===============================================================

   We ask that you try to follow these conventions to keep this file readable:

   Component Set  Naming Convention:

      Most compset names follow the convention:

      <ComponentSpec>_<TimeSelector>[_<OPT1>][_<OPT2>]

      ComponentSpec = [A,B,C,D,E,F,G,K,X] 
      TimeSelector  = [1850, 1850-2000, 2000, 
                       RCP2.6, RCP4.5, RCP6.0, RCP8.5, 
                       AMIP (F_), 1955-2005 (F_),
                       NORMAL_YEAR (C_,D_,G_), INTERANNUAL (C_,D_,G_), 
                       PRESENT_DAY]  
                      
      Notes: There are two exceptions to TimeSelector which should be changed: 
             _SD and and _TROP_STRAT_CHEM

   BEG_COMPSET_MATCH:

      In general in what follows, BEG_COMPSET_MATCH matches either the
      first token, <ComponentSpec>, or the first two tokens,
      <ComponentSpec>_<TimeSelector> (although it could just match a
      portion of the TimeSelector token, as is the case for the
      RCPs). 

      Furthermore, there is generally a BEG_COMPSET_MATCH for just
      <ComponentSpec>, optionally followed by BEG_COMPSET_MATCHes for
      the specific time periods for that ComponentSpec. For example, there
      are BEG_COMPSET_MATCHes for "B_", "B_2000" and "B_RCP".

      GEN_COMPSET_MATCH (see below) is used for everything else.  

   GEN_COMPSET_MATCH:

      In general, GEN_COMPSET_MATCH is used to match single option tokens
      that follow <TimeSelector> in the compset name (e.g., <OPT1> and <OPT2>
      in the compset naming convention given above)

To create a customized compset, you will need to generate a file that has the format similar to $CCSMROOT/scripts/sample_compset_file.xml. The simples thing to do is to issue the following command


> cd $CCSMROOT/scripts
> cp $CCSMROOT/scripts/ccsm_utils/Case.template/config_compsets.xml my_compset.xml

Edit the file, my_compset.xml, to create your own compset configuration. In particular, the NAME, SHORTNAME, DESC, and COMP_ variables must be specified. Other CESM env variables can optionally be added here. See scripts/ccsm_utils/Case.template/config_compsets.xml for other variables that might be related to compset configuration.

Next run create_newcase with the optional -compset_file argument. Assume below that the compset name that is given in the my_compset.xml file is MYCS.


> create_newcase -case mycase -res f19_g16 -compset MYCS -mach mymach -compset_file my_compset.xml

The case mycase should have been generated and the configuration should be consistent with settings from the my_compset.xml file.