1 |
% $Header: /u/gcmpack/manual/part3/case_studies/fourlayer_gyre/fourlayer.tex,v 1.22 2006/06/28 18:57:15 jmc Exp $ |
2 |
% $Name: $ |
3 |
|
4 |
\section[Baroclinic Gyre MITgcm Example]{Four Layer Baroclinic Ocean Gyre In Spherical Coordinates} |
5 |
\label{www:tutorials} |
6 |
\label{sect:eg-fourlayer} |
7 |
\begin{rawhtml} |
8 |
<!-- CMIREDIR:eg-fourlayer: --> |
9 |
\end{rawhtml} |
10 |
\begin{center} |
11 |
(in directory: {\it verification/tutorial\_baroclinic\_gyre/}) |
12 |
\end{center} |
13 |
|
14 |
\bodytext{bgcolor="#FFFFFFFF"} |
15 |
|
16 |
%\begin{center} |
17 |
%{\Large \bf Using MITgcm to Simulate a Baroclinic Ocean Gyre In Spherical |
18 |
%Polar Coordinates} |
19 |
% |
20 |
%\vspace*{4mm} |
21 |
% |
22 |
%\vspace*{3mm} |
23 |
%{\large May 2001} |
24 |
%\end{center} |
25 |
|
26 |
This document describes an example experiment using MITgcm |
27 |
to simulate a baroclinic ocean gyre for four layers in spherical |
28 |
polar coordinates. The files for this experiment can be found |
29 |
in the verification directory under tutorial\_baroclinic\_gyre. |
30 |
|
31 |
\subsection{Overview} |
32 |
\label{www:tutorials} |
33 |
|
34 |
This example experiment demonstrates using the MITgcm to simulate |
35 |
a baroclinic, wind-forced, ocean gyre circulation. The experiment |
36 |
is a numerical rendition of the gyre circulation problem similar |
37 |
to the problems described analytically by Stommel in 1966 |
38 |
\cite{Stommel66} and numerically in Holland et. al \cite{Holland75}. |
39 |
\\ |
40 |
|
41 |
In this experiment the model is configured to represent a mid-latitude |
42 |
enclosed sector of fluid on a sphere, $60^{\circ} \times 60^{\circ}$ in |
43 |
lateral extent. The fluid is $2$~km deep and is forced |
44 |
by a constant in time zonal wind stress, $\tau_{\lambda}$, that varies |
45 |
sinusoidally in the north-south direction. Topologically the simulated |
46 |
domain is a sector on a sphere and the coriolis parameter, $f$, is defined |
47 |
according to latitude, $\varphi$ |
48 |
|
49 |
\begin{equation} |
50 |
\label{EQ:eg-fourlayer-fcori} |
51 |
f(\varphi) = 2 \Omega \sin( \varphi ) |
52 |
\end{equation} |
53 |
|
54 |
\noindent with the rotation rate, $\Omega$ set to $\frac{2 \pi}{86400s}$. |
55 |
\\ |
56 |
|
57 |
The sinusoidal wind-stress variations are defined according to |
58 |
|
59 |
\begin{equation} |
60 |
\label{EQ:taux} |
61 |
\tau_{\lambda}(\varphi) = \tau_{0}\sin(\pi \frac{\varphi}{L_{\varphi}}) |
62 |
\end{equation} |
63 |
|
64 |
\noindent where $L_{\varphi}$ is the lateral domain extent ($60^{\circ}$) and |
65 |
$\tau_0$ is set to $0.1N m^{-2}$. |
66 |
\\ |
67 |
|
68 |
Figure \ref{FIG:eg-fourlayer-simulation_config} |
69 |
summarizes the configuration simulated. |
70 |
In contrast to the example in section \ref{sect:eg-baro}, the |
71 |
current experiment simulates a spherical polar domain. As indicated |
72 |
by the axes in the lower left of the figure the model code works internally |
73 |
in a locally orthogonal coordinate $(x,y,z)$. For this experiment description |
74 |
the local orthogonal model coordinate $(x,y,z)$ is synonymous |
75 |
with the coordinates $(\lambda,\varphi,r)$ shown in figure |
76 |
\ref{fig:spherical-polar-coord} |
77 |
\\ |
78 |
|
79 |
The experiment has four levels in the vertical, each of equal thickness, |
80 |
$\Delta z = 500$~m. Initially the fluid is stratified with a reference |
81 |
potential temperature profile, |
82 |
$\theta_{250}=20^{\circ}$~C, |
83 |
$\theta_{750}=10^{\circ}$~C, |
84 |
$\theta_{1250}=8^{\circ}$~C, |
85 |
$\theta_{1750}=6^{\circ}$~C. The equation of state used in this experiment is |
86 |
linear |
87 |
|
88 |
\begin{equation} |
89 |
\label{EQ:eg-fourlayer-linear1_eos} |
90 |
\rho = \rho_{0} ( 1 - \alpha_{\theta}\theta^{'} ) |
91 |
\end{equation} |
92 |
|
93 |
\noindent which is implemented in the model as a density anomaly equation |
94 |
|
95 |
\begin{equation} |
96 |
\label{EQ:eg-fourlayer-linear1_eos_pert} |
97 |
\rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'} |
98 |
\end{equation} |
99 |
|
100 |
\noindent with $\rho_{0}=999.8\,{\rm kg\,m}^{-3}$ and |
101 |
$\alpha_{\theta}=2\times10^{-4}\,{\rm degrees}^{-1} $. Integrated forward in |
102 |
this configuration the model state variable {\bf theta} is equivalent to |
103 |
either in-situ temperature, $T$, or potential temperature, $\theta$. For |
104 |
consistency with later examples, in which the equation of state is |
105 |
non-linear, we use $\theta$ to represent temperature here. This is |
106 |
the quantity that is carried in the model core equations. |
107 |
|
108 |
\begin{figure} |
109 |
%% \begin{center} |
110 |
%% \resizebox{7.5in}{5.5in}{ |
111 |
%% \includegraphics*[0.2in,0.7in][10.5in,10.5in] |
112 |
%% {part3/case_studies/fourlayer_gyre/simulation_config.eps} } |
113 |
%% \end{center} |
114 |
\centerline{ |
115 |
\scalefig{.95} |
116 |
\epsfbox{part3/case_studies/fourlayer_gyre/simulation_config.eps} |
117 |
} |
118 |
\caption{Schematic of simulation domain and wind-stress forcing function |
119 |
for the four-layer gyre numerical experiment. The domain is enclosed by solid |
120 |
walls at $0^{\circ}$~E, $60^{\circ}$~E, $0^{\circ}$~N and $60^{\circ}$~N. |
121 |
An initial stratification is |
122 |
imposed by setting the potential temperature, $\theta$, in each layer. |
123 |
The vertical spacing, $\Delta z$, is constant and equal to $500$m. |
124 |
} |
125 |
\label{FIG:eg-fourlayer-simulation_config} |
126 |
\end{figure} |
127 |
|
128 |
\subsection{Equations solved} |
129 |
\label{www:tutorials} |
130 |
For this problem |
131 |
the implicit free surface, {\bf HPE} (see section \ref{sect:hydrostatic_and_quasi-hydrostatic_forms}) form of the |
132 |
equations described in Marshall et. al \cite{marshall:97a} are |
133 |
employed. The flow is three-dimensional with just temperature, $\theta$, as |
134 |
an active tracer. The equation of state is linear. |
135 |
A horizontal Laplacian operator $\nabla_{h}^2$ provides viscous |
136 |
dissipation and provides a diffusive sub-grid scale closure for the |
137 |
temperature equation. A wind-stress momentum forcing is added to the momentum |
138 |
equation for the zonal flow, $u$. Other terms in the model |
139 |
are explicitly switched off for this experiment configuration (see section |
140 |
\ref{SEC:eg_fourl_code_config} ). This yields an active set of equations |
141 |
solved in this configuration, written in spherical polar coordinates as |
142 |
follows |
143 |
|
144 |
\begin{eqnarray} |
145 |
\label{EQ:eg-fourlayer-model_equations} |
146 |
\frac{Du}{Dt} - fv + |
147 |
\frac{1}{\rho}\frac{\partial p^{\prime}}{\partial \lambda} - |
148 |
A_{h}\nabla_{h}^2u - A_{z}\frac{\partial^{2}u}{\partial z^{2}} |
149 |
& = & |
150 |
\cal{F}_{\lambda} |
151 |
\\ |
152 |
\frac{Dv}{Dt} + fu + |
153 |
\frac{1}{\rho}\frac{\partial p^{\prime}}{\partial \varphi} - |
154 |
A_{h}\nabla_{h}^2v - A_{z}\frac{\partial^{2}v}{\partial z^{2}} |
155 |
& = & |
156 |
0 |
157 |
\\ |
158 |
\frac{\partial \eta}{\partial t} + \frac{\partial H \widehat{u}}{\partial \lambda} + |
159 |
\frac{\partial H \widehat{v}}{\partial \varphi} |
160 |
&=& |
161 |
0 |
162 |
\label{eq:fourl_example_continuity} |
163 |
\\ |
164 |
\frac{D\theta}{Dt} - |
165 |
K_{h}\nabla_{h}^2\theta - K_{z}\frac{\partial^{2}\theta}{\partial z^{2}} |
166 |
& = & |
167 |
0 |
168 |
\label{eq:eg_fourl_theta} |
169 |
\\ |
170 |
p^{\prime} & = & |
171 |
g\rho_{0} \eta + \int^{0}_{-z}\rho^{\prime} dz |
172 |
\\ |
173 |
\rho^{\prime} & = &- \alpha_{\theta}\rho_{0}\theta^{\prime} |
174 |
\\ |
175 |
{\cal F}_{\lambda} |_{s} & = & \frac{\tau_{\lambda}}{\rho_{0}\Delta z_{s}} |
176 |
\\ |
177 |
{\cal F}_{\lambda} |_{i} & = & 0 |
178 |
\end{eqnarray} |
179 |
|
180 |
\noindent where $u$ and $v$ are the components of the horizontal |
181 |
flow vector $\vec{u}$ on the sphere ($u=\dot{\lambda},v=\dot{\varphi}$). |
182 |
The terms $H\widehat{u}$ and $H\widehat{v}$ are the components of the vertical |
183 |
integral term given in equation \ref{eq:free-surface} and |
184 |
explained in more detail in section \ref{sect:pressure-method-linear-backward}. |
185 |
However, for the problem presented here, the continuity relation (equation |
186 |
\ref{eq:fourl_example_continuity}) differs from the general form given |
187 |
in section \ref{sect:pressure-method-linear-backward}, |
188 |
equation \ref{eq:linear-free-surface=P-E+R}, because the source terms |
189 |
${\cal P}-{\cal E}+{\cal R}$ |
190 |
are all $0$. |
191 |
|
192 |
The pressure field, $p^{\prime}$, is separated into a barotropic part |
193 |
due to variations in sea-surface height, $\eta$, and a hydrostatic |
194 |
part due to variations in density, $\rho^{\prime}$, integrated |
195 |
through the water column. |
196 |
|
197 |
The suffices ${s},{i}$ indicate surface layer and the interior of the domain. |
198 |
The windstress forcing, ${\cal F}_{\lambda}$, is applied in the surface layer |
199 |
by a source term in the zonal momentum equation. In the ocean interior |
200 |
this term is zero. |
201 |
|
202 |
In the momentum equations |
203 |
lateral and vertical boundary conditions for the $\nabla_{h}^{2}$ |
204 |
and $\frac{\partial^{2}}{\partial z^{2}}$ operators are specified |
205 |
when the numerical simulation is run - see section |
206 |
\ref{SEC:eg_fourl_code_config}. For temperature |
207 |
the boundary condition is ``zero-flux'' |
208 |
e.g. $\frac{\partial \theta}{\partial \varphi}= |
209 |
\frac{\partial \theta}{\partial \lambda}=\frac{\partial \theta}{\partial z}=0$. |
210 |
|
211 |
|
212 |
|
213 |
\subsection{Discrete Numerical Configuration} |
214 |
\label{www:tutorials} |
215 |
|
216 |
The domain is discretised with |
217 |
a uniform grid spacing in latitude and longitude |
218 |
$\Delta \lambda=\Delta \varphi=1^{\circ}$, so |
219 |
that there are sixty grid cells in the zonal and meridional directions. |
220 |
Vertically the |
221 |
model is configured with four layers with constant depth, |
222 |
$\Delta z$, of $500$~m. The internal, locally orthogonal, model coordinate |
223 |
variables $x$ and $y$ are initialized from the values of |
224 |
$\lambda$, $\varphi$, $\Delta \lambda$ and $\Delta \varphi$ in |
225 |
radians according to |
226 |
|
227 |
\begin{eqnarray} |
228 |
x=r\cos(\varphi)\lambda,~\Delta x & = &r\cos(\varphi)\Delta \lambda \\ |
229 |
y=r\varphi,~\Delta y &= &r\Delta \varphi |
230 |
\end{eqnarray} |
231 |
|
232 |
The procedure for generating a set of internal grid variables from a |
233 |
spherical polar grid specification is discussed in section |
234 |
\ref{sect:spatial_discrete_horizontal_grid}. |
235 |
|
236 |
\noindent\fbox{ \begin{minipage}{5.5in} |
237 |
{\em S/R INI\_SPHERICAL\_POLAR\_GRID} ({\em |
238 |
model/src/ini\_spherical\_polar\_grid.F}) |
239 |
|
240 |
$A_c$, $A_\zeta$, $A_w$, $A_s$: {\bf rAc}, {\bf rAz}, {\bf rAw}, {\bf rAs} |
241 |
({\em GRID.h}) |
242 |
|
243 |
$\Delta x_g$, $\Delta y_g$: {\bf DXg}, {\bf DYg} ({\em GRID.h}) |
244 |
|
245 |
$\Delta x_c$, $\Delta y_c$: {\bf DXc}, {\bf DYc} ({\em GRID.h}) |
246 |
|
247 |
$\Delta x_f$, $\Delta y_f$: {\bf DXf}, {\bf DYf} ({\em GRID.h}) |
248 |
|
249 |
$\Delta x_v$, $\Delta y_u$: {\bf DXv}, {\bf DYu} ({\em GRID.h}) |
250 |
|
251 |
\end{minipage} }\\ |
252 |
|
253 |
|
254 |
|
255 |
As described in \ref{sect:tracer_equations}, the time evolution of potential |
256 |
temperature, |
257 |
$\theta$, (equation \ref{eq:eg_fourl_theta}) |
258 |
is evaluated prognostically. The centered second-order scheme with |
259 |
Adams-Bashforth time stepping described in section |
260 |
\ref{sect:tracer_equations_abII} is used to step forward the temperature |
261 |
equation. Prognostic terms in |
262 |
the momentum equations are solved using flux form as |
263 |
described in section \ref{sect:flux-form_momentum_eqautions}. |
264 |
The pressure forces that drive the fluid motions, ( |
265 |
$\frac{\partial p^{'}}{\partial \lambda}$ and $\frac{\partial p^{'}}{\partial \varphi}$), are found by summing pressure due to surface |
266 |
elevation $\eta$ and the hydrostatic pressure. The hydrostatic part of the |
267 |
pressure is diagnosed explicitly by integrating density. The sea-surface |
268 |
height, $\eta$, is diagnosed using an implicit scheme. The pressure |
269 |
field solution method is described in sections |
270 |
\ref{sect:pressure-method-linear-backward} and |
271 |
\ref{sect:finding_the_pressure_field}. |
272 |
|
273 |
\subsubsection{Numerical Stability Criteria} |
274 |
\label{www:tutorials} |
275 |
|
276 |
The Laplacian viscosity coefficient, $A_{h}$, is set to $400 m s^{-1}$. |
277 |
This value is chosen to yield a Munk layer width, |
278 |
|
279 |
\begin{eqnarray} |
280 |
\label{EQ:eg-fourlayer-munk_layer} |
281 |
M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}} |
282 |
\end{eqnarray} |
283 |
|
284 |
\noindent of $\approx 100$km. This is greater than the model |
285 |
resolution in mid-latitudes |
286 |
$\Delta x=r \cos(\varphi) \Delta \lambda \approx 80~{\rm km}$ at |
287 |
$\varphi=45^{\circ}$, ensuring that the frictional |
288 |
boundary layer is well resolved. |
289 |
\\ |
290 |
|
291 |
\noindent The model is stepped forward with a |
292 |
time step $\delta t=1200$secs. With this time step the stability |
293 |
parameter to the horizontal Laplacian friction |
294 |
|
295 |
\begin{eqnarray} |
296 |
\label{EQ:eg-fourlayer-laplacian_stability} |
297 |
S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2} |
298 |
\end{eqnarray} |
299 |
|
300 |
\noindent evaluates to 0.012, which is well below the 0.3 upper limit |
301 |
for stability for this term under ABII time-stepping. |
302 |
\\ |
303 |
|
304 |
\noindent The vertical dissipation coefficient, $A_{z}$, is set to |
305 |
$1\times10^{-2} {\rm m}^2{\rm s}^{-1}$. The associated stability limit |
306 |
|
307 |
\begin{eqnarray} |
308 |
\label{EQ:eg-fourlayer-laplacian_stability_z} |
309 |
S_{l} = 4 \frac{A_{z} \delta t}{{\Delta z}^2} |
310 |
\end{eqnarray} |
311 |
|
312 |
\noindent evaluates to $4.8 \times 10^{-5}$ which is again well below |
313 |
the upper limit. |
314 |
The values of $A_{h}$ and $A_{z}$ are also used for the horizontal ($K_{h}$) |
315 |
and vertical ($K_{z}$) diffusion coefficients for temperature respectively. |
316 |
\\ |
317 |
|
318 |
\noindent The numerical stability for inertial oscillations |
319 |
|
320 |
\begin{eqnarray} |
321 |
\label{EQ:eg-fourlayer-inertial_stability} |
322 |
S_{i} = f^{2} {\delta t}^2 |
323 |
\end{eqnarray} |
324 |
|
325 |
\noindent evaluates to $0.0144$, which is well below the $0.5$ upper |
326 |
limit for stability. |
327 |
\\ |
328 |
|
329 |
\noindent The advective CFL for a extreme maximum |
330 |
horizontal flow |
331 |
speed of $ | \vec{u} | = 2 ms^{-1}$ |
332 |
|
333 |
\begin{eqnarray} |
334 |
\label{EQ:eg-fourlayer-cfl_stability} |
335 |
C_{a} = \frac{| \vec{u} | \delta t}{ \Delta x} |
336 |
\end{eqnarray} |
337 |
|
338 |
\noindent evaluates to $5 \times 10^{-2}$. This is well below the stability |
339 |
limit of 0.5. |
340 |
\\ |
341 |
|
342 |
\noindent The stability parameter for internal gravity waves |
343 |
propagating at $2~{\rm m}~{\rm s}^{-1}$ |
344 |
|
345 |
\begin{eqnarray} |
346 |
\label{EQ:eg-fourlayer-igw_stability} |
347 |
S_{c} = \frac{c_{g} \delta t}{ \Delta x} |
348 |
\end{eqnarray} |
349 |
|
350 |
\noindent evaluates to $\approx 5 \times 10^{-2}$. This is well below the linear |
351 |
stability limit of 0.25. |
352 |
|
353 |
\subsection{Code Configuration} |
354 |
\label{www:tutorials} |
355 |
\label{SEC:eg_fourl_code_config} |
356 |
|
357 |
The model configuration for this experiment resides under the |
358 |
directory {\it verification/tutorial\_barotropic\_gyre/}. |
359 |
The experiment files |
360 |
\begin{itemize} |
361 |
\item {\it input/data} |
362 |
\item {\it input/data.pkg} |
363 |
\item {\it input/eedata}, |
364 |
\item {\it input/windx.sin\_y}, |
365 |
\item {\it input/topog.box}, |
366 |
\item {\it code/CPP\_EEOPTIONS.h} |
367 |
\item {\it code/CPP\_OPTIONS.h}, |
368 |
\item {\it code/SIZE.h}. |
369 |
\end{itemize} |
370 |
contain the code customisations and parameter settings for this |
371 |
experiment. Below we describe the customisations to these files |
372 |
associated with this experiment. |
373 |
|
374 |
\subsubsection{File {\it input/data}} |
375 |
\label{www:tutorials} |
376 |
|
377 |
This file, reproduced completely below, specifies the main parameters |
378 |
for the experiment. The parameters that are significant for this configuration |
379 |
are |
380 |
|
381 |
\begin{itemize} |
382 |
|
383 |
\item Line 4, |
384 |
\begin{verbatim} tRef=20.,10.,8.,6., \end{verbatim} |
385 |
this line sets the initial and reference values of potential |
386 |
temperature at each model level in units of $^{\circ}\mathrm{C}$. The entries |
387 |
are ordered from surface to depth. For each depth level the initial |
388 |
and reference profiles will be uniform in $x$ and $y$. The values |
389 |
specified here are read into the variable \varlink{tRef}{tRef} in the |
390 |
model code, by procedure \filelink{INI\_PARMS}{model-src-ini_parms.F} |
391 |
|
392 |
\fbox{ |
393 |
\begin{minipage}{5.0in} |
394 |
{\it S/R INI\_THETA}({\it ini\_theta.F}) |
395 |
\end{minipage} |
396 |
} |
397 |
\filelink{ini\_theta.F}{model-src-ini_theta.F} |
398 |
|
399 |
\item Line 6, |
400 |
\begin{verbatim} viscAz=1.E-2, \end{verbatim} |
401 |
this line sets the vertical Laplacian dissipation coefficient to $1 |
402 |
\times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary conditions for this |
403 |
operator are specified later. The variable \varlink{viscAz}{viscAz} |
404 |
is read in the routine \filelink{ini\_parms.F}{model-src-ini_parms.F} |
405 |
and is copied into model general vertical coordinate variable |
406 |
\varlink{viscAr}{viscAr} At each time step, the viscous term |
407 |
contribution to the momentum equations is calculated in routine |
408 |
\varlink{CALC\_DIFFUSIVITY}{CALC_DIFFUSIVITY} |
409 |
|
410 |
\fbox{ |
411 |
\begin{minipage}{5.0in} |
412 |
{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F}) |
413 |
\end{minipage} |
414 |
} |
415 |
|
416 |
\item Line 7, |
417 |
\begin{verbatim} |
418 |
viscAh=4.E2, |
419 |
\end{verbatim} |
420 |
this line sets the horizontal laplacian frictional dissipation |
421 |
coefficient to $1 \times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary |
422 |
conditions for this operator are specified later. The variable |
423 |
\varlink{viscAh}{viscAh} is read in the routine |
424 |
\varlink{INI\_PARMS}{INI_PARMS} and applied in routine |
425 |
\varlink{MOM\_FLUXFORM}{MOM_FLUXFORM}. |
426 |
|
427 |
\fbox{ |
428 |
\begin{minipage}{5.0in} |
429 |
{\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F}) |
430 |
\end{minipage} |
431 |
} |
432 |
|
433 |
\item Line 8, |
434 |
\begin{verbatim} |
435 |
no_slip_sides=.FALSE. |
436 |
\end{verbatim} |
437 |
this line selects a free-slip lateral boundary condition for the |
438 |
horizontal laplacian friction operator e.g. $\frac{\partial |
439 |
u}{\partial y}$=0 along boundaries in $y$ and $\frac{\partial |
440 |
v}{\partial x}$=0 along boundaries in $x$. The variable |
441 |
\varlink{no\_slip\_sides}{no_slip_sides} is read in the routine |
442 |
\varlink{INI\_PARMS}{INI_PARMS} and the boundary condition is |
443 |
evaluated in routine |
444 |
|
445 |
\fbox{ |
446 |
\begin{minipage}{5.0in} |
447 |
{\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F}) |
448 |
\end{minipage} |
449 |
} |
450 |
\filelink{mom\_fluxform.F}{pkg-mom_fluxform-mom_fluxform.F} |
451 |
|
452 |
\item Lines 9, |
453 |
\begin{verbatim} |
454 |
no_slip_bottom=.TRUE. |
455 |
\end{verbatim} |
456 |
this line selects a no-slip boundary condition for bottom boundary |
457 |
condition in the vertical laplacian friction operator e.g. $u=v=0$ |
458 |
at $z=-H$, where $H$ is the local depth of the domain. The variable |
459 |
\varlink{no\_slip\_bottom}{no\_slip\_bottom} is read in the routine |
460 |
\filelink{INI\_PARMS}{model-src-ini_parms.F} and is applied in the |
461 |
routine \varlink{MOM\_FLUXFORM}{MOM_FLUXFORM}. |
462 |
|
463 |
\fbox{ |
464 |
\begin{minipage}{5.0in} |
465 |
{\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F}) |
466 |
\end{minipage} |
467 |
} |
468 |
\filelink{mom\_fluxform.F}{pkg-mom_fluxform-mom_fluxform.F} |
469 |
|
470 |
\item Line 10, |
471 |
\begin{verbatim} |
472 |
diffKhT=4.E2, |
473 |
\end{verbatim} |
474 |
this line sets the horizontal diffusion coefficient for temperature |
475 |
to $400\,{\rm m^{2}s^{-1}}$. The boundary condition on this operator |
476 |
is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ at |
477 |
all boundaries. The variable \varlink{diffKhT}{diffKhT} is read in |
478 |
the routine \varlink{INI\_PARMS}{INI_PARMS} and used in routine |
479 |
\varlink{CALC\_GT}{CALC_GT}. |
480 |
|
481 |
\fbox{ \begin{minipage}{5.0in} |
482 |
{\it S/R CALC\_GT}({\it calc\_gt.F}) |
483 |
\end{minipage} |
484 |
} |
485 |
\filelink{calc\_gt.F}{model-src-calc_gt.F} |
486 |
|
487 |
\item Line 11, |
488 |
\begin{verbatim} |
489 |
diffKzT=1.E-2, |
490 |
\end{verbatim} |
491 |
this line sets the vertical diffusion coefficient for temperature to |
492 |
$10^{-2}\,{\rm m^{2}s^{-1}}$. The boundary condition on this |
493 |
operator is $\frac{\partial}{\partial z}$ = 0 on all boundaries. |
494 |
The variable \varlink{diffKzT}{diffKzT} is read in the routine |
495 |
\varlink{INI\_PARMS}{INI_PARMS}. It is copied into model general |
496 |
vertical coordinate variable \varlink{diffKrT}{diffKrT} which is |
497 |
used in routine \varlink{CALC\_DIFFUSIVITY}{CALC_DIFFUSIVITY}. |
498 |
|
499 |
\fbox{ \begin{minipage}{5.0in} |
500 |
{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F}) |
501 |
\end{minipage} |
502 |
} |
503 |
\filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F} |
504 |
|
505 |
\item Line 13, |
506 |
\begin{verbatim} |
507 |
tAlpha=2.E-4, |
508 |
\end{verbatim} |
509 |
This line sets the thermal expansion coefficient for the fluid to $2 |
510 |
\times 10^{-4}\,{\rm degrees}^{-1}$ The variable |
511 |
\varlink{tAlpha}{tAlpha} is read in the routine |
512 |
\varlink{INI\_PARMS}{INI_PARMS}. The routine |
513 |
\varlink{FIND\_RHO}{FIND\_RHO} makes use of {\bf tAlpha}. |
514 |
|
515 |
\fbox{ |
516 |
\begin{minipage}{5.0in} |
517 |
{\it S/R FIND\_RHO}({\it find\_rho.F}) |
518 |
\end{minipage} |
519 |
} |
520 |
\filelink{find\_rho.F}{model-src-find_rho.F} |
521 |
|
522 |
\item Line 18, |
523 |
\begin{verbatim} |
524 |
eosType='LINEAR' |
525 |
\end{verbatim} |
526 |
This line selects the linear form of the equation of state. The |
527 |
variable \varlink{eosType}{eosType} is read in the routine |
528 |
\varlink{INI\_PARMS}{INI_PARMS}. The values of {\bf eosType} sets |
529 |
which formula in routine {\it FIND\_RHO} is used to calculate |
530 |
density. |
531 |
|
532 |
\fbox{ |
533 |
\begin{minipage}{5.0in} |
534 |
{\it S/R FIND\_RHO}({\it find\_rho.F}) |
535 |
\end{minipage} |
536 |
} |
537 |
\filelink{find\_rho.F}{model-src-find_rho.F} |
538 |
|
539 |
\item Line 40, |
540 |
\begin{verbatim} |
541 |
usingSphericalPolarGrid=.TRUE., |
542 |
\end{verbatim} |
543 |
This line requests that the simulation be performed in a spherical |
544 |
polar coordinate system. It affects the interpretation of grid input |
545 |
parameters, for example {\bf delX} and {\bf delY} and causes the |
546 |
grid generation routines to initialize an internal grid based on |
547 |
spherical polar geometry. The variable |
548 |
\varlink{usingSphericalPolarGrid}{usingSphericalPolarGrid} is read |
549 |
in the routine \varlink{INI\_PARMS}{INI_PARMS}. When set to {\bf |
550 |
.TRUE.} the settings of {\bf delX} and {\bf delY} are taken to be |
551 |
in degrees. These values are used in the routine |
552 |
|
553 |
\fbox{ |
554 |
\begin{minipage}{5.0in} |
555 |
{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) |
556 |
\end{minipage} |
557 |
} |
558 |
\filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} |
559 |
|
560 |
\item Line 41, |
561 |
\begin{verbatim} |
562 |
phiMin=0., |
563 |
\end{verbatim} |
564 |
This line sets the southern boundary of the modeled domain to |
565 |
$0^{\circ}$ latitude. This value affects both the generation of the |
566 |
locally orthogonal grid that the model uses internally and affects |
567 |
the initialization of the coriolis force. Note - it is not required |
568 |
to set a longitude boundary, since the absolute longitude does not |
569 |
alter the kernel equation discretisation. The variable |
570 |
\varlink{phiMin}{phiMin} is read in the |
571 |
routine \varlink{INI\_PARMS}{INI_PARMS} and is used in routine |
572 |
|
573 |
\fbox{ |
574 |
\begin{minipage}{5.0in} |
575 |
{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) |
576 |
\end{minipage} |
577 |
} |
578 |
\filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} |
579 |
|
580 |
\item Line 42, |
581 |
\begin{verbatim} |
582 |
delX=60*1., |
583 |
\end{verbatim} |
584 |
This line sets the horizontal grid spacing between each y-coordinate |
585 |
line in the discrete grid to $1^{\circ}$ in longitude. The variable |
586 |
\varlink{delX}{delX} is read in the routine |
587 |
\varlink{INI\_PARMS}{INI_PARMS} and is used in routine |
588 |
|
589 |
\fbox{ |
590 |
\begin{minipage}{5.0in} |
591 |
{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) |
592 |
\end{minipage} |
593 |
} |
594 |
\filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} |
595 |
|
596 |
\item Line 43, |
597 |
\begin{verbatim} |
598 |
delY=60*1., |
599 |
\end{verbatim} |
600 |
This line sets the horizontal grid spacing between each y-coordinate |
601 |
line in the discrete grid to $1^{\circ}$ in latitude. The variable |
602 |
\varlink{delY}{delY} is read in the routine |
603 |
\varlink{INI\_PARMS}{INI_PARMS} and is used in routine |
604 |
|
605 |
\fbox{ |
606 |
\begin{minipage}{5.0in} |
607 |
{\it S/R INI\_SPEHRICAL\_POLAR\_GRID}({\it ini\_spherical\_polar\_grid.F}) |
608 |
\end{minipage} |
609 |
} |
610 |
\filelink{ini\_spherical\_polar\_grid.F}{model-src-ini_spherical_polar_grid.F} |
611 |
|
612 |
\item Line 44, |
613 |
\begin{verbatim} |
614 |
delZ=500.,500.,500.,500., |
615 |
\end{verbatim} |
616 |
This line sets the vertical grid spacing between each z-coordinate |
617 |
line in the discrete grid to $500\,{\rm m}$, so that the total model |
618 |
depth is $2\,{\rm km}$. The variable \varlink{delZ}{delZ} is read |
619 |
in the routine \varlink{INI\_PARMS}{INI_PARMS}. It is copied into |
620 |
the internal model coordinate variable \varlink{delR}{delR} which is |
621 |
used in routine |
622 |
|
623 |
\fbox{ |
624 |
\begin{minipage}{5.0in} |
625 |
{\it S/R INI\_VERTICAL\_GRID}({\it ini\_vertical\_grid.F}) |
626 |
\end{minipage} |
627 |
} |
628 |
\filelink{ini\_vertical\_grid.F}{model-src-ini_vertical_grid.F} |
629 |
|
630 |
\item Line 47, |
631 |
\begin{verbatim} |
632 |
bathyFile='topog.box' |
633 |
\end{verbatim} |
634 |
This line specifies the name of the file from which the domain |
635 |
bathymetry is read. This file is a two-dimensional ($x,y$) map of |
636 |
depths. This file is assumed to contain 64-bit binary numbers giving |
637 |
the depth of the model at each grid cell, ordered with the x |
638 |
coordinate varying fastest. The points are ordered from low |
639 |
coordinate to high coordinate for both axes. The units and |
640 |
orientation of the depths in this file are the same as used in the |
641 |
MITgcm code. In this experiment, a depth of $0m$ indicates a solid |
642 |
wall and a depth of $-2000m$ indicates open ocean. The matlab |
643 |
program {\it input/gendata.m} shows an example of how to generate a |
644 |
bathymetry file. The variable \varlink{bathyFile}{bathyFile} is |
645 |
read in the routine \varlink{INI\_PARMS}{INI_PARMS}. The bathymetry |
646 |
file is read in the routine |
647 |
|
648 |
\fbox{ |
649 |
\begin{minipage}{5.0in} |
650 |
{\it S/R INI\_DEPTHS}({\it ini\_depths.F}) |
651 |
\end{minipage} |
652 |
} |
653 |
\filelink{ini\_depths.F}{model-src-ini_depths.F} |
654 |
|
655 |
\item Line 50, |
656 |
\begin{verbatim} |
657 |
zonalWindFile='windx.sin_y' |
658 |
\end{verbatim} |
659 |
This line specifies the name of the file from which the x-direction |
660 |
(zonal) surface wind stress is read. This file is also a |
661 |
two-dimensional ($x,y$) map and is enumerated and formatted in the |
662 |
same manner as the bathymetry file. The matlab program {\it |
663 |
input/gendata.m} includes example code to generate a valid {\bf |
664 |
zonalWindFile} file. The variable |
665 |
\varlink{zonalWindFile}{zonalWindFile} is read in the routine |
666 |
\varlink{INI\_PARMS}{INI_PARMS}. The wind-stress file is read in |
667 |
the routine |
668 |
|
669 |
\fbox{ |
670 |
\begin{minipage}{5.0in} |
671 |
{\it S/R EXTERNAL\_FIELDS\_LOAD}({\it external\_fields\_load.F}) |
672 |
\end{minipage} |
673 |
} |
674 |
\filelink{external\_fields\_load.F}{model-src-external_fields_load.F} |
675 |
|
676 |
\end{itemize} |
677 |
|
678 |
\noindent other lines in the file {\it input/data} are standard values. |
679 |
|
680 |
\begin{rawhtml}<PRE>\end{rawhtml} |
681 |
\begin{small} |
682 |
\input{part3/case_studies/fourlayer_gyre/input/data} |
683 |
\end{small} |
684 |
\begin{rawhtml}</PRE>\end{rawhtml} |
685 |
|
686 |
\subsubsection{File {\it input/data.pkg}} |
687 |
\label{www:tutorials} |
688 |
|
689 |
This file uses standard default values and does not contain |
690 |
customisations for this experiment. |
691 |
|
692 |
\subsubsection{File {\it input/eedata}} |
693 |
\label{www:tutorials} |
694 |
|
695 |
This file uses standard default values and does not contain |
696 |
customisations for this experiment. |
697 |
|
698 |
\subsubsection{File {\it input/windx.sin\_y}} |
699 |
\label{www:tutorials} |
700 |
|
701 |
The {\it input/windx.sin\_y} file specifies a two-dimensional ($x,y$) |
702 |
map of wind stress ,$\tau_{x}$, values. The units used are $Nm^{-2}$ |
703 |
(the default for MITgcm). Although $\tau_{x}$ is only a function of |
704 |
latitude, $y$, in this experiment this file must still define a |
705 |
complete two-dimensional map in order to be compatible with the |
706 |
standard code for loading forcing fields in MITgcm (routine {\it |
707 |
EXTERNAL\_FIELDS\_LOAD}. The included matlab program {\it |
708 |
input/gendata.m} gives a complete code for creating the {\it |
709 |
input/windx.sin\_y} file. |
710 |
|
711 |
\subsubsection{File {\it input/topog.box}} |
712 |
\label{www:tutorials} |
713 |
|
714 |
|
715 |
The {\it input/topog.box} file specifies a two-dimensional ($x,y$) |
716 |
map of depth values. For this experiment values are either |
717 |
$0~{\rm m}$ or $-2000\,{\rm m}$, corresponding respectively to a wall or to deep |
718 |
ocean. The file contains a raw binary stream of data that is enumerated |
719 |
in the same way as standard MITgcm two-dimensional, horizontal arrays. |
720 |
The included matlab program {\it input/gendata.m} gives a complete |
721 |
code for creating the {\it input/topog.box} file. |
722 |
|
723 |
\subsubsection{File {\it code/SIZE.h}} |
724 |
\label{www:tutorials} |
725 |
|
726 |
Two lines are customized in this file for the current experiment |
727 |
|
728 |
\begin{itemize} |
729 |
|
730 |
\item Line 39, |
731 |
\begin{verbatim} sNx=60, \end{verbatim} this line sets |
732 |
the lateral domain extent in grid points for the |
733 |
axis aligned with the x-coordinate. |
734 |
|
735 |
\item Line 40, |
736 |
\begin{verbatim} sNy=60, \end{verbatim} this line sets |
737 |
the lateral domain extent in grid points for the |
738 |
axis aligned with the y-coordinate. |
739 |
|
740 |
\item Line 49, |
741 |
\begin{verbatim} Nr=4, \end{verbatim} this line sets |
742 |
the vertical domain extent in grid points. |
743 |
|
744 |
\end{itemize} |
745 |
|
746 |
\begin{small} |
747 |
\include{part3/case_studies/fourlayer_gyre/code/SIZE.h} |
748 |
\end{small} |
749 |
|
750 |
\subsubsection{File {\it code/CPP\_OPTIONS.h}} |
751 |
\label{www:tutorials} |
752 |
|
753 |
This file uses standard default values and does not contain |
754 |
customisations for this experiment. |
755 |
|
756 |
|
757 |
\subsubsection{File {\it code/CPP\_EEOPTIONS.h}} |
758 |
\label{www:tutorials} |
759 |
|
760 |
This file uses standard default values and does not contain |
761 |
customisations for this experiment. |
762 |
|
763 |
\subsubsection{Other Files } |
764 |
\label{www:tutorials} |
765 |
|
766 |
Other files relevant to this experiment are |
767 |
\begin{itemize} |
768 |
\item {\it model/src/ini\_cori.F}. This file initializes the model |
769 |
coriolis variables {\bf fCorU} and {\bf fCorV}. |
770 |
\item {\it model/src/ini\_spherical\_polar\_grid.F} This file |
771 |
initializes the model grid discretisation variables {\bf |
772 |
dxF, dyF, dxG, dyG, dxC, dyC}. |
773 |
\item {\it model/src/ini\_parms.F}. |
774 |
\end{itemize} |
775 |
|
776 |
\subsection{Running The Example} |
777 |
\label{www:tutorials} |
778 |
\label{SEC:running_the_example} |
779 |
|
780 |
\subsubsection{Code Download} |
781 |
\label{www:tutorials} |
782 |
|
783 |
In order to run the examples you must first download the code distribution. |
784 |
Instructions for downloading the code can be found in section |
785 |
\ref{sect:obtainingCode}. |
786 |
|
787 |
\subsubsection{Experiment Location} |
788 |
\label{www:tutorials} |
789 |
|
790 |
This example experiments is located under the release sub-directory |
791 |
|
792 |
\vspace{5mm} |
793 |
{\it verification/exp2/ } |
794 |
|
795 |
\subsubsection{Running the Experiment} |
796 |
\label{www:tutorials} |
797 |
|
798 |
To run the experiment |
799 |
|
800 |
\begin{enumerate} |
801 |
\item Set the current directory to {\it input/ } |
802 |
|
803 |
\begin{verbatim} |
804 |
% cd input |
805 |
\end{verbatim} |
806 |
|
807 |
\item Verify that current directory is now correct |
808 |
|
809 |
\begin{verbatim} |
810 |
% pwd |
811 |
\end{verbatim} |
812 |
|
813 |
You should see a response on the screen ending in |
814 |
|
815 |
{\it verification/exp2/input } |
816 |
|
817 |
|
818 |
\item Run the genmake script to create the experiment {\it Makefile} |
819 |
|
820 |
\begin{verbatim} |
821 |
% ../../../tools/genmake -mods=../code |
822 |
\end{verbatim} |
823 |
|
824 |
\item Create a list of header file dependencies in {\it Makefile} |
825 |
|
826 |
\begin{verbatim} |
827 |
% make depend |
828 |
\end{verbatim} |
829 |
|
830 |
\item Build the executable file. |
831 |
|
832 |
\begin{verbatim} |
833 |
% make |
834 |
\end{verbatim} |
835 |
|
836 |
\item Run the {\it mitgcmuv} executable |
837 |
|
838 |
\begin{verbatim} |
839 |
% ./mitgcmuv |
840 |
\end{verbatim} |
841 |
|
842 |
\end{enumerate} |
843 |
|
844 |
|