--- manual/s_examples/deep_convection/convection.tex 2001/12/19 14:34:39 1.1 +++ manual/s_examples/deep_convection/convection.tex 2004/10/16 03:40:13 1.5 @@ -1,5 +1,9 @@ -\section{Example: Surface driven convection} +\section{Surface Driven Convection} +\label{www:tutorials} \label{sect:eg-bconv} +\begin{rawhtml} + +\end{rawhtml} \bodytext{bgcolor="#FFFFFFFF"} @@ -22,10 +26,10 @@ for the surface driven convection experiment. The domain is doubly periodic with an initially uniform temperature of 20 $^oC$. } -\label{FIG:simulation_config} +\label{FIG:eg-bconv-simulation_config} \end{figure} -This experiment, figure \ref{FIG:simulation_config}, showcasing MITgcm's non-hydrostatic capability, was designed to explore +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. It is @@ -39,6 +43,7 @@ \end{itemize} \subsection{Overview} +\label{www:tutorials} The model domain consists of an approximately 3 km square by 1 km deep box of initially @@ -50,14 +55,14 @@ used in this experiment is linear \begin{equation} -\label{EQ:linear1_eos} +\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:linear1_eos_pert} +\label{EQ:eg-bconv-linear1_eos_pert} \rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'} \end{equation} @@ -72,9 +77,10 @@ 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:vertsection} and \ref{FIG:horizsection}), under the influence of +(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}{ @@ -83,9 +89,12 @@ \end{center} \caption{ } -\label{FIG:vertsection} +\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}{ @@ -94,14 +103,17 @@ \end{center} \caption{ } -\label{FIG:horizsection} +\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 @@ -111,11 +123,11 @@ 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:global_forcing_ft}). This produces a set of equations +$\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:model_equations} +\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 - @@ -171,12 +183,14 @@ \\ \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 @@ -190,7 +204,7 @@ 50 m, the implied maximum timestep for stability, $\delta t_u$ is \begin{eqnarray} -\label{EQ:advectiveCFLcondition} +\label{EQ:eg-bconv-advectiveCFLcondition} %\delta t_u = \frac{\Delta x}{| \vec{u} \} = 50 s \end{eqnarray} @@ -202,6 +216,7 @@ 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 @@ -218,16 +233,19 @@ 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} @@ -255,6 +273,7 @@ \begin{rawhtml}\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 @@ -264,7 +283,7 @@ \item Line 4, \begin{verbatim} - 4 tRef=20*20.0, + 4 tRef=20*20.0, \end{verbatim} this line sets the initial and reference values of potential temperature at each model @@ -274,19 +293,19 @@ $x$ and $y$. The values specified are read into the variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} tRef \begin{rawhtml} \end{rawhtml} } in the model code, by procedure {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml}. } The temperature field is initialised, by procedure {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_THETA ({\it ini\_theta.F}) \begin{rawhtml} \end{rawhtml}. } @@ -294,7 +313,7 @@ \item Line 5, \begin{verbatim} - 5 sRef=20*35.0, + 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 @@ -304,19 +323,19 @@ $x$ and $y$. The values specified are read into the variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} sRef \begin{rawhtml} \end{rawhtml} } in the model code, by procedure {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) } \begin{rawhtml} \end{rawhtml}. The salinity field is initialised, by procedure {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_SALT ({\it ini\_salt.F}) \begin{rawhtml} \end{rawhtml}. } @@ -324,30 +343,30 @@ \item Line 6, \begin{verbatim} - 6 viscAh=0.1, + 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} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} viscAh \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_params.F}) \begin{rawhtml} \end{rawhtml} } and applied in routines {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F}) \begin{rawhtml} \end{rawhtml} } and {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_GW ({\it calc\_gw.F}) \begin{rawhtml} \end{rawhtml} }. @@ -355,32 +374,32 @@ \item Line 7, \begin{verbatim} - 7 viscAz=0.1, + 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} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} viscAz \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and is copied into model general vertical coordinate variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} viscAr \begin{rawhtml} \end{rawhtml} }. At each time step, the viscous term contribution to the momentum equations is calculated in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F}) \begin{rawhtml} \end{rawhtml} }. @@ -396,18 +415,18 @@ $\frac{\partial v}{\partial x}$=0 along boundaries in $x$. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} no\_slip\_sides \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and the boundary condition is evaluated in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F}) \begin{rawhtml} \end{rawhtml} }. @@ -422,18 +441,18 @@ e.g. $u=v=0$ at $z=-H$, where $H$ is the local depth of the domain. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} no\_slip\_bottom \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and is applied in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_MOM\_RHS ({\it calc\_mom\_rhs.F}) \begin{rawhtml} \end{rawhtml} }. @@ -448,18 +467,18 @@ all boundaries. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKhT \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and used in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_GT ({\it calc\_gt.F}) \begin{rawhtml} \end{rawhtml} }. @@ -473,24 +492,24 @@ operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKzT \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} }. It is copied into model general vertical coordinate variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKrT \begin{rawhtml} \end{rawhtml} } which is used in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F}) \begin{rawhtml} \end{rawhtml} }. @@ -506,18 +525,18 @@ all boundaries. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKsT \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and used in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_GS ({\it calc\_gs.F}) \begin{rawhtml} \end{rawhtml} }. @@ -532,24 +551,24 @@ operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKzS \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} }. It is copied into model general vertical coordinate variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} diffKrS \begin{rawhtml} \end{rawhtml} } which is used in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CALC\_DIFFUSIVITY ({\it calc\_diffusivity.F}) \begin{rawhtml} \end{rawhtml} }. @@ -578,19 +597,19 @@ to $2 \times 10^{-4}$ $^o$ C$^{-1}$. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} tAlpha \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} }. The routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R FIND\_RHO ({\it find\_rho.F}) \begin{rawhtml} \end{rawhtml} } makes use of {\bf tAlpha}. @@ -656,7 +675,7 @@ gradient solver will use to 40, {\bf irrespective of the convergence criteria being met}. Used in routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CG3D ({\it cg3d.F}) \begin{rawhtml} \end{rawhtml} }. @@ -669,12 +688,12 @@ \end{verbatim} Sets the tolerance which the three-dimensional, conjugate gradient solver will use to test for convergence in equation -\ref{EQ:congrad_3d_resid} to $1 \times 10^{-9}$. +\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} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R CG3D ({\it cg3d.F}) \begin{rawhtml} \end{rawhtml} }. @@ -743,19 +762,19 @@ surface heat flux file used in the example. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} Qsurf \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R INI\_PARMS ({\it ini\_parms.F}) \begin{rawhtml} \end{rawhtml} } and applied in {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} S/R EXTERNAL\_FORCING\_SURF ({\it external\_forcing\_surf.F}) \begin{rawhtml} \end{rawhtml} } where the flux is converted to a temperature tendency. @@ -772,17 +791,20 @@ \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 @@ -801,17 +823,20 @@ \end{center} \caption{ } -\label{FIG:Qsurf} +\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 @@ -819,6 +844,7 @@ {\it verification/convection/ } \subsubsection{Running the Experiment} +\label{www:tutorials} To run the experiment