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	\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	The only change need in the code might be in {RBCS.h}, for
36	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	%$\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	The former is how often to load, the latter is how often to cycle
52	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	is only read in at the beginning of the run and kept constant
56	the rest of the run. Default is 0.
57	\\
58	$\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	$\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	1/tauRelaxT. Default is 1.\\
86	$\bullet$ {\bf tauRelaxS}: same for salinity.\\
87	$\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	\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	rbcsForcingCycle = 0
123	\end{quote}
124	When starting the run at time 0 (as usually the case), a period with center before
125	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	For aligned periods (one period starting at time 0) and one extra record before
128	time 0 (and ending at time 0), set rbcsForcingOffset${}=-$Period.
129	For other situations, see the description of rbcsForcingOffset above.
130
131	\item Cyclic Forcing:
132	\begin{quote}
133	rbcsForcingPeriod = period in seconds\\
134	rbcsForcingCycle = cycle in seconds
135	\end{quote}
136	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	\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	rbcsSingleTimeFiles = .FALSE.
147	\end{quote}
148	All time records are in one big file.
149
150	\item A separate file for each time:
151	\begin{quote}
152	rbcsSingleTimeFiles = .TRUE.\\
153	deltaTrbcs = time step used to generate forcing files\\
154	rbcsIter0 = iteration number of first file $-$ rbcsForcingPeriod/deltaTrbcs
155	\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	was used for generating the files (and the file names), set deltaTrbcs to it.
159	If there is a shift in time, set rbcsIter0.
160	\end{enumerate}
161
162
163
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	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
179
180	%%% \end{itemize}
181