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.
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.
Preprocessor flags are activated in the form -Doption in the Macros.* files. The flags specific to the ice model are
CPPDEFS := $(CPPDEFS) -Dcoupled -DNPROC_X=$(NX) -DNPROC_Y=$(NY) -D_MPI
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 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.
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.
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.
The main driver script for CCSM2 is scripts/test.a1/test.a1.run. 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.
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.
| 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:
ice_model_size.F.100x116x1
ice_model_size.F.100x116x3
ice_model_size.F.100x116x5
ice_model_size.F.100x116x10
ice_model_size.F.320x384x1
ice_model_size.F.320x384x3
ice_model_size.F.320x384x5
ice_model_size.F.320x384x10
| 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 4.8.3.3.
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 f20.007.cam2.h1.0006-01-01-00000.nc and is f20.007.cam2.h1.0006-01-01-00000.nc 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 = 1data_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.
The namelist parameters in this setup script are similar to those in datm.setup.csh. See section 4.1.3.3 for comments on data_dir, data_year0, data_nyear, and data_oyear. The forcong filename is f20.007.cpl5.ha.0006-xx.nc for the T31 grid, f20.006.cpl5.ha.0006-xx.nc for the T42 grid, and lsmh_0016.nc 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.
The docn.setup.csh script is also set up to read in the new Hurrell sea surface temperature dataset. The file name is sst_clim_hurrell_1x1_020724.nc, 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
The parameters that determine when a simulation will stop are set in the coupler namelist. The preset values are
stop_option = 'ndays' stop_n = 5This 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 = 365To 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 monthIf 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 = 3rest_n is only used if rest_freq = 'ndays'. See the coupler User's Guide for more information on these and other parameters.