Warning, /doc/phys_pkgs/rbcs.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 849a52ce on 2021-08-10 07:52:56 UTC
8679f9097b Jeff*0001 .. _sub_phys_pkg_rbcs:
0002
0003 RBCS Package
0004 ------------
0005
0006 .. _ssub_phys_pkg_rbcs_intro:
0007
0008 Introduction
0009 ++++++++++++
0010
7accb48276 Jeff*0011 :filelink:`pkg/rbcs` provides the flexibility to relax fields (temperature,
14154de37c Mart*0012 salinity, ptracers, horizontal velocities) in any 3-D location, thus can be
0013 used to implement a sponge layer, or a “source” anywhere in the domain, among
0014 other uses.
8679f9097b Jeff*0015
14154de37c Mart*0016 For a field (:math:`T`) at every grid point the tendency is modified so that:
8679f9097b Jeff*0017
0018 .. math:: \frac{dT}{dt}=\frac{dT}{dt} - \frac{M_{rbc}}{\tau_T} (T-T_{rbc})
0019
14154de37c Mart*0020 where :math:`M_{rbc}` is a 3-D mask (no time dependence) between 0
0021 and 1. Values are relaxed to a field given by :math:`T_{rbc}`, which can be set
0022 to vary in time.
849a52ce32 Mart*0023 Where :math:`M_{rbc}(x,y,z) = 1.0`, the relaxing timescale is :math:`\tau_T`;
14154de37c Mart*0024 where :math:`M_{rbc}(x,y,z) = 0.0`, there is no relaxing. If
849a52ce32 Mart*0025 :math:`M_{rbc}(x,y,z) = 0.5` then relaxation occurs but at a timescale of
0026 :math:`2\,\tau_T`.
8679f9097b Jeff*0027
14154de37c Mart*0028 A separate mask can be used for :math:`\theta, S` and ptracers and each of
0029 these can be relaxed or not and can have its own timescale
0030 :math:`\tau_T`. These are set in ``data.rbcs`` (see below).
8679f9097b Jeff*0031
0032 Key subroutines and parameters
0033 ++++++++++++++++++++++++++++++
0034
0035 The only compile-time parameter you are likely to have to change is in
7accb48276 Jeff*0036 :filelink:`RBCS_SIZE.h <pkg/rbcs/RBCS_SIZE.h>`, the number of masks,
849a52ce32 Mart*0037 PARAMETER( :varlink:`maskLEN` = 3 ) by default, see below.
bf89a37abc Phob*0038
14154de37c Mart*0039 :numref:`tab_phys_pkg_rbcs_runtime_flags` summarizes the runtime flags that are
0040 set in ``data.rbcs``, and their default values.
bf89a37abc Phob*0041
0042 .. tabularcolumns:: |\Y{.285}|\Y{.09}|\Y{.105}|\Y{.545}|
0043
0d16355195 Oliv*0044 .. table:: RBCS runtime parameters
0045 :name: tab_phys_pkg_rbcs_runtime_flags
0046
7accb48276 Jeff*0047 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0048 | Flag/Parameter | Group | Default | Description |
0049 +====================================+========+========================+==============================================================================================================================================================+
0050 | :varlink:`rbcsForcingPeriod` | PARM01 | 0.0 | time interval between forcing fields (in seconds), zero means constant-in-time forcing |
0051 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0052 | :varlink:`rbcsForcingCycle` | PARM01 | 0.0 | repeat cycle of forcing fields (in seconds), zero means non-cyclic forcing |
0053 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0c4c42048f Jeff*0054 | :varlink:`rbcsForcingOffset` | PARM01 | 0.0 | time offset of forcing fields (in seconds), relative to time averages starting at :math:`t=0`, |
1904f49c87 Jeff*0055 | | | | i.e., the first forcing record/file is placed at (:varlink:`rbcsForcingOffset` + :varlink:`rbcsForcingPeriod`)/2; see below for examples |
7accb48276 Jeff*0056 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0057 | :varlink:`rbcsSingleTimeFiles` | PARM01 | FALSE | if ``.TRUE.``, forcing fields are given one file per :varlink:`rbcsForcingPeriod` |
0058 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0059 | :varlink:`deltaTrbcs` | PARM01 | :varlink:`deltaTclock` | time step used to compute the iteration numbers for :varlink:`rbcsSingleTimeFiles` = ``.TRUE.`` |
0060 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0061 | :varlink:`rbcsVanishingTime` | PARM01 | 0.0 | if :varlink:`rbcsVanishingTime` > 0, the relaxation strength reduces linearly to vanish at :varlink:`myTime` == :varlink:`rbcsVanishingTime` |
0062 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0063 | :varlink:`rbcsIter0` | PARM01 | 0 | shift in iteration numbers used to label files if :varlink:`rbcsSingleTimeFiles` = ``.TRUE.`` (see below for examples) |
0064 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0065 | :varlink:`useRBCtemp`, | PARM01 | FALSE | whether to use RBCS for T/S/U/V |
0066 | :varlink:`useRBCsalt`, | | | |
0067 | :varlink:`useRBCuVel`, | | | |
0068 | :varlink:`useRBCvVel` | | | |
0069 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0c4c42048f Jeff*0070 | :varlink:`tauRelaxT`, | PARM01 | 0.0 | timescales (in seconds) for relaxing T/S/U/V (:math:`\tau_T` in equation above); required if the corresponding ``useRBCxxx`` is ``.TRUE.`` |
7accb48276 Jeff*0071 | :varlink:`tauRelaxS`, | | | |
0072 | :varlink:`tauRelaxU`, | | | |
0073 | :varlink:`tauRelaxV` | | | |
0074 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0075 | :varlink:`relaxMaskFile` (irbc) | PARM01 | :kbd:`' '` | filename of 3-D file with mask (:math:`M_{rbc}` above), requires a file for each irbc (1=temperature, 2=salinity, 3=ptracer1, 4=ptracer2, etc); |
0076 | | | | if :varlink:`maskLEN` is less than the number of tracers, then :code:`relaxMaskFile(maskLEN)` is used for all remaining tracers |
0077 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0078 | :varlink:`relaxMaskUFile`, | PARM01 | :kbd:`' '` | filename of 3-D file with mask for U/V. |
0079 | :varlink:`relaxMaskVFile` | | | |
0080 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0081 | :varlink:`relaxTFile`, | PARM01 | :kbd:`' '` | name of file with 3-D relaxation field values (:math:`T_{rbc}` in equation above); |
0082 | :varlink:`relaxSFile`, | | | if :varlink:`rbcsSingleTimeFiles` = ``.FALSE.``, it must have one record for each forcing period, |
0083 | :varlink:`relaxUFile`, | | | otherwise there must be a separate file for each period with a 10-digit iteration number appended |
0084 | :varlink:`relaxVFile` | | | to the file name (see :numref:`tab_phys_pkg_rbcs_timing` and examples below) |
0085 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0086 | :varlink:`useRBCpTrNum` (iTrc) | PARM02 | FALSE | if ``.TRUE.``, use RBCS for the corresponding passive tracer |
0087 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0088 | :varlink:`tauRelaxPTR` (iTrc) | PARM02 | 0.0 | relaxing timescale (seconds) for the corresponding ptracer |
0089 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
0090 | :varlink:`relaxPtracerFile` (iTrc) | PARM02 | :kbd:`' '` | file with relaxation field for the corresponding ptracer |
0091 +------------------------------------+--------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+
8679f9097b Jeff*0092
0093 Timing of relaxation forcing fields
0094 +++++++++++++++++++++++++++++++++++
0095
14154de37c Mart*0096 For constant-in-time relaxation, set :varlink:`rbcsForcingPeriod` =0. For
0097 time-varying relaxation, :numref:`tab_phys_pkg_rbcs_timing` illustrates the
0098 relation between model time and forcing fields (either records in one big file
0c4c42048f Jeff*0099 or, for :varlink:`rbcsSingleTimeFiles` = ``.TRUE.`` , individual files labeled
14154de37c Mart*0100 with an iteration number). With :varlink:`rbcsSingleTimeFiles` = ``.TRUE.`` ,
0101 this is the same as in the offline package, except that the forcing offset is
0102 in seconds.
8679f9097b Jeff*0103
0104 .. tabularcolumns:: |l|l|l|c|
0105
0106 .. _tab_phys_pkg_rbcs_timing:
0107
0108 .. table:: Timing of RBCS relaxation fields
0109
0110 +-------------------+-------------------------------------------------------------------------------------+-------------------+
0111 | | rbcsSingleTimeFiles = T | F |
0112 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0113 | | :math:`c=0` | :math:`c\ne0` | :math:`c\ne0` |
0114 +===================+==========================================+==========================================+===================+
0115 | **model time** | **file number** | **file number** | **record** |
0116 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0117 | :math:`t_0 - p/2` | :math:`i_0` | :math:`i_0 + c/{\Delta t_{\text{rbcs}}}` | :math:`c/p` |
0118 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0119 | :math:`t_0 + p/2` | :math:`i_0 + p/{\Delta t_{\text{rbcs}}}` | :math:`i_0 + p/{\Delta t_{\text{rbcs}}}` | :math:`1` |
0120 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0121 | :math:`t_0+p+p/2` | :math:`i_0 + 2p/{\Delta t_{\text{rbcs}}}`| :math:`i_0 + 2p/{\Delta t_{\text{rbcs}}}`| :math:`2` |
0122 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0123 | ... | ... | ... | ... |
0124 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0125 | :math:`t_0+c-p/2` | ... | :math:`i_0 + c/{\Delta t_{\text{rbcs}}}` | :math:`c/p` |
0126 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0127 | ... | ... | ... | ... |
0128 +-------------------+------------------------------------------+------------------------------------------+-------------------+
0129
0130 where
0131
bf89a37abc Phob*0132 :math:`p` = :varlink:`rbcsForcingPeriod`
8679f9097b Jeff*0133
bf89a37abc Phob*0134 :math:`c` = :varlink:`rbcsForcingCycle`
8679f9097b Jeff*0135
bf89a37abc Phob*0136 :math:`t_0` = :varlink:`rbcsForcingOffset`
8679f9097b Jeff*0137
bf89a37abc Phob*0138 :math:`i_0` = :varlink:`rbcsIter0`
8679f9097b Jeff*0139
bf89a37abc Phob*0140 :math:`{\Delta t_{\text{rbcs}}}` = :varlink:`deltaTrbcs`
8679f9097b Jeff*0141
0142
0143
0144
0145 Example 1: forcing with time averages starting at :math:`t=0`
0146 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
0147
0148 Cyclic data in a single file
0149 #############################
0150
14154de37c Mart*0151 Set :varlink:`rbcsSingleTimeFiles` = :code:`.FALSE.` and
0152 :varlink:`rbcsForcingOffset` = 0, and the model will start by interpolating the
0153 last and first records of rbcs data, placed at :math:`-p/2` and :math:`p/2`,
0154 respectively, as appropriate for fields averaged over the time intervals
0155 :math:`[-p, 0]` and :math:`[0, p]`.
8679f9097b Jeff*0156
0157 Non-cyclic data, multiple files
0158 ###############################
0159
14154de37c Mart*0160 Set :varlink:`rbcsForcingCycle` = 0 and :varlink:`rbcsSingleTimeFiles` =
0161 :code:`.TRUE.` . With :varlink:`rbcsForcingOffset` = 0, :varlink:`rbcsIter0` =
0162 0 and :varlink:`deltaTrbcs` = :varlink:`rbcsForcingPeriod`, the model would
0163 then start by interpolating data from files ``relax\*File.0000000000.data`` and
0164 ``relax\*File.0000000001.data``, ... , again placed at :math:`-p/2` and
0165 :math:`p/2`.
8679f9097b Jeff*0166
0167 Example 2: forcing with snapshots starting at :math:`t=0`
0168 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
0169
0170 Cyclic data in a single file
0171 ############################
0172
14154de37c Mart*0173 Set :varlink:`rbcsSingleTimeFiles` = :code:`.FALSE.` and
0174 :varlink:`rbcsForcingOffset` =\ :math:`-p/2`, and the model will start forcing
0175 with the first record at :math:`t=0`.
8679f9097b Jeff*0176
0177 Non-cyclic data, multiple files
0178 ###############################
0179
14154de37c Mart*0180 Set :varlink:`rbcsForcingCycle` = 0 and :varlink:`rbcsSingleTimeFiles` =
0181 :code:`.TRUE.`. In this case, it is more natural to set
0182 :varlink:`rbcsForcingOffset` =\ :math:`+p/2`. With :varlink:`rbcsIter0` = 0 and
0183 :varlink:`deltaTrbcs` = :varlink:`rbcsForcingPeriod`, the model would then
0184 start with data from files ``relax\*File.0000000000.data`` at :math:`t=0`. It
0185 would then proceed to interpolate between this file and files
bf89a37abc Phob*0186 ``relax\*File.0000000001.data`` at :math:`t={}`\ :varlink:`rbcsForcingPeriod`.
8679f9097b Jeff*0187
0188 Do’s and Don’ts
0189 +++++++++++++++
0190
0191 Reference Material
0192 ++++++++++++++++++
0193
0194 Experiments and tutorials that use rbcs
0195 +++++++++++++++++++++++++++++++++++++++
0196
7accb48276 Jeff*0197 In the directory, the following experiments use :filelink:`pkg/rbcs`:
8679f9097b Jeff*0198
14154de37c Mart*0199 - tutorial :ref:`Southern Ocean Reentrant Channel <sec_eg_reentrant_channel>`
0200 makes use of :filelink:`pkg/rbcs` at its northern boundary as a sponge layer;
8679f9097b Jeff*0201
7accb48276 Jeff*0202 - :filelink:`exp4 <verification/exp4>` simulating flow over a Gaussian bump
0203 based on :cite:`adcroft:97`, demonstrating relaxation of a ptracer field.
