River Input

Adding river input to FVCOM involves the following steps:

1. Create the necessary input files.
2. Add the relevant information to the name list.

Creating FVCOM input files from POLCOMS files

The FVCOM manual gives an example of the format for the NetCDF file required by FVCOM version 3.x. The script write_FVCOM_river.m generates a file matching this format. In addition, to convert a POLCOMS ASCII river file to FVCOM NetCDF, the function get_POLCOMS_rivers.m can be used. The procedure which follows outlines the necessary steps:

1. Read in an SMS mesh (read_sms_mesh).
2. Extract open boundary nodes (add_obc_nodes_list), assigning a value of 1 to the ObcType in add_obc_nodes_list's arguments if no mean flow will be applied, otherwise select 2 for the ObcType. See Table 6.1 in the FVCOM manual for the ObcType options.
3. Read in the POLCOMS river positions from and index file and a NetCDF of a POLCOMS model domain using get_POLCOMS_river_positions.
4. Read in the POLCOMS river discharges using get_POLCOMS_river_discharge.
5. For each river in the POLCOMS files, find the nearest node in the FVCOM domain using get_FVCOM_rivers. Nodes at which several rivers are added have their discharges summed.
6. Write out the river discharge data with write_FVCOM_river to NetCDF.

If river discharge is input at grid nodes, then the river node must not belong to an element with two coastline edges (and only one open edge). The figure below illustrates good and bad nodes for river input. In fact, elements with two coastline edges should be removed from the grid entirely as they will always have a zero velocity.

{{:configuration:river_nodes.png?600 |}}

Generating the rivers name list (nml) file

1. Follow the procedure above (number 1-5).
2. Run write_FVCOM_river_nml with the output of get_FVCOM_rivers to generate a name list with the necessary information in it.

N.B. The name list vertical distribution for the river discharge, temperature and salinity (RIVER_VERTICAL_DISTRIBUTION) based on the sigma levels. Alternatively, a string of 'uniform' may be added to the RIVER_VERTICAL_DISTRIBUTION value manually. To use the sigma levels derived vertical distribution, FVCOM may need to be compiled with FLAG_14 = -DRIVER_FLOAT uncommented. The default (commented) means the vertical distribution is given by a string (e.g. 'uniform', or '40*2.5E-02,10*0' (see here for an example)).

Editing the model name list

To include the river data in the model simulation, edit the following entries:

     &NML_RIVER_TYPE
     RIVER_NUMBER          = n,
     RIVER_KIND            = 'variable',
     RIVER_TS_SETTING      = 'calculated',
     RIVER_INFLOW_LOCATION = 'node',
     RIVER_INFO_FILE       = 'casename_riv.nml',
     /

Where n is the number of rivers in the NetCDF and name list (nml) files. Setting RIVER_TS_SETTING to calculated uses the modelled temperature and salinity adjusting as necessary to maintain mass conservation. RIVER_KIND can be changed to 'periodic' if the discharge data are climatology (i.e. not for a given year) rather than time series for a specific time. Do not include the RIVER_FILE directive if you have multiple rivers (which are each described in the casename_riv.nml file) otherwise the model will refuse to launch. Errors might include:

     Read_Name_List:
     &NML_RIVER_TYPE
     RIVER_NUMBER    =           1,
     RIVER_KIND      = variable                                                                        ,
     RIVER_TS_SETTING        = calculated                                                                      ,
     RIVER_INFO_FILE = casename_riv.nml                                                           ,
     RIVER_INFLOW_LOCATION   = node
     /
     Opend File: ./input/casename_riv.nml
     Bad River data in the Name List!
     Specified number of rivers:           1
     But Found           0 ; Valid river name list objects.(Printing Last)
     &NML_RIVER
     RIVER_NAME      = AFON_GOCH                                                                       ,
     RIVER_FILE      = casename_riv.nc                                                            ,
     RIVER_GRID_LOCATION     =        4100,
     RIVER_VERTICAL_DISTRIBUTION     = 0.1
     /
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     FVCOM Fatal Error!
     PLEASE REPAIR THE NAME LIST SO IT IS CONSISTANT... see above
     Stopping FVCOM
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

where the error is the inclusion of the RIVER_FILE directive (or a poorly formatted rivers namelist), or

     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     FVCOM Fatal Error!
     Can Not Read NameList NML_RIVER_TYPE from file: ./casename_run.nml
     Stopping FVCOM
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

where the error is the format of the rivers name list (nml) file. Both of these can be avoided by following the procedure outlined above.

A note about river names

FVCOM doesn't like river names which contain special characters (for example, spaces, (, ) or _. This list is obviously not exhaustive - please add to it as you find more). Numbers and - appear to be fine.

FVCOM also does not like two rivers sharing the same name. Rename your rivers, e.g. Name1 and Name2.

With either of these snags, FVCOM will crash and not tell you why.

WARNING

FVCOM does not interpolate river data in time but instead uses the nearest river time stamp to the current model time step. So, if you use data from the wrong year, the river input will always use the last or first (whichever is closer).