4.3 Model Input Variables

The ice model setup script contains two namelists. The first, named ice_in contains variables that control the model setup, and the second is icefields_nml, and controls the fields that are written to the history files. The latter is described in Section 4.8.3.3. The ice setup script reads the input namelists at runtime, and writes the namelist information to the file ice_in in the directory where the model executable is located. Therefore, the namelist will be updated even if the ice model is not recompiled. The variables are set to default values in ice_init.F. If they are not set in the namelist ice_in in ice.setup.csh, they will assume the default values listed in Tables 3-10 and 12, which list all available namelist parameters. Only a few of these variables are required to be set in the namelist; these values are noted in the paragraphs below. An example of the default namelist is shown in Section 4.3.2.1.

**Table 3:** Namelist Variables for Time Management
Varible	Type	Default Value	Description
`runid`	Character	'unknown_runid'	Text used in netCDF global attributes
`runtype`	Character	'unknown_runtype'	Determines if BASEDATE is received from coupler or restart file
`istep0`	Integer	0	Step counter, number of steps taken in previous integration
`npt`	Integer	99999	Total number of timesteps in a model run, model stops when istep exceeds npt (not used in coupled runs)
`dt`	Double	3600.	Timestep in seconds
`ndte`	Integer	120	Number of subcycles per timestep in ice dynamics

4.3.1.1 Namelist Variables for Time Management

The time management namelist options are shown in Table 3. runid is a character string that contains descriptive information gathered from the main setup script. This information is written to the global attributes in the history files. runtype is determined from the value of $RUNTYPE set in the main setup script. The options for this are discussed in section 4.5. istep0 is the number of steps taken in a previous integration. It is written to the restart file but is not used to initialize the time for a coupled run. The value npt is the upper limit on the number of steps allowed in a model run and is not used in a coupled run, since the point at which to stop integration is determined by the coupler.

dt is the timestep in seconds for the ice model thermodynamics and transport. The thermodynamics component is stable but not necessarily accurate for any value of the timestep. The value chosen for dt depends on the stability of the transport and the grid resolution. A conservative estimate of dt for the transport using the MPDATA advection scheme is

**Table 4:** Maximum values for ice model timestep `dt`
Grid	$min(\Delta x, \Delta y)$	$max \Delta t$
gx3	28845.9 m	4.0 hr
gx1v3	8558.2 m	1.2 hr

The ice model dynamics is subcycled ndte times per timestep so that the elastic waves are damped before the next timestep. The subcycling timestep is calculated as dte = dt/ndte and must be sufficiently smaller than the damping timescale T, which needs to be sufficiently shorter than dt

**Table 5:** Namelist Variables for Writing Output
Varible	Type	Default	Description
`diagfreq`	Integer	24	Frequency of diagnostics written (min, max, hemispheric sums) to standard output
			24 => writes once every 24 timesteps
			1 => diagnostics written each timestep
			0 => no diagnostics written
`histfreq`	Character	'm'	Frequency of output written to history file
			'D' or 'd' writes daily data
			'W' or 'w' writes weekly data
			'M' or 'm' writes monthly data
			'Y' or 'y' writes yearly data
			'1' writes every timestep
			'0' no history data is written
`hist_avg`	Logical	.true.	If true, averaged history information is written out at a frequency determined by histfreq. If false, instantaneous values rather than time-averages are written.
`dumpfreq`	Character	'y'	Frequency of restart data written to file
			'D' or 'd' writes restart files daily
			'M' or 'm' writes restart files monthly
			'Y' or 'y' writes restart files yearly
			'0' no restart data is written
`print_points`	Logical	.false.	If true, point data is printed.

4.3.1.2 Namelist Variables for Writing Output

The namelist variables that control the frequency of the model diagnostics, netCDF history files, and binary restart files are shown in Table 5. By default, diagnostics are written out once every 24 timesteps to the ascii file ice.log.$LID (see section 4.8.1). $LID is a time stamp that is set in the main script.

histfreq controls the output frequency of the netCDF history files; writing monthly averages is the default. The content of the history files is described in section 4.8.3. The value of hist_avg determines if instantaneous or averaged variables are written at the frequency set by histfreq. If histfreq is set to '1' for instantaneous output, hist_avg is set to .false. within the source code to avoid conflicts. dumpfreq controls the output frequency of the binary restart files; writing restart files yearly is the default.

If print_points is .true., ascii files are created for the locations shown in Table 6; data is written out every timestep. Additional information is written if the ocean mixed layer model within the ice model is operative. Filenames are of the form pnt.$BASEDATE.01 are created in the directory $EXEROOT/ice.

**Table 6:** Location of Point Data
Location	Latitude	Longitude
SHEBA Camp (Oct 97)	75	-145
SHEBA Camp (July 98)	78	-167
SHEBA Camp (Oct 98)	80	-165
Icelandic Sea	70	-15
Weddell Sea	-65	-40
Ross Sea	-74	-170
East Antarctica	-55	90

**Table 7:** Namelist Variables for Model Physics
Varible Name	Type	Default Value	Description
`restart`	Logical	.false.	If true, model is initialized using a restart file, if false, model is initialized using initial conditions in ice_init.F.
`kcolumn`	Integer	0	Column model flag.
			0 = off
			1 = column model (not tested or supported)
`kitd`	Integer	1	Determines ITD conversion
			0 = delta scheme
			1 = linear remapping
`kdyn`	Integer	1	Determines ice dynamics
			0 = No ice dynamics
			1 = Elastic viscous plastic dynamics
`kstrength`	Integer	1	Determines pressure formulation
			0 = (Hibler(1979)) parameterization
			1 = (Rothrock(1975)) parameterization
`evp_damping`	Logical	.false.	If true, use damping procedure in evp dynamics (not supported).
`snow_into_ocn`	Logical	.false.	If true, snow on ridged ice falls into ocean (not supported).
`advection`	Character	'mpdata2'	Determines horizontal advection scheme.
			'mpdata2' = second order advection
			'upwind' = first order advection
`grid_type`	Character	'displaced_pole'	Determines grid type.
			'displaced_pole' or 'rectangular' (not supported)

4.3.1.3 Namelist Variables for Model Physics

The namelist variables for the ice model physics are listed in Table 7. restart is always true for coupled runs since all run types begin by reading in a binary restart file. See section 4.5 for a description of the run types and sections 4.5.1.2 and 4.5.1.1 about using restart files and model generated data as initial conditions. kcolumn is a flag that will run the model as a single column if is set to 1. This option has not been thoroughly tested and is not supported.

kitd determines the scheme used to redistribute sea ice within the ice thickness distribution (ITD) as the ice grows and melts. The linear remapping scheme is the default and approximates the thickness distribution in each category as a linear function ((Lipscomb(2001))). The delta function method represents g(h) in each category as a delta function ((Bitz et al.(2001))). This method can leave some categories mostly empty at any given time and cause jumps in the properties of g(h).

kdyn determines the ice dynamics used in the model. The default is the elastic-viscous-plastic (EVP) dynamics (Hunke and Dukowicz(1997)). If kdyn is set to 0, the ice dynamics is inactive. In this case, ice velocities are not computed and ice is not transported. Since the initial ice velocities are read in from the restart file, the maximum and minimum velocities written to the log file will be non-zero in this case, but they are not used in any calculations.

The value of kstrength determines which formulation is used to calculate the strength of the pack ice. The (Hibler(1979)) calculation depends on mean ice thickness and open water fraction. The calculation of (Rothrock(1975)) is based on energetics and should not be used if the ice that participates in ridging is not well resolved.

evp_damping is used to control the damping of elastic waves in the ice dynamics. It is typically set to .true. for high-resolution simulations where the elastic waves are not sufficiently damped out in a small timestep without a significant amount of subcycling. This procedure works by reducing the effective ice strength that's used by the dynamics and is not a supported option.

The value of snow_into_ocean determines what happens to the snow on ice that is ridged. The default value is .false., so the snow cover remains on the ridged ice. If snow_into_ocean is .true., then the snow on ice that undergoes ridging is put into the ocean. This may cause a problem with the fresh water budgets; this is not a supported option.

advection determines the advection scheme used. The default is mpdata, which is second order accurate, but more computationally expensive. The upwind scheme is only first order accurate.

For coupled runs, both supported grids (gx3 and gx1v3) are 'displaced_pole'. The 'rectangular' option for a regular grid with constant latitude and longitude spacing is not supported.

**Table 8:** Namelist Variables for File Names
Varible	Type	Default Value	Description
`grid_file`	Character	'data.domain.grid'	Input filename containing grid information.
`kmt_file`	Character	'data.domain.kmt'	Input filename containing land mask information.
`pointer_file`	Character	'ice.restart_file'	Pointer file that contains the name of the restart file.
`incond_dir`	Character	' '	Directory where netCDF initial condition file is output.
`restart_dir`	Character	' '	Directory where restart files are output.
`history_dir`	Character	' '	Directory where history files are output.
`incond_file`	Character	'incond'	Root name of netCDF output initial condition file.
`dump_file`	Character	'iced'	Prefix for output file containing restart information.
`history_file`	Character	'iceh'	Root name of history files.
`mss_dir`	Character	'null'	Directory on NCAR MSS where history and restart files will be written.
`mss_rtpd`	Integer	365	MSS retention period in days.
`mss_pass`	Character	' '	MSS password.
`mss_rmlf`	Integer	0	If true (=1), local files will be removed after being written to MSS.

4.3.1.4 Namelist Variables for File Names

The namelist parameters listed in Table 8 are for initial condition, restart, and history file and directory information. Information for NCAR MSS access is also in Table 8. During execution, the ice model reads grid and land mask information from the files grid_file and kmt_file that should be located in $EXEDIR. There are commands in ice.setup.csh that copy these files from the input data directory to $EXEDIR, rename them from global_$ICE_GRID.grid and global_$ICE_GRID.kmt to the default filenames shown in Table 8.

The namelist variable pointer_file is set to the name of the pointer file that contains the name of the restart file that will be read when model execution begins. This file resides in the $SCRIPTS directory and is created initially by the ice setup script but is overwritten every time a new restart file is created. It will contain the name of the latest restart file. The default filename ice.restart_file shown in Table 8 will not work unless some modifications are made to the ice setup script and a file is created with this name and contains the name of a valid restart file; this variable must be set in the namelist. More information on restart pointer files can be found in section 4.8.2.1.

incond_dir, restart_dir and history_dir are the directories where the initial condition file, the restart files and the history files will be written, respectively. These values are set at the top of the ice setup script and have been modified from the default values to meet the requirements of the CCSM2.0 filenaming convention. This allows each type of output file to be written to a separate directory. If the default values are used, all of the output files will be written to $EXEDIR.

incond_file, dump_file and history_file are the root filenames for the initial condition file, the restart files and the history files, respectively. These strings have been determined by the requirements of the CCSM2.0 filenaming convention, so the default values listed in Table 8 are not the same as those shown in Section 4.3.2.1. See sections 4.8.2 and 4.8.3 for an explanation of how the rest of the filename is created.

The namelist variables that contain the string 'mss' determine if ice model output files will be written to the NCAR MSS and where they will be stored. Currently, the ice model has the capability to write only initial condition, history and restart files to MSS. The ice.log.$LID files are also written to MSS, but not via the ice model. The data harvester (see CCSM2.0 User's Guide) will write these files to a /logs directory. If the first four characters of mss_dir are set to 'null', no ice model output is written to MSS. If mss_dir is not set in the namelist, it will be set to the default value of 'null' in the ice model. As shown in example 1, mss_dir takes the value of $MSSDIR that is set in the main setup script. The MSS retention period mss_rtpd and password mss_pass are also set in the main script. If mss_rmlf is set to 1, each time a new history file is written to MSS, the previous history file is removed from $EXEDIR/hist.

**Table 9:** Namelist Variables for Prescribed Ice Model
Varible Name	Type	Default Value	Description
`prescribed_ice`	Logical	.false.	If true, run model with prescribed ice data.
`prescribed_ice_file`	Character	'prescribed_ice.nc'	Name of file with prescribed ice data.
`prescribed_ice_climatology`	Logical	.true.	If true, use AMIP climatology for prescribed ice model.

4.3.1.5 Namelist Variables for Prescribed Ice Model

The namelist variables for the prescribed ice model are shown in Table 9. As shown in the section 4.3.2.1, all of these variables are set via environment variables in the ice setup script. To run the prescribed ice model, $PRESCRIBED_ICE must be set to true at the top of ice.setup.csh. There are commands in ice.setup.csh that set $PICE_DATA to the name of the file containing the Atmospheric Model Intercomparison Project (AMIP) ice concentration data, and copy this file from the input data directory to $EXEDIR. The default filename prescribed_ice.nc shown in Table 9 will not work unless modifications are made to the ice setup script. If $PRESCRIBED_ICE_CLIM is set to true, the model will use a single annual cycle of monthly averaged climatological AMIP data repeatedly. If this parameter is set to false, the model will use a 19 year time series of monthly averaged AMIP observations. More details on how to set up the prescribed ice model and the input data can be found in sections 3.5 and 4.6.6.

**Table 10:** Namelist Variables for Ocean Mixed Layer Model
Varible Name	Type	Default Value	Description
`oceanmixed_ice`	Logical	.false.	If true, run model with ocean mixed layer model.
`oceanmixed_ice_file`	Character	'oceanmixed_ice.nc'	Name of file with ocean mixed layer data.
`oceanmixed_ice_sst_init`	Logical	.false.	If true, Jan 1 sst is read from forcing file.
`prntdiag_oceanmixed`	Logical	.false.	If true, print ocean mixed layer diagnostics.

4.3.1.6 Namelist Variables for Ocean Mixed Layer Model

The namelist variables for the ocean mixed layer model within the ice model are shown in Table 10. To use the slab ocean model, $OCEANMIXED_ICE must be set to true at the top of ice.setup.csh. There are commands in ice.setup.csh that will copy the grid dependent forcing file from the input data directory to $EXEDIR and rename it oceanmixed_ice.nc. If $OML_ICE_SST_INIT is set to true at the top of ice.setup.csh, the model will read the Jan 1 sea surface temperature from the forcing file. If this parameter is set to false, the model will read sea surface temperature and the freeze/melt potential from a restart file. More details on how to set up the slab ocean mixed layer model can be found in section 4.6.7.

4.3.2 Example Namelists

The following example is the default namelist taken directly from ice.setup.csh. Most of the variables in the namelist are determined from environment variables set in the main setup script (see Table 1) or prior to the namelist in the ice setup script (Table 2). Variables that are commonly changed directly in the namelist are the timestep dt and the number of subcycles per timestep in the ice dynamics ndte.

The second namelist controls what variables are written to the history file. The logical variables shown in this example are input variables from the atmosphere and ocean. Due to the reduced size of the buffer being sent to and received from the coupler, the values in these fields are not known everywhere, so they are not currently written to the history file. These fields can be retrieved from the ocean or atmosphere history files.