--- manual/s_examples/deep_convection/convection.tex 2001/12/19 14:34:39 1.1 +++ manual/s_examples/deep_convection/convection.tex 2006/06/27 19:08:22 1.7 @@ -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,12 +26,14 @@ 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 +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 @@ -39,6 +45,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 +57,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 +79,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 +91,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 +105,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 +125,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 +185,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 +206,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 +218,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 +235,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 +275,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,29 +285,29 @@ \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 -level in units of $^{\circ}$C. Here the value is arbitrary since, in this case, the +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} \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 +315,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 +325,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 +345,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 +376,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 +417,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 +443,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 +469,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 +494,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 +527,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 +553,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 +599,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 +677,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 +690,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 +764,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 +793,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 +825,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 +846,7 @@ {\it verification/convection/ } \subsubsection{Running the Experiment} +\label{www:tutorials} To run the experiment