Important note: When assembling a CSM configuration, carefully consider the limitations and requirements of all components and be sure that the complete set of component models will interact in a meaningful way. In particular, consider whether the data provided by this model is adequate for your application.
Contents
Note: if CSM configuration consists of a dummy ocean and a dummy ice model
(e.g. coupled to active atmosphere and land models), normally one would
coordinate the ice model's SST data with the ocean model's SST data so that
the SST's and ice extent were consistent.
How the output fields are derived
Each CSM component gets it's own, separate subdirectory in which it's setup
script is run, in which the it's executable resides, and in which all of
it's input and output files are kept.
A set of environment variables set in a parent NQS script and is available
for use (a model may not actually use all of these variables).
Below is an example setup script, followed by some explanation.
(a) Build an executable
The goal here is to build an executable binary in the current working directory.
This is done by
The model resolution (i.e. the number of x and y grid points) must be known
at compile time and is specified in one resolution-dependent file: dims.h.
Notice how an appropriate dims.h file is selected.
Several dims.h files are provided corresponding to frequently used resolutions,
but it is easy to create a dims.h file for any desired resolution.
The details of how to build the executable
(e.g. preprocessor and compiler options) are contained in the Makefile.
(b) Document the source code used
Here we make a detailed listing of the source code used,
a list of revision control system (CVS) information,
and list of the contents of the current working directory.
This information can be used to identify the source code
used in a particular simulation.
(c) Gather or create necessary input files
Here an input data file directory is specified,
the data files found in that directory are copied into the working directory
(note they are all netCDF files), and the desired input files are linked to
the file names "data.sst.nc" and "data.domain.nc"
(the model expects files by these names to exist in the working directory).
Next an input namelist file is constructed.
See the section describing the input namelist variables for more details.
The code must be compiled with a particular model resolution in mind.
The only files that must change with respect to resolution
(i.e. have "hard-coded" resolution dependence) are dims.h (a source code file)
and data.domain (an input data file). See the section describing the
setup script for an example on how these dependencies are handled
at compile time and run time.
This code was developed using the CVS revision control system, but only one
"tagged" version of the code is available within any one distribution.
Each source code file contains detailed revision control information.
 §1  Input data
 §2  Output data
 §3  Input parameters
 §4  Preparing the model for execution
 §5  Source code maintenance
1   Input data
SST data
The ice model state variable ice fraction (equivalently, ice extent)
is derived from input SST data.
On startup, this model reads in SST data from a netCDF file.
This file, is called data.sst.nc, contains 12 months of SST data
(presumably monthly mean fields) on a global 2x2 degree grid.
A file is provided (bundled with the source code distribution)
that can be used in this context.
This file contains Shea, Trenberth, & Reynolds (STR) SST climatology data.
The file provided can be replaced by any other SST data file that is in the
same format. Because netCDF files are self describing, one can query the file
itself for specifics about the file format.
Model domain
On startup, this model reads in domain data from a netCDF file.
Data exchanged with the coupler will be on this model domain.
This file, called data.domain.nc, contains x & y coordinate
arrays as well as a domain mask.
This model uses a latitude/longitude grid only, with 1d coordinate arrays
x(i) & y(j), and a 2d domain mask mask(i,j). A mask value of 0 indicates
land points (i.e. not in the model's domain) and negative values indicate
land-locked regions (e.g. the Caspian Sea).
Input parameter namelist
On startup, this model reads an input namelist parameter file from stdin.
This model has very few input namelist parameters. Often times there will be
only one input parameter, ncpl, which is a positive integer specifying how
many times per simulated day this model will communicate with the flux coupler.
See the section on input namelist variables
for a complete list and description of namelist parameters.
Data received from the flux coupler
This model receives the following fields from the flux coupler
(via message passing):
fluxes
Normally none of these fields are used by this model.
These fields are received because the coupler/ice interface specification
requires that this set of fields be received.
The coupler has no way of knowing whether the components it is connected to
are active models or data models.
states
2   Output data
History files
This model does not create history files. Normally the only data associated with
this model is the data that is already contained in the input SST data file.
Restart files
Normally this model does not need or create restart files.
There are exceptions, however:
restart files will be created if any of the input parameters flux_uv,
flux_Qacc, or flux_swpf (see below) have been reset from their default values.
Restart files are in a machine dependent binary format.
If users want to examine the contents of a restart file,
they will have to look at the source code to see how it was created
and write their own program to read the file and examine it's contents.
Runtime diagnostics
This model generates some diagnostic messages which are written to stdout.
This output consists mostly of brief messages that indicate how the simulation
is progressing and whether any error conditions have been detected. Stdout
also contains a record of the values of all model input parameters.
Data sent to the flux coupler
This model sends the following fields to the flux coupler (via message passing):
states
This model must send these fields to the coupler
because this is part of the coupler/ice interface requirement.
The coupler has no way of knowing whether
the components it is connected to are active models or data models.
fluxes
The input SST is assumed to be 12 monthly average fields.
This data is linearly interpolated in time to get an instantaneous
SST field. Normally the SST data is STR SST data, in which case
a temperature of -1.8 °F indicates sea ice.
The ice fraction is derived from SST as follows:
Temperatures are computed such that the values are similar to those
found in an uncoupled version of the CCM3 atmosphere model:
T north
= 260.0 + 10.0*cos(2
*(emonth - 8)/12)
,   emonth = months elapsed since new year
T south
= 260.0 + 10.0*cos(2
*(emonth - 2)/12)
The default velocity values are zero.
If the input parameter flux_uv is set to "geostrophic," then
the velocities are set to the geostrophic ocean velocities,
which are derived from the ocean surface slope:
u = -g/f*dh/dy,   g=gravity, f=coriolis force
v = -g/f*dh/dx
Snow depth is a constant 0.005m everywhere, which is based on values
found in an uncoupled version of the CCM3 atmosphere model.
The albedos are constant values, have no diurnal cycle, and are based on
a formula found in an uncoupled version of the CCM3 atmosphere model:
avsdr = 0.5*(1.0-snowfrac) + 0.80*snowfrac,   snowfrac = 0.286
anidr = 0.7*(1.0-snowfrac) + 0.96*snowfrac
avsdf = 0.5*(1.0-snowfrac) + 0.70*snowfrac
anidf = 0.7*(1.0-snowfrac) + 0.95*snowfrac
The default penetrating shortwave (thru ice into ocn) is zero.
If the input parameter flux_swpf (short wave penetration factor)
is set to greater than zero, then
penetrating shortwave = flux_swpf * netshortwave
The default values are zero.
If the input parameter flux_Qacc is non-zero (i.e. "true"),
then the model will accumulate ice (if Q > 0),
and later release any accumulated water (if Q < 0).
When water is released (i.e. ice is melted) there is a corresponding
heat flux.
3   Input parameters
The model reads an input namelist from stdin at runtime.
Following is a list and description of available namelist input parameters.
Required: no, and only used if restart files are necessary
(see above), ignored otherwise
Description: This is the case name text string,
up to 8 characters, which is included in output files
to help identify the model run.
Required: no, and only used if restart files are necessary
(see above), ignored otherwise
Description: This is a short text string, up to 80 characters,
which is included in output files to help identify
the model run.
Required: only when restart files are necessary (see above),
ignored otherwise
Description: This selects the run type. Valid choices are:
"initial," "continue," "branch," "regenerate."
Selecting "branch" or "regenerate"
makes rest_bfile a required input.
Required: only when restart files are necessary (see above),
ignored otherwise
Description: This is a mass store directory name.
Restart and history files go into this directory.
For continuation or regeneration runs, the initial
condition restart file must also be in this directory.
Required: only when restart files are necessary (see above) and
rest_type = "branch" or "regeneration,"
ignored otherwise
Description: This is the name of a restart file (on the mass store)
which will provide the IC's for a branch or
regeneration run.
Required: only when restart files are necessary (see above),
ignored otherwise
Description: This is the complete path and name of the restart
pointer file. The path must specify an existing,
NFS mounted directory.
Required: no (assuming the default value is appropriate)
Description: This specifies how many times per day the model
communicates (exchanges data) with the coupler
Required: no
Description: If flux_Qacc 0
(i.e. true, accumulation is activated),
accumulate ice formed in the ocean if Q > 0,
and melt any accumulated ice if Q < 0.
Note: the melt rate won't exceed
(a) the rate that would melt all accumulated ice
in one communication interval, or
(b) the maximum melt rate specified by flux_Qmin.
Required: no (only used if flux_Qacc
0)
Description: On an initial run, the accumulated
water mass field is initialized to this value.
Required: no (only used if flux_Qacc
0)
Description: The melt rate is limited by flux_Qmin
(recall fluxes are positive down).
This prevents a potentially unreasonable melt rates.
Required: no
Description: Debugging information level: 0, 1, 2, or 3.
4   Preparing the model for execution
The model's setup script, called ice.setup.csh, is invoked prior to the
execution of the model. The setup script builds the executable code,
documents the source code, and gathers the required input data files.
#! /bin/csh -f
#======================================================================
# Purpose:
# (a) build an executable model (dice4 climatological data ice model)
# (b) document the source code used
# (c) gather or create necessary input files
#======================================================================
echo '================================================================='
echo ' Preparing model for execution '
echo '================================================================='
echo ' '
echo Date: `date`
echo ' '
echo 'Env variables by a parent shell:'
echo ' $CASE = ' $CASE
echo ' $CASESTR = ' $CASESTR
echo ' $RUNTYPE = ' $RUNTYPE
echo ' $ARCH = ' $ARCH
echo ' $CSMSHARE = ' $CSMSHARE
echo ' $MAXCPUS = ' $MAXCPUS
echo ' $SSD = ' $SSD
echo ' $MSS = ' $MSS
echo ' $MSSDIR = ' $MSSDIR
echo ' $MSSRPD = ' $MSSRPD
echo ' $MSSPWD = ' $MSSPWD
echo ' $RPTDIR = ' $RPTDIR
echo ' $MSGLIB = ' $MSGLIB
echo '-----------------------------------------------------------------'
echo ' (a) Build an executable '
echo '-----------------------------------------------------------------'
if ( -e ice ) then
echo 'Note: using an existing binary'
ls -lFt ice src/Build.log.* | head
else
#--- create a src code sub-directory ---
mkdir src
cd src
#--- document the build ---
set BLDLOG = Build.log."`date +%y%m%d-%H%M%S`"
echo 'Note: (re)building a binary'
echo "See: $BLDLOG "
echo "Build log " >! $BLDLOG
echo "Date: `date` " >>& $BLDLOG
echo "Dir : `pwd` " >>& $BLDLOG
echo "User: $LOGNAME " >>& $BLDLOG
#--- gather source code ---
echo "/fs/cgd/csm/models/ice/dice4.0 " >! Filepath
#cho "/insert/filepath/for/patches " >> Filepath
foreach SRCDIR (`cat Filepath`)
echo "o gathering src code from $SRCDIR" >>& $BLDLOG
cat $SRCDIR/README >>& $BLDLOG
ls -lF $SRCDIR >>& $BLDLOG
cp -fp $SRCDIR/* . >>& $BLDLOG
end
#--- select resolution ---
rm -f dims.h ; ln -s dims.h.150x111 dims.h
#--- create make's include files & invoke make ---
Makeprep >>& $BLDLOG
make EXEC=dice4 ARCH=$ARCH >>& $BLDLOG || exit 2
#--- link binary into /. directory ---
cd ..
rm -f ice ; ln -s src/dice4 ice
endif
echo '-----------------------------------------------------------------'
echo ' (b) document the source code used '
echo '-----------------------------------------------------------------'
echo "o contents of /src:" ; ls -alFt src ; echo ' '
echo "o revision control info:" ; grep 'CVS' src/*.[hF] ; echo ' '
echo '-----------------------------------------------------------------'
echo ' (c) gather or create necessary input files '
echo '-----------------------------------------------------------------'
set DATADIR = /fs/cgd/csm/models/ice/dice4.0
cp -fp $DATADIR/*.nc .
rm data.sst.nc ; ln -s sst.str.nc data.sst.nc
rm data.domain.nc ; ln -s domain.150x111.nc data.domain.nc
cat >! ice.parm << EOF
&inparm
ncpl = 24
/
EOF
echo "o contents of ice.parm:" ; cat ice.parm ; echo ' '
echo "o contents of `pwd`:" ; ls -alF ; echo ' '
echo '================================================================='
echo ' End of setup shell script '
echo '================================================================='
Items (a) through (c) in the above setup script are now reviewed.
o identifying a source code directory (directories),
o acquiring the source code from that directory (directories),
o selecting a resolution-dependent "dims.h" file,
o executing the Makeprep script which creates the include files required
by the makefile (e.g. a list of dependencies), and
o executing the Makefile.
5   Source Code Maintenance
The distribution Fortran source code for this model comes with a Makefile which
suitable for use Cray C90, Cray J90, SGI, or NEC SX4 architectures.
By examining how compilation between these various machines is handled,
it should be easy to port this code to other machines as well.
The code is written almost entirely using standard Fortran 77.