.. _sub_phys_pkg_rbcs:
RBCS Package
------------
.. _ssub_phys_pkg_rbcs_intro:
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.
For a tracer (:math:`T`) at every grid point the tendency is modified so
that:
.. math:: \frac{dT}{dt}=\frac{dT}{dt} - \frac{M_{rbc}}{\tau_T} (T-T_{rbc})
where :math:`M_{rbc}` is a 3-D mask (no time dependence) with values
between 0 and 1. Where :math:`M_{rbc}` is 1, relaxing timescale is
:math:`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
:math:`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 :math:`\tau_T`. These
are set in data.rbcs (see below).
Key subroutines and parameters
++++++++++++++++++++++++++++++
The only compile-time parameter you are likely to have to change is in
:code:`RBCS.h`, the number of masks, PARAMETER(maskLEN = 3 ), see below.
The runtime parameters are set in :code:`data.rbcs`:
Set in RBCS\_PARM01:
- **rbcsForcingPeriod**: time interval between forcing fields (in seconds), zero means constant-in-time forcing.
- **rbcsForcingCycle**: repeat cycle of forcing fields (in seconds), zero means non-cyclic forcing.
- **rbcsForcingOffset**: time offset of forcing fields (in seconds, default 0); this is relative to time averages starting at :math:`t=0`, i.e., the first forcing record/file is placed at :math:`{\rm rbcsForcingOffset+rbcsForcingPeriod}/2`; see below for examples.
- **rbcsSingleTimeFiles**: true or false (default false), if true, forcing fields are given 1 file per rbcsForcingPeriod.
- **deltaTrbcs**: time step used to compute the iteration numbers for rbcsSingleTimeFiles=T.
- **rbcsIter0**: shift in iteration numbers used to label files if rbcsSingleTimeFiles=T (default 0, see below for examples).
- **useRBCtemp**: true or false (default false)
- **useRBCsalt**: true or false (default false)
- **useRBCptracers**: true or false (default false), must be using ptracers to set true
- **tauRelaxT**: timescale in seconds of relaxing in temperature (:math:`\tau_T` in equation above). Where mask is 1, relax rate will be 1/tauRelaxT. Default is 1.
- **tauRelaxS**: same for salinity.
- **relaxMaskFile(irbc)**: filename of 3-D file with mask (:math:`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.
- **relaxTFile**: name of file where temperatures that need to be relaxed to (:math:`T_{rbc}` in equation above) are stored. The file must contain 3-D records to match the model domain. If rbcsSingleTimeFiles=F, it must have one record for each forcing period. If T, there must be a separate file for each period and a 10-digit iteration number is appended to the file name (see Table [tab:pkg:rbcs:timing] and examples below).
- **relaxSFile**: same for salinity.
Set in RBCS\_PARM02 for each of the ptracers (iTrc):
- **useRBCptrnum(iTrc)**: true or false (default is false).
- **tauRelaxPTR(iTrc)**: relax timescale.
- **relaxPtracerFile(iTrc)**: file with relax fields.
Timing of relaxation forcing fields
+++++++++++++++++++++++++++++++++++
For constant-in-time relaxation, set rbcsForcingPeriod=0. For
time-varying relaxation, Table [tab:pkg:rbcs:timing] illustrates the
relation between model time and forcing fields (either records in one
big file or, for rbcsSingleTimeFiles=T, individual files labeled with an
iteration number). With rbcsSingleTimeFiles=T, this is the same as in
the offline package, except that the forcing offset is in seconds.
.. tabularcolumns:: |l|l|l|c|
.. _tab_phys_pkg_rbcs_timing:
.. table:: Timing of RBCS relaxation fields
+-------------------+-------------------------------------------------------------------------------------+-------------------+
| | rbcsSingleTimeFiles = T | F |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| | :math:`c=0` | :math:`c\ne0` | :math:`c\ne0` |
+===================+==========================================+==========================================+===================+
| **model time** | **file number** | **file number** | **record** |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| :math:`t_0 - p/2` | :math:`i_0` | :math:`i_0 + c/{\Delta t_{\text{rbcs}}}` | :math:`c/p` |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| :math:`t_0 + p/2` | :math:`i_0 + p/{\Delta t_{\text{rbcs}}}` | :math:`i_0 + p/{\Delta t_{\text{rbcs}}}` | :math:`1` |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| :math:`t_0+p+p/2` | :math:`i_0 + 2p/{\Delta t_{\text{rbcs}}}`| :math:`i_0 + 2p/{\Delta t_{\text{rbcs}}}`| :math:`2` |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| ... | ... | ... | ... |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| :math:`t_0+c-p/2` | ... | :math:`i_0 + c/{\Delta t_{\text{rbcs}}}` | :math:`c/p` |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
| ... | ... | ... | ... |
+-------------------+------------------------------------------+------------------------------------------+-------------------+
where
:math:`p` = rbcsForcingPeriod
:math:`c` = rbcsForcingCycle
:math:`t_0` = rbcsForcingOffset
:math:`i_0` = rbcsIter0
:math:`{\Delta t_{\text{rbcs}}}` = deltaTrbcs
Example 1: forcing with time averages starting at :math:`t=0`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Cyclic data in a single file
#############################
Set rbcsSingleTimeFiles=F and rbcsForcingOffset=0, and the model will
start by interpolating the last and first records of rbcs data, placed
at :math:`-p/2` and :math:`p/2`, resp., as appropriate for fields
averaged over the time intervals :math:`[-p, 0]` and :math:`[0, p]`.
Non-cyclic data, multiple files
###############################
Set rbcsForcingCycle=0 and rbcsSingleTimeFiles=T. 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 :math:`-p/2` and :math:`p/2`.
Example 2: forcing with snapshots starting at :math:`t=0`
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Cyclic data in a single file
############################
Set rbcsSingleTimeFiles=F and rbcsForcingOffset=\ :math:`-p/2`, and the
model will start forcing with the first record at :math:`t=0`.
Non-cyclic data, multiple files
###############################
Set rbcsForcingCycle=0 and rbcsSingleTimeFiles=T. In this case, it is
more natural to set rbcsForcingOffset=\ :math:`+p/2`. With rbcsIter0=0
and deltaTrbcs=rbcsForcingPeriod, the model would then start with data
from files relax\*File.0000000000.data at :math:`t=0`. It would then
proceed to interpolate between this file and files
relax\*File.0000000001.data at :math:`t={}`\ rbcsForcingPeriod.
Do’s and Don’ts
+++++++++++++++
Reference Material
++++++++++++++++++
Experiments and tutorials that use rbcs
+++++++++++++++++++++++++++++++++++++++
In the directory , the following experiments use :code:`rbcs`:
- :code:`exp4` : box with 4 open boundaries, simulating flow over a Gaussian bump
based on :cite:`adcroft:97`