User's Guide to the NCAR CSM Sea Ice Model Version 2.2.6

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