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	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.3	$\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	stephd	1.1	$\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	jahn	1.3	\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	stephd	1.1
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	cnh	1.2	%%% \end{itemize}
170	stephd	1.1