CUG 6.5 BASICS What are CIME xml variables and CIME environment variables

Like in CESM1.0 and CESM1.1, CESM1.2 cases are customized, built and run largely through setting what CESM calls "environment variables". These actually appear to the user as variables defined in xml files. Those files appear in the case directory once a case is created and are named something like env_*.xml. They are converted to actual environment variables via a csh script called ccsm_getenv. That script calls a perl script called xml2env that converts the xml files to shell files that are then sourced and removed. The ccsm_getenv and xml2env exist in the $CASEROOT/Tools directory. The environment variables are specified in xml files to support extra automated error checking and automatic generation of env variable documentation. If you want to have the cesm environment variables in your local shell environment, do the following

> cd $CASEROOT
> source ./Tools/ccsm_getenv

You must run the ccsm_getenv from the CASEROOT directory exactly as shown above. There are multiple env_*.xml files including env_case.xml, env_mach_pes.xml, env_build.xml, and env_run.xml. To a large degree, the different env files exist so variables can be locked in different phases of the case setup, build, and run process. For more info on locking files, see the Section called BASICS: Why is there file locking and how does it work?. The important point is that env_case.xml variables cannot be changed after create_newcase is invoked. env_mach_pes cannot be changed after cesm_setup is invoked unless you plan to invoke the commands cesm_setup -clean, and cesm_setup again. env_build variables cannot be changed after the model is built unless you plan to clean and rebuild. env_run.xml variables can be changed at any time. The CESM scripting software checks that xml files are not changed when they shouldn't be.

CESM recommends using the xmlchange tool to modify env variables. This will decrease the chance that typographical errors will creep into the xml files. Conversion of the xml files to environment variables can fail silently with certain xml format errors. To use xmlchange, do, for instance,

> cd $CASEROOT
> ./xmlchange STOP_OPTION=nmonths
> ./xmlchange STOP_N=6

which will change the variables STOP_OPTION and STOP_N in the file env_run.xml to the specified values. The xml files can be edited manually, but users should take care not to introduce any formatting errors that could lead to incomplete env settings. If there appear to be problems with the env variables (i.e. if the model doesn't seem to have consistent values compared to what's set in the xml files), then confirm that the env variables are being set properly. There are a couple of ways to do that. First, run the ccsm_getenv script as indicated above and review the output generated by the command "env|sort". The env variables should match the xml settings. Another option is to edit the $CASEROOT/Tools/ccsm_getenv script and comment out the line "rm $i:r". That should leave the shell env files around, and they can then be reviewed. The latter approach should be undone as soon as possible to avoid problems running ccsm_getenv later.