# 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 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.

- Read in an SMS mesh (
`read_sms_mesh`

). - 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. - Read in the sigma coordinates (use
`read_sigma`

to load a`sigma.dat`

file). - Identify the elements with a face along the open boundary (
`find_boundary_elements`

). - 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]. - 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`

). - 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.