# 8.3.2. RBCS Package¶

## 8.3.2.1. Introduction¶

A package which provides the flexibility to relax fields (temperature, salinity, ptracers, horizontal velocities) in any 3-D location: so could be used as a sponge layer, or as a “source” anywhere in the domain.

For a field (\(T\)) at every grid point the tendency is modified so that:

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).

## 8.3.2.2. Key subroutines and parameters¶

The only compile-time parameter you are likely to have to change is in RBCS_SIZE.h, the number of masks, PARAMETER(maskLEN = 3 ), see below.

Table 8.3 summarizes the
runtime flags that are set in `data.rbcs`

, and
their default values.

Flag/Parameter | Group | Default | Description |
---|---|---|---|

rbcsForcingPeriod | PARM01 | 0.0 | Time interval between forcing fields (in seconds), zero means constant-in-time forcing. |

rbcsForcingCycle | PARM01 | 0.0 | Repeat cycle of forcing fields (in seconds), zero means non-cyclic forcing. |

rbcsForcingOffset | PARM01 | 0.0 | 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 (rbcsForcingOffset + rbcsForcingPeriod )/2 ; see below for examples. |

rbcsSingleTimeFiles | PARM01 | FALSE | If `.TRUE.` , forcing fields are given 1 file per rbcsForcingPeriod. |

deltaTrbcs | PARM01 | deltaTclock | Time step used to compute the iteration numbers for rbcsSingleTimeFiles = `.TRUE.` . |

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

rbcsIter0 | PARM01 | 0 | Shift in iteration numbers used to label files if rbcsSingleTimeFiles = `.TRUE.` (see below for examples). |

useRBCtemp, useRBCsalt, useRBCuVel, useRCvVel | PARM01 | FALSE | Whether to use RBCS for T/S/U/V. |

tauRelaxT, tauRelaxT, tauRelaxT, tauRelaxT | PARM01 | 0.0 | Timescales in seconds of relaxing in T/S/U/V (\(\tau_T\) in equation above). Where mask is 1, relax rate will be 1/tauRelaxT. Must be set if the corresponding `useRBCxxx` is `TRUE` . |

relaxMaskFile (irbc) | PARM01 | ' ' |
Filename of 3-D file with mask (\(M_{rbc}\) in equation above). Need a file for each irbc (1=temperature, 2=salinity, 3=ptracer1, 4=ptracer2, etc). If maskLEN is les than the number of tracers, then `relaxMaskFile(maskLEN)` is used for all remaining tracers. |

relaxMaskUFile, relaxMaskVFile | PARM01 | ' ' |
Filename of 3-D file with mask for U/V. |

relaxTFile, relaxSFile, relaxUFile, relaxVFile | PARM01 | ' ' |
Name of file where the field that need to be relaxed to (\(T_{rbc}\) in equation above) is stored. The file must contain 3-D records to match the model domain.
If rbcsSingleTimeFiles = `.FALSE.` , it must have one record for each forcing period.
Otherwise there must be a separate file for each period and a 10-digit iteration number is appended to the file name (see Table [Timing of RBCS relaxation fields] and examples below). |

useRBCptracers | PARM02 | FALSE | DEPRECATED Use one useRBCpTrNum per tracer instead. |

useRBCpTrNum (iTrc) | PARM02 | FALSE | Whether to use RBCS for the corresponding passive tracer. |

tauRelaxPTR (iTrc) | PARM02 | 0.0 | Relaxing timescale for the corresponding ptracer. |

relaxPtracerFile (iTrc) | PARM02 | ' ' |
File with relax fields for the corresponding ptracer. |

## 8.3.2.3. Timing of relaxation forcing fields¶

For constant-in-time relaxation, set rbcsForcingPeriod =0.
For time-varying relaxation, Table 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+c-p/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\), resp., as appropriate for fields
averaged over the time intervals \([-p, 0]\) and \([0, p]\).

### 8.3.2.4.2. Non-cyclic 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. Non-cyclic 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 `rbcs`

:

- exp4 : box with 4 open boundaries, simulating flow over a Gaussian bump based on [adcroft:97]