Rivers
======

**Related CPP options:**

================= ==========================================================================
PSOURCE           Activate point sources (rivers)
ANA_PSOURCE       | use analytical vertical profiles for point sources 
                  | (set in set_global_definitions.h)
PSOURCE_NCFILE    Read variable river transports in netcdf file
PSOURCE_NCFILE_TS Read variable river concentration in netcdf file
PSOURCE_MASS      | Apply point source as volume vertical influx at rho point
                  | instead of a flux through u,v interfaces
================= ==========================================================================


**ANA_PSOURCE**  gives the vertical distribution of point source outflow. The default 
shape is an exponential vertical distribution. The vertical shape can be customized 
in subroutine *ana_psource* in `analytical.F`


An example of runoff file with **PSOURCE_NCFILE** is given below ::

  netcdf croco_runoff {
  dimensions:
  qbar_time = 28193 ;
  n_qbar = 9 ;
  runoffname_StrLen = 30 ;
  two = 2 ;
  temp_src_time = 10690 ;
  salt_src_time = 10690 ;
  variables:
  double qbar_time(qbar_time) ;
    qbar_time:long_name = "runoff time" ;
    qbar_time:units = "days" ;
    qbar_time:cycle_length = 0. ;
    qbar_time:long_units = "days since 1900-01-01" ;
  char runoff_name(n_qbar, runoffname_StrLen) ;
    runoff_name:long_name = "runoff name" ;
  double runoff_position(n_qbar, two) ;
    runoff_position:long_name = "position of the runoff (by line) in the CROCO grid" ;
  double runoff_direction(n_qbar, two) ;
    runoff_direction:long_name = "direction/sense of the runoff (by line) in the CROCO grid" ;
  double Qbar(n_qbar, qbar_time) ;
    Qbar:long_name = "runoff discharge" ;
    Qbar:units = "m3.s-1" ;
  double temp_src_time(temp_src_time) ;
    temp_src_time:cycle_length = 0. ;
    temp_src_time:long_units = "days since 1900-01-01" ;
  double salt_src_time(salt_src_time) ;
    salt_src_time:cycle_length = 0. ;
    salt_src_time:long_units = "days since 1900-01-01" ;
  double temp_src(n_qbar, temp_src_time) ;
    temp_src:long_name = "runoff temperature" ;
    temp_src:units = "Degrees Celcius" ;
  double salt_src(n_qbar, temp_src_time) ;
    salt_src:long_name = "runoff salinity" ;
    salt_src:units = "psu" ;
                } 


When using **PSOURCE**, Isrc and Jsrc refer to the i,j index of the u-face or v-face the 
flow crosses - NOT the i,j index of the rho cell it flows into. The i,j values must follow 
ROMS Fortran numbering convention for the appropriate u-point or v-point on the ROMS 
staggered grid.

This numbering convention is shown in the figure below 
(Courtesy of `ROMS-RUTGERS <https://myroms.org/>`_  team) for flow crossing a u-face 
into a cell from either the left or the right. This makes it more obvious why the index 
of the u-face must be specified, because to give the i,j indices of the receiving 
rho-cell would be ambiguous.

The u-face or v-face should be a land/sea mask boundary (i.e. a coastline). If the cell 
face is placed wholly in the land you get nothing because there is no wet cell for the 
flow to enter. If the face is in the middle of open water you have a situation where the 
flow at that cell face computed by the advection algorithm is 'REPLACED, not augmented, 
by the source.

It is very easy to misconfigure source/sink locations so caution and careful checking is required.

.. image:: figures/river_riverposition.jpg
	:scale: 75 %

When using **PSOURCE_MASS**,  Isrc and Jsrc refer to the i,j index of the rho cell it flows into. 
In this case there is no need to be along land/sea boundary

.. note::

    **PSOURCE_MASS** is not available with openmp parallelization