% Main program and subroutines

\chapter{TIMCOM Subroutines}
\label{app:subroutines}

In chapter \ref{chap:structure}, we have described some subroutines. Here we 
present more detailed listings of the TIMCOM subroutines of TIMCOM.
 
\section{Subroutines Called by prep.f90} 

Program {\bf prep.f90} is the preprocessor for TIMCOM. It resides in directory 
{\bf CODE}, sets all scalar and array parameters and writes them to output 
files that are read by TIMCOM. The user may write his own program(s) or 
subroutines to create surface forcing, open lateral boundary and depth data 
files. The subroutines called in {\bf prep.f90} are: 

\begin{description}

\item[PROGRAM PREP] is the main program of {\bf prep.f90}. It opens input and 
output data files and controls the initialization process. 

\item[SUBROUTINE PRE] is the preprocessor for the elliptic rigid lid EVP 
pressure solver. It generates influence coefficient and inverse matrix data for 
the EVP solver. 

\item[SUBROUTINE INITFS] initializes all controlling arrays and also some 
derived scalar control parameters. 

\item[SUBROUTINE BOUNDS] is used to derive thermal winds on the logigically 
rectangular model domain boundaries from Levitus climatology and uses this to 
derive normal inflow velocities. 

\item[SUBROUTINE POISOL] is used to fill in $T$ and $S$ values at points not 
included in Levitus climatology. The model grid might not have the same 
resolution as Levitus climatology. Also, there is a mismatch between Levitus 
climatology and bottom topography data resolutions (great savings would be 
achieved if someone would fix this). POISOL can be used to fill in the missing 
data. 

\end{description}

\section{Subroutines Called in the Model}
 
TIMCOM reads output files from {\bf prep.f90} which specify initial and 
boundary conditions and other model parameters. Although it is often possible to 
specify all controlling data in {\bf prep.f90}, it is sometimes desirable to 
modify TIMCOM slightly in order to implement special boundary treatments for 
certain problems. 

\begin{description}

\item[PROGRAM TIMCOM] controls the flow of the calculation (and the calculation of 
the flow). Input and output files are opened; model initialization, time 
marching, and graphics output subroutines are called; and optionally restart 
data is saved at specified intervals. Restarts are seamless. 

\item[SUBROUTINE FS] is called by the {\bf MAIN PROGRAM} to march one time step 
each time it is called. 

\end{description}

\noindent The following four subroutines are called optionally by 
\mbox{{\bf SUBROUTINE FS}}, allowing the user to determine the level of physics 
desired. 

\begin{description}

\item[SUBROUTINE DIFUSE] adds turbulence contributions to the vertical momentum, 
heat, and salinity diffusivities. The diffusivities are composed of this 
optional part plus a user-specified background value plus a part determined by 
the user-specified vertical cell Reynolds number. 

\item[SUBROUTINE WIND] adds wind forcing to the top layer. 

\item[SUBROUTINE HEAT] adds surface heat flux to the top layer, normally from 
air-sea exchanges. 

\item[SUBROUTINE SUN] adds radiative heating effects distributed vertically 
according to a user specified vertical profile array. 

\item[SUBROUTINE FSPLTS] is called by the {\bf MAIN PROGRAM} in order to save 
data for the standard output fields at user specified intervals. Data is saved 
for the three basic kinds of cross-sections ($X-Y$, $X-Z$ and $Y-Z$), each 
at specified intervals in the respective third direction. These include 
barotropic streamfunction (calculated diagnostically only for graphics output), 
vorticity, pressure, velocity, temperature, salinity and others. 

\item[SUBROUTINE COMXY] is called by the {\bf MAIN PROGRAM} to generate output 
data for animations, optionally. 

\end{description}

\noindent The following three subroutines are called by {\bf SUBROUTINE FSPLTS} 
to save data for ploting.

\begin{description}
 
\item[SUBROUTINE XYPLOT] saves horizontal plots data.
 
\item[SUBROUTINE XZPLOT] saves vertical-longitudinal cross-section plots.
 
\item[SUBROUTINE YZPLOT] saves vertical-latitudinal cross-section plots.
 
\item[SUBROUTINE RANGE] determines the maximum and minimum of the input field 
data. 

\item[SUBROUTINE REP] solves the Poisson equation for the rigid lid surface 
pressure using the EVP method. 

\item[SUBROUTINE INITFS] is called by the {\bf PROGRAM TIMCOM} to read input data 
files from the preprocessor program PREP.F and do other initialization and 
optional restart functions. 

\end{description}

\newpage