next up previous contents
Next: 4.2 Multiple Resubmissions Up: 4 Using CSIM4 Previous: 4 Using CSIM4   Contents


4.1 How to Build and Run CSIM4 within CCSM2

Building and executing any configuration of CCSM2 is carried out in the scripts. This section describes the build environment and the scripts. It is assumed that the user has done a 5 day startup run using a configuration described in Section 3.

4.1.1 The Build Environment

All components of CCSM2 use the same Makefile and make environment. These files are located in the models/bld directory. There is a single makefile for all models and all platforms. However, there is a Macros.* file for each platform. Macros.AIX is for the IBM, Macros.IRIX64 is for the SGI, and Macros.OSF1 is for the Compaq. These files contain information for the preprocessor and the compiler. CSIM4 has a set of options that is different from the default values at the top of the file. These are after the line ifeq ($(MODEL),csim) in the Macros.* files and are described below. CSIM4 Preprocessor Flags

Preprocessor flags are activated in the form -Doption in the Macros.* files. The flags specific to the ice model are


The option -Dcoupled is set to activate the coupling interface. This will include the source code in ice_coupling.F, for example. For uncoupled runs (not supported), it can be set to anything else (i.e. uncoupled) or removed. If the model is run uncoupled or a coupler other than the CCSM2 coupler is used, there is a flag called -Dfcd_coupled that will keep the fluxes from being divided by the ice area. In coupled runs, the CCSM2 coupler multiplies the fluxes by the ice area, so they are divided by the ice area in CSIM4 to get the correct fluxes.

The options -DNPROC_X=$(NX) and -DNPROC_Y=$(NY) set the number of processors used in each grid direction. These values are calculated in ice.setup.csh using $NTASK from the main setup script. NX and NY must divide evenly into the grid. This is used only for MPI grid decomposition. The values of NX and NY are not used for OPENMP (not supported) and single processor runs. If NX or NY do not divide evenly into the grid, the model setup will exit from the ice.setup.csh script and print an error message to the ice.log* file.

The flag -D_MPI sets up the message passing interface. This must be set for runs using a parallel environment. To get a better idea of what code is included or excluded at compile time, grep for "ifdef" and "ifndef" in the code. or look at the *.f files in the /obj directory if they are not removed by gmake. CSIM4 Compiler Options

CSIM4 uses the CCSM2 default compiler options on the SGI and Compaq platforms. On the IBM, the following options are set in Macros.AIX:

-c -O3 -qstrict -qrealsize=8 -qarch=pwr3 -qtune=auto -I${INCROOT}

All but the last option are standard Fortran compiler options. The last flag includes the Earth System Modeling Framework (ESMF) library, which is not currently used by the ice model.

4.1.2 Creating and Running the Executable

It is assumed that the user has obtained and extracted the source code and input data as described in Section 2 and that the appropriate changes have been made to the main setup script as described in section 3. The executable file is created and executed by simply submitting the main script. Below is a brief description of the data model and coupler setup scripts, and a more complete description of the ice model script. A detailed description of the other scripts can be found in the CCSM2 User's Guide.

4.1.3 Setup Scripts

The purpose of the main driver script is to set environment variables that are available to the component model scripts, execute the setup scripts for each component in the desired configuration, and then execute all components simultaneously. Each component model is prepared for execution via a separate script. These scripts create directories, position input data, create a file with the namelist input, and build an executable. This section describes the scripts necessary to setup the D configuration: the active ice component with data models for the ocean, atmosphere, and land. Main Driver Script

The main driver script for CCSM2 is scripts/test.a1/ The script is set up for the default B configuration. To run CCSM2 in this configuration, see section 3. A complete description of this script is available in the CCSM2 User's Guide. Several changes will have to be made to this file to set up the D configuration. These changes are discussed in section 3.3. Ice Setup Script

The purpose of the ice setup script, ice.setup.csh, is to build an executable version of the ice model, document what source code and data files are being used in the ice.log.$LID file, and gather or create any necessary input data files. $LID is a time stamp set in the main script. This file is executed from the main driver script. The environment variables shown in Table 1 are set in the main script and used in the ice setup script. These variables are described in the CCSM2 User's Guide.

Table 1: Environment Variables in Main Script Used in Ice Setup Script
Symbol Description Default Value Other Values
ARCH system architecture m ncar lanl
BASEDATE initial start date (YYYY-MM-DD) 0001-01-01  
CASE case name test.a1  
CSMBLD makefile and Macros directory $CSMROOT/models/bld  
CSMCODE source code base directory $CSMROOT/models  
CSMDATA input data base directory /fs/cgd/csm/inputdata  
CSMSHR directory for shared code $CSMROOT/models/csm_share  
EXEDIR ice model executable directory $EXEROOT/ice  
GRID atm and ocean grid T42_gx1v3 T31_gx3v4
ICE_GRID ice model grid gx1v3 gx3v4
MODEL name of component model ice  
MSSDIR MSS directory path name null:/dev/nul  
MSSPWD MSS file write password $LOGNAME  
MSSRPD MSS file retention period in days 0  
NTASK number of tasks for ice model 16 4, 8
NTHRD number of threads for ice model 1  
OBJDIR component model code is built here $OBJROOT/ice/obj  
REFCASE input data case name for branch run test.a1  
REFDATE start date for branch run 0001-01-06  
RUNTYPE run type startup continue
SCRIPTS directory for run scripts $CSMROOT/scripts/$CASE  

The environment variables set locally in the ice setup script are listed in Table 2. $HSTDIR, $RSTDIR and $INIDIR are the directories in $EXEDIR where the history, restart, and initial condition files are output, respectively. These follow the directory structure set in the CCSM2 output filename requirements. $ICEDATA is the directory under $CSMDATA where the ice input data is located. The ice model input templates are located in $ICESRC. These templates are fortran modules that contain information on grid dimensions, number of ice thickness categories and vertical resolution in the ice categories. The grid is determined in the main script and the resolution $RES is set in ice.setup.csh: 100x116 for the gx3v4 grid and 320x384 for gx1v3. Depending on $RES and the number of ice thickness categories $NCAT set in ice.setup.csh, the appropriate input template ice_model_size.${RES}x${NCAT} will be copied into the ice model source code directory and renamed ice_model_size.F. Files exist for the following configurations:


Table 2: Environment Variables Set in the Ice Setup Script
Symbol Description
HSTDIR directory where history files are written
RSTDIR directory where restart files are written
INIDIR directory where initial condition files are written
ICEDATA subdirectory where ice model input data collection is located
ICESRC directory where ice model input templates are located
RES grid dimensions used to select model resolution
NCAT number of thickness categories in the ice thickness distribution
NX number of processors assigned in the x direction, used for MPI grid decomposition
NY number of processors assigned in the y direction, used for MPI grid decomposition
NLAT number of latitudes in grid resolution
NLON number of longitudes in grid resolution
OCEANMIXED_ICE logical variable used to implement ocean mixed layer model
OML_ICE_SST_INIT logical variable, if true initialize ocean mixed layer temperature from within ice model
PICE_DATA datafile containing forcing for prescribed ice model
PRESCRIBED_ICE logical variable used to implement prescribed ice model
PRESCRIBED_ICE_CLIM logical variable, if true, climatological data is used with the prescribed ice model
RESTART logical variable used to initialize model from a restart file
RSTFILE name of restart file

The total number of processors $NTASK allocated to the ice model is set in the main script. In ice.setup.csh, this number is divided into the number of processors in the x and y directions, $NX and $NY. The grid decomposition has been fixed at NY=1 for fewer then 8 processors, NY=2 for 8 or more processors, and NX=NTASK/NY. Currently, NX and NY MUST divide evenly into the grid. There are checks for this in the ice setup script and in the ice source code; the model will stop if these criteria are not met. $NLAT and $NLON are used for this purpose.

The environment variable $OCEANMIXED_ICE is set to .true. to implement the slab ocean mixed layer within the ice model. Details on this option and how to set $OML_ICE_SST_INIT are described in section 4.6.7.

Similarly, the environment variable $PRESCRIBED_ICE is set to .true. to activate the prescribed ice option within the ice model. This option is meant to be run with active atmosphere and land components and a data ocean, and will require changes to the main setup script. Details on setting up the prescribed ice model and a description of $PRESCRIBED_ICE_CLIM can be found in sections 3.5 and 4.6.6.

The sea ice model contains two namelists. The variables for both lists are set in ice.setup.csh and are written to the file ice_in in $EXEDIR/ice when the ice setup script is executed. Changes to the namelists must be made in the setup script, not in the ice_in file. The ice model reads his file at runtime. The first namelist is called ice_nml and is defined in ice_init.F. The variables are listed in Tables 3-10. The namelist options are discussed in section 4.3.1.

The second namelist is called icefields_nml and is defined in ice_history.F. It contains a list of logical variables that correspond to ice fields that can be written to the history file. By default, all these variables are set to ".true.", so leaving the namelist blank will result in all variables being written to the history file. The available fields are listed in Table 12. Changing the content of the history files via the namelist is discussed in section Data atm Setup Script

There are two data atmosphere models. The first is datm5 and uses the setup script datm.setup.csh. This data model reads in netCDF output files from a previous CAM atmospheric simulation and interpolates the data in time. The filename for the T31 forcing is and is for the T42 grid. These filenames are already set in the datm setup script as are the namelist parameters for the years of data that are read in:

  data_year0 =  0006
  data_nyear =  1
  data_oyear =  1
data_year0 specifies the first year in the input atmosphere data file sequence. data_nyear specifies the number of years in the input atmosphere data file sequence. data_oyear is the simulated year that corresponds to data_year0. Note that only one year of CAM data is provided with this release of CCSM2. Changes to the datm script to read in the appropriate file are made automatically when $GRID is changed in the main setup script.

To modify the solar forcing, a namelist parameter can be added

 flux_swfact=  1.3

All CCM shortwave fields will be multiplied by this factor. The code for this is also in models/atm/datm5/ data_in_nc.F90.

The second data atmosphere model is called latm5 and uses the setup script latm.setup.csh. This data model can read in NCEP forcing or a combination of any datasets. One year of NCEP data has been included with this release of CCSM2 and consists of air density, specific humidity, wind speed, and air temperature at 10 meters, precipitation, downwelling longwave, and downwelling and upwelling shortwave. To use latm5, the grid for the atmosphere must be set to T62 in the main setup script. This grid configuration is supported only for latm5 runs; other modifications will have to be made in the main script. See section 3.4 and the data model User's Guide for more information. Data lnd Setup Script

The namelist parameters in this setup script are similar to those in datm.setup.csh. See section for comments on data_dir, data_year0, data_nyear, and data_oyear. The forcong filename is for the T31 grid, for the T42 grid, and for the T62 grid. Changes to the dlnd script to read the appropriate file are made automatically when $GRID is changed in the main setup script.

See the data model User's Guide for more information. Data ocn Setup Script

The docn.setup.csh script is also set up to read in the new Hurrell sea surface temperature dataset. The file name is, and the docn model will interpolate the data from the 1x1 grid to the ocean grid set in the main script. A comment should be made about when docn is set in $SETUPS in the main script and $OCEANMIXED_ICE is set to .true. in the ice setup script. Data is read in by docn5 and is received by the ice model from the coupler. This information will be written over by the values calculated in the slab ocean model within the ice model. See the data model User's Guide for more information Coupler Setup Script

The parameters that determine when a simulation will stop are set in the coupler namelist. The preset values are

  stop_option = 'ndays'
  stop_n      = 5
This will stop the simulation after advancing stop_n days; stop_n is used only when stop_option = 'ndays'. To run the model for a year, set
  stop_n      = 365
To stop the simulation when a particular date is reached, set
    stop_option = 'date'
    stop_date   = 19800801
Other options for stop_option are
 stop_option = 'newdecade' stop at the start of the next decade 
 stop_option = 'newyear'   stop on the next January 1st 
 stop_option = 'newmonth'  stop on the 1st of the next month
If stop_option is set to any of these other options, no date or namelist stop information is needed.

The frequency at which restart files are written by the coupler and other components is determined by the parameter rest_freq. The coupler will send a message to the other components signaling that it is time to write a restart file. The ice model contains its own flag to signal when to write a restart file: dumpfreq in the ice model namelist. The ice model will write out restart files if rest_freq is true or if dumpfreq is true. The preset value for the coupler flag is
rest_freq = 'monthly'
Other options for this parameter are
rest_freq = 'yearly'
rest_freq = 'ndays'
To create restart files every three days, set

  rest_freq   = 'ndays'
  rest_n      = 3
rest_n is only used if rest_freq = 'ndays'. See the coupler User's Guide for more information on these and other parameters.

next up previous contents
Next: 4.2 Multiple Resubmissions Up: 4 Using CSIM4 Previous: 4 Using CSIM4   Contents