\chapter{Checklists for setting up a model\label{cha:smr}}


\section{Standard setup\label{sec:smr_standard}}
This is a pointwise run-through of the steps needed to set up and run NERSC-HYCOM.
\subsection{Step 0. Retrieve code and compile}
You need to retrieve the code from the svn as explained in the introduction, and compile the MSCPROGS (and HYCOM\_ALL if you are the first one on the machine) utilities as explained in Section \ref{sec:MSCPROGS}

\subsection{Step 1. Configure region}
Skip this step if a region is already set up. More details can be found in
section~\ref{sec:setup_region}.
\begin{itemize}
\item Decide on a suitable region name. Suggested naming scheme is ``XXXYZ.ZZ'',
where XXX is a three letter ID which should be somewhat descriptive of the
region.  Y is a lowercase letter (a, b, c, etc) indicating minor revisions to a
model grid.  Z.ZZ is an indicator of resolution, example 0.10 for a grid with
1/10 degree resolution
\item Set up new region directory. This is best done by running the script
\file{bin/newregion.sh} under an already existing region directory. A
``template'' region directory is copied with the svn, under \\[.7em]
 \indent  \file{./hycom/HYCOM\_2.2.37/NATa1.00}
\item The \file{newRegion.sh} script can be run without arguments for quick info
on its usage. When it is finished check the file \file{REGION.src} to make sure
the variable ``R'' is set to the region name.
\item Copy the \file{regional.grid.[ab]} files, as well as the file
\file{grid.info} into the \file{topo/} subdirectory of the region directory.
These files must be created with the conformal mapping tool. Do not copy
topography files at this stage.
\end{itemize}


\subsection{Configure topographies\label{sec:smr_topo}}
After setting up a region, the next step is to set up a topography. Topographies
are usually imported from an old model run or modified locally (mainly for
nesting). See section~\ref{sec:setup_topo} for more info.
\begin{itemize}
\item Decide on a topography version number.  Typically  you should start with
00 (the one produced from grid) and work your way upwards.
\item Create or import topographies. You can either import an existing
topography or modify an existing one (for nesting):
\begin{itemize}
   \item Import an existing topography file. Topography files from old NERSC-HYCOM
   model runs have a different land value than in version 2.2, so they need to be
   modified in order to use them in v 2.2. The script \file{topo/bin/regioncopy.sh}
   should take care of that.  Run with no arguments to get info on its usage.
   \item  Or use the \file{topo/bin/nestbat.sh} script to generate a 
   topography for a nested model.  Also needs information on the model to nest
   from.
   \item Make sure that the topography is robust, that they are no island or too abrupt change in the 3 first grid cells 
  \end{itemize}
\end{itemize}


\subsection{Configure experiment}
Skip this step if a experiment is already set up. More details can be found in
section~\ref{sec:setup_expt}.
\begin{itemize}
\item Decide on a experiment number - it should be a three-digit floating point
number with one decimal digit. Examples are $01.0, 01.1, 01.2, ... , 99.8,
99.9$. 
\item The region setup process in step 1 should by default set up a experiment
directory for experiment $01.0$. The name of this default experiment directory is
``expt\_01.0''. You may use that as a starting point.
%
If you need to create a new experiment directory based on an
already existing experiment, the script \file{bin/newExpt.sh} can do this for
you. 
\item Make sure the file \file{EXPT.src} in the experiment directory reflects
the experiment number (set in variable ``X'') and that the variable ``E'' is the
same as ``X'', but without the period. As an example, if X=01.0, we would have
E=010.
\item Modify the variable ``T'' in \file{EXPT.src} to link this experiment to
one of the topography versions in the \file{topo/} subdirectory.
   \item You must also set up the \file{blkdat.input} properly. As a minimum make sure the
   variables ``iexpt'', ``idm'', ``jdm'' are set properly as weel as information about the vertical structure. ``iexpt'' must match
   the variable E in \file{EXPT.src}, ``idm'' and ``jdm'' must match those of
   \file{regional.grid.b}. For the vertical coordinate you need to chose the number of layers, the reference densities, the number of hybrid layer ...
\end{itemize}

\subsection{Configure relaxation data files}
This step sets up the data files needed to initilize the model, and for running
with climatology relaxation. See sections~\ref{sec:setup_relax} 
for more info.
\begin{itemize}
\item Look at the \file{blkdat.input} and get the value of the thflag parameter.
\item Decide on whether to use PHC or Levitus climatologies (supplied with
standard HYCOM), and call scripts \file{relax/bin/z\_phc.sh} or
\file{relax/bin/z\_levitus.sh} with the thref value as parameter. The PHC
climatology is recommended.
\item Run the script \file{relax/bin/relax.sh} to generate ocean climatologies
for HYCOM.
\item Run the script \file{relax/bin/relax\_rmu.sh} to generate a relaxation mask.
You will be asked some questions as the script runs.
\item If you use the ``old'' climatology when setting up forcing, you will need to
run the scipt \file{relax/bin/old\_lev\_nersc.sh} as well.
\end{itemize}
The cimatologies are now located in \file{relax/\$E/} where \$E corresponds to
the value of E in \file{EXPT.src}.


\subsection{Configure forcing files}
This step sets up the forcing files needed to run the model, which includes
atmospheric and river data sets, see Section~\ref{sec:setup_force}.
\begin{itemize}
\item To generate climatology forcing files, call the  script
   \file{force/bin/nersc\_clim.sh}. It is possible to generate climatologies from
   several data sets (er40, ncep etc) and keep them in the \file{force/}
   subdirectory. This is usually needed when running with climatology forcing,
   but also when using the ``INLINE\_FORCING'' CPP option in NERSC-HYCOM, see
   section~\ref{tab:CPPNERSC}.
\item To generate synoptic forcing files, call the script 
   \file{force/bin/nersc\_synoptic.sh}. The file \file{infile.in} in the experiment
   directory must be set up before running this script. Only needed if running 
   with the forcing flag ``prep'' set in \file{infile.in}.
\item To generate river forcing files, call the  script  \file{force/bin/nersc\_trip.sh}
or \file{force/bin/nersc\_rivers.sh}. The latter relies on the existence of a file
   \file{rivers.dat} in the force directory while the former will compute an estimate from an hydrological model. Only needed when running with river forcing switched on in \file{blkdat.input}.
\item To generate seawifs water type  forcing files, call the  script
   \file{force/bin/seawifs\_mon\_kpar.sh}. This is only needed if running HYCOM
   with kpar=1, set in \file{blkdat.input}.
\end{itemize}
The forcing files should now be set up in the different subdirecories of
\file{force/}.



\subsection{Configure MPI and compile\label{sec:smr_compile}}
This step sets up the MPI partitioning and compiler flags 
needed to run the model, Section~\ref{sec:setup_partit} and
section~\ref{sec:setup_code}.
\begin{itemize}
\item Set up tile partition files using the script
   \file{topo/bin/tile\_grid.sh}. This will create files in the
   \file{topo/partit/} directory. The last number in this file name is the
   number of MPI tasks that will be used.
\item Link (or copy) the \file{src\_2.2.12/} and \file{config/} files into the region directory, they
   can be found in this location on hexagon\\[.7em]
   \indent ./hycom/HYCOM\_2.2.37/CodeOnly/\\[.7em]
   Remember to keep the same directory names.
\item Copy the the build directory into the region directory, but rename it to
   \file{Build\_V2.2.12\_X{01.0}/}, where the last number is the experiment
   number (here 01.0 is the experiment number).
\item Run the script \file{setuppatch.sh} in the build directory. Input is the
   number of MPI tasks to use.  This number must match the number of MPI tasks
   in an already existing patch-file in the
   \file{topo/partit/} directory. 
\item Set up makefile configuration files, libraries and CPP flags in the file
   \file{flags} in the build directory.
\item Compile the model with ``make''
\end{itemize}
You should now have the executable in the build directory.


\subsection{Configure run-time options and run}
This step sets up the final setup of the model
forcing files needed to run the model, which includes
atmospheric and river data sets, see Section~\ref{chp:run}.
\begin{itemize}
\item Make sure that the data and scratch directories are properly set in
   \file{EXPT.src} in the experiment directory.
\item Edit the run-time configuration files \file{blkdat.input},
   \file{infile.in}, etc to make sure they are properly set up.
\item Remember that to initialize from climatology, you must create an empty
   file called  ``INIITIALIZE'' in the experiment directory. The same must be
   done when copying a restart file to another date.
\item Run the script \file{preprocess.sh} to make sure you have all the files
   necessary to run the model. If something is missing, you will be told. Make
   sure \file{preprocess.sh} runs without errors before running the model.
\item Edit the job script, set up the number of MPI and OpenMP tasks (if they
are not automatically set by the script).
\item Finally run the model by submitting the job script.
\end{itemize}

\section{Other setup options}
The standard setup, Section~\ref{sec:smr_standard}, is the bare minimum needed
to run the model. In order to run the model with more options, the following
additional steps are needed.

\subsection{Nesting (outer)\label{sec:smr_nestouter}}
To set up outer nesting  some additional steps are also needed.
here, see Section~\ref{sec:setup_topo}, Section~\ref{sec:setup_nest}, and
Section~\ref{sec:run_nestouter} for
additional info.
\begin{itemize}
\item Run the script \file{nest\_nersc/bin/nest\_outer.sh}. This will set up
   interpolation info needed when interpolating from the outer model to the
   inner model. This step can be done at any time after the topography is set up
   in the current model and the model which will receive nesting data.
\item Before starting the model make sure that the path in the file \file{nesting.in} has written permission. 
\item Switch on outer nesting in \file{infile.in}
\end{itemize}

\subsection{Nesting (inner)}
To set up inner nesting  some additional steps are needed which will be given
here, see Section~\ref{sec:setup_topo}, section~\ref{sec:setup_nest} and
Section~\ref{sec:run_nestinner} for additional info.
\begin{itemize}
\item In the  topography checklist, given in Section~\ref{sec:smr_topo}, the
   \file{nestbat.sh} script should be used. This will smooth the model topography
   towards the outer model. The newly created topography should also be used by
   setting topography version in \file{EXPT.src} in the experiment directory.
\item Run the script \file{nest\_nersc/bin/nest\_inner.sh}. This will set up
   nesting relaxation masks and ports needed when running the model. This step
   can be done at any time after the nestbat step.
\item Before starting the model, the nesting conditions must be linked or copied
   into the current experiment directory as\\[.7em]
   \indent ./nest\_R\_T/\\[0.7em]
   The values of R
   and T must match the region name and topography version of the model in this
   experiment. Note that this is the same name that the outer model will save
   nesting conditions to, see Section~\ref{sec:smr_nestouter}
\item Switch on inner nesting in \file{infile.in}
\end{itemize}


\subsection{Tidal forcing}
See Section~\ref{sec:setup_tide} for additional info.
\begin{itemize}
\item Call one of the scripts \file{tides\_nersc/bin/tide\_CSR.sh} or 
   \file{tides\_nersc/bin/tide\_FES.sh}.
\item Switch on tides in \file{infile.in}. Make sure the tidal data set matches
   what was set up in step 1 (FES or CSR).
\end{itemize}

