next up previous contents
Next: 5 Running the CCSM Up: UsersGuide Previous: 3 The CCSM Scripts   Contents


4 Building the CCSM

CCSM2.0 is supported on IBM SP2 and SGI Origin 2000 platforms. These platforms represent examples of both distributed-memory and shared memory-architectures. A sample script is distributed with the model to illustrate how to configure the model to run on these different architectures, at different resolutions, with different combinations of models.

4.1 The CCSM directory structure

The CCSM2.0 code distribution consists of three directories:

                     |            |               |
                  scripts/      models/          doc/

In the scripts/ directory are sample CCSM run scripts, tool scripts and a graphical user interface for constructing different CCSM configurations. The scripts/test.a1/ directory contains the master run script (scripts/test.a1/ and all the setup scripts necessary to build and run the CCSM on the supported platforms.

The scripts/test.a1/ script has three main tasks:

1 Define common build and run environment variables.
2 Run the setup script for each component.
  a. Acquire any initial or boundary datasets needed by that component.
  b. Generate the components namelist input file.
  c. Build the component executable.
3 Execute all components simultaneously.

The common build and run environment variables set in the run script are automatically propagated to each of the component model setup scripts. The setup scripts will use tools found in the scripts/test.a1/tools. In scripts/test.a1/gui_run is a graphical user interface to generate different CCSM configurations based on the test.a1 sample scripts.

The models/ directory contains all the source code needed to build the CCSM. Underneath the models/ directory are directories for each of the CCSM components:

models/bld/ Gnumake Makefiles and machine-dependent macro files
models/cpl/ Flux Coupler source code
models/atm/ source code for all atmosphere models
models/ice/ source code for the sea-ice models
models/ocn/ source code for the ocean models
models/lnd/ source code for the land models
models/utils/ common utilities source code
models/csm_share/ source code shared by more than one CCSM component
models/camclm_share/ source code shared by CLM and CAM only

The input data necessary to run the model is distributed separately and is discussed below.

4.2 $CSMBLD contents

The directory $CSMBLD contains the files necessary to build the CCSM components.

                    $CSMROOT/models/bld    ($CSMBLD)
       |        |          |        |             |            |      
    makdep.c Makefile Macros.AIX Macros.OSF1 Macros.IRIX64 Macros.Linux

The Macros files contain makefile defaults for each platform. In the current release, the Macros have been divided into different files depending on platform. Within each platform are site/machine specific options. The platform type is set in the main test script with the environment variable OS. In addition, machine dependent options are also included in the Macros files for specific platforms that have been tested. The machine specific options are set in the Macros files by use of the environment variable MACH.

4.3 $EXEDIR structure

The CCSM is built in the directory specified by $EXEROOT which is defined in the main run script, scripts/test.a1/ Underneath $EXEROOT, all of the model components will be build in their own separate subdirectories. The subdirectories will be below the $EXEDIR unless the user selects a non-defual location for $OBJDIR.

                   /scratch/$LOGNAME/$CASE    ($EXEROOT)
       |           |               |             |            |      
      cpl/        atm/            ocn/          ice/         lnd/     ($EXEDIR)
       |           |               |             |            |      
    +--+---+    +--+---+        +--+---+      +--+---+     +--+---+       
           |           |               |             |            |
          obj/        obj/            obj/          obj/         obj/ ($OBJDIR)

Each $EXEDIR subdirectory contains everything needed to run a specific CCSM component: the objects, executables, input and boundary datasets. Output from the component, such as standard out logs and history and restart datasets will also be written into $EXEDIR subdirectories. Some of the components, such as the ocean and sea-ice, have separate subdirectories for input, restart and history data, while the atmosphere and land put all of these in one directory.

For each component there is a directory which contains all the files created during the compilation of that component. This includes the dependency files, cpp products and object files. In this example, $OBJDIR is located below the component $EXEDIRs. However, $OBJDIR (set in can be set to be completely independent of $EXEDIR if desired.

4.4 Input data positioning

The CCSM input data is distributed separately from the source code. Individual tar files exist for various resolutions and configurations. To run CCSM, these data need to be untarred from the inputdata tar file and the root location of the untarred input data needs to be used to define the variable $CSMDATA in the $SCRIPTS/ script.

As with the models and $EXEDIR directories, separate directories exist for each CCSM component in the $CSMDATA directory:

       |           |                 |           |            |      
      cpl/        atm/              ocn/        ice/         lnd/    
       |           |                 |           |            |       
       |     +-----+------+      +---+--+     +--+----+       +------+ 
       |     |     |      |      |      |     |       |       |      |                               
     cpl5/  cam/ datm5/ latm5/  pop/  docn5/ csim4/ dice/    clm2/ dlnd/

$CSMDATA can be located anywhere as long as the data can be copied from that location to $EXEROOT. Once $CSMDATA has been identified in scripts/test.a1/, the individual setup scripts copy the data required for their component from $CSMDATA to the component directories under $EXEROOT.

4.5 Building the model interactively

Currently, the build and run of the CCSM model are interweaved in the same scripts. While CCSM is usually not run interactively, it is often convenient to compile the model interactively to verify initial data placement and compilation success without having to wait in a queue. There is a comment line in the main run script that when made active will cause the script to exit before CCSM begins to execute. The exit command looks like


So, the CCSM model can be built interactively by making the above line active (uncommenting the line) and executing


next up previous contents
Next: 5 Running the CCSM Up: UsersGuide Previous: 3 The CCSM Scripts   Contents