CESM1 cases are configured largely through setting what CESM1 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 ccsm 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_conf.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 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_conf and env_mach_pes cannot be changed after configure is invoked unless you plan to reconfigure the case. env_build variables cannot be changed after the model is built unless you plan to clean and rebuild. env_run variables can be changed anytime. The CESM1 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 -file env_run.xml -id STOP_OPTION -val nmonths > ./xmlchange -file env_run.xml -id STOP_N -val 6 |
which will change the variables STOP_OPTION and STOP_N in the file env_run.xml to the specified values. The "-warn" option to xmlchange also makes sure you aren't overwriting a current value in a field. And the "-append" option to xmlchange keeps the current value in a field and just appends a new value on the end. It can be useful to know the value was merely appended and the previous value wasn't inadvertently changed as well. 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". 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.