.. _doc.coupling.oasis.intro:

**The coupler : OASIS Library** 
===============================

**General presentation**
------------------------

The OASIS coupler, currently developed in the framework of the EU FP7 IS-ENES2 project, is a software allowing synchronized exchanges of coupling information between numerical codes representing different components of the climate system. Current OASIS developers are CERFACS (Toulouse, France) and Centre National de la Recherche Scientifique (Paris, France).

We invite the user or developer to visit the official website of the `Cerfacs`_ and `Oasis`_ Coupler website.

The MARS team thanks the Cerfacs (Anthony Thévenin) who has instrumented Oasis into MARS code in the framework of the Prévimer project. MARS has been initially coupled with WRF atmospheric code to benefit the OASIS implementation in WRF previously done by Sébastien Masson (IPSL), Guillaume Samson (Legos) and Eric Maisonnave (Cerfacs). Many thanks to our collegues who supplied us with their WRF-OASIS version.


**Downloading** 
----------------

The code has been downloaded from the official repository : https://verc.enes.org/oasis/news/oasis3-mct_2.0-official-release. The current version we use at Ifremer is OASIS3-MCT_2.0 official release.

.. svn checkout http://oasis3mct.cerfacs.fr/svn/branches/OASIS3-MCT_2.0_branch/oasis3-mct

**Compilation** 
----------------

Please follow the OASIS manual, the compilation is very well documented. More generally, the user will refer to the `oasismanual`_ for any question about the coupling. This page and the followings just give an overview of the use of MARS coupled with WW3 (waves) or Méso-NH (atmosphere) codes

Under Caparmor,

*MPI*
^^^^^

::

   module purge ; module load intel-comp/14.0.0 intel-mpi/4.0.0.028
   cd /home3/caparmor/marsdev/OASIS/oasis3-mct/util/make_dir
   modify make.inc to use make.caparmor
   cp make.caparmor_mpi4.0 make.caparmor  (which uses previmer netcdf4 libraries)
   make realclean -f TopMakefileOasis3
   make -f TopMakefileOasis3 | tee out_make_mpi.txt

The static OASIS libraries (libmct.a  libmpeu.a  libpsmile.MPI1.a  libscrip.a) that need to be linked to the models are available in the /home3/caparmor/marsdev/OASIS/oasis3-mct/compile_oa3-mct_mpi4.0/lib directory.


*MPT*
^^^^^

::

   module purge ; module load NETCDF/4.3.3.1-mpt-intel2016
   # directory containing the compiled library
   setenv OASISDIR /home.../OASIS/oasis3-mct2.0-netcdf-4.3.3.1-mpt-intel2016/
   # go to the reference directory
   cd /home..../OASIS/oasis3-mct2.0/util/make_dir
   # adapt the link for OASIS directories in the files: make.inc and make.mpt
   cp make.mpt make.datarmor  # make sure that it links the right oasis path
   make.inc  # make sure that it links the generic make.datarmor
   # To clean the OASIS directory
   make realclean -f TopMakefileOasis3 > $OASISDIR/output/clean.out
   # To compile the OASIS library
   make -f TopMakefileOasis3 | tee out_make_mpt.txt

The static OASIS libraries (libmct.a  libmpeu.a  libpsmile.MPI1.a  libscrip.a) that need to be linked to the models are available in the /home3/caparmor/marsdev/OASIS/oasis3-mct/compile_oa3-mct_mpt2.06/lib directory.

.. _Cerfacs: http://www.cerfacs.fr/
.. _Oasis: https://verc.enes.org/oasis/
.. _oasismanual: http://pantar.cerfacs.fr/globc/publication/technicalreport/2013/oasis3mct_UserGuide.pdf

*Test using OASIS tutorial*
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To check if OASIS run, follow these following steps
   ::

      1. compile model1.F90_TP and model2.F90_TP (gmake clean; gmake model1 model2 | tee make_toys.txt)

      #. cp data_oasis3/namcouple_TP data_oasis3/namcouple

      #. modify the run_tutorial by specifying::

         * the Architecture (arch=caparmor)
         * the number of cpus (nproc_exe1 and nproc_exe2)
         * the mpirun executable (MPIRUN)
         * and the run directory (rundir)

      #. Execute run_tutorial

Results are under your rundir directory. You should get these kind of files::

   run_tutorial.caparmor
   nout.000000
   grids.nc
   areas.nc
   masks.nc
   rmp_lmdz_to_torc_BILINEAR.nc
   FRECVOCN_model1_03.nc
   FRECVATM_model2_01.nc
   fdatm.nc
   model2.out_105
   model2.out_104
   FSENDATM_model2_02.nc
   model2.out_103
   FSENDOCN_model1_02.nc
   fdocn.nc
   FSENDOCN_model1_01.nc
   model1.out_102
   model1.out_101
   f2avg.nc
   model1.out_100
   debug.02.000002
   debug.02.000001
   debug.02.000000
   debug.01.000002
   debug.01.000001
   debug.01.000000
   out