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

\section {Making Code Modifications} 

The source code for CSIM is located in {\bf ccsm3/models/ice/csim4/src/source}.

\begin{Ventry}{NOTE:}
\item[NOTE]
      The source code in this directory, and any code that has been checked out of
      the CVS repository should be treated as frozen code.  It is recommended that
      the permissions on these files be changed to read only.  To modify a module
      in CSIM, whether running coupled or uncoupled, first copy that module to a 
      separate directory.  If running CSIM coupled, this directory is near the 
      top of the CCSM directory tree and is called 
      {\bf ccsm3/scripts/\$YOUR\_CASE/SourceMods/src.csim}.  If running CSIM uncoupled,
      make a directory under the active ice component called \\
      {\bf models/ice/csim4/src/src.ice}.
      Make the modifications to the copied file.  The scripts are set up so that
      these directories are the last in the filepath, so the modified files are the last
      copied to the executable directory.
      This is a highly recommended programming practice, keeping your modifications
      separate from the original code.
\end{Ventry}

\subsection {Write Statements and Error Messages}

Adding write statements to source code that is using multiple processors can
produce unexpected results if not done correctly.  Generally, diagnostic write statements
should be done only by the controlling processor, called the {\tt master\_task}.  The
task number for the master processor is always zero and is set in {\it setup\_mpi}. The
master task is the only processor that can write to the log file.  If other tasks are
allowed to write to the log file, output from the master task will most likely be overwritten.
Write statements should be surrounded by an 'if' block:

\begin{verbatim}
if (my_task == master_task) then
  write (nu_diag,*) 'istep1:',istep1
endif
\end{verbatim}

Without the 'if' statement, all processors will write out the information.
Output from other processors will be written to the standard output file.

\subsubsection*{Finding Error Messages}

Errors that cause the ice model to stop do not always occur in the master task
subdomain, so there may not be information about the error in the log file.
When the model stops, look for error messages in the log files, standard output,
standard error, fort.*, and core files.  Since multiple processors are writing to
the standard output file, the error that caused the model to stop is not always right
at the bottom of the file.

\subsection {History Fields}

Adding a field to the history namelist is different than adding a field to
the history file.  If the field is already in the namelist, it can be added
or removed from the history file simply by modifying the namelist called
{\bf ice\_fields\_nml}. This is discussed in the CSIM User's Guide.

The fields that are available to the history file namelist are set in 
{\bf ice\_history.F}.  At the top of this module are instructions on
what to modify there, in the namelist in the ice setup script, and in
subroutines {\it init\_hist} and {\it ice\_write\_hist}.


\subsection {Restart Fields}

Fields that are necessary for an exact restart should be added to the
restart file.  These are binary files that are read by the ice model
for initial conditions for almost all types of runs.   There are
two subroutines in {\bf ice\_history.F} called {\it restartfile} and
{\it dumpfile} that read and write these files.  The actual reading of
the unformatted file is done by subroutine {\it ice\_read} in module
{\bf ice\_read\_write.F}.  New fields should be added to the end of the
restart file to allow backwards compatibility, i.e. older versions of
the model should be able to read the new restart file.  There is code in
{\it restartfile} that checks for the end of the file.  Currently, the
salt flux is the last field in the file.  If this field is present, it
is read in, if not, it is set to zero.  An exact restart test should be
done after modifying the restart file.  This test is automated in the
CSIM and CCSM scripts.  Adding more fields to the restart file should
only be done if required by physics changes.  It needs to be done
carefully, considering the need for backwards compatibility.
