How component configurations work

The E3SM Atmosphere Model and E3SM Land Model have a complex system for configuring its compile- and runtime-options that was inherited from CESM

When creating a case with CIME, a compset alias is expanded to a compset longname and the 2nd element in that longname specifies the atmosphere configuration.

This example will use an F-case with CAM.

Example: ./create_newcase --case Fcaseex --compset FC5AV1C --res ne30_ne30

FC5AV1C becomes 2000_CAM5%AV1C_CLM45%SPBC_CICE%PRES_DOCN%DOM_SROF_SGLC_SWAV

The translation between alias and longname for F-cases is in cam/cime_config/config_compsets.xml https://github.com/E3SM-Project/E3SM/blob/master/components/cam/cime_config/config_compsets.xml

The entire longname is use to find more options to define both how CAM is built and what goes in to its namelist. These settings are in cam/cime_config/config_components.xml https://github.com/E3SM-Project/E3SM/blob/master/components/cam/cime_config/config_component.xml and CIME searches that file to find the settings for the case the user is trying to set up.

First search: configure options.

The first search is for one or more setting in CAM_CONFIG_OPTS, an xml block inside config_components.xml This defines the string that is passed to the CAM “configure” command (a perl script located in components/cam/bld/configure).

The atmosphere part of the compset will match this setting.

<value compset="_CAM5%AV1C" >-clubb_sgs -microphys mg2 -chem linoz_mam4_resus_mom -rain_evap_to_coarse_aero -nlev 72</value>

But there are other lines in CAM_CONFIG_OPTS that match the compset strings.

The addition of “phys cam5” comes from this line:

<value compset="_CAM5" >-phys cam5</value>

The addition of “-bc_dep_to_snow_updates” comes from this part of the compset: CLM45%SPBC and this line in the CAM config_components.xml:

<value compset="CLM45%[^]*BC" >-bc_dep_to_snow_updates</value>

Yes you can set atmosphere config options based on land model configs.

In a BGC coupled case, there is an additional item on the end of most compset long names like this:

SSP585_CAM5%CMIP6_CLM45%CNPECACNTBC_MPASSI%BGC_MPASO%OIECOOIDMS_MOSART_SGLC_SWAV_BGC%BDRC

The combination of “CAM5” and “BGC%BDRC” will cause this line to match:

<value compset="_CAM.*_BGC%B" >-co2_cycle</value>

and so “-co2_cycle” will be added to the configure string.

The actual call to configure for this example:

/qfs/people/jaco316/E3SM/components/cam/bld/configure -s -ccsm_seq -ice none -ocn docn -caseroot /qfs/people/jaco316/E3SM/cime/scripts/FLbase -comp_intf mct -spmd -spmd -smp -nosmp -dyn se -dyn_target preqx -res ne30np4 -phys cam5 -clubb_sgs -microphys mg2 -chem linoz_mam4_resus_mom -rain_evap_to_coarse_aero -nlev 72 -bc_dep_to_snow_updates

“-phys cam5” is first because it is also earlier in the CAM_CONFIG_OPTS block.

“configure” is called by the eam/cime_config/buildnml script.

Multiple matches will ADD up to the final configure line because of this line in the CAM_CONFIG_OPTS block

The other options in the configure command (“-spmd -spmd”, “-dyn se”) come from logic in the python buildnml script in cam/cime_config which calls the configure script.

The basic configure options are recorded in the casedir in env_build.xml.

<entry id="CAM_CONFIG_OPTS" value="-phys cam5 -clubb_sgs -microphys mg2 -chem linoz_mam4_resus_mom -rain_evap_to_coarse_aero -nlev 72 -bc_dep_to_snow_updates">

You can see this with “./xmlquery CAM_CONFIG_OPTS”

CAM used to require more compile-time settings. The compile-time settings then determined what was possible to set at run-time in a namelist. A lot of the logic in this system is to make sure the initial namelist blocks match the configured options. (its still possible to add a variable to user_nl_cam that has no effect).

CAM Is now a lot more run-time configurable. The only compile-time settings that still matter are dycore and number of vertical levels. ( ? )

But the smallest buildable unit in CAM is a directory of code. So another part of what the CAM “configure” does is determine which subdirectories of code are compiled. E.g. if you are using the SE dycore, nothing in cam/src/dynamics/eul will be compiled.

NOTE: although the script is called “configure” it has nothing to do with the Autoconf command of the same name.

Second search: namelist options

config_components.xml is consulted again to find the settings for CAM_NML_USE_CASE, another xml block. For this case, the matching setting is:

<value compset="2000_CAM5.*AV1C" >2000_cam5_av1c</value>

The use case value is the name for an xml file in components/cam/bld/namelist_files/use_cases.

In this example it is this file: https://github.com/E3SM-Project/E3SM/blob/master/components/cam/bld/namelist_files/use_cases/2000_cam5_av1c.xml

That file is passed as an argument to the build-namelist call as shown below:

/qfs/people/jaco316/E3SM/components/cam/bld/build-namelist -infile /qfs/people/jaco316/E3SM/cime/scripts/FLbase/Buildconf/camconf/cesm_namelist -csmdata /compyfs/inputdata -ignore_ic_year -use_case 2000_cam5_av1c -inputdata /qfs/people/jaco316/E3SM/cime/scripts/FLbase/Buildconf/cam.input_data_list -ntasks 900 -namelist " &atmexp /

And this call creates the atm_in file read in by the model at runtime.

“build-namelist” is also called by buildnml in eam/cime_config AFTER the call to “configure”.

The use case file is recorded in the casedir in env_run.xml

<entry id="CAM_NML_USE_CASE" value="2000_cam5_av1c">

you can see this with “./xmlquery CAM_NML_USE_CASE”

Unlike CAM_CONFIG_OPTS, there can only be one correct match.

Third search: description

config_components.xml is searched in the description xml block for a text string describing this component setting. In this case it will match:

<desc compset="_CAM5.*AV1C" >CAM with complete set of E3SM atmospheric mods for V1 (72 layers model):</desc>

It will ALSO match this line

<desc compset="_CAM5" >cam5 physics:</desc>

This string is used in output to the screen during case configuration. You can also see it in the README.case file in the casedir:

2020-06-26 19:51:07: Component ATM is cam5 physics:CAM with complete set of E3SM atmospheric mods for V1 (72 layers model):

This string is also additive. Multiple matches to the longname will keep appending to the description.

It does not appear to be saved in a casedir xml file.