Content and architecture
-------------------------

**croco_pytools/prepro** remains in the footsteps of the matlab 
**croco_tools** by separating all the steps involved 
in preparing input files for a given configuration:

* Build the grid, interpolate and smooth the bathymetry, build the mask
* Build the lateral boundary conditions (3D currents, temperature and salinity, 
  barotropic currents, surface elevation)
* Build the initial conditions (3D currents, temperature and salinity, 
  barotropic currents, surface elevation)

And eventually:

* Build tidal forcing
* Build river forcing


The repository contains:

* The main python scripts or notebooks to perform the different steps of the 
  preprocessing (`make_*.py` and `nb_*.ipynb`). 
* Some scripts to download datasets that can be used as inputs to prepare 
  initial and boundary conditions for CROCO, as well as forcings 
  (e.g. atmospheric forcing, rivers)
* In `readers.jsonc`, a dictionnary to associate and decode the variable 
  names from input datasets (topo, initial and boundary conditions, 
  rivers, tides) with those used in the scripts
* Examples of configuration files containing user parameters to be 
  edited (directory `Examples`). 
  These files will be read and used by the scripts and notebooks.
* Test script can be found in `Tests` directory to perform functionnal test
  using given examples.
* The sub-directory with all sub-routines `Modules` containing all python 
  sub-routines to run the **croco_pytools/prepro**. Fortran routines are 
  in the sub-directory **tools_fort_routines**


.. tip::

    You can use separated configuration files for each script or a merged 
    version to use the same .ini file for all the scripts


The details of the content of each element is given below :

.. list-table::

   * - ``Examples``
     - Directory containing example on several areas
   * - ``make_grid.py``
     - Script to build CROCO grid and associated nests,
       see :ref:`Build the grid <tuto_grid>`
   * - ``nb_make_grid.ipynb``
     - Notebook version of the script to build CROCO grid, it allows visualizing 
       the grid, and edit its mask and bathymetry
   * - ``nb_make_grid_zoom.ipynb``
     - Notebook version of the script to build CROCO child grids (zooms), 
       it allows visualizing the nested grid, and edit its mask and bathymetry
   * - ``make_bry.py``
     - Script to build the lateral boundary conditions (surface elevation, 3D 
       currents, barotropic currents, temperature and salinity, other tracers)
       for CROCO grid and associated nests,
       see :ref:`Build initial and boundary conditions <tuto_ibc>`
   * - ``make_ini.py``
     - Script to build the initial 3D conditions (surface elevation, 3D currents, 
       barotropic currents, temperature and salinity, other tracers) for 
       CROCO grid and associated nests,
       see :ref:`Build initial and boundary conditions <tuto_ibc>`
   * - ``make_tides.py``
     - Script to build the tidal forcing (amplitude and phase) for elevation and 
       barotropic current,
       see :ref:`Build tidal forcing <tuto_tide>`
   * - ``make_rivers.py``
     - Script to create netcdf file containing runoff flows,
       see :ref:`Build rivers forcing <tuto_rivers>`
   * - ``nb_make_rivers.ipynb``
     - Notebook version of the script to build runoff flows, it allows 
       edit the location of each river.
   * - ``readers.jsonc``
     - Dictionnary to associate and decode the variable names from input 
       datasets (topo, initial and boundary conditions, 
       rivers, tides) with those used in the scripts,
       see :ref:`Readers for input data <tuto_readers>`
   * - ``download_mercator.py``
     - Script to download Mercator GLORYS products using the Copernicus Marine 
       API,
       see :ref:`Download Mercator dataset <download_mercator_lk>`
   * - ``download_hycom.py``
     - Script to download HYCOM products using the HYCOM OpenDAP server, 
       see :ref:`Download HYCOM dataset <download_hycom_lk>`
   * - ``download_era5.py``
     - Script to download ERA5 reanalysis using the Climate Data Store API,
       see :ref:`Download ERA5 dataset <download_era5_lk>`
   * - ``download_glofas_river.py``
     - Script to download river discharges from Global Flood Awareness System 
       (GloFAS) using the Climate Data Store API,
       see :ref:`Download GloFAS dataset <download_glofas_lk>`
   * - ``Modules``
     - Directory containing all python sub-routines to run the 
       **croco_pytools/prepro**. Fortran routines are in the 
       sub-directory **tools_fort_routines**
   * - ``Tests``
     - Directory containing a test python script, 
       see :ref:`Test script <test_script>`