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	% $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}