s_examples/deep_convection/convection.tex

\section{Surface Driven Convection}
\label{www:tutorials}
\label{sect:eg-bconv}
\begin{rawhtml}
<!-- CMIREDIR:eg-bconv: -->
\end{rawhtml}
\begin{center}
(in directory: {\it verification/tutorial\_deep\_convection/})
\end{center}

\bodytext{bgcolor="#FFFFFFFF"}

%\begin{center} 
%{\Large \bf Surface driven convection}
%
%\vspace*{4mm}
%
%\vspace*{3mm}
%{\large Dec 2001}
%\end{center}

\begin{figure}
\begin{center}
 \resizebox{7.5cm}{5.5cm}{
   \includegraphics*[0.2in,0.7in][10.5in,10.5in]
   {part3/case_studies/doubly_periodic_convection/simulation_config.eps} }
\end{center}
\caption{Schematic of simulation domain 
for the surface driven convection experiment. The domain is doubly periodic
with an initially uniform temperature of 20 $^oC$. 
}
\label{FIG:eg-bconv-simulation_config}
\end{figure}

This experiment, figure \ref{FIG:eg-bconv-simulation_config}, showcasing MITgcm's non-hydrostatic 
capability, was designed to explore 
the temporal and spatial characteristics of convection plumes as they might exist during a 
period of oceanic deep convection. The files for this experiment can be found in the verification
directory under tutorial\_deep\_convection. It is

\begin{itemize}
\item non-hydrostatic 
\item doubly-periodic with cubic geometry
\item has 50 m resolution 
\item Cartesian  
\item is on an $f$-plane 
\item with a linear equation of state 
\end{itemize}

\subsection{Overview}
\label{www:tutorials}

The model domain consists of an approximately 3
km square by 1 km deep box of initially
unstratified, resting fluid. The domain is doubly periodic. 

The experiment has 20 levels in the vertical, each of equal thickness $\Delta z =$ 50
m (the horizontal resolution is also 50 m). The fluid is initially unstratified with a
uniform reference potential temperature $\theta = $ 20 $^o$C. The equation of state
used in this experiment is linear

\begin{equation}
\label{EQ:eg-bconv-linear1_eos}
\rho = \rho_{0} ( 1 - \alpha_{\theta}\theta^{'} )
\end{equation}

\noindent which is implemented in the model as a density anomaly equation

\begin{equation}
\label{EQ:eg-bconv-linear1_eos_pert}
\rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'}
\end{equation}

\noindent with $\rho_{0}=1000\,{\rm kg\,m}^{-3}$ and 
$\alpha_{\theta}=2\times10^{-4}\,{\rm degrees}^{-1} $. Integrated forward in
this configuration the model state variable {\bf theta} is equivalent to
either in-situ temperature, $T$, or potential temperature, $\theta$. For 
consistency with other examples, in which the equation of state is
non-linear, we use $\theta$ to represent temperature here. This is
the quantity that is carried in the model core equations.

As the fluid in the surface layer is cooled (at a mean rate of 800 Wm$^2$), it becomes 
convectively unstable and 
overturns, at first close to the grid-scale, but, as the flow matures, on larger scales 
(figures \ref{FIG:eg-bconv-vertsection} and \ref{FIG:eg-bconv-horizsection}), under the influence of 
rotation ($f_o = 10^{-4}$ s$^{-1}$) .

\begin{rawhtml}MITGCM_INSERT_FIGURE_BEGIN surf-convection-vertsection\end{rawhtml}
\begin{figure}
\begin{center}
 \resizebox{15cm}{10cm}{
   \includegraphics*[0.2in,0.7in][10.5in,10.5in]
   {part3/case_studies/doubly_periodic_convection/verticalsection.ps} }
\end{center}
\caption{
}
\label{FIG:eg-bconv-vertsection}
\label{fig:surf-convection-vertsection}
\end{figure}
\begin{rawhtml}MITGCM_INSERT_FIGURE_END\end{rawhtml}

\begin{rawhtml}MITGCM_INSERT_FIGURE_BEGIN surf-convection-horizsection\end{rawhtml}
\begin{figure}
\begin{center}
 \resizebox{10cm}{10cm}{
   \includegraphics*[0.2in,0.7in][10.5in,10.5in]
   {part3/case_studies/doubly_periodic_convection/surfacesection.ps} }
\end{center}
\caption{
}
\label{FIG:eg-bconv-horizsection}
\label{fig:surf-convection-horizsection}
\end{figure}
\begin{rawhtml}MITGCM_INSERT_FIGURE_END\end{rawhtml}

Model parameters are specified in file {\it input/data}. The grid dimensions are
prescribed in {\it code/SIZE.h}. The forcing (file {\it input/Qsurf.bin}) is specified 
in a binary data file generated using the Matlab script {\it input/gendata.m}.

\subsection{Equations solved}
\label{www:tutorials}

The model is configured in nonhydrostatic form, that is, all terms in the Navier 
Stokes equations are retained and the pressure field is found, subject to appropriate
bounday condintions, through inversion of a three-dimensional elliptic equation. 

The implicit free surface form of the
pressure equation described in Marshall et. al \cite{marshall:97a} is
employed. A horizontal Laplacian operator $\nabla_{h}^2$ provides viscous
dissipation. The thermodynamic forcing appears as a sink in the potential temperature, 
$\theta$, equation (\ref{EQ:eg-bconv-global_forcing_ft}). This produces a set of equations 
solved in this configuration as follows:

\begin{eqnarray}
\label{EQ:eg-bconv-model_equations}
\frac{Du}{Dt} - fv + 
  \frac{1}{\rho}\frac{\partial p^{'}}{\partial x} - 
  \nabla_{h}\cdot A_{h}\nabla_{h}u - 
  \frac{\partial}{\partial z}A_{z}\frac{\partial u}{\partial z} 
 & = &
\begin{cases}
0 & \text{(surface)} \\
0 & \text{(interior)}
\end{cases}
\\
\frac{Dv}{Dt} + fu + 
  \frac{1}{\rho}\frac{\partial p^{'}}{\partial y} - 
  \nabla_{h}\cdot A_{h}\nabla_{h}v - 
  \frac{\partial}{\partial z}A_{z}\frac{\partial v}{\partial z} 
& = &
\begin{cases}
0 & \text{(surface)} \\
0 & \text{(interior)}
\end{cases}
\\
\frac{Dw}{Dt} + g \frac{\rho^{'}}{\rho} + 
  \frac{1}{\rho}\frac{\partial p^{'}}{\partial z} - 
  \nabla_{h}\cdot A_{h}\nabla_{h}w - 
  \frac{\partial}{\partial z}A_{z}\frac{\partial w}{\partial z} 
& = &
\begin{cases}
0 & \text{(surface)} \\
0 & \text{(interior)}
\end{cases}
\\
\frac{\partial u}{\partial x} + 
\frac{\partial v}{\partial y} + 
\frac{\partial w}{\partial z} + 
&=&
0
\\
\frac{D\theta}{Dt} -
 \nabla_{h}\cdot K_{h}\nabla_{h}\theta
 - \frac{\partial}{\partial z}K_{z}\frac{\partial\theta}{\partial z} 
& = &
\begin{cases}
{\cal F}_\theta & \text{(surface)} \\
0 & \text{(interior)}
\end{cases}
\end{eqnarray}

\noindent where $u=\frac{Dx}{Dt}$, $v=\frac{Dy}{Dt}$  and 
$w=\frac{Dz}{Dt}$ are the components of the
flow vector in directions $x$, $y$ and $z$. 
The pressure is diagnosed through inversion (subject to appropriate boundary
conditions) of a 3-D elliptic equation derived from the divergence of the momentum 
equations and continuity (see section \ref{sec:finding_the_pressure_field}).
\\

\subsection{Discrete numerical configuration}
\label{www:tutorials}

The domain is discretised with a uniform grid spacing in each direction. There are 64
grid cells in directions $x$ and $y$ and 20 vertical levels thus the domain
comprises a total of just over 80 000 gridpoints.

\subsection{Numerical stability criteria and other considerations}
\label{www:tutorials}

For a heat flux of 800 Wm$^2$ and a rotation rate of $10^{-4}$ s$^{-1}$ the
plume-scale can be expected to be a few hundred meters guiding our choice of grid
resolution. This in turn restricts the timestep we can take. It is also desirable to 
minimise the level of diffusion and viscosity we apply.

For this class of problem it is generally the advective time-scale which restricts 
the timestep. 

For an extreme maximum flow speed of $ | \vec{u} | = 1 ms^{-1}$, at a resolution of
50 m, the implied maximum timestep for stability, $\delta t_u$ is 

\begin{eqnarray}
\label{EQ:eg-bconv-advectiveCFLcondition}
%\delta t_u = \frac{\Delta x}{| \vec{u} \} = 50 s
\end{eqnarray}

The choice of $\delta t = 10$ s is a safe 20 percent of this maximum.
 
Interpreted in terms of a mixing-length hypothesis, a magnitude of Laplacian
diffusion coefficient $\kappa_h (=
\kappa_v) = 0.1$ m$^2$s$^{-1}$ is consistent with an eddy velocity of 2 mm s$^{-1}$
correlated over 50 m.  

\subsection{Experiment configuration}
\label{www:tutorials}

The model configuration for this experiment resides under the directory
{\it verification/convection/}. The experiment files
\begin{itemize}
\item {\it code/CPP\_EEOPTIONS.h}
\item {\it code/CPP\_OPTIONS.h},
\item {\it code/SIZE.h}. 
\item {\it input/data}
\item {\it input/data.pkg}
\item {\it input/eedata},
\item {\it input/Qsurf.bin},
\end{itemize}
contain the code customisations and parameter settings for this 
experiment. Below we describe these experiment-specific customisations.

\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
\label{www:tutorials}

This file uses standard default values and does not contain
customisations for this experiment.

\subsubsection{File {\it code/CPP\_OPTIONS.h}}
\label{www:tutorials}

This file uses standard default values and does not contain
customisations for this experiment.

\subsubsection{File {\it code/SIZE.h}}
\label{www:tutorials}

Three lines are customized in this file. These prescribe the domain grid dimensions.
\begin{itemize}

\item Line 36, 
\begin{verbatim} sNx=64, \end{verbatim} this line sets
the lateral domain extent in grid points for the
axis aligned with the $x$-coordinate.

\item Line 37, 
\begin{verbatim} sNy=64, \end{verbatim} this line sets
the lateral domain extent in grid points for the
axis aligned with the $y$-coordinate.

\item Line 46, 
\begin{verbatim} Nr=20,   \end{verbatim} this line sets
the vertical domain extent in grid points.

\end{itemize}

\begin{rawhtml}<PRE>\end{rawhtml}
\begin{small}
\input{part3/case_studies/doubly_periodic_convection/code/SIZE.h}
\end{small}
\begin{rawhtml}</PRE>\end{rawhtml}

\subsubsection{File {\it input/data}}
\label{www:tutorials}

This file, reproduced completely below, specifies the main parameters 
for the experiment. The parameters that are significant for this configuration
are

\begin{itemize}

\item Line 4, 
\begin{verbatim}
     4   tRef=20*20.0,
\end{verbatim}
this line sets
the initial and reference values of potential temperature at each model
level in units of $^{\circ}\mathrm{C}$. Here the value is arbitrary since, in this case, the 
flow evolves independently of the absolute magnitude of the reference temperature.
For each depth level the initial and reference profiles will be uniform in
$x$ and $y$. The values specified are read into the
variable 
{\bf 
\begin{rawhtml} <A href=../code_reference/vdb/names/OK.htm> \end{rawhtml}
tRef
\begin{rawhtml} </A>\end{rawhtml}
} 
in the model code, by procedure 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}.
}
The temperature field is initialised, by procedure 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/OK.htm> \end{rawhtml}
S/R INI\_THETA ({\it ini\_theta.F})
\begin{rawhtml} </A>\end{rawhtml}.
}


\item Line 5,
\begin{verbatim}
     5   sRef=20*35.0,
\end{verbatim}
this line sets the initial and reference values of salinity at each model
level in units of ppt. In this case salinity is set to an (arbitrary) uniform value of 
35.0 ppt. However since, in this example, density is independent of salinity, 
an appropriatly defined initial salinity could provide a useful passive 
tracer. For each depth level the initial and reference profiles will be uniform in
$x$ and $y$. The values specified are read into the
variable 
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/OK.htm> \end{rawhtml}
sRef
\begin{rawhtml} </A>\end{rawhtml}
} 
in the model code, by procedure 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
}
\begin{rawhtml} </A>\end{rawhtml}.
The salinity field is initialised, by procedure 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/OK.htm> \end{rawhtml}
S/R INI\_SALT ({\it ini\_salt.F})
\begin{rawhtml} </A>\end{rawhtml}.
}


\item Line 6,
\begin{verbatim}
     6   viscAh=0.1,
\end{verbatim}
this line sets the horizontal laplacian dissipation coefficient to
0.1 ${\rm m^{2}s^{-1}}$. Boundary conditions
for this operator are specified later. 
The variable 
{\bf 
\begin{rawhtml} <A href=../code_reference/vdb/names/SI.htm> \end{rawhtml}
viscAh
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_params.F})
\begin{rawhtml} </A>\end{rawhtml}
} and applied in routines 
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F})
\begin{rawhtml} </A>\end{rawhtml}
} and 
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_GW ({\it calc\_gw.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Line 7,
\begin{verbatim}
     7   viscAz=0.1,
\end{verbatim}
this line sets the vertical laplacian frictional dissipation coefficient to
0.1 ${\rm m^{2}s^{-1}}$. Boundary conditions
for this operator are specified later.
The variable 
{\bf 
\begin{rawhtml} <A href=../code_reference/vdb/names/ZQ.htm> \end{rawhtml}
viscAz
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
}
and is copied into model general vertical coordinate variable 
{\bf 
\begin{rawhtml} <A href=../code_reference/vdb/names/PF.htm> \end{rawhtml}
viscAr
\begin{rawhtml} </A>\end{rawhtml}
}. At each time step, the viscous term contribution to the momentum equations
is calculated in routine
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Line 8,
\begin{verbatim}
no_slip_sides=.FALSE.
\end{verbatim}
this line selects a free-slip lateral boundary condition for
the horizontal laplacian friction operator 
e.g. $\frac{\partial u}{\partial y}$=0 along boundaries in $y$ and
$\frac{\partial v}{\partial x}$=0 along boundaries in $x$.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/UT.htm> \end{rawhtml}
no\_slip\_sides
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
} and the boundary condition is evaluated in routine
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Lines 9,
\begin{verbatim}
no_slip_bottom=.TRUE.
\end{verbatim}
this line selects a no-slip boundary condition for the bottom
boundary condition in the vertical laplacian friction operator 
e.g. $u=v=0$ at $z=-H$, where $H$ is the local depth of the domain.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/UK.htm> \end{rawhtml}
no\_slip\_bottom
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
} and is applied in the routine 
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F})
\begin{rawhtml} </A>\end{rawhtml}
}.

\item Line 11,
\begin{verbatim}
diffKhT=0.1,
\end{verbatim}
this line sets the horizontal diffusion coefficient for temperature
to 0.1 $\rm m^{2}s^{-1}$. The boundary condition on this
operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ at
all boundaries.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/RC.htm> \end{rawhtml}
diffKhT
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
} and used in routine 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_GT ({\it calc\_gt.F})
\begin{rawhtml} </A>\end{rawhtml}
}.

\item Line 12,
\begin{verbatim}
diffKzT=0.1,
\end{verbatim}
this line sets the vertical diffusion coefficient for temperature
to 0.1 ${\rm m^{2}s^{-1}}$. The boundary condition on this
operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/ZT.htm> \end{rawhtml}
diffKzT
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
}.
It is copied into model general vertical coordinate variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/PD.htm> \end{rawhtml}
diffKrT
\begin{rawhtml} </A>\end{rawhtml}
} which is used in routine 
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Line 13,
\begin{verbatim}
diffKhS=0.1,
\end{verbatim}
this line sets the horizontal diffusion coefficient for salinity
to 0.1 $\rm m^{2}s^{-1}$. The boundary condition on this
operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
all boundaries.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/RC.htm> \end{rawhtml}
diffKsT
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
} and used in routine 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_GS ({\it calc\_gs.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Line 14,
\begin{verbatim}
diffKzS=0.1,
\end{verbatim}
this line sets the vertical diffusion coefficient for temperature
to 0.1 ${\rm m^{2}s^{-1}}$. The boundary condition on this
operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/ZT.htm> \end{rawhtml}
diffKzS
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
}.
It is copied into model general vertical coordinate variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/PD.htm> \end{rawhtml}
diffKrS
\begin{rawhtml} </A>\end{rawhtml}
} which is used in routine 
{\it 
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F})
\begin{rawhtml} </A>\end{rawhtml}
}.


\item Line 15,
\begin{verbatim}
f0=1E-4,
\end{verbatim}
this line sets the Coriolis parameter to $1 \times 10^{-4}$ s$^{-1}$. 
Since $\beta = 0.0$ this value is then adopted throughout the domain.

 
\item Line 16,
\begin{verbatim}
beta=0.E-11,
\end{verbatim}
this line sets the the variation of Coriolis parameter with latitude to $0$.


\item Line 17,
\begin{verbatim}
tAlpha=2.E-4,
\end{verbatim}
This line sets the thermal expansion coefficient for the fluid
to $2 \times 10^{-4}$ $^o$ C$^{-1}$.
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/ZV.htm> \end{rawhtml}
tAlpha 
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
}. 
The routine 
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R FIND\_RHO ({\it find\_rho.F})
\begin{rawhtml} </A>\end{rawhtml}
} makes use of {\bf tAlpha}.

\item Line 18,
\begin{verbatim}
sBeta=0,
\end{verbatim}
This line sets the saline expansion coefficient for the fluid
to $0$ consistent with salt's passive role in this example.


\item Line 23-24,
\begin{verbatim}
rigidLid=.FALSE., 
implicitFreeSurface=.TRUE., 
\end{verbatim}
Selects the barotropic pressure equation to be the implicit free surface
formulation.

\item Line 25,
\begin{verbatim}
eosType='LINEAR',
\end{verbatim}
Selects the linear form of the equation of state.


\item Line 26,
\begin{verbatim}
nonHydrostatic=.TRUE.,
\end{verbatim}
Selects for non-hydrostatic code.


\item Line 27,
\begin{verbatim}
readBinaryPrec=64,
\end{verbatim}
Sets format for reading binary input datasets holding model fields to
use 64-bit representation for floating-point numbers.

\item Line 31,
\begin{verbatim}
cg2dMaxIters=1000,
\end{verbatim}
Inactive - the pressure field in a non-hydrostatic simulation is inverted through a 3D
elliptic equation.


\item Line 32,
\begin{verbatim}
cg2dTargetResidual=1.E-9,
\end{verbatim}
Inactive - the pressure field in a non-hydrostatic simulation is inverted through a 3D
elliptic equation.


\item Line 33,
\begin{verbatim}
cg3dMaxIters=40,
\end{verbatim}
This line sets the  maximum number of iterations the three-dimensional, conjugate
gradient solver will use to 40, {\bf irrespective of the convergence 
criteria being met}. Used in routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CG3D ({\it cg3d.F})
\begin{rawhtml} </A>\end{rawhtml}
}. 


\item Line 34,
\begin{verbatim}
cg3dTargetResidual=1.E-9,
\end{verbatim}
Sets the tolerance which the three-dimensional, conjugate
gradient solver will use to test for convergence in equation 
\ref{EQ:eg-bconv-congrad_3d_resid} to $1 \times 10^{-9}$.
The solver will iterate until the 
tolerance falls below this value or until the maximum number of
solver iterations is reached. Used in routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R CG3D ({\it cg3d.F})
\begin{rawhtml} </A>\end{rawhtml}
}. 


\item Line 38,
\begin{verbatim}
startTime=0,
\end{verbatim}
Sets the starting time for the model internal time counter.
When set to non-zero this option implicitly requests a 
checkpoint file be read for initial state.
By default the checkpoint file is named according to
the integer number of time steps in the {\bf startTime} value.
The internal time counter works in seconds.

\item Line 39,
\begin{verbatim}
nTimeSteps=8640.,
\end{verbatim}
Sets the number of timesteps at which this simulation will terminate (in this case
8640 timesteps or 1 day or $\delta t = 10$ s). 
At the end of a simulation a checkpoint file is automatically
written so that a numerical experiment can consist of multiple
stages.

\item Line 40,
\begin{verbatim}
deltaT=10,
\end{verbatim}
Sets the timestep $\delta t$  to 10 s.


\item Line 51,
\begin{verbatim}
dXspacing=50.0,
\end{verbatim}
Sets horizontal ($x$-direction) grid interval to 50 m. 


\item Line 52,
\begin{verbatim}
dYspacing=50.0,
\end{verbatim}
Sets horizontal ($y$-direction) grid interval to 50 m. 


\item Line 53,
\begin{verbatim}
delZ=20*50.0,
\end{verbatim}
Sets vertical grid spacing to 50 m. Must be consistent with {\it code/SIZE.h}. Here,
20 corresponds to the number of vertical levels.

\item Line 57,
\begin{verbatim}
surfQfile='Qsurf.bin'
\end{verbatim}
This line specifies the name of the file from which the surface heat flux 
is read. This file is a two-dimensional
($x,y$) map. It is assumed to contain 64-bit binary numbers 
giving the value of $Q$ (W m$^2$) to be applied in each surface grid cell, ordered with 
the $x$ coordinate varying fastest. The points are ordered from low coordinate
to high coordinate for both axes. The matlab program
{\it input/gendata.m} shows how to generate the 
surface heat flux file used in the example. 
The variable
{\bf
\begin{rawhtml} <A href=../code_reference/vdb/names/179.htm> \end{rawhtml}
Qsurf 
\begin{rawhtml} </A>\end{rawhtml}
}
is read in the routine
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R INI\_PARMS ({\it ini\_parms.F})
\begin{rawhtml} </A>\end{rawhtml}
}
and applied in  
{\it
\begin{rawhtml} <A href=../code_reference/vdb/code/94.htm> \end{rawhtml}
S/R EXTERNAL\_FORCING\_SURF ({\it external\_forcing\_surf.F})
\begin{rawhtml} </A>\end{rawhtml}
} where the flux is converted to a temperature tendency.


\end{itemize}


\begin{rawhtml}<PRE>\end{rawhtml}
\begin{small}
\input{part3/case_studies/doubly_periodic_convection/input/data}
\end{small}
\begin{rawhtml}</PRE>\end{rawhtml}


\subsubsection{File {\it input/data.pkg}}
\label{www:tutorials}

This file uses standard default values and does not contain
customisations for this experiment.

\subsubsection{File {\it input/eedata}}
\label{www:tutorials}

This file uses standard default values and does not contain
customisations for this experiment.


\subsubsection{File {\it input/Qsurf.bin}}
\label{www:tutorials}

The file {\it input/Qsurf.bin} specifies a two-dimensional ($x,y$) 
map of heat flux values where 
$Q = Q_o \times ( 0.5 + \mbox{random number between 0 and 1})$.

In the example $Q_o = 800$ W m$^{-2}$ so that values of $Q$ lie in the range 400 to
1200 W m$^{-2}$ with a mean of $Q_o$. Although the flux models a loss, because it is
directed upwards, according to the model's sign convention, $Q$ is positive.


\begin{figure}
\begin{center}
% \resizebox{15cm}{10cm}{
%   \includegraphics*[0.2in,0.7in][10.5in,10.5in]
%   {part3/case_studies/doubly_periodic_convection/Qsurf.ps} }
\end{center}
\caption{
}
\label{FIG:eg-bconv-Qsurf}
\end{figure}

\subsection{Running the example}
\label{www:tutorials}

\subsubsection{Code download}
\label{www:tutorials}

In order to run the examples you must first download the code distribution.
Instructions for downloading the code can be found in \ref{sect:obtainingCode}.

\subsubsection{Experiment Location}
\label{www:tutorials}

 This example experiments is located under the release sub-directory

\vspace{5mm}
{\it verification/convection/ }

\subsubsection{Running the Experiment}
\label{www:tutorials}

 To run the experiment

\begin{enumerate}
\item Set the current directory to {\it input/ }

\begin{verbatim}
% cd input
\end{verbatim}

\item Verify that current directory is now correct

\begin{verbatim}
% pwd
\end{verbatim}

 You should see a response on the screen ending in

{\it verification/convection/input }


\item Run the genmake script to create the experiment {\it Makefile}

\begin{verbatim}
% ../../../tools/genmake -mods=../code
\end{verbatim}

\item Create a list of header file dependencies in {\it Makefile}

\begin{verbatim}
% make depend
\end{verbatim}

\item Build the executable file.

\begin{verbatim}
% make
\end{verbatim}

\item Run the {\it mitgcmuv} executable

\begin{verbatim}
% ./mitgcmuv
\end{verbatim}

\end{enumerate}

