%=======================================================================
% CVS: $Id: ice_module_desc.tex 5 2005-12-12 17:41:05Z mvr $
% CVS: $Source$
% CVS: $Name$
%=======================================================================

\subsection {CSIM Module Descriptions}
\label{sec:csim_dir_structure}

The ice model uses {\bf \textsl{ProTex}}, which is a tool for self-documenting source code.
ProTex is a perl script that produces a LaTeX compatible document from 
Fortran source code that contains a ProTex prologue at the top of each module,
function and subroutine. The output from ProTex can be over 100 pages, and
make files and build scripts would not be included in any documentation
created by the ProTex tool.  In light of this, the ice model source code and
the build scripts are described briefly in this section.  There is additional
information in the code at the top of each module, subroutine and function. 

\begin{description}
  \item [csim4/src/csim.setup.csh] compiles the uncoupled ice model and prestages
                             the input data, contains the namelist, used
                             by {\bf csim\_run}
  \item [csim4/src/csim\_run] runs the uncoupled ice model
  \item [csim4/src/IBM\_tests] runs debug and exact restart tests on the {\bf \textsl{NCAR}}
                  IBM for the uncoupled ice model
  \item [csim4/src/bld/Macros.OS] macro definitions for supported operating systems, 
                            used by {\bf Makefile}
  \item [csim4/src/bld/makdep.c] perl script that determines module dependencies
  \item [csim4/src/bld/Makefile] builds the uncoupled ice model
  \item [csim4/src/input\_templates/ice\_model\_size.F.*] input files prestaged by 
                               {\bf csim.setup.csh} depending on the grid dimensions
                               and number of ice thickness categories set in this file.
\end{description}

Below is a list of one-line descriptions for the ice model modules from {\bf csim4/src/source}.

\begin{description}
  \item [ice.F]                     main program 
  \item [ice\_albedo.F]             albedo parameterization
  \item [ice\_atmo.F]               stability-based parameterization for calculating
                                        turbulent ice-atmosphere fluxes
  \item [ice\_calendar.F]           time manager
  \item [ice\_constants.F]          parameters, physical and numerical constants
  \item [ice\_coupling.F]           interface with flux coupler
  \item [ice\_diagnostics.F]        diagnostic and debugging routines
  \item [ice\_domain.F]             {\bf \textsl{MPI}} subdomain sizes and parallel processing info
  \item [ice\_dyn\_evp.F]           elastic-viscous-plastic dynamics component
  \item [ice\_exit.F]               aborts the model and prints error message
  \item [ice\_fileunits.F]          unit numbers for I/O
  \item [ice\_flux.F]               fluxes needed/produced by the model
  \item [ice\_flux\_in.F]           routines to read and interpolate forcing for stand-alone ice model
  \item [ice\_grid.F]               grids and land masks
  \item [ice\_history.F]            netCDF output routines and read/write restart
  \item [ice\_init.F]               namelist and initializations
  \item [ice\_itd.F]                utilities for managing ice thickness distribution
  \item [ice\_itd\_linear.F]        linear remapping for transport in thickness space
  \item [ice\_kinds\_mod.F]         definitions of reals, integers, etc.
  \item [ice\_mechred.F]            mechanical redistribution (ridging)
  \item [ice\_model\_size.F]        grid size, number of thickness categories and vertical layers
  \item [ice\_mpi\_internal.F]      utilities for internal MPI parallelization
  \item [ice\_ocean.F]              slab ocean mixed layer model
  \item [ice\_prescribed.F]         prescribed ice (not supported in this release)
  \item [ice\_read\_write.F]        utilities for reading/writing files
  \item [ice\_scaling.F]            ice-area scaling of fluxes sent to coupler
  \item [ice\_state.F]              arrays defining ice state 
  \item [ice\_therm\_itd.F]         thermodynamics changes mostly due to ITD (post-coupling)
  \item [ice\_therm\_vertical.F]    vertical growth rates and fluxes (pre-coupling thermodynamics)
  \item [ice\_timers.F]             timing routines 
  \item [ice\_transport\_mpdata.F]  horizontal advection via MPDATA or upwind
  \item [ice\_transport\_remap.F]   horizontal advection via incremental remapping
  \item [ice\_work.F]               globally accessible work arrays
\end{description}
