s_phys_pkgs/text/rbcs.tex

\subsection {RBCS Package} 
\label{sec:pkg:rbcs}
\begin{rawhtml}
<!-- CMIREDIR:package_rbcs: -->
\end{rawhtml}

\subsubsection {Introduction}

A package which provides the flexibility
to relax fields (temperature, salinity, ptracers)
in any 3-D location:
so could be used as a sponge layer, or as a
"source" anywhere in the domain.

\noindent
For a tracer ($T$) at every grid point the tendency is modified so that:
\[
\frac{dT}{dt}=\frac{dT}{dt} - \frac{M_{rbc}}{\tau_T} (T-T_{rbc})
\]

\noindent
where $M_{rbc}$ is a 3-D mask (no time dependence) with
values between 0 and 1. Where $M_{rbc}$ is 1, relaxing timescale
is $1/\tau_T$. Where it is 0 there is no relaxing.
The value relaxed to is a 3-D (potentially varying in
time) field given by $T_{rbc}$. 

A seperate mask can be used for T,S and ptracers and
each of these
can be relaxed or not and can have its own timescale
$\tau_T$. These are set in data.rbcs (see below).

\subsubsection {Key subroutines and parameters}

The only change need in the code might be in {RBCS.h}, for
PARAMETER(maskLEN = 3 ), if you need more than 3
masks (see below).

\vspace{.5cm}

\noindent
There are runtime parameters
set in {\it data.rbcs}:\\
These runtime options include\\
Set in {RBCS\_PARM01}:\\
%$\bullet$ Parameters to set the timing for periodic fields to
%relax to are to
%be loaded are:
$\bullet$ {\bf rbcsForcingPeriod}, {\bf rbcsForcingCycle}: timing of
fields to relax to.
The former is how often to load, the latter is how often to cycle
through those fields (eg. period could be monthly and cycle one year).
rbcs\_ForcingCycle=0 means non-cyclic forcing, and
rbcs\_ForcingPeriod=0 non-time-varying forcing, where the relax field
is only read in at the beginning of the run and kept constant
the rest of the run. Default is 0.
\\
$\bullet$  {\bf rbcsForcingOffset}: time offset of forcing fields (in seconds).
If the forcing fields are time averages over forcing periods,
then this must be set to the time at the beginning of the
first forcing period.  The fields will then be placed at time
rbcsForcingOffset+rbcsForcingPeriod/2 for interpolation.  Default is 0.
If you use snapshots and the first snapshot is at $t_1$, you need to set
\[
  {\rm rbcsForcingOffset} = t_1 - {\rm rbcsForcingPeriod}/2
\]
(This used to be rbcsInIter and was in units of iterations.)\\
$\bullet$  {\bf rbcsSingleTimeFiles}: true or false (default false),
if true, forcing fields are given 1 file per time labeled by iteration number.\\
$\bullet$  {\bf deltaTrbcs}: time step used to compute the iteration numbers
for rbcsSingleTimeFiles=T.\\
$\bullet$  {\bf rbcsIter0}: shift in iteration numbers used to label files if
rbcsSingleTimeFiles=T (default 0).  If the file for the first forcing period
(as specified by rbcsForcingOffset) has label $i_1$, you need to set
\[
  {\rm rbcsIter0} = i_1 - {\rm rbcsForcingPeriod}/{\rm deltaTrbcs}
\]
$\bullet$  {\bf useRBCtemp}: true or false (default false)\\
$\bullet$  {\bf useRBCsalt}: true or false (default false)\\
$\bullet$  {\bf useRBCptracers}: true or false (default false), must be using
ptracers to set true\\
$\bullet$  {\bf tauRelaxT}: timescale in seconds of relaxing
in temperature ($\tau_T$ in equation above). 
Where mask is 1, relax rate will be
1/tauRelaxT. Default is 1.\\
$\bullet$  {\bf tauRelaxS}: same for salinity.\\
$\bullet$  {\bf relaxMaskFile(irbc)}: filename of 3-D file
with mask ($M_{rbc}$ in equation above. 
Need a file for each irbc. 1=temperature,
2=salinity, 3=ptracer01, 4=ptracer02 etc. If the mask numbers
end (see maskLEN) are less than the number tracers, then
relaxMaskFile(maskLEN) is used for all remaining ptracers.\\
$\bullet$  {\bf relaxTFile}: name of file where temperatures
that need to be realxed to ($T_{rbc}$ in equation above)
are stored. Need 3-D fields to
match model domain, and as many entries as given by
rbcsForcingPeriod and rbcsForcingCycle.\\
$\bullet$  {\bf relaxSFile}: same for salinity.\\

\vspace{.5cm}
\noindent
Set in {RBCS\_PARM02} for each of the ptracers (iTrc):\\
$\bullet$ {\bf useRBCptrnum(iTrc)}: true or false (default
is false).\\
$\bullet$ {\bf tauRelaxPTR(iTrc)}: relax timescale.\\
$\bullet$ {\bf relaxPtracerFile(iTrc)}: file with relax
fields.\\

\noindent
Typical ways of specifying timing of relaxation fields:
\begin{enumerate}
\item Constant-in-time forcing:
  \begin{quote}
     rbcsForcingPeriod = 0
  \end{quote}
  One field is read and used for all times.  Use this to emulate the result of
  rbcsForcingCycle=0 before 2010-11-10.

\item Non-cyclic time-varying forcing:
  \begin{quote}
     rbcsForcingPeriod = period in seconds\\
     rbcsForcingCycle = 0
  \end{quote}
  When starting the run at time 0 (as usually the case), a period with center before
  or at time 0 is needed for time interpolation.  If you are not providing separate
  files for each time (rbcsSingleTimeFiles=F), rbcsForcingOffset needs to be negative.
  For aligned periods (one period starting at time 0) and one extra record before
  time 0 (and ending at time 0), set rbcsForcingOffset${}=-$Period.
  For other situations, see the description of rbcsForcingOffset above.

\item Cyclic Forcing:
  \begin{quote}
     rbcsForcingPeriod = period in seconds\\
     rbcsForcingCycle = cycle in seconds
  \end{quote}
  The same comment as for non-cyclic forcing applies, but rbcsForcingOffset may now be
  after the time of the first required record even with rbcsSingleTimeFiles=F, in which
  case records from the end of the file will be used (via cyclicity).
\end{enumerate}

\noindent
Ways to organize the files:
\begin{enumerate}
\item One big file with many time records:
  \begin{quote}
     rbcsSingleTimeFiles = .FALSE.
  \end{quote}
  All time records are in one big file.

\item A separate file for each time:
  \begin{quote}
     rbcsSingleTimeFiles = .TRUE.\\
     deltaTrbcs = time step used to generate forcing files\\
     rbcsIter0 = iteration number of first file $-$ rbcsForcingPeriod/deltaTrbcs
  \end{quote}
  The rbcs field for each time needed is in a separate file, labeled by the
  iteration number at the end of the forcing period.  If a different timestep
  was used for generating the files (and the file names), set deltaTrbcs to it.
  If there is a shift in time, set rbcsIter0.
\end{enumerate}


\subsubsection{Do's and Don'ts}

\subsubsection{Reference Material}

\subsubsection{Experiments and tutorials that use rbcs}
\label{sec:pkg:rbcs:experiments}

In the directory \code{verifcation}, the following experiments use
\code{rbcs}:
\begin{itemize}
\item \code{exp4}: box with 4 open boundaries, simulating flow over a
  Gaussian bump based on \citet{adcroft:97}.
\end{itemize}


%%% \end{itemize}

1	stephd	1.1	\subsection {RBCS Package}
2			\label{sec:pkg:rbcs}
3			\begin{rawhtml}
4			<!-- CMIREDIR:package_rbcs: -->
5			\end{rawhtml}
6
7			\subsubsection {Introduction}
8
9			A package which provides the flexibility
10			to relax fields (temperature, salinity, ptracers)
11			in any 3-D location:
12			so could be used as a sponge layer, or as a
13			"source" anywhere in the domain.
14
15			\noindent
16			For a tracer ($T$) at every grid point the tendency is modified so that:
17			\[
18			\frac{dT}{dt}=\frac{dT}{dt} - \frac{M_{rbc}}{\tau_T} (T-T_{rbc})
19			\]
20
21			\noindent
22			where $M_{rbc}$ is a 3-D mask (no time dependence) with
23			values between 0 and 1. Where $M_{rbc}$ is 1, relaxing timescale
24			is $1/\tau_T$. Where it is 0 there is no relaxing.
25			The value relaxed to is a 3-D (potentially varying in
26			time) field given by $T_{rbc}$.
27
28			A seperate mask can be used for T,S and ptracers and
29			each of these
30			can be relaxed or not and can have its own timescale
31			$\tau_T$. These are set in data.rbcs (see below).
32
33			\subsubsection {Key subroutines and parameters}
34
35	jahn	1.3	The only change need in the code might be in {RBCS.h}, for
36	stephd	1.1	PARAMETER(maskLEN = 3 ), if you need more than 3
37			masks (see below).
38
39			\vspace{.5cm}
40
41			\noindent
42			There are runtime parameters
43			set in {\it data.rbcs}:\\
44			These runtime options include\\
45			Set in {RBCS\_PARM01}:\\
46	jahn	1.3	%$\bullet$ Parameters to set the timing for periodic fields to
47			%relax to are to
48			%be loaded are:
49			$\bullet$ {\bf rbcsForcingPeriod}, {\bf rbcsForcingCycle}: timing of
50			fields to relax to.
51	stephd	1.1	The former is how often to load, the latter is how often to cycle
52	jahn	1.3	through those fields (eg. period could be monthly and cycle one year).
53			rbcs\_ForcingCycle=0 means non-cyclic forcing, and
54			rbcs\_ForcingPeriod=0 non-time-varying forcing, where the relax field
55	stephd	1.1	is only read in at the beginning of the run and kept constant
56			the rest of the run. Default is 0.
57			\\
58	jahn	1.4	$\bullet$ {\bf rbcsForcingOffset}: time offset of forcing fields (in seconds).
59			If the forcing fields are time averages over forcing periods,
60			then this must be set to the time at the beginning of the
61			first forcing period. The fields will then be placed at time
62			rbcsForcingOffset+rbcsForcingPeriod/2 for interpolation. Default is 0.
63			If you use snapshots and the first snapshot is at $t_1$, you need to set
64			\[
65			{\rm rbcsForcingOffset} = t_1 - {\rm rbcsForcingPeriod}/2
66			\]
67			(This used to be rbcsInIter and was in units of iterations.)\\
68			$\bullet$ {\bf rbcsSingleTimeFiles}: true or false (default false),
69			if true, forcing fields are given 1 file per time labeled by iteration number.\\
70			$\bullet$ {\bf deltaTrbcs}: time step used to compute the iteration numbers
71			for rbcsSingleTimeFiles=T.\\
72			$\bullet$ {\bf rbcsIter0}: shift in iteration numbers used to label files if
73			rbcsSingleTimeFiles=T (default 0). If the file for the first forcing period
74			(as specified by rbcsForcingOffset) has label $i_1$, you need to set
75			\[
76			{\rm rbcsIter0} = i_1 - {\rm rbcsForcingPeriod}/{\rm deltaTrbcs}
77			\]
78	stephd	1.1	$\bullet$ {\bf useRBCtemp}: true or false (default false)\\
79			$\bullet$ {\bf useRBCsalt}: true or false (default false)\\
80			$\bullet$ {\bf useRBCptracers}: true or false (default false), must be using
81			ptracers to set true\\
82			$\bullet$ {\bf tauRelaxT}: timescale in seconds of relaxing
83			in temperature ($\tau_T$ in equation above).
84			Where mask is 1, relax rate will be
85	jahn	1.4	1/tauRelaxT. Default is 1.\\
86			$\bullet$ {\bf tauRelaxS}: same for salinity.\\
87	stephd	1.1	$\bullet$ {\bf relaxMaskFile(irbc)}: filename of 3-D file
88			with mask ($M_{rbc}$ in equation above.
89			Need a file for each irbc. 1=temperature,
90			2=salinity, 3=ptracer01, 4=ptracer02 etc. If the mask numbers
91			end (see maskLEN) are less than the number tracers, then
92			relaxMaskFile(maskLEN) is used for all remaining ptracers.\\
93			$\bullet$ {\bf relaxTFile}: name of file where temperatures
94			that need to be realxed to ($T_{rbc}$ in equation above)
95			are stored. Need 3-D fields to
96			match model domain, and as many entries as given by
97			rbcsForcingPeriod and rbcsForcingCycle.\\
98			$\bullet$ {\bf relaxSFile}: same for salinity.\\
99
100			\vspace{.5cm}
101			\noindent
102			Set in {RBCS\_PARM02} for each of the ptracers (iTrc):\\
103			$\bullet$ {\bf useRBCptrnum(iTrc)}: true or false (default
104			is false).\\
105			$\bullet$ {\bf tauRelaxPTR(iTrc)}: relax timescale.\\
106			$\bullet$ {\bf relaxPtracerFile(iTrc)}: file with relax
107			fields.\\
108
109	jahn	1.3	\noindent
110			Typical ways of specifying timing of relaxation fields:
111			\begin{enumerate}
112			\item Constant-in-time forcing:
113			\begin{quote}
114			rbcsForcingPeriod = 0
115			\end{quote}
116			One field is read and used for all times. Use this to emulate the result of
117			rbcsForcingCycle=0 before 2010-11-10.
118
119			\item Non-cyclic time-varying forcing:
120			\begin{quote}
121			rbcsForcingPeriod = period in seconds\\
122	jahn	1.4	rbcsForcingCycle = 0
123	jahn	1.3	\end{quote}
124			When starting the run at time 0 (as usually the case), a period with center before
125	jahn	1.4	or at time 0 is needed for time interpolation. If you are not providing separate
126			files for each time (rbcsSingleTimeFiles=F), rbcsForcingOffset needs to be negative.
127	jahn	1.3	For aligned periods (one period starting at time 0) and one extra record before
128	jahn	1.4	time 0 (and ending at time 0), set rbcsForcingOffset${}=-$Period.
129			For other situations, see the description of rbcsForcingOffset above.
130	jahn	1.3
131			\item Cyclic Forcing:
132			\begin{quote}
133			rbcsForcingPeriod = period in seconds\\
134	jahn	1.4	rbcsForcingCycle = cycle in seconds
135	jahn	1.3	\end{quote}
136	jahn	1.4	The same comment as for non-cyclic forcing applies, but rbcsForcingOffset may now be
137			after the time of the first required record even with rbcsSingleTimeFiles=F, in which
138			case records from the end of the file will be used (via cyclicity).
139	jahn	1.3	\end{enumerate}
140
141			\noindent
142			Ways to organize the files:
143			\begin{enumerate}
144			\item One big file with many time records:
145			\begin{quote}
146	jahn	1.4	rbcsSingleTimeFiles = .FALSE.
147	jahn	1.3	\end{quote}
148			All time records are in one big file.
149
150			\item A separate file for each time:
151			\begin{quote}
152	jahn	1.4	rbcsSingleTimeFiles = .TRUE.\\
153	jahn	1.3	deltaTrbcs = time step used to generate forcing files\\
154	jahn	1.4	rbcsIter0 = iteration number of first file $-$ rbcsForcingPeriod/deltaTrbcs
155	jahn	1.3	\end{quote}
156			The rbcs field for each time needed is in a separate file, labeled by the
157			iteration number at the end of the forcing period. If a different timestep
158	jahn	1.4	was used for generating the files (and the file names), set deltaTrbcs to it.
159	jahn	1.3	If there is a shift in time, set rbcsIter0.
160			\end{enumerate}
161
162
163	stephd	1.1
164			\subsubsection{Do's and Don'ts}
165
166			\subsubsection{Reference Material}
167
168			\subsubsection{Experiments and tutorials that use rbcs}
169			\label{sec:pkg:rbcs:experiments}
170
171	jahn	1.4	In the directory \code{verifcation}, the following experiments use
172			\code{rbcs}:
173			\begin{itemize}
174			\item \code{exp4}: box with 4 open boundaries, simulating flow over a
175			Gaussian bump based on \citet{adcroft:97}.
176			\end{itemize}
177
178	stephd	1.1
179
180	cnh	1.2	%%% \end{itemize}
181	stephd	1.1