8.3.2. RBCS Package¶
8.3.2.1. Introduction¶
pkg/rbcs provides the flexibility to relax fields (temperature, salinity, ptracers, horizontal velocities) in any 3D location, thus can be used to implement a sponge layer, or a “source” anywhere in the domain, among other uses.
For a field (\(T\)) at every grid point the tendency is modified so that:
where \(M_{rbc}\) is a 3D mask (no time dependence) between 0 and 1. Values are relaxed to a field given by \(T_{rbc}\), which can be set to vary in time. Where \(M_{rbc}(x,y,z) = 1.0\), the relaxing timescale is \(\tau_T\); where \(M_{rbc}(x,y,z) = 0.0\), there is no relaxing. If \(M_{rbc}(x,y,z) = 0.5\) then relaxation occurs but at a timescale of \(2\,\tau_T\).
A separate mask can be used for \(\theta, 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).
8.3.2.2. Key subroutines and parameters¶
The only compiletime parameter you are likely to have to change is in RBCS_SIZE.h, the number of masks, PARAMETER( maskLEN = 3 ) by default, see below.
Table 8.3 summarizes the runtime flags that are
set in data.rbcs
, and their default values.
Flag/Parameter 
Group 
Default 
Description 

PARM01 
0.0 
time interval between forcing fields (in seconds), zero means constantintime forcing 

PARM01 
0.0 
repeat cycle of forcing fields (in seconds), zero means noncyclic forcing 

PARM01 
0.0 
time offset of forcing fields (in seconds), relative to time averages starting at \(t=0\), i.e., the first forcing record/file is placed at (rbcsForcingOffset + rbcsForcingPeriod)/2; see below for examples 

PARM01 
FALSE 
if 

PARM01 
time step used to compute the iteration numbers for rbcsSingleTimeFiles = 

PARM01 
0.0 
if rbcsVanishingTime > 0, the relaxation strength reduces linearly to vanish at myTime == rbcsVanishingTime 

PARM01 
0 
shift in iteration numbers used to label files if rbcsSingleTimeFiles = 

PARM01 
FALSE 
whether to use RBCS for T/S/U/V 

PARM01 
0.0 
timescales (in seconds) for relaxing T/S/U/V (\(\tau_T\) in equation above); required if the corresponding 

relaxMaskFile (irbc) 
PARM01 
' ' 
filename of 3D file with mask (\(M_{rbc}\) above), requires a file for each irbc (1=temperature, 2=salinity, 3=ptracer1, 4=ptracer2, etc);
if maskLEN is less than the number of tracers, then 
PARM01 
' ' 
filename of 3D file with mask for U/V. 

PARM01 
' ' 
name of file with 3D relaxation field values (\(T_{rbc}\) in equation above);
if rbcsSingleTimeFiles = 

useRBCpTrNum (iTrc) 
PARM02 
FALSE 
if 
tauRelaxPTR (iTrc) 
PARM02 
0.0 
relaxing timescale (seconds) for the corresponding ptracer 
relaxPtracerFile (iTrc) 
PARM02 
' ' 
file with relaxation field for the corresponding ptracer 
8.3.2.3. Timing of relaxation forcing fields¶
For constantintime relaxation, set rbcsForcingPeriod =0. For
timevarying relaxation, Table 8.4 illustrates the
relation between model time and forcing fields (either records in one big file
or, for rbcsSingleTimeFiles = .TRUE.
, individual files labeled
with an iteration number). With rbcsSingleTimeFiles = .TRUE.
,
this is the same as in the offline package, except that the forcing offset is
in seconds.
rbcsSingleTimeFiles = T 
F 


\(c=0\) 
\(c\ne0\) 
\(c\ne0\) 

model time 
file number 
file number 
record 
\(t_0  p/2\) 
\(i_0\) 
\(i_0 + c/{\Delta t_{\text{rbcs}}}\) 
\(c/p\) 
\(t_0 + p/2\) 
\(i_0 + p/{\Delta t_{\text{rbcs}}}\) 
\(i_0 + p/{\Delta t_{\text{rbcs}}}\) 
\(1\) 
\(t_0+p+p/2\) 
\(i_0 + 2p/{\Delta t_{\text{rbcs}}}\) 
\(i_0 + 2p/{\Delta t_{\text{rbcs}}}\) 
\(2\) 
… 
… 
… 
… 
\(t_0+cp/2\) 
… 
\(i_0 + c/{\Delta t_{\text{rbcs}}}\) 
\(c/p\) 
… 
… 
… 
… 
where
\(p\) = rbcsForcingPeriod
\(c\) = rbcsForcingCycle
\(t_0\) = rbcsForcingOffset
\(i_0\) = rbcsIter0
\({\Delta t_{\text{rbcs}}}\) = deltaTrbcs
8.3.2.4. Example 1: forcing with time averages starting at \(t=0\)¶
8.3.2.4.1. Cyclic data in a single file¶
Set rbcsSingleTimeFiles = .FALSE.
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\),
respectively, as appropriate for fields averaged over the time intervals
\([p, 0]\) and \([0, p]\).
8.3.2.4.2. Noncyclic data, multiple files¶
Set rbcsForcingCycle = 0 and rbcsSingleTimeFiles =
.TRUE.
. 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
, … , again placed at \(p/2\) and
\(p/2\).
8.3.2.5. Example 2: forcing with snapshots starting at \(t=0\)¶
8.3.2.5.1. Cyclic data in a single file¶
Set rbcsSingleTimeFiles = .FALSE.
and
rbcsForcingOffset =\(p/2\), and the model will start forcing
with the first record at \(t=0\).
8.3.2.5.2. Noncyclic data, multiple files¶
Set rbcsForcingCycle = 0 and rbcsSingleTimeFiles =
.TRUE.
. 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.
8.3.2.6. Do’s and Don’ts¶
8.3.2.7. Reference Material¶
8.3.2.8. Experiments and tutorials that use rbcs¶
In the directory, the following experiments use pkg/rbcs:
tutorial Southern Ocean Reentrant Channel makes use of pkg/rbcs at its northern boundary as a sponge layer;
exp4 simulating flow over a Gaussian bump based on [AHM97], demonstrating relaxation of a ptracer field.