TST-OBC

Update：20190320

We updated the codes by including inflow=0 for outflow in the OBC related codes, for example, in u2dbc_im.F , line: 278. It was excluded in version released on October 2, 2018, and we found that if you compile the code in an elder server with elder intel-fortran compiler, the elder code may not work properly. This update will solve this problem.

1. What is TST-OBC

TST-OBC is an “active” open boundary condition for circulations concurrently driven by tidal and subtidal forcings.  It is designed to permit dual-waves (tidal and subtidal) propagating across the OBs, and solving the barotropic and baroclinic velocities in a dynamics coherent way. It is integrated into the Rutgers ROMS Framework: October 2, 2018, and can be used by defining “TST” or “TSTNud” in the input parameter file (e.g. ocean_upwelling.in). In general, the codes just provide an alternative option, and will not greatly affect the current configuration applications. You can smoothly configure your applications by combing the TST-OBC options will those currently implemented in ROMS.

2. Copyright of TST-OBC in ROMS

This package of codes in ROMS is prepared from the scheme in Liu and Gan (2016). According to the license of ROMS, it is not recommended to distribute the modified code in this way. However, in order to share our research in an easier way, we prepared two package of codes. The copyright of ROMS should be strictly compiled. In terms of TST-OBC, we declare that:

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIMS, DAMAGES OR OTHER LIABILITIES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

3. How to implement the codes?

  1. Simply download the package ROMS3.7_TST.tar.gz, which is based on the very original version of ROMS (ROMS3.7.tar.gz) and configure the simulation.
  2. Migrate the codes by using subversion management software by comparing the source codes in ROMS3.7_TST.tar.gz and ROMS3.7.tar.gz
  3. Put the file ROMS3.7_TST_lite.tar.gz in your application directory (where the folder ROMS positions), and uncompress it.
  4. Search for keywords “LiuZHQ” in the codes and modify them accordingly. The related files, packaged in ROMS3.7_TST_lite.tar.gz, are shown in the file “modified_codes.txt”.

4. How to activate TST-OBC?

You can simply define TST (for 2D, 3D and tracers) or TSTNud (for 3D and tracers) as shown in “ocean_upwelling.in” to activate the TST-OBC. It should be noted that:

  1. According to the suggestion of ROMS, you are requested to set the topography and tidal forcing files at the position within three-grids away from the OBs be identical to that at the OBs;
  2. ADD_FSOBC and ADD_M2OBC should be excluded from your ROMS configuration.
  3. You should prepare the tidal forcing file in full-grid, instead of only define those tidally-related variables at the OBs;
  4. The meaning of M2NUDG, M3NUDG, TNUDG and OBCFAC is different from those in the very original version of ROMS. Nudging is always activated in TST-OBC when waves are transmitting into the computational domain, so, even when TST option is used for 3D velocities or tracers, boundary file, containing subtidal solutions from the upper-scale simulations, should be provided, and the time scale of nudging is determined by M3NUDG/OBCFAC or TNUDG/OBCFAC. When TSTNud is used for 3D velocities or tracers, the solution was restored towards the boundary values with the time scale is determined by M3NUDG and TNUDG, as well as OBCFAC. When TST is used for 2D velocities, a boundary file, containing the subtidal velocities from upper-scale simulations, should be provided, and the nudging timescale for flows under the condition when inward propagation of waves is calculated by M2NUDG/OBCFAC. In this sense, with appearance of concurrent tidal and subtidal forces, M2NUDG should be smaller, 1 hr or 1/24 days, for example. It should be noted that, since tidal and subtidal flows are concurrently provided, you have to tune the terms “M2NUDG, M3NUDG, TNUDG and OBCFAC” in your applications to find a proper combination.
  5. The terms M2FC and M2EtC are used to tune the intensity of tidal waves, whose scheme is shown in the following equation:

The default value for M2FC and M2EtC is 1.0.

5. Our recommendation of parameters:

    1. When tidal forcing is much stronger than subtidal flow in your applications (coastal area, for example), M2NUDG=1/24, M3NUDG=0.5, TNUDG=0.5, M2FC=1.0 M2EtC=1.0
    2. When tidal forcing in much weaker than subtidal flow in your applications (open ocean, for example), M2NUDG=0.5, M3NUDG=0.5, TNUDG=0.5, M2FC=1.0 M2EtC=1.0
    3. When TSTNud is used, the aforementioned combination can be respectively changed to:

M2NUDG=2/24, M3NUDG=1.0, TNUDG=1.0, M2FC=1.0 M2EtC=1.0, OBCFAC=2
M2NUDG=1.0, M3NUDG=1.0, TNUDG=1.0, M2FC=1.0 M2EtC=1.0, OBCFAC=2

  1. When there is not tidal forcing in your applications, just simply fill the value tidal_Eamp, tidal_Cmin and tidal_Cmax in your tidal forcing file with 0. Or, you can undefined SSH_TIDES and UV_TIDES from your ROMS configuration file and recompile your application. You are also suggested to use M2FC=0.0 under this condition.
  2. When you want to tune down the subtidal flow across OBs, tune down M2EtC to, for example, M2EtC=0.5
  3. You are suggested to use IMPLICIT_NUDGING in your configuration file (.h file in ROMS/Include)
  4. You can use RADIATION_2D in your configuration file, since it is preserved in the package.
  5. You can also combine TST-OBC with the default applications in ROMS, for example, TST for 2D velocities and RadNud for 3D velocities and tracers.

6. Source Codes and Citation

The TST-OBC source codes: TST-OBC.zip.

When TST-OBC is used, you are requested to cite our research:

Liu Z. and J. Gan, 2016. Open boundary conditions for tidally and subtidally forced circulation in a limited-area coastal model using the Regional Ocean Modeling System (ROMS), J. Geophys. Res (Oceans), 121 (8), 6184-6203, doi:10.1002/2016JC011975.

Please contact us at (Dr. Jianping GAN) magan@ust.hk or (Dr. Zhiqiang LIU) liuzhq@connect.ust.hk, if you want to know more details about the TST-OBC applications.