.. _tuto_readers:

Readers for input data
-----------------------

Several types of data are used to prepare files for CROCO realistic simulations: 

* topographic/bathymetric data to build the model bathymetry
* 3D ocean data (generally from another (re-)analysis) to build the initial 
  and boundary conditions
* tidal harmonics to build the tidal forcing

To read these data, depending on their own formatting, the toolbox uses the 
configuration file ``readers.jsonc``.

Several readers are already implemented, but you can add any other reader for 
managing your input data if needed. 

.. note:: 
  
  Several readers are designed for "homemade preprocessed data" inherited from 
  **croco_tools** and available in 
  example datasets provided along with CROCO (e.g. etopo2, cfsr, mercator_croco...)


Topography : section "Topo" of ``readers.jsonc`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Input data needed by the tools must be in netcdf format. The extensions
of the files could be .nc or .grd.

To build bathymetry from a netcdf file, the dictionnary needs at least four keys:

.. list-table::

  * - ``lon``
    - Longitude 
  * - ``lat``
    - Latitude
  * - ``topo``
    - Name of the 2-D bathymetric field
  * - ``zaxis``
    - Direction of z axis (up or down)


.. warning::

  A supplementary key ``srtm`` needs to be added and set to ``True`` if the input 
  dataset is `STRM30plus <https://topex.ucsd.edu/WWW_html/srtm30_plus.html>`_



Initial and boundary conditions: section "IBC" of ``readers.jsonc`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Reader for initial and boundary conditions (ibc) handles 2D and 3D fields and 
their evolution in time. It requires their coordinates:

.. list-table::

    * - ``depth``
      - Z-coordinates variables 
    * - ``lonr, lonu, lonv``
      - Longitude name for Rho,U,V grid. If only one grid put the same name 
        everywhere
    * - ``latr, latu, latv``
      - Latitude name for Rho,U,V grid. If only one grid put the same name 
        everywhere
    * - ``time, time_dim``
      - Time variable and the associated time dimension

And the following fields:

.. list-table::

    * - ``ssh``
      - Sea Surface Elevation variable name
    * - ``u``
      - Eastward velocity (m/s) variable name
    * - ``v``
      - Northward velocity (m/s) variable name
    * - ``temp``
      - temperature (C) variable name
    * - ``salt``
      - salinity (PSU) variable name

You can also add other tracers if needed following the same pattern:

::

    "temp": "thetao",
    "salt": "so",
    "tracer": "tracer_name_in_dataset",


Tides: section "Tides" of ``readers.jsonc`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First the keys for geographical coordinates are specified:

.. list-table:: 

   * - ``lonr, lonu, lonv``
     - Longitude name for Rho, U, V grid. If only one grid put the same name 
       everywhere
   * - ``latr, latu, latv``
     - Latitude name for Rho, U, V grid. If only one grid put the same name 
       everywhere

Tide data consist in three fields (elevation, easwtward velocity, northward 
velocity), and each field has two components. Depending on the input dataset, 
those two components can be either Amplitude/Phase 
(like `FES <https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>`_)
or Real/Imaginary part (like `TPXO <https://www.tpxo.net/global>`_).

If your dataset follows an Amplitude/Phase, keys to declare are:

.. list-table::

   * - ``H_a``
     - Elevation amplitude
   * - ``H_p``
     - Elevation phase
   * - ``U_a``
     - Eastward velocity amplitude
   * - ``U_p``
     - Eastward velocity phase
   * - ``V_a``
     - Northward velocity amplitude
   * - ``V_p``
     -  Northward velocity phase

Or if it follows a Real/Imaginary format, keys to declare are:

.. list-table::

   * - ``H_r``
     - Elevation real part
   * - ``H_i``
     - Elevation imaginary part
   * - ``U_r``
     - Eastward velocity real part
   * - ``U_i``
     - Eastward velocity imaginary part
   * - ``V_r``
     - Northward velocity real part
   * - ``V_i``
     - Northward velocity imaginary part


Some datasets like TPXO follow a complex a-b*i convention. You therefore need 
to pay attention to the sign when calculating the phase. 
A flag for the phase is thus provided:

.. list-table::

   * - ``invert_phase``
     - true/false flag. True when need to revert the phase (e.g. TPXO case)


In addition, for some datasets, like TPXO, U and V are given as transport. 
To convert them to velocities, the depth is required, thus additional
variables are provided in the reader:

.. list-table:: 

   * - ``topor, topou, topov``
     - depth name for Rho, U, V grid. If only one grid put the same name 
       everywhere