The following User's Guide is included with the model
source code. It should be
sufficient to give the user enough information run the sea ice
model in conjunction with the other components of CSM (e.g.,
detailed description of the namelist variables).
csim2.2.6 Quick Start User's Guide
------------------------------------
Note: csim2.2.6 is the CSM Sea Ice Model code for the CSM 1.2
release of July 1998.
Table of Contents:
------------------
More Detailed Information
Running csim2.2.6
Building the Executable
Model Configuration
Preprocessor Definitions
Source Code Modifications
Conceptual Flowchart
Namelist Input Variable Description
Sea Ice Climatology Mode
More Detailed Information
-------------------------
The following documentation is provided for informational purposes, and
is not intended to be complete. A description of the CSM Sea Ice Model
can be found in:
Bettge,T.W., J.W. Weatherly, W.M. Washington, D. Pollard,
B.P. Briegleb, and W. G. Strand, Jr., 1996: "The CSM
Sea Ice Model." NCAR Technical Note NCAR/TN-425+STR,
National Center for Atmospheric Research, Boulder,
Colorado.
The above document is available thru the CSM home page
(http://www.cgd.ucar.edu/csm).
Running csim2.2.6
-----------------
Building the Executable
-----------------------
It is assumed that the user has obtained the csim2.2.6 tarfile
release, and created the ./csim2.2.6 directory which contains the
source code, files needed to build the model, data input files
which are not obtained during execution (but must exist at run
time). In fact, the ability to read this file assumes the user
has done the above!
The ./csim2.2.6/run_scripts subdirectory contains two scripts,
ice.setup.csh and standalone, both of which provide details
on how the executable is build. It is recommended that one of
these scripts be used to build the ice model executable. Simply
create a directory into which you should copy one of the
scripts (presumably this will be in /usr/tmp space somewhere),
and follow the instructions within the script, modifying the
script as necessary. You will have to set an environment variable
ICE_SRC_ROOT to the location of the csim2.2.6 top-level directory.
The end result of running the script will be the creation of the
following within the directory:
(1) the ice* executable
(2) the namelist parameter file 'ice.parm'
(3) a log file with the output from this script (optional)
(4) 'mask' files from $ICE_SRC_ROOT/masks
(5) a subdirectory src/ containing the files generated
during the building of the ice executable
(6) a subdirectory mach_deps/ containing files within
which 'make' machine dependencies reside
Model Configuration
-------------------
The CSIM configuration is established via the definition of five
compilation tokens (preprocessor definitions) contained in the
file defs.h, which is created during the execution of the ice.setup.csh
script. To change the ice model configuration, the defs.h file
must be modified.
The five relevant tokens and meanings are:
(1) machine architecture
Options: CRAY, SUN, SGI
Default: CRAY
(2) CSIM resolution
Options: model2x2, model3x3, model3x3p
Default: model2x2
(3) coupled configuration
Options: FULLY_COUPLED, SAFORCE
Default: FULLY_COUPLED
(4) use of NCAR mass storage system
Options: NCARMSS, NO_NCARMSS
Default: NCARMSS
(5) clean-up (file removal when no longer used)
Options: CLEAN, MAKE_A_MESS
Default: CLEAN
The default defs.h file is:
#ifndef DEFS_SET
#define DEFS_SET
#define CRAY
#define model2x2
#define FULLY_COUPLED
#define NCARMSS
#define CLEAN
#endif
If, for example, one wishes to use the x3 model in a fully coupled
integration on the CRAY, then the line #define model2x2 must be
changed to #define model3x3 .
Complete descriptions of the preprocessor definitions follow:
TOKEN DESCRIPTION DEFAULT
----- ----------- -------
SGI, CRAY machine architecture; CRAY
(SGI refers to R10000; which
is still relatively untested)
FULLY_COUPLED, SAFORCE model configuration; either FULLY_COUPLED
standalone forcing or fully
fully coupled using message
passing (SAFORCE is used for
model code tests, and should
NOT be interpreted as if the
sea ice model can run in
standalone mode giving realistic
results)
NCARMSS, NO_NCARMSS use NCAR MSS as needed (assumes NCARMSS
msread and mswrite libraries
are available); otherwise, all
files assumed to be available
within the execution directory,
and all files produced are in
execution directory; Exception:
if NCARMSS is not defined, the
mspathr and mspathw namelist
variables can be used to specify
a full path location.
model3x3, model2x2, ice grid model2x2
model3x3p
CLEAN, MAKE_A_MESS will rm (unlink) restart dataset CLEAN
after it has been used; will rm
(unlink) save dataset after it has
been written (Warning: don't want
to CLEAN unless using CRAY *and*
NCARMSS)
Source Code Modifications
-------------------------
Source code modifications can be accomplished by copying files
from the ./csim2.2.6/src directory into ./csim2.2.6/srcnew directory,
or by adding new files to the ./csim2.2.6/srcnew directory, and
rebuilding the model. The build procedure will use the new
files when making the executable.
Conceptual Flowchart
--------------------
Sea Ice Model Driver (ice_driver.F)
o read namelist input (rdnam.F)
o read land/ocean/marginal sea mask (rdsav.F)
o read the restart dataset (rdsav.F)
o initialize communication with Flux Coupler
o loop over time
* exchange information with Flux Coupler
------- * integrate ice model
| over one time period (mdlice.F)
| * write history dataset (icecdf.F)
| * write restart dataset (wrsav.F)
|
|
|
------------------
|
|
MDLICE (mdlice.F)
o prepare data for model timestep
|
|
STEPICE (stepic.F)
------- o thermodynamics
| ----- o dynamics
| | o update surface albedo
| |
| |
| ---------------------------------------
| |
THERMODYNAMICS (thermo.F) DYNAMICS (dynice.F)
o lateral ice growth o main loop over hemispheres
o lateral ice melt o iterative solution to ice
o vertical energy balance velocities (cavset.F,
model (tice3l.F *or* ticezl.F) cavit.F, icefre.F, and
icedia.F)
o advection (advect.F)
Namelist Input Variables
------------------------
Preliminary Documentation of Sea Ice Model NAMELIST Input
---------------------------------------------------------
domain INTEGER Domain of computation. If 0, global. If
1, southern hemisphere only. If 2, northern
hemisphere only.
Example: domain = 1
Default: 0
hicenh REAL When icemode='conclim' or 'sstclim', the
ice thickness of specified ice in the
Northern Hemisphere. (meters)
Example: hicenh = 3.0
Default: 2.5
hicesh REAL When icemode='conclim' or 'sstclim', the
ice thickness of specified ice in the
Southern Hemisphere. (meters)
Example: hicesh = 0.5
Default: 1.0
histdump INTEGER Frequency of netCDF history dataset dumps,
keyed to day of month. If histdump=1,
dumps will be made every day (at end of
day). If histdump=10, dumps will be
made on days 10, 20, and 30 (except Feb!)
of month.
Examples: histdump = 30
histdump = 2
Default: 10
Note: The netCDF files produced will
be placed into the 'mspathw'
directory on the mass store. The
filename will be:
yyyymmdd.nc
where yyyymmdd is date. (This is
subject to change).
icemode CHAR Mode of the current ice model integration.
Must be one of:
'active' - full ice computations,
including both thermodynamics
and dynamics
'sstclim' - ice concentration is
specified from SST
climatology (see namelist
input variable "sstpath");
ice thickness is assigned
by "hicenh" and "hicesh";
only thermodynamics are
performed, computing a valid
ice surface temperature
'conclim' - same as 'sstclim', but uses
ice concentration climatology
(Note: in the case of
'conclim' the dataset is
assumed to be available
in the working directory
with the filename assigned
by "sstpath".)
Example: icemode = 'sstclim'
Default: 'active'
ice_dynam INTEGER Ice dynamics are active if ice_dynam is
non-zero. Ice dynamics turned off if
ice_dynam is zero.
Example: ice_dynam = 0
Default: 1 (ice dynamics are ON)
idate INTEGER Date of current restart dataset. In the
form [yyyyddmm]. If a positive value,
the date on the restart dataset is ignored
and this date is used. If negative, the
date on the restart dataset is used.
Examples: idate = 19950401
idate = -1
Default: -1
locpathr CHAR Local path of input (read) restart dataset.
Limited to 56 characters. Can be an
environment variable such as '$TMPDIR'.
Example: locpathr = '$TMPDIR'
Default: '.'
monavg INTEGER Produce monthly averaged ice netCDF
history dataset. Produced if monavg
is non-zero. No data produced if
monavg is zero. If written, the
filename on the mass store is
yyyymm00.nc For example, 00411200.nc
is the average of month 12, year 41.
Example: monavg = 0
Default: 1 (monthly averages ARE produced)
msfiler CHAR Mass store file name of input (read) restart
dataset. Limited to 56 characters.
Example: msfiler = '19950901.restart'
Default: [see Example 1]
mspathr CHAR Mass store path of input (read) restart
dataset. Limited to 56 characters.
Example: mspathr = '/SMITH/ice'
Default: '/$LOGNAME/$CASE/ice'
mspathw CHAR Mass store path of output (write) restart
dataset. Limited to 56 characters.
Examples: mspathw = '/SMITH/ice'
mspathw = '/SMITH/$CASE/ice'
Default: '/$LOGNAME/$CASE/ice'
nadv INTEGER Number of timesteps per model day.
Example: nadv = 12
Default: 72
naldays INTEGER Number of days to run the model in
"standalone" mode.
Example: naldays = 10
Default: 1
rest_pfile CHAR full pathname of the restart pointer file
located on disk; this file must exist
during a continuation run; it is
overwritten and updated everytime new
restart data files are output.
Examples: rest_pfile = './rest_pointer'
rest_pfile = '$HOME/ice/$CASE'
Default: '$HOME/ice.$CASE.rpointer'
savretpd INTEGER Mass store retention period in days for
output (write) restart dataset. Can be as
large as 4096.
Example: savretpd = 731
Default: 367
savwcomm CHAR Mass store comment associated with output
(write) restart file. Can be as long as
56 characters.
Examples: savwcomm = ' this is nonsense '
savwcomm = ' $CASE $CASESTR '
Default: ' ' (blank)
savwpass CHAR Mass store write password associated with
output (write) restart file.
Example: savwpass = 'fgump'
Default: ' ' (blank)
safpath CHAR Full mass store directory AND file pathname
to the standalone forcing file. File will
be named locally (in pwd) as 'saf.data'.
Example: sstpath =
'/BETTGE/CSM-T01/ice/B05.30dforc.ieee'
Default: ' ' (blank)
sstpath CHAR Full mass store directory AND file pathname
to the SST climatology for use when icemode=
'sstclim'. File will be named locally (in
pwd) as 'sst.climatology'. When icemode=
'conclim', sstpath is the name of a file
which must exist in pwd at run time.
Examples:
sstpath = '/KAUFF/DATA/sst.str.mom2x2'
(if icemode='sstclim')
sstpath = 'icefrac.nc'
(if icemode='conclim')
Default: ' ' (blank)
The following variables MUST be specified:
None - all the defaults will suffice in simplest case,
see example 1.
Example 1:
$SEAICE
$END
In this case, the user has specified that the restart date is
as appears on the restart dataset (idate=-1). The restart
dataset will be taken for the mass store directory
/$LOGNAME/$CASE/ice ($LOGNAME will be resolved in all upper
case, and $CASE is an environment variable which MUST be set).
Under these conditions, the ice model will access and read
the *rest_pfile*,
which contains the date (yyyymmdd) of the most recent restart
dataset (this file is updated every time a restart dataset is
generated). Thus, the restart dataset is implicitly taken to
be:
/$LOGNAME/$CASE/ice/[contents of 'rest_pfile'].restart
Also, in this case, all restart and history files will be placed
into the /$LOGNAME/$CASE/ice directory on the mass store.
This example represents a standard operating procedure during
an extended integration restart.....that is, no namelist
input needs to be updated or changed.
Example 2:
$SEAICE
, idate=19950901
, mspathr='/SMITH/CSM-xxx/ice'
, msfiler='19950901.restart'
, mspathw='/SMITH/$CASE/ice'
, savwpass='jssmith'
, savwcomm=' $CASE $CASESTR '
, savretpd=32
, icemode='active'
, histdump=10
$END
(1) The mass store restart file is /SMITH/CSM-xxx/ice/19950901.restart
(2) All restart and netcdf history files generated during the run will
be written onto the mass store in the /SMITH/$CASE/ice subdirectory.
($CASE will be resolved at run time.)
(3) Under normal circumstances, the first restart will be written at the
beginning of the next month, and will be moved to the mass store
under the pathname/filename /SMITH/CSM-xxx/ice/19951001.restart.
(4) The first history dataset generated will be placed on the mass store
under the name /SMITH/CSM-xxx/ice/19950910.nc
(6) All restart and history files written will have a password of
'jssmith', a comment ' $CASE $CASESTR ', and a retention period of
32 days on the mass store ($CASE and $CASESTR will be resolved at
run time).
Sea Ice Climatology Mode
------------------------
The Dummy Ice Model 24 October 1995
Updated: 29 February 1996
Updated: 8 April 1997
The ice model has been set up to read a climatological SST
or climatological ice concentration dataset, and produce a
climatological sea ice distribution.
Use icemode='sstclim' or icemode='conclim' in the namelist input.
Details:
When icemode='sstclim' or icemode='conclim' is set, the ice
model performs ice thermodynamic calculations only....returning
a "valid" ice surface temperature to the flux-coupler from
computations in tice3l.f. No ice dynamics are performed.
When ice is determined to exist within a grid box (using either
an SST within 1C of freezing [see (8) below] or a climatological
ice fraction), the ice thickness is set to "hicenh" in the NH and
"hicesh" in the SH.
Here is a list and description of the fields and fluxes
returned by the ice model to the flux-coupler during
'sstclim' integrations.....
(1) tsice ! ice/snow surface temperature (K)
a realistic value, consistent with
the same calculation made during an
'active' ice integration
(2) snowd ! snow depth on ice (m of equiv h2o)
a realistic value, calculated by
accumulating snow on top of the seaice
which has been specified by climatology;
same as active ice integration
(3) fwfice ! wtr flx at bot of ice[(kg/s)/m**2]
currently, is calculated as in 'active'
during ice growth and melt phases; however,
since no lateral melt occurs, and since the
seaice is specified as described in 'ficeh'
below, and held to a constant thickness of
1.0 meters, this term is *not* consistent
with any process occurring, and should be
*ignored*
(4) s4bot ! solar passing thru ice (W/m**2)
as with 'active' model, is computed
(5) h4 ! heat flx frm sno/ice melt (W/m**2)
since no lateral melt takes place
(ice is specified!), is zero
(6) uiceh ! eastward ice velocity (m/s)
(7) viceh ! northward ice velocity (m/s)
ice is specified, ice velocity is zero
(8) ficeh ! ice concentration on h-grid when
icemode='sstclim' is set as follows:
ficeh = max ( 0.0,
min(ficemax, tfreez+1.0 - SST) )
that is, ramps up linearly starting
within one degree of the freezing point
of sea water (-1.8 in the SSTs); never
greater than ficemax, which is 0.96 in
SH and 0.99 in NH (identical to 'active'
model)
(10) albsi ! ice albedo shortwave direct
(11) albli ! ice albedo longwave direct
(12) albsf ! ice albedo shortwave diffuse
(13) alblf ! ice albedo longwave diffuse
set as in active model