[[PageOutline]] Last edited '''[[LastModified()]]'''

'''Author''' : Casimir de Lavergne, Gurvan Madec

'''ticket''' : #1674

'''Branch''' : [https://forge.ipsl.jussieu.fr/nemo/browser/branches/2015/dev_r6287_ZDFTMX_new 2015/dev_r6287_ZDFTMX_new]

'''Reviewer''' : Christian Ethé

----
= Description =
Introduce in the v3.6_STABLE a non intrusive version of a new parameterization of internal wave-driven mixing.

The original parameterization that has been developed is implemented with the two following undesirable features for the v3.6_STABLE:[[BR]] (1) a module replacing the existing zdftmx.F90 module (impossible to use the old param); [[BR]] (2) avt and avs arrays always defined (suppression of zdfddm_substitute.h90 which introduces changes in ~25 modules)

Here, the parameterization is introduced as an additional option, making both the current parameterization and the new one available. Note that the new one will only be available if double diffusive mixing is activated (key_zdfddm defined). Therefore changes to the code are restricted to the namelist and the zdftmx.F90 module. The ZDF chapter of the Documentation is also updated.

----
= Strategy =
In Changeset [https://forge.ipsl.jussieu.fr/nemo/changeset/6294 6294] the following changes have been made :

(1) in zdftmx:  introduce in zdftmx.F90 a new CPP key : key_zdftmx_new so that: [[BR]]

{{{
MODULE zdftmx
...
#if defined key_zdftmx   ||   defined key_esopa
   !!----------------------------------------------------------------------
   !!   'key_zdftmx'                                  Tidal vertical mixing   <<<==OLD version
   !!----------------------------------------------------------------------
   !!   zdf_tmx      : global     momentum & tracer Kz with tidal induced Kz
   !!   tmx_itf      : Indonesian momentum & tracer Kz with tidal induced Kz 
   !!   zdf_tmx_init : initialisation of tidal induced Kz
   !!----------------------------------------------------------------------
   ...
   LOGICAL, PUBLIC, PARAMETER ::   lk_zdftmx = .TRUE.    !: tidal mixing flag     <<=== same flag
   ...
#elif defined key_zdftmx_new
   !!----------------------------------------------------------------------
   !!   'key_zdftmx_new'                          New Tidal vertical mixing   <<<==NEW version
   !!----------------------------------------------------------------------
   !!   zdf_tmx      : global     momentum & tracer Kz with tidal induced Kz
   !!   zdf_tmx_init : initialisation of tidal induced Kz
   !!----------------------------------------------------------------------
   ...
   LOGICAL, PUBLIC, PARAMETER ::   lk_zdftmx = .TRUE.    !: tidal mixing flag     <<=== same flag
   ...
#else
   !!----------------------------------------------------------------------
   !!   Default option          Dummy module                NO Tidal MiXing
   !!----------------------------------------------------------------------
   ...
#endif
}}}
(2) add in the new param a test to stop the code if key_zdfddm not defined.

(3) Introduce minimal changes to zdfddm.F90 and zdftke.F90: these changes are surrounded by #ifdef key_zdftmx_new and #endif (hence no changes when the key is not defined).

(4) Introduce in namelist_ref a new namelist called “namzdf_tmx_new” which is used if key_zdftmx_new and key_zdfddm are defined.

(5) Update field_def.xml with the new possible output.

(6) Add in the input .tar file for both ORCA2 and ORCA1 the input files of the new parameterization.

The rationale behind changes in zdftke.F90 and zdffdm.F90 mentioned in (3) is the following:

 * zdftke.F90:

The new parameterization replaces BOTH the former tidal mixing scheme and the so-called background diffusion. Up to now, the background diffusion was set by the namelist parameters rn_avm0 and rn_avt0, which define floors on diffusivity and viscosity, and the parameter rn_emin, which defines the floor on the turbulent kinetic energy (TKE, m^2/s^2). With the new mixing scheme activated, floors on diffusivity and viscosity are set to molecular levels (1.4e-7 m^2/s and 1.4e-6 m^2/s, respectively) within the new zdftmx.F90 module, and a very low floor on TKE (1e-10 m^2/s^2) is enforced in the zdf_tke_init subroutine of zdftke.F90.

However, the low floors on viscosity (avm) and TKE could cause some numerical instability in the computation of the TKE, so that we imposed a floor of 1e-5 m^2/s for the vertical diffusion of TKE in the tke_tke subroutine.^

 * zdfddm.F90:

The zdfddm module used to set avs to avt plus an additional double diffusive component. Because the new zdftmx parameterization, which is called before zdfddm, can give different values to avt and avs (if default namelist parameter nn_tsdiff=T is used), zdfddm should update avs as avs plus the double diffusive component when the new scheme is chosen.

= Code Review : =
(1) The code  is OK, not intrusive and do not change the results when key_zdftmx_new  is switched off

(2) SETTE tests are OK with each of the 2 parameterization  ( key_zdftmx or key_zdftmx_new )

(3) The new parameterization gives the results that have been expected in a longer run ( ORCA2 )