Skip to content

Latest commit

 

History

History
203 lines (158 loc) · 17.6 KB

rbcs.rst

File metadata and controls

203 lines (158 loc) · 17.6 KB
Raw

RBCS Package

Introduction

:filelink:`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).

Key subroutines and parameters

The only compile-time parameter you are likely to have to change is in :filelink:`RBCS_SIZE.h <pkg/rbcs/RBCS_SIZE.h>`, the number of masks, PARAMETER( :varlink:`maskLEN` = 3 ) by default, see below.

:numref:`tab_phys_pkg_rbcs_runtime_flags` summarizes the runtime flags that are set in data.rbcs, and their default values.

.. tabularcolumns:: |\Y{.285}|\Y{.09}|\Y{.105}|\Y{.545}|
RBCS runtime parameters
Flag/Parameter Group Default Description
:varlink:`rbcsForcingPeriod` PARM01 0.0 time interval between forcing fields (in seconds), zero means constant-in-time forcing
:varlink:`rbcsForcingCycle` PARM01 0.0 repeat cycle of forcing fields (in seconds), zero means non-cyclic forcing
:varlink:`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 (:varlink:`rbcsForcingOffset` + :varlink:`rbcsForcingPeriod`)/2; see below for examples
:varlink:`rbcsSingleTimeFiles` PARM01 FALSE if .TRUE., forcing fields are given one file per :varlink:`rbcsForcingPeriod`
:varlink:`deltaTrbcs` PARM01 :varlink:`deltaTclock` time step used to compute the iteration numbers for :varlink:`rbcsSingleTimeFiles` = .TRUE.
:varlink:`rbcsVanishingTime` PARM01 0.0 if :varlink:`rbcsVanishingTime` > 0, the relaxation strength reduces linearly to vanish at :varlink:`myTime` == :varlink:`rbcsVanishingTime`
:varlink:`rbcsIter0` PARM01 0 shift in iteration numbers used to label files if :varlink:`rbcsSingleTimeFiles` = .TRUE. (see below for examples)
:varlink:`useRBCtemp`, :varlink:`useRBCsalt`, :varlink:`useRBCuVel`, :varlink:`useRBCvVel` PARM01 FALSE whether to use RBCS for T/S/U/V
:varlink:`tauRelaxT`, :varlink:`tauRelaxS`, :varlink:`tauRelaxU`, :varlink:`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.
:varlink:`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 :varlink:`maskLEN` is less than the number of tracers, then relaxMaskFile(maskLEN) is used for all remaining tracers
:varlink:`relaxMaskUFile`, :varlink:`relaxMaskVFile` PARM01 ' ' filename of 3-D file with mask for U/V.
:varlink:`relaxTFile`, :varlink:`relaxSFile`, :varlink:`relaxUFile`, :varlink:`relaxVFile` PARM01 ' ' name of file with 3-D relaxation field values (T_{rbc} in equation above); if :varlink:`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 :numref:`tab_phys_pkg_rbcs_timing` and examples below)
:varlink:`useRBCpTrNum` (iTrc) PARM02 FALSE if .TRUE., use RBCS for the corresponding passive tracer
:varlink:`tauRelaxPTR` (iTrc) PARM02 0.0 relaxing timescale (seconds) for the corresponding ptracer
:varlink:`relaxPtracerFile` (iTrc) PARM02 ' ' file with relaxation field for the corresponding ptracer

Timing of relaxation forcing fields

For constant-in-time relaxation, set :varlink:`rbcsForcingPeriod` =0. For time-varying relaxation, :numref:`tab_phys_pkg_rbcs_timing` illustrates the relation between model time and forcing fields (either records in one big file or, for :varlink:`rbcsSingleTimeFiles` = .TRUE. , individual files labeled with an iteration number). With :varlink:`rbcsSingleTimeFiles` = .TRUE. , this is the same as in the offline package, except that the forcing offset is in seconds.

.. tabularcolumns:: |l|l|l|c|
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 = :varlink:`rbcsForcingPeriod`

c = :varlink:`rbcsForcingCycle`

t_0 = :varlink:`rbcsForcingOffset`

i_0 = :varlink:`rbcsIter0`

{\Delta t_{\text{rbcs}}} = :varlink:`deltaTrbcs`

Example 1: forcing with time averages starting at t=0

Cyclic data in a single file

Set :varlink:`rbcsSingleTimeFiles` = .FALSE. and :varlink:`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].

Non-cyclic data, multiple files

Set :varlink:`rbcsForcingCycle` = 0 and :varlink:`rbcsSingleTimeFiles` = .TRUE. . With :varlink:`rbcsForcingOffset` = 0, :varlink:`rbcsIter0` = 0 and :varlink:`deltaTrbcs` = :varlink:`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.

Example 2: forcing with snapshots starting at t=0

Cyclic data in a single file

Set :varlink:`rbcsSingleTimeFiles` = .FALSE. and :varlink:`rbcsForcingOffset` =-p/2, and the model will start forcing with the first record at t=0.

Non-cyclic data, multiple files

Set :varlink:`rbcsForcingCycle` = 0 and :varlink:`rbcsSingleTimeFiles` = .TRUE.. In this case, it is more natural to set :varlink:`rbcsForcingOffset` =+p/2. With :varlink:`rbcsIter0` = 0 and :varlink:`deltaTrbcs` = :varlink:`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={}:varlink:`rbcsForcingPeriod`.

Do’s and Don’ts

Reference Material

Experiments and tutorials that use rbcs

In the directory, the following experiments use :filelink:`pkg/rbcs`: