Adding Rivers
=============

If you want to include rivers in your simulation domain, there are several 
variables to define as:

* the number of rivers: Nsrc
* the position of the rivers on the model grid: **Isrc** and **Jsrc**
* the zonal or meridional axis of the river flow: **Dsrc**
* **if flow (and concentration) is constant**,  the flow rate of the river 
  (in m3/s): **Qbar** (positive or negative)
* **if flow (and concentration) is variable, and read from a netCDF file**, 
  the direction of the flow  **qbardir**: 

  *  1 for west-east / south-north
  * -1 for east-west / north-south

* the type of tracer advected by the river: **Lsrc**
* the value/concentration: **Tsrc**

Constant flow and concentration
################################

For this you need to define the cpp-keys in cppdefs.h 
::
  
    #define PSOURCE

And re-compile. 

Then in the croco.in file  
::    

    psource:   Nsrc  Isrc  Jsrc  Dsrc  Qbar [m3/s]    Lsrc        Tsrc
             2
                     3    54     1    200.       T T      20. 15.
                     3    40     0    200.       T T      20. 15.


where Nsrc=2 is the number of rivers processed, then each line describes a 
river. Let’s describe the parameter for river #1:

* Isrc=3, Jsrc=54 are the i, j indices where the river is positioned
* Dsrc=1  indicates the orientation (here meridional => along V direction)
* 200 is the runoff flow value in m3/s, oriented to the east
* T T are true/false indications for reading or not the following variables 
  (here temperature and salinity)
* 20 and 15 are respectively the temperature and salinity of the river. 
  You can edit these parameters.

.. warning:: 
  
  The sources points must be placed on U or V points on the C-grid and not 
  on rho-points

You can then run the model:

::

    qsub job_croco_mpi.pbs


Variable flow read in a netCDF file and **constant concentration**
##################################################################

Instead of using a constant flow, you can use variable flow. 
For that you need read it from a netcdf file. 
First define the dedicated cpp-key in cppdefs.h 
::

    #define PSOURCE_NCFILE  

And re-compile the model. 

Then you also need to prepare the netcdf river runoff input file. 

For that, you can choose one of the option :

* If you are using Matlab croco_tools, you can use ``make_runoff`` 
  (Rivers/make_runoff.m) which detect the main rivers located in your domain 
  (from **RUNOFF_DAI** runoff climatology : a global monthly runoff climatology 
  containing the  925 first rivers over the world, 
  from *Dai and Trenberth, 2000*). 
  See https://croco-ocean.gitlabpages.inria.fr/croco_tools/
* If you are using Python croco_pytools, you can use ``make_rivers.py``.
  See https://croco-ocean.gitlabpages.inria.fr/croco_pytools/


.. warning:: 

    The order of the sources in the ``croco.in`` file must match the order of 
    the netcdf file. 
    It's impliticly the case if you generate your runoff file with the 
    croco_tools or croco_pytools 
    which give you the lines to add into your croco.in
  

Variable flow and **variable concentration** from a netCDF file 
###################################################################

To run CROCO with a variable concentration of river tracers, you need to 
define the following cpp-key in cppdefs.h

::

  #define PSOURCE_NCFILE_TS

You also need to prepare your netcdf input file following the tools 
documentation (Matlab or Python) and adapt your croco.in file :

::

  psource_ncfile:   Nsrc  Isrc  Jsrc  Dsrc qbardir  Lsrc  Tsrc   runoff file name
                           CROCO_FILES/croco_runoff.nc
                 2 
                        25  34  0  -1   30*T   16.0387 25.0368
                        30  19  0  -1   30*T   16.1390 25.1136

You also can edit these parameters. 

.. warning::

  The Tsrc value reported in croco.in are the annual-mean tracer values, 
  they are just for information. The real tracer concentration (Tsrc) are 
  read in the runoff netCDF file created. 


Using a nest
############

The above procedure can be applied to a nested grid to generate 

::

  croco_runoff.nc.1


.. note:: 
  
  The runoff has a default vertical profile defined in CROCO as an 
  exponential vertical distribution of velocity. It is in ``analytical.F``, 
  subroutine ``ana_psource`` if you need to change it.