In CESM, there are several different $CASEROOT xml files. These include env_case.xml, env_mach_pes.xml, env_build.xml, and env_run.xml. These files are organized so variables can be locked during different phases of the case setup, build, and run. Locking variables is a feature of CESM that prevents users from changing variables after they have been resolved (used) in other parts of the scripts system. The variables in env_case are locked when create_newcase is called. The env_mach_pes variables are locked when cesm_setup is called. The env_build variables are locked when CESM is built, and the env_run variables are never locked and can be changed anytime. In addition, the Macros file is locked as part of the build step. The $CASEROOT/LockedFiles directory saves copies of the xml files to facilitate the locking feature. In summary:

  • env_case.xml is locked upon invoking create_newcase and cannot be unlocked. To change settings in env_case, a new case has to be generated with create_newcase.

  • env_mach_pes.xml are locked after running cesm_setup. After changing variable values in this file, you need to invoked cesm_setup -clean and then cesm_setup.

  • Macros and env_build.xml are locked upon the successful completion of $CASE.build. Both Macros and env_build.xml can be unlocked by invoking $CASE.cleanbuild and then the model should be rebuilt.