Example of a set of web pages generated by Barakuda: https://brodeau.github.io/barakuda/example/

Getting-started with Barakuda

Requirements

• A FORTRAN 90 compiler

• netcdf library with support for the appropriate F90 compiler

• NCO

• 'convert' from ImageMagick if you want to generate GIF movies

• 'ffmpeg' with x264 support if you want to generate MP4 movies

• 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 ${BARAKUDA_ROOT}/configs/config_.sh or ./config_.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"

  For NEMO 3.6 and above some appropriate sets of xml configuration files for XIOS2 can be found in: src/xios2_xml/

• a NEMO mesh_mask file and the the corresponding basin_mask (ocean basins). (variables MM_FILE and BM_FILE into the config_.sh file you use).

  To create the NEMO mesh_mask.nc just launch the relevant NEMO experiment with the namelist parameter nn_msh set to 1 !

  For both ORCA1 and ORCA025 configs (regardless of the number of levels) it is safe to use the basin_mask.nc provided in the "data/" sub-directory of Barakuda.

  If you want to create your own basin_mask.nc containing your favorite seas/regions, proceed as follow:

  1. use the "python/exec/orca_mesh_mask_to_bitmap.py" python script to create a black-and-white bitmap image of the land-sea-mask from the mesh_mask.nc generated by NEMO.

  2. use your favorite rater image editor (Gimp, PhotoShop, Paint, etc) to easily edit the bitmap image and create a new image of your sea/region of interest. Save it as a "tiff" image!

  3. then you can use "python/exec/tiff_to_orca_mask.py" python script to generate the new basin_mask.nc netcdf file out of your tiff images!

I / Compile CDFTOOLS executables

• CDFTOOLS is a set of FORTRAN executables intended to perform a multitude of ocean diagnostics based on NEMO output (https://github.com/meom-group/CDFTOOLS). 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 8 following executables:

    * cdficediags.x
    * cdfmaxmoc.x
    * cdfmhst.x
    * cdfmoc.x
    * cdfpsi.x
    * cdfsigtrp.x
    * cdficeflux.x
    * cdftransportiz.x
    * cdfvT.x
  

II / Create and configure your own "config_<MY_CONF>.sh"

All setup related to your host, simulation, location of third party files is defined in the "config_<MY_CONF>.sh" file.

You can either used to chose a config file located in the "${BARAKUDA_ROOT}/configs" directory of Barakuda: ('${BARAKUDA_ROOT}/configs/config_<MY_CONF>.sh')

Or, in case you have no write access into ${BARAKUDA_ROOT}/ and call the Barakuda suite of scripts from another location, hereafter "work directory", you can use a "config_<MY_CONF>.sh" present in the "work directory".

Note: if a given "config_<MY_CONF>.sh" exists both in "${BARAKUDA_ROOT}/configs" and the "work directory", Barakuda will always refer to "config_<MY_CONF>.sh" present in the "work directory".

IMPORTANT: Always refer to the most relevant '${BARAKUDA_ROOT}/configs/config_*_TEMPLATE.sh' file to design or re-adjust yours! These are symbolic links pointing to the last officially supported and most up-to-date config files. It should be sufficiently well commented for you to be able to adjust your own config file.

MY_CONF should always be of the form: "(e)ORCAL.sh" ( with NLEV being the number of z levels )

NEMO output files must be monthly averages and of the following form:

    <EXP 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 experiment started in 1990 is the 6th year so files for 1995 are saved into sub-directory (of NEMO_OUT_STRCT) "006" (set 'ece_exp' to 1 or 2 then).

If you want to perform the "climatology" plots (see section IV) you will need monthly "observed" 2D and 3D of T and S (and sea-ice fraction) data interpolated on the ORCA grid you are using. Usually you should already have them since they are needed to initialize your simulation (initial state for T & S). These are the following files in your Barakuda config file: F_T_OBS_3D_12, F_S_OBS_3D_12, F_SST_OBS_12, F_ICE_OBS_12.

Alternatively, you can download these climatologies for the ORCA1.L75 and ORCA025.L75 configurations here: http://misu228.misu.su.se/barakuda/input_barakuda/ORCA1.L75_barakuda.tar http://misu228.misu.su.se/barakuda/input_barakuda/ORCA025.L75_barakuda.tar

The "CONF_INI_DIR" variable in your config file should point to the location of the directory you created by untaring one of these tar archives.

III) Create diagnostics

Launch "barakuda.sh"

   ./barakuda.sh -C <MY_CONF> -R <EXP>

   (ex: ./barakuda.sh -C ORCA1_L75_v36_triolith -R SL36C00)

Use the -h switch to see available options.

IV) Create figures and browsable HTML page

• 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 <EXP> -e

    (ex: ./barakuda.sh -C ORCA1_L75_v36_triolith -R SL36C00 -e)

To generate time-series + 2D climatology plots use the "-E" switch, provided you have built the monthly/annual climatology (based on N years of your simulation) out of your experiment with the "build_clim.sh" script (see next bullet point):

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

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

  1. create the climatology with the "build_clim.sh" script:

     ./build_clim.sh -C <MY_CONF> -R -i <first_year> -e <last_year>

  Use the -h switch to see available options.

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

• To compare time-series between at least 2 (already diagnosed) experiments:

     ./compare_time-series.sh -C <MY_CONF> -R <EXP1>,<EXP2>,...,<EXPn>
  
     (ex: ./compare_time-series.sh -C ORCA1_L75_v36_triolith -R SL36C00,SL36EIE )