s_getstarted/text/getting_started.tex

% $Header: /u/gcmpack/mitgcmdoc/part3/getting_started.tex,v 1.3 2001/10/11 19:18:41 adcroft Exp $
% $Name:  $

%\section{Getting started}

In this section, we describe how to use the model. In the first
section, we provide enough information to help you get started with
the model. We believe the best way to familiarize yourself with the
model is to run the case study examples provided with the base
version. Information on how to obtain, compile, and run the code is
found there as well as a brief description of the model structure
directory and the case study examples.  The latter and the code
structure are described more fully in chapters
\ref{chap:discretization} and \ref{chap:sarch}, respectively. Here, in
this section, we provide information on how to customize the code when
you are ready to try implementing the configuration you have in mind.

\section{Where to find information}
\label{sect:whereToFindInfo}

A web site is maintained for release 1 (Sealion) of MITgcm:
\begin{verbatim}
http://mitgcm.org/sealion
\end{verbatim}
Here you will find an on-line version of this document, a
``browsable'' copy of the code and a searchable database of the model
and site, as well as links for downloading the model and
documentation, to data-sources and other related sites.

There is also a support news group for the model that you can email at
\texttt{support@mitgcm.org} or browse at:
\begin{verbatim}
news://mitgcm.org/mitgcm.support
\end{verbatim}
A mail to the email list will reach all the developers and be archived
on the newsgroup. A users email list will be established at some time
in the future.


\section{Obtaining the code}
\label{sect:obtainingCode}

If CVS is available on your system, we strongly encourage you to use it. CVS
provides an efficient and elegant way of organizing your code and keeping
track of your changes. If CVS is not available on your machine, you can also
download a tar file.

Before you can use CVS, the following environment variable has to be set in
your .cshrc or .tcshrc:
\begin{verbatim}
% setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack
% cvs login ( CVS password: cvsanon )
\end{verbatim}

You only need to do ``cvs login'' once. To obtain the source for the release:
\begin{verbatim}
% cvs co -d directory -P -r release1 MITgcmUV
\end{verbatim}

This creates a directory called \textit{directory}. If \textit{directory}
exists this command updates your code based on the repository. Each
directory in the source tree contains a directory \textit{CVS}. This
information is required by CVS to keep track of your file versions with
respect to the repository. Don't edit the files in \textit{CVS}! To obtain a
different \textit{version} that is not the latest source:
\begin{verbatim}
% cvs co -d directory -P -r version MITgcm
\end{verbatim}
or the latest development version:
\begin{verbatim}
% cvs co -d directory -P MITgcm
\end{verbatim}

\paragraph*{Conventional download method}
\label{sect:conventionalDownload}

If you do not have CVS on your system, you can download the model as a
tar file from the reference web site at:
\begin{verbatim}
http://mitgcm.org/download/
\end{verbatim}
The tar file still contains CVS information which we urge you not to
delete; even if you do not use CVS yourself the information can help
us if you should need to send us your copy of the code.

\section{Model and directory structure}

The ``numerical'' model is contained within a execution environment support
wrapper. This wrapper is designed to provide a general framework for
grid-point models. MITgcmUV is a specific numerical model that uses the
framework. Under this structure the model is split into execution
environment support code and conventional numerical model code. The
execution environment support code is held under the \textit{eesupp}
directory. The grid point model code is held under the \textit{model}
directory. Code execution actually starts in the \textit{eesupp} routines
and not in the \textit{model} routines. For this reason the top-level 
\textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,
end-users should not need to worry about this level. The top-level routine
for the numerical part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F%
}. Here is a brief description of the directory structure of the model under
the root tree (a detailed description is given in section 3: Code structure).

\begin{itemize}
\item \textit{bin}: this directory is initially empty. It is the default
directory in which to compile the code.

\item \textit{diags}: contains the code relative to time-averaged
diagnostics. It is subdivided into two subdirectories \textit{inc} and 
\textit{src} that contain include files (*.\textit{h} files) and fortran
subroutines (*.\textit{F} files), respectively.

\item \textit{doc}: contains brief documentation notes.

\item \textit{eesupp}: contains the execution environment source code. Also
subdivided into two subdirectories \textit{inc} and \textit{src}.

\item \textit{exe}: this directory is initially empty. It is the default
directory in which to execute the code.

\item \textit{model}: this directory contains the main source code. Also
subdivided into two subdirectories \textit{inc} and \textit{src}.

\item \textit{pkg}: contains the source code for the packages. Each package
corresponds to a subdirectory. For example, \textit{gmredi} contains the
code related to the Gent-McWilliams/Redi scheme, \textit{aim} the code
relative to the atmospheric intermediate physics. The packages are described
in detail in section 3.

\item \textit{tools}: this directory contains various useful tools. For
example, \textit{genmake} is a script written in csh (C-shell) that should
be used to generate your makefile. The directory \textit{adjoint} contains
the makefile specific to the Tangent linear and Adjoint Compiler (TAMC) that
generates the adjoint code. The latter is described in details in part V.

\item \textit{utils}: this directory contains various utilities. The
subdirectory \textit{knudsen2} contains code and a makefile that
compute coefficients of the polynomial approximation to the knudsen
formula for an ocean nonlinear equation of state. The \textit{matlab}
subdirectory contains matlab scripts for reading model output directly
into matlab. \textit{scripts} contains C-shell post-processing
scripts for joining processor-based and tiled-based model output.

\item \textit{verification}: this directory contains the model examples. See
section \ref{sect:modelExamples}.
\end{itemize}

\section{Example experiments}
\label{sect:modelExamples}

Now that you have successfully downloaded the model code we recommend that
you first try to run the examples provided with the base version. You will
probably want to run the example that is the closest to the configuration
you will use eventually. The examples are located in subdirectories under
the directory \textit{verification} and are briefly described below (a full
description is given in section 2):

\subsection{List of model examples}

\begin{itemize}
\item \textit{exp0} - single layer, ocean double gyre (barotropic with
free-surface).

\item \textit{exp1} - 4 layers, ocean double gyre.

\item \textit{exp2} - 4x4 degree global ocean simulation with steady
climatological forcing.

\item \textit{exp4} - flow over a Gaussian bump in open-water or channel
with open boundaries.

\item \textit{exp5} - inhomogenously forced ocean convection in a doubly
periodic box.

\item \textit{front\_relax} - relaxation of an ocean thermal front (test for
Gent/McWilliams scheme). 2D (Y-Z).

\item \textit{internal wave} - ocean internal wave forced by open boundary
conditions.

\item \textit{natl\_box} - eastern subtropical North Atlantic with KPP
scheme; 1 month integration

\item \textit{hs94.1x64x5} - zonal averaged atmosphere using Held and Suarez
'94 forcing.

\item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez
'94 forcing.

\item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
Suarez '94 forcing on the cubed sphere.

\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics, 5 layers
Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution.

\item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric
physics, 5 layers Molteni physics package. Equatorial Slice configuration.
2D (X-Z).

\item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
physics, 5 layers Molteni physics package. 3D Equatorial Channel
configuration (not completely tested).

\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers
Molteni physics package. Global configuration, 128x64x5 resolution.

\item \textit{adjustment.128x64x1}

\item \textit{adjustment.cs-32x32x1}
\end{itemize}

\subsection{Directory structure of model examples}

Each example directory has the following subdirectories:

\begin{itemize}
\item \textit{code}: contains the code particular to the example. At a
minimum, this directory includes the following files:

\begin{itemize}
\item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to the
``execution environment'' part of the code. The default version is located
in \textit{eesupp/inc}.

\item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to the
``numerical model'' part of the code. The default version is located in 
\textit{model/inc}.

\item \textit{code/SIZE.h}: declares size of underlying computational grid.
The default version is located in \textit{model/inc}.
\end{itemize}

In addition, other include files and subroutines might be present in \textit{%
code} depending on the particular experiment. See section 2 for more details.

\item \textit{input}: contains the input data files required to run the
example. At a mimimum, the \textit{input} directory contains the following
files:

\begin{itemize}
\item \textit{input/data}: this file, written as a namelist, specifies the
main parameters for the experiment.

\item \textit{input/data.pkg}: contains parameters relative to the packages
used in the experiment.

\item \textit{input/eedata}: this file contains ``execution environment''
data. At present, this consists of a specification of the number of threads
to use in $X$ and $Y$ under multithreaded execution.
\end{itemize}

In addition, you will also find in this directory the forcing and topography
files as well as the files describing the initial state of the experiment.
This varies from experiment to experiment. See section 2 for more details.

\item \textit{results}: this directory contains the output file \textit{%
output.txt} produced by the simulation example. This file is useful for
comparison with your own output when you run the experiment.
\end{itemize}

Once you have chosen the example you want to run, you are ready to compile
the code.

\section{Building the code}
\label{sect:buildingCode}

To compile the code, we use the {\em make} program. This uses a file
({\em Makefile}) that allows us to pre-process source files, specify
compiler and optimization options and also figures out any file
dependancies. We supply a script ({\em genmake}), described in section
\ref{sect:genmake}, that automatically creates the {\em Makefile} for
you. You then need to build the dependancies and compile the code.

As an example, let's assume that you want to build and run experiment
\textit{verification/exp2}. The are multiple ways and places to actually
do this but here let's build the code in
\textit{verification/exp2/input}:
\begin{verbatim}
% cd verification/exp2/input
\end{verbatim}
First, build the {\em Makefile}:
\begin{verbatim}
% ../../../tools/genmake -mods=../code
\end{verbatim}
The command line option tells {\em genmake} to override model source
code with any files in the directory {\em ./code/}.

If there is no \textit{.genmakerc} in the \textit{input} directory, you have
to use the following options when invoking \textit{genmake}:
\begin{verbatim}
% ../../../tools/genmake  -mods=../code
\end{verbatim}

Next, create the dependancies:
\begin{verbatim}
% make depend
\end{verbatim}
This modifies {\em Makefile} by attaching a [long] list of files on
which other files depend. The purpose of this is to reduce
re-compilation if and when you start to modify the code. {\tt make
depend} also created links from the model source to this directory.

Now compile the code:
\begin{verbatim}
% make
\end{verbatim}
The {\tt make} command creates an executable called \textit{mitgcmuv}.

Now you are ready to run the model. General instructions for doing so are
given in section \ref{sect:runModel}. Here, we can run the model with:
\begin{verbatim}
./mitgcmuv > output.txt
\end{verbatim}
where we are re-directing the stream of text output to the file {\em
output.txt}.


\subsection{Building/compiling the code elsewhere}

In the example above (section \ref{sect:buildingCode}) we built the
executable in the {\em input} directory of the experiment for
convenience. You can also configure and compile the code in other
locations, for example on a scratch disk with out having to copy the
entire source tree. The only requirement to do so is you have {\tt
genmake} in your path or you know the absolute path to {\tt genmake}.

The following sections outline some possible methods of organizing you
source and data.

\subsubsection{Building from the {\em ../code directory}}

This is just as simple as building in the {\em input/} directory:
\begin{verbatim}
% cd verification/exp2/code
% ../../../tools/genmake
% make depend
% make
\end{verbatim}
However, to run the model the executable ({\em mitgcmuv}) and input
files must be in the same place. If you only have one calculation to make:
\begin{verbatim}
% cd ../input
% cp ../code/mitgcmuv ./
% ./mitgcmuv > output.txt
\end{verbatim}
or if you will be making muliple runs with the same executable:
\begin{verbatim}
% cd ../
% cp -r input run1
% cp code/mitgcmuv run1
% cd run1
% ./mitgcmuv > output.txt
\end{verbatim}

\subsubsection{Building from a new directory}

Since the {\em input} directory contains input files it is often more
useful to keep {\em input} prestine and build in a new directory
within {\em verification/exp2/}:
\begin{verbatim}
% cd verification/exp2
% mkdir build
% cd build
% ../../../tools/genmake -mods=../code
% make depend
% make
\end{verbatim}
This builds the code exactly as before but this time you need to copy
either the executable or the input files or both in order to run the
model. For example,
\begin{verbatim}
% cp ../input/* ./
% ./mitgcmuv > output.txt
\end{verbatim}
or if you tend to make multiple runs with the same executable then
running in a new directory each time might be more appropriate:
\begin{verbatim}
% cd ../
% mkdir run1
% cp build/mitgcmuv run1/
% cp input/* run1/
% cd run1
% ./mitgcmuv > output.txt
\end{verbatim}

\subsubsection{Building from on a scratch disk}

Model object files and output data can use up large amounts of disk
space so it is often the case that you will be operating on a large
scratch disk. Assuming the model source is in {\em ~/MITgcm} then the
following commands will build the model in {\em /scratch/exp2-run1}:
\begin{verbatim}
% cd /scratch/exp2-run1
% ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
% make depend
% make
\end{verbatim}
To run the model here, you'll need the input files:
\begin{verbatim}
% cp ~/MITgcm/verification/exp2/input/* ./
% ./mitgcmuv > output.txt
\end{verbatim}

As before, you could build in one directory and make multiple runs of
the one experiment:
\begin{verbatim}
% cd /scratch/exp2
% mkdir build
% cd build
% ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
% make depend
% make
% cd ../
% cp -r ~/MITgcm/verification/exp2/input run2
% cd run2
% ./mitgcmuv > output.txt
\end{verbatim}


\subsection{\textit{genmake}}
\label{sect:genmake}

To compile the code, use the script \textit{genmake} located in the \textit{%
tools} directory. \textit{genmake} is a script that generates the makefile.
It has been written so that the code can be compiled on a wide diversity of
machines and systems. However, if it doesn't work the first time on your
platform, you might need to edit certain lines of \textit{genmake} in the
section containing the setups for the different machines. The file is
structured like this:
\begin{verbatim}
        .
        .
        .
general instructions (machine independent)
        .
        .
        .
    - setup machine 1
    - setup machine 2
    - setup machine 3
    - setup machine 4
       etc
        .
        .
        .
\end{verbatim}

For example, the setup corresponding to a DEC alpha machine is reproduced
here:
\begin{verbatim}
  case OSF1+mpi:
    echo "Configuring for DEC Alpha"
    set CPP        = ( '/usr/bin/cpp -P' )
    set DEFINES    = ( ${DEFINES}  '-DTARGET_DEC -DWORDLENGTH=1' )
    set KPP        = ( 'kapf' )
    set KPPFILES   = ( 'main.F' )
    set KFLAGS1    = ( '-scan=132 -noconc -cmp=' )
    set FC         = ( 'f77' )
    set FFLAGS     = ( '-convert big_endian -r8 -extend_source -automatic -call_shared -notransform_loops -align dcommons' )
    set FOPTIM     = ( '-O5 -fast -tune host -inline all' )
    set NOOPTFLAGS = ( '-O0' )
    set LIBS       = ( '-lfmpi -lmpi -lkmp_osfp10 -pthread' )
    set NOOPTFILES = ( 'barrier.F different_multiple.F external_fields_load.F')
    set RMFILES    = ( '*.p.out' )
    breaksw
\end{verbatim}

Typically, these are the lines that you might need to edit to make \textit{%
genmake} work on your platform if it doesn't work the first time. \textit{%
genmake} understands several options that are described here:

\begin{itemize}
\item -rootdir=dir

indicates where the model root directory is relative to the directory where
you are compiling. This option is not needed if you compile in the \textit{%
bin} directory (which is the default compilation directory) or within the 
\textit{verification} tree.

\item -mods=dir1,dir2,...

indicates the relative or absolute paths directories where the sources
should take precedence over the default versions (located in \textit{model}, 
\textit{eesupp},...). Typically, this option is used when running the
examples, see below.

\item -enable=pkg1,pkg2,...

enables packages source code \textit{pkg1}, \textit{pkg2},... when creating
the makefile.

\item -disable=pkg1,pkg2,...

disables packages source code \textit{pkg1}, \textit{pkg2},... when creating
the makefile.

\item -platform=machine

specifies the platform for which you want the makefile. In general, you
won't need this option. \textit{genmake} will select the right machine for
you (the one you're working on!). However, this option is useful if you have
a choice of several compilers on one machine and you want to use the one
that is not the default (ex: \texttt{pgf77} instead of \texttt{f77} under
Linux).

\item -mpi

this is used when you want to run the model in parallel processing mode
under mpi (see section on parallel computation for more details).

\item -jam

this is used when you want to run the model in parallel processing mode
under jam (see section on parallel computation for more details).
\end{itemize}

For some of the examples, there is a file called \textit{.genmakerc} in the 
\textit{input} directory that has the relevant \textit{genmake} options for
that particular example. In this way you don't need to type the options when
invoking \textit{genmake}.


\section{Running the model}
\label{sect:runModel}

If compilation finished succesfuully (section \ref{sect:buildModel})
then an executable called {\em mitgcmuv} will now exist in the local
directory.

To run the model as a single process (ie. not in parallel) simply
type:
\begin{verbatim}
% ./mitgcmuv
\end{verbatim}
The ``./'' is a safe-guard to make sure you use the local executable
in case you have others that exist in your path (surely odd if you
do!). The above command will spew out many lines of text output to
your screen.  This output contains details such as parameter values as
well as diagnostics such as mean Kinetic energy, largest CFL number,
etc. It is worth keeping this text output with the binary output so we
normally re-direct the {\em stdout} stream as follows:
\begin{verbatim}
% ./mitgcmuv > output.txt
\end{verbatim}

For the example experiments in {\em vericication}, an example of the
output is kept in {\em results/output.txt} for comparison. You can compare
your {\em output.txt} with this one to check that the set-up works.


\subsection{Output files}

The model produces various output files. At a minimum, the instantaneous
``state'' of the model is written out, which is made of the following files:

\begin{itemize}
\item \textit{U.00000nIter} - zonal component of velocity field (m/s and $>
0 $ eastward).

\item \textit{V.00000nIter} - meridional component of velocity field (m/s
and $> 0$ northward).

\item \textit{W.00000nIter} - vertical component of velocity field (ocean:
m/s and $> 0$ upward, atmosphere: Pa/s and $> 0$ towards increasing pressure
i.e. downward).

\item \textit{T.00000nIter} - potential temperature (ocean: $^{0}$C,
atmosphere: $^{0}$K).

\item \textit{S.00000nIter} - ocean: salinity (psu), atmosphere: water vapor
(g/kg).

\item \textit{Eta.00000nIter} - ocean: surface elevation (m), atmosphere:
surface pressure anomaly (Pa).
\end{itemize}

The chain \textit{00000nIter} consists of ten figures that specify the
iteration number at which the output is written out. For example, \textit{%
U.0000000300} is the zonal velocity at iteration 300.

In addition, a ``pickup'' or ``checkpoint'' file called:

\begin{itemize}
\item \textit{pickup.00000nIter}
\end{itemize}

is written out. This file represents the state of the model in a condensed
form and is used for restarting the integration. If the C-D scheme is used,
there is an additional ``pickup'' file:

\begin{itemize}
\item \textit{pickup\_cd.00000nIter}
\end{itemize}

containing the D-grid velocity data and that has to be written out as well
in order to restart the integration. Rolling checkpoint files are the same
as the pickup files but are named differently. Their name contain the chain 
\textit{ckptA} or \textit{ckptB} instead of \textit{00000nIter}. They can be
used to restart the model but are overwritten every other time they are
output to save disk space during long integrations.

\subsection{Looking at the output}

All the model data are written according to a ``meta/data'' file format.
Each variable is associated with two files with suffix names \textit{.data}
and \textit{.meta}. The \textit{.data} file contains the data written in
binary form (big\_endian by default). The \textit{.meta} file is a
``header'' file that contains information about the size and the structure
of the \textit{.data} file. This way of organizing the output is
particularly useful when running multi-processors calculations. The base
version of the model includes a few matlab utilities to read output files
written in this format. The matlab scripts are located in the directory 
\textit{utils/matlab} under the root tree. The script \textit{rdmds.m} reads
the data. Look at the comments inside the script to see how to use it.

Some examples of reading and visualizing some output in {\em Matlab}:
\begin{verbatim}
% matlab
>> H=rdmds('Depth');
>> contourf(H');colorbar;
>> title('Depth of fluid as used by model');

>> eta=rdmds('Eta',10);
>> imagesc(eta');axis ij;colorbar;
>> title('Surface height at iter=10');

>> eta=rdmds('Eta',[0:10:100]);
>> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
\end{verbatim}

\section{Doing it yourself: customizing the code}

When you are ready to run the model in the configuration you want, the
easiest thing is to use and adapt the setup of the case studies experiment
(described previously) that is the closest to your configuration. Then, the
amount of setup will be minimized. In this section, we focus on the setup
relative to the ''numerical model'' part of the code (the setup relative to
the ''execution environment'' part is covered in the parallel implementation
section) and on the variables and parameters that you are likely to change.

\subsection{\protect\bigskip Configuration and setup}

The CPP keys relative to the ''numerical model'' part of the code are all
defined and set in the file \textit{CPP\_OPTIONS.h }in the directory \textit{%
model/inc }or in one of the \textit{code }directories of the case study
experiments under \textit{verification.} The model parameters are defined
and declared in the file \textit{model/inc/PARAMS.h }and their default
values are set in the routine \textit{model/src/set\_defaults.F. }The
default values can be modified in the namelist file \textit{data }which
needs to be located in the directory where you will run the model. The
parameters are initialized in the routine \textit{model/src/ini\_parms.F}.
Look at this routine to see in what part of the namelist the parameters are
located.

In what follows the parameters are grouped into categories related to the
computational domain, the equations solved in the model, and the simulation
controls.

\subsection{Computational domain, geometry and time-discretization}

\begin{itemize}
\item dimensions
\end{itemize}

The number of points in the x, y,\textit{\ }and r\textit{\ }directions are
represented by the variables \textbf{sNx}\textit{, }\textbf{sNy}\textit{, }%
and \textbf{Nr}\textit{\ }respectively which are declared and set in the
file \textit{model/inc/SIZE.h. }(Again, this assumes a mono-processor
calculation. For multiprocessor calculations see section on parallel
implementation.)

\begin{itemize}
\item grid
\end{itemize}

Three different grids are available: cartesian, spherical polar, and
curvilinear (including the cubed sphere). The grid is set through the
logical variables \textbf{usingCartesianGrid}\textit{, }\textbf{%
usingSphericalPolarGrid}\textit{, }and \textit{\ }\textbf{%
usingCurvilinearGrid}\textit{. }In the case of spherical and curvilinear
grids, the southern boundary is defined through the variable \textbf{phiMin}%
\textit{\ }which corresponds to the latitude of the southern most cell face
(in degrees). The resolution along the x and y directions is controlled by
the 1D arrays \textbf{delx}\textit{\ }and \textbf{dely}\textit{\ }(in meters
in the case of a cartesian grid, in degrees otherwise). The vertical grid
spacing is set through the 1D array \textbf{delz }for the ocean (in meters)
or \textbf{delp}\textit{\ }for the atmosphere (in Pa). The variable \textbf{%
Ro\_SeaLevel} represents the standard position of Sea-Level in ''R''
coordinate. This is typically set to 0m for the ocean (default value) and 10$%
^{5}$Pa for the atmosphere. For the atmosphere, also set the logical
variable \textbf{groundAtK1} to '.\texttt{TRUE}.'. which put the first level
(k=1) at the lower boundary (ground).

For the cartesian grid case, the Coriolis parameter $f$ is set through the
variables \textbf{f0}\textit{\ }and \textbf{beta}\textit{\ }which correspond
to the reference Coriolis parameter (in s$^{-1}$) and $\frac{\partial f}{%
\partial y}$(in m$^{-1}$s$^{-1}$) respectively. If \textbf{beta }\textit{\ }%
is set to a nonzero value, \textbf{f0}\textit{\ }is the value of $f$ at the
southern edge of the domain.

\begin{itemize}
\item topography - full and partial cells
\end{itemize}

The domain bathymetry is read from a file that contains a 2D (x,y) map of
depths (in m) for the ocean or pressures (in Pa) for the atmosphere. The
file name is represented by the variable \textbf{bathyFile}\textit{. }The
file is assumed to contain binary numbers giving the depth (pressure) of the
model at each grid cell, ordered with the x coordinate varying fastest. The
points are ordered from low coordinate to high coordinate for both axes. The
model code applies without modification to enclosed, periodic, and double
periodic domains. Periodicity is assumed by default and is suppressed by
setting the depths to 0m for the cells at the limits of the computational
domain (note: not sure this is the case for the atmosphere). The precision
with which to read the binary data is controlled by the integer variable 
\textbf{readBinaryPrec }which can take the value \texttt{32} (single
precision) or \texttt{64} (double precision). See the matlab program \textit{%
gendata.m }in the \textit{input }directories under \textit{verification }to
see how the bathymetry files are generated for the case study experiments.

To use the partial cell capability, the variable \textbf{hFacMin}\textit{\ }%
needs to be set to a value between 0 and 1 (it is set to 1 by default)
corresponding to the minimum fractional size of the cell. For example if the
bottom cell is 500m thick and \textbf{hFacMin}\textit{\ }is set to 0.1, the
actual thickness of the cell (i.e. used in the code) can cover a range of
discrete values 50m apart from 50m to 500m depending on the value of the
bottom depth (in \textbf{bathyFile}) at this point.

Note that the bottom depths (or pressures) need not coincide with the models
levels as deduced from \textbf{delz}\textit{\ }or\textit{\ }\textbf{delp}%
\textit{. }The model will interpolate the numbers in \textbf{bathyFile}%
\textit{\ }so that they match the levels obtained from \textbf{delz}\textit{%
\ }or\textit{\ }\textbf{delp}\textit{\ }and \textbf{hFacMin}\textit{. }

(Note: the atmospheric case is a bit more complicated than what is written
here I think. To come soon...)

\begin{itemize}
\item time-discretization
\end{itemize}

The time steps are set through the real variables \textbf{deltaTMom }and 
\textbf{deltaTtracer }(in s) which represent the time step for the momentum
and tracer equations, respectively. For synchronous integrations, simply set
the two variables to the same value (or you can prescribe one time step only
through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing
parameter is set through the variable \textbf{abEps }(dimensionless). The
stagger baroclinic time stepping can be activated by setting the logical
variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'.

\subsection{Equation of state}

First, because the model equations are written in terms of perturbations, a
reference thermodynamic state needs to be specified. This is done through
the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }%
specifies the reference potential temperature profile (in $^{o}$C for
the ocean and $^{o}$K for the atmosphere) starting from the level
k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity
profile (in ppt) for the ocean or the reference specific humidity profile
(in g/kg) for the atmosphere.

The form of the equation of state is controlled by the character variables 
\textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{%
buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and
needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In
this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'.
For the ocean, two forms of the equation of state are available: linear (set 
\textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial
approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\ 
}to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the
thermal and haline expansion coefficients represented by the variables 
\textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$%
^{-1}$). For the nonlinear case, you need to generate a file of polynomial
coefficients called \textit{POLY3.COEFFS. }To do this, use the program 
\textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is
available in the same directory and you will need to edit the number and the
values of the vertical levels in \textit{knudsen2.f }so that they match
those of your configuration). \textit{\ }

\subsection{Momentum equations}

In this section, we only focus for now on the parameters that you are likely
to change, i.e. the ones relative to forcing and dissipation for example.
The details relevant to the vector-invariant form of the equations and the
various advection schemes are not covered for the moment. We assume that you
use the standard form of the momentum equations (i.e. the flux-form) with
the default advection scheme. Also, there are a few logical variables that
allow you to turn on/off various terms in the momentum equation. These
variables are called \textbf{momViscosity, momAdvection, momForcing,
useCoriolis, momPressureForcing, momStepping}\textit{, }and \textit{\ }%
\textbf{metricTerms }and are assumed to be set to '.\texttt{TRUE}.' here.
Look at the file \textit{model/inc/PARAMS.h }for a precise definition of
these variables.

\begin{itemize}
\item initialization
\end{itemize}

The velocity components are initialized to 0 unless the simulation is
starting from a pickup file (see section on simulation control parameters).

\begin{itemize}
\item forcing
\end{itemize}

This section only applies to the ocean. You need to generate wind-stress
data into two files \textbf{zonalWindFile}\textit{\ }and \textbf{%
meridWindFile }corresponding to the zonal and meridional components of the
wind stress, respectively (if you want the stress to be along the direction
of only one of the model horizontal axes, you only need to generate one
file). The format of the files is similar to the bathymetry file. The zonal
(meridional) stress data are assumed to be in Pa and located at U-points
(V-points). As for the bathymetry, the precision with which to read the
binary data is controlled by the variable \textbf{readBinaryPrec}.\textbf{\ }
See the matlab program \textit{gendata.m }in the \textit{input }directories
under \textit{verification }to see how simple analytical wind forcing data
are generated for the case study experiments. 

There is also the possibility of prescribing time-dependent periodic
forcing. To do this, concatenate the successive time records into a single
file (for each stress component) ordered in a (x, y, t) fashion and set the
following variables: \textbf{periodicExternalForcing }to '.\texttt{TRUE}.', 
\textbf{externForcingPeriod }to the period (in s) of which the forcing
varies (typically 1 month), and \textbf{externForcingCycle }to the repeat
time (in s) of the forcing (typically 1 year -- note: \textbf{%
externForcingCycle }must be a multiple of \textbf{externForcingPeriod}).
With these variables set up, the model will interpolate the forcing linearly
at each iteration.

\begin{itemize}
\item dissipation
\end{itemize}

The lateral eddy viscosity coefficient is specified through the variable 
\textbf{viscAh}\textit{\ }(in m$^{2}$s$^{-1}$). The vertical eddy viscosity
coefficient is specified through the variable \textbf{viscAz }(in m$^{2}$s$%
^{-1}$) for the ocean and \textbf{viscAp}\textit{\ }(in Pa$^{2}$s$^{-1}$)
for the atmosphere. The vertical diffusive fluxes can be computed implicitly
by setting the logical variable \textbf{implicitViscosity }to '.\texttt{TRUE}%
.'. In addition, biharmonic mixing can be added as well through the variable 
\textbf{viscA4}\textit{\ }(in m$^{4}$s$^{-1}$). On a spherical polar grid,
you might also need to set the variable \textbf{cosPower} which is set to 0
by default and which represents the power of cosine of latitude to multiply
viscosity. Slip or no-slip conditions at lateral and bottom boundaries are
specified through the logical variables \textbf{no\_slip\_sides}\textit{\ }%
and \textbf{no\_slip\_bottom}. If set to '\texttt{.FALSE.}', free-slip
boundary conditions are applied. If no-slip boundary conditions are applied
at the bottom, a bottom drag can be applied as well. Two forms are
available: linear (set the variable \textbf{bottomDragLinear}\textit{\ }in s$%
^{-1}$) and quadratic (set the variable \textbf{bottomDragQuadratic}\textit{%
\ }in m$^{-1}$).

The Fourier and Shapiro filters are described elsewhere.

\begin{itemize}
\item C-D scheme
\end{itemize}

If you run at a sufficiently coarse resolution, you will need the C-D scheme
for the computation of the Coriolis terms. The variable\textbf{\ tauCD},
which represents the C-D scheme coupling timescale (in s) needs to be set.

\begin{itemize} 
\item calculation of pressure/geopotential
\end{itemize} 

First, to run a non-hydrostatic ocean simulation, set the logical variable 
\textbf{nonHydrostatic} to '.\texttt{TRUE}.'. The pressure field is then
inverted through a 3D elliptic equation. (Note: this capability is not
available for the atmosphere yet.) By default, a hydrostatic simulation is
assumed and a 2D elliptic equation is used to invert the pressure field. The
parameters controlling the behaviour of the elliptic solvers are the
variables \textbf{cg2dMaxIters}\textit{\ }and \textbf{cg2dTargetResidual }%
for the 2D case and \textbf{cg3dMaxIters}\textit{\ }and \textbf{%
cg3dTargetResidual }for the 3D case. You probably won't need to alter the
default values (are we sure of this?).

For the calculation of the surface pressure (for the ocean) or surface
geopotential (for the atmosphere) you need to set the logical variables 
\textbf{rigidLid} and \textbf{implicitFreeSurface}\textit{\ }(set one to '.%
\texttt{TRUE}.' and the other to '.\texttt{FALSE}.' depending on how you
want to deal with the ocean upper or atmosphere lower boundary).

\subsection{Tracer equations}

This section covers the tracer equations i.e. the potential temperature
equation and the salinity (for the ocean) or specific humidity (for the
atmosphere) equation. As for the momentum equations, we only describe for
now the parameters that you are likely to change. The logical variables 
\textbf{tempDiffusion}\textit{, }\textbf{tempAdvection}\textit{, }\textbf{%
tempForcing}\textit{,} and \textbf{tempStepping} allow you to turn on/off
terms in the temperature equation (same thing for salinity or specific
humidity with variables \textbf{saltDiffusion}\textit{, }\textbf{%
saltAdvection}\textit{\ }etc). These variables are all assumed here to be
set to '.\texttt{TRUE}.'. Look at file \textit{model/inc/PARAMS.h }for a
precise definition.

\begin{itemize}
\item initialization
\end{itemize}

The initial tracer data can be contained in the binary files \textbf{%
hydrogThetaFile }and \textbf{hydrogSaltFile}. These files should contain 3D
data ordered in an (x, y, r) fashion with k=1 as the first vertical level.
If no file names are provided, the tracers are then initialized with the
values of \textbf{tRef }and \textbf{sRef }mentioned above (in the equation
of state section). In this case, the initial tracer data are uniform in x
and y for each depth level.

\begin{itemize} 
\item forcing
\end{itemize}

This part is more relevant for the ocean, the procedure for the atmosphere
not being completely stabilized at the moment.

A combination of fluxes data and relaxation terms can be used for driving
the tracer equations. \ For potential temperature, heat flux data (in W/m$%
^{2}$) can be stored in the 2D binary file \textbf{surfQfile}\textit{. }%
Alternatively or in addition, the forcing can be specified through a
relaxation term. The SST data to which the model surface temperatures are
restored to are supposed to be stored in the 2D binary file \textbf{%
thetaClimFile}\textit{. }The corresponding relaxation time scale coefficient
is set through the variable \textbf{tauThetaClimRelax}\textit{\ }(in s). The
same procedure applies for salinity with the variable names \textbf{EmPmRfile%
}\textit{, }\textbf{saltClimFile}\textit{, }and \textbf{tauSaltClimRelax}%
\textit{\ }for freshwater flux (in m/s) and surface salinity (in ppt) data
files and relaxation time scale coefficient (in s), respectively. Also for
salinity, if the CPP key \textbf{USE\_NATURAL\_BCS} is turned on, natural
boundary conditions are applied i.e. when computing the surface salinity
tendency, the freshwater flux is multiplied by the model surface salinity
instead of a constant salinity value.

As for the other input files, the precision with which to read the data is
controlled by the variable \textbf{readBinaryPrec}. Time-dependent, periodic
forcing can be applied as well following the same procedure used for the
wind forcing data (see above).

\begin{itemize}
\item dissipation
\end{itemize}

Lateral eddy diffusivities for temperature and salinity/specific humidity
are specified through the variables \textbf{diffKhT }and \textbf{diffKhS }%
(in m$^{2}$/s). Vertical eddy diffusivities are specified through the
variables \textbf{diffKzT }and \textbf{diffKzS }(in m$^{2}$/s) for the ocean
and \textbf{diffKpT }and \textbf{diffKpS }(in Pa$^{2}$/s) for the
atmosphere. The vertical diffusive fluxes can be computed implicitly by
setting the logical variable \textbf{implicitDiffusion }to '.\texttt{TRUE}%
.'. In addition, biharmonic diffusivities can be specified as well through
the coefficients \textbf{diffK4T }and \textbf{diffK4S }(in m$^{4}$/s). Note
that the cosine power scaling (specified through \textbf{cosPower }- see the
momentum equations section) is applied to the tracer diffusivities
(Laplacian and biharmonic) as well. The Gent and McWilliams parameterization
for oceanic tracers is described in the package section. Finally, note that
tracers can be also subject to Fourier and Shapiro filtering (see the
corresponding section on these filters).

\begin{itemize}
\item ocean convection
\end{itemize}

Two options are available to parameterize ocean convection: one is to use
the convective adjustment scheme. In this case, you need to set the variable 
\textbf{cadjFreq}, which represents the frequency (in s) with which the
adjustment algorithm is called, to a non-zero value (if set to a negative
value by the user, the model will set it to the tracer time step). The other
option is to parameterize convection with implicit vertical diffusion. To do
this, set the logical variable \textbf{implicitDiffusion }to '.\texttt{TRUE}%
.' and the real variable \textbf{ivdc\_kappa }to a value (in m$^{2}$/s) you
wish the tracer vertical diffusivities to have when mixing tracers
vertically due to static instabilities. Note that \textbf{cadjFreq }and 
\textbf{ivdc\_kappa }can not both have non-zero value.

\subsection{Simulation controls}

The model ''clock'' is defined by the variable \textbf{deltaTClock }(in s)
which determines the IO frequencies and is used in tagging output.
Typically, you will set it to the tracer time step for accelerated runs
(otherwise it is simply set to the default time step \textbf{deltaT}).
Frequency of checkpointing and dumping of the model state are referenced to
this clock (see below).

\begin{itemize}
\item run duration
\end{itemize}

The beginning of a simulation is set by specifying a start time (in s)
through the real variable \textbf{startTime }or by specifying an initial
iteration number through the integer variable \textbf{nIter0}. If these
variables are set to nonzero values, the model will look for a ''pickup''
file \textit{pickup.0000nIter0 }to restart the integration\textit{. }The end
of a simulation is set through the real variable \textbf{endTime }(in s).
Alternatively, you can specify instead the number of time steps to execute
through the integer variable \textbf{nTimeSteps}. 

\begin{itemize}
\item frequency of output
\end{itemize}

Real variables defining frequencies (in s) with which output files are
written on disk need to be set up. \textbf{dumpFreq }controls the frequency
with which the instantaneous state of the model is saved. \textbf{chkPtFreq }%
and \textbf{pchkPtFreq }control the output frequency of rolling and
permanent checkpoint files, respectively. See section 1.5.1 Output files for the
definition of model state and checkpoint files. In addition, time-averaged
fields can be written out by setting the variable \textbf{taveFreq} (in s).
The precision with which to write the binary data is controlled by the
integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{%
64}).