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}: if you want to offset rbcs forcing
timing. This is the time at the beginning of the first forcing period
(in seconds).  Default is 0.  (This used to be rbcsInIter and was in
units of iterations.)\\
$\bullet$  {\bf rbcsSingleTimeFiles}: if true, relax fields are given
1 file per time labeled by iteration number.\\
$\bullet$  {\bf deltaTrbcs}: time step used to compute iteration numbers 
for rbcsSingleTimeFiles.\\
$\bullet$  {\bf rbcsIter0}: rbcsSingleTimeFiles iteration number
corresponding to rbcsForcingOffset.\\
$\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\\
     rbcsForcingOffset = beginning of first forcing period in seconds (default 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, hence Offset 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 Offset=-Period.

  This option makes most sense with rbcsSingleTimeFiles=T (see below), but may be
  used with either setting.

\item Cyclic Forcing:
  \begin{quote}
     rbcsForcingPeriod = period in seconds\\
     rbcsForcingCycle = cycle in seconds\\
     rbcsForcingOffset = beginning of first forcing period in seconds (default 0)
  \end{quote}
  Here Offset may be at or after the start time (actually starttime-period/2),
  in which case records from the end of the cycle are used for missing records at
  the beginning (via cyclicity).  Not very nice, but works.

  This is the traditional way used with rbcsSingleTimeFiles=F, but again may be
  used with either setting.
\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 = forcing file iteration number corresponding to rbcsForcingOffset
  \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.
  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}


%%% \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}: if you want to offset rbcs forcing
59	timing. This is the time at the beginning of the first forcing period
60	(in seconds). Default is 0. (This used to be rbcsInIter and was in
61	units of iterations.)\\
62	$\bullet$ {\bf rbcsSingleTimeFiles}: if true, relax fields are given
63	1 file per time labeled by iteration number.\\
64	$\bullet$ {\bf deltaTrbcs}: time step used to compute iteration numbers
65	for rbcsSingleTimeFiles.\\
66	$\bullet$ {\bf rbcsIter0}: rbcsSingleTimeFiles iteration number
67	corresponding to rbcsForcingOffset.\\
68	$\bullet$ {\bf useRBCtemp}: true or false (default false)\\
69	$\bullet$ {\bf useRBCsalt}: true or false (default false)\\
70	$\bullet$ {\bf useRBCptracers}: true or false (default false), must be using
71	ptracers to set true\\
72	$\bullet$ {\bf tauRelaxT}: timescale in seconds of relaxing
73	in temperature ($\tau_T$ in equation above).
74	Where mask is 1, relax rate will be
75	1/tauRelaxT. Default is 1.
76	$\bullet$ {\bf tauRelaxS}: same for salinity.
77	$\bullet$ {\bf relaxMaskFile(irbc)}: filename of 3-D file
78	with mask ($M_{rbc}$ in equation above.
79	Need a file for each irbc. 1=temperature,
80	2=salinity, 3=ptracer01, 4=ptracer02 etc. If the mask numbers
81	end (see maskLEN) are less than the number tracers, then
82	relaxMaskFile(maskLEN) is used for all remaining ptracers.\\
83	$\bullet$ {\bf relaxTFile}: name of file where temperatures
84	that need to be realxed to ($T_{rbc}$ in equation above)
85	are stored. Need 3-D fields to
86	match model domain, and as many entries as given by
87	rbcsForcingPeriod and rbcsForcingCycle.\\
88	$\bullet$ {\bf relaxSFile}: same for salinity.\\
89
90	\vspace{.5cm}
91	\noindent
92	Set in {RBCS\_PARM02} for each of the ptracers (iTrc):\\
93	$\bullet$ {\bf useRBCptrnum(iTrc)}: true or false (default
94	is false).\\
95	$\bullet$ {\bf tauRelaxPTR(iTrc)}: relax timescale.\\
96	$\bullet$ {\bf relaxPtracerFile(iTrc)}: file with relax
97	fields.\\
98
99	\noindent
100	Typical ways of specifying timing of relaxation fields:
101	\begin{enumerate}
102	\item Constant-in-time forcing:
103	\begin{quote}
104	rbcsForcingPeriod = 0
105	\end{quote}
106	One field is read and used for all times. Use this to emulate the result of
107	rbcsForcingCycle=0 before 2010-11-10.
108
109	\item Non-cyclic time-varying forcing:
110	\begin{quote}
111	rbcsForcingPeriod = period in seconds\\
112	rbcsForcingCycle = 0\\
113	rbcsForcingOffset = beginning of first forcing period in seconds (default 0)
114	\end{quote}
115	When starting the run at time 0 (as usually the case), a period with center before
116	or at time 0 is needed for time interpolation, hence Offset needs to be negative.
117	For aligned periods (one period starting at time 0) and one extra record before
118	time 0 (and ending at time 0), set Offset=-Period.
119
120	This option makes most sense with rbcsSingleTimeFiles=T (see below), but may be
121	used with either setting.
122
123	\item Cyclic Forcing:
124	\begin{quote}
125	rbcsForcingPeriod = period in seconds\\
126	rbcsForcingCycle = cycle in seconds\\
127	rbcsForcingOffset = beginning of first forcing period in seconds (default 0)
128	\end{quote}
129	Here Offset may be at or after the start time (actually starttime-period/2),
130	in which case records from the end of the cycle are used for missing records at
131	the beginning (via cyclicity). Not very nice, but works.
132
133	This is the traditional way used with rbcsSingleTimeFiles=F, but again may be
134	used with either setting.
135	\end{enumerate}
136
137	\noindent
138	Ways to organize the files:
139	\begin{enumerate}
140	\item One big file with many time records:
141	\begin{quote}
142	rbcsSingleTimeFiles = .False.
143	\end{quote}
144	All time records are in one big file.
145
146	\item A separate file for each time:
147	\begin{quote}
148	rbcsSingleTimeFiles = .True.\\
149	deltaTrbcs = time step used to generate forcing files\\
150	rbcsIter0 = forcing file iteration number corresponding to rbcsForcingOffset
151	\end{quote}
152	The rbcs field for each time needed is in a separate file, labeled by the
153	iteration number at the end of the forcing period. If a different timestep
154	was used for generating the files (and the file names), set deltaTrbcs.
155	If there is a shift in time, set rbcsIter0.
156	\end{enumerate}
157
158
159
160	\subsubsection{Do's and Don'ts}
161
162	\subsubsection{Reference Material}
163
164	\subsubsection{Experiments and tutorials that use rbcs}
165	\label{sec:pkg:rbcs:experiments}
166
167
168
169	%%% \end{itemize}
170