--- manual/s_examples/baroclinic_gyre/fourlayer.tex 2001/10/25 18:36:55 1.9 +++ manual/s_examples/baroclinic_gyre/fourlayer.tex 2003/07/30 13:42:53 1.14 @@ -1,8 +1,9 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.9 2001/10/25 18:36:55 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.14 2003/07/30 13:42:53 edhill Exp $ % $Name: $ -\section{Example: Four layer Baroclinic Ocean Gyre In Spherical Coordinates} -\label{sec:eg-fourlayer} +\section{Four Layer Baroclinic Ocean Gyre In Spherical Coordinates} +\label{www:tutorials} +\label{sect:eg-fourlayer} \bodytext{bgcolor="#FFFFFFFF"} @@ -19,13 +20,14 @@ This document describes an example experiment using MITgcm to simulate a baroclinic ocean gyre in spherical polar coordinates. The barotropic -example experiment in section \ref{sec:eg-baro} +example experiment in section \ref{sect:eg-baro} illustrated how to configure the code for a single layer simulation in a Cartesian grid. In this example a similar physical problem is simulated, but the code is now configured for four layers and in a spherical polar coordinate system. \subsection{Overview} +\label{www:tutorials} This example experiment demonstrates using the MITgcm to simulate a baroclinic, wind-forced, ocean gyre circulation. The experiment @@ -43,7 +45,7 @@ according to latitude, $\varphi$ \begin{equation} -\label{EQ:fcori} +\label{EQ:eg-fourlayer-fcori} f(\varphi) = 2 \Omega \sin( \varphi ) \end{equation} @@ -61,9 +63,9 @@ $\tau_0$ is set to $0.1N m^{-2}$. \\ -Figure \ref{FIG:simulation_config} +Figure \ref{FIG:eg-fourlayer-simulation_config} summarizes the configuration simulated. -In contrast to the example in section \ref{sec:eg-baro}, the +In contrast to the example in section \ref{sect:eg-baro}, the current experiment simulates a spherical polar domain. As indicated by the axes in the lower left of the figure the model code works internally in a locally orthogonal coordinate $(x,y,z)$. For this experiment description @@ -82,14 +84,14 @@ linear \begin{equation} -\label{EQ:linear1_eos} +\label{EQ:eg-fourlayer-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-fourlayer-linear1_eos_pert} \rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'} \end{equation} @@ -114,13 +116,14 @@ imposed by setting the potential temperature, $\theta$, in each layer. The vertical spacing, $\Delta z$, is constant and equal to $500$m. } -\label{FIG:simulation_config} +\label{FIG:eg-fourlayer-simulation_config} \end{figure} \subsection{Equations solved} +\label{www:tutorials} For this problem -the implicit free surface, {\bf HPE} (see section \ref{sec:hydrostatic_and_quasi-hydrostatic_forms}) form of the -equations described in Marshall et. al \cite{Marshall97a} are +the implicit free surface, {\bf HPE} (see section \ref{sect:hydrostatic_and_quasi-hydrostatic_forms}) form of the +equations described in Marshall et. al \cite{marshall:97a} are employed. The flow is three-dimensional with just temperature, $\theta$, as an active tracer. The equation of state is linear. A horizontal Laplacian operator $\nabla_{h}^2$ provides viscous @@ -133,7 +136,7 @@ follows \begin{eqnarray} -\label{EQ:model_equations} +\label{EQ:eg-fourlayer-model_equations} \frac{Du}{Dt} - fv + \frac{1}{\rho}\frac{\partial p^{\prime}}{\partial \lambda} - A_{h}\nabla_{h}^2u - A_{z}\frac{\partial^{2}u}{\partial z^{2}} @@ -202,6 +205,7 @@ \subsection{Discrete Numerical Configuration} +\label{www:tutorials} The domain is discretised with a uniform grid spacing in latitude and longitude @@ -221,7 +225,7 @@ The procedure for generating a set of internal grid variables from a spherical polar grid specification is discussed in section -\ref{sec:spatial_discrete_horizontal_grid}. +\ref{sect:spatial_discrete_horizontal_grid}. \noindent\fbox{ \begin{minipage}{5.5in} {\em S/R INI\_SPHERICAL\_POLAR\_GRID} ({\em @@ -242,15 +246,15 @@ -As described in \ref{sec:tracer_equations}, the time evolution of potential +As described in \ref{sect:tracer_equations}, the time evolution of potential temperature, $\theta$, (equation \ref{eq:eg_fourl_theta}) is evaluated prognostically. The centered second-order scheme with Adams-Bashforth time stepping described in section -\ref{sec:tracer_equations_abII} is used to step forward the temperature +\ref{sect:tracer_equations_abII} is used to step forward the temperature equation. Prognostic terms in the momentum equations are solved using flux form as -described in section \ref{sec:flux-form_momentum_eqautions}. +described in section \ref{sect:flux-form_momentum_eqautions}. The pressure forces that drive the fluid motions, ( $\frac{\partial p^{'}}{\partial \lambda}$ and $\frac{\partial p^{'}}{\partial \varphi}$), are found by summing pressure due to surface elevation $\eta$ and the hydrostatic pressure. The hydrostatic part of the @@ -258,15 +262,16 @@ height, $\eta$, is diagnosed using an implicit scheme. The pressure field solution method is described in sections \ref{sect:pressure-method-linear-backward} and -\ref{sec:finding_the_pressure_field}. +\ref{sect:finding_the_pressure_field}. \subsubsection{Numerical Stability Criteria} +\label{www:tutorials} The Laplacian viscosity coefficient, $A_{h}$, is set to $400 m s^{-1}$. This value is chosen to yield a Munk layer width, \begin{eqnarray} -\label{EQ:munk_layer} +\label{EQ:eg-fourlayer-munk_layer} M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}} \end{eqnarray} @@ -282,7 +287,7 @@ parameter to the horizontal Laplacian friction \begin{eqnarray} -\label{EQ:laplacian_stability} +\label{EQ:eg-fourlayer-laplacian_stability} S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2} \end{eqnarray} @@ -294,7 +299,7 @@ $1\times10^{-2} {\rm m}^2{\rm s}^{-1}$. The associated stability limit \begin{eqnarray} -\label{EQ:laplacian_stability_z} +\label{EQ:eg-fourlayer-laplacian_stability_z} S_{l} = 4 \frac{A_{z} \delta t}{{\Delta z}^2} \end{eqnarray} @@ -307,7 +312,7 @@ \noindent The numerical stability for inertial oscillations \begin{eqnarray} -\label{EQ:inertial_stability} +\label{EQ:eg-fourlayer-inertial_stability} S_{i} = f^{2} {\delta t}^2 \end{eqnarray} @@ -320,7 +325,7 @@ speed of $ | \vec{u} | = 2 ms^{-1}$ \begin{eqnarray} -\label{EQ:cfl_stability} +\label{EQ:eg-fourlayer-cfl_stability} C_{a} = \frac{| \vec{u} | \delta t}{ \Delta x} \end{eqnarray} @@ -332,7 +337,7 @@ propagating at $2~{\rm m}~{\rm s}^{-1}$ \begin{eqnarray} -\label{EQ:igw_stability} +\label{EQ:eg-fourlayer-igw_stability} S_{c} = \frac{c_{g} \delta t}{ \Delta x} \end{eqnarray} @@ -340,6 +345,7 @@ stability limit of 0.25. \subsection{Code Configuration} +\label{www:tutorials} \label{SEC:eg_fourl_code_config} The model configuration for this experiment resides under the @@ -359,6 +365,7 @@ to these files associated with this experiment. \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 @@ -376,13 +383,13 @@ $x$ and $y$. The values specified here 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} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. @@ -395,7 +402,7 @@ %% \file{ini_parms} \newcommand{\VARtref}{ {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} tRef \begin{rawhtml} \end{rawhtml} } @@ -410,7 +417,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -423,19 +430,19 @@ 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} INI\_PARMS \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 @@ -448,7 +455,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -462,13 +469,13 @@ 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} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and applied in routines {\it CALC\_MOM\_RHS} and {\it CALC\_GW}. @@ -479,7 +486,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -490,7 +497,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -505,13 +512,13 @@ $\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} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and the boundary condition is evaluated in routine @@ -524,7 +531,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -538,13 +545,13 @@ 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} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and is applied in the routine {\it S/R CALC\_MOM\_RHS}. @@ -555,7 +562,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -570,13 +577,13 @@ 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} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and used in routine {\it S/R CALC\_GT}. @@ -586,7 +593,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -600,19 +607,19 @@ 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} INI\_PARMS \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 S/R CALC\_DIFFUSIVITY}. @@ -622,7 +629,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -637,13 +644,13 @@ to $2 \times 10^{-4}\,{\rm degrees}^{-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} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. The routine {\it S/R FIND\_RHO} makes use of {\bf tAlpha}. @@ -654,7 +661,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -666,13 +673,13 @@ This line selects the linear form of the equation of state. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} eosType \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. The values of {\bf eosType} sets which formula in routine @@ -684,7 +691,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -702,13 +709,13 @@ on spherical polar geometry. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} usingSphericalPolarGrid \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. When set to {\bf .TRUE.} the settings of {\bf delX} and {\bf delY} are @@ -721,7 +728,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -739,13 +746,13 @@ not alter the kernel equation discretisation. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} phiMin \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. @@ -756,7 +763,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -769,13 +776,13 @@ in the discrete grid to $1^{\circ}$ in longitude. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} delX \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. @@ -786,7 +793,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -799,13 +806,13 @@ in the discrete grid to $1^{\circ}$ in latitude. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} delY \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} } and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. @@ -816,7 +823,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -830,20 +837,20 @@ is $2\,{\rm km}$. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} delZ \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. It is copied into the internal model coordinate variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} delR \begin{rawhtml} \end{rawhtml} } which is used in routine {\it INI\_VERTICAL\_GRID}. @@ -854,7 +861,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -876,13 +883,13 @@ bathymetry file. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} bathyFile \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. The bathymetry file is read in the routine {\it INI\_DEPTHS}. @@ -893,7 +900,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -912,13 +919,13 @@ file. The variable {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} zonalWindFile \begin{rawhtml} \end{rawhtml} } is read in the routine {\it -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} INI\_PARMS \begin{rawhtml} \end{rawhtml} }. The wind-stress file is read in the routine @@ -930,7 +937,7 @@ \end{minipage} } {\bf -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} goto code \begin{rawhtml} \end{rawhtml} } @@ -946,16 +953,19 @@ \begin{rawhtml}\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/windx.sin\_y}} +\label{www:tutorials} The {\it input/windx.sin\_y} file specifies a two-dimensional ($x,y$) map of wind stress ,$\tau_{x}$, values. The units used are $Nm^{-2}$ (the @@ -969,6 +979,7 @@ code for creating the {\it input/windx.sin\_y} file. \subsubsection{File {\it input/topog.box}} +\label{www:tutorials} The {\it input/topog.box} file specifies a two-dimensional ($x,y$) @@ -980,6 +991,7 @@ code for creating the {\it input/topog.box} file. \subsubsection{File {\it code/SIZE.h}} +\label{www:tutorials} Two lines are customized in this file for the current experiment @@ -1006,17 +1018,20 @@ \end{small} \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/CPP\_EEOPTIONS.h}} +\label{www:tutorials} This file uses standard default values and does not contain customisations for this experiment. \subsubsection{Other Files } +\label{www:tutorials} Other files relevant to this experiment are \begin{itemize} @@ -1029,15 +1044,18 @@ \end{itemize} \subsection{Running The Example} +\label{www:tutorials} \label{SEC:running_the_example} \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 section \ref{sect:obtainingCode}. \subsubsection{Experiment Location} +\label{www:tutorials} This example experiments is located under the release sub-directory @@ -1045,6 +1063,7 @@ {\it verification/exp2/ } \subsubsection{Running the Experiment} +\label{www:tutorials} To run the experiment