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 compile-time parameter you are likely to have to change is in {RBCS.h},
the number of masks, PARAMETER(maskLEN = 3 ), see below.

The runtime parameters are set in {\it data.rbcs}:

\vspace{.5cm}
\noindent
Set in {RBCS\_PARM01}:\\
$\bullet$ {\bf rbcsForcingPeriod}: time interval between forcing fields
(in seconds), zero means constant-in-time forcing.\\
$\bullet$ {\bf rbcsForcingCycle}: repeat cycle of forcing fields (in seconds),
zero means non-cyclic forcing.\\
$\bullet$  {\bf rbcsForcingOffset}: time offset of forcing fields
(in seconds, default 0); this is relative to time averages starting at
$t=0$, i.e., the first forcing record/file is placed at
${\rm rbcsForcingOffset+rbcsForcingPeriod}/2$; see below for examples.\\
$\bullet$  {\bf rbcsSingleTimeFiles}: true or false (default false),
if true, forcing fields are given 1 file per rbcsForcingPeriod.\\
$\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, see below for examples).\\
$\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 relaxed to ($T_{rbc}$ in equation above)
are stored.  The file must contain 3-D records to match the model domain.
If rbcsSingleTimeFiles=F, it must have one record for each forcing period.
If T, there must be a separate file for each period and a 10-digit iteration
number is appended to the file name (see Table~\ref{tab:pkg:rbcs:timing} 
and examples below).\\
$\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.\\


\subsubsection{Timing of relaxation forcing fields}

For constant-in-time relaxation, set rbcsForcingPeriod=0.
For time-varying relaxation, Table~\ref{tab:pkg:rbcs:timing} illustrates the
relation between model time and forcing fields (either records in
one big file or, for rbcsSingleTimeFiles=T, individual files labeled with an
iteration number).  With rbcsSingleTimeFiles=T, this is the same as in the
offline package, except that the forcing offset is in seconds.
\newcommand{\dtr}{\Delta t_{\text{rbcs}}}%
\begin{table}
    \centering
    \begin{tabular}{|l|l|l|c|}
      \hline 
      &
      \multicolumn{2}{|c|}{rbcsSingleTimeFiles = T} &
      F \\
      &
      \textbf{$c=0$} &
      \textbf{$c\ne0$} &
      \textbf{$c\ne0$}
      \\ \hline
      \textbf{model time} &
      \textbf{file number} &
      \textbf{file number} &
      \textbf{record} \\
      \hline \hline
        $t_0 -     p/2$ & $i_0$            & $i_0 +   c/\dtr$ & $c/p$ \\ \hline
        $t_0 +     p/2$ & $i_0 +   p/\dtr$ & $i_0 +   p/\dtr$ & $1$ \\ \hline
        $t_0 + p + p/2$ & $i_0 + 2 p/\dtr$ & $i_0 + 2 p/\dtr$ & $2$ \\ \hline
        \dots & \dots & \dots & \dots \\ \hline
        $t_0 + c - p/2$ & \dots            & $i_0 +   c/\dtr$ & $c/p$ \\ \hline
        \dots & \dots & \dots & \dots \\ \hline
    \end{tabular}
    \qquad
    \begin{tabular}{c@{${}={}$}l}
        \multicolumn{2}{l}{} \\[4ex]
        \multicolumn{2}{l}{where} \\[1ex]
        $p$    & rbcsForcingPeriod \\
        $c$    & rbcsForcingCycle \\
        $t_0$  & rbcsForcingOffset \\
        $i_0$  & rbcsIter0 \\
        $\dtr$ & deltaTrbcs \\
    \end{tabular}\\[3ex]
    \caption{Timing of relaxation forcing fields.}
    \label{tab:pkg:rbcs:timing}
\end{table}


\subsubsection{Example 1: forcing with time averages starting at $t=0$}

\paragraph{Cyclic data in a single file.}  Set rbcsSingleTimeFiles=F and
rbcsForcingOffset=0, and the model will start by interpolating the last and first
records of rbcs data, placed at $-p/2$ and $p/2$, resp., as appropriate for fields
averaged over the time intervals $[-p, 0]$ and $[0, p]$.

\paragraph{Non-cyclic data, multiple files.}  Set rbcsForcingCycle=0 and
rbcsSingleTimeFiles=T.  With rbcsForcingOffset=0, rbcsIter0=0 and
deltaTrbcs=rbcsForcingPeriod, the model would then start by interpolating data from
files relax*File.0000000000.data and relax*File.0000000001.data, \dots,
again placed at $-p/2$ and $p/2$.


\subsubsection{Example 2: forcing with snapshots starting at $t=0$}

\paragraph{Cyclic data in a single file.}  Set rbcsSingleTimeFiles=F and
rbcsForcingOffset=$-p/2$, and the model will start forcing with the first
record at $t=0$.

\paragraph{Non-cyclic data, multiple files.}  Set rbcsForcingCycle=0 and
rbcsSingleTimeFiles=T.  In this case, it is more natural to set
rbcsForcingOffset=$+p/2$.
With rbcsIter0=0 and deltaTrbcs=rbcsForcingPeriod, the model would then start
with data from files relax*File.0000000000.data at $t=0$.
It would then proceed to interpolate between this file and files
relax*File.0000000001.data at $t={}$rbcsForcingPeriod.


\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	jahn	1.5
34	stephd	1.1	\subsubsection {Key subroutines and parameters}
35
36	jahn	1.5	The only compile-time parameter you are likely to have to change is in {RBCS.h},
37			the number of masks, PARAMETER(maskLEN = 3 ), see below.
38
39			The runtime parameters are set in {\it data.rbcs}:
40	stephd	1.1
41			\vspace{.5cm}
42			\noindent
43			Set in {RBCS\_PARM01}:\\
44	jahn	1.5	$\bullet$ {\bf rbcsForcingPeriod}: time interval between forcing fields
45			(in seconds), zero means constant-in-time forcing.\\
46			$\bullet$ {\bf rbcsForcingCycle}: repeat cycle of forcing fields (in seconds),
47			zero means non-cyclic forcing.\\
48			$\bullet$ {\bf rbcsForcingOffset}: time offset of forcing fields
49			(in seconds, default 0); this is relative to time averages starting at
50			$t=0$, i.e., the first forcing record/file is placed at
51			${\rm rbcsForcingOffset+rbcsForcingPeriod}/2$; see below for examples.\\
52	jahn	1.4	$\bullet$ {\bf rbcsSingleTimeFiles}: true or false (default false),
53	jahn	1.5	if true, forcing fields are given 1 file per rbcsForcingPeriod.\\
54	jahn	1.4	$\bullet$ {\bf deltaTrbcs}: time step used to compute the iteration numbers
55			for rbcsSingleTimeFiles=T.\\
56			$\bullet$ {\bf rbcsIter0}: shift in iteration numbers used to label files if
57	jahn	1.5	rbcsSingleTimeFiles=T (default 0, see below for examples).\\
58	stephd	1.1	$\bullet$ {\bf useRBCtemp}: true or false (default false)\\
59			$\bullet$ {\bf useRBCsalt}: true or false (default false)\\
60			$\bullet$ {\bf useRBCptracers}: true or false (default false), must be using
61			ptracers to set true\\
62			$\bullet$ {\bf tauRelaxT}: timescale in seconds of relaxing
63			in temperature ($\tau_T$ in equation above).
64			Where mask is 1, relax rate will be
65	jahn	1.4	1/tauRelaxT. Default is 1.\\
66			$\bullet$ {\bf tauRelaxS}: same for salinity.\\
67	stephd	1.1	$\bullet$ {\bf relaxMaskFile(irbc)}: filename of 3-D file
68			with mask ($M_{rbc}$ in equation above.
69			Need a file for each irbc. 1=temperature,
70			2=salinity, 3=ptracer01, 4=ptracer02 etc. If the mask numbers
71			end (see maskLEN) are less than the number tracers, then
72			relaxMaskFile(maskLEN) is used for all remaining ptracers.\\
73			$\bullet$ {\bf relaxTFile}: name of file where temperatures
74	jahn	1.5	that need to be relaxed to ($T_{rbc}$ in equation above)
75			are stored. The file must contain 3-D records to match the model domain.
76			If rbcsSingleTimeFiles=F, it must have one record for each forcing period.
77			If T, there must be a separate file for each period and a 10-digit iteration
78			number is appended to the file name (see Table~\ref{tab:pkg:rbcs:timing}
79			and examples below).\\
80	stephd	1.1	$\bullet$ {\bf relaxSFile}: same for salinity.\\
81
82			\vspace{.5cm}
83			\noindent
84			Set in {RBCS\_PARM02} for each of the ptracers (iTrc):\\
85			$\bullet$ {\bf useRBCptrnum(iTrc)}: true or false (default
86			is false).\\
87			$\bullet$ {\bf tauRelaxPTR(iTrc)}: relax timescale.\\
88			$\bullet$ {\bf relaxPtracerFile(iTrc)}: file with relax
89			fields.\\
90
91	jahn	1.3
92	jahn	1.5	\subsubsection{Timing of relaxation forcing fields}
93	jahn	1.3
94	jahn	1.5	For constant-in-time relaxation, set rbcsForcingPeriod=0.
95			For time-varying relaxation, Table~\ref{tab:pkg:rbcs:timing} illustrates the
96			relation between model time and forcing fields (either records in
97			one big file or, for rbcsSingleTimeFiles=T, individual files labeled with an
98			iteration number). With rbcsSingleTimeFiles=T, this is the same as in the
99			offline package, except that the forcing offset is in seconds.
100			\newcommand{\dtr}{\Delta t_{\text{rbcs}}}%
101			\begin{table}
102			\centering
103			\begin{tabular}{\|l\|l\|l\|c\|}
104			\hline
105			&
106			\multicolumn{2}{\|c\|}{rbcsSingleTimeFiles = T} &
107			F \\
108			&
109			\textbf{$c=0$} &
110			\textbf{$c\ne0$} &
111			\textbf{$c\ne0$}
112			\\ \hline
113			\textbf{model time} &
114			\textbf{file number} &
115			\textbf{file number} &
116			\textbf{record} \\
117			\hline \hline
118			$t_0 - p/2$ & $i_0$ & $i_0 + c/\dtr$ & $c/p$ \\ \hline
119			$t_0 + p/2$ & $i_0 + p/\dtr$ & $i_0 + p/\dtr$ & $1$ \\ \hline
120			$t_0 + p + p/2$ & $i_0 + 2 p/\dtr$ & $i_0 + 2 p/\dtr$ & $2$ \\ \hline
121			\dots & \dots & \dots & \dots \\ \hline
122			$t_0 + c - p/2$ & \dots & $i_0 + c/\dtr$ & $c/p$ \\ \hline
123			\dots & \dots & \dots & \dots \\ \hline
124			\end{tabular}
125			\qquad
126			\begin{tabular}{c@{${}={}$}l}
127			\multicolumn{2}{l}{} \\[4ex]
128			\multicolumn{2}{l}{where} \\[1ex]
129			$p$ & rbcsForcingPeriod \\
130			$c$ & rbcsForcingCycle \\
131			$t_0$ & rbcsForcingOffset \\
132			$i_0$ & rbcsIter0 \\
133			$\dtr$ & deltaTrbcs \\
134			\end{tabular}\\[3ex]
135			\caption{Timing of relaxation forcing fields.}
136			\label{tab:pkg:rbcs:timing}
137			\end{table}
138
139
140			\subsubsection{Example 1: forcing with time averages starting at $t=0$}
141
142			\paragraph{Cyclic data in a single file.} Set rbcsSingleTimeFiles=F and
143			rbcsForcingOffset=0, and the model will start by interpolating the last and first
144			records of rbcs data, placed at $-p/2$ and $p/2$, resp., as appropriate for fields
145			averaged over the time intervals $[-p, 0]$ and $[0, p]$.
146
147			\paragraph{Non-cyclic data, multiple files.} Set rbcsForcingCycle=0 and
148			rbcsSingleTimeFiles=T. With rbcsForcingOffset=0, rbcsIter0=0 and
149			deltaTrbcs=rbcsForcingPeriod, the model would then start by interpolating data from
150			files relaxFile.0000000000.data and relaxFile.0000000001.data, \dots,
151			again placed at $-p/2$ and $p/2$.
152
153
154			\subsubsection{Example 2: forcing with snapshots starting at $t=0$}
155
156			\paragraph{Cyclic data in a single file.} Set rbcsSingleTimeFiles=F and
157			rbcsForcingOffset=$-p/2$, and the model will start forcing with the first
158			record at $t=0$.
159
160			\paragraph{Non-cyclic data, multiple files.} Set rbcsForcingCycle=0 and
161			rbcsSingleTimeFiles=T. In this case, it is more natural to set
162			rbcsForcingOffset=$+p/2$.
163			With rbcsIter0=0 and deltaTrbcs=rbcsForcingPeriod, the model would then start
164			with data from files relax*File.0000000000.data at $t=0$.
165			It would then proceed to interpolate between this file and files
166			relax*File.0000000001.data at $t={}$rbcsForcingPeriod.
167	jahn	1.3
168	stephd	1.1
169			\subsubsection{Do's and Don'ts}
170
171			\subsubsection{Reference Material}
172
173			\subsubsection{Experiments and tutorials that use rbcs}
174			\label{sec:pkg:rbcs:experiments}
175
176	jahn	1.4	In the directory \code{verifcation}, the following experiments use
177			\code{rbcs}:
178			\begin{itemize}
179			\item \code{exp4}: box with 4 open boundaries, simulating flow over a
180			Gaussian bump based on \citet{adcroft:97}.
181			\end{itemize}
182
183	stephd	1.1
184
185	cnh	1.2	%%% \end{itemize}
186	stephd	1.1