s_examples/global_oce_latlon/inp_data.templ

% $Header: /u/gcmpack/manual/s_examples/global_oce_latlon/climatalogical_ogcm.tex,v 1.19 2010/08/30 23:09:20 jmc Exp $
% $Name:  $

%\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
are

\begin{itemize}

\item Lines 7-10 and 11-14 
\begin{verbatim} tRef= 16.0 , 15.2 , 14.5 , 13.9 , 13.3 ,  \end{verbatim} 
$\cdots$ \\
set reference values for potential
temperature and salinity at each model level in units of $^{\circ}\mathrm{C}$ and
${\rm ppt}$. The entries are ordered from surface to depth.
Density is calculated from anomalies at each level evaluated
with respect to the reference values set here.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R INI\_THETA}({\it ini\_theta.F})
\end{minipage}
}


\item Line 15, 
\begin{verbatim} viscAz=1.E-3, \end{verbatim}
this line sets the vertical Laplacian dissipation coefficient to
$1 \times 10^{-3} {\rm m^{2}s^{-1}}$. Boundary conditions
for this operator are specified later. This variable is copied into
model general vertical coordinate variable {\bf viscAr}.

\fbox{
\begin{minipage}{5.0in}
{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F})
\end{minipage}
}

\item Line 16, 
\begin{verbatim}
viscAh=5.E5,
\end{verbatim} 
this line sets the horizontal Laplacian frictional dissipation coefficient to
$5 \times 10^{5} {\rm m^{2}s^{-1}}$. Boundary conditions
for this operator are specified later.

\item Lines 17,
\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$.

\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.

\item Line 19,
\begin{verbatim}
diffKhT=1.E3,
\end{verbatim}
this line sets the horizontal diffusion coefficient for temperature
to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
all boundaries.

\item Line 20,
\begin{verbatim}
diffKzT=3.E-5,
\end{verbatim}
this line sets the vertical diffusion coefficient for temperature
to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary 
condition on this operator is $\frac{\partial}{\partial z}=0$ at both
the upper and lower boundaries.

\item Line 21,
\begin{verbatim}
diffKhS=1.E3,
\end{verbatim}
this line sets the horizontal diffusion coefficient for salinity
to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
all boundaries.

\item Line 22,
\begin{verbatim}
diffKzS=3.E-5,
\end{verbatim}
this line sets the vertical diffusion coefficient for salinity
to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary 
condition on this operator is $\frac{\partial}{\partial z}=0$ at both
the upper and lower boundaries.

\item Lines 23-26
\begin{verbatim}
beta=1.E-11,
\end{verbatim}
\vspace{-5mm}$\cdots$\\
These settings do not apply for this experiment.

\item Line 27,
\begin{verbatim}
gravity=9.81,
\end{verbatim}
Sets the gravitational acceleration coefficient to $9.81{\rm m}{\rm s}^{-1}$.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R CALC\_PHI\_HYD}~({\it calc\_phi\_hyd.F})\\
{\it S/R INI\_CG2D}~({\it ini\_cg2d.F})\\
{\it S/R INI\_CG3D}~({\it ini\_cg3d.F})\\
{\it S/R INI\_PARMS}~({\it ini\_parms.F})\\
{\it S/R SOLVE\_FOR\_PRESSURE}~({\it solve\_for\_pressure.F})
\end{minipage}
}


\item Line 28-29,
\begin{verbatim}
rigidLid=.FALSE., 
implicitFreeSurface=.TRUE., 
\end{verbatim}
Selects the barotropic pressure equation to be the implicit free surface
formulation.

\item Line 30,
\begin{verbatim}
eosType='POLY3',
\end{verbatim}
Selects the third order polynomial form of the equation of state.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R FIND\_RHO}~({\it find\_rho.F})\\
{\it S/R FIND\_ALPHA}~({\it find\_alpha.F})
\end{minipage}
}

\item Line 31,
\begin{verbatim}
readBinaryPrec=32,
\end{verbatim}
Sets format for reading binary input datasets holding model fields to
use 32-bit representation for floating-point numbers.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R READ\_WRITE\_FLD}~({\it read\_write\_fld.F})\\
{\it S/R READ\_WRITE\_REC}~({\it read\_write\_rec.F})
\end{minipage}
}

\item Line 36,
\begin{verbatim}
cg2dMaxIters=1000,
\end{verbatim}
Sets maximum number of iterations the two-dimensional, conjugate
gradient solver will use, {\bf irrespective of convergence 
criteria being met}.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R CG2D}~({\it cg2d.F})
\end{minipage}
}

\item Line 37,
\begin{verbatim}
cg2dTargetResidual=1.E-13,
\end{verbatim}
Sets the tolerance which the two-dimensional, conjugate
gradient solver will use to test for convergence in equation 
%- note: Description of Conjugate gradient method (& related params) is missing
%  in the mean time, substitute this eq ref:
\ref{eq:elliptic-backward-free-surface} %\ref{eq:congrad_2d_resid} 
to $1 \times 10^{-13}$.
Solver will iterate until tolerance falls below this value or until the 
maximum number of solver iterations is reached.\\
\fbox{
\begin{minipage}{5.0in}
{\it S/R CG2D}~({\it cg2d.F})
\end{minipage}
}

\item Line 42,
\begin{verbatim}
startTime=0,
\end{verbatim}
Sets the starting time for the model internal time counter.
When set to non-zero this option implicitly requests a 
checkpoint file be read for initial state.
By default the checkpoint file is named according to
the integer number of time steps in the {\bf startTime} value.
The internal time counter works in seconds.

\item Line 43,
\begin{verbatim}
endTime=2808000.,
\end{verbatim}
Sets the time (in seconds) at which this simulation will terminate.
At the end of a simulation a checkpoint file is automatically
written so that a numerical experiment can consist of multiple
stages.

\item Line 44,
\begin{verbatim}
#endTime=62208000000,
\end{verbatim}
A commented out setting for endTime for a 2000 year simulation.

\item Line 45,
\begin{verbatim}
deltaTmom=2400.0,
\end{verbatim}
Sets the timestep $\delta t_{v}$ used in the momentum equations to
$20~{\rm mins}$.
%- note: Distord Physics (using different time-steps) is not described
%  in the mean time, put this section ref:
See section \ref{sec:time_stepping}. %\ref{sec:mom_time_stepping}.

\fbox{
\begin{minipage}{5.0in}
{\it S/R TIMESTEP}({\it timestep.F})
\end{minipage}
}

\item Line 46,
\begin{verbatim}
tauCD=321428.,
\end{verbatim}
Sets the D-grid to C-grid coupling time scale $\tau_{CD}$ 
used in the momentum equations.
%- note: description of CD-scheme pkg (and related params) is missing;
%  in the mean time, comment out this ref.
%See section \ref{sec:cd_scheme}.

\fbox{
\begin{minipage}{5.0in}
{\it S/R INI\_PARMS}({\it ini\_parms.F})\\
{\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F})
\end{minipage}
}

\item Line 47,
\begin{verbatim}
deltaTtracer=108000.,
\end{verbatim}
Sets the default timestep, $\delta t_{\theta}$, for tracer equations to
$30~{\rm hours}$.
%- note: Distord Physics (using different time-steps) is not described
%  in the mean time, put this section ref:
See section \ref{sec:time_stepping}. %\ref{sec:tracer_time_stepping}.

\fbox{
\begin{minipage}{5.0in}
{\it S/R TIMESTEP\_TRACER}({\it timestep\_tracer.F})
\end{minipage}
}

\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.


\item Line 50,
\begin{verbatim}
zonalWindFile='windx.sin_y'
\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.  

\end{itemize}

\noindent other lines in the file {\it input/data} are standard values
that are described in the MITgcm Getting Started and MITgcm Parameters
notes.

\begin{small}
\input{s_examples/global_oce_latlon/input/data}
\end{small}

1	jmc	1.1	% $Header: /u/gcmpack/manual/s_examples/global_oce_latlon/climatalogical_ogcm.tex,v 1.19 2010/08/30 23:09:20 jmc Exp $
2			% $Name: $
3
4			%\subsubsection{File {\it input/data}}
5			%\label{www:tutorials}
6
7			This file, reproduced completely below, specifies the main parameters
8			for the experiment. The parameters that are significant for this configuration
9			are
10
11			\begin{itemize}
12
13			\item Lines 7-10 and 11-14
14			\begin{verbatim} tRef= 16.0 , 15.2 , 14.5 , 13.9 , 13.3 , \end{verbatim}
15			$\cdots$ \\
16			set reference values for potential
17			temperature and salinity at each model level in units of $^{\circ}\mathrm{C}$ and
18			${\rm ppt}$. The entries are ordered from surface to depth.
19			Density is calculated from anomalies at each level evaluated
20			with respect to the reference values set here.\\
21			\fbox{
22			\begin{minipage}{5.0in}
23			{\it S/R INI\_THETA}({\it ini\_theta.F})
24			\end{minipage}
25			}
26
27
28			\item Line 15,
29			\begin{verbatim} viscAz=1.E-3, \end{verbatim}
30			this line sets the vertical Laplacian dissipation coefficient to
31			$1 \times 10^{-3} {\rm m^{2}s^{-1}}$. Boundary conditions
32			for this operator are specified later. This variable is copied into
33			model general vertical coordinate variable {\bf viscAr}.
34
35			\fbox{
36			\begin{minipage}{5.0in}
37			{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F})
38			\end{minipage}
39			}
40
41			\item Line 16,
42			\begin{verbatim}
43			viscAh=5.E5,
44			\end{verbatim}
45			this line sets the horizontal Laplacian frictional dissipation coefficient to
46			$5 \times 10^{5} {\rm m^{2}s^{-1}}$. Boundary conditions
47			for this operator are specified later.
48
49			\item Lines 17,
50			\begin{verbatim}
51			no_slip_sides=.FALSE.
52			\end{verbatim}
53			this line selects a free-slip lateral boundary condition for
54			the horizontal Laplacian friction operator
55			e.g. $\frac{\partial u}{\partial y}$=0 along boundaries in $y$ and
56			$\frac{\partial v}{\partial x}$=0 along boundaries in $x$.
57
58			\item Lines 9,
59			\begin{verbatim}
60			no_slip_bottom=.TRUE.
61			\end{verbatim}
62			this line selects a no-slip boundary condition for bottom
63			boundary condition in the vertical Laplacian friction operator
64			e.g. $u=v=0$ at $z=-H$, where $H$ is the local depth of the domain.
65
66			\item Line 19,
67			\begin{verbatim}
68			diffKhT=1.E3,
69			\end{verbatim}
70			this line sets the horizontal diffusion coefficient for temperature
71			to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
72			operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
73			all boundaries.
74
75			\item Line 20,
76			\begin{verbatim}
77			diffKzT=3.E-5,
78			\end{verbatim}
79			this line sets the vertical diffusion coefficient for temperature
80			to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary
81			condition on this operator is $\frac{\partial}{\partial z}=0$ at both
82			the upper and lower boundaries.
83
84			\item Line 21,
85			\begin{verbatim}
86			diffKhS=1.E3,
87			\end{verbatim}
88			this line sets the horizontal diffusion coefficient for salinity
89			to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
90			operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
91			all boundaries.
92
93			\item Line 22,
94			\begin{verbatim}
95			diffKzS=3.E-5,
96			\end{verbatim}
97			this line sets the vertical diffusion coefficient for salinity
98			to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary
99			condition on this operator is $\frac{\partial}{\partial z}=0$ at both
100			the upper and lower boundaries.
101
102			\item Lines 23-26
103			\begin{verbatim}
104			beta=1.E-11,
105			\end{verbatim}
106			\vspace{-5mm}$\cdots$\\
107			These settings do not apply for this experiment.
108
109			\item Line 27,
110			\begin{verbatim}
111			gravity=9.81,
112			\end{verbatim}
113			Sets the gravitational acceleration coefficient to $9.81{\rm m}{\rm s}^{-1}$.\\
114			\fbox{
115			\begin{minipage}{5.0in}
116			{\it S/R CALC\_PHI\_HYD}~({\it calc\_phi\_hyd.F})\\
117			{\it S/R INI\_CG2D}~({\it ini\_cg2d.F})\\
118			{\it S/R INI\_CG3D}~({\it ini\_cg3d.F})\\
119			{\it S/R INI\_PARMS}~({\it ini\_parms.F})\\
120			{\it S/R SOLVE\_FOR\_PRESSURE}~({\it solve\_for\_pressure.F})
121			\end{minipage}
122			}
123
124
125			\item Line 28-29,
126			\begin{verbatim}
127			rigidLid=.FALSE.,
128			implicitFreeSurface=.TRUE.,
129			\end{verbatim}
130			Selects the barotropic pressure equation to be the implicit free surface
131			formulation.
132
133			\item Line 30,
134			\begin{verbatim}
135			eosType='POLY3',
136			\end{verbatim}
137			Selects the third order polynomial form of the equation of state.\\
138			\fbox{
139			\begin{minipage}{5.0in}
140			{\it S/R FIND\_RHO}~({\it find\_rho.F})\\
141			{\it S/R FIND\_ALPHA}~({\it find\_alpha.F})
142			\end{minipage}
143			}
144
145			\item Line 31,
146			\begin{verbatim}
147			readBinaryPrec=32,
148			\end{verbatim}
149			Sets format for reading binary input datasets holding model fields to
150			use 32-bit representation for floating-point numbers.\\
151			\fbox{
152			\begin{minipage}{5.0in}
153			{\it S/R READ\_WRITE\_FLD}~({\it read\_write\_fld.F})\\
154			{\it S/R READ\_WRITE\_REC}~({\it read\_write\_rec.F})
155			\end{minipage}
156			}
157
158			\item Line 36,
159			\begin{verbatim}
160			cg2dMaxIters=1000,
161			\end{verbatim}
162			Sets maximum number of iterations the two-dimensional, conjugate
163			gradient solver will use, {\bf irrespective of convergence
164			criteria being met}.\\
165			\fbox{
166			\begin{minipage}{5.0in}
167			{\it S/R CG2D}~({\it cg2d.F})
168			\end{minipage}
169			}
170
171			\item Line 37,
172			\begin{verbatim}
173			cg2dTargetResidual=1.E-13,
174			\end{verbatim}
175			Sets the tolerance which the two-dimensional, conjugate
176			gradient solver will use to test for convergence in equation
177			%- note: Description of Conjugate gradient method (& related params) is missing
178			% in the mean time, substitute this eq ref:
179			\ref{eq:elliptic-backward-free-surface} %\ref{eq:congrad_2d_resid}
180			to $1 \times 10^{-13}$.
181			Solver will iterate until tolerance falls below this value or until the
182			maximum number of solver iterations is reached.\\
183			\fbox{
184			\begin{minipage}{5.0in}
185			{\it S/R CG2D}~({\it cg2d.F})
186			\end{minipage}
187			}
188
189			\item Line 42,
190			\begin{verbatim}
191			startTime=0,
192			\end{verbatim}
193			Sets the starting time for the model internal time counter.
194			When set to non-zero this option implicitly requests a
195			checkpoint file be read for initial state.
196			By default the checkpoint file is named according to
197			the integer number of time steps in the {\bf startTime} value.
198			The internal time counter works in seconds.
199
200			\item Line 43,
201			\begin{verbatim}
202			endTime=2808000.,
203			\end{verbatim}
204			Sets the time (in seconds) at which this simulation will terminate.
205			At the end of a simulation a checkpoint file is automatically
206			written so that a numerical experiment can consist of multiple
207			stages.
208
209			\item Line 44,
210			\begin{verbatim}
211			#endTime=62208000000,
212			\end{verbatim}
213			A commented out setting for endTime for a 2000 year simulation.
214
215			\item Line 45,
216			\begin{verbatim}
217			deltaTmom=2400.0,
218			\end{verbatim}
219			Sets the timestep $\delta t_{v}$ used in the momentum equations to
220			$20~{\rm mins}$.
221			%- note: Distord Physics (using different time-steps) is not described
222			% in the mean time, put this section ref:
223			See section \ref{sec:time_stepping}. %\ref{sec:mom_time_stepping}.
224
225			\fbox{
226			\begin{minipage}{5.0in}
227			{\it S/R TIMESTEP}({\it timestep.F})
228			\end{minipage}
229			}
230
231			\item Line 46,
232			\begin{verbatim}
233			tauCD=321428.,
234			\end{verbatim}
235			Sets the D-grid to C-grid coupling time scale $\tau_{CD}$
236			used in the momentum equations.
237			%- note: description of CD-scheme pkg (and related params) is missing;
238			% in the mean time, comment out this ref.
239			%See section \ref{sec:cd_scheme}.
240
241			\fbox{
242			\begin{minipage}{5.0in}
243			{\it S/R INI\_PARMS}({\it ini\_parms.F})\\
244			{\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F})
245			\end{minipage}
246			}
247
248			\item Line 47,
249			\begin{verbatim}
250			deltaTtracer=108000.,
251			\end{verbatim}
252			Sets the default timestep, $\delta t_{\theta}$, for tracer equations to
253			$30~{\rm hours}$.
254			%- note: Distord Physics (using different time-steps) is not described
255			% in the mean time, put this section ref:
256			See section \ref{sec:time_stepping}. %\ref{sec:tracer_time_stepping}.
257
258			\fbox{
259			\begin{minipage}{5.0in}
260			{\it S/R TIMESTEP\_TRACER}({\it timestep\_tracer.F})
261			\end{minipage}
262			}
263
264			\item Line 47,
265			\begin{verbatim}
266			bathyFile='topog.box'
267			\end{verbatim}
268			This line specifies the name of the file from which the domain
269			bathymetry is read. This file is a two-dimensional ($x,y$) map of
270			depths. This file is assumed to contain 64-bit binary numbers
271			giving the depth of the model at each grid cell, ordered with the x
272			coordinate varying fastest. The points are ordered from low coordinate
273			to high coordinate for both axes. The units and orientation of the
274			depths in this file are the same as used in the MITgcm code. In this
275			experiment, a depth of $0m$ indicates a solid wall and a depth
276			of $-2000m$ indicates open ocean. The matlab program
277			{\it input/gendata.m} shows an example of how to generate a
278			bathymetry file.
279
280
281			\item Line 50,
282			\begin{verbatim}
283			zonalWindFile='windx.sin_y'
284			\end{verbatim}
285			This line specifies the name of the file from which the x-direction
286			surface wind stress is read. This file is also a two-dimensional
287			($x,y$) map and is enumerated and formatted in the same manner as the
288			bathymetry file. The matlab program {\it input/gendata.m} includes example
289			code to generate a valid
290			{\bf zonalWindFile}
291			file.
292
293			\end{itemize}
294
295			\noindent other lines in the file {\it input/data} are standard values
296			that are described in the MITgcm Getting Started and MITgcm Parameters
297			notes.
298
299			\begin{small}
300			\input{s_examples/global_oce_latlon/input/data}
301			\end{small}
302