--- manual/s_examples/baroclinic_gyre/fourlayer.tex 2001/10/25 12:06:56 1.8 +++ manual/s_examples/baroclinic_gyre/fourlayer.tex 2006/06/27 19:08:22 1.21 @@ -1,8 +1,12 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.8 2001/10/25 12:06:56 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.21 2006/06/27 19:08:22 molod Exp $ % $Name: $ -\section{Example: Four layer Baroclinic Ocean Gyre In Spherical Coordinates} -\label{sec:eg-fourlayer} +\section[Baroclinic Gyre MITgcm Example]{Four Layer Baroclinic Ocean Gyre In Spherical Coordinates} +\label{www:tutorials} +\label{sect:eg-fourlayer} +\begin{rawhtml} + +\end{rawhtml} \bodytext{bgcolor="#FFFFFFFF"} @@ -17,19 +21,16 @@ %\end{center} 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} -ilustrated 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. +to simulate a baroclinic ocean gyre for four layers in spherical +polar coordinates. The files for this experiment can be found +in the verification directory under tutorial\_baroclinic\_gyre. \subsection{Overview} +\label{www:tutorials} This example experiment demonstrates using the MITgcm to simulate a baroclinic, wind-forced, ocean gyre circulation. The experiment -is a numerical rendition of the gyre circulation problem simliar +is a numerical rendition of the gyre circulation problem similar to the problems described analytically by Stommel in 1966 \cite{Stommel66} and numerically in Holland et. al \cite{Holland75}. \\ @@ -43,7 +44,7 @@ according to latitude, $\varphi$ \begin{equation} -\label{EQ:fcori} +\label{EQ:eg-fourlayer-fcori} f(\varphi) = 2 \Omega \sin( \varphi ) \end{equation} @@ -61,13 +62,13 @@ $\tau_0$ is set to $0.1N m^{-2}$. \\ -Figure \ref{FIG:simulation_config} -summarises the configuration simulated. -In contrast to the example in section \ref{sec:eg-baro}, the +Figure \ref{FIG:eg-fourlayer-simulation_config} +summarizes the configuration simulated. +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 orthoganal coordinate $(x,y,z)$. For this experiment description -the local orthogonal model coordinate $(x,y,z)$ is synonomous +in a locally orthogonal coordinate $(x,y,z)$. For this experiment description +the local orthogonal model coordinate $(x,y,z)$ is synonymous with the coordinates $(\lambda,\varphi,r)$ shown in figure \ref{fig:spherical-polar-coord} \\ @@ -82,14 +83,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} @@ -102,11 +103,15 @@ the quantity that is carried in the model core equations. \begin{figure} -\begin{center} - \resizebox{7.5in}{5.5in}{ - \includegraphics*[0.2in,0.7in][10.5in,10.5in] - {part3/case_studies/fourlayer_gyre/simulation_config.eps} } -\end{center} +%% \begin{center} +%% \resizebox{7.5in}{5.5in}{ +%% \includegraphics*[0.2in,0.7in][10.5in,10.5in] +%% {part3/case_studies/fourlayer_gyre/simulation_config.eps} } +%% \end{center} +\centerline{ + \scalefig{.95} + \epsfbox{part3/case_studies/fourlayer_gyre/simulation_config.eps} +} \caption{Schematic of simulation domain and wind-stress forcing function for the four-layer gyre numerical experiment. The domain is enclosed by solid walls at $0^{\circ}$~E, $60^{\circ}$~E, $0^{\circ}$~N and $60^{\circ}$~N. @@ -114,26 +119,27 @@ 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 +A horizontal Laplacian operator $\nabla_{h}^2$ provides viscous dissipation and provides a diffusive sub-grid scale closure for the temperature equation. A wind-stress momentum forcing is added to the momentum equation for the zonal flow, $u$. Other terms in the model -are explicitly switched off for this experiement configuration (see section +are explicitly switched off for this experiment configuration (see section \ref{SEC:eg_fourl_code_config} ). This yields an active set of equations solved in this configuration, written in spherical polar coordinates as 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 +208,7 @@ \subsection{Discrete Numerical Configuration} +\label{www:tutorials} The domain is discretised with a uniform grid spacing in latitude and longitude @@ -210,7 +217,7 @@ Vertically the model is configured with four layers with constant depth, $\Delta z$, of $500$~m. The internal, locally orthogonal, model coordinate -variables $x$ and $y$ are initialised from the values of +variables $x$ and $y$ are initialized from the values of $\lambda$, $\varphi$, $\Delta \lambda$ and $\Delta \varphi$ in radians according to @@ -221,7 +228,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 +249,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 +265,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}$. +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} @@ -279,10 +287,10 @@ \noindent The model is stepped forward with a time step $\delta t=1200$secs. With this time step the stability -parameter to the horizontal laplacian friction +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 +302,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 +315,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 +328,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} @@ -329,10 +337,10 @@ \\ \noindent The stability parameter for internal gravity waves -propogating at $2~{\rm m}~{\rm s}^{-1}$ +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 +348,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 @@ -354,11 +363,12 @@ \item {\it code/CPP\_OPTIONS.h}, \item {\it code/SIZE.h}. \end{itemize} -contain the code customisations and parameter settings for this -experiements. Below we describe the customisations -to these files associated with this experiment. +contain the code customisations and parameter settings for this +experiment. Below we describe the customisations 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 @@ -368,572 +378,302 @@ \item Line 4, \begin{verbatim} tRef=20.,10.,8.,6., \end{verbatim} -this line sets -the initial and reference values of potential temperature at each model -level in units of $^{\circ}$C. -The entries are ordered from surface to depth. For each -depth level the inital and reference profiles will be uniform in -$x$ and $y$. The values specified here are read into the -variable -{\bf -\begin{rawhtml} \end{rawhtml} -tRef -\begin{rawhtml} \end{rawhtml} -} -in the model code, by procedure -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. - -%% \codelink{var:tref} tRef \endlink -%% \codelink{file:ini_parms} {\it INI\_PARMS } \endlink -%% \codelink{proc:ini_parms} {\it INI\_PARMS } \endlink -%% \var{tref} -%% \proc{ini_parms} -%% \file{ini_parms} -\newcommand{\VARtref}{ -{\bf -\begin{rawhtml} \end{rawhtml} -tRef -\begin{rawhtml} \end{rawhtml} -} -} - - +this line sets the initial and reference values of potential +temperature at each model level in units of $^{\circ}\mathrm{C}$. The entries +are ordered from surface to depth. For each depth level the initial +and reference profiles will be uniform in $x$ and $y$. The values +specified here are read into the variable \varlink{tRef}{tRef} in the +model code, by procedure \filelink{INI\_PARMS}{model-src-ini_parms.F} \fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_THETA} -({\it ini\_theta.F}) -\end{minipage} + \begin{minipage}{5.0in} + {\it S/R INI\_THETA}({\it ini\_theta.F}) + \end{minipage} } -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} - +\filelink{ini\_theta.F}{model-src-ini_theta.F} \item Line 6, \begin{verbatim} viscAz=1.E-2, \end{verbatim} -this line sets the vertical laplacian dissipation coefficient to -$1 \times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary conditions -for this operator are specified later. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -viscAz -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} -and is copied into model general vertical coordinate variable -{\bf -\begin{rawhtml} \end{rawhtml} -viscAr -\begin{rawhtml} \end{rawhtml} -}. At each time step, the viscous term contribution to the momentum eqautions -is calculated in routine -{\it S/R CALC\_DIFFUSIVITY}. +this line sets the vertical Laplacian dissipation coefficient to $1 +\times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary conditions for this +operator are specified later. The variable \varlink{viscAz}{viscAz} +is read in the routine \filelink{ini\_parms.F}{model-src-ini_parms.F} +and is copied into model general vertical coordinate variable +\varlink{viscAr}{viscAr} At each time step, the viscous term +contribution to the momentum equations is calculated in routine +\varlink{CALC\_DIFFUSIVITY}{CALC_DIFFUSIVITY} \fbox{ \begin{minipage}{5.0in} {\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F}) \end{minipage} } -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} \item Line 7, \begin{verbatim} viscAh=4.E2, \end{verbatim} -this line sets the horizontal laplacian frictional dissipation coefficient to -$1 \times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary conditions -for this operator are specified later. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -viscAh -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and applied in routines {\it CALC\_MOM\_RHS} and {\it CALC\_GW}. + this line sets the horizontal laplacian frictional dissipation + coefficient to $1 \times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary + conditions for this operator are specified later. The variable + \varlink{viscAh}{viscAh} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS} and applied in routines + \varlink{CALC\_MOM\_RHS}{CALC_MOM_RHS} and + \varlink{CALC\_GW}{CALC_GW}. \fbox{ -\begin{minipage}{5.0in} -{\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} + \begin{minipage}{5.0in} + {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) + \end{minipage} } - \fbox{ -\begin{minipage}{5.0in} -{\it S/R CALC\_GW}({\it calc\_gw.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} + \begin{minipage}{5.0in} + {\it S/R CALC\_GW}({\it calc\_gw.F}) + \end{minipage} } -\item Lines 8, +\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} \end{rawhtml} -no\_slip\_sides -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and the boundary condition is evaluated in routine -{\it S/R CALC\_MOM\_RHS}. - - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} - + 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 + \varlink{no\_slip\_sides}{no_slip_sides} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS} and the boundary condition is + evaluated in routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) + \end{minipage} + } + \filelink{calc\_mom\_rhs.F}{calc_mom_rhs.F} + \item Lines 9, \begin{verbatim} no_slip_bottom=.TRUE. \end{verbatim} -this line selects a no-slip boundary condition for 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} \end{rawhtml} -no\_slip\_bottom -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and is applied in the routine {\it S/R CALC\_MOM\_RHS}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + this line selects a no-slip boundary condition for 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 + \varlink{no\_slip\_bottom}{no\_slip\_bottom} is read in the routine + \filelink{INI\_PARMS}{model-src-ini_parms.F} and is applied in the + routine \varlink{CALC\_MOM\_RHS}{CALC_MOM_RHS}. + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F}) + \end{minipage} + } + \filelink{calc\_mom\_rhs.F}{calc_mom_rhs.F} \item Line 10, \begin{verbatim} diffKhT=4.E2, \end{verbatim} -this line sets the horizontal diffusion coefficient for temperature -to $400\,{\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} \end{rawhtml} -diffKhT -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and used in routine {\it S/R CALC\_GT}. - -\fbox{ \begin{minipage}{5.0in} -{\it S/R CALC\_GT}({\it calc\_gt.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + this line sets the horizontal diffusion coefficient for temperature + to $400\,{\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 \varlink{diffKhT}{diffKhT} is read in + the routine \varlink{INI\_PARMS}{INI_PARMS} and used in routine + \varlink{CALC\_GT}{CALC_GT}. + + \fbox{ \begin{minipage}{5.0in} + {\it S/R CALC\_GT}({\it calc\_gt.F}) + \end{minipage} + } + \filelink{calc\_gt.F}{model-src-calc_gt.F} \item Line 11, \begin{verbatim} diffKzT=1.E-2, \end{verbatim} -this line sets the vertical diffusion coefficient for temperature -to $10^{-2}\,{\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} \end{rawhtml} -diffKzT -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. -It is copied into model general vertical coordinate variable -{\bf -\begin{rawhtml} \end{rawhtml} -diffKrT -\begin{rawhtml} \end{rawhtml} -} which is used in routine {\it S/R CALC\_DIFFUSIVITY}. - -\fbox{ \begin{minipage}{5.0in} -{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} - - + this line sets the vertical diffusion coefficient for temperature to + $10^{-2}\,{\rm m^{2}s^{-1}}$. The boundary condition on this + operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries. + The variable \varlink{diffKzT}{diffKzT} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS}. It is copied into model general + vertical coordinate variable \varlink{diffKrT}{diffKrT} which is + used in routine \varlink{CALC\_DIFFUSIVITY}{CALC_DIFFUSIVITY}. + + \fbox{ \begin{minipage}{5.0in} + {\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F}) + \end{minipage} + } + \filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F} \item Line 13, \begin{verbatim} tAlpha=2.E-4, \end{verbatim} -This line sets the thermal expansion coefficient for the fluid -to $2 \times 10^{-4}\,{\rm degrees}^{-1}$ -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -tAlpha -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. The routine {\it S/R FIND\_RHO} makes use of {\bf tAlpha}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R FIND\_RHO}({\it find\_rho.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line sets the thermal expansion coefficient for the fluid to $2 + \times 10^{-4}\,{\rm degrees}^{-1}$ The variable + \varlink{tAlpha}{tAlpha} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS}. The routine + \varlink{FIND\_RHO}{FIND\_RHO} makes use of {\bf tAlpha}. + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R FIND\_RHO}({\it find\_rho.F}) + \end{minipage} + } + \filelink{find\_rho.F}{model-src-find_rho.F} \item Line 18, \begin{verbatim} eosType='LINEAR' \end{verbatim} -This line selects the linear form of the equation of state. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -eosType -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. The values of {\bf eosType} sets which formula in routine -{\it FIND\_RHO} is used to calculate density. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R FIND\_RHO}({\it find\_rho.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} - - + This line selects the linear form of the equation of state. The + variable \varlink{eosType}{eosType} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS}. The values of {\bf eosType} sets + which formula in routine {\it FIND\_RHO} is used to calculate + density. + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R FIND\_RHO}({\it find\_rho.F}) + \end{minipage} + } + \filelink{find\_rho.F}{model-src-find_rho.F} \item Line 40, \begin{verbatim} usingSphericalPolarGrid=.TRUE., \end{verbatim} -This line requests that the simulation be performed in a -spherical polar coordinate system. It affects the interpretation of -grid inoput parameters, for exampl {\bf delX} and {\bf delY} and -causes the grid generation routines to initialise an internal grid based -on spherical polar geometry. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -usingSphericalPolarGrid -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. When set to {\bf .TRUE.} the settings of {\bf delX} and {\bf delY} are -taken to be in degrees. These values are used in the -routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line requests that the simulation be performed in a spherical + polar coordinate system. It affects the interpretation of grid input + parameters, for example {\bf delX} and {\bf delY} and causes the + grid generation routines to initialize an internal grid based on + spherical polar geometry. The variable + \varlink{usingSphericalPolarGrid}{usingSphericalPolarGrid} is read + in the routine \varlink{INI\_PARMS}{INI_PARMS}. When set to {\bf + .TRUE.} the settings of {\bf delX} and {\bf delY} are taken to be + in degrees. These values are used in the routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) + \end{minipage} + } + \filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} \item Line 41, \begin{verbatim} phiMin=0., \end{verbatim} -This line sets the southern boundary of the modeled -domain to $0^{\circ}$ latitude. This value affects both the -generation of the locally orthogonal grid that the model -uses internally and affects the initialisation of the coriolis force. -Note - it is not required to set -a longitude boundary, since the absolute longitude does -not alter the kernel equation discretisation. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -phiMin -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line sets the southern boundary of the modeled domain to + $0^{\circ}$ latitude. This value affects both the generation of the + locally orthogonal grid that the model uses internally and affects + the initialization of the coriolis force. Note - it is not required + to set a longitude boundary, since the absolute longitude does not + alter the kernel equation discretisation. The variable + \varlink{phiMin}{phiMin} is read in the + routine \varlink{INI\_PARMS}{INI_PARMS} and is used in routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) + \end{minipage} + } + \filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} \item Line 42, \begin{verbatim} delX=60*1., \end{verbatim} -This line sets the horizontal grid spacing between each y-coordinate line -in the discrete grid to $1^{\circ}$ in longitude. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -delX -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line sets the horizontal grid spacing between each y-coordinate + line in the discrete grid to $1^{\circ}$ in longitude. The variable + \varlink{delX}{delX} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS} and is used in routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) + \end{minipage} + } + \filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} \item Line 43, \begin{verbatim} delY=60*1., \end{verbatim} -This line sets the horizontal grid spacing between each y-coordinate line -in the discrete grid to $1^{\circ}$ in latitude. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -delY -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -} and is used in routine {\it INI\_SPEHRICAL\_POLAR\_GRID}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line sets the horizontal grid spacing between each y-coordinate + line in the discrete grid to $1^{\circ}$ in latitude. The variable + \varlink{delY}{delY} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS} and is used in routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) + \end{minipage} + } + \filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} \item Line 44, \begin{verbatim} delZ=500.,500.,500.,500., \end{verbatim} -This line sets the vertical grid spacing between each z-coordinate line -in the discrete grid to $500\,{\rm m}$, so that the total model depth -is $2\,{\rm km}$. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -delZ -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. -It is copied into the internal -model coordinate variable -{\bf -\begin{rawhtml} \end{rawhtml} -delR -\begin{rawhtml} \end{rawhtml} -} which is used in routine {\it INI\_VERTICAL\_GRID}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_VERTICAL\_GRID}({\it ini\_vertical\_grid.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line sets the vertical grid spacing between each z-coordinate + line in the discrete grid to $500\,{\rm m}$, so that the total model + depth is $2\,{\rm km}$. The variable \varlink{delZ}{delZ} is read + in the routine \varlink{INI\_PARMS}{INI_PARMS}. It is copied into + the internal model coordinate variable \varlink{delR}{delR} which is + used in routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_VERTICAL\_GRID}({\it ini\_vertical\_grid.F}) + \end{minipage} + } + \filelink{ini\_vertical\_grid.F}{model-src-ini_vertical_grid.F} \item Line 47, \begin{verbatim} bathyFile='topog.box' \end{verbatim} -This line specifies the name of the file from which the domain -bathymetry is read. This file is a two-dimensional ($x,y$) map of -depths. This file is assumed to contain 64-bit binary numbers -giving the depth of the model at each grid cell, ordered with the x -coordinate varying fastest. The points are ordered from low coordinate -to high coordinate for both axes. The units and orientation of the -depths in this file are the same as used in the MITgcm code. In this -experiment, a depth of $0m$ indicates a solid wall and a depth -of $-2000m$ indicates open ocean. The matlab program -{\it input/gendata.m} shows an example of how to generate a -bathymetry file. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -bathyFile -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. The bathymetry file is read in the routine {\it INI\_DEPTHS}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R INI\_DEPTHS}({\it ini\_depths.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} - + This line specifies the name of the file from which the domain + bathymetry is read. This file is a two-dimensional ($x,y$) map of + depths. This file is assumed to contain 64-bit binary numbers giving + the depth of the model at each grid cell, ordered with the x + coordinate varying fastest. The points are ordered from low + coordinate to high coordinate for both axes. The units and + orientation of the depths in this file are the same as used in the + MITgcm code. In this experiment, a depth of $0m$ indicates a solid + wall and a depth of $-2000m$ indicates open ocean. The matlab + program {\it input/gendata.m} shows an example of how to generate a + bathymetry file. The variable \varlink{bathyFile}{bathyFile} is + read in the routine \varlink{INI\_PARMS}{INI_PARMS}. The bathymetry + file is read in the routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R INI\_DEPTHS}({\it ini\_depths.F}) + \end{minipage} + } + \filelink{ini\_depths.F}{model-src-ini_depths.F} \item Line 50, \begin{verbatim} zonalWindFile='windx.sin_y' \end{verbatim} -This line specifies the name of the file from which the x-direction -(zonal) surface wind stress is read. This file is also a two-dimensional -($x,y$) map and is enumerated and formatted in the same manner as the -bathymetry file. The matlab program {\it input/gendata.m} includes example -code to generate a valid -{\bf zonalWindFile} -file. -The variable -{\bf -\begin{rawhtml} \end{rawhtml} -zonalWindFile -\begin{rawhtml} \end{rawhtml} -} -is read in the routine -{\it -\begin{rawhtml} \end{rawhtml} -INI\_PARMS -\begin{rawhtml} \end{rawhtml} -}. The wind-stress file is read in the routine -{\it EXTERNAL\_FIELDS\_LOAD}. - -\fbox{ -\begin{minipage}{5.0in} -{\it S/R EXTERNAL\_FIELDS\_LOAD}({\it external\_fields\_load.F}) -\end{minipage} -} -{\bf -\begin{rawhtml} \end{rawhtml} -goto code -\begin{rawhtml} \end{rawhtml} -} + This line specifies the name of the file from which the x-direction + (zonal) surface wind stress is read. This file is also a + two-dimensional ($x,y$) map and is enumerated and formatted in the + same manner as the bathymetry file. The matlab program {\it + input/gendata.m} includes example code to generate a valid {\bf + zonalWindFile} file. The variable + \varlink{zonalWindFile}{zonalWindFile} is read in the routine + \varlink{INI\_PARMS}{INI_PARMS}. The wind-stress file is read in + the routine + + \fbox{ + \begin{minipage}{5.0in} + {\it S/R EXTERNAL\_FIELDS\_LOAD}({\it external\_fields\_load.F}) + \end{minipage} + } + \filelink{external\_fields\_load.F}{model-src-external_fields_load.F} \end{itemize} @@ -946,29 +686,32 @@ \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 -default for MITgcm). -Although $\tau_{x}$ is only a function of latituted, $y$, -in this experiment -this file must still define a complete two-dimensional map in order -to be compatible with the standard code for loading forcing fields -in MITgcm (routine {\it EXTERNAL\_FIELDS\_LOAD}. -The included matlab program {\it input/gendata.m} gives a complete -code for creating the {\it input/windx.sin\_y} file. +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 default for MITgcm). Although $\tau_{x}$ is only a function of +latitude, $y$, in this experiment this file must still define a +complete two-dimensional map in order to be compatible with the +standard code for loading forcing fields in MITgcm (routine {\it + EXTERNAL\_FIELDS\_LOAD}. The included matlab program {\it + input/gendata.m} gives a complete 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 +723,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 +750,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 +776,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 +795,7 @@ {\it verification/exp2/ } \subsubsection{Running the Experiment} +\label{www:tutorials} To run the experiment @@ -1061,7 +812,7 @@ % pwd \end{verbatim} - You shold see a response on the screen ending in + You should see a response on the screen ending in {\it verification/exp2/input }