Build rivers forcing

2.7. Build rivers forcing#

2.7.1. Introduction#

Unlike data from global ocean reanalyses, river data are heterogeneous and do not follow the same formalism.

make_rivers.py is a script that attempts to compensate for this lack of formalism by being able to read input data from river reanalysis (e.g. CEMS), or observations (e.g. in Europe Marinesitu).

Warning

Unlike the matlab tool, this script does not allow you to build a river forcing file from a climatology. However, it is possible to create a one-year, 365.25-day cycle.

Note

The script is currently unable to manage variations in river temperature and salinity. The cpp key to be used during simulation is PSOURCE_NCFILE. This allows us to take into account only a flow with a default temperature and salinity set in croco.in.

2.7.2. Edit the user-defined parameters#

All the requested user-defined parameters to build the rivers forcing are gathered in a configuration file, here named rivers.ini.

This file contains:

[Croco_Files]
croco_files_dir = ../results/CROCO_FILES
croco_grd_prefix = croco_grd
croco_rivers_prefix = croco_runoff

[Zoom_Options]
is_zoom = False
is_agrif = False
agrif_level = 0

[Times]
Ystart = 2013
Mstart = 1
Dstart = 1
Hstart = 12
Yend = 2013
Mend = 1
Dend = 31
Hend = 12
Yorig = 2000
Morig = 1
Dorig = 1
Horig = 0

[Rivers_Options]
nb_iter_mask = 3
rivers_freq = DAILY

[Rivers_Input_Files]
rivers_file_list = Examples/rivers_list.txt

The [Croco_Files] section defines the path and filenames for CROCO files:

croco_files_dir

Path of the CROCO files directory

croco_grd_prefix

Prefix for the CROCO grid file

croco_rivers_prefix

Prefix for the croco river forcing file (usually croco_runoff)

The [Zoom_Options] section defines if the grid is the main grid (parent grid) or a nested grid (zoom or child grid):

is_zoom

True/False flag to define if the grid is a zoom or the main grid

is_agrif

True/False flag to define if the grid is an agrif nested grid

agrif_level

integer level of the agrif grid to consider (0 is parent, 1 is first child)

The [Times] section defines:

Ystart, Mstart, Dstart, Hstart

year, month, day, hour of the chosen start date

Yend, Mend, Dend, Hend

year, month, day, hour of the chosen end date

Yorig, Morig, Dorig, Horig

year, month, day, hour of the time origin date

The [Rivers_Options] section defines:

nb_iter_mask

the number of iteration used to broaden the coast mask.

rivers_freq

equal to HOURLY,DAILY,MONTHLY depending on available data

The [Rivers_Input_Files] section defines:

rivers_file_list

Path/name of the file listing river data entries

2.7.3. Rivers input data available formats#

Unlike other scripts to generate forcing files, make_rivers does not use a reader to decrypt data because of the heterogeneity of formats.

The list of rivers to be taken into account is given to the script in a text file pointed by the rivers_file_list configuration parameter following this formalism:

# input_file     |    Lon    |  Lat/Qmin  |
river.nc            -2.05        47.30
loire.dat           -2.05        47.30
Rhone.txt            4.82        43.37
2ddata.nc             X            10

Each column represents, respectively, the river file, the longitude, and the latitude of the river mouth or the minimal flowrate to search for data.

Four formats are availables :

  • 2D netcdf file : the line must contain a filename with .nc extension, no longitude (X) and a Qmin value. The code will automatically determine the position of rivers meeting the minimum flow condition. Example above with 2ddata.nc: line, X is indicated for longitude data and 10 \(m^3/s\) for the minimum flow to be considered.

  • 1D netcdf file with one river : the line must contain a filename with .nc extension, longitude and latitude values (unique station). Example above with river.nc.

  • 1D netcdf file with several rivers : the line must contain a filename with .nc extension, no longitude (X) and no latitude (X) values (multiple stations)

  • text file : the line must contain a filename with another extension than .nc (example .txt or .dat), longitude and latitude values. Examples above with loire.dat or Rhone.txt.

For text file data, each line represents the river flow at a specific date such as:

1950/01/01 12:00:00 730.000000
1950/01/02 12:00:00 695.000000
1950/01/03 12:00:00 675.000000
1950/01/04 12:00:00 645.000000
1950/01/05 12:00:00 610.000000
1950/01/06 12:00:00 600.000000

Each line must follow the format YYYY/MM/DD hh:mm:ss Qsrc where Qsrc is the river flow at the time YYYY/MM/DD hh:mm:ss in \(m^3/s\).

Note

In the case of a netcdf file, the variable containing the river flow must have an element from this list as a unit attribute. ['m3 s-1','m**3 s**-1','m3/s'].

2.7.4. Build the rivers forcing conditions with make_rivers.py#

The make_rivers.py script will perform the following steps:

  • read rivers_file_list

  • read data for each format type

  • co-locate in time all data as CROCO use a unique time axis for all rivers data

  • check location on the CROCO grid mask. This is done automatically using make_rivers.py. It can be checked and changed manually using the notebook version: nb_make_rivers.ipynb.

To use the script you have to :

  • Edit your .ini configuration file (e.g. rivers.ini)

  • Launch the script:

    python make_rivers.py rivers.ini

  • Check the 2 generated files, which are defined with the prefix defined in croco_rivers_prefix:

    {croco_river_prefix}.nc
{croco_river_prefix}.in

2.7.5. Build and/or edit the rivers with nb_make_rivers.ipynb#

Following the given notebook nb_make_rivers.ipynb, you can generate a rivers forcing file or use an existent one and edit the rivers location and direction of flowrate.

You can also split a river on several grid points. The flowrate is then equally redistribute over all the point of the given base river. To do that, use the “Add point to selection” button. A new point is created for the river selected and new point names with a suffix “_splitk” are given to all points related to the initial river selected.

The river editor allows other fetures as :

  • hide/show a summary of all rivers in the CROCO grid domain. This summary shows :

    • the number of rivers, the number of points and the number of splitted river. If some rivers are splitted, the number of point is greater than the number of rivers.

    • the name of each river, its coordinates in mesh number i,j and in lon,lat, and the flow direction with dsrc and qbardir

  • select a river by (left) clicking on it. Note that selection is disabled in case of zooming features activated. Deactivate zoom before selection. When a river is selected, you can move it using a left click on the new location. Use a right click to unselect the river point.

  • modify dsrc and qbardir for the selected river

  • delete a river point selected

  • add a point to the selection to split a river. The flowrate is then equally redistribute over all the point of the given base river.

  • hide/show mesh and mask

  • undo action

  • save

Tip

When a river is moved, a green line and a new location marked in green can appear if the location choose is not compatible with the CROCO grid mask. This is to guide you in not selecting unavailable location.

On save, if some rivers are still in this case, they will be automatically moved

Contents