~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Quick getting-started guide to BaraKuda
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


I / What do you need to be able to use BaraKuda ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- A FORTRAN 90 compiler

- netcdf library with support for the appropriate F90 compiler

- NCO

- 'convert' from ImageMagick if you want to generate GIF movies (i_do_movi=1) 

- For time-series and 2D plots, the following up-to-date packages:
  => python-netcdf4 (from netCDF4 import Dataset) and Matplotlib
  => for map projections you'll also need the Basemap package
  
  A good idea is to install a shiny python distribution, something like Canopy:
  => https://www.enthought.com/products/canopy/

  In any case, specify the appropriate "PYTHON_HOME" environment variable in
  your config/conf_<MYCONF>.sh file

- NEMO output data! => A directory containing the MONTHLY-AVERAGED, global
                       (rebuilt), NEMO output to analyze
               (grid_T, grid_U, grid_V and icemod files) as "*.nc", "*.nc.gz" or ".nc4"

- a NEMO mesh_mask file and the the corresponding basin_mask (ocean basins).
  (variables MM_FILE and BM_FILE into your config/conf_<MYCONF>.sh file)
  To create the NEMO mesh_mask.nc just launch the relevant NEMO experiment with the
  namelist parameter nn_msh set to 1 !
  If you use ORCA1 or ORCA025 you can use the "<ORCA>_create_basin_mask_from_meshmask.py" in python/exec
  to generate the basin file!
              tmaskatl(y, x) => "Atlantic Basin" ;
              tmaskpac(y, x) => "Pacific Basin" ;
              tmaskind(y, x) => "Indian Basin" ;



II / Compile CDFTOOLS executables 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * CDFTOOLS is a set of FORTRAN executables intended to perform a multitude of
   diagnostics on NEMO output file and is developed by Jean-Marc Molines at LEGI
   in Grenoble.  However, this is a slightly modified light version here...
   SO DO NOT USE AN OFFICIAL CDFTOOLS DISTRIBUTION, stick to the one that comes with
   BaraKuda!

- move to the 'barakuda/cdftools_light' directory

- configure your own 'make.macro' for your system (some templates for gfortran and Intel are provided...)
    => just copy or link your own "macro.your_arch" to "make.macro" !
    => F90 compiler and related netcdf library to use

- compile with 'gmake'

- if that was successful the 'barakuda/bin' directory should contain the following executables
    => cdfcurl.x cdfmaxmoc.x cdfmhst.x cdfmoc.x cdfpsi.x  cdftransportiz.x  cdfzonalmean.x
       cdfhflx.x cdfmeanvar.x cdfmocatl.x cdfmoy.x cdfrmsssh.x cdfvT.x cdficediags.x  cdfmean.x
       cdfmocsig.x cdfmxl.x cdfsigtrp.x cdfw.x



III / Create and configure your own "configs/config_<MY_CONF>.sh" from an existing one
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NEMO output files must be monthly averages and of the following form:
==> <RUN NAME>_1m_<YEAR>0101_<YEAR>1231_<GRID_TYPE>.nc(.gz)   (GRID_TYPE=grid_T/grid_U/grid_V/icemod) 

Gzipped or not!

All files for all years must all be saved in the same directory (see
NEMO_OUT_STRCT in the config file). Better if this directory only contains NEMO
output files and nothing else!

Alternatively NEMO files can be saved/organized in sub-directories a la
EC-Earth: (ex: year 1995 of run started in 1990 is the 6th year so files for
1995 are saved into sub-directory (of NEMO_OUT_STRCT) "006" (set 'ece_run' to 1
or 2 then).

If you want to perform the "climatology" plots (see section IV) you will need
some 2D and 3D climatologies of T and S interpolated on the relevant ORCA
grid. Usually you should already have them since they are needed for your
simulation. These are the following files in your BaraKuda config file:
F_T_CLIM_3D_12, F_S_CLIM_3D_12, SST_CLIM_12



IV) Create diagnostics
~~~~~~~~~~~~~~~~~~~~~~

Launch "barakuda.sh" 
./barakuda.sh -C <MY_CONF> -R <RUN>
(ex: ./barakuda.sh -C ORCA1_L75_v36_triolith -R SL36C00)

Use the -h switch to see available options



V) Create figures and browsable HTML page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A/ Once the previous job has finished to run, launch

   * To only generate time-series plots use the "-e" switch:

   ./barakuda.sh -C <MY_CONF> -R <RUN> -e
   (ex: ./barakuda.sh -C ORCA1_L75_v36_triolith -R SL36C00 -e)

   * To generate time-series + 2D climatological plots use the "-E" switch,
     provided you have built a climatology out of your run with the
     "build_clim.sh" script (see point V/B):

   ./barakuda.sh -C <MY_CONF> -R <RUN> -E


B/ To be able to create the "climatology" plots (maps, sections, etc, based on a
   monthly climatology of a few years) you will have to

  i) create the climatology with the "build_clim.sh" script:
   
   ./build_clim.sh -C <MY_CONF> -R <RUN> -i <first_year> -e <last_year>
         (check ./build_clim.sh -h to see the other important options...)

    (ex: ./build_clim.sh -C ORCA1_L75_v36_triolith -R SL36C00 -f 10 -i 0090 -e 0099 -k 4)
      

  ii) the you can tell "barakuda.sh" to create climatology-related plots by
       using the "-E" switch instead of "-e" (see point V/A)


C/ To compare time-series between at least 2 runs (each already diagnosed, at least stage III):
   
   ./compare_time-series.sh -C <MY_CONF> -R <RUN1>,<RUN2>,...,<RUNn>
   (ex: ./compare_time-series.sh -C ORCA1_L75_v36_triolith -R SL36C00,SL36EIE )