next up previous contents index
Next: 5 Building, Running and Up: UsersGuide Previous: 3 Obtaining code, scripts   Contents   Index

Subsections


4 Creating cases (preparing model runs)

CCSM3 cases refer to the way a user creates a particular CCSM model run. It refers to both the ``name'' of the model run (and the name associated with model run output data) as well as the directory name where the scripts for the model run will be generated.

In what follows and throughout this document, we will use the following naming and style convention:

4.1 Scripts usage overview

The CCSM3.0 scripts have been significantly upgraded from those in CCSM2. The new scripts are based on a very different design philosophy, making their use much easier for both novice as well as expert users. The new scripts operate by generating resolved scripts (see section 4.3) for a specific component set, resolution and CCSM3 initialization type. In addition, machine-specific build, run and archiving scripts are produced for each machine requested. The script generation process does not have to occur on the production machine and can occur on a front end machine if needed. Only the user-generated resolved build and run scripts have to be executed on the production machine. The README file in the ccsm3/scripts/ directory provides up-to-date information on how to use the CCSM3.0 scripts. Users should reference that file for additional information.

The following steps provide a summary of the steps necessary to create, build and run a model case using the CCSM3.0 scripts. These steps will be covered in detail in sections 4.2, 4.3, 4.4.1, 4.6, 4.7, 4.8 and 6.

  1. cd $CCSMROOT/ccsm3/scripts/
  2. invoke ./create_newcase -case $CASEROOT -mach $MACH (see section 4.2)
  3. cd $CASEROOT/
  4. optionally edit env_conf and tasks/threads portion of env_mach.$MACH
  5. invoke configure -mach $MACH
  6. optionally edit env_run and non-tasks/threads portion of env_mach.$MACH
  7. interactively run ./$CASE.$MACH.build (see section 4.4.1)
  8. submit $CASE.$MACH.run to the batch queue on $MACH (see section 4.4.1)

As shown above, the user must invoke the two commands, create_newcase and configure to generate a new model case. Invoking create_newcase (as shown below) results in the generation of a new $CASEROOT/ directory containing environment variable files and the script configure. Executing configure results in the creation of several $CASEROOT/ subdirectories containing scripts for namelist generation, input data prestaging, and creation of component executables and required CCSM3 libraries. $CASEROOT/ also contains scripts for building, running, and performing long- term data archiving on machine $MACH.


4.2 create_newcase

The script, create_newcase, is the starting point for the generation of a new CCSM3 case. The create_newcase script exists in the $CCSMROOT/ccsm3/scripts/ directory and must be run from this directory. Invoking create_newcase generates environment variable files and an accompanying configure script in a new user-specified case directory.

To obtain a concise usage summary type: 

      >  create_newcase

To obtain a detailed usage summary type: 

      >  create_newcase -help

To obtain a new case directory type: 

      >  create_newcase -case $CASEROOT -mach $MACH         
             [-res resolution]  [-compset <component set name>]
             [-ccsmroot <ccsm root directory>]

The -case and -mach arguments are required. If $CASEROOT does not contain a full pathname (e.g. it is simply set to $CASE), a new case directory ($CASEROOT/) will be generated in the $CCSMROOT/ccsm3/scripts/ directory. This is not recommended and the user is urged to set $CASEROOT to a full pathname. Although a target machine must be specified on the create_newcase command line, other machines can be added to $CASEROOT/ at a later time (see section 6.10). Typing 

      >  ./create_newcase -case /home/user/$CASE -mach $MACH

will result in the creation of a new directory /home/user/$CASE (i.e. $CASEROOT) which will in turn contain the following:

The files env_conf, env_run and env_mach.$MACH contain environment variables that define the CCSM run. The SourceMods/ subdirectory is an optional location for user-modified source code. Optional arguments to create_newcase are resolution (-res), component set name (-compset), and the CCSM3 root directory (-ccsmroot). Including the arguments -res and -compset will modify the default env_conf file that is generated. If no optional arguments provided to configure, the resolution will be set to T42_gx1v3 and the component set will be set to B in env_conf. As an example, running 

      >  ./create_newcase -case /user/case1 -mach bluesky -res T85_gx1v3 -compset K

will result in a new case directory, (/user/case1/) containing an env_conf file which will set up a CCSM run using component set K (cam, clm, dice and docn, cpl, see section 1.3.1) at T85_gx1v3 resolution (see section 1.3.2). The directory, (/user/case1/), will also contain an env_mach.bluesky file.


4.3 Resolved scripts

The concept of ``resolved'' scripts is new to CCSM3. A ``resolved'' namelist-prestaging script generates a component namelist and prestages component input data for a given CCSM resolution and a given way of starting up the CCSM run. Different initialization datasets are required for different types of CCSM initializations (see 5.4). Similarly, different initialization datasets are required for different CCSM resolutions. For instance, input datasets needed for a T42_gx1v3 run are different than those needed for a T31_gx3v5 run. Components comprising a startup T42_gx1v3 run will have different namelists from those comprising a branch T42_gx1v3 run. Components comprising a startup T31_gx1v5 run will have different namelists from those comprising a startup T42_gx1v3 run. Finally, component set B at T42_gx1v3 will have different namelists than component set A at T42_gx1v3.

4.4 configure

The script configure generates ``resolved'' CCSM3 scripts in the $CASEROOT/ directory. These will function to create component namelists, prestage the necessary component input data and build and run the CCSM model on a target machine. configure must be run from the $CASE directory.

The environment variables listed in env_conf determine what is ``resolved'' when configure is invoked and consequently what may not be modified once the resolved scripts exist. In particular, the contents of the scripts generated by configure (in Buildnml_prestage/ and Buildexe/) depend on the values of the environment variables in env_conf. In general, env_conf resolves model resolution, model component sets and model initialization type (e.g. startup, branch or hybrid). Consequently, env_conf must be modified before configure is run. Once configure is invoked env_conf may be modified only by running configure -cleannall (see below) first.

In addition, running configure for a given machine also generates batch queue commands for the given machine that depend on the task/thread settings in env_mach.$MACH. Consequently, if values other than the default values listed are desired, these should be changed before running configure. In this case, the following lines in env_mach.$MACH must be modified before running configure): 

      setenv NTASKS_ATM $ntasks_atm
      setenv NTHRDS_ATM $nthrds_atm
      setenv NTASKS_LND $ntasks_lnd
      setenv NTHRDS_LND $nthrds_lnd
      setenv NTASKS_ICE $ntasks_ice
      setenv NTHRDS_ICE $nthrds_ice
      setenv NTASKS_OCN $ntasks_ocn
      setenv NTHRDS_OCN $nthrds_ocn
      setenv NTASKS_CPL $ntasks_cpl
      setenv NTHRDS_CPL $nthrds_cpl

The usage for configure is as follows.

To obtain a concise summary of the usage type: 

      >  configure

To obtain extensive documentation of the usage type: 

      >  configure -help

To invoke the various configure options type: 

      >  configure [-mach $MACH] [-addmach $MACH] [-cleanmach $MACH] [-cleanall]

A full summary of each option is provided below.


4.4.1 configure -mach

Running configure -mach $MACH creates the following sub-directories and files in the $CASEROOT/ directory:

4.4.2 configure -cleanmach and configure -cleanall

The configure options -cleanmach and -cleanall provide the user with the ability to make changes to env_conf or env_mach.$MACH after configure -mach $MACH has been invoked. The configure script will stop with an error message if a user attempts to recreate scripts that already exist. The build and run scripts will also recognize changes in env_conf or env_mach.$MACH that require configure to be rerun. Note that the options -cleanall and -cleanmach are fundamentally different.

Running configure -cleanmach $MACH renames the build, run, and l_archive scripts for the particular machine and allows the user to reset the machine tasks and threads and rerun configure. It is important to note that the Build*/ directories will NOT be updated in this process. As a result, local changes to namelist, input data, or the environment variable files will be preserved.

Running configure -cleanall removes all files associated with all previous invocations of the configure script. The $CASEROOT/ directory will now appear as if create_newcase had just been run with the exception that local modifications to the env_* files are preserved. All Build*/ directories will be removed, however. As a result, any changes to the namelist generation scripts in Buildnml_prestage/ will NOT be preserved. Before invoking this command, users should make backup copies of their ``resolved'' component namelists in the Buildnml_Prestage/ directory if modifications to the generated scripts were made.

4.4.3 configure -addmach

The advantage of having scripts for more than one machine in one $CASEROOT/ directory is that the same ``resolved'' scripts in Buildnml_prestage/ and Buildexe/ can be used on multiple machines. Since long production runs are often performed on more than one machine during the course of a model run, this mechanism makes it very seamless to change machines during the course of a single model run.

Running configure -addmach $MACH allows the user to add new machines to an already generated $CASEROOT/ directory. For instance, if a $CASEROOT/ directory and accompanying scripts were created for bluesky, the following build and run scripts for bluesky would exist in the $CASEROOT/ directory:

Users can generate scripts for blackforest in the $CASEROOT/ directory as follows:

  1. cd $CASEROOT/
  2. ./configure -addmach blackforest (this adds env_mach.blackforest to $CASEROOT/)
  3. optionally edit env_mach.blackforest to change default values of tasks and/or threads
  4. ./configure -mach blackforest

The following additional scripts are then produced in the $CASEROOT/ directory:

4.5 Environment variables

The files env_conf, env_run and env_mach.$MACH contain environment variables needed to generate ``resolved'' scripts, build and run the CCSM model and perform short and long-term archiving on output data. The following table give a summary of the environment variables in each file. Those entries where ``User Modification'' is ``yes'' denote environment variables that the user might want to modify whereas those where ``User Modification'' is ``no'' are environment variable that are given reasonable default values and that in general the user might not want to change. A full discussion of each of these environment variables is given in sections 4.6, 4.7 and 4.8. The same summary can be found in $CASEROOT/env.readme.

Table 5: env_conf, env_run and env_mach.$MACH variables
File Environment Variable(s) User
    Modification
env_conf $CASE yes
env_conf $CASEST yes
env_conf $COMP_ATM, $COMP_LND, $COMP_ICE yes
  $COMP_OCN, $COMP_CPL  
env_conf $CSIM_MODE yes
env_conf $GRID yes
env_conf $RUN_TYPE yes
env_conf $RUN_STARTDATE yes
env_conf $RUN_REFCASE, $RUN_REFDATE yes
env_conf $IPCC_MODE yes
env_conf $RAMP_CO2_START_YMD yes
env_run $RESUBMIT yes
env_run $CCSMROOT yes
env_run $CASEROOT yes
env_run $CONTINUE_RUN yes
env_run $STOP_OPTION, $STOP_N yes
env_run $REST_OPTION no
env_run $REST_N no
env_run $INFO_DBUG no
env_run $DEBUG no
env_run $SETBLD no
env_run $OCN_TRACER_MODULES no
env_run $HIST_OPTION no
env_run $HIST_N no
env_run $HIST_64BIT no
env_run $AVHIST_OPTION no
env_run $AVHIST_N no
env_run $DIAG_OPTION no
env_run $DIAG_N no
env_run $LOGDIR no
env_mach.$MACH $NTASKS_ATM,$NTHRDS_ATM, yes
  $NTASKS_LND,$NTHRDS_LND,  
  $NTASKS_ICE,$NTHRDS_ICE,  
  $NTASKS_OCN,$NTHRDS_OCN,  
  $NTASKS_CPL,$NTHRDS_CPL  
env_mach.$MACH $MAX_TASKS_PER_NODE (IBM only) no
env_mach.$MACH $EXEROOT yes
env_mach.$MACH $RUNROOT no
env_mach.$MACH $GMAKE_J yes
env_mach.$MACH $DIN_LOC_ROOT, DIN_LOC_ROOT_USER, yes
  $DIN_LOC_MSROOT,  
  $DIN_REM_MACH, DIN_REM_MSROOT,  
  $DIN_REM_ROOT  
env_mach.$MACH $DOUT_S, DOUT_S_ROOT yes
env_mach.$MACH $DOUT_L_MS yes
  $DOUT_L_MSNAME, DOUT_L_MSROOT  
  $DOUT_L_MSPWD, DOUT_L_MSRPD,  
  $DOUT_L_MSPRJ  
  $DOUT_L_RCP, DOUT_L_RCP_ROOT  


4.6 Environment variables in env_conf


name
CASE
description
Case name (short identifier for run)
valid values
string of up to 80 characters


name
CASESTR
description
Descriptive Case String (identifier for run)
valid values
string of up to 256 characters


name
COMP_ATM
description
Atmospheric component name. Component build and namelist-prestage generation scripts will only be created for this specified component name
valid values
cam, datm, latm or xatm
Default setting is cam.


name
COMP_LND
description
Land component name. Component build and namelist-prestage generation scripts will only be created for this specified component name
valid values
clm, dlnd or xlnd
Default setting is clm


name
COMP_ICE
description
Ice component name. Component build and namelist-prestage generation scripts will only be created for this specified component name
valid values
csim, dice or xice
Default setting is csim


name
COMP_OCN
description
Ocean component name. Component build and namelist-prestage generation scripts will only be created for this specified component name
valid values
pop, docn or xocn
Default setting is pop


name
COMP_CPL
description
Coupler component name. Component build and namelist-prestage generation scripts will only be created for this specified component name
valid values
cpl


name
CSIM_MODE
description
CSIM model specification
valid values
prognostic or ocean_mixed_ice
A setting of prognostic implies that the complete CSIM ice model will be used.
A setting of ocean_mixed_ice implies that the slab ocean mixed layer within CSIM is utilized.
See the Community Sea Ice Model (CSIM) User's Guide Version 5.0 for more details. Default setting is prognostic


name
GRID
description
CCSM grid resolution
valid values
T85_gx1v3, T42_gx1v3, T31_gx3v5, 2x2.5_gx1v3,
T62_gx1v3 or T62_gx3v5
Default setting is T42_gx1v3


name
RUN_TYPE
description
Type of CCSM initialization
valid values
startup, branch or hybrid (see section 5.4)
Default setting is startup


name
RUN_STARTDATE
description
Start date of CCSM run. Only used for startup or hybrid runs. Ignored for branch runs (see section 5.4).
valid values
YYYY-MM-DD (e.g. 1990-01-01)



name
RUN_REFCASE
description
Reference case for branch or hybrid runs. Ignored for startup runs (see section 5.4).
valid values
string of up to 80 characters


name
RUN_REFDATE
description
Reference date for branch or hybrid runs. Ignored for startup runs (see section 5.4).
valid values
YYYY-MM-DD (e.g. 1990-01-01)


name
IPCC_MODE
description
Turns on various supported IPCC mode configurations
valid values
OFF, 1870_CONTROL, RAMP_CO2_ONLY
By default, $IPCC_MODE is set to OFF.


name
RAMP_CO2_START_YMD
description
Start date of CAM CO2 ramp
This MUST be set if IPCC_MODE is set to RAMP_CO2_ONLY.
This variable is ignored if $IPCC_MODE is not set to RAMP_CO2_ONLY.
valid values
YYYYMMDD


4.7 Environment variables in env_run


name
RESUBMIT
description
Flag to determine if the model should resubmit itself at the end of a run. If $RESUBMIT is 0, then the run script will not resubmit itself. If $RESUBMIT is greater than 0, then the case run script will resubmit itself, decrement $RESUBMIT by 1 and set the value of $CONTINUE_RUN to TRUE.
valid values
an integer greater than or equal to 0


name
CASEROOT
description
Root model case directory (full pathname containing where $CASE directory and also containing the files env_conf, env_run, etc.)


name
CCSMROOT
description
Root ccsm source directory (contains the directories models/, scripts/, etc.)


name
CONTINUE_RUN
description
Flag to specify whether run is a continuation run.
A continue run extends an existing CCSM run exactly, where "exactly" means that exact same answers at the bit-level are obtained as if the existing run had not been stopped. A run may be continued indefinitely from an existing run.
valid values
TRUE or FALSE


name
OCN_TRACER_MODULES
description
POP model passive tracer specification. Used only by POP scripts. Setting the passive tracer modules to ( ) results in only 2 tracers (the default in POP).
valid values
(iage), (cfc), (iage cfc), or ( )
Default setting is (iage)


name
DEBUG
description
Flag to turn on run and compile time debugging.
valid values
TRUE or FALSE
Default setting is FALSE


name
SETBLD
description
Flag to specify whether model will be built at runtime.
valid values
AUTO, TRUE or FALSE
Models use the $BLDTYPE environment variable, which is determined from the setting of $SETBLD, to determine if a build should be executed at run time. Each component build script checks this flag to determine if gmake is to be invoked.
If $SETBLD is TRUE, gmake will always be invoked on each component at run time.
If $SETBLD is FALSE, gmake will not be invoked on each component at run time.
If $SETBLD is AUTO, gmake will only be invoked on each component if $CONTINUE_RUN is FALSE.
Default setting is TRUE


name
STOP_OPTION
description
Coupler namelist variable that sets the ending simulation time.
If $STOP_OPTION is set to:
date - model stops on given date.
ndays - model stops every $STOP_N days relative to start date
nmonths - model stops every $STOP_N months relative to start date.
daily - model stops every day
monthly - model stops every 1st day of month
yearly - model stops every 1st day of year
valid values
date, ndays, nmonths, daily, monthly, or yearly
Default setting is ndays.


name
STOP_N
description
Coupler namelist variable that provides additional information with respect to $STOP_OPTION.
If $STOP_OPTION is set to:
ndays - $STOP_N is the number of days to run.
nmonths - $STOP_N is the number of months to run.
date - daily, monthly, or yearly, this option is ignored.
valid values
integer
Default setting 5


name
REST_OPTION
description
Coupler namelist variable that sets the frequency at which restart files are created.
If $REST_OPTION is set to:
ndays - restart files are generated every $REST_N days relative to start date
nmonths - restart files are generated every $REST_N months relative to start date
daily - restart files are generated every day
monthly - restart files are generated every first day of every month
yearly - restart files are generated every first day of every year
valid values
date, ndays, nmonths, daily, monthly, or yearly
Default setting is $STOP_OPTION.


name
REST_N
description
Coupler namelist variable that provides additional information with respect to $REST_OPTION.
If $REST_OPTION is set to:
ndays - restart files are generated every $REST_N days.
nmonths - restart files are generated every $REST_N months.
date - daily, monthly, or yearly, this option is ignored.
valid values
integer
Default setting is $STOP_N.


name
HIST_OPTION
description
Coupler namelist variable that sets the frequency that coupler history files are created. This does not apply to other model component history files.
If $HIST_OPTION is set to:
date - coupler history files are generated on given date
ndays - coupler history files are generated every $HIST_N days relative to start date
nmonths - coupler history files are generated every $HIST_N months relative to start date
daily - coupler history files are generated every day
monthly - coupler history files are generated every first day of every month
yearly - coupler history files are generated every first day of every year
never - coupler history files are never
valid values
date, ndays, nmonths, daily, monthly, yearly or never
Default setting is never.


name
HIST_N
description
Coupler namelist variable that provides additional information with respect to $HIST_OPTION.
If $HIST_OPTION is set to:
ndays - coupler history files are generated every $HIST_N days.
nmonths - coupler history files are generated every $HIST_N months.
date - daily, monthly, or yearly, this option is ignored.
valid values
integer
Default settings is -999.


name
HIST_DATE
description
Coupler namelist variable that provides additional information with respect to $HIST_OPTION.
If $HIST_OPTION is set to date, $HIST_DATE is the date at which to write a coupler history file.
If $HIST_OPTION is not set to date, this option is ignored.
valid values
integer


name
DIAG_OPTION
description
Coupler namelist variable that sets the frequency that coupler diagnostic files are created.
If $DIAG_OPTION is set to:
date - coupler diagnostic files are generated on given date.
ndays - coupler diagnostic files are generated every $DIAG_N days relative to start date
nmonths - coupler diagnostic files are generated every $DIAG_N months relative to start date
daily - coupler diagnostic files are generated every day
monthly - coupler diagnostic files are generated every first day of every month
yearly - coupler diagnostic files are generated every first day of every year never - coupler diagnostic files are never created
valid values
date, ndays, nmonths, daily, monthly, yearly or never
Default setting is never.


name
DIAG_N
description
Coupler namelist variable that provides additional information with respect to $DIAG_OPTION.
If $DIAG_OPTION is set to ndays, diagnostic files are generated every $DIAG_N days.
If $DIAG_OPTION is set to nmonths, diagnostic files are generated every $DIAG_N months.
If $DIAG_OPTION is set to date, daily, monthly, or yearly, this option is ignored.
valid values
integer
Default setting in script is -999.


name
INFO_DBUG
description
Coupler output information flag. Higher levels result in more information written to every component model's standard output file.
valid values
0,1,2 or 3
Default setting is 1


name
LOGDIR
description
Full pathname of directory where stdout and stderr should be copied. If $LOGDIR is set to "", then stdout and stderr will not be copied to a $LOGDIR/ directory before short-term archiving occurs.
valid values
full pathname or `` `` Default setting is `` ``


4.8 Environment variables in env_mach.$MACH

4.8.1 env_mach.$MACH tasks/threads


name
NTASKS_ATM, NTASKS_LND, NTASKS_OCN, NTASKS_ICE, NTASKS_CPL
description
Number of component MPI tasks for each component.
valid values
integer


name
NTHRDS_ATM, NTHRDS_LND, NTHRDS_OCN, NTHRDS_ICE, NTHRDS_CPL
description
Number of OpenMP threads per MPI task for each component.
valid values
integer


name
MAX_TASKS_PER_NODE
description
Maximum number of MPI tasks per node.
Currently, this is only applicable to IBM machines
valid values
integer

4.8.2 env_mach.$MACH general machine specific settings


name
EXEROOT
description
Root executable directory. Model executables are built here.


name
RUNROOT
description
Root executable run directory. Model executables are run here.


name
GMAKE_J
description
Number of threads invoked as part of gmake.
valid values
integer greater than 0.

4.8.3 env_mach.$MACH input data prestaging


name
DIN_LOC_ROOT
description
Local disk root directory for officially released CCSM input data.
Used by the script Tools/ccsm_getinput.


name
DIN_LOC_MSROOT
description
Local mass store root directory for officially released CCSM input data.
Used by the script Tools/ccsm_getinput.


name
DIN_LOC_ROOT_USER
description
Local disk root directory for user-specific CCSM input data.
Used by the script Tools/ccsm_getinput.


name
DIN_REM_MACH
description
Name of remote machine where officially released CCSM input data are located.


name
DIN_REM_ROOT
description
Remote machine disk root containing officially released CCSM input data.


name
DIN_REM_MSROOT
description
Remote machine mass store root containing officially released CCSM input data

4.8.4 env_mach.$MACH output data short-term archiving environment variables


name
DOUT_S
description
Flag to determine if short-term archiving of output data is enabled.
A setting of TRUE implies that short-term archiving will be enabled.
valid values
TRUE or FALSE
Default setting is TRUE


name
DOUT_S_ROOT
description
Short-term archiving root directory.


4.8.5 env_mach.$MACH output data long-term archiving


name
DOUT_L_MS
description
Flag to determine whether long-term archiving of model output data will be done. long-term archiving of output data is done from the short-term archiving area to a local and possibly a remote mass store using the CCSM long-term archiving script, $CASE.l_archive. long-term archiving of output data will only be activated only if the environment variable $DOUT_S is also set to TRUE.
valid values
TRUE or FALSE
Default setting is FALSE


name
DOUT_L_RCP
description
Flag to determines if long-term archiving should copy files to another site in addition to copying files to the local mass store. If long-term archiving is required to copy files to another site, this requires that ssh be set up so that passwords are note required
valid values
TRUE or FALSE
Default setting is FALSE


name
DOUT_L_MSROOT
description
Local mass store long-term archiving root Used by the script $CASE.l_archive if available. Ignored if $DOUT_L_MS is set to FALSE.


name
DOUT_L_MSNAME
description
Logname in uppercase. Only used for NCAR MSS. Used by the script $CASE.l_archive if available. Ignored if $DOUT_L_MS is set to FALSE.


name
DOUT_L_PWD
description
Mass store file write password. Only used for NCAR MSS. Used by script $CASE.l_archive if available. Ignored if $DOUT_L_MS is set to FALSE.


name
DOUT_L_RPD
description
Mass store file read password. Only used for NCAR MSS. Used by script $CASE.l_archive if available. Ignored if $DOUT_L_MS is set to FALSE.


name
DOUT_L_PRJ
description
Mass store project charge number Only used for NCAR MSS. Used by script $CASE.l_archive if available. Ignored if $DOUT_L_MS is set to FALSE.


name
DOUT_L_RCP_ROOT
description
Mass store directory path name (only used for NCAR MSS)
description
Remote machine directory for to be used if $DOUT_L_RCP is set to TRUE. Ignored if $DOUT_L_RCP is set to FALSE.

4.9 Scripts design for developers

This section provides a brief overview of the design of the scripts and can be used by CCSM developers to help understand how the scripts are implemented and how they operate.

The highest level scripts, create_newcase and create_test, are in the $CCSMROOT/ccsm3/scripts directory. All supporting utilities are contained in the $CCSMROOT/ccsm3/scripts/ccsm_utils/ directory, which in turn has the following directory structure: 

                                 ccsm_utils/
                                     |
        +--------------+-------------+---- ---------+----------+
        |              |             |              |          |
  Case.template/   Components/    Machines/     Testcases/   Tools/
        |
    SourceMods/
        |
      src.*

create_newcase copies the Case.template/ directory recursively to any a new $CASEROOT/ directory and subsequently modifies these files with the appropriate sed commands. The files and directories in Case.template form the baseline set of files for every new case.

The Components/ directory contains a unique script for every CCSM3 component. The template files set up the component scripts in the $CASEROOT/Build*/ directories. These include namelist generation and data prestaging scripts for the CCSM3 components as well as scripts for building internal libraries and CCSM3 component executables. The filename convention is component.template (e.g. cam.template). Template scripts for each component selected in the env_conf file are executed when configure is called. There are also templates for each CCSM3 internal library that needs to be built.

The ccsm_utiles/Machines/ directory contains all machine specific information. The only other directory where machine-specific information exists is $CCSMROOT/ccsm3/models/bld/, where machine specific compiler flags are placed. In the Machines/ directory, each machine may contain up to five files. For each supported machine there are always three files: env*.$MACH, batch*.$MACH, and run*.$MACH. If long-term archiving exists for that machine, l_archive*.$MACH will also exist. In addition, some machines may also have modules.*.$MACH, if modules are used on that machine. The env*.$MACH file is copied directly to the $CASEROOT/ directory and renamed env_mach.$MACH by the script create_newcase. The batch*.$MACH, run*.$MACH and l_archive*.$MACH scripts are used by configure (in conjunction with other tools) to generate the machine-dependent build, run, and long-term archiving scripts in the $CASEROOT/ directory.

The ccsm_utils/Testcases/ directory contains scripts which automatically generate CCSM test cases. For each test case, there are two scripts. Each test case is designated by a unique six character name, e.g. ER.01a, and has its own setup script. These scripts are used by create_test to generate a wide variety of CCSM tests (see section 7).

Finally, the Tools/ directory contains a large suite of scripts. Some of these scripts are used by create_newcase and configure. Others are simply used as utilities by the ``resolved'' scripts in the Buildnml_Prestage/ directory and the ``resolved'' run and build scripts in the $CASEROOT/ directory.

Users will generally not need to modify any of the scripts under ccsm_utils/. Exceptions where such modifications may be needed would be porting to a new machine, modifying the default archiving behavior, adding new resolutions, or adding new test cases. Such issues are described in more detail later (see section 6). Users should feel free to modify files in ccsm_utils/ as needed. If modifications to ccsm_utils/ files are needed, they must be done by users in their personal workarea and not in code directories that are shared among more than one user.

4.10 General script tools

As described above, the ccsm_utils/Tools/ directory contains several generic utilities. The scope of these scripts varies significantly. Although many of the tools contained in this directory are self described, we provide a general summary of their usage below.

4.11 Script generation tools

4.11.1 Script validation tools

4.11.2 Input/output data movement

next up previous contents index
Next: 5 Building, Running and Up: UsersGuide Previous: 3 Obtaining code, scripts   Contents   Index
csm@ucar.edu