Chapter 3. Configuring a Case

Table of Contents
Configure Overview
Customizing the configuration
Setting component-specific variables
Reconfiguring a Case
Summary of Files in the Case Directory

Configure Overview

Configure generates buildnml and buildexe scripts for each component in the Buildconf directory. It also generates build, run, l_archive, and clean_build scripts in the CASEROOT directory. These scripts generate namelist for components and build and run the CESM1 model.

configure (invoked with the -case option) uses variables in env xml files to generate a new Buildconf/ directory and several new files in $CASEROOT.

Note: Any user modifications to env_conf.xml and env_mach_pes.xml must be done before configure is invoked. In the simplest case, configure can be run without modifying either of these files and default settings will be then be used.

Before exploring the details of configure, it is important to understand the concept of locked env files. The env files are "locked" after the variables have been used by other parts of the system and cannot be changed. The scripts do this by "locking" a file and not permitting the user to modify that file. More information on locking files can be found in the Section called Why is there file locking and how does it work? in Chapter 11

The configure command must be run in the $CASEROOT directory and must be invoked with one of the following options:


configure [-help] [-case] \
          [-cleanmach] [-cleannamelist] [-cleanall] 

-case

sets up the case for build and run phases. It creates Buildconf/, $CASE.$MACH.run, $CASE.$MACH.build, $CASE.$MACH.clean_build, $CASE.$MACH.l_archive, directories and files in $CASEROOT.

-cleanmach

Moves all machine-related files to a date-stamped backup directory under MachinesHist/. These files include: Macros.$MACH, $CASE.$MACH.build, $CASE.$MACH.clean_build, $CASE.$MACH.l_archive, and $CASE.$MACH.run. It also unlocks env_mach_pes.xml, Macros.$MACH, and env_build.xml, so users can reset machine tasks and threads and rerun configure. Reconfiguring with -cleanmach results in the loss of any local modifications to the local build and run scripts. But the Buildconf/ directory will not be updated in this process. As a result, local changes to namelists will be preserved.

If you only modify env_mach_pes.xml after running configure, do the following:


> configure -cleanmach
> # Make changes to env_mach_pes.xml
> configure -case
-cleannamelist

Moves Buildconf/ to a date-stamped backup directory under MachinesHist/ and unlocks env_conf.xml. Reconfiguring with -cleannamelist results in the loss of any local modifications to the Buildconf buildnml and buildexe files. But the local build and run scripts will be preserved.

If you only want to modify env_conf.xml after running configure, do the following:


> configure -cleannamelist
> # Make changes to env_conf.xml here
> configure -case
-cleanall

This performs the functions of both the -cleanmach and -cleannamelist options. All files associated with the previous invocation of configure are moved to a time-stamped directory in MachinesHist. The $CASEROOT directory will now appear as if create_newcase had just been run with the exception that local modifications to the env_*.xml files are preserved. After further modifications are made to env_conf.xml and env_mach_pes.xml, you must run configure -case before you can build and run the model. Reconfiguring results in the loss of all local modifications to the component buildnml or buildexe files in Buildconf as well as the loss of all local modifications to the local build and run scripts.

-help

Lists all options with short descriptions.

Configure generates buildnml and buildexe scripts for each component in the Buildconf directory. It also generates build, run, l_archive, and clean_build scripts in the CASEROOT directory. These scripts are now sufficient to build and run the model.

Table 3-1. Result of invoking configure

File or DirectoryDescription
Buildconf/Contains scripts that generate component libraries and utility libraries (e.g., PIO, MCT) and scripts that generate component namelists.
$CASE.$MACH.build Creates the component and utility libraries and model executable (see building CESM).
$CASE.$MACH.runRuns the CESM model and performs short-term archiving of output data (see running CESM). Contains the necessary batch directives to run the model on the required machine for the requested PE layout.
$CASE.$MACH.l_archivePerforms long-term archiving of output data (see long-term archiving). This script will only be created if long-term archiving is available on the target machine.
$CASE.$MACH.clean_build Removes all object files and libraries and unlocks Macros.$MACH and env_build.xml. This step is required before a clean build of the system.
env_derivedContains environmental variables derived from other settings. Should not be modified by the user.