The sea-ice setup script, scripts/test.a1/ice.setup.csh, is called by test.a1.run when the ice model is selected in the MODELS environment variable array. The script ice.setup.csh prepares the sea-ice model component for execution. To do so, the setup script defines the run environment, positions the sea-ice input data sets, then builds the dynamic sea-ice model by calling gmake.
If ice.setup.csh is unable to complete any of these tasks, it will abort with a non-zero error status. The test.a1.run script checks the error status and will halt if an error is detected.
#! /bin/csh -f #======================================================================= # CVS $Id: ice.setup.csh.tex,v 1.5 2002/06/18 21:25:50 southern Exp $ # CVS $Source: # CVS $Name: $ #======================================================================= # ice.setup.csh: Preparing a CSM sea-ice model, csim4, for execution # # (a) set environment variables, preposition input data files # (b) create the namelist input file # (b) build this component executable # # For help, see: http://www.cesm.ucar.edu/models/ice-csim4 #======================================================================= cat $0;$TOOLS/ccsm_checkenvs || exit -1 # cat this file, check envs
This first section documents the sea-ice setup script.
The first line of this section identifies this as a C-shell script. The "-f" option prevents the user's personalized $HOME/.cshrc file from being executed to avoid introducing aliases that could adversely affect the operation of this script.
The CVS lines document the revision control version of this script.
The echo lines document the purpose of this script. These output from the echo commands will appear in the component log files.
The cat command combines two functions on one line. The "cat $0" command prints a copy of the entire setup script into the output log file in order to document the exact options set by this script. Then $TOOLS/ccsm_checkenvs writes the environment variables that have been set by test.a1.run into the same output log file. If any of the required environment variables are not set, the setup script will exit with an error status of -1.
echo ------------------------------------------------------------------- echo a. set ice setup variables, get input files echo ------------------------------------------------------------------- set PRESCRIBED_ICE = .false. set PRESCRIBED_ICE_CLIM = .false. set OCEANMIXED_ICE = .false. set NCAT = 5 # number of ice catagories
The first variables set in ice.setup.csh are flags that enable or disable the prescribed ice, climatological prescribed ice and the mixed-layer ocean options. For a fully coupled CCSM run, each of these flags will be set to .false.
| PRESCRIBED_ICE | = .false. will result in the fully dynamical sea-ice model. Setting $PRESCRIBED_ICE to .true. will force the ice model to run in a thermodynamic-only state. Under these conditions, the ice extent and thickness are read in from a 19 year observational data file. |
|---|---|
| PRESCRIBED_ICE_CLIM | = .false. disables the climatological cycling option for $PRESCRIBED_ICE = .true. $PRESCRIBED_ICE_CLIM = .true. is a special case of PRESCRIBED_ICE where the ice model continually cycles over 12 months of a climatological sea-ice data. |
| OCEANMIXED_ICE | = .false. disables the slab mixed-layer ocean model option in the sea-ice model. The slab mixed- layer ocean model option is generally used for sea-ice testing. |
# Create directories for output hist/rest filenames #----------------------------------------------------------------------- set HSTDIR = $EXEDIR/hist ; if !(-d $HSTDIR) mkdir -p $HSTDIR set RSTDIR = $EXEDIR/rest ; if !(-d $RSTDIR) mkdir -p $RSTDIR set INIDIR = $EXEDIR/init ; if !(-d $INIDIR) mkdir -p $INIDIR # Calculate year used in new hist/rest filenames #----------------------------------------------------------------------- if ($RUNTYPE == branch || $RUNTYPE == hybrid) then set DATEDASH = $REFDATE-00000 else set DATEDASH = $BASEDATE-00000 endif
Next, the directories for the history, restart and initial data are created if they don't already exist. Then the relevant date information is parsed into a form acceptable by CSIM based on the type of run being made.
# read in ice datasets
#-----------------------------------------------------------------------
set ICEDATA = ice/csim4/
set RESTART = .true.
set PICE_DATA = " "
set OML_ICE_SST_INIT = .false.
rm -f data.domain.grid data.domain.kmt
$TOOLS/ccsm_getinput $ICEDATA/global_${ICE_GRID}.grid data.domain.grid || exit 2
$TOOLS/ccsm_getinput $ICEDATA/global_${ICE_GRID}.kmt data.domain.kmt || exit 2
| ICEDATA | = ice/csim4/ defines the directory path (relative to $CSMDATA set in test.a1.run) for the ice initial and boundary data in the CCSM2.0 distribution. |
|---|---|
| RESTART | = .true. instructs the ice model to read the names of the initial files from the restart pointer files. |
| PICE_DATA | = `` `` initializes the value of the variable containing the filename of the input data for the prescribed ice option to blank. |
| OML_ICE_SST_INIT | = .false. sets the flag controlling whether the SST values are initialized from the ocean fractional data |
Next, files containing the sea-ice grid and land-mask information are copied into the $EXEDIR directory.
if ($PRESCRIBED_ICE == .true.) then
if ($PRESCRIBED_ICE_CLIM == .false. && $BASEDATE != 1977-01-01) then
echo "Set BASEDATE in main script to 1977-01-01" ; exit -1
endif
if ($RUNTYPE == startup) set RESTART = .false.
if ($ICE_GRID == 'gx3') \
set PICE_DATA = AMIP_bc${ICE_GRID}_1976-1996_011030.nc
if ($ICE_GRID == 'gx1v3') \
set PICE_DATA = AMIP_bc${ICE_GRID}_1976-1996_010817.nc
$TOOLS/ccsm_getinput $ICEDATA/$PICE_DATA . || exit 99
endif
Here the actual initial and boundary files are positioned for the prescribed ice case. First, a specific BASEDATE of January 01 1977 is enforced when the ice model is not being run in climatological mode. Next, the RESTART flag is used to tell the model not to use the restart pointer files on a startup run to obtain the initial data. Then the time-varying boundary data sets are named and copied into place.
if ($RESTART == .true.) then
if ($RUNTYPE == startup ) then
set RSTFILE = iced.0001-01-01.${ICE_GRID}
$TOOLS/ccsm_getinput $ICEDATA/$RSTFILE $RSTDIR/ || exit 2
echo $RSTDIR/$RSTFILE >! $SCRIPTS/rpointer.ice
else if ($RUNTYPE == branch || $RUNTYPE == hybrid) then
set RSTFILE = $REFCASE.csim.r.$DATEDASH
$TOOLS/ccsm_getfile $REFCASE/ice/rest/$RSTFILE $RSTDIR/ || exit 2
echo $RSTDIR/$RSTFILE >! $SCRIPTS/rpointer.ice
endif
endif
For startup, hybrid and branch runs, the filenames for the initial data files are constructed and placed into the restart pointer files. ccsm_getfile copies the initial data files into the restart directory. For a continuation run, nothing is done and the restart file names contained in the existing restart pointer files are used to continue the model run. Note, this script segment will be skipped for a startup run when $PRESCRIBED_ICE = .true. .
if ($OCEANMIXED_ICE == .true. ) then
$TOOLS/ccsm_getinput $ICEDATA/pop_frc_${ICE_GRID}_010815.nc
oceanmixed_ice.nc || exit 99
if ($RUNTYPE == startup) set OML_ICE_SST_INIT = .true.
if ( $PRESCRIBED_ICE == .true.) then
echo " Prescribed_ice cannot have Oceanmixed_ice -stop-" ; exit -1
endif
endif
Finally, for the slab ocean case, the initial data corresponding to the specified ice grid is copied in and the OML_ICE_SST_INIT flag is set to initialize the SST's from the ocean data. If both OCEANMIXED_ICE and PRESCRIBED_ICE are set to .true., the script exits with an error status of -1.
echo -------------------------------------------------------------------
echo b. create the namelist input file
echo -------------------------------------------------------------------
cat << EOF >! ice_in
&ice_nml
runid = '$CASE $CASESTR'
, runtype = '$RUNTYPE'
, istep0 = 0
, dt = 3600.0
, ndte = 120
, npt = 99999
, diagfreq = 24
, histfreq = 'm'
, dumpfreq = 'y'
, hist_avg = .true.
, restart = $RESTART
, print_points = .false.
, kitd = 1
, kdyn = 1
, kstrength = 1
, evp_damping = .false.
, snow_into_ocn = .false.
, advection = 'mpdata2'
, grid_type = 'displaced_pole'
, grid_file = 'data.domain.grid'
, kmt_file = 'data.domain.kmt'
, incond_dir = '$INIDIR/'
, incond_file = '$CASE.csim.i.'
, restart_dir = '$RSTDIR/'
, dump_file = '$CASE.csim.r.'
, history_dir = '$HSTDIR/'
, history_file = '$CASE.csim.h'
, mss_dir = '$MSSDIR/$MODEL/ '
, mss_rtpd = $MSSRPD
, mss_pass = '$MSSPWD'
, mss_rmlf = 0
, prescribed_ice = $PRESCRIBED_ICE
, prescribed_ice_file = '$PICE_DATA'
, prescribed_ice_climatology = $PRESCRIBED_ICE_CLIM
, pointer_file = '$SCRIPTS/rpointer.$MODEL'
, oceanmixed_ice = $OCEANMIXED_ICE
, oceanmixed_ice_file = 'oceanmixed_ice.nc'
, oceanmixed_ice_sst_init = $OML_ICE_SST_INIT
, prntdiag_oceanmixed = .false.
/
This section constructs the input namelist that is used to control runtime operation of the sea-ice model. The namelist input file defines a wide range of parameters to control the behavior of the sea-ice model. The namelist input file, ice_in, is read by the sea-ice model on startup. Namelist input for the sea-ice model consists of text strings enclosed in quotes, integer and real numerical values and logicals.
The "cat" command uses the C-shell here-document option to create the file $EXEDIR/ice_in with all the settings being evaluated to the current values of the specified environment variables.
| &ice_nml | is the namelist group name, which matches the groupname defined within the sea-ice model. |
|---|---|
| runid | = '$CASE $CASESTR' (string) provides 80 characters to further describe this run. This description appears in the output logs and in the header data for the output data sets. $CASESTR is set in the $SCRIPTS/test.a1.run script. |
| runtype | = '$RUNTYPE' (string) specifies the state in which this run is to begin. See the sample setup script section for discussion of this variable. |
| istep0 | = 0 (integer) is the starting step number used to set the current elapsed time of the run on startup. |
| dt | = 3600.0 (real) sets the timestep for the ice transport and thermodynamics to 3600 seconds. |
| ndte | = 120 (integer) sets the number of ice model dynamics subcycles per model timestep to damp elastic waves. |
| npt | = 99999 (integer) sets the total number of timesteps. This is ignored in a coupled run where the flux coupler determines the stop point. |
| diagfreq | = 24 (integer) results in diagnostic printout being output at noon every 24 hours. |
| histfreq | = 'm' (string) requests that history output be written monthly. |
| dumpfreq | = 'y' (string) requests that restart output be written yearly. In a coupled run, this variable is ignored and instructions from the coupler are used. |
| hist_avg | = .true. (logical) defines the output history data as being averaged over the output period. |
| restart | = $RESTART (logical) flags whether or not to read the restart data filenames from the restart pointer files. |
| print_points | = .false. (logical) flags whether or not to print out grid point data. |
| kitd | = 1 (integer) determines the type of itd conversions (0 = delta f, 1 = linear). |
| kdyn | = 1 (integer) determines the type of ice dynamics. Currently, only elastic-viscous-plastic dynamics (kdyn=1) is supported. |
| kstrength | = 1 (integer) instructs the ice to use Rothrock 1975 pressure formulation. |
| evp_damping | = .false. (logical) turns off the elastic-viscous-plastic ice damping. |
| snow_into_ocn | = .false. (logical) keeps ridging snow from being dumped into the ocean. |
| advection | = 'mpdata2' (string) set the ice transport advection algorithm to a second order advection scheme using mpdata, |
| grid_type | = 'displaced_pole' (string) sets the ice grid to displace_pole rather than rectangular (default). |
| grid_file | = 'data.domain.grid' (string) names the file containing the ice grid information. |
| kmt_file | = 'data.domain.kmt' (string) names the file containing the land-mask information. |
| incond_dir | = '$INIDIR/' (string) is the directory for snapshot initial conditions. |
| incond_file | = '$CASE.csim.i.' (string) is the filename for snapshot initial conditions. |
| restart_dir | = '$RSTDIR/' (string) is the directory for restart files. |
|---|---|
| dump_file | = '$CASE.csim.r.' (string) is the prefix of the filename for restart files. |
| history_dir | = '$HSTDIR/' (string) is the directory for history output files. |
| history_file | = '$CASE.csim.h' (string) is the prefix of the filename for output history files. |
| mss_dir | = '$MSSDIR/$MODEL/ (string) ' is the NCAR Mass Storage System (MSS) directory for the output files. |
| mss_rtpd | = $MSSRPD (integer) is the retention period for MSS files. |
|---|---|
| mss_pass | = '$MSSPWD' (string) is the write password for MSS files. |
| mss_rmlf | = 0 (integer) instructs the ice model not to remove files from disk after writing them to the MSS. |
| prescribed_ice | = $PRESCRIBED_ICE (logical) is the flag for using the thermodynamic-only prescribed-ice option. |
|---|---|
| prescribed_ice_file | = '$PICE_DATA' (string) is the data file containing the prescribed ice data when using the thermodynamic only prescribed-ice option. |
| prescribed_ice_climatology | = $PRESCRIBED_ICE_CLIM (logical) is the flag for using the climatology option to the thermodynamic only prescribed ice option. |
| pointer_file | = '$SCRIPTS/rpointer.$MODEL' (string) gives the location of the restart pointer file. |
| oceanmixed_ice | = $OCEANMIXED_ICE (logical) is the flag for using the slab mixed-layer ocean option. |
| oceanmixed_ice_file | = 'oceanmixed_ice.nc' (string) is the input data for use by the slab mixed-layer ocean. |
| oceanmixed_ice_sst_init | = $OML_ICE_SST_INIT (logical) controls whether the SST values are initialized from the ocean fractional data. |
| prntdiag_oceanmixed | = .false. (logical) disables diagnostic printout from the slab mixed layer ocean. |
| / | marks the end of the ice_nml group of namelist variables. |
| &icefields_nml | is an unused input namelist file. |
| / | marks the end of the icefields_nml group of namelist variables. |
The CSIM executable is built in this section. First the location of the source code is specified, then some resolution and processor tiling information is resolved. Once the source code Filepath and resolution information has been set, the CSIM executable is built with gmake.
echo ------------------------------------------------------------------- echo c. Build an executable in $OBJDIR echo ------------------------------------------------------------------- cd $OBJDIR # Filepath: List of source code directories (in order of importance). #----------------------------------------------------------------------- \cat >! Filepath << EOF $SCRIPTS/src.$MODEL $CSMCODE/ice/csim4/src/source $CSMSHR EOF
The sea-ice model is build in the directory $OBJDIR to ensure that all the files involved with building the sea-ice model are in one directory.
The Filepath file contains the list of source-code directories from which to gather the input source code. This list will be used as the input to the gmake VPATH list.
The directories appearing in the Filepath file are listed in order of precedence, from most important to least important. If a file is found in more than one of the directories listed in Filepath, the version of the file found in the directory listed first will be used to build the code. The first directory listed, $SCRIPTS/src.ice, is typically used to hold modified sea-ice source code. If a directory in the filepath list is either empty or doesn't exist at all, no error will result.
# select resolution #----------------------------------------------------------------------- if ( $GRID =~ *gx3) set RES = 100x116 if ( $GRID =~ *hx1) set RES = 384x320 if ( $GRID =~ *gx1v3) set RES = 320x384 if !($?RES) echo "ERROR: ice can't deal with GRID = $GRID" if !($?RES) exit -1 set NLON = `echo $RES | sed s/x.\*//` set NLAT = `echo $RES | sed s/.\*x//`
With Filepath set, the CCSM ice grid is parsed into integer longitude and latitude grid dimension values (NLON and NLAT) acceptable to the sea-ice model.
# Calculate processor tiling based on $NTASK #----------------------------------------------------------------------- @ nlon = $NLON setenv NY 1 if ($NTASK > 16) setenv NY 2 @ nx = $NTASK / $NY ; setenv NX $nx @ rem = $nlon % $nx if ($rem != 0) echo ERROR: NX must divide evenly into grid, $NLON,$NX if ($rem != 0) exit -1 # Wipe and rebuild if NX or NY have changed #----------------------------------------------------------------------- echo $NX $NY >! NXNY.new cmp -s NXNY.old NXNY.new || rm $OBJDIR/*.o $EXEDIR/ice echo $NX $NY >! NXNY.old
$NX and $NY specify the number of processors to assign to the latitude and longitude dimensions. This is designed to be automatic. More details on NX and NY can be found in the CSIM documentation.
The CSIM processor tiling is compiled into the model executable. Any changes to the number of processors assigned to CSIM will change the tiling, which requires recompiling the code. This section compares the currently requested tiling with the tiling specified during the last build; if the two tilings are different, a recompilation of CSIM is forced.
# Position new ice_model_size.F when needed
#-----------------------------------------------------------------------
set ICESRC = $CSMCODE/ice/csim4/src/input_templates
cmp -s $ICESRC/ice_model_size.F.${RES}x${NCAT} ice_model_size.F || \
cp $ICESRC/ice_model_size.F.${RES}x${NCAT} ice_model_size.F || exit 3
Predefined templates for the ice-model global domain size, ice categories and number of layers are copied into the current directory. If the current resolution and number of ice categories is different than what was used before, this routine will be recompiled.
# run make
#-----------------------------------------------------------------------
if ($BLDTYPE == 'true') then
cc -o makdep $CSMBLD/makdep.c || exit 2
if ($NTHRD > 1) setenv THREAD TRUE
gmake -j 6 VPFILE=Filepath MODEL=csim EXEC=$EXEDIR/$MODEL \
NX=$NX NY=$NY THREAD=$THREAD \
-f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS || exit 2
else
echo "BLDTYPE = $BLDTYPE"
endif
In this last section the sea-ice model is built using gmake.
The CCSM uses the gnumake (also known as ``gmake'') tool to build the model executable. Each of the components setup scripts creates a list of source code directories from which to gather the input source code for that component. This list is called Filepath and will be used as the input to the gmake VPATH list. The file Filepath is written in each of the components $OBJDIR directories.
The Filepath directories are listed in order of precedence. If a file is found in more than one of the directories listed in Filepath, the version of the file found in the directory listed first will be used to build the code. The first directory, $SCRIPTS/src.ice, is typically used to hold modified component source code. If a directory in the Filepath list is either empty or doesn't exist at all, no error will result. In general, the directories $SCRIPTS/src.$MODEL can be used to store locally modified source code. Each component script recognizes this directory as the top priority for finding source code.
First the makdep code is compiled. This utility program is called by the Makefile and checks for source code dependencies. This is done by seeing if any of the header or include files have been updated since the model was last built and ensures that the F90 modules are constructed in the proper order.
Once makdep is compiled, the GNU make program, gmake, is used to actually build the model. The -j 6 option uses 6 processors to build the model. The -f $CSMBUILD/Makefile points to the generic CCSM Makefile while MACFILE=$CSMBLD/Macros.$OS points to the machine specific make options. MODEL identifies the component being built and VPFILE points to the Filepath list. Finally, the actual executable to be built is $EXEDIR/$MODEL.
# document the source code used, cleanup $OBJDIR files #----------------------------------------------------------------------- grep 'CVS' *.[hf]* #gmake -f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS mostlyclean echo ' ' echo ------------------------------------------------------------------- echo End of setup shell script `date` echo -------------------------------------------------------------------
Once the executable is successfully built, the script documents the revision-control states of the source code and then exits with a 0 status.