boundary_conditions_tide_velocity - UK-FVCOM-Usergroup/uk-fvcom GitHub Wiki

Open boundary treatments

The majority of the instructions here rely on the FVCOM MATLAB toolbox (fvcom-toolbox). In order to use the mean flow functions in FVCOM, FVCOM must be recompiled with the mean flow flag enabled in make.inc (as of 2013/02/26, this is FLAG_18 = -DMEAN_FLOW).

Tide only (spectral or surface elevation)

The process to generate boundary forcing with the MATLAB tools:fvcom-toolbox is as follows:

  • Read in an SMS mesh (read_sms_mesh).
  • Extract open boundary nodes (add_obc_nodes_list), assigning a value of 1 to the ObcType in add_obc_nodes_list's arguments. See Table 6.1 in the FVCOM manual for the ObcType options.
  • Save the open boundary node files with write_FVCOM_obc.

For spectral tides:

  • extract tidal harmonic amplitude and phases at the open boundary locations (making use of Mobj.read_obc_nodes to identify the nodes at the boundary). Both TPXO and POLPRED have successfully been used to extract the required values. Save the tidal amplitude and phases into Mobj.obc_amp and Mobj.obc_phase and use write_FVCOM_spectide to output to netCDF.

For surface elevations at the boundary:

  • using Mobj.read_obc_nodes to identify the open boundary nodes, use the TPXO tool tmd_tide_pred to generate time series for each node, saving to Mobj.surfaceElevation and Mobj.el_time and writing out with write_FVCOM_elevtide.

In the &NML_OPEN_BOUNDARY_CONTROL section of the namelist, set the following values:

    OBC_ON                     = T,
    OBC_NODE_LIST_FILE         = 'casename_obc.dat',
    OBC_ELEVATION_FORCING_ON   = T,
    OBC_ELEVATION_FILE         = 'casename_tide.nc',

where casename_tide.nc is the netCDF for the spectral or surface elevation tides.

Tide and mean flow

The tide aspect is similar to the pure tide situation above, but becomes more complicated for the mean flow.

  1. Read in an SMS mesh (read_sms_mesh).
  2. Extract open boundary nodes (add_obc_nodes_list), assigning a value of 2 to the ObcType in add_obc_nodes_list's arguments (this is "clamped" after Beardsley and Haidvogel (1981)). See Table 6.1 in the FVCOM manual for the ObcType options.
  3. Read in the sigma coordinates (use read_sigma to load a sigma.dat file).
  4. Identify the elements with a face along the open boundary (find_boundary_elements).
  5. Generate boundary mean flow values at the centroids of the open boundary elements. For the various output files, we need both u and v as well as depth averaged velocity at each boundary node position. get_POLCOMS_meanflow uses PML POLCOMS-ERSEM NetCDF files to interpolate mean flow to the FVCOM open boundary elements and vertical grid. The velocity data should be saved in Mobj.velocity of size [nElements, nTime] and the u and v components in Mobj.meanflow_u and Mobj.meanflow_v as arrays of size [nElements, nSiglay, nTime].
  6. The depth averaged velocity data at the open boundary nodes can be written to netCDF with write_FVCOM_meanflow. The NetCDF file generated includes the depth scaling factor (MFDIST) as well as the mean flow volume (DMFQDIS).
  7. In addition to the netCDF file, FVCOM has a number of files hard-coded into mod_obcs2.F which must also be generated for the mean flow condition. To do so, run write_FVCOM_meanflow_ascii, supplying the same velocity arrays (Mobj.velocity, Mobj.meanflow_u and Mobj.meanflow_v generated from the POLCOMS data, for example) as were used to create the netCDF file.

In the &NML_OPEN_BOUNDARY_CONTROL section of the namelist, set the following values:

    OBC_ON                     = T,
    OBC_NODE_LIST_FILE         = 'casename_obc.dat',
    OBC_ELEVATION_FORCING_ON   = T,
    OBC_ELEVATION_FILE         = 'casename_spectide.nc',
    OBC_MEANFLOW               = T,
    OBC_MEANFLOW_FILE          = 'casename_mf.nc',

Multiple Open Boundaries

The dimensions of Mobj.surfaceElevation must be [nObc_nodes, nTime] where nObc_nodes is the total number of nodes for ALL open boundaries, whether user specified (OBC_TYPE=1) or any other open boundary type, and nTime is the total number of time-steps. So, for example, in the case of a simple channel of constant width 11 nodes, with the upstream end a user specified open boundary and the downstream end closed the the size of Mobj.surfaceElevaton should be 11 by nTime and the casename_obc.dat file will read:

  OBC Node Number = 11
  1 n1 1
  2 n2 1
  ...

where ni is the node ID of the OBC node i. If the downstream end of the channel is now changed to a gravity-wave radiation open boundary (OBC_TYPE=5), whilst the upstream end remains a user specified open boundary, then the casename_obc.dat file will now read:

  OBC Node Number = 22
  1 n1 1
  2 n2 1
  ...
  12 n12 5
  13 n13 5
  ...

Now the dimensions of Mobj.surfaceElevation must be 22 by nTime even though the new open boundary is not user specified. So for this example the additional space in Mobj.surfaceElevation may be filled with zeros, but the dimensions must be [nObc_nodes, nTime] or FVCOM will call a fatal error.

Notes on mean flow

The mean flow parts of FVCOM are remnants from the FVCOM 2.7 code base. There are, therefore, some rough edges.

Firstly, the files which are read in to mod_obcs2.F are hard-coded in the source:

201      CALL FOPEN(INMF,   TRIM(INPUT_DIR)//TRIM(CASENAME)//'_meanflow.dat'  ,"cfr")
202      CALL FOPEN(INTCELL,TRIM(INPUT_DIR)//TRIM(CASENAME)//'_tide_cell.dat' ,"cfr")
203      CALL FOPEN(INTNODE,TRIM(INPUT_DIR)//TRIM(CASENAME)//'_tide_node.dat' ,"cfr")
204      CALL FOPEN(INTELEL,TRIM(INPUT_DIR)//TRIM(CASENAME)//'_tide_el.dat'   ,"cfr")
205      CALL FOPEN(INTUV,  TRIM(INPUT_DIR)//TRIM(CASENAME)//'_tide_uv.dat'   ,"cfr")

Their format is relatively straightforward (see print_vals.F and mod_obcs2.F) and is outlined below.

casename_meanflow.dat:

n
belID(1)
belID(2)
...
belID(m)
1 mfdist(1, 1) mfdist(1, 2) ... mfdist(1, z)
2 mfdist(2, 1) mfdist(2, 2) ... mfdist(2, z)
...
m mfdist(m, 1) mfdist(m, 2) ... mfdist(m, z)
tt
t(0)
dmfqdis(1, 1) dmfqdis(1, 2) ... dmfqdis(1, m)
t(1)
dmfqdis(2, 2) dmfqdis(2, 2) ... dmfqdis(2, m)
...
t(n-1)
dmfqdis(tt, 1) dmfqdis(tt, 2) ... dmfqdis(tt, m)

where m is the number of boundary elements, belID is the boundary element IDs, mfdist is the vertical distribution of mean flow flux, z is the number of vertical layers, dmfqdis is the mean flow flux, t is the time step number (not time) and tt is the number of time steps.

casename_tide_el.dat:

tt(1) elev(1, 1) elev(1, 2) ... elev(1, m)
tt(2) elev(2, 1) elev(2, 2) ... elev(2, m)
...
tt(t) elev(t, 1) elev(t, 2) ... elev(t, m)

where tt is the time since the model start in seconds, t is the number of time steps, m is the number of boundary nodes and elev is the surface elevation at the open boundary nodes.

casename_tide_node.dat:

n
bndID(1)
bndID(2)
...
bndID(n)

where n is the number of boundary nodes and bndID is the boundary node IDs.

casename_tide_cell.dat:

e
belID(1)
belID(2)
...
belID(e)

where e is the number of boundary elements and belID is the boundary element IDs.

casename_tide_uv.dat:

tt(1) ubar(1, 1) ubar(1, 2) ... ubar(1, m)
tt(1) vbar(1, 1) vbar(1, 2) ... vbar(1, m)
tt(1) u(1, 1, 1) u(1, 1, 2) ... u(1, 1, m)
tt(1) v(1, 1, 1) v(1, 1, 2) ... v(1, 1, m)
tt(1) u(1, 2, 1) u(1, 2, 2) ... u(1, 2, m)
tt(1) v(1, 2, 1) v(1, 2, 2) ... v(1, 2, m)
...
tt(1) u(1, z, 1) u(1, z, 2) ... u(1, z, m)
tt(1) v(1, z, 1) v(1, z, 2) ... v(1, z, m)
tt(2) ubar(2, 1) ubar(2, 2) ... ubar(2, m)
tt(2) vbar(2, 1) vbar(2, 2) ... vbar(2, m)
tt(2) u(2, 1, 1) u(2, 1, 2) ... u(2, 1, m)
tt(2) v(2, 1, 1) v(2, 1, 2) ... v(2, 1, m)
tt(2) u(2, 2, 1) u(2, 2, 2) ... u(2, 2, m)
tt(2) v(2, 2, 1) v(2, 2, 2) ... v(2, 2, m)
...
tt(2) u(2, z, 1) u(2, z, 2) ... u(2, z, m)
tt(2) v(2, z, 1) v(2, z, 2) ... v(2, z, m)
...
...
tt(t) ubar(t, 1) ubar(t, 2) ... ubar(t, m)
tt(t) vbar(t, 1) vbar(t, 2) ... vbar(t, m)
tt(t) u(t, 1, 1) u(t, 1, 2) ... u(t, 1, m)
tt(t) v(t, 1, 1) v(t, 1, 2) ... v(t, 1, m)
tt(t) u(t, 2, 1) u(t, 2, 2) ... u(t, 2, m)
tt(t) v(t, 2, 1) v(t, 2, 2) ... v(t, 2, m)
...
tt(t) u(t, z, 1) u(t, z, 2) ... u(t, z, m)
tt(t) v(t, z, 1) v(t, z, 2) ... v(t, z, m)

where tt is the time in seconds (since the start of the time series?), t is the time index, m is the number of boundary elements, z is the number of sigma layers, u and v and the mean flow u and v components (sized [t, z, m]) and ubar and vbar are the depth-averaged mean flow u and v components (sized [t, m]).

casename_elj_obc.dat is an extra file specified in mod_obcs2.F at line 235:

235        CALL FOPEN(111,TRIM(INPUT_DIR)//TRIM(CASENAME)//'_elj_obc.dat',"cfr")

It's format is very similar to casename_tide_el.dat except it omits the time stamp in the first column:

casename_elj_obc.dat:

elev(1, 1) elev(1, 2) ... elev(1, m)
elev(2, 1) elev(2, 2) ... elev(2, m)
...
elev(tt, 1) elev(tt, 2) ... elev(tt, m)

where tt is the number of time steps, m is the number of boundary nodes and elev is the surface elevation at the open boundary nodes.