Skip to content

River Boundary Conditions

This page explains how to configure river forcing in SURF-NEMO, including the supported input variables, input-file format, file placement, file naming, and how river data are connected to the NEMO simulation.

River forcing represents freshwater input from rivers into the coastal ocean. River discharge adds freshwater volume to the ocean that can affect local sea surface height, salinity distribution, coastal stratification, and river-plume dynamics in the nested domain.

In SURF-NEMO, each river is prescribed as a point source at a user-defined location representing the river mouth. The salinity value specified by the user at the river mouth contributes to the salinity tendency through the surface forcing term \(F^S\) in the salinity tracer equation:

\[ \frac{\partial S}{\partial t} = -\frac{1}{e_1 e_2} \left[ \frac{\partial \left(e_2 S u\right)}{\partial i} + \frac{\partial \left(e_1 S v\right)}{\partial j} \right] - \frac{1}{e_3} \frac{\partial \left(S w\right)}{\partial k} + D^S + F^S \]

where \(S\) is salinity; \(e_1\), \(e_2\), and \(e_3\) are the scale factors; \(u\), \(v\), and \(w\) are the velocity components; \(D^S\) is the subgrid-scale parameterisation term; and \(F^S\) is the surface forcing term.

Input Files

For each river input file, the user must provide time series for the following physical variables:

  • River Discharge, in \(m^3 s^{-1}\)

  • Salinity, in \(psu\), typically a small value or 0 for fresh river water

User can define multiple rivers in the same simulation, as long as each river has a correctly formatted input file. To represent a river that has multiple mouths or branches, each branch can be treated as a separate river. In this case, the total river discharge should be distributed carefully among the different branches so that the combined runoff remains equal to the intended total runoff.

In the current version, SURF-NEMO supports climatological river forcing only. Each river is defined by a 12-month cycle, with one value for each month of the year. Therefore, each river input file must contain exactly 12 data rows. River runoff is currently applied only at the ocean surface, in the uppermost model grid cell; vertical distribution of runoff over depth is not yet supported.

File placement

Where to place river input files

River input files must be placed in a subdirectory named river_input/ inside the experiment input-data directory.

The expected structure is:

Base Directory/

├── Experiment Directory/
│   └── ...
└── river_input/
    ├── RiverName1.txt
    ├── RiverName2.txt
    └── ...

The river_input/ directory is read during the preprocessing phase when river boundary conditions are enabled.

File format

How to format river input files

River input files must be saved as .txt files and must contain two columns in the following order:

Column 1 Column 2
Discharge [m3/s] Salinity [psu]

Use a semicolon (;) as column delimiter, with no spaces.

Example:

#Discharge [m3/s];Salinity [psu]
4000.47;0.1
800.98;0.1
38.23;0.1
49.82;0.1
32.66;0.1
22.57;0.1
14.27;0.1
10.46;0.1
11.39;0.1
8.95;0.1
17.32;0.1
5000.38;0.1

Exactly 12 data rows

The 12 rows correspond to the 12 months of the climatological year, from January to December. Files with fewer or more than 12 data rows are not valid.

The same monthly cycle is repeated for every simulated year.

File naming

How to name river input files

Each file must be named exactly as the corresponding river name defined in the JSON configuration file.

For example, if the river name in the configuration is:

"BusaLevante"

then the input file must be named:

BusaLevante.txt

River names and file names must match exactly, including capitalization.

How SURF-NEMO processes your river data

When river forcing is enabled, SURF-NEMO processes the user-provided text files during preprocessing and converts them into the river forcing file required by NEMO.

The workflow includes three main steps.

1. River grid-point selection

For each river coordinate pair defined in the configuration file, SURF-NEMO searches the child grid for a suitable coastal ocean cell where the river will be applied.

A valid river cell must be:

  • an ocean cell;
  • adjacent to at least one land cell;
  • not already assigned to another river.

Among the valid candidates, SURF-NEMO selects the closest cell to the user-defined river-mouth coordinates.

Each river is therefore assigned to exactly one grid cell.

2. Unit conversion

The monthly river discharge values are provided by the user as volume fluxes in \((m^3 s^{-1})\).

During preprocessing, SURF-NEMO converts these values into the freshwater flux format required by NEMO.

3. NetCDF forcing file generation

SURF-NEMO writes the processed river forcing to a single NetCDF file named:

surf_river.nc
This file contains:

  • sorunoff: freshwater mass flux;
  • s_river: river salinity;
  • river_mask: binary mask identifying the selected river cells;
  • a time dimension of length 12, corresponding to the climatological months.

Adding rivers to an experiment, step by step

Adding rivers to an experiment

To add river forcing to a SURF-NEMO experiment:

  1. Enable river forcing in the JSON configuration file.
  2. Define the river names and river-mouth coordinates in the river-forcing section.
  3. Prepare one .txt file for each river.
  4. Make sure each file contains one header line and exactly 12 monthly data rows.
  5. Save the files in the river_input/ directory.
  6. Run the experiment.
  7. After preprocessing, inspect surf_river.nc to verify the selected river cells.

Best practices

  • Start with a single river to validate the workflow before adding more.
  • Always provide an explicit salinity value, even for fully fresh rivers, rather than relying on defaults.
  • Check that your discharge values are physically realistic for the named river (e.g. Po ≈ 1500 m³/s annual mean).
  • After preprocessing, plot river_mask over the model bathymetry to confirm mouth locations before running long simulations.
  • Generate the surf_river.nc file only once per experiment. If you need to regenerate it in the same experiment, remove the existing file before running the routine again; otherwise, rivers may be unintentionally concatenated in the output file.