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 3-D 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:

\[\frac{dT}{dt}=\frac{dT}{dt} - \frac{M_{rbc}}{\tau_T} (T-T_{rbc})\]

where \(M_{rbc}\) is a 3-D 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 compile-time 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.

Table 8.3 RBCS runtime parameters

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), 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 one 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, useRBCvVel

PARM01

FALSE

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

tauRelaxT, tauRelaxS, tauRelaxU, tauRelaxV

PARM01

0.0

timescales (in seconds) for relaxing T/S/U/V (\(\tau_T\) in equation above); required if the corresponding useRBCxxx is .TRUE.

relaxMaskFile (irbc)

PARM01

' '

filename of 3-D 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 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 with 3-D relaxation field values (\(T_{rbc}\) in equation above); if rbcsSingleTimeFiles = .FALSE., it must have one record for each forcing period, otherwise there must be a separate file for each period with a 10-digit iteration number appended to the file name (see Table 8.4 and examples below)

useRBCpTrNum (iTrc)

PARM02

FALSE

if .TRUE., use RBCS for the corresponding passive tracer

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 constant-in-time relaxation, set rbcsForcingPeriod =0. For time-varying 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.

Table 8.4 Timing of RBCS relaxation fields

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\), respectively, 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 pkg/rbcs: