<div class="title">Fjord Tidal Test Case</div>
 
 
{| style="width:98%; background:yellow; margin-top:10px; border:1px solid red;" cellpadding="5" cellspacing="0"
|-
|{{warning}} '''This WikiROMS article is currently under HEAVY construction. This message will be erased when active construction is finished (in 1 or 2 days).''' April 21, 2008 
|}

There are a few ways to setup tidal forcing in ROMS ([[Tidal_Forcing|...learn more about tides in ROMS]]). This tutorial will explain the simplest way, which is to prescribe (analytically) tidal variations in sea-surface height at a open boundary (this uses a FLATHER/CHAPMAN combination).
I learned this trick from '''hetland''' in this [https://www.myroms.org/forum/viewtopic.php?p=249&sid=a059e4ffb90b2ad96b0a5463875277fe forum post] (at the bottom).
 
 
{{warning}} RESTRICTIONS: This technique is ONLY applicable to embayments with a relatively small open boundary (say < 10 km). In this cases, the tidal height along the open boundary is essentially uniform and can be prescribed analytically.
 
 
{{warning}} PREREQUISITES: This tutorial assumes that you have (1) downloaded ROMS, (2) installed it in your computer (or cluster), and (3) tested it by compiling and running one of the included test cases. If you haven't done all the above, check the [[Getting_Started|"Getting Started"]] and [[Tutorials|"Tutorials"]] WikiROMS sections.
 
 

==Geographical Preamble==
This application is for Ship Harbour, an estuarine fjord in Nova Scotia, Canada. [http://maps.google.ca/maps/ms?hl=en&ie=UTF8&msa=0&ll=44.774524,-62.817421&spn=0.177915,0.310707&t=h&z=12&msid=109937017048460614209.00044a9aa08be20958242 Click here] to see the location in Google. Tides are semidiurnal and tidal range is 1.4 m on average and 2 m on spring tides. Ship Harbour is a long embayment (~7 km) with an open (EAST) boundary of ~1 km, therefore it is an ideal candidate for the type of analytical tidal forcing taught in this tutorial. For now I will only include tidal forcing, however, there is a river at the uppermost end of the estuary, which discharges freshwater at an annual average rate of 18 m3 s-1. I plan to write another tutorial on how to add a river, but for now is only tides.
 
 
==Grid Generation==
The first step to set up a realistic application is to set up a realistic grid. There are several [[Grid_Generation|software packages]] to generate ROMS grids; [[seagrid|SEAGRID]] and [http://www.marine.csiro.au/~sak007/ GRIDGEN] being the most popular ones. I used the much-less-fancy EASYGRID, which is a bit easier to get up and running.
 
 
[http://easygrid4roms.googlecode.com/files/FJORD_grid_ini.rar DOWNLOAD HERE] the '''grid and initialization files required for this tutorial'''. Alternatively, you can create your own grid and initialization files for this tutorial using the grid-generation software of your choice. You can download the bathymetry and coastline data for Ship Harbour Fjord [http://easygrid4roms.googlecode.com/files/EASYGRID_v0.rar HERE].
 
 
{{note}} NOTE: I also wrote a [[easygrid|tutorial for grid generation using EASYGRID]]. The output of that tutorial are the grid and initialization files '''used in this tutorial''' (see above). So if you want to start from scratch, you may want to begin with that tutorial.
 
 
==Compiling ROMS with tides==
Before you compile ROMS, you need to create a header (.h) file with the appropriate cpp definitions that turn ON the analytical tides. Also, you need to modify some analytical Fortran files, where you are going to specify how to create the analytical tide.

===Creating header (.h) file===

Create a file named fjord.h and copy-paste the cpp definitions below:

/*
**
** Options for Tidal Fjord.
**
** Application flag: FJORD
** Input script: ocean_fjord.in
*/
#define UV_ADV /* use to turn ON or OFF advection terms */
#define UV_COR /* use to turn ON or OFF Coriolis term */
#define UV_QDRAG /* use to turn ON or OFF quadratic bottom friction */
#define UV_VIS4 /* use to turn ON or OFF harmonic horizontal mixing */
#define MIX_S_UV /* momentum mixing on s-surfaces */
#define DJ_GRADPS /* use if splines density Jacobian (Shchepetkin, 2000) */
#define TS_U3HADVECTION /* use if 3rd-order upstream horiz. advection */
#define TS_C4VADVECTION /* use if 4th-order centered vertical advection */
#define SOLVE3D /* use if solving 3D primitive equations */
#define SPLINES /* use to activate parabolic splines reconstruction */
/* */
#define ANA_SMFLUX /* use if analytical surface momentum stress */
#define ANA_STFLUX /* use if analytical surface temperature flux */
#define ANA_SSFLUX /* use if analytical surface salinity flux */
#define ANA_BSFLUX /* use if analytical bottom salinity flux */
#define ANA_BTFLUX /* use if analytical bottom temperature flux */
#define MASKING /* use if analytical masking is enabled */
#define EAST_FSCHAPMAN /* use if free-surface Chapman condition*/
#define EAST_M2FLATHER /* use if 2D momentum Flather condition*/
#define EAST_M3RADIATION /* use if 3D momentum radiation condition*/
#define EAST_TRADIATION /* use if tracers radiation condition*/
#define ANA_FSOBC /* use if analytical free-surface boundary conditions*/
#define ANA_M2OBC /* use if analytical 2D momentum boundary conditions*/

{{note}} The last 6 cpp definitions are the responsible for the analytical tidal forcing. I used the basin.h header file as a starting template... the first 10 cpp definitions are from it. 
{{warning}} If your open boundary is not EAST... change EAST_FSCHAPMAN, EAST_M2FLATHER, EAST_M3RADIATION and EAST_TRADIATION to represent your open boundary (e.g. WEST__FSCHAPMAN for a west open boundary... etc.).

 
 

===Modify ana_fsobc.h===
You will have to edit the file ana_fsobc.h (located in trunk/ROMS/Functionals) to tell ROMS to estimate surface height analytically (at the open boundary) when running the FJORD case. Below is a snippet of the end of the file... you have to ADD the green code.
#elif defined TEST_CHAN
IF (WESTERN_EDGE) THEN
cff=0.0_r8
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=cff
END DO
END IF
IF (EASTERN_EDGE) THEN
cff=-0.4040_r8*MIN(time(ng)/150000.0_r8,1.0_r8)
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=cff
END DO
END IF
#elif defined WEDDELL
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)/REAL(Iend+1,r8)
phase=(277.0_r8+(277.0_r8-240.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=fac*val*COS(omega-phase)
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)
phase=(277.0_r8+(277.0_r8-240.0_r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=fac*val*COS(omega-phase)
END DO
END IF
#elif defined FJORD
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)
phase=(277.0_r8+(277.0_r8-240.0_r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=fac*val*COS(omega-phase)
END DO
END IF 
#else
IF (EASTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=0.0_r8
END DO
END IF
IF (WESTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=0.0_r8
END DO
END IF
IF (SOUTHERN_EDGE) THEN
DO i=IstrR,IendR
BOUNDARY(ng)%zeta_south(i)=0.0_r8
END DO
END IF
IF (NORTHERN_EDGE) THEN
DO i=IstrR,IendR
BOUNDARY(ng)%zeta_north(i)=0.0_r8
END DO
END IF
#endif
RETURN
END SUBROUTINE ana_fsobc_tile

 
 

===Modify ana_m2obc.h===
You will have to edit the file ana_m2obc.h (located in trunk/ROMS/Functionals) to tell ROMS to estimate currents analytically (at the open boundary) when running the FJORD case. Below is a snippet of the end of the file... you have to ADD the green code.
#elif defined WEDDELL
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)/REAL(Iend+1,r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)/REAL(Iend+1,r8)
phase=(318.0_r8+(318.0_r8-355.0_r8)/REAL(Iend+1,r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Istr-1,j)+angler(Istr,j))
BOUNDARY(ng)%ubar_west(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Istr-1,j-1)+angler(Istr-1,j))
BOUNDARY(ng)%vbar_west(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)
phase=(318.0_r8+(318.0_r8-355.0_r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Iend,j)+angler(Iend+1,j))
BOUNDARY(ng)%ubar_east(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Iend+1,j-1)+angler(Iend+1,j))
BOUNDARY(ng)%vbar_east(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
#elif defined FJORD
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)
phase=(318.0_r8+(318.0_r8-355.0_r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Iend,j)+angler(Iend+1,j))
BOUNDARY(ng)%ubar_east(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Iend+1,j-1)+angler(Iend+1,j))
BOUNDARY(ng)%vbar_east(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
#else
IF (EASTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%ubar_east(j)=0.0_r8
END DO
DO j=Jstr,JendR
BOUNDARY(ng)%vbar_east(j)=0.0_r8
END DO
END IF
IF (WESTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%ubar_west(j)=0.0_r8
END DO
DO j=Jstr,JendR
BOUNDARY(ng)%vbar_west(j)=0.0_r8
END DO
END IF
IF (SOUTHERN_EDGE) THEN
DO i=Istr,IendR
BOUNDARY(ng)%ubar_south(i)=0.0_r8
END DO
DO i=IstrR,IendR
BOUNDARY(ng)%vbar_south(i)=0.0_r8
END DO
END IF
IF (NORTHERN_EDGE) THEN
DO i=Istr,IendR
BOUNDARY(ng)%ubar_north(i)=0.0_r8
END DO
DO i=IstrR,IendR
BOUNDARY(ng)%vbar_north(i)=0.0_r8
END DO
END IF
#endif
RETURN
END SUBROUTINE ana_m2obc_tile

 
 
Now you are ready to compile ROMS! 
Same as you did with the test cases... now you have to compile ROMS using the newly created fjord.h header file. If you are unsure of how to compile ROMS, you may want to take a look to the [[build_Script|build.sh / build.bash]] page and to the [[Talk:build_Script|example]] within the "contributions" section of that page.
 
 

==Creating ocean_fjord.in==
Once ROMS has been compiled and you have your oceanS (or oceanM) executable file, you need to created an input file to run ROMS. You may want to make a copy of ocean_basin.in (trunk/ROMS/External) and use it as a starting template. {{warning}} Don't forget to rename the copy as ocean_fjord.in
 
 
Below are snippets of ocean_basin.in. In GREEN are the parts that you need to change in the copy (ocean_fjord.in). Parts in RED also need to be changed in the copy, but the actual ''replaced text'' will depend on your own configuration.
 
 
===Application Title & RHO-grid dimensions===
! Application title.
!
TITLE = Tidal Fjord
!
! C-preprocessing Flag.
!
MyAppCPP = FJORD
!
! Input variable information file name. This file needs to be processed
! first so all information arrays can be initialized properly.
!
VARNAME = ../PATH2VARINFO/varinfo.dat
!
! Grid dimension parameters. See notes below in the Glossary for how to set
! these parameters correctly.
!
Lm == 90 ! Number of I-direction INTERIOR RHO-points
Mm == 24 ! Number of J-direction INTERIOR RHO-points
N == 10 ! Number of vertical levels

{{note}} NOTE: The values of Lm, Mm and N are output to the screen when creating the grid file using EASYGRID.
 
 
 
===Parallelizations parameters ===
If Running ROMS in parallel, use the configuration below... otherwise you may leave NtileI == 1 and NtileJ == 1
! Domain decomposition parameters for serial, distributed-memory or
! shared-memory configurations used to determine tile horizontal range
! indices (Istr,Iend) and (Jstr,Jend), [1:Ngrids].
!
NtileI == 4 ! I-direction partition
NtileJ == 1 ! J-direction partition
 
 
 
===Time steps ===
! Time-Stepping parameters.
!
NTIMES == 1866241 ! 3 days
DT == 10
NDTFAST == 20

{{note}} NOTE: The values of DT is also output to the screen when creating the grid file using EASYGRID.
 
 
 

===Other parameters ===
This changes are just to speed up simulations.
! Number of eigenvalues (NEV) and eigenvectors (NCV) to compute for the
! Lanczos/Arnoldi problem in the Generalized Stability Theory (GST)
! analysis. NCV must be greater than NEV (see documentation below).
!
NEV = 2 ! Number of eigenvalues
NCV = 10 ! Number of eigenvectors
!
! Input/Output parameters.
!
NRREC == 0
LcycleRST == T
NRST == 360 ! Every 1 hour
NSTA == 360 ! Every 1 hour
NFLT == 360 ! Every 1 hour
NINFO == 360 ! Every 1 hour
!
! Output history, average, diagnostic files parameters.
!
LDEFOUT == T
NHIS == 60 ! Every 10 minutes
NDEFHIS == 0
NTSAVG == 1
NAVG == 60 ! Every 10 minutes
NDEFAVG == 0
NTSDIA == 1
NDIA == 60 ! Every 10 minutes
NDEFDIA == 0
 
 
 
===Diffusion coefficients ===
{{warning}} I'm not sure why, but the values below work ok, while other values make ROMS to blow up 
! Harmonic/biharmonic horizontal diffusion of tracer: [1:NAT+NPT,Ngrids].
!
TNU2 == 20.0d0 20.0d0 ! m2/s
TNU4 == 2*0.0d0 ! m4/s
!
! Harmononic/biharmonic, horizontal viscosity coefficient: [Ngrids].
!
VISC2 == 100.0d0 ! m2/s
VISC4 == 0.0d0 ! m4/s
 
 
 
===Vertical S-coordinates parameters===
Adjust parameters for the depth of the our fjord
! Vertical S-coordinates parameters, [1:Ngrids].
!
THETA_S == 5.0d0 ! 0 < THETA_S < 20
THETA_B == 0.4d0 ! 0 < THETA_B < 1
TCLINE == 30.0d0 ! m
 
 
 
===Time-stamp at start and reference time===
! Time-stamp assigned for model initialization, reference time
! origin for tidal forcing, and model reference time for output
! NetCDF units attribute.
!
DSTART = 52791.0d0 ! days
TIDE_START = 52791.0d0 ! days
TIME_REF = 18581117.0 ! yyyymmdd.dd
 
 
 

===Logical switches===
! Logical switches (TRUE/FALSE) to specify the state surface forcing
! variable whose stochastic optimals is required.
!
SOstate(isUstr) == F ! surface u-stress
SOstate(isVstr) == F ! surface v-stress
 
 
 
To speed up simulations
Hout(inert) == F ! inert passive tracers

Hout(idBott) == F F F F F F F F F F F F F F F F
 
 
 
===Input files===
Write path to the GRID and INITIALIZATION input files. !Comment-out the ones that we don't need.
! Input NetCDF file names, [1:Ngrids].
!
GRDNAME == ../PATH2yourFILE/Fjord_grd.nc
ININAME == ../PATH2yourFILE/Fjord_ini.nc
! ITLNAME == ocean_itl.nc
! IRPNAME == ocean_irp.nc
! IADNAME == ocean_iad.nc
! CLMNAME == ocean_clm.nc
! BRYNAME == ocean_bry.nc
! FWDNAME == ocean_fwd.nc
! ADSNAME == ocean_ads.nc
 
 
 

===Forcing files===
No forcing. !Comment-out the what we don't need.
! NFFILES == 1 ! number of forcing files
!
! FRCNAME == ocean_frc.nc ! forcing file 1, grid 1
 
 
 

===Output files===
Finally, the output file names (may want to change all, eventhough only his, avg and rst will be used)
! Output NetCDF file names, [1:Ngrids].
!
GSTNAME == Fjord_ocean_gst.nc
RSTNAME == Fjord_ocean_rst.nc
HISNAME == Fjord_ocean_his.nc
TLMNAME == Fjord_ocean_tlm.nc
TLFNAME == Fjord_ocean_tlf.nc
ADJNAME == Fjord_ocean_adj.nc
AVGNAME == Fjord_ocean_avg.nc
DIANAME == Fjord_ocean_dia.nc
STANAME == Fjord_ocean_sta.nc
FLTNAME == Fjord_ocean_flt.nc

 
 

==Running ROMS==

Similarly to the [[Getting_Started|"Getting Started"]] tutorial...
*To run ROMS in serial, just type:
oceanS < ROMS/External/ocean_fjord.in > & log &
*or to run in parallel (distributed-memory) on four processors:
mpirun -np 4 oceanM ROMS/External/ocean_fjord.in > & log &

2008-04-24T05:03:10Z

Diego: /* How to install MEXNC? */

<div class="title">Matlab MEXNC, SNCTOOLS and ROMS tool-kit</div>

MATLAB is powerful software that is commonly used to create ROMS inputs and to visualize and analyze ROMS output. However, out-of-the-box Matlab doesn't come with the capabilities to read/write ROMS NetCDF files. For that you need to download and install MEXNC, which is a mex-file interface to NetCDF files for MATLAB. In simple terms, it is a set of files (mex and .m files) that allows Matlab to read and write NetCDF files. Also, if you want to fully exploit Matlab's capabilities to manipulate/analyze ROMS files, you may want to download/install SNCTOOLS and the ROMS Matlab tool-kit, which are Matlab routines (that sit on top of MEXNC) that facilitate the manipulation, visualization and analysis of ROMS input/output NetCDF files. There are free alternatives to Matlab (see links below), however in this tutorial I will only review (some) tools for Matlab.

{| style="width:100%; background:Honeydew; margin-top:10px; border:1px solid YellowGreen; font-size:85%;" cellpadding="1" cellspacing="0"
|-
| '''Quick links:'''
|-
|[http://www.mathworks.com/products/matlab/ MATLAB]
|[http://mexcdf.sourceforge.net/ MEXNC project page]
|[http://mexcdf.sourceforge.net/tutorial SNCTOOLS tutorial] (for Matlab)
|-
|[http://www.scilab.org/ Scilab] Free Matlab-clone
|[http://ace.acadiau.ca/math/ACMMaC/software/scilab_netcdf.html Scilab/NetCDF Interface]
|[http://mexcdf.sourceforge.net/netcdf_toolbox/netcdf_toolbox.html NetCDF Toolbox] (for Matlab)
|-
|[http://www.gnu.org/software/octave/ Octave] Free Matlab-clone
|[http://ocgmod1.marine.usf.edu/mediawiki/index.php/NetCDF_toolbox_for_Octave OCTCDF] Octave/NetCDF interface
|}
 
__TOC__

==How to install MEXNC?==
You have to download the MEXNC version that matches BOTH, your specific Matlab version and your operating system. 

# First determine what Matlab version you have by typing on the Matlab command line:<div class="box">version('-release') </div>
# Then, go to the [http://mexcdf.sourceforge.net/downloads/ download] area, scroll down and click on your Matlab version (verify that you operating system is listed as an option).
# Download the latest release
# Extract (i.e. unzip or unpack) the file in a location where it can stay indefinitely
# In Matlab, add the path of your recently extracted mexnc directory. To do this...
#* Click on File > Set Path... (a GUI will pop-up)
#* Click on the Add with Subfolders... button, and add the path to your new mexnc folder
#* Click on the Save button, and close the GUI 
# If you are using WINDOWS operating system (I don't know if others too), you will have to add the netcdf.dll file to your Matlab system directory. To do this...
#* Go to your recently extracted mexnc directory and go inside the win32 folder...
#* Copy the netcdf.dll file and PASTE it into one (or both) of the following directories:<div class="box">C:\MATLAB\bin and/or C:\MATLAB\bin\win32</div>{{warning}} In the example above, C:\MATLAB is the location where matlab is located, but this '''may be different''' in your computer. 
#* Similarly as in '''(5)''', add the path to the directory(ies) above (i.e. C:\MATLAB\bin and C:\MATLAB\bin\win32) to the Matlab search path. {{note}} NOTE: In some cases, it will be important to have C:\MATLAB\bin and C:\MATLAB\bin\win32 at the '''TOP''' of the searching path. 
#* Done! However, you may need have to download [http://mexcdf.sourceforge.net/ SNCTOOLS] and the matlab tool-kit to be fully operational... read below.

{{note}} If you are using [http://www.scilab.org/ Scilab] (free Matlab-clone)... [http://ace.acadiau.ca/math/ACMMaC/software/scilab_netcdf.html Click here] to get the Scilab interface to NetCDF files. 

==How to install SNCTOOLS?==
Written by John Evans, [http://mexcdf.sourceforge.net/ SNCTOOLS] is a set of m-files that sit on top of MEXNC (and optionally, java) and strive to provide the user with a kinder, gentler interface (rather than MEXNC alone). Here is a [http://mexcdf.sourceforge.net/tutorial/index.html tutorial] and below are instructions for download and "installation":
# Go to the [http://sourceforge.net/project/showfiles.php?group_id=119464&package_id=130914 download] page and get the latest release.
# Extract the file in a location where it can stay indefinitely
# Similar to step '''(5)''' above, add the path to the recently extracted directory to the Matlab search path.

==How to install ROMS Matlab tool-kit?==
This is a compilation (from a lot of smart people) of matlab tools (i.e. m-files), that sit on top of SNCTOOLS (which sits on top of MEXNC). Here are instructions for download and "installation":
# Go to the [http://www.myroms.org/index.php?page=Processing download] page, enter the matlab directory, and download the '''matlab.tar.gz''' file.
# Extract the file in a location where it can stay indefinitely
# Similar to step (5) above, add the path to the recently extracted directory to the Matlab search path.

FJORD TIDAL CASE

2008-04-23T14:58:39Z

Diego: /* Creating ocean_fjord.in */

<div class="title">Fjord Tidal Test Case</div>
 
 
{| style="width:98%; background:yellow; margin-top:10px; border:1px solid red;" cellpadding="5" cellspacing="0"
|-
|{{warning}} '''This WikiROMS article is currently under HEAVY construction. This message will be erased when active construction is finished (in 1 or 2 days).''' April 21, 2008 
|}

There are a few ways to setup tidal forcing in ROMS ([[Tidal_Forcing|...learn more about tides in ROMS]]). This tutorial will explain the simplest way, which is to prescribe (analytically) tidal variations in sea-surface height at a open boundary (this uses a FLATHER/CHAPMAN combination).
I learned this trick from '''hetland''' in this [https://www.myroms.org/forum/viewtopic.php?p=249&sid=a059e4ffb90b2ad96b0a5463875277fe forum post] (at the bottom).
 
 
{{warning}} RESTRICTIONS: This technique is ONLY applicable in cases with one relatively narrow open boundary (say < 10 km). In this cases, the tidal height along the open boundary is essentially uniform and can be prescribed analytically.
 
 
{{warning}} PREREQUISITES: This tutorial assumes that you have (1) downloaded ROMS, (2) installed it in your computer (or cluster), and (3) tested it by compiling and running one of the included test cases. If you haven't done all the above, check the [[Getting_Started|"Getting Started"]] and [[Tutorials|"Tutorials"]] WikiROMS sections.
 
 

==Geographical Preamble==
This application is for Ship Harbour, an estuarine fjord in Nova Scotia, Canada. [http://maps.google.ca/maps/ms?hl=en&ie=UTF8&msa=0&ll=44.774524,-62.817421&spn=0.177915,0.310707&t=h&z=12&msid=109937017048460614209.00044a9aa08be20958242 Click here] to see the location in Google. Tides are semidiurnal and tidal range is 1.4 m on average and 2 m on spring tides. Ship Harbour is a long embayment (~7 km) with an open (EAST) boundary of ~1 km, therefore it is an ideal candidate for the type of analytical tidal forcing taught in this tutorial. For now I will only include tidal forcing, however, there is a river at the uppermost end of the estuary, which discharges freshwater at an annual average rate of 18 m3 s-1. I plan to write another tutorial on how to add a river, but for now is only tides.
 
 
==Grid Generation==
The first step to set up a realistic application is to set up a realistic grid. There are several [[Grid_Generation|software packages]] to generate ROMS grids; [[seagrid|SEAGRID]] and [http://www.marine.csiro.au/~sak007/ GRIDGEN] being the most popular ones. I used the much-less-fancy EASYGRID, which is a bit easier to get up and running.
 
 
DOWNLOAD HERE to get the '''GRID and INITIALIZATION files required for this tutorial'''. Alternatively, you can create your own grid and initialization files for this tutorial using the grid-generation software of your choice. You can download the bathymetry and coastline data for Ship Harbour Fjord [http://easygrid4roms.googlecode.com/files/EASYGRID_v1.rar HERE].
 
 
{{note}} NOTE: I also wrote a [[easygrid|tutorial for grid generation using EASYGRID]]. The output of that tutorial are the grid and initialization files '''used in this tutorial''' (see above). So if you want to start from scratch, you should begin with the EASYGRID tutorial.
 
 
==Compiling ROMS with tides==
Before we compile ROMS, we need to create a header (.h) file with the appropriate cpp definitions that turn ON the analytical tides. Also, we need to modify some analytical Fortran files, where we are going to specify how create the analytical tide.

===Creating header (.h) file===

Create a file named fjord.h and copy-paste the cpp definitions below:

/*
**
** Options for Tidal Fjord.
**
** Application flag: FJORD
** Input script: ocean_fjord.in
*/
#define UV_ADV /* use to turn ON or OFF advection terms */
#define UV_COR /* use to turn ON or OFF Coriolis term */
#define UV_QDRAG /* use to turn ON or OFF quadratic bottom friction */
#define UV_VIS4 /* use to turn ON or OFF harmonic horizontal mixing */
#define MIX_S_UV /* momentum mixing on s-surfaces */
#define DJ_GRADPS /* use if splines density Jacobian (Shchepetkin, 2000) */
#define TS_U3HADVECTION /* use if 3rd-order upstream horiz. advection */
#define TS_C4VADVECTION /* use if 4th-order centered vertical advection */
#define SOLVE3D /* use if solving 3D primitive equations */
#define SPLINES /* use to activate parabolic splines reconstruction */
/* */
#define ANA_SMFLUX /* use if analytical surface momentum stress */
#define ANA_STFLUX /* use if analytical surface temperature flux */
#define ANA_SSFLUX /* use if analytical surface salinity flux */
#define ANA_BSFLUX /* use if analytical bottom salinity flux */
#define ANA_BTFLUX /* use if analytical bottom temperature flux */
#define MASKING /* use if analytical masking is enabled */
#define EAST_FSCHAPMAN /* use if free-surface Chapman condition*/
#define EAST_M2FLATHER /* use if 2D momentum Flather condition*/
#define EAST_M3RADIATION /* use if 3D momentum radiation condition*/
#define EAST_TRADIATION /* use if tracers radiation condition*/
#define ANA_FSOBC /* use if analytical free-surface boundary conditions*/
#define ANA_M2OBC /* use if analytical 2D momentum boundary conditions*/

{{note}} The last 6 cpp definitions are the responsible for the analytical tidal forcing. I used the basin.h header file as a starting template... the first 10 cpp definitions are from it. 
{{warning}} If your open boundary is not EAST... change EAST_FSCHAPMAN, EAST_M2FLATHER, EAST_M3RADIATION and EAST_TRADIATION to represent your open boundary (e.g. WEST__FSCHAPMAN for a west open boundary... etc.).

 
 

===Modify ana_fsobc.h===
You will have to edit the file ana_fsobc.h (located in trunk/ROMS/Functionals) to tell ROMS to estimate surface height analytically when running the FJORD case. Below is a snippet of the end of the file... you have to ADD the green code.
#elif defined TEST_CHAN
IF (WESTERN_EDGE) THEN
cff=0.0_r8
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=cff
END DO
END IF
IF (EASTERN_EDGE) THEN
cff=-0.4040_r8*MIN(time(ng)/150000.0_r8,1.0_r8)
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=cff
END DO
END IF
#elif defined WEDDELL
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)/REAL(Iend+1,r8)
phase=(277.0_r8+(277.0_r8-240.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=fac*val*COS(omega-phase)
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)
phase=(277.0_r8+(277.0_r8-240.0_r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=fac*val*COS(omega-phase)
END DO
END IF
#elif defined FJORD
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)/REAL(Iend+1,r8)
phase=(277.0_r8+(277.0_r8-240.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=fac*val*COS(omega-phase)
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
val=0.53_r8+(0.53_r8-0.48_r8)
phase=(277.0_r8+(277.0_r8-240.0_r8))*deg2rad
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=fac*val*COS(omega-phase)
END DO
END IF 
#else
IF (EASTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_east(j)=0.0_r8
END DO
END IF
IF (WESTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%zeta_west(j)=0.0_r8
END DO
END IF
IF (SOUTHERN_EDGE) THEN
DO i=IstrR,IendR
BOUNDARY(ng)%zeta_south(i)=0.0_r8
END DO
END IF
IF (NORTHERN_EDGE) THEN
DO i=IstrR,IendR
BOUNDARY(ng)%zeta_north(i)=0.0_r8
END DO
END IF
#endif
RETURN
END SUBROUTINE ana_fsobc_tile

 
 

===Modify ana_m2obc.h===
You will have to edit the file ana_m2obc.h (located in trunk/ROMS/Functionals) to tell ROMS to estimate currents analytically when running the FJORD case. Below is a snippet of the end of the file... you have to ADD the green code.
#elif defined WEDDELL
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)/REAL(Iend+1,r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)/REAL(Iend+1,r8)
phase=(318.0_r8+(318.0_r8-355.0_r8)/REAL(Iend+1,r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Istr-1,j)+angler(Istr,j))
BOUNDARY(ng)%ubar_west(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Istr-1,j-1)+angler(Istr-1,j))
BOUNDARY(ng)%vbar_west(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)
phase=(318.0_r8+(318.0_r8-355.0_r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Iend,j)+angler(Iend+1,j))
BOUNDARY(ng)%ubar_east(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Iend+1,j-1)+angler(Iend+1,j))
BOUNDARY(ng)%vbar_east(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
#elif defined FJORD
IF (WESTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)/REAL(Iend+1,r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)/REAL(Iend+1,r8)
phase=(318.0_r8+(318.0_r8-355.0_r8)/REAL(Iend+1,r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8)/REAL(Iend+1,r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Istr-1,j)+angler(Istr,j))
BOUNDARY(ng)%ubar_west(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Istr-1,j-1)+angler(Istr-1,j))
BOUNDARY(ng)%vbar_west(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
IF (EASTERN_EDGE) THEN
fac=TANH((tdays(ng)-dstart)/1.0_r8)
omega=2.0_r8*pi*time(ng)/(12.42_r8*3600.0_r8) ! M2 Tide period
minor=0.0143_r8+(0.0143_r8+0.010_r8)
major=0.1144_r8+(0.1144_r8-0.013_r8)
phase=(318.0_r8+(318.0_r8-355.0_r8))*deg2rad
angle=(125.0_r8+(125.0_r8- 25.0_r8))*deg2rad
DO j=JstrR,JendR
val=0.5_r8*(angler(Iend,j)+angler(Iend+1,j))
BOUNDARY(ng)%ubar_east(j)=fac*(major*COS(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& SIN(omega-phase))
END DO
DO j=Jstr,JendR
val=0.5_r8*(angler(Iend+1,j-1)+angler(Iend+1,j))
BOUNDARY(ng)%vbar_east(j)=fac*(major*SIN(angle-val)* &
& COS(omega-phase)- &
& minor*SIN(angle-val)* &
& COS(omega-phase))
END DO
END IF
#else
IF (EASTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%ubar_east(j)=0.0_r8
END DO
DO j=Jstr,JendR
BOUNDARY(ng)%vbar_east(j)=0.0_r8
END DO
END IF
IF (WESTERN_EDGE) THEN
DO j=JstrR,JendR
BOUNDARY(ng)%ubar_west(j)=0.0_r8
END DO
DO j=Jstr,JendR
BOUNDARY(ng)%vbar_west(j)=0.0_r8
END DO
END IF
IF (SOUTHERN_EDGE) THEN
DO i=Istr,IendR
BOUNDARY(ng)%ubar_south(i)=0.0_r8
END DO
DO i=IstrR,IendR
BOUNDARY(ng)%vbar_south(i)=0.0_r8
END DO
END IF
IF (NORTHERN_EDGE) THEN
DO i=Istr,IendR
BOUNDARY(ng)%ubar_north(i)=0.0_r8
END DO
DO i=IstrR,IendR
BOUNDARY(ng)%vbar_north(i)=0.0_r8
END DO
END IF
#endif
RETURN
END SUBROUTINE ana_m2obc_tile

 
 
Now you are ready to compile ROMS! 
Same as you did with the test cases... now you have to compile ROMS using the newly created fjord.h header file. If you are unsure of how to compile ROMS, you may want to take a look to the [[build_Script|build.sh / build.bash]] page and to the [[Talk:build_Script|example]] within the "contributions" section of that page.
 
 
==Creating ocean_fjord.in==
Once ROMS has been compiled and you have your oceanS (or oceanM) executable file, you need to created an input file to run ROMS. You may want to make a copy of ocean_basin.in (trunk/ROMS/External) and use it as a starting template. {{warning}} Don't forget to rename the copy ocean_fjord.in
 
 
Below are snippets of ocean_basin.in. In GREEN are the parts that you need to change in the copy (ocean_fjord.in). Parts in RED also need to be changed in the copy, but the actual ''replaced text'' will depend on your own configuration.
 
 
! Application title.
!
TITLE = Tidal Fjord
!
! C-preprocessing Flag.
!
MyAppCPP = FJORD
!
! Input variable information file name. This file needs to be processed
! first so all information arrays can be initialized properly.
!
VARNAME = ../PATH2VARINFO/varinfo.dat
!
! Grid dimension parameters. See notes below in the Glossary for how to set
! these parameters correctly.
!
Lm == 90 ! Number of I-direction INTERIOR RHO-points
Mm == 24 ! Number of J-direction INTERIOR RHO-points
N == 10 ! Number of vertical levels

{{note}} NOTE: The values of Lm, Mm and N are output to the screen while creating the grid file using EASYGRID.
 
 
 
If Running ROMS in parallel, use the configuration below... otherwise you may leave NtileI == 1 and NtileJ == 1
! Domain decomposition parameters for serial, distributed-memory or
! shared-memory configurations used to determine tile horizontal range
! indices (Istr,Iend) and (Jstr,Jend), [1:Ngrids].
!
NtileI == 4 ! I-direction partition
NtileJ == 1 ! J-direction partition
 
 
 
! Time-Stepping parameters.
!
NTIMES == 17280 ! 2-days
DT == 10
NDTFAST == 20

{{note}} NOTE: The values of DT is also output to the screen while creating the grid file using EASYGRID.
 
 
 
This changes are just to speed up simulations.
! Number of eigenvalues (NEV) and eigenvectors (NCV) to compute for the
! Lanczos/Arnoldi problem in the Generalized Stability Theory (GST)
! analysis. NCV must be greater than NEV (see documentation below).
!
NEV = 2 ! Number of eigenvalues
NCV = 10 ! Number of eigenvectors
!
! Input/Output parameters.
!
NRREC == 0
LcycleRST == T
NRST == 360 ! Every 1 hour
NSTA == 360 ! Every 1 hour
NFLT == 360 ! Every 1 hour
NINFO == 360 ! Every 1 hour
!
! Output history, average, diagnostic files parameters.
!
LDEFOUT == T
NHIS == 60 ! Every 10 minutes
NDEFHIS == 0
NTSAVG == 1
NAVG == 60 ! Every 10 minutes
NDEFAVG == 0
NTSDIA == 1
NDIA == 60 ! Every 10 minutes
NDEFDIA == 0
 
 
 
{{warning}} Lets see if this works 
! Harmonic/biharmonic horizontal diffusion of tracer: [1:NAT+NPT,Ngrids].
!
TNU2 == 20.0d0 20.0d0 ! m2/s
TNU4 == 2*0.0d0 ! m4/s
!
! Harmononic/biharmonic, horizontal viscosity coefficient: [Ngrids].
!
VISC2 == 100.0d0 ! m2/s
VISC4 == 0.0d0 ! m4/s
 
 
 
Adjust parameters for the depth of the our fjord
! Vertical S-coordinates parameters, [1:Ngrids].
!
THETA_S == 5.0d0 ! 0 < THETA_S < 20
THETA_B == 0.4d0 ! 0 < THETA_B < 1
TCLINE == 30.0d0 ! m
 
 
 
! Logical switches (TRUE/FALSE) to specify the state surface forcing
! variable whose stochastic optimals is required.
!
SOstate(isUstr) == F ! surface u-stress
SOstate(isVstr) == F ! surface v-stress
 
 
 
To speed up simulations
Hout(inert) == F ! inert passive tracers

Hout(idBott) == F F F F F F F F F F F F F F F F
 
 
 
Write path to the GRID and INITIALIZATION input files. Comment-out the one that we don't need.
! Input NetCDF file names, [1:Ngrids].
!
GRDNAME == ../PATH2yourFILE/Fjord_grd.nc
ININAME == ../PATH2yourFILE/Fjord_ini.nc
! ITLNAME == ocean_itl.nc
! IRPNAME == ocean_irp.nc
! IADNAME == ocean_iad.nc
! CLMNAME == ocean_clm.nc
! BRYNAME == ocean_bry.nc
! FWDNAME == ocean_fwd.nc
! ADSNAME == ocean_ads.nc
 
 
 
No forcing.
NFFILES == 0 ! number of forcing files
!
! FRCNAME == ocean_frc.nc ! forcing file 1, grid 1
 
 
 
Finally, the output file names (change all, eventhough only his, avg and rst will be used)
! Output NetCDF file names, [1:Ngrids].
!
GSTNAME == Fjord_ocean_gst.nc
RSTNAME == Fjord_ocean_rst.nc
HISNAME == Fjord_ocean_his.nc
TLMNAME == Fjord_ocean_tlm.nc
TLFNAME == Fjord_ocean_tlf.nc
ADJNAME == Fjord_ocean_adj.nc
AVGNAME == Fjord_ocean_avg.nc
DIANAME == Fjord_ocean_dia.nc
STANAME == Fjord_ocean_sta.nc
FLTNAME == Fjord_ocean_flt.nc