% Running the Model

\chapter{Running the Model}
\label{chap:execute}

The first step in running TIMCOM is to specify input data for the program 
\textbf{\mbox{prep.f90}}, which prepares coordinate structure and
reference data for TIMCOM. 

Bathymetry, wind stress, temperature and salinity data 
are read and interpreted with subroutines: \textbf{\mbox{inmet.f90}}, 
\textbf{\mbox{indata.f90}}, often 
from DBDB5 (Digital Bathymetric Data Base at 5 minute resolution) or
Etopo5 (5-Minute Gridded Global Relief Data Collection ) global 
bathymetry data sets, Hellerman or COADS (Comprehensive Ocean-Atmosphere Data 
Set) winds, and Levitus or Yashayaev annual cycle temperature and salinity 
climatology, respectively. 

Open lateral boundary data may also be specified by \textbf{\mbox{prep.f90}}. A 
common practice 
is to nudge model surface temperature\citep{Haney71} and salinity toward data 
from Levitus climatology; the model uses a better approach \citep{Dietrich04b}. 
Open lateral boundary data is stored in the aforementioned ghost zones, and 
often comes from Levitus climatology. 

Next, compile and run \textbf{\mbox{prep.f90}}, which is documented by extensive 
internal 
comments that explain its variables and the sequential steps used to generate 
initial and boundary condition data. After running \textbf{\mbox{prep.f90}}, one 
simply compiles and runs the TIMCOM model. For user’s convenience, 
we wrote a script file {\bf run.sh} to automate these 
commands. Once the configuration is done, simply carry out \textbf{\mbox{run.sh}} 
to launch the model.

Basic instruction will be introduced in this chapter. We have two step-by-
step examples of running TIMCOM. First time users can run the code first and 
then come back to this section for more I/O details. 

For detailed running instruction from ground up, 
please refer to Appendix~\ref{app:running}.

\section{Getting Started}

This section describes how to use the TIMCOM ocean model by two examples, 
which are numerical simulation of island 
wakes in the ocean\citep{Dietrich96} and a three dimensional gravity plume 
on a continental slope\citep{Tseng06b}. Step-by-tep tutorial
is also provided. The best way to familiarize 
yourself with the model is to run these two cases directly. Information on how 
to obtain, compile and run the code is found here. 

\subsection{Obtain the Code}
 
You can download the two examples from the following website 

\noindent {\it http://efdl.as.ntu.edu.tw/research/TIMCOM/} 

As a courtesy we ask you to send email to us at yhtseng@stanfordalumni.org to 
enable us to keep track of who's using the model in what application.

\subsection{Configuration}

\noindent {\bf precfg.txt } \\

Some initializing parameters controlling how the model run are defined in 
{\bf init\_var.f90}, and their values are managed by user and stored in 
\mbox{{\bf precfg.txt}}. 
When the model is launched, it automatically read in these initializing 
parameters from {\bf precfg.txt}, which provide the means for user to customize
his own model. Configure this file is the first step to run a new model. \newline

\noindent {\bf run.sh   }  \\

TIMCOM program needs to know more beside variable name and initial value. 
A working 
direction is where the whole model source files and configuration files reside. 
Full path indicating where climatological data files are located are also 
specified by editing {\bf run.sh}. When the model is running, it reads and 
writes temporary files in a structured directory tree. 
In where to store the output data is up to the user’s specification.

User needs to edit {\bf run.sh} to specify these informations. \newline

\subsection{Compilation and Running} 

TIMCOM is a complex and large scale system, new features will also be added 
consequently in the future. For coding and maintenance convenience, it is 
separated into multiple parts, each of which is located in separated source 
files. 

Makefile is used to manage the dependence between each part and the dependence 
between source file and derived executable file. It make the running easier and 
of more efficience.

After configuration, just carry out run.sh to make the model run.

\section{Numerical Simulation of Island Wakes}

\subsection{Description}
 
The two dimensional, hydrostatic TIMCOM ocean model simulates the idealized 
oceanic flow around small islands patterned after Barbados, W. I.
\citep{Dietrich96}. 
The effects of vortex shedding and wake patterns can be examed by 
changing the Reynolds number. The velocity and vorticity fields are illustrated 
in Figure 4.1 at day 180. 

\begin{figure}[htbp]
\centerline{\scalebox{.7}{\includegraphics{FIGS/Island_Wake.eps}}}
\caption{(a) The velocity field at day 180 for resolution $80 \times 80$. (b) The 
vorticity field at day 180 for resolution $80 \times 80$.}
\label{fig:Island_Wake}
\end{figure}

\subsection{Running the Code}
\label{sec:wakerun}
\bn
 
\item Unzip the {\bf TIMCOMxx.tar.gz} file. It will automatically create a 
directory called TIMCOMXX by typing:
 
{\bf tar -xzvf TIMCOM.tar.gz (UNIX)}
 
At this point, we have 2 versions of TIMCOM, one is a global model called 
TIMCOMGLO with a file name {\bf TIMCOMGLO.tar.gz}, the other is a 2-domain 
couple model called TIMCOMNPNT with file name {\bf TIMCOMNPNT.tar.gz}.
Upon finishing unzipping, directory {\bf \mbox{TIMCOMXX}} is created automatically, which is 
the home directory of TIMCOM.

\item Edit {\bf run.sh}

This is an executable script file. Before running, TIMCOM need to know the 
directory name where the model source files reside, the name and path of 
bathymetry, salinity, temperature and wind stress data files must be specified 
by the user. 

By specifying path for climatological data and carrying out {\bf run.sh}, all 
consequent steps are completed automatically. A fraction of {\bf run.sh} 
is shown below to demostrate the path setting. \newline

{\bf \#!/bin/bash}

{\bf TIMCOMGLO='/home/yhtseng/RESEARCH/TIMCOMGLO'}

{\bf DIR\_BATHY=\$TIMCOMGLO/DATA/Etopo}

{\bf DIR\_ST=\$TIMCOMGLO/DATA/Levitus}  

{\bf DIR\_WS=\$TIMCOMGLO/DATA/Hellerman} \newline

The configuration is self-explaioned. 
In this sample case, the root directory of TIMCOM is set to 
{\bf \mbox{/home/yhtseng/RESEARCH/TIMCOMGLO}}, while Etopo, Levitus and
Hellerman data are located under the subdirectory {\bf DATA}.

\item Run the model: 

Once configuration described in step 2 is complete, carry out {\bf run.sh} 
to trigger the sequences:

\bn 
\item Create directory tree

\item Call the make process, compile source files

\item Carry out TIMCOM.
\en

According to user defined configuration, TIMCOM initialize control parameters, 
generate grid coordinate, read salinity/temperature and wind stress data, 
generate boundary conditions, and begin computation until time limitation
is reached.

\item If the program runs well, it will generate a file call KBVIEW and four 
necessary data under directory {\bf TIMCOMXX/EXAMPLE/CASE1/TEMP/}. The
{\bf KBVIEW} 
provides the grid information and resolution etc. 

\item The code should be done within 5 mins for a 180 days simulation in modern 
computers. You can compare your output.txt with the example run under directory 
{\bf TIMCOMXX/EXAMPLE/CASE1/TEMP/}.

\en 

\subsection{Viewing the Results}
\label{sec:wake_view_result}
 
There are two way to view the results quickly. Using MATLAB, or, you can 
view the results immediately on your computers using gv or ghostview (see 
Chapter 4 for the information). 

\bn
\item Using the existing plotting program and {\bf gv}:  

You can view the results directly under directory OUTPUT/XYPLOTS/ by typing the 
following commands: 

{\bf \% cd XYPLOTS} 

{\bf \% f77 plot0.f -o plot0 }

{\bf \% ./plot0} 

{\bf \% f77 plots.f -o plots} 

{\bf \% ./plots} 

The above steps will generate a large ps file called {\bf ps.dat}. Just use your 
ghostview to read it by typing 

{\bf \% gv ps.dat} or {\bf \%ghostview ps.dat} 

You should be able to see the results immediately. 

\item Using MATLAB commercial software:
 
You can download the MATLAB script from the following website 
{\it http://efdl.as.ntu.edu.tw/research/TIMCOM/matlab.html}. This file includes 
all necessary files and directories you need. You will see file name starting 
with {\bf plot\_data\_*.m} and a subdirectory {\bf matlab}. For island wakes 
problem, just run the file {\bf plot\_data\_ile.m} and you will get the results 
immediately. 

\en

\section{Three Dimensional Density Current over a Continental Slope}

\subsection{Description}
 
The TIMCOM model is applied to the DOME (Dynamics of Overflow Mixing and 
Entrainment) experiment. A $1100Km$ (longitude) by 400 km (latitude) region is 
modeled ~\ref{fig:Slope}. The uniform vertical and horizontal resolution is 100  m 
and $10Km$, respectively. The northernmost latitude is $500m$ deep. A 1\% shelf 
slope brings it to maximum depth 2200m at the latitude $17/40$ of the total width 
% Figure required!
to a closed southern boundary (Figure ~\ref{fig:Slope} (b)). The depth is uniformly 2200 m 
further south. This domain is the same as the high resolution experiment Z4 in 
\citet{Ezer04a}. Inflow is imposed from the northern boundary, patterned 
after the Denmark Strait (Figure ~\ref{fig:Slope} (a)). 

\begin{figure}[htbp]
\centerline{\scalebox{.7}{\includegraphics{FIGS/Slope.eps}}}
\caption{(a) The horizontal domain and northern inflow velocity vector at the 
bottom. (b) Illustration of latitudinal/vertical grid and initial temperature 
stratification.}
\label{fig:Slope}
\end{figure}


The northern inflow is bottom concentrated and geostrophically balanced. The 
bottom layer (at depth 500-600 m) inflow temperature increases linearly from 
$5.3\,^{\circ}\mathrm{C}$ on its west side to $9.9\,^{\circ}\mathrm{C}$ on its 
east 
side. The top layer inflow temperature increases linearly from 
$13\,^{\circ}\mathrm{C}$ on its west side to $15\,^{\circ}\mathrm{C}$ on its 
east side. The 
inflow is bottom-concentrated, with a total of $4.98Sv$(1 Sverdrup=$10^6m^3/s$) 
inflow. Initial conditions are identical to the DOME conditions used by \citet{
Ezer04a} and \citet{Ezer04b}. The eastern and southern boundaries are closed. 
The 
western boundary is open, using upwind-based outflow conditions modified to give 
no net inflow into the modeled region. For simplicity, we use constant 
horizontal viscosity ($v$) and diffusivity ($k$) of $50$ and $10m^2/s$, 
respectively, and a modified \citet{Pacanowski81} Richardson-number based 
vertical viscosity and diffusivity (background values of $0.1cm^2/s$). These 
conditions give typical cell Reynolds number $O(100$). Resolutions is $10km$ 
horizontal resolution with $100m$ vertical resolution. The users can double\/
change that resolution using the same boundary conditions, viscosity and 
diffusivity. 

For detailed modeled results and viscosity sensitivity, please refer to 
\citet{Tseng06b}

\subsection{Running the Code}
 
Follow the same procedures as in section \ref{sec:wakerun}.  

\bn

\item Unzip the {\bf DENSITY.tar.gz} (UNIX) or {\bf DENSITY.zip} (WINDOWS) file.
It will automatically create a directory called {\bf DENSITY\_CURRENT} by 
typing:
 
{\bf \% tar -xzvf DENSITY.tar.gz (UNIX)} 

\item Specify working directory in {\bf run.sh}.
 
\item Run: 

{\bf \% ./run.sh}

\en 
 
\subsection{Viewing the Results}
 
There are two way to view the results quickly. See section \ref{sec:wake_view_result} 
for the procedures. 



\newpage