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	\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
34	\subsubsection {Key subroutines and parameters}
35
36	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
41	\vspace{.5cm}
42	\noindent
43	Set in {RBCS\_PARM01}:\\
44	$\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	$\bullet$ {\bf rbcsSingleTimeFiles}: true or false (default false),
53	if true, forcing fields are given 1 file per rbcsForcingPeriod.\\
54	$\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	rbcsSingleTimeFiles=T (default 0, see below for examples).\\
58	$\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	1/tauRelaxT. Default is 1.\\
66	$\bullet$ {\bf tauRelaxS}: same for salinity.\\
67	$\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	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	$\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
92	\subsubsection{Timing of relaxation forcing fields}
93
94	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
168
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	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
184
185	%%% \end{itemize}
186