.. _doc.coupling.marsww3:

**Dynamical coupling : MARS-WW3** 
=================================

The MARS-WW3 coupling has been instrumented by Anthony Thévenin (Cerfacs) and Valérie Garnier (Ifremer) thanks to the precious help of Fabrice Ardhuin and Mickael Accensi (Ifremer). The integration of the OASIS coupler benefited from the work of Anne-Claire Bennis who has initially coupled MARS and WW3 codes with the PALM coupler.

The following technical report explains the OASIS instrumentation in MARS and WW3. Lien DOC AnthonyXXXX


**Version of the codes**
------------------------

To couple MARS and WW3 with OASIS, use the following or newer versions:

   * MARS : V10.5 or r1771 for developpers only
   * WW3 : The official WW3 release XXX or r1083 from IFREMER SVN repository


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


*WW3* : add the following switches in switch.OASIS: ``COU OASIS OASOCM``

*MARS* : add the following CPP keys: ``-Dkey_oasis -Dkey_oasis_mars_ww3``

Compile each code in its own environment. Be careful, MARS, OASIS and WW3 must use (and must be compiled with) the same libraries.

.. note::
   You must compile WW3 and MARS in parallel (MPI or MPT)


**Exchanged variables**
-----------------------

18 variables are exchanged between MARS and WW3::

   +====================+===================================+================+===================+
   | Variable Name (WW3)| Signification                     |    MARS name   |     WW3 name      |
   +====================+===================================+================+===================+
   | WLV     (MARS var) | Sea surface Height (m)            |   MARS_SSH     |    WW3__SSH       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | CX      (MARS var) | Oceanic current u-component (m/s) |   MARS__UZ     |    WW3___UZ       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | CY      (MARS var) | Oceanic current v-component (m/s) |   MARS__VZ     |    WW3___VZ       |
   +====================+===================================+================+===================+
   | T0M1     (WW3 var) | Mean wave period (s)              |   MARST0M1     |    WW3_T0M1       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | HS       (WW3 var) | Wave height (hs in m)             |   MARS__HS     |    WW3___HS       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | THM      (WW3 var) | Mean wave direction (degrees)     |   MARS_DIR     |    WW3__DIR       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | BHD      (WW3 var) | Wave-induced Bernoulli head       |   MARS_BHD     |    WW3__BHD       |
   |                    | pressure (N.m-1) (J term)         |                |                   |
   +--------------------+-----------------------------------+----------------+-------------------+
   | TAUOX    (WW3 var) | Wave-ocean momentum flux (m2.s-2) |   MARSTWOX     |    WW3_TWOX       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | TAUOY    (WW3 var) | Wave-ocean momentum flux (m2.s-2) |   MARSTWOY     |    WW3_TWOY       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | UBA      (WW3 var) | Bottom rms velocity (m/s)         |   MARS_UBR     |    WW3__UBR       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | PHIOC    (WW3 var) | Wave-to-ocean TKE flux (W.m-2)    |   MARS_FOC     |    WW3__FOC       |
   +--------------------+-----------------------------------+----------------+-------------------+
   | TAUWIX   (WW3 var) | Net wave-supported stress (m2.s-2)|   MARSTAWX     |   WW3_TAWX        |
   +--------------------+-----------------------------------+----------------+-------------------+
   | TAUWIY   (WW3 var) | Net wave-supported stress (m2.s-2)|   MARSTAWY     |   WW3_TAWY        |
   +--------------------+-----------------------------------+----------------+-------------------+
   | WLM      (WW3 var) | Mean wave length (m)              |   MARS__LM     |   WW3___LM        |
   +====================+===================================+================+===================+


For the wave variables, the _LM, _TAWY extensions correspond to the names introduced
in ww3_shel.inp to estimate and save the variables in WW3.


**Coupling namelist**
---------------------

   An exemple of namcouple file is available under `namcouple <FILES/DOWNLOAD/namcouple>`_

*Main rules*
^^^^^^^^^^^^

*To estimate the gridding weigths at the begining of the run (spatial interpolation)*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*To use previously estimated gridding weigths (spatial interpolation)*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Run MARS and WW3 together**
-----------------------------

* In a **data** directory, save the following files::

   bathymetric MARS and WW3 files,
   restart files,
   job_mars_ww3_coupling.pbs file,
   namcouple file

The job_mars_ww3_coupling.pbs file specifies the libraries, the run optimization and the number of cpu allocated to each of the codes:

.. literalinclude:: FILES/COUPLING/job_mars_ww3_coupling.pbs