--- manual/s_examples/rotating_tank/tank.tex 2004/07/26 16:21:15 1.3 +++ manual/s_examples/rotating_tank/tank.tex 2004/10/13 18:52:17 1.10 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.3 2004/07/26 16:21:15 afe Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.10 2004/10/13 18:52:17 afe Exp $ % $Name: $ \bodytext{bgcolor="#FFFFFFFF"} @@ -13,192 +13,66 @@ %{\large May 2001} %\end{center} -This is the first in a series of tutorials describing -example MITgcm numerical experiments. The example experiments -include both straightforward examples of idealized geophysical -fluid simulations and more involved cases encompassing -large scale modeling and -automatic differentiation. Both hydrostatic and non-hydrostatic -experiments are presented, as well as experiments employing -Cartesian, spherical-polar and cube-sphere coordinate systems. -These ``case study'' documents include information describing -the experimental configuration and detailed information on how to -configure the MITgcm code and input files for each experiment. - \section{A Rotating Tank in Cylindrical Coordinates} \label{sect:eg-tank} \label{www:tutorials} - -This example experiment demonstrates using the MITgcm to simulate -a Barotropic, wind-forced, ocean gyre circulation. The experiment -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}. - -In this experiment the model -is configured to represent a rectangular enclosed box of fluid, -$1200 \times 1200 $~km in lateral extent. The fluid is $5$~km deep and is forced -by a constant in time zonal wind stress, $\tau_x$, that varies sinusoidally -in the ``north-south'' direction. Topologically the grid is Cartesian and -the coriolis parameter $f$ is defined according to a mid-latitude beta-plane -equation - -\begin{equation} -\label{EQ:eg-baro-fcori} -f(y) = f_{0}+\beta y -\end{equation} - -\noindent where $y$ is the distance along the ``north-south'' axis of the -simulated domain. For this experiment $f_{0}$ is set to $10^{-4}s^{-1}$ in -(\ref{EQ:eg-baro-fcori}) and $\beta = 10^{-11}s^{-1}m^{-1}$. +This section illustrates an example of MITgcm simulating a laboratory +experiment on much smaller scales than those commonly considered in +geophysical +fluid dynamics. + +\subsection{Overview} +\label{www:tutorials} + + +This example configuration demonstrates using the MITgcm to simulate +a laboratory demonstration using a rotating tank of water with an ice +bucket in the center. The simulation is configured for a laboratory +scale on a +$3^{\circ}$ $\times$ 20cm +cyclindrical grid with twenty-nine vertical +levels. \\ +example illustration from GFD lab here \\ - The sinusoidal wind-stress variations are defined according to -\begin{equation} -\label{EQ:eg-baro-taux} -\tau_x(y) = \tau_{0}\sin(\pi \frac{y}{L_y}) -\end{equation} - -\noindent where $L_{y}$ is the lateral domain extent ($1200$~km) and -$\tau_0$ is set to $0.1N m^{-2}$. -\\ -\\ -Figure \ref{FIG:eg-baro-simulation_config} -summarizes the configuration simulated. -%% === eh3 === -\begin{figure} -%% \begin{center} -%% \resizebox{7.5in}{5.5in}{ -%% \includegraphics*[0.2in,0.7in][10.5in,10.5in] -%% {part3/case_studies/barotropic_gyre/simulation_config.eps} } -%% \end{center} -\centerline{ - \scalefig{.95} - \epsfbox{part3/case_studies/barotropic_gyre/simulation_config.eps} -} -\caption{Schematic of simulation domain and wind-stress forcing function -for barotropic gyre numerical experiment. The domain is enclosed bu solid -walls at $x=$~0,1200km and at $y=$~0,1200km.} -\label{FIG:eg-baro-simulation_config} -\end{figure} + + \subsection{Equations Solved} \label{www:tutorials} -The model is configured in hydrostatic form. 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 wind-stress momentum input is added to the momentum equation -for the ``zonal flow'', $u$. Other terms in the model -are explicitly switched off for this experiment configuration (see section -\ref{SEC:code_config} ), yielding an active set of equations solved in this -configuration as follows - -\begin{eqnarray} -\label{EQ:eg-baro-model_equations} -\frac{Du}{Dt} - fv + - g\frac{\partial \eta}{\partial x} - - A_{h}\nabla_{h}^2u -& = & -\frac{\tau_{x}}{\rho_{0}\Delta z} -\\ -\frac{Dv}{Dt} + fu + g\frac{\partial \eta}{\partial y} - - A_{h}\nabla_{h}^2v -& = & -0 -\\ -\frac{\partial \eta}{\partial t} + \nabla_{h}\cdot \vec{u} -&=& -0 -\end{eqnarray} - -\noindent where $u$ and $v$ and the $x$ and $y$ components of the -flow vector $\vec{u}$. -\\ \subsection{Discrete Numerical Configuration} \label{www:tutorials} The domain is discretised with -a uniform grid spacing in the horizontal set to - $\Delta x=\Delta y=20$~km, so -that there are sixty grid cells in the $x$ and $y$ directions. Vertically the -model is configured with a single layer with depth, $\Delta z$, of $5000$~m. - -\subsubsection{Numerical Stability Criteria} -\label{www:tutorials} - -The Laplacian dissipation coefficient, $A_{h}$, is set to $400 m s^{-1}$. -This value is chosen to yield a Munk layer width \cite{adcroft:95}, - -\begin{eqnarray} -\label{EQ:eg-baro-munk_layer} -M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}} -\end{eqnarray} - -\noindent of $\approx 100$km. This is greater than the model -resolution $\Delta x$, ensuring that the frictional boundary -layer is well resolved. +a uniform cylindrical grid spacing in the horizontal set to + $\Delta a=1$~cm and $\Delta \phi=3^{\circ}$, so +that there are 120 grid cells in the azimuthal direction and thirty-one grid cells in the radial. Vertically the +model is configured with twenty-nine layers of uniform 0.5cm thickness. \\ - -\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 \cite{adcroft:95} - - - -\begin{eqnarray} -\label{EQ:eg-baro-laplacian_stability} -S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2} -\end{eqnarray} - -\noindent evaluates to 0.012, which is well below the 0.3 upper limit -for stability. -\\ - -\noindent The numerical stability for inertial oscillations -\cite{adcroft:95} - -\begin{eqnarray} -\label{EQ:eg-baro-inertial_stability} -S_{i} = f^{2} {\delta t}^2 -\end{eqnarray} - -\noindent evaluates to $0.0144$, which is well below the $0.5$ upper -limit for stability. -\\ - -\noindent The advective CFL \cite{adcroft:95} for an extreme maximum -horizontal flow speed of $ | \vec{u} | = 2 ms^{-1}$ - -\begin{eqnarray} -\label{EQ:eg-baro-cfl_stability} -S_{a} = \frac{| \vec{u} | \delta t}{ \Delta x} -\end{eqnarray} - -\noindent evaluates to 0.12. This is approaching the stability limit -of 0.5 and limits $\delta t$ to $1200s$. +something about heat flux \subsection{Code Configuration} \label{www:tutorials} \label{SEC:eg-baro-code_config} -The model configuration for this experiment resides under the -directory {\it verification/exp0/}. The experiment files +The model configuration for this experiment resides under the +directory {\it verification/rotatingi\_tank/}. The experiment files \begin{itemize} \item {\it input/data} \item {\it input/data.pkg} \item {\it input/eedata}, -\item {\it input/windx.sin\_y}, -\item {\it input/topog.box}, +\item {\it input/bathyPol.bin}, +\item {\it input/thetaPol.bin}, \item {\it code/CPP\_EEOPTIONS.h} \item {\it code/CPP\_OPTIONS.h}, -\item {\it code/SIZE.h}. +\item {\it code/SIZE.h}. \end{itemize} + contain the code customizations and parameter settings for this experiments. Below we describe the customizations to these files associated with this experiment. @@ -212,98 +86,107 @@ \begin{itemize} -\item Line 7, \begin{verbatim} viscAh=4.E2, \end{verbatim} this line sets -the Laplacian friction coefficient to $400 m^2s^{-1}$ -\item Line 10, \begin{verbatim} beta=1.E-11, \end{verbatim} this line sets +\item Line 10, \begin{verbatim} viscAh=5.0E-6, \end{verbatim} this line sets +the Laplacian friction coefficient to $6 \times 10^{-6} m^2s^{-1}$, +which is ususally +low because of the small scale, presumably.... qqq + +\item Line 19, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the +coriolis term, and represents a tank spinning at 2/s +\item Line 20, \begin{verbatim} beta=1.E-11, \end{verbatim} this line sets $\beta$ (the gradient of the coriolis parameter, $f$) to $10^{-11} s^{-1}m^{-1}$ -\item Lines 15 and 16 +\item Lines 27 and 28 \begin{verbatim} -rigidLid=.FALSE., -implicitFreeSurface=.TRUE., +rigidLid=.TRUE., +implicitFreeSurface=.FALSE., \end{verbatim} -these lines suppress the rigid lid formulation of the surface + +qqq these lines do the opposite of the following: +suppress the rigid lid formulation of the surface pressure inverter and activate the implicit free surface form of the pressure inverter. -\item Line 27, +\item Line 44, \begin{verbatim} -startTime=0, +nIter=0, \end{verbatim} this line indicates that the experiment should start from $t=0$ and implicitly suppresses searching for checkpoint files associated with restarting an numerical integration from a previously saved state. -\item Line 29, -\begin{verbatim} -endTime=12000, -\end{verbatim} -this line indicates that the experiment should start finish at $t=12000s$. -A restart file will be written at this time that will enable the -simulation to be continued from this point. - -\item Line 30, +\item Line 47, \begin{verbatim} -deltaTmom=1200, +deltaT=0.1, \end{verbatim} -This line sets the momentum equation timestep to $1200s$. +This line sets the integration timestep to $0.1s$. This is an unsually +small value among the examples due to the small physical scale of the +experiment. -\item Line 39, +\item Line 58, \begin{verbatim} -usingCartesianGrid=.TRUE., +usingCylindricalGrid=.TRUE., \end{verbatim} This line requests that the simulation be performed in a -Cartesian coordinate system. +cylindrical coordinate system. -\item Line 41, +\item Line 60, \begin{verbatim} -delX=60*20E3, +dXspacing=3, \end{verbatim} -This line sets the horizontal grid spacing between each x-coordinate line +This line sets the azimuthal grid spacing between each $x$-coordinate line in the discrete grid. The syntax indicates that the discrete grid -should be comprise of $60$ grid lines each separated by $20 \times 10^{3}m$ -($20$~km). +should be comprise of $120$ grid lines each separated by $3^{\circ}$. + -\item Line 42, + +\item Line 61, \begin{verbatim} -delY=60*20E3, +dYspacing=0.01, \end{verbatim} -This line sets the horizontal grid spacing between each y-coordinate line -in the discrete grid to $20 \times 10^{3}m$ ($20$~km). +This line sets the radial cylindrical grid spacing between each $a$-coordinate line +in the discrete grid to $1cm$. -\item Line 43, +\item Line 62, \begin{verbatim} -delZ=5000, +delZ=29*0.005, \end{verbatim} This line sets the vertical grid spacing between each z-coordinate line in the discrete grid to $5000m$ ($5$~km). -\item Line 46, +\item Line 68, \begin{verbatim} -bathyFile='topog.box' +bathyFile='bathyPol.bin', \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 +``bathymetry'' (tank depth) is read. This file is a two-dimensional +($a,\phi$) 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 +giving the depth of the model at each grid cell, ordered with the $\phi$ coordinate varying fastest. The points are ordered from low coordinate -to high coordinate for both axes. The units and orientation of the +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 $-5000m$ indicates open ocean. The matlab program -{\it input/gendata.m} shows an example of how to generate a -bathymetry file. +experiment, a depth of $0m$ indicates an area outside of the tank +and a depth +f $-0.145m$ indicates the tank itself. +\item Line 67, +\begin{verbatim} +hydrogThetaFile='thetaPol.bin', +\end{verbatim} +This line specifies the name of the file from which the initial values +of temperature +are read. This file is a three-dimensional +($x,y,z$) map and is enumerated and formatted in the same manner as the +bathymetry file. -\item Line 49, +\item Line qqq \begin{verbatim} -zonalWindFile='windx.sin_y' + tCyl = 0 \end{verbatim} -This line specifies the name of the file from which the x-direction -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. +This line specifies the temperature in degrees Celsius of the interior +wall of the tank -- usually a bucket of ice water. + \end{itemize} @@ -312,7 +195,7 @@ notes. \begin{small} -\input{part3/case_studies/barotropic_gyre/input/data} +\input{part3/case_studies/rotating_tank/input/data} \end{small} \subsubsection{File {\it input/data.pkg}} @@ -327,28 +210,23 @@ This file uses standard default values and does not contain customizations for this experiment. -\subsubsection{File {\it input/windx.sin\_y}} +\subsubsection{File {\it input/thetaPol.bin}} \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}$. -Although $\tau_{x}$ is only a function of $y$n 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. The included matlab program {\it input/gendata.m} gives a complete -code for creating the {\it input/windx.sin\_y} file. +The {\it input/thetaPol.bin} file specifies a three-dimensional ($x,y,z$) +map of initial values of $\theta$ in degrees Celsius. This particular +experiment is set to random values x around 20C to provide initial +perturbations. -\subsubsection{File {\it input/topog.box}} +\subsubsection{File {\it input/bathyPol.bin}} \label{www:tutorials} -The {\it input/topog.box} file specifies a two-dimensional ($x,y$) +The {\it input/bathyPol.bin} file specifies a two-dimensional ($x,y$) map of depth values. For this experiment values are either -$0m$ or {\bf -delZ}m, corresponding respectively to a wall or to deep -ocean. The file contains a raw binary stream of data that is enumerated +$0m$ or {\bf -delZ}m, corresponding respectively to outside or inside of +the tank. The file contains a raw binary stream of data that is enumerated in the same way as standard MITgcm two-dimensional, horizontal arrays. -The included matlab program {\it input/gendata.m} gives a complete -code for creating the {\it input/topog.box} file. \subsubsection{File {\it code/SIZE.h}} \label{www:tutorials} @@ -358,19 +236,19 @@ \begin{itemize} \item Line 39, -\begin{verbatim} sNx=60, \end{verbatim} this line sets +\begin{verbatim} sNx=120, \end{verbatim} this line sets the lateral domain extent in grid points for the axis aligned with the x-coordinate. \item Line 40, -\begin{verbatim} sNy=60, \end{verbatim} this line sets +\begin{verbatim} sNy=31, \end{verbatim} this line sets the lateral domain extent in grid points for the axis aligned with the y-coordinate. \end{itemize} \begin{small} -\input{part3/case_studies/barotropic_gyre/code/SIZE.h} +\input{part3/case_studies/rotating_tank/code/SIZE.h} \end{small} \subsubsection{File {\it code/CPP\_OPTIONS.h}}