Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/INSTALL.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/INSTALL.rst	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/INSTALL.rst	(revision 10321)
@@ -1,38 +1,64 @@
-Install the modelling framework (NEMO and XIOS)
+*********************
+Install the framework
+*********************
 
-Last edition: 2018-02-14 21:32 CET by nicolasmartin
+.. contents::
+	:local:
+      
+Dependencies
+============
 
-    Extract the NEMO code
-        Description of NEMOGCM directory tree
-    Extract and install XIOS
-    Setup your architecture configuration file
-    Compile and create NEMO executable
-        More options
-        Default behaviour
-        Tools used during the process
-        Examples
-    Running the model
-    Viewing and changing list of active CPP keys
+| The NEMO source code is written in Fortran 95 and part of its dependencies are already included (``./ext``):
+  AGRIF preprocessing program "conv", FCM build system and IOIPSL library for outputs.
+| And some Perl 5, Fortran compiler (ifort, gfortran, pgfortran, ...), MPI library (Open MPI or MPICH)
 
-Extract the NEMO code
+But The following dependencies should be from the official repositories of your Linux distribution but
+you will probably have to compile them from source for enabling parallel I/O support.
 
-Using your account registered here ('my_login' with password)
+- `HDF5`_   (C library)
+- `NetCDF`_ (C and Fortran libraries)
+
+Extract the source code
+=======================
+
+Download the source code
+------------------------
 
 .. code:: console
-svn --username 'mylogin' co http://forge.ipsl.jussieu.fr/nemo/svn/branches/2015/nemo_v3_6_STABLE/NEMOGCM
 
-Description of NEMOGCM directory tree
+	$ svn co http://forge.ipsl.jussieu.fr/nemo/svn/NEMO/releases/release-4.0
 
-The image below shows the directory tree:
+Description of directory tree
+-----------------------------
 
-simple table:
-    ARCH    Compilation option files, with format arch_compiler.fcm, the compiler name has to be provided with –m option
-    CONFIG	All configurations and a cpp.fcm file containing the list of CPP keys to each configuration
-    EXTERNAL    Package to implement an embedded model (AGRIF)
-    NEMO    FORTRAN source codes in several sub-directories
-    SETTE    Package to make tests to ensure the reproducibility and restartability of the code after changes
-    TOOLS    Useful softwares to different utilities
++-----------+------------------------------------------------------------+
+| Folder    | Purpose                                                    |
++===========+============================================================+
+| ``arch``  | Settings (per architecture-compiler pair)                  |
++-----------+------------------------------------------------------------+
+| ``cfgs``  | :doc:`Reference configurations <configurations>`           |
++-----------+------------------------------------------------------------+
+| ``doc``   | - ``latex``: reference manuals for |OPA|, |SI3| & |TOP|    |
+|           | - ``namelists``: k start guide                             |
+|           | - ``rst``:   quick start guide                             |
++-----------+------------------------------------------------------------+
+| ``ext``   | Dependencies included (AGRIF, FCM & IOIPSL)                |
++-----------+------------------------------------------------------------+
+| ``mk``    | Building  routines                                         |
++-----------+------------------------------------------------------------+
+| ``src``   | Modelling routines                                         |
+|           |                                                            |
+|           | - ``ICE``: |SI3| for sea ice                               |
+|           | - ``NST``: AGRIF for embedded zooms                        |
+|           | - ``OCE``: |OPA| for ocean dynamics                        |
+|           | - ``MBG``: |TOP| for tracers                               |
++-----------+------------------------------------------------------------+
+| ``tests`` | :doc:`Test cases <test_cases>` (unsupported)               |
++-----------+------------------------------------------------------------+
+| ``tools`` | :doc:`Utilities <tools>` to [pre|post]process data         |
++-----------+------------------------------------------------------------+
 
 Extract and install XIOS
+========================
 
 Diagnostic outputs from NEMO are handled by the third party XIOS library.
@@ -42,5 +68,5 @@
 
 When you compile NEMO you will need to specify the following CPP keys:
-
+  
     key_iomput
     key_mpp_mpi (if you want to run with multiple processes and/or use "detached mode" for the IOs system XIOS)
@@ -48,4 +74,5 @@
 
 Setup your architecture configuration file
+==========================================
 
 All compiler options in NEMO are controlled using files in NEMOGCM/ARCH/arch-'my_arch'.fcm where 'my_arch' is the name of the computing architecture.
@@ -58,59 +85,42 @@
 
 Compile and create NEMO executable
+==================================
 
 The main script to compile and create executable is called makenemo and located in the CONFIG directory, it is used to identify the routines you need from the source code, to build the makefile and run it.
 As an example, compile GYRE with 'my_arch' to create a 'MY_GYRE' configuration:
 
-   cd NEMOGCM/CONFIG; ./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
+.. code-block:: sh
+
+	./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
 
 The image below shows the structure and some content of "MY_CONFIG" directory from the launching of the configuration creation (directories and fundamental files created by makenemo).
 
-	
++------------+----------------------------------------------------+
+| Folder     | Purpose                                            |
++============+====================================================+
+| ``BLD``    |                                                    |
++------------+----------------------------------------------------+
+| ``EXP00``  |                                                    |
++------------+----------------------------------------------------+
+| ``EXPREF`` |                                                    |
++------------+----------------------------------------------------+
+| ``MY_SRC`` |                                                    |
++------------+----------------------------------------------------+
+| ``WORK``   |                                                    |
++------------+----------------------------------------------------+
 
-    WORK
-
-	
-
-    Folder with the symbolic links to all unpreprocessed routines considered in the configuration
-
-    BLD
-
-	
-
-    Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
-
-    EXP00
-
-	
-
-    Computation folder for running the model (namelists, xml, executables and inputs-outputs)
-
-    MY_SRC
-
-	
-
-    Folder intended to contain your customized routines (modified from initial ones or new entire routines)
+Folder with the symbolic links to all unpreprocessed routines considered in the configuration
+Compilation folder (executables, headers files, libraries, preprocessed routines, flags, …)
+Computation folder for running the model (namelists, xml, executables and inputs-outputs)
+Folder intended to contain your customised routines (modified from initial ones or new entire routines)
 
 After successful execution of makenemo command, the executable called opa is created in the EXP00 directory (in the example above, the executable is created in CONFIG/MY_GYRE/EXP00).
 More options
 
-        echo "Usage      : "${b_n} \
-            " [-h] [-n name] [-m arch] [-d "dir1 dir2"] [-r conf] [-u conf] [-s Path] [-e Path] [-j No] [-v No] [-k 0/1]";
-        echo " -h               : help";
-        echo " -h institute : specific help for consortium members";
-        echo " -n name      : config name, [-n help] to list existing configurations";
-        echo " -m arch      : choose compiler, [-m help] to list existing compilers";
-        echo " -d dir       : choose NEMO sub-directories";
-        echo " -r conf      : choose reference configuration";
-        echo " -u conf      : choose an unsupported (external) configuration";
-        echo " -s Path      : choose alternative location for NEMO main directory";
-        echo " -e Path      : choose alternative location for MY_SRC directory";
-        echo " -j No        : number of processes used to compile (0=nocompilation)";
-        echo " -v No        : set verbosity level for compilation [0-3]";
-        echo " -k 0/1       : used cpp keys check (default = 1 -> check activated)";
-        echo " -t dir       : temporary directory for compilation"
-        echo "";
+..
+	.. literalinclude::
 
 Default behaviour
+-----------------
 
     At the first use, you need the -m option to specify the architecture configuration file (compiler and its options, routines and libraries to include), then for next compilation, it is assumed you will be using the same compiler.
@@ -118,4 +128,5 @@
 
 Tools used during the process
+-----------------------------
 
     functions.sh : bash functions used by makenemo, for instance to create the WORK directory
@@ -124,4 +135,5 @@
 
 Examples
+--------
 
         echo "Example to install a new configuration MY_CONFIG";
@@ -149,7 +161,8 @@
 
 Running the model
+=================
 
-Once makenemo has run successfully, the opa executable is available in CONFIG/"MY_CONFIG"/EXP00
-For the reference configurations, the EXP00 folder also contains the initial input files (namelists, *xml files for the IOs…). If the configuration also needs NetCDF input files, this should be downloaded here from the corresponding tar file, see Users/Reference Configurations
+Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00``
+For the reference configurations, the EXP00 folder also contains the initial input files (namelists, \*xml files for the IOs…). If the configuration also needs NetCDF input files, this should be downloaded here from the corresponding tar file, see Users/Reference Configurations
 
    cd 'MY_CONFIG'/EXP00
@@ -157,8 +170,12 @@
 
 Viewing and changing list of active CPP keys
+============================================
 
-For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in
+For a given configuration (here called MY_CONFIG), the list of active CPP keys can be found in::
 
-   NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
+	NEMOGCM/CONFIG/'MYCONFIG'/cpp_'MY_CONFIG'.fcm
 
 This text file can be edited to change the list of active CPP keys. Once changed, one needs to recompile opa executable using makenemo command in order for this change to be taken in account.
+
+.. _HDF5:   http://www.hdfgroup.org/downloads/hdf5
+.. _NetCDF: http://www.unidata.ucar.edu/downloads/netcdf
Index: MO/branches/UKMO/NEMO4_beta_mirror/README-setup-configs
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/README-setup-configs	(revision 10320)
+++ 	(revision )
@@ -1,53 +1,0 @@
-==============================================================
-== HOW TO set up user’s configuration in NEMO version 4.0 : ==
-==============================================================
-This document describes how a configuration is set up in NEMO.
-
-In NEMO 4.0 two types of configurations can be build: global/regional and idealized.
-
-- create ./cfgs/your_config
-- case 1: regional or global 
-    => ln_read_cfg = .true. in ./cfgs/your_config/EXP00/namelist_cfg (i.e. read domain_cfg.nc)
-- case 2: idealized 
-    =>in ./cfgs/your_config/EXP00/namelist_cfg :
-      ln_read_cfg = .false. (need to define usrdef_hgr.F90 and usrdef_zgr.F90) 
-      ln_usr = .true.       (need to define usrdef_sbc.F90)    
-    => copy ./src/OCE/USR in ./cfgs/your_config/MY_SRC routines nedeed to set up domain, forcing fields and initial state
-    
-  Routines in NEMOGCM/NEMO/OCE/USR define analytically the domain, the initial state and the surface boundary conditions for the reference configuration GYRE.
-	  •	usrdef_hgr.F90 and usrdef_zgr.F90 : define horizontal and vertical grid
-	  •	usrdef_sbc.F90    : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
-	  •	usrdef_istate.F90 : defines initialization of the dynamics and tracers
-	  •	usrdef_fmask.F90  : used just in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits 
-	  •	usrdef_closea.F90 : used just in ORCA CONFIGURATIONS for specific treatments associated with closed seas
-	  •	usrdef_nam.F90    : set the domain characteristics of a user configuration
-
-  Other analytical examples are given in ./tests.
-
-===========================================
-== The domain_cfg.nc file must contain : ==
-===========================================
-   int ORCA  , ORCA_index            : configuration name, configuration resolution
-   int jpiglo, jpjglo , jpkglo       : global domain sizes 
-   int jperio                        : lateral global domain b.c. 
-   int ln_zco, ln_zps, ln_sco        : flags for z-coordinate, z-coordinate with partial steps and s-coordinate 
-   int ln_isfcav                     : flag  for ice shelf cavities 
-   double glamt, glamu, glamv, glamf : geographic position 
-   double gphit, gphiu, gphiv, gphif : geographic position
-   double iff, ff_f, ff_t            : Coriolis parameter (if not on the sphere)
-   double e1t, e1u, e1v, e1f         : horizontal scale factors
-   double e2t, e2u, e2v, e2f         : horizontal scale factors
-   double ie1e2u_v, e1e2u, e1e2v     : U and V surfaces (if grid size reduction in some straits)
-   double e3t_1d, e3w_1d             : reference vertical scale factors at T and W points
-   double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 : vertical scale factors 3D coordinate at T,U,V,F and W points
-   double e3uw_0,e3vw_0              : vertical scale factors 3D coordinate at UW and VW points
-   int bottom_level, top_level       : last wet T-points, 1st wet T-points (for ice shelf cavities)
-
-=======================================
-= HOW TO CREATE domain_cfg.nc file : ==
-=======================================
-Two options are possible :
-
- - users can create with his own tool the domain_cfg.nc with all mandatory fields.  
-
- - tool is available in ./tools/DOMAINcfg based on NEMO 3.6 version. See ./tools/DOMAINcfg/README.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/README.rst	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/README.rst	(revision 10321)
@@ -1,103 +1,89 @@
-.. role:: rstblue
-.. role:: rstgrey
-.. role:: rstgreen
+:Authors: NEMO System Team
+:Release: |release|
+:Date:    |today|
 
-================
-NEMO Ocean Model
-================
+`NEMO`_ for *Nucleus for European Modelling of the Ocean* is a state-of-the-art modelling framework for
+research activities and forecasting services in ocean and climate sciences.
 
-NEMO_ (Nucleus for European Modelling of the Ocean) is a state-of-the-art modelling framework of 
-ocean related engines for oceanographic research, operational oceanography, seasonal forecast and 
-[paleo]climate studies.
+.. contents::
+	:local:
+
+Overview
+========
 
 The NEMO ocean model has 3 major components:
 
-- :rstblue:`OPA` is fundamental to all users by modelling the ocean [thermo]dynamics and 
-  solving the primitive equations;
-- :rstgrey:`LIM` for sea-ice simulates ice [thermo]dynamics, brine inclusions and 
-  subgrid-scale thickness variations;
-- :rstgreen:`TOP-PISCES` models biogeochemistry with TOP for 
-  the on/offline oceanic tracers transport and PISCES for the biogeochemical processes.
+- |OPA| models the ocean [thermo]dynamics and solves the primitive equations
+  (``./src/OCE``) :cite:`NEMO_manual`;
+- |SI3| simulates ice [thermo]dynamics, brine inclusions and subgrid-scale thickness variations
+  (``./src/ICE``) :cite:`SI3_manual`;
+- |TOP| models the [on|off]line oceanic tracers transport and the biogeochemical processes
+  (``./src/MBG``) :cite:`TOP_manual`.
 
-These physical engines are described in their respective `reference publications`_.
+These physical core engines are described in their respective <reference publications> that must be cited for
+any work related to their use.
 
-They are complemented by a 2-way nesting software (AGRIF_) and 
-a versatile data assimilation interface with 3 different modules
-(linear-tangent TAM, observational operators OBS, and increment ASM).
+Applications and capabilities
+=============================
 
-------------
-Applications
-------------
+Not only does the NEMO framework model the ocean circulation,
+it offers various features to enable
 
-| Distributed under CeCILL license (GNU GPL compatible - see ``LICENSE``), 
-  the framework offers several builtins reference configurations to 
-  check your computing architecture and evaluate the model skills and performances (``./cfgs``).
-| The end user could also find some idealized test cases on the web to serve as examples and 
-  to study particular processes.
+- Create :doc:`embedded zooms <zooms>` seamlessly with 2-way nesting package `AGRIF`_.
+- :doc:`Low cost biogeochemistry <coarsening>` and :doc:`alternative model opportunity <tracers>`.
+- Versatile :doc:`assimilation <assimilation>`.
+- :doc:`Output diagnostics <diagnostics>` with `XIOS`_ server.
+- :doc:`Coupling <coupling>` via `OASIS`_ for Earth system modelling.
 
-A set of tools is also provided to setup your own configuration and 
-[pre|post]process your data (``./tools``).
+| Several :doc:`builtins configurations <configurations>` are provided to assess the skills and performances of
+	the model which can be used as templates for :doc:`setting up a new configuration <setup>` (``./cfgs``).
+| The end user could also find some :doc:`idealised test cases <test_cases>` online to serve as templates and
+	to study particular processes (``./tests``).
 
--------
-Options
--------
+A set of :doc:`utilities <tools>` is also provided to [pre|post]process your data (``./tools``).
 
-For writing diagnostics in a efficient way, NEMO make use of XIOS_ server which 
-controlled the outputs using XML input file.
+Literature
+==========
 
-To enable Earth system modelling, NEMO can be interfaced via 
-OASIS_ coupleur to external components such as atmospheric models or 
-alternative models of sea-ice or biogeochemistry.
+:doc:`install`
 
--------------
-Documentation
--------------
+The reference documentation is archived online
 
-The NEMO reference manual can be generated from the LaTeX source code (``./doc``), 
-either in PDF or in HTML format, but it mights require some additionnal installations.
++-------+-------------------+----------------+
+|       | Reference manual  | |NEMO manual|_ |
+| |OPA| +-------------------+----------------+
+|       | Quick start guide | |NEMO guide|_  |
++-------+-------------------+----------------+
+| |SI3|                     | |SI3 manual|_  |
++---------------------------+----------------+
+| |TOP|                     | |TOP manual|_  |
++---------------------------+----------------+
 
-In any case, both formats are available online on the `NEMO website`__.
+.. |NEMO manual| image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |NEMO guide|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |SI3 manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |TOP manual|  image:: http://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
 
----------------------
+| Reference manuals and quick start guide can be build from source and exported to HTML or PDF (``./doc``).
+| In any case, one can find them online:
+
+Since 2014 the project has a `Special Issue <http://www.geosci-model-dev.net/special_issue40.html>`_ in
+the open-access journal Geoscientific Model Development (GMD) from the European Geosciences Union (EGU).
+The main scope is to collect relevant manuscripts covering various topics and to provide a single portal to
+assess the model potential and evolution.
+
+Used by a wide audience, numerous :website:`associated projects <projects>` have been carried out and
+extensive :website:`bibliography <bibliography/publications>` published.
+
 Community development
----------------------
+=====================
 
-| The NEMO Consortium gathering 6 European institutes organises the sustainable development in order to 
-  keep a reliable evolving system since 2008.
-| It defined the multiyear development strategy which is implemented by the NEMO System Team.
+| The NEMO Consortium pulling together 5 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_)
+	plans the sustainable development in order to keep a reliable evolving framework since 2008.
+| It defines the |NEMO strategy|_ which is implemented by the System Team on
+	a yearly basis in	order to release a new version almost every four years.
 
---------
-Acronyms
---------
+.. |NEMO strategy| replace:: multi-year development strategy
 
-AGRIF
- Adaptive Grid Refinement In Fortran
-
-LIM
- Louvain-la-Neuve Ice Model
-
-OPA
- "Océan PArallélisé" (french)
-
-PISCES
- Pelagic Interactions Scheme for Carbon and Ecosystem Studies
-
-TAM
- Tangent Adjoint Model
-
-TOP
- Tracers in Ocean Paradigm
-
-XIOS
- XML Input Output Server
-
-----
-
-.. _AGRIF:                  http://agrif.imag.fr
-.. _Forge:                  http://forge.ipsl.jussieu.fr/nemo
-.. _NEMO:                   http://www.nemo-ocean.eu
-.. _OASIS:                  http://verc.enes.org/oasis
-.. _reference publications: http://www.nemo-ocean.eu/bibliography/documentation
-.. _XIOS:                   http://forge.ipsl.jussieu.fr/ioserver
-
-.. __:  NEMO_
+When the need arises, :forge:`working groups <wiki/WorkingGroups>` are created or resumed to
+gather the community expertise for advising on the development activities.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/REFERENCES.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/REFERENCES.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/REFERENCES.bib	(revision 10321)
@@ -0,0 +1,68 @@
+@manual{NEMO_manual,
+   title={NEMO ocean engine},
+   author={Madec Gurvan and NEMO System Team},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={27},
+   publisher={Zenodo},
+   abstract={The ocean engine of NEMO is a primitive equation model adapted to regional and
+   global ocean circulation problems.
+   It is intended to be a flexible tool for studying the ocean and its interactions with
+   the others components of the earth climate system over a wide range of space and time scales.},
+   doi={10.5281/zenodo.1464816},
+   edition={},
+   year={}
+}
+
+@manual{SI3_manual,
+   title={SI³ – Sea Ice modelling Integrated Initiative – The NEMO Sea Ice engine},
+   author={NEMO Sea Ice Working Group},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={31},
+   publisher={Zenodo},
+   abstract={SI³ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO
+   (Nucleus for European Modelling of the Ocean).
+   It is adapted to regional and global sea ice and climate problems.
+   It is intended to be a flexible tool for studying sea ice and its interactions with
+   the other components of the Earth System over a wide range of space and time scales.
+   SI3 is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework,
+   combining the ice thickness distribution framework, the conservation of horizontal momentum,
+   an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics.
+   Prognostic variables are the two-dimensional horizontal velocity field, ice volume, area, enthalpy,
+   salt content, snow volume and enthalpy.
+   In the horizontal direction, the model uses a curvilinear orthogonal grid.
+   In the vertical direction, the model uses equally-spaced layers.
+   In thickness space, the model uses thickness categories with prescribed boundaries.
+   Various physical and numerical choices are available to describe sea ice physics.
+   SI3 is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with
+   several atmospheric general circulation models.
+   It also supports two-way grid embedding via the AGRIF software.},
+   doi={10.5281/zenodo.1471689},
+   edition={},
+   year={}
+}
+
+@manual{TOP_manual,
+   title={TOP – Tracers in Ocean Paradigm – The NEMO Tracers engine},
+   author={NEMO TOP Working Group},
+   organization={NEMO Consortium},
+   journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)},
+   number={28},
+   publisher={Zenodo},
+   abstract={},
+   doi={10.5281/zenodo.1471700},
+   edition={},
+   year={}
+}
+
+@Article{gmd-8-1245-2015,
+   author = {Vidard, A. and Bouttier, P.-A. and Vigilant, F.},
+   title = {{NEMOTAM}: {T}angent and {A}djoint {M}odels for the ocean modelling platform {NEMO}},
+   journal = {Geoscientific Model Development},
+   volume = {8},
+   year = {2015},
+   number = {4},
+   pages = {1245--1257},
+   doi = {10.5194/gmd-8-1245-2015}
+}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/RELEASE_NOTES.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/RELEASE_NOTES.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/RELEASE_NOTES.rst	(revision 10321)
@@ -0,0 +1,214 @@
+**********************
+What's new in NEMO 4.0
+**********************
+
+.. contents::
+	:local:
+      
+Original sea-ice component SI\ :sup:`3`\
+========================================
+
+| Meeting in 2017, the `sea ice working group`_ decided to gather sea ice developers and
+  scientific expertise within the NEMO community in order to build a unified model.
+  The replacement of LIM (Louvain-la-Neuve Ice Model) has required the backport of
+  the desired functionalities from each of CICE, GELATO and LIM into a common code in the NEMO framework.
+| This new model has been named SI\ :sup:`3`\ ("sea ice cubed") and
+  means "**Sea Ice modelling Integrated Initiative**".
+
+- Physics
+
+  * Landfast ice: simple grounding with a "release" stress (not fully operational)
+  * Lateral melting
+  * Melt ponds: constant or `Holland 2012`_ formulation (and soon topographic melt ponds)
+  * Ice-atm. drags from `Lupkes 2012`_ (depending on ice concentration) or `Lupkes 2014`_
+    (Depending on sea ice concentration and atm. stability)
+- Numerics
+
+  * Advection: Ultimate-Macho scheme
+  * Rheology: adaptive EVP (`Kimmritz 2016`_)
+  * Coupling interface: conductivity as surface forcing instead of heat fluxes (Met Office requirement)
+- Performance
+
+  * All thermodynamics in 1D
+  * Reduced mpp communications
+- Users & developers friendly
+
+  * Comprehensive set of outputs (universal units and understandable names + includes limp)
+  * New architecture and namelist
+  * All processes can be decoupled from each other (switch on/off)
+  * Ice categories bounds can be defined by the user or set automatically
+  * For open boundaries, the number of ice categories from the forcing model can be different
+    from the number of categories in the regional simulation
+  * Fully compatible with AGRIF
+
+First Test Cases
+================
+
+Define and install a separate repository for test cases to all easy contributions from the NEMO Users Community
+
+Core components
+===============
+
+Passive tracer TOP and biogeochemical PISCES components
+-------------------------------------------------------
+
+- The passive tracers transport component was redesigned toward a modular structure and
+  users can enable each module directly through logical flags in namelist_top (no more Fortran macros!).
+- TOP on-line user documentation is available on NEMO Trac platform (`TOP User Quick Guide`_)
+- TOP currently accounts for the following 5 modules:
+
+  * ``CFC`` contains inorganic carbon tracers (CFC11/CFC12/SF6)
+  * ``MY_TRC`` is a template for new modules (or external couplings)
+  * ``AGE`` deals with water age tracking
+  * ``C14`` as a radiocarbon passive tracer
+  * ``PISCES`` the companion ecosystem model
+- A generalized infrastructure was developed to handle the prescription of either surface, coastal, or
+  open boundaries conditions for each passive tracer.
+- PISCES model contains new developments and modifications:
+
+  * Particulate Organic Carbon (POC) component comes with a new liability scheme,
+    while the former Kriest parameterisation was superseded;
+  * A complex iron chemistry scheme is now available, with an improved description of ligands for
+    the marine iron cycle
+  * Carbonate chemistry is based on MOCSY 2.0 routines (see `Orr and Epitalon 2015`_),
+    by complying also with CMIP6 standards.
+  * Ecosystem components can be optionally modelled by means of explicit nutrient quotas (PISCES-QUOTA)
+
+AGRIF (embedded zooms)
+----------------------
+
+The NEMO 4.0 includes new capabilities, configurations and test cases with AGRIF:
+
+.. role:: underline
+	:class: underline
+
+:underline:`New capabilities from NEMO 3.6 to NEMO 4.0`
+
+AGRIF is continuously maintained so that it could be activated with all NEMO components (OPA, sea-ice, TOP).
+Depending on NEMO version, it is nevertheless not the case so that some options may not be compatible with
+the use of online grid refinement.
+Check out the table below to know the status according to the NEMO release you may use.
+
+:underline:`Status of available options with AGRIF (if not listed, option is compatible with AGRIF)`:
+
++--------------------------------------------------------+----------------+---------------------+
+|                                                        | NEMO 3.6       | NEMO 4.0            |
++========================================================+================+=====================+
+| LIM2                                                   | yes            | ``-``               |
++--------------------------------------------------------+----------------+---------------------+
+| LIM3/SI3                                               | no             | yes                 |
++--------------------------------------------------------+----------------+---------------------+
+| TOP                                                    | yes            | yes                 |
++--------------------------------------------------------+----------------+---------------------+
+| GLS vertical mixing                                    | no             | yes                 |
++--------------------------------------------------------+----------------+---------------------+
+| z*                                                     | no             | yes                 |
++--------------------------------------------------------+----------------+---------------------+
+| z~                                                     | no             | no                  |
++--------------------------------------------------------+----------------+---------------------+
+| Lagrangian icebergs                                    | no             | no                  |
++--------------------------------------------------------+----------------+---------------------+
+| East-west periodic and/or north fold bcs in zooms      | no             | no                  |
++--------------------------------------------------------+----------------+---------------------+
+| Online timing                                          | no             | no                  |
++--------------------------------------------------------+----------------+---------------------+
+| Stochastic parameterization                            | no             | no                  |
++--------------------------------------------------------+----------------+---------------------+
+| Vertical coordinate change in zooms (``key_vertical``) | no             | yes, but not tested |
++--------------------------------------------------------+----------------+---------------------+
+| Number of ghost cells                                  | 1 (hard coded) | 3 (parameter)       |
++--------------------------------------------------------+----------------+---------------------+
+
+[Important notice concerning the change of ghost cells number]
+
+The default number of ghost cells (i.e. the number of cells that serve as open boundary data provision) has been
+increased from 1 to 3 in NEMO 4.0.
+This allows to properly handle boundary conditions for numerical schemes that
+have a discretization order greater than 2.
+On the user point of view this does not change anything++ except in the definition of level 1 grids in
+the ``AGRIF_FixedGrids.in`` file.
+In order to retrieve exactly the position of a nested grid in NEMO 4.0 one has to shift indices by
+2 points to the south-west.
+Taking the ``ICEDYN`` example above for NEMO 4.0, the "old" NEMO 3.6 corresponding file would contain::
+
+	1
+	36 65 36 65 3 3 3
+	0
+
+++ Child grid output files are now greater by 4 points in each direction.
+
+- Now compatible with new sea ice component and z* coordinate
+- Extended ghost cells area to properly handle scheme with spatial order >2
+- Added vertical refinement (beta)
+- Nesting tools for setup now up to date and working
+
+Adding of 3 Reference Configurations
+------------------------------------
+
+- ``AGRIF_DEMO``: 2 interlocked zooms (1:4 & 1:3) in the Nordic Seas + 1 zoom (1:1) at the equator
+- ``ORCA2_OFF_TRC``: a benchmark simulation environment to deal with inert carbon tracers dynamics by
+  exploiting the offline coupling with NEMO.
+- ``SPITZ12``: regional configuration around the Svalbard archipelago.
+
+Misc. improvments
+=================
+
+Physics
+-------
+
+- Bulk formulae : move to aerobulk package (`Brodeau 2017`_), i.e. NCAR, COARE and ECMWF bulk
+  (remove Clio and MFS bulk)
+- Fix for tracer conservation with split explicit free surface
+- Wetting and drying
+- iso-neutral mixing (iso and triad operators): add the Method of Stabilizing Correction (MSC)
+  (more accurate calculation) + add a bilaplacian case
+- Lateral physics (LDF): scale aware setting of eddy viscosity and diffusivity
+- Wave coupling: large scale wave interaction process added in momentum and tracer equations
+- Remove the acceleration of convergence
+
+Numerics
+--------
+
+- Added tidal self attraction and loading either read from a file or from usual "scalar" approximation
+- Vertical physics (ZDF) (modularity, share shear production calculation between TKE and GKS,
+  removal of all ZDF CPP keys, removal of avmu & avmv, minimization of MPP comm.: ~15 removed)
+- Remove the split-explicit ZDF scheme for both TRA and DYN
+- Lateral physics (LDF): simplification of user interface and removal of CPP keys
+- Add a 4th order centered (CEN) and Flux Corrected Transport (FCT) tracer advection
+  (using a 4th compact in the vertical)
+- Generalised lbc_lnk and lbc_nfd
+- Configuration interface completely rewritten (DOM module mainly suppressed,
+  and in place: domain_cfg.nc file, or usr_def module)
+- Vorticity: 2 new energy conserving scheme:  ENT with Coriolis defined at T-point
+  (better for Flux form) and EET a variant of EEN where e3t is used instead of e3f
+  (solved the issue with e3f specification but is not enstrophy conserving)
+- Wave coupling: coupled interface to external wave model
+
+Performances
+------------
+
+- MPI Message passing recoded to reduce number of MPI communications (suppression of redundant communications,
+  gather multiple communications into one)
+- Back to standard dynamical allocation (remove of wrk_alloc/dealloc statements)
+- XIOS software for IOs version 2 as default, and optionally available for restarts
+- Unify mppini
+- Use non uniform jpi/jpj with dynamic allocation to avoid ghost rows/columns
+
+Environment
+-----------
+
+- Revised structure of namelist_ref/_cfg and default reference values.
+- Reorganisation of SVN repository to be compliant with usual directory tree and facilitate building of
+  NEMO executable
+- Improvements of reliability through automatic and regular testing of the changes made in repository
+
+.. _sea ice working group:       http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/SI3
+.. _TOP User Quick Guide:        http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/top-dg/TOP-UserQuickGuide
+
+.. The following references should be in the manual bibliographies and referenced via 'bibliography' directive
+.. _Brodeau 2017:                http://doi.org/10.1175/JPO-D-16-0169.1
+.. _Holland 2012:                http://doi.org/10.1175/JCLI-D-11-00078.1
+.. _Lupkes 2012:                 http://doi.org/10.1029/2012JD017630
+.. _Lupkes 2014:                 http://doi.org/10.1002/2014JD022418
+.. _Kimmritz 2016:               http://doi.org/10.1016/j.ocemod.2016.03.004
+.. _Orr and Epitalon 2015:       http://doi.org/10.5194/gmd-8-485-2015
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/1_namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/1_namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/1_namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !                         AGRIF ICE configuration                      !
@@ -127,5 +127,5 @@
 &namsbc_rnf    !   runoffs                                              (ln_rnf =T)
 !-----------------------------------------------------------------------
-   ln_rnf_mouth= .true.    !  specific treatment at rivers mouths
+   ln_rnf_mouth = .true.    !  specific treatment at rivers mouths
       rn_hrnf     =  15.e0    !  depth over which enhanced vertical mixing is used    (ln_rnf_mouth=T)
       rn_avt_rnf  =   1.e-3   !  value of the additional vertical mixing coef. [m2/s] (ln_rnf_mouth=T)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/2_namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/2_namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/2_namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/1_namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/1_namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !                         AGRIF ICE configuration                      !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/3_namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/3_namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/3_namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/1_namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/1_namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !                         AGRIF ICE configuration                      !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !                         AGRIF ICE configuration                      !
@@ -127,5 +127,5 @@
 &namsbc_rnf    !   runoffs                                              (ln_rnf =T)
 !-----------------------------------------------------------------------
-   ln_rnf_mouth= .true.    !  specific treatment at rivers mouths
+   ln_rnf_mouth = .true.    !  specific treatment at rivers mouths
       rn_hrnf     =  15.e0    !  depth over which enhanced vertical mixing is used    (ln_rnf_mouth=T)
       rn_avt_rnf  =   1.e-3   !  value of the additional vertical mixing coef. [m2/s] (ln_rnf_mouth=T)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/README.rst	(revision 10321)
@@ -0,0 +1,107 @@
+**********************
+Embedded zooms (AGRIF)
+**********************
+
+.. contents::
+   :local:
+
+Overview
+========
+
+AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over
+rectangular regions in NEMO.
+Refinement factors can be odd or even (usually lower than 5 to maintain stability).
+Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and
+the child grid provides volume averages of prognostic variables once a given number of time step is completed.
+These pages provide guidelines how to use AGRIF in NEMO.
+For a more technical description of the library itself, please refer to http://agrif.imag.fr.
+
+Compilation
+===========
+
+Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time: 
+
+.. code-block:: sh
+
+	./makenemo add_key 'key_agrif'
+
+Although this is transparent to users, the way the code is processed during compilation is different from
+the standard case:
+a preprocessing stage (the so called "conv" program) translates the actual code so that
+saved arrays may be switched in memory space from one domain to an other.
+
+Definition of the grid hierarchy
+================================
+
+An additional text file ``AGRIF_FixedGrids.in`` is required at run time.
+This is where the grid hierarchy is defined.
+An example of such a file, here taken from the ``ICEDYN`` test case, is given below::
+
+	1
+	34 63 34 63 3 3 3
+	0
+
+The first line indicates the number of zooms (1).
+The second line contains the starting and ending indices in both directions on the root grid
+(imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3).
+The last line is the number of child grid nested in the refined region (0).
+A more complex example with telescoping grids can be found below and
+in the ``AGRIF_DEMO`` reference configuration directory.
+
+[Add some plots here with grid staggering and positioning ?]
+
+When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and
+depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and
+nbghostcells=3.
+The grid refinement is 3 and nxfin is the number of child grid points in i-direction.  
+
+.. image:: _static/agrif_grid_position.jpg
+
+Note that rectangular regions must be defined so that they are connected to a single parent grid.
+Hence, defining overlapping grids with the same refinement ratio will not work properly,
+boundary data exchange and update being only performed between root and child grids.
+Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
+Defining for instance a circumpolar zoom in a global model is therefore not possible. 
+
+Preprocessing
+=============
+
+Knowing the refinement factors and area, a ``NESTING`` pre-processing tool may help to create needed input files
+(mesh file, restart, climatological and forcing files).
+The key is to ensure volume matching near the child grid interface,
+a step done by invoking the ``Agrif_create_bathy.exe`` program.
+You may use the namelists provided in the ``NESTING`` directory as a guide.
+These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
+
+Namelist options
+================
+
+Each child grid expects to read its own namelist so that different numerical choices can be made
+(these should be stored in the form ``1_namelist_cfg``, ``2_namelist_cfg``, etc... according to their rank in
+the grid hierarchy).
+Consistent time steps and number of steps with the chosen time refinement have to be provided.
+Specific to AGRIF is the following block:
+
+.. code-block:: fortran
+
+	!-----------------------------------------------------------------------
+	&namagrif      !  AGRIF zoom                                            ("key_agrif")
+	!-----------------------------------------------------------------------
+	   ln_spc_dyn    = .true.  !  use 0 as special value for dynamics
+	   rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s]
+	   rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s]
+	   ln_chk_bathy  = .false. !  =T  check the parent bathymetry
+	/             
+
+where sponge layer coefficients have to be chosen according to the child grid mesh size.
+The sponge area is hard coded in NEMO and applies on the following grid points:
+2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area) 
+
+References
+==========
+
+.. bibliography:: zooms.bib
+	:all:
+	:style: unsrt
+	:labelprefix: A
+	:keyprefix: a-
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/zooms.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/zooms.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AGRIF_DEMO/zooms.bib	(revision 10321)
@@ -0,0 +1,35 @@
+@article{DEBREU2012,
+   title = "Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation",
+   journal = "Ocean Modelling",
+   volume = "49-50",
+   pages = "1 - 21",
+   year = "2012",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2012.03.003",
+   author = "Laurent Debreu and Patrick Marchesiello and Pierrick Penven and Gildas Cambon",
+   keywords = "Two-way nesting, Finite difference method, Modeling, Boundary conditions, Coastal upwelling"
+}
+
+@article{PENVEN2006,
+   title = "Evaluation and application of the {ROMS} 1-way embedding procedure to the central california upwelling system",
+   journal = "Ocean Modelling",
+   volume = "12",
+   number = "1",
+   pages = "157 - 187",
+   year = "2006",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2005.05.002",
+   author = "Pierrick Penven and Laurent Debreu and Patrick Marchesiello and James C. McWilliams",
+   keywords = "Ocean models, Boundary conditions, Embedding, Coastal upwelling, Mesoscale eddies, Eddy kinetic energy, North America, West Coast, Central upwelling system, Monterey Bay, 35–41°N, 128–121°W"
+}
+
+@article{SPALL1991,
+   author = {Spall, Michael A. and Holland, William R.},
+   title = {A Nested Primitive Equation Model for Oceanic Applications},
+   journal = {Journal of Physical Oceanography},
+   volume = {21},
+   number = {2},
+   pages = {205-220},
+   year = {1991},
+   doi = {10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2},
+}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AMM12/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AMM12/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/AMM12/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !                          AMM12 configuration                         !
@@ -219,5 +219,5 @@
 &namdrg        !   top/bottom drag coefficient                          (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_loglayer= .true.     !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .true.     !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
 /
 !-----------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/EXPREF/namelist_cfg	(revision 10321)
@@ -2,5 +2,5 @@
 !! NEMO/OCE :   Reference namelist_ref                                !!
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  :  1 - Domain & run manager (namrun, namcfg, namdom, namtsd, namcrs, namc1d, namc1d_uvd)
+!! NEMO/OCE  :  1 - Domain & run manager (namrun, namcfg, namdom, namtsd, namcrs, namc1d, namc1d_uvd)
 !! namelists    2 - Surface boundary (namsbc, namsbc_flx, namsbc_blk, namsbc_cpl,
 !!                                    namsbc_sas, namtra_qsr, namsbc_rnf,
@@ -81,5 +81,5 @@
    rn_lat1d    =      50   !  Column latitude
    rn_lon1d    =    -145   !  Column longitude
-   ln_c1d_locpt=  .true.   ! Localization of 1D config in a grid (T) or independant point (F)
+   ln_c1d_locpt =  .true.   ! Localization of 1D config in a grid (T) or independant point (F)
 /
 !-----------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -30,5 +30,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/C1D_PAPA/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_BFM/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_BFM/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_BFM/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  : GYRE Configuration namelist : overwrite reference namelist
+!! NEMO/OCE  : GYRE Configuration namelist : overwrite reference namelist
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_PISCES/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_PISCES/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/GYRE_PISCES/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite reference namelist
+!! NEMO/OCE  Configuration namelist : overwrite reference namelist
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                      GYRE PISCES configuration                     !!
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/context_nemo.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/context_nemo.xml	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/context_nemo.xml	(revision 10321)
@@ -6,23 +6,13 @@
 <context id="nemo">
 <!-- $id$ -->
-    <variable_definition>
-    <!-- Year of time origin for NetCDF files; defaults to 1800 -->
-       <variable id="ref_year" type="int"   > 1800 </variable>
-       <variable id="rau0"     type="float" > 1026.0 </variable>
-       <variable id="cpocean"  type="float" > 3991.86795711963 </variable>
-       <variable id="convSpsu" type="float" > 0.99530670233846  </variable>
-       <variable id="rhoic"    type="float" > 917.0 </variable>
-       <variable id="rhosn"    type="float" > 330.0 </variable>
-       <variable id="missval"  type="float" > 1.e20 </variable>
-    </variable_definition>
 <!-- Fields definition -->
-    <field_definition src="./field_def_nemo-oce.xml"/>    <!--  NEMO ocean dynamics     -->
-    <field_definition src="./field_def_nemo-ice.xml"/>    <!--  NEMO sea-ice model      -->
-    <field_definition src="./field_def_nemo-pisces.xml"/> <!--  NEMO ocean biology      -->
+    <field_definition src="./field_def_nemo-oce.xml"/>    <!--  NEMO ocean dynamics     --> 
+    <field_definition src="./field_def_nemo-ice.xml"/>    <!--  NEMO sea-ice model      --> 
+    <field_definition src="./field_def_nemo-pisces.xml"/> <!--  NEMO ocean biology      --> 
 
 <!-- Files definition -->
-    <file_definition src="./file_def_nemo-oce.xml"/>     <!--  NEMO ocean dynamics      -->
-    <file_definition src="./file_def_nemo-ice.xml"/>     <!--  NEMO sea-ice model       -->
-    <file_definition src="./file_def_nemo-pisces.xml"/>  <!--  NEMO ocean biology       -->
+    <file_definition src="./file_def_nemo-oce.xml"/>     <!--  NEMO ocean dynamics      --> 
+    <file_definition src="./file_def_nemo-ice.xml"/>     <!--  NEMO sea-ice model       --> 
+    <file_definition src="./file_def_nemo-pisces.xml"/>  <!--  NEMO ocean biology       --> 
     <!-- 
 ============================================================================================================
@@ -32,13 +22,14 @@
     
     <axis_definition>
-      <axis id="deptht"  long_name="Vertical T levels"  unit="m" positive="down" />
-      <axis id="depthu"  long_name="Vertical U levels"  unit="m" positive="down" />
-      <axis id="depthv"  long_name="Vertical V levels"  unit="m" positive="down" />
-      <axis id="depthw"  long_name="Vertical W levels"  unit="m" positive="down" />
-      <axis id="nfloat"  long_name="Float number"       unit="-"                 />
-      <axis id="icbcla"  long_name="Iceberg class"      unit="1"                 />
-      <axis id="ncatice" long_name="Ice category"       unit="1"                 />
-      <axis id="iax_20C" long_name="20 degC isotherm"   unit="degC"              />
-      <axis id="iax_28C" long_name="28 degC isotherm"   unit="degC"              />
+      <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
+      <axis id="depthu" long_name="Vertical U levels" unit="m" positive="down" />
+      <axis id="depthv" long_name="Vertical V levels" unit="m" positive="down" />
+      <axis id="depthw" long_name="Vertical W levels" unit="m" positive="down" />
+      <axis id="profsed" long_name="Vertical S levels" unit="cm" positive="down" />
+      <axis id="nfloat" long_name="Float number"      unit="-"                 />
+      <axis id="icbcla"  long_name="Iceberg class"      unit="1"               />
+      <axis id="ncatice" long_name="Ice category"       unit="1"               />
+      <axis id="iax_20C" long_name="20 degC isotherm"   unit="degC"            />
+      <axis id="iax_28C" long_name="28 degC isotherm"   unit="degC"            />
     </axis_definition>
  
@@ -46,4 +37,4 @@
   
     <grid_definition src="./grid_def_nemo.xml"/>
-
+    
 </context>
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!             ORCA2 - ICE - PISCES configuration                     !!
@@ -88,4 +88,14 @@
    nn_fwb      = 2         !  FreshWater Budget: 
    !                       !    =2 annual global mean of e-p-r set to zero
+   ln_wave     = .false.   !  Activate coupling with wave  (T => fill namsbc_wave)
+   ln_cdgw     = .false.   !  Neutral drag coefficient read from wave model (T => ln_wave=.true. & fill namsbc_wave)
+   ln_sdw      = .false.   !  Read 2D Surf Stokes Drift & Computation of 3D stokes drift (T => ln_wave=.true. & fill namsbc_wave) 
+   nn_sdrift   =  0        !  Parameterization for the calculation of 3D-Stokes drift from the surface Stokes drift
+      !                    !   = 0 Breivik 2015 parameterization: v_z=v_0*[exp(2*k*z)/(1-8*k*z)]
+      !                    !   = 1 Phillips:                      v_z=v_o*[exp(2*k*z)-beta*sqrt(-2*k*pi*z)*erfc(sqrt(-2*k*z))]
+      !                    !   = 2 Phillips as (1) but using the wave frequency from a wave model
+   ln_tauwoc   = .false.   !  Activate ocean stress modified by external wave induced stress (T => ln_wave=.true. & fill namsbc_wave)
+   ln_tauw     = .false.   !  Activate ocean stress components from wave model
+   ln_stcor    = .false.   !  Activate Stokes Coriolis term (T => ln_wave=.true. & ln_sdw=.true. & fill namsbc_wave)
 /
 !-----------------------------------------------------------------------
@@ -135,5 +145,5 @@
 &namsbc_rnf    !   runoffs                                              (ln_rnf =T)
 !-----------------------------------------------------------------------
-   ln_rnf_mouth= .true.    !  specific treatment at rivers mouths
+   ln_rnf_mouth = .true.    !  specific treatment at rivers mouths
       rn_hrnf     =  15.e0    !  depth over which enhanced vertical mixing is used    (ln_rnf_mouth=T)
       rn_avt_rnf  =   1.e-3   !  value of the additional vertical mixing coef. [m2/s] (ln_rnf_mouth=T)
@@ -149,4 +159,8 @@
    sn_t_rnf    = 'runoffs'            ,    24    , 'rotemper',   .true.     , .true. , 'yearly'  , ''       , ''       , ''
    sn_dep_rnf  = 'runoffs'            ,     0    , 'rodepth' ,   .false.    , .true. , 'yearly'  , ''       , ''       , ''
+/
+!-----------------------------------------------------------------------
+&namsbc_wave   ! External fields from wave model                        (ln_wave=T)
+!-----------------------------------------------------------------------
 /
 !-----------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_pisces_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_pisces_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_ICE_PISCES/EXPREF/namelist_pisces_cfg	(revision 10321)
@@ -16,9 +16,9 @@
 /
 !-----------------------------------------------------------------------
-&namp4zice     !   parameters for nutrient limitations for PISCES std  - ln_p4z
+&namp4zlim     !   parameters for nutrient limitations for PISCES std  - ln_p4z
 !-----------------------------------------------------------------------
 /
 !-----------------------------------------------------------------------
-&namp5zice     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
+&namp5zlim     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
 !-----------------------------------------------------------------------
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/context_nemo.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/context_nemo.xml	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/context_nemo.xml	(revision 10321)
@@ -23,4 +23,5 @@
       <axis id="depthv" long_name="Vertical V levels" unit="m" positive="down" />
       <axis id="depthw" long_name="Vertical W levels" unit="m" positive="down" />
+      <axis id="profsed" long_name="Vertical S levels" unit="cm" positive="down" />
       <axis id="nfloat" long_name="Float number"      unit="-"                 />
       <axis id="icbcla"  long_name="Iceberg class"      unit="1"               />
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/namelist_pisces_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/namelist_pisces_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_PISCES/EXPREF/namelist_pisces_cfg	(revision 10321)
@@ -17,9 +17,9 @@
 /
 !-----------------------------------------------------------------------
-&namp4zice     !   parameters for nutrient limitations for PISCES std  - ln_p4z
+&namp4zlim     !   parameters for nutrient limitations for PISCES std  - ln_p4z
 !-----------------------------------------------------------------------
 /
 !-----------------------------------------------------------------------
-&namp5zice     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
+&namp5zlim     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
 !-----------------------------------------------------------------------
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_TRC/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_TRC/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_OFF_TRC/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!               ORCA2 - OFF - TRC configuration                     !!
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_SAS_ICE/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_SAS_ICE/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/ORCA2_SAS_ICE/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                ORCA2-ICE (with SAS) configuration                  !!
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/README.rst	(revision 10321)
@@ -0,0 +1,349 @@
+*****************************
+Run a reference configuration
+*****************************
+
+.. contents::
+	:local:
+	:depth: 1
+      
+Official configurations
+=======================
+
+| NEMO is distributed with some reference configurations allowing both the user to set up a first application and
+  the developer to validate their developments.
+| :underline:`The NEMO System Team is in charge of these configurations`.
+
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+|                      | OPA | SI3 | TOP | PISCES | AGRIF | Inputs                        |
++======================+=====+=====+=====+========+=======+===============================+
+| `AGRIF_DEMO`_        |  X  |  X  |     |        |   X   | - `AGRIF_DEMO_v4.0.tar`_      |
+|                      |     |     |     |        |       | - `ORCA2_ICE_v4.0.tar`_       |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `AMM12`_             |  X  |     |     |        |       | `AMM12_v4.0.tar`_             |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `C1D_PAPA`_          |  X  |     |     |        |       | `INPUTS_C1D_PAPA_v4.0.tar`_   |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `GYRE_BFM`_          |  X  |     |  X  |        |       | ``-``                         |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `GYRE_PISCES`_       |  X  |     |  X  |   X    |       | ``-``                         |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `ORCA2_ICE_PISCES`_  |  X  |  X  |  X  |   X    |       | - `ORCA2_ICE_v4.0.tar`_       |
+|                      |     |     |     |        |       | - `INPUTS_PISCES_v4.0.tar`_   |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `ORCA2_OFF_PISCES`_  |     |     |  X  |   X    |       | - `INPUTS_PISCES_v4.0.tar`_   |
+|                      |     |     |     |        |       | - `ORCA2_OFF_v4.0.tar`_       |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `ORCA2_OFF_TRC`_     |     |     |  X  |        |       | `ORCA2_OFF_v4.0.tar`_         |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `ORCA2_SAS_ICE`_     |     |  X  |     |        |       | - `ORCA2_ICE_v4.0.tar`_       |
+|                      |     |     |     |        |       | - `INPUTS_SAS_v4.0.tar`_      |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+| `SPITZ12`_           |  X  |  X  |     |        |       | `SPITZ12_v4.0.tar`_           |
++----------------------+-----+-----+-----+--------+-------+-------------------------------+
+
+AGRIF_DEMO
+----------
+
+.. image:: _static/AGRIF_DEMO.jpg
+
+``AGRIF_DEMO`` is based on the ``ORCA2_LIM3_PISCES`` global 2° configuration but
+it includes 3 online nested grids that demonstrate the overall capabilities of AGRIF in a realistic context,
+including nesting sea ice models.
+
+The configuration includes a 1:1 grid in the Pacific and two successively nested grids with odd and
+even refinement ratios over the Arctic ocean.
+The finest grid spanning the whole Svalbard archipelago is of particular interest to check that
+sea ice coupling is done properly.
+The 1:1 grid, used alone, is used as a benchmark to check that the solution is not corrupted by grid exchanges.
+
+Note that since grids interact only at the baroclinic time level,
+numerically exact results can not be achieved in the 1:1 case.
+One has to switch to a fully explicit in place of a split explicit free surface scheme in order to
+retrieve perfect reproducibility.
+
+Corresponding ``AGRIF_FixedGrids.in`` file is given by::
+
+	2
+	42 82 49 91 1 1 1
+	122 153 110 143 4 4 4
+	0
+	1
+	38 80 71 111 3 3 3
+	0
+
+AMM12
+-----
+
+``AMM12`` for *Atlantic Margin Model 12kms* is a `regional model`_ covering the Northwest European Shelf domain on
+a regular lat-lon grid at approximately 12km horizontal resolution.
+The key ``key_amm_12km`` is used to create the correct dimensions of the AMM domain.
+
+| This configuration tests several features of NEMO functionality specific to the shelf seas.
+| In particular, the AMM uses s-coordinates in the vertical rather than z-coordinates and is forced with
+  tidal lateral boundary conditions using a flather boundary condition from the BDY module (``key_bdy``).
+
+The AMM configuration uses the GLS (``key_zdfgls``) turbulence scheme,
+the VVL non-linear free surface (``key_vvl``) and time-splitting (``key_dynspg_ts``).
+
+In addition to the tidal boundary condition, the model may also take open boundary conditions from
+a North Atlantic model.
+Boundaries may be completely ommited by removing the BDY key (key_bdy) in ``./cfgs/AMM12/cpp_AMM12_fcm``.
+
+Sample surface fluxes, river forcing and a sample initial restart file are included to test a realistic model run.
+The Baltic boundary is included within the river input file and is specified as a river source.
+Unlike ordinary river points the Baltic inputs also include salinity and temperature data.
+
+C1D_PAPA
+--------
+
+``C1D_PAPA`` is a 1D configuration (one water column called NEMO1D, activated with CPP key ``key_c1d``),
+located at the `PAPA station 145W-50N <http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml>`_.
+
+| NEMO1D is useful to test vertical physics in NEMO
+  (turbulent closure scheme, solar penetration, interaction ocean/atmosphere.,...)
+| Size of the horizontal domain is 3x3 grid points.
+
+This reference configuration uses a 75 vertical levels grid (1m at the surface),
+the GLS (key_zdfgls) turbulence scheme with K-epsilon closure and the CORE BULK formulae.
+The atmospheric forcing comes from ECMWF operational analysis with a modification of the long and short waves flux.
+This set has been rescaled at a frequency of 1h. 1 year is simulated in outputs,
+see below (June,15 2010 to June,14 2011)
+
+`Reffray 2015`_ describes some tests on vertical physic using this configuration.
+
+The inputs tar file includes:
+
+- forcing files covering the years 2010 and 2011 (``forcing_PAPASTATION_1h_y201*.nc``)
+- initialization file for June,15 2010 deduced from observed data and Levitus 2009 climatology
+  (``init_PAPASTATION_m06d15.nc``)
+- surface chlorophyll file (``chlorophyll_PAPASTATION.nc``) deduced from Seawifs data.
+
+GYRE_BFM
+--------
+
+``GYRE_BFM`` is the same configuration as `GYRE_PISCES`_, except that PISCES is replaced by
+BFM biogeochemichal model in coupled mode.
+
+GYRE_PISCES
+-----------
+
+| Idealized configuration representing double gyres in the North hemisphere, Beta-plane with
+  a regular grid spacing at 1° horizontal resolution (and possible use as a benchmark by
+  easily inscreasing grid size), 101 vertical levels, forced with analytical heat, freshwater and
+  wind-stress fields.
+| This configuration is coupled to `PISCES biogeochemical model`_.
+
+Running GYRE as a benchmark
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This simple configuration can be used as a benchmark since it is easy to increase resolution
+(and in this case no physical meaning of outputs):
+
+1. Choose the grid size
+
+   In ``./cfgs/GYRE/EXP00``, edit your ``namelist_cfg`` file to change the ``jp_cfg``, ``jpi``, ``jpj``,
+   ``jpk`` variables in &namcfg:
+
+	+------------+---------+---------+---------+------------------+---------------+
+	| ``jp_cfg`` | ``jpi`` | ``jpj`` | ``jpk`` | Number of points | Equivalent to |
+	+============+=========+=========+=========+==================+===============+
+	| 1          | 30      | 20      | 101     | 60600            | GYRE 1°       |
+	+------------+---------+---------+---------+------------------+---------------+
+	| 25         | 750     | 500     | 101     | 37875000         | ORCA 1/2°     |
+	+------------+---------+---------+---------+------------------+---------------+
+	| 50         | 1500    | 1000    | 101     | 151500000        | ORCA 1/4°     |
+	+------------+---------+---------+---------+------------------+---------------+
+	| 150        | 4500    | 3000    | 101     | 1363500000       | ORCA 1/12°    |
+	+------------+---------+---------+---------+------------------+---------------+
+	| 200        | 6000    | 4000    | 101     | 2424000000       | ORCA 1/16°    |
+	+------------+---------+---------+---------+------------------+---------------+
+
+2. In `namelist_cfg` again, avoid problems in the physics (and results will not be meaningful in terms of physics) by setting `nn_bench = 1` in &namctl
+
+.. code-block:: fortran
+   
+   nn_bench    =    1     !  Bench mode (1/0): CAUTION use zero except for bench
+
+3. If you increase domain size, you may need to decrease time-step (for stability) by changing `rn_rdt` value in &namdom (i.e. for `jp_cfg = 150`, ORCA12 equivalent, use `rn_rdt = 1200`)
+
+.. code-block:: fortran
+   
+   rn_rdt      = 1200.     !  time step for the dynamics
+
+4. Optional, in order to increase the number of MPI communication for benchmark purposes:
+   you can change the number of sub-timesteps computed in the time-splitting scheme each iteration.
+   First change the list of active CPP keys for your experiment,
+   in `cfgs/"your configuration name"/cpp_"your configuration name".fcm`:
+   replace ``key_dynspg_flt by key_dynspg_ts`` and recompile/create your executable again
+   
+   .. code-block:: fortran
+   
+   makenemo [...] add_key 'key_dynspg_ts' del_key 'key_dynspg_flt'
+
+In your ``namelist_cfg`` file, edit the &namsplit namelist by adding the following line: 
+
+.. code-block:: fortran
+   
+   nn_baro       =    30               !  Number of iterations of barotropic mode/
+
+``nn_baro = 30`` is a kind of minimum (we usually use 30 to 60).
+So than increasing the ``nn_baro`` value will increase the number of MPI communications.
+
+The GYRE CPP keys, namelists and scripts can be explored in the ``GYRE`` configuration directory
+(``./cfgs/GYRE`` and ``./cfgs/GYRE/EXP00``).
+
+Find monthly mean outputs of 1 year run here:
+http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html
+
+ORCA2_ICE_PISCES
+----------------
+
+ORCA is the generic name given to global ocean configurations.
+Its specificity lies on the horizontal curvilinear mesh used to overcome the North Pole singularity found for
+geographical meshes.
+SI3 (Sea Ice Integrated Initiative) is a thermodynamic-dynamic sea ice model specifically designed for
+climate studies.
+A brief description of the model is given here.
+
+:underline:`Space-time domain`
+
+The horizontal resolution available through the standard configuration is ORCA2.
+It is based on a 2 degrees Mercator mesh, (i.e. variation of meridian scale factor as cosinus of the latitude).
+In the northern hemisphere the mesh has two poles so that the ratio of anisotropy is nearly one everywhere.
+The mean grid spacing is about 2/3 of the nominal value: for example it is 1.3 degrees for ORCA2.
+Other resolutions (ORCA4, ORCA05 and ORCA025) are running or under development within specific projects.
+In the coarse resolution version (i.e. ORCA2 and ORCA4) the meridional grid spacing is increased near
+the equator to improve the equatorial dynamics.
+Figures in pdf format of mesh and bathymetry can be found and downloaded here.
+The sea-ice model runs on the same grid.
+
+The vertical domain spreads from the surface to a depth of 5000m.
+There are 31 levels, with 10 levels in the top 100m.
+The vertical mesh is deduced from a mathematical function of z ([[AttachmentNum(1)]]).
+The ocean surface corresponds to the w-level k=1, and the ocean bottom to the w-level k=31.
+The last T-level (k=31) is thus always in the ground.The depths of the vertical levels and
+the associated scale factors can be viewed.
+Higher vertical resolution is used in ORCA025 and ORCA12 (see `DRAKKAR project <http://www.drakkar-ocean.eu>`_).
+
+The time step depends on the resolution. It is 1h36' for ORCA2 so that there is 15 time steps in one day.
+
+:underline:`Ocean Physics (for ORCA2)`
+
+- horizontal diffusion on momentum: the eddy viscosity coefficient depends on the geographical position.
+  It is taken as 40000 $m^2/s$, reduced in the equator regions (2000 $m^2/s$) excepted near the western boundaries.
+- isopycnal diffusion on tracers: the diffusion acts along the isopycnal surfaces (neutral surface) with
+  a eddy diffusivity coefficient of 2000 $m^2/s$.
+- Eddy induced velocity parametrization with a coefficient that depends on the growth rate of
+  baroclinic instabilities (it usually varies from 15 $m^2/s$ to 3000 $m^2/s$).
+- lateral boundary conditions : zero fluxes of heat and salt and no-slip conditions are applied through
+  lateral solid boundaries.
+- bottom boundary condition : zero fluxes of heat and salt are applied through the ocean bottom.
+  The Beckmann [19XX] simple bottom boundary layer parameterization is applied along continental slopes.
+  A linear friction is applied on momentum.
+- convection: the vertical eddy viscosity and diffusivity coefficients are increased to 1 $m^2/s$ in case of
+  static instability.
+- forcings: the ocean receives heat, freshwater, and momentum fluxes from the atmosphere and/or the sea-ice.
+  The solar radiation penetrates the top meters of the ocean.
+  The downward irradiance I(z) is formulated with two extinction coefficients [Paulson and Simpson, 1977],
+  whose values correspond to a Type I water in Jerlov's classification (i.e the most transparent water)
+
+ORCA2_ICE_PISCES is a reference configuration with the following characteristics:
+
+- global ocean configuration
+- based on a tri-polar ORCA grid, with a 2° horizontal resolution
+- 31 vertical levels
+- forced with climatological surface fields
+- coupled to the sea-ice model SI3.
+- coupled to TOP passive tracer transport module and `PISCES biogeochemical model`_.
+
+:underline:`AGRIF demonstrator`
+
+| From the ``ORCA2_ICE_PISCES`` configuration, a demonstrator using AGRIF nesting can be activated.
+  It includes the global ``ORCA2_ICE_PISCES`` configuration and a nested grid in the Agulhas region.
+| To set up this configuration, after extracting NEMO:
+
+- Build your AGRIF configuration directory from ORCA2_ICE_PISCES, with the key_agrif CPP key activated:
+
+.. code-block:: console
+                
+	$ ./makenemo -r 'ORCA2_ICE_PISCES' -n 'AGRIF' add_key 'key_agrif'
+
+- Using the ``ORCA2_ICE_PISCES`` input files and namelist, AGRIF test configuration is ready to run
+
+:underline:`On-The-Fly Interpolation`
+
+| NEMO allows to use the interpolation on the fly option allowing to interpolate input data during the run.
+  If you want to use this option you need files giving informations on weights, which have been created.
+| You can find at http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/WEIGHTS/catalog.html
+  2 weights files `bil_weights` for scalar field (bilinear interpolation) and `bic_weights` for
+  vector field (bicubic interpolation).
+| The data files used are `COREII forcing <http://data1.gdfl.noaa.gov/nomads/forms/mom4/COREv2>`_ extrapolated on
+  continents, ready to be used for on the fly option:
+  `COREII`_ forcing files extrapolated on continents
+
+ORCA2_OFF_PISCES
+----------------
+
+``ORCA2_OFF_PISCES`` uses the ORCA2 configuration in which the `PISCES biogeochemical model`_ has been activated in
+standalone using the dynamical fields that are pre calculated.
+
+See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
+
+The input files for PISCES are needed, in addition the dynamical fields are used as input.
+They are coming from a 2000 years of an ORCA2_LIM climatological run using ERA40 atmospheric forcing.
+
+ORCA2_OFF_TRC
+-------------
+
+``ORCA2_OFF_TRC`` uses the ORCA2_LIM configuration in which the tracer passive transport module TOP has been
+activated in standalone using the dynamical fields that are pre calculated.
+
+See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
+
+In ``namelist_top_cfg``, different passive tracers can be activated ( cfc11, cfc12, sf6, c14, age ) or my-trc,
+a user-defined tracer.
+
+The dynamical fields are used as input, they are coming from a 2000 years of an ORCA2_LIM climatological run using
+ERA40 atmospheric forcing.
+
+ORCA2_SAS_ICE
+-------------
+
+``ORCA2_SAS_ICE`` is a demonstrator of the SAS ( Stand-alone Surface module ) based on ORCA2_LIM configuration.
+
+The standalone surface module allows surface elements such as sea-ice, iceberg drift and surface fluxes to
+be run using prescribed model state fields.
+For example, it can be used to inter-compare different bulk formulae or adjust the parameters of
+a given bulk formula
+
+See `ORCA2_ICE_PISCES`_ for general description of ORCA2.
+
+Same input files as `ORCA2_ICE_PISCES`_ are needed plus fields from a previous ORCA2_LIM run.
+
+More informations on input and configuration files in `NEMO manual`_.
+
+SPITZ12
+-------
+
+``SPITZ12``
+
+Unsupported configurations
+==========================
+
+Other configurations are developed and used by some projects with "NEMO inside",
+these projects are welcome to publicize it here: http://www.nemo-ocean.eu/projects/add-project
+
+:underline:`Obviously these "projects configurations" are not under the NEMO System Team's responsibility`.
+
+.. _regional model:               http://www.tandfonline.com/doi/pdf/10.1080/1755876X.2012.11020128
+.. _AMM12_v4.0.tar:               http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AMM12_v4.0.tar
+.. _PISCES biogeochemical model:  http://www.geosci-model-dev.net/8/2465/2015
+.. _INPUTS_PISCES_v4.0.tar:       http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_PISCES_v4.0.tar
+.. _ORCA2_OFF_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_OFF_v4.0.tar
+.. _ORCA2_ICE_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_ICE_v4.0.tar
+.. _INPUTS_SAS_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_SAS_v4.0.tar
+.. _INPUTS_C1D_PAPA_v4.0.tar:     http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_C1D_PAPA_v4.0.tar
+.. _Reffray 2015:                 http://www.geosci-model-dev.net/8/69/2015
+.. _COREII:                       http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/FILLED_FILES/catalog.html
+.. _SPITZ12_v4.0.tar:             http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/SPITZ12_v4.0.tar
+.. _AGRIF_DEMO_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AGRIF_DEMO_v4.0.tar
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/README.rst	(revision 10321)
@@ -0,0 +1,104 @@
+******************
+Diagnostics (XIOS)
+******************
+
+.. contents::
+	:local:
+
+| Output of diagnostics in NEMO is usually done using XIOS.
+  This is an efficient way of writing diagnostics because the time averaging, file writing and even
+  some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
+| This page gives a basic introduction to using XIOS with NEMO.
+  Much more information is available from the XIOS homepage above and from the `NEMO manual`_.
+
+Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``.
+The default version of XIOS is the 2.0 release. 
+
+Extracting and installing XIOS
+==============================
+
+1. Install the NetCDF4 library.
+   If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO.
+2. Download the version of XIOS that you wish to use.
+   The recommended version is now XIOS 2.0:
+   
+	.. code-block:: console
+
+		$ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0
+
+	and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
+	If you find problems at this stage, support can be found by subscribing to the `XIOS mailing list
+	<http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users>`_
+	and sending a mail message to it. 
+
+Namelists
+=========
+
+XIOS is controlled using xml input files that should be copied to your model run directory before
+running the model.
+The exact setup differs slightly between 1.0 and 2.0 releases.
+
+An ``iodef.xml`` file is still required in the run directory.
+For XIOS 2.0 the ``field_def.xml`` file has been further split into ``field_def-oce.xml`` (for physics),
+``field_def-ice.xml`` (for ice) and ``field_def-bgc.xml`` (for biogeochemistry).
+Also the definition of the output files has been moved from the ``iodef.xml`` file into
+separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file.
+Note that the ``domain_def.xml`` file is also different for XIOS 2.0.
+
+Modes
+=====
+
+Detached Mode
+-------------
+
+In detached mode the XIOS executable is executed on separate cores from the NEMO model.
+This is the recommended method for using XIOS for realistic model runs.
+To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file:
+
+.. code-block:: xml
+
+	<variable id="using_server" type="boolean">true</variable>
+
+Make sure there is a copy (or link to) your XIOS executable in the working directory and
+in your job submission script allocate processors to XIOS.
+
+Attached Mode
+-------------
+
+In attached mode XIOS runs on each of the cores used by NEMO.
+This method is less efficient than the detached mode but can be more convenient for testing or
+with small configurations.
+To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file
+
+.. code-block:: xml
+
+	<variable id="using_server" type="boolean">false</variable>
+
+and don't allocate any cores to XIOS.
+Note that due to the different domain decompositions between XIOS and NEMO if
+the total number of cores is larger than the number of grid points in the j direction then the model run will fail.
+
+Adding new diagnostics
+======================
+
+If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
+
+1. Add any necessary code to calculate you new diagnostic in NEMO
+2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for
+   your new diagnostics and variable is the fortran variable containing the data.
+   This should be called at every model timestep regardless of how often you want to output the field.
+   No time averaging should be done in the model code. 
+3. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to
+   determine if it is requested in the current model run. For example,
+   
+	.. code-block:: fortran
+
+		IF iom_use('field_id') THEN
+		   !Some expensive computation
+	   	!...
+		   !...
+	   	iom_put('field_id', variable)
+		ENDIF
+
+4. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file
+5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/field_def_nemo-pisces.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/field_def_nemo-pisces.xml	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/field_def_nemo-pisces.xml	(revision 10321)
@@ -115,4 +115,49 @@
 
      </field_group>
+
+     <!-- SEDIMENT variables on T sediment grid  -->
+     <field_group id="sed_T" grid_ref="grid_T_3DS">
+       <field id="SedDIC"          long_name="Dissolved inorganic Concentration"        unit="mmol/m3" />
+       <field id="SedAlkalini"     long_name="Total Alkalinity Concentration"           unit="mmol/m3" />
+       <field id="SedO2"           long_name="Oxygen Concentration"                     unit="mmol/m3" />
+       <field id="SedCaCO3"        long_name="Calcite Concentration"                    unit="%" />
+       <field id="SedPOS"          long_name="Semi-ref POC Concentration"               unit="%" />
+       <field id="SedPOR"          long_name="Refractory POC Concentration"             unit="%" />
+       <field id="SedPO4"          long_name="Phosphate Concentration"                  unit="mmol/m3" />
+       <field id="SedPOC"          long_name="Labile POC Concentration"                 unit="%" />
+       <field id="SedSil"          long_name="Silicate Concentration"                   unit="mmol/m3" />
+       <field id="SedFe2"          long_name="Fe2+ Concentration"                       unit="mmol/m3" />
+       <field id="SedBSi"          long_name="Biogenic Silicate Concentration"          unit="%" />
+       <field id="SedNO3"          long_name="Nitrate Concentration"                    unit="mmol/m3" />
+       <field id="SedNH4"          long_name="Ammonium Concentration"                   unit="mmol/m3" />
+       <field id="SedH2S"          long_name="H2S Concentration"                        unit="mmol/m3" />
+       <field id="SedSO4"          long_name="SO4 Concentration"                        unit="mmol/m3" />
+       <field id="SedClay"         long_name="Clay Concentration"                       unit="%" />
+       <field id="SedFeO"          long_name="Fe(OH)3 Concentration"                    unit="%" />
+       <field id="SedFeS"          long_name="FeS Concentration"                        unit="%" />
+       <field id="SedpH"           long_name="PH"                                       unit="1"          />
+       <field id="SedCO3por"       long_name="Bicarbonates"                             unit="mol/m3" />
+     </field_group>
+
+     <!-- SEDIMENT additional variables on T sediment grid  -->
+     <field_group id="Diag_S" grid_ref="grid_T_2D">
+       <field id="FlxSi"       long_name="Si sediment flux"                        unit="mol/cm2/s"     />
+       <field id="FlxO2"       long_name="O2 sediment flux"                        unit="mol/cm2/s"     />
+       <field id="FlxDIC"      long_name="DIC sediment flux"                       unit="mol/cm2/s"     />
+       <field id="FlxNO3"      long_name="NO3 sediment flux"                       unit="mol/cm2/s"     />
+       <field id="FlxPO4"      long_name="PO4 sediment flux"                       unit="mol/cm2/s"     />
+       <field id="FlxAlkalini" long_name="Alkalinity sediment flux"                unit="mol/cm2/s"     />
+       <field id="FlxNH4"      long_name="Ammonium sediment flux"                  unit="mol/cm2/s"     />
+       <field id="FlxH2S"      long_name="H2S sediment flux"                       unit="mol/cm2/s"     />
+       <field id="FlxSO4"      long_name="SO4 sediment flux"                       unit="mol/cm2/s"     />
+       <field id="FlxFe2"      long_name="Fe2+ sediment flux"                      unit="mol/cm2/s"     />
+       <field id="Flxtot"      long_name="Sediment net burial rate"                unit="cm/s"     />
+       <field id="dzdep"       long_name="Sedimentation rate"                      unit="cm/s"     />
+       <field id="sflxclay"    long_name="Clay sedimentation rate"                 unit="g/m2/s"     />
+       <field id="sflxcal"     long_name="Calcite sedimentation rate"              unit="mol/m2/s"     />
+       <field id="sflxbsi"     long_name="BSi Sedimentation rate"                  unit="mol/m2/s"     />
+       <field id="sflxpoc"     long_name="POC Sedimentation rate"                  unit="mol/m2/s"     />
+       <field id="sflxfeo"     long_name="Fe(OH)3 Sedimentation rate"              unit="mol/m2/s"     />
+</field_group>
 
      <!-- PISCES additional diagnostics on T grid  -->
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/grid_def_nemo.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/grid_def_nemo.xml	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/grid_def_nemo.xml	(revision 10321)
@@ -15,4 +15,9 @@
          <domain id="grid_T" />
          <axis id="deptht" />
+       </grid>
+        <!--  -->
+       <grid id="grid_T_3DS" >
+         <domain id="grid_T" />
+         <axis id="profsed" />
        </grid>
         <!--  -->
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ice_ref
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ice_ref	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ice_ref	(revision 10321)
@@ -205,5 +205,5 @@
    sn_tmi = 'Ice_initialization'    , -12 ,'tmi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
    sn_smi = 'Ice_initialization'    , -12 ,'smi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   cn_dir='./'
+   cn_dir ='./'
 /
 !------------------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_pisces_ref
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_pisces_ref	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_pisces_ref	(revision 10321)
@@ -17,4 +17,5 @@
   ln_p5z    = .false.        !  PISCES QUOTA model used
   ln_ligand = .false.        !  Enable  organic ligands
+  ln_sediment = .false.      !  Enable sediment module
 /
 !-----------------------------------------------------------------------
@@ -49,5 +50,5 @@
    wsbio2     =  50.      ! Big particles sinking speed
    wsbio2max  =  50.      ! Big particles maximum sinking speed
-   wsbio2scale=  5000.    ! Big particles length scale of sinking
+   wsbio2scale =  5000.    ! Big particles length scale of sinking
    niter1max  =  1        ! Maximum number of iterations for POC
    niter2max  =  2        ! Maximum number of iterations for GOC
@@ -62,5 +63,5 @@
 /
 !-----------------------------------------------------------------------
-&namp4zice     !   parameters for nutrient limitations for PISCES std  - ln_p4z
+&namp4zlim     !   parameters for nutrient limitations for PISCES std  - ln_p4z
 !-----------------------------------------------------------------------
    concnno3   =  1.e-6    ! Nitrate half saturation of nanophytoplankton
@@ -86,5 +87,5 @@
 /
 !-----------------------------------------------------------------------
-&namp5zice     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
+&namp5zlim     !   parameters for nutrient limitations PISCES QUOTA    - ln_p5z
 !-----------------------------------------------------------------------
    concnno3   =  3e-6     ! Nitrate half saturation of nanophytoplankton
@@ -370,4 +371,5 @@
    ln_hydrofe  =  .false.  ! boolean for from hydrothermal vents
    sedfeinput  =  2.e-9    ! Coastal release of Iron
+   distcoast   =  5.e3     ! Distance off the coast for Iron from sediments
    dustsolub   =  0.02     ! Solubility of the dusta
    mfrac       =  0.035    ! Fe mineral fraction of dust
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ref
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ref	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SHARED/namelist_ref	(revision 10321)
@@ -2,5 +2,5 @@
 !! NEMO/OCE :   Reference namelist_ref                                !!
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  :  1 - Domain & run manager (namrun, namcfg, namdom, namtsd, namcrs, namc1d, namc1d_uvd)
+!! NEMO/OCE  :  1 - Domain & run manager (namrun, namcfg, namdom, namtsd, namcrs, namc1d, namc1d_uvd)
 !! namelists    2 - Surface boundary (namsbc, namsbc_flx, namsbc_blk, namsbc_cpl,
 !!                                    namsbc_sas, namtra_qsr, namsbc_rnf,
@@ -50,5 +50,5 @@
       cn_ocerst_indir = "."         !  directory from which to read input ocean restarts
       cn_ocerst_out   = "restart"   !  suffix of ocean restart name (output)
-      cn_ocerst_outdir= "."         !  directory in which to write output ocean restarts
+      cn_ocerst_outdir = "."         !  directory in which to write output ocean restarts
    ln_iscpl    = .false.   !  cavity evolution forcing or coupling to ice sheet model
    nn_istate   =       0   !  output the initial state (1) or not (0)
@@ -90,5 +90,5 @@
       !                         !  If closea_mask field doesn't exist in the domain_cfg file
       !                         !       then this logical does nothing.
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
       cn_domcfg_out = "domain_cfg_out" ! newly created domain configuration filename
       !
@@ -116,5 +116,5 @@
    ln_wd_dl    = .false.   !  T/F activation of directional limiter
    ln_wd_dl_bc = .false.   !  T/F Directional limiteer Baroclinic option
-   ln_wd_dl_rmp= .false.   !  T/F Turn on directional limiter ramp
+   ln_wd_dl_rmp = .false.   !  T/F Turn on directional limiter ramp
    rn_wdmin0   =  0.30     !  depth at which WaD starts
    rn_wdmin1   =  0.2      !  Minimum wet depth on dried cells
@@ -143,5 +143,5 @@
    rn_lat1d    =      50   !  Column latitude
    rn_lon1d    =    -145   !  Column longitude
-   ln_c1d_locpt=  .true.   ! Localization of 1D config in a grid (T) or independant point (F)
+   ln_c1d_locpt =  .true.   ! Localization of 1D config in a grid (T) or independant point (F)
 /
 !-----------------------------------------------------------------------
@@ -248,6 +248,6 @@
    !                    !  bulk algorithm :
    ln_NCAR     = .false.   ! "NCAR"      algorithm   (Large and Yeager 2008)
-   ln_COARE_3p0= .false.   ! "COARE 3.0" algorithm   (Fairall et al. 2003)
-   ln_COARE_3p5= .false.   ! "COARE 3.5" algorithm   (Edson et al. 2013)
+   ln_COARE_3p0 = .false.   ! "COARE 3.0" algorithm   (Fairall et al. 2003)
+   ln_COARE_3p5 = .false.   ! "COARE 3.5" algorithm   (Edson et al. 2013)
    ln_ECMWF    = .false.   ! "ECMWF"     algorithm   (IFS cycle 31)
       !
@@ -398,9 +398,9 @@
 &namsbc_rnf    !   runoffs                                              (ln_rnf =T)
 !-----------------------------------------------------------------------
-   ln_rnf_mouth= .false.   !  specific treatment at rivers mouths
+   ln_rnf_mouth = .false.   !  specific treatment at rivers mouths
       rn_hrnf     =  15.e0    !  depth over which enhanced vertical mixing is used    (ln_rnf_mouth=T)
       rn_avt_rnf  =   1.e-3   !  value of the additional vertical mixing coef. [m2/s] (ln_rnf_mouth=T)
    rn_rfact    =   1.e0    !  multiplicative factor for runoff
-   ln_rnf_depth= .false.   !  read in depth information for runoff
+   ln_rnf_depth = .false.   !  read in depth information for runoff
    ln_rnf_tem  = .false.   !  read in temperature information for runoff
    ln_rnf_sal  = .false.   !  read in salinity information for runoff
@@ -462,6 +462,6 @@
    sn_rnfisf   = 'rnfisf'    ,         -12       ,'sofwfisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 !* nn_isf = 2 and 3 cases 
-   sn_depmax_isf='rnfisf'    ,         -12       ,'sozisfmax',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
-   sn_depmin_isf='rnfisf'    ,         -12       ,'sozisfmin',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_depmax_isf ='rnfisf'    ,         -12       ,'sozisfmax',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_depmin_isf ='rnfisf'    ,         -12       ,'sozisfmin',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 !* nn_isf = 2 case
    sn_Leff_isf = 'rnfisf'    ,         -12       ,'Leff'     ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
@@ -481,14 +481,14 @@
    !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
    !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
-   sn_cdg      =  'sdw_wave'             ,        1          , 'drag_coeff' ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_usd      =  'sdw_wave'             ,        1          , 'u_sd2d'     ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_vsd      =  'sdw_wave'             ,        1          , 'v_sd2d'     ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_hsw      =  'sdw_wave'             ,        1          , 'hs'         ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_wmp      =  'sdw_wave'             ,        1          , 'wmp'        ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_wfr      =  'sdw_wave'             ,        1          , 'wfr'        ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_wnum     =  'sdw_wave'             ,        1          , 'wave_num'   ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_tauwoc   =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_tauwx    =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
-   sn_tauwy    =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_cdg      =  'sdw_ecwaves_orca2'    ,        6          , 'drag_coeff' ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_usd      =  'sdw_ecwaves_orca2'    ,        6          , 'u_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_vsd      =  'sdw_ecwaves_orca2'    ,        6          , 'v_sd2d'     ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_hsw      =  'sdw_ecwaves_orca2'    ,        6          , 'hs'         ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wmp      =  'sdw_ecwaves_orca2'    ,        6          , 'wmp'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wfr      =  'sdw_ecwaves_orca2'    ,        6          , 'wfr'        ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_wnum     =  'sdw_ecwaves_orca2'    ,        6          , 'wave_num'   ,  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwoc   =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwx    =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
+   sn_tauwy    =  'sdw_ecwaves_orca2'    ,        6          , 'wave_stress',  .true.  , .true. , 'yearly'  ,  ''              , ''       , ''
 /
 !-----------------------------------------------------------------------
@@ -581,5 +581,5 @@
       cn_coords_file = 'coordinates.bdy.nc'  !  bdy coordinates files
    ln_mask_file   = .false.   !  =T : read mask from file
-      cn_mask_file= ''        !  name of mask file (if ln_mask_file=.TRUE.)
+      cn_mask_file = ''        !  name of mask file (if ln_mask_file=.TRUE.)
    cn_dyn2d    = 'none'       !
    nn_dyn2d_dta   =  0        !  = 0, bdy data are equal to the initial state
@@ -603,5 +603,5 @@
    ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities
    rn_time_dmp   =  1.        !  Damping time scale in days
-   rn_time_dmp_out= 1.        !  Outflow damping time scale
+   rn_time_dmp_out = 1.        !  Outflow damping time scale
    nn_rimwidth   = 10         !  width of the relaxation zone
    ln_vol        = .false.    !  total volume correction (see nn_volctl parameter)
@@ -794,5 +794,5 @@
    nn_mld_uv   = 0         ! space interpolation of MLD at u- & v-pts (0=min,1=averaged,2=max)
    nn_conv     = 0         ! =1 no MLE in case of convection ; =0 always MLE
-   rn_rho_c_mle= 0.01      ! delta rho criterion used to calculate MLD for FK
+   rn_rho_c_mle = 0.01      ! delta rho criterion used to calculate MLD for FK
 /
 !-----------------------------------------------------------------------
@@ -857,5 +857,5 @@
    ln_dynadv_vec = .false. !  vector form - 2nd centered scheme
      nn_dynkeg     = 0        ! grad(KE) scheme: =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
@@ -1154,5 +1154,5 @@
    !                       !  or computed with Blanke' scheme (F)
    ln_ariane   = .true.    !  Input with Ariane tool convention(T)
-   ln_flo_ascii= .true.    !  Output with Ariane tool netcdf convention(F) or ascii file (T)
+   ln_flo_ascii = .true.    !  Output with Ariane tool netcdf convention(F) or ascii file (T)
 /
 !-----------------------------------------------------------------------
@@ -1170,5 +1170,5 @@
     nn_dct     = 15        !  time step frequency for transports computing
     nn_dctwri  = 15        !  time step frequency for transports writing
-    nn_secdebug= 112       !      0 : no section to debug
+    nn_secdebug = 112       !      0 : no section to debug
     !                      !     -1 : debug all section
     !                      !  0 < n : debug section number n
@@ -1187,7 +1187,7 @@
 &namnc4        !   netcdf4 chunking and compression settings            ("key_netcdf4")
 !-----------------------------------------------------------------------
-   nn_nchunks_i=   4       !  number of chunks in i-dimension
-   nn_nchunks_j=   4       !  number of chunks in j-dimension
-   nn_nchunks_k=   31      !  number of chunks in k-dimension
+   nn_nchunks_i =   4       !  number of chunks in i-dimension
+   nn_nchunks_j =   4       !  number of chunks in j-dimension
+   nn_nchunks_k =   31      !  number of chunks in k-dimension
    !                       !  setting nn_nchunks_k = jpk will give a chunk size of 1 in the vertical which
    !                       !  is optimal for postprocessing which works exclusively with horizontal slabs
@@ -1236,5 +1236,5 @@
    cn_altbiasfile = 'altbias.nc'     ! Altimeter bias input file name
    cn_sstbiasfiles = 'sstbias.nc'    ! SST bias input file name
-   cn_gridsearchfile='gridsearch.nc' ! Grid search file name
+   cn_gridsearchfile ='gridsearch.nc' ! Grid search file name
    rn_gridsearchres = 0.5            ! Grid search resolution
    rn_mdtcorr  = 1.61                ! MDT  correction
@@ -1292,5 +1292,5 @@
    !                       !  buffer blocking send or immediate non-blocking sends, resp.
    nn_buffer   =   0       !  size in bytes of exported buffer ('B' case), 0 no exportation
-   ln_nnogather=  .false.  !  activate code to avoid mpi_allgather use at the northfold
+   ln_nnogather =  .false.  !  activate code to avoid mpi_allgather use at the northfold
    jpni        =   0       !  jpni   number of processors following i (set automatically if < 1)
    jpnj        =   0       !  jpnj   number of processors following j (set automatically if < 1)
@@ -1316,5 +1316,5 @@
    ln_sto_eos  = .false.   ! stochastic equation of state
    nn_sto_eos  = 1         ! number of independent random walks
-   rn_eos_stdxy= 1.4       ! random walk horz. standard deviation (in grid points)
+   rn_eos_stdxy = 1.4       ! random walk horz. standard deviation (in grid points)
    rn_eos_stdz = 0.7       ! random walk vert. standard deviation (in grid points)
    rn_eos_tcor = 1440.     ! random walk time correlation (in timesteps)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SPITZ12/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SPITZ12/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/cfgs/SPITZ12/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                       SPITZ 1/12 configuration                     !!
@@ -390,5 +390,5 @@
 &namnc4        !   netcdf4 chunking and compression settings            ("key_netcdf4")
 !-----------------------------------------------------------------------
-   nn_nchunks_k=   75      !  number of chunks in k-dimension
+   nn_nchunks_k =   75      !  number of chunks in k-dimension
    !                       !  setting nn_nchunks_k = jpk will give a chunk size of 1 in the vertical which
    !                       !  is optimal for postprocessing which works exclusively with horizontal slabs
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/HTML_htlatex.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/HTML_htlatex.sh	(revision 10320)
+++ 	(revision )
@@ -1,11 +1,0 @@
-#!/bin/bash
-
-./inc/clean.sh
-./inc/build.sh
-
-mkdir -p html_htlatex
-cd tex_main
-htlatex NEMO_manual "NEMO_manual,2" "" "-d../html_htlatex/" "-shell-escape"
-cd -
-
-exit 0
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/HTML_latex2html.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/HTML_latex2html.sh	(revision 10320)
+++ 	(revision )
@@ -1,20 +1,0 @@
-#!/bin/bash
-
-./inc/clean.sh
-./inc/build.sh
-
-cd tex_main
-sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s/^/%/' \
-	../tex_sub/*.tex
-sed -i    's#\\subfile{#\\include{#g' \
-	NEMO_manual.tex
-latex2html -local_icons -no_footnode -split 4 -link 2 -mkdir -dir ../html_LaTeX2HTML 	\
-				$* 																								\
-	NEMO_manual
-sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s/^%//' \
-	../tex_sub/*.tex
-sed -i    's#\\include{#\\subfile{#g' \
-	NEMO_manual.tex
-cd -
-
-exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/PDF_creation.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/PDF_creation.sh	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/PDF_creation.sh	(revision 10321)
@@ -1,11 +1,34 @@
 #!/bin/sh
 
-./inc/clean.sh
-./inc/build.sh
 
-cd tex_main
-pdflatex -shell-escape NEMO_manual
-mv NEMO_manual.pdf ..
-cd -
+export opts='-shell-escape -interaction=nonstopmode'
+model='NEMO'
+
+clean() {
+    ## Delete latex build files
+    find latex -regextype posix-extended -regex ".*\.(aux|log|maf|mtc|out|toc).*" -exec rm {} \;
+
+    ## Remove 'minted' directories
+    find latex -type d -name '_minted*' -exec rm -r {} \;
+
+    ## HTML exports
+    find latex -type d -name 'html*'    -exec rm -r {} \;
+}
+
+build() {
+    cd latex/$1/main
+
+    latex     $opts              $1'_manual' > /dev/null
+    makeindex -s $1'_manual'.ist $1'_manual' > /dev/null
+    bibtex                       $1'_manual' > /dev/null
+    #latex     $opts              $1'_manual' > /dev/null
+    pdflatex  $opts              $1'_manual' > /dev/null
+
+    mv $1'_manual'.pdf ../../..
+    cd -
+}
+
+clean
+build    $model
 
 exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_check.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_check.sh	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_check.sh	(revision 10321)
@@ -0,0 +1,31 @@
+#!/bin/sh
+
+if [[ $* != '' ]]; then
+
+    if [[ $1 = 'all' ]]; then
+        models='NEMO SI3 TOP'
+    else
+        models=$1
+    fi
+
+else
+    models='NEMO'
+fi
+
+for model in $models; do
+    [[ $model =~ ^(SI3|TOP)$ ]] && continue
+    echo 'Namelists not included in the '$model' manual:'
+
+    for nlst in $( ls namelists ); do
+
+        if [[ ! $( grep "\\nlst{$nlst}" ./latex/$model/subfiles/*.tex ) ]]; then
+            printf "$nlst "
+        fi
+
+    done
+
+    echo
+
+done
+
+exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_update.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_update.sh	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/bin/nlsts_update.sh	(revision 10321)
@@ -0,0 +1,247 @@
+#! /bin/sh
+#
+#       usage for NEMO doc to create an update of the Namelists directory :
+# 1- delete the existing directory (You can also choose to save it somewhere) 
+#    rm -rf Namelists
+# 2- create the updated Namelists directory from the SHARED/namelist_ref :
+#    ./namelist_split.sh -i ../NEMOGCM/CONFIG/SHARED/namelist_ref -o Namelists
+#
+# .. _namelist_split.sh:
+#
+# =================
+# namelist_split.sh
+# =================
+#
+# ----------------
+# split a namelist
+# ----------------
+#
+# SYNOPSIS
+# ========
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i namelist -o dirout [-n]
+#
+# DESCRIPTION
+# ===========
+#
+# Split a namelist file (NEMO convention syntax) given in parameter
+# into files in a given output directory.
+#
+# .. option:: -i <input file (namelist)>
+# .. option:: -o <output directory>
+# .. option:: -n <numbered output files>
+#
+# Each file of the output directory is named after the *block* it contains.
+#
+# We assume here that the input file is written with this pattern of block:
+#
+# .. parsed-literal::
+#
+#    !---------------
+#    &nameblock
+#    !---------------
+#    var1 = val1
+#    ...
+#    varn = valn
+#    /
+#
+# If ``-n`` option is used, files in the directory output are named after
+# the number of the block it contains and the name of this block. This might
+# be useful to recombine blocks in the same order.
+#
+# EXAMPLES
+# ========
+#
+# To split the namelist NEMO ORCA2_LIM experiment 00 if you are in NEMO
+# working space :
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i CONFIG/ORCA2_LIM/EXP00/namelist -o /tmp/EXP00_namelist_split/
+#
+# To split the namelist under data directory with numbered files:
+#
+# .. code-block:: bash
+#
+#    namelist_split.sh -i ./data/namelist -o /tmp/EXP00_namelist_split/ -n
+#
+# Check can be made by concatenation of files in output directory if ``-n``
+# option have been used and comparison with original file :
+#
+# .. code-block:: bash
+#
+#    cat /tmp/EXP00_namelist_split/b???_* > /tmp/EXP00_namelist_rebuild
+#    sdiff -w80 ./data/namelist /tmp/EXP00_namelist_rebuild
+#
+# Output contains lines which are before the first block, after the last
+# block and lines between blocks.
+#
+# EVOLUTIONS
+# ==========
+#
+# $Id$
+#
+# - fplod 2008-08-11T08:56:44Z aedon.locean-ipsl.upmc.fr (Darwin)
+#
+#   * commentaires dans ce fichier en reStructuredText
+#     cf. reStructuredText_ and Docutils_
+#
+# .. _reStructuredText: http://docutils.sourceforge.net/rst.html
+# .. _Docutils: http://docutils.sourceforge.net/
+#
+# - fplod 2008-07-22T12:41:04Z aedon.locean-ipsl.upmc.fr (Darwin)
+#
+#   * creation with test on
+#     http://forge.ipsl.jussieu.fr/nemo/browser/trunk/CONFIG/ORCA2_LIM/EXP00/namelist revision 1151
+#-
+#
+system=$(uname)
+case "${system}" in
+    AIX|IRIX64)
+        echo " www : no specific posix checking"
+    ;;
+    *)
+        set -o posix
+    ;;
+esac
+unset system
+#
+command=$(basename ${0})
+log_date=$(date -u +"%Y%m%dT%H%M%SZ")
+#
+usage=" Usage : ${command} -i namelist -o dirout [-n]"
+#
+# default
+blocknum=0
+#
+minargcount=4
+if [ ${#} -lt ${minargcount} ]
+then
+    echo "eee : not enough arguments"
+    echo "${usage}"
+    exit 1
+fi
+#
+while [ ${#} -gt 0 ]
+do
+    case ${1} in
+        -i)
+            filein=${2}
+            shift
+        ;;
+        -o)
+            dirout=${2}
+            shift
+        ;;
+        -h)
+            echo "${usage}"
+            exit 0
+        ;;
+        -n)
+            blocknum=1
+        ;;
+        *)
+            # anything else
+            echo "eee : unknown option ${1}"
+            echo "eee : ${usage}"
+            exit 1
+        ;;
+    esac
+    # next flag
+    shift
+done
+unset usage
+#
+set -u
+#
+# check for filein
+if [ ! -r ${filein} ]
+then
+    echo "eee : ${filein} not accessible"
+    exit 1
+fi
+#
+# check for dirout
+# the idea is to prevent unwanted overwrite
+if [ -d ${dirout} ]
+then
+    echo "eee : ${dirout} already exist"
+    exit 1
+else
+    mkdir -p ${dirout}
+    if [ ${?} -ne 0 ]
+    then
+        echo "eee : cannot create ${dirout}"
+        exit 1
+    fi
+fi
+#
+# loop on each line of ${filein} ie the namelist to be split
+fileout=/dev/null
+begin=0
+if [ ${blocknum} -eq 1 ]
+then
+    iblock=0
+fi
+nbline=$(wc -l ${filein} | awk '{print $1}')
+il=1
+while [ ${il} -le ${nbline} ]
+do
+    line=$(sed -ne "${il},${il}p" ${filein})
+    # if current line start with "&", we can establish the name of output file
+    echo ${line} | grep -q "^&"
+    if [ ${?} -eq 0 ]
+    then
+        begin=1
+        # the form of this line is "&block   !"
+        block=${line#&}
+        block=${block%% *}
+        echo "iii : detection of the beginning of ${block}"
+        if [ ${blocknum} -eq 1 ]
+        then
+            iblock=$(( ${iblock} + 1))
+            fileout=${dirout}/b$(echo ${iblock} | awk '{printf "%3.3d", $1}')_${block}
+        else
+            fileout="${dirout}/${block}"
+        fi
+        # check for ${fileout}
+        if [ -f ${fileout} ]
+        then
+            echo "eee : ${fileout} already exists"
+            exit 1
+        fi
+        # write the previous line and the current line
+        echo "${memoline}" > ${fileout}
+        echo "${line}" >> ${fileout}
+    fi
+    # if current line contains "/" there will be no more lines to put in fileout
+    echo ${line} | grep -q "^/$"
+    if [ ${?} -eq 0 ]
+    then
+        echo "iii : detection of the end of ${block}"
+        echo "${line}" >> ${fileout}
+        fileout="/dev/null"
+    fi
+    # if current line is between "&" and "/", it should be written in fileout
+    # if current line is before the first &, it won't be written
+    if [ "${fileout}" != "/dev/null" ]
+    then
+        if [ ${begin} -eq 0 ]
+        then
+            echo "${line}" >> ${fileout}
+        fi
+    fi
+    # keep memory of this current line to use it if the next one is the
+    # beginning of a block
+    memoline=${line}
+    begin=0
+    # next line
+    il=$(( ${il} + 1 ))
+done
+#
+echo "iii : ${filein} is split in ${dirout}"
+#
+# end
+exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_htlatex.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_htlatex.sh	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_htlatex.sh	(revision 10321)
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+./inc/clean.sh
+./inc/build.sh
+
+mkdir -p html_htlatex
+cd tex_main
+htlatex NEMO_manual "NEMO_manual,2" "" "-d../html_htlatex/" "-shell-escape"
+cd -
+
+exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_latex2html.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_latex2html.sh	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/HTML_latex2html.sh	(revision 10321)
@@ -0,0 +1,20 @@
+#!/bin/bash
+
+./inc/clean.sh
+./inc/build.sh
+
+cd tex_main
+sed -i -e 's#\\documentclass#%\\documentclass#' -e '/{document}/ s/^/%/' \
+	../tex_sub/*.tex
+sed -i    's#\\subfile{#\\include{#g' \
+	NEMO_manual.tex
+latex2html -local_icons -no_footnode -split 4 -link 2 -mkdir -dir ../html_LaTeX2HTML 	\
+				$* 																								\
+	NEMO_manual
+sed -i -e 's#%\\documentclass#\\documentclass#' -e '/{document}/ s/^%//' \
+	../tex_sub/*.tex
+sed -i    's#\\include{#\\subfile{#g' \
+	NEMO_manual.tex
+cd -
+
+exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_coding_conv.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_coding_conv.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_coding_conv.tex	(revision 10321)
@@ -0,0 +1,599 @@
+\documentclass[a4paper]{article}
+\usepackage{type1cm} 
+\usepackage{times} 
+\usepackage{color} 
+\usepackage{rotating} 
+\usepackage{color} 
+\usepackage{framed} 
+\usepackage{makeidx} 
+\graphicspath{{figures/}}
+
+%%%%%%%
+\pagestyle{empty} 
+\setlength{\leftmargin}{1 cm} 
+\setlength{\rightmargin}{1 cm} 
+\setlength{\oddsidemargin}{0 cm} 
+\setlength{\evensidemargin}{0 cm} 
+\setlength{\topmargin}{-1cm} 
+\setlength{\textwidth}{16 cm} 
+\setlength{\textheight}{25cm} 
+
+%%%%%%%%%essai plus jolis from NEMO book
+\usepackage{fancyhdr}
+
+\pagestyle{fancy}
+%\usepackage[colorlinks=true]{hyperref} %%create link
+ 
+\makeindex %% run first makeindex NEMO_coding.conv.idx NEMO_coding.conv.ist
+		
+\begin{document}
+
+
+\title{ 
+\includegraphics[width=0.3\textwidth]{NEMO_logo_Black} \\
+\vspace{1.0cm}
+\rule{345pt}{1.5pt} \\
+\vspace{0.45cm}
+ {\Huge NEMO coding conventions} 
+\rule{345pt}{1.5pt} \\ 
+{\small  -- version 3 --}   }
+%\title{NEMO coding conventions}
+\author{NEMO System Team }
+\date{March 2011}
+
+
+\maketitle
+
+\newpage
+
+\tableofcontents   
+         
+\newpage
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Introduction}
+This document describes conventions\index{conventions} used in NEMO coding and suggested for its development. The objectives are to offer a guide to all readers of the NEMO code, and to facilitate the work of all the developers, including the validation of their developments, and eventually the implementation of these developments within the NEMO platform. \\
+A first approach of these rules can be found in the code in $NEMO/OPA\_SRC/module\_example$ where all the basics coding conventions are illustrated. More details can be found below.\\
+This work is based on the coding conventions in use for the Community Climate System Model, \footnote { http://www.cesm.ucar.edu/working\_groups/Software/dev\_guide/dev\_guide/node7.html }
+ the previous version of this document (``FORTRAN coding standard in the OPA System'') and the expertise of the NEMO System Team which can be contacted for further information ($nemo\_st@locean-ipsl.upmc.fr$)
+After a general overview below, this document will describe :
+\begin{itemize} 
+\item The style rules, i.e. the syntax, appearance and naming conventions chosen to improve readability of the code;
+\item The content rules, i.e. the conventions to improve the reliability of the different parts of the code;
+\item The package rules to go a step further by improving the reliability of the whole and interfaces between routines and modules.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Overview and general conventions}
+NEMO has several different components: ocean dynamics ($OPA\_SRC$), sea-ice ($LIM\_SRC$), ocean biogeochemistry\- ($TOP\_SRC$), linear-tangent and adjoint of the dynamics ($TAM$)É each of them corresponding to a directory.
+In each directory, one will find some FORTRAN files and/or subdirectories, one per functionality of the code: $BDY$ (boundaries), $DIA$ (diagnostics), $DOM$ (domain), $DYN$ (dynamics), $LDF$ (lateral diffusion), etc...\\
+All name are chosen to be as self-explanatory as possible, in English, all prefixes are 3 digits.\\
+English is used for all variables names, comments, and documentation. \\
+Physical units are MKS. The only exception to this is the temperature, which is expressed in degrees Celsius, except in bulk formulae and part of LIM sea-ice model where it is in Kelvin. See $DOM/phycst.F90$ files for conversions.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Architecture}
+Within each directory, organisation of files is driven by ÒorthogonalityÓ\index{orthogonality}, i.e. one functionality of the code is intended to be in one and only one directory, and one module and all its related routines are in one file.
+The functional modules\index{module} are:
+\begin{itemize} 
+\item SBC		surface module 
+\item IOM		management of the I/O 
+\item NST		interface to AGRIF (nesting model) for dynamics and biogeochemistry 
+\item OBC, BDY	management of structured and unstructured open boundaries 
+\item C1D		1D (vertical) configuration for dynamics, sea-ice and biogeochemistry 
+\item OFF		off-line module: passive tracer or biogeochemistry alone 
+\item CFG 		tutorial and reference configurations 
+\item DOC		documentation 
+\end{itemize}
+
+For example, the file $domain.F90$ contains the module $domain$ and all the subroutines related to this module ($ dom\_init, dom\_nam, dom\_ctl$).
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Style rules}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Argument list format}
+Routine argument lists will contain a maximum 5 variables\index{variable} per line, whilst continuation lines can be used. 
+This applies both to the calling routine and the dummy argument list in the routine being called. The purpose is to simplify matching up the arguments between caller and callee. 
+
+\begin{verbatim}
+SUBROUTINE tra_adv_eiv( kt, pun, pvn, pwn )
+
+      CALL tra_adv_eiv( kt, zun, zvn, zwn )
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Array syntax}
+Except for long loops (see below), array notation should be used if possible. To improve readability the array shape must be shown in brackets, e.g.: 
+\begin{verbatim}
+onedarraya(:) = onedarrayb(:) + onedarrayc(:) 
+twodarray (:,:) = scalar * anothertwodarray(:,:) 
+\end{verbatim}
+When accessing sections of arrays, for example in finite difference equations, do so by using the triplet notation on the full array, e.g.:
+\begin{verbatim}
+twodarray(:,2:len2) = scalar                      & 
+   &                * ( twodarray2(:,1:len2-1 )   & 
+   &                -   twodarray2(:,2:len2 ) ) 
+\end{verbatim}   
+For long, complicated loops, explicitly indexed loops should be preferred. In general when using this syntax, the order of the loops indices should reflect the following scheme (for best usage of data locality):
+\begin{verbatim}
+DO jk = 1, jpk 
+   DO jj = 1, jpj 
+      DO ji = 1, jpi 
+         array(ji,jj,jk) = ... 
+      END DO 
+   END DO 
+END DO 
+\end{verbatim}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Case}
+All FORTRAN keywords are in capital : \begin {verbatim} DIMENSION, WRITE, DO, END DO, NAMELIST \end{verbatim} 
+All other parts of the NEMO code will be written in lower case.	
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Comments}
+Comments in the code are useful when reading the code and changing or developing it. \\
+The full documentation and detailed explanations are to be added in the reference manual (TeX files, aside from the code itself). \\
+In the code, the comments should explain variable content and describe each computational step.\\
+Comments in the header start with ``!!''. For more details on the content of the headers, see ÒContent rules/HeadersÓ in this document.\\
+Comments in the code start with ``!''.\\
+All comments are indented (3, 6, or 9 É blank spaces).\\
+Short comments may be included on the same line as executable code, and an additional line can be used with proper alignment. For example: 
+\begin{verbatim}
+      zx = zx *zzy   ! Describe what is going on and if it is 
+      !              ! too long use another Ô!Õ for proper 
+      !              ! alignment with automatic indentation 
+\end{verbatim}      
+More in-depth comments should be written in the form: 
+\begin{verbatim}
+!   Check of some namelist values
+\end{verbatim}         
+or 
+\begin{verbatim}    
+!
+!         !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!         !  Bottom boundary condition on tke
+!         !<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+!
+\end{verbatim}    
+Key features of this style are 1) it starts with a "!" in the column required for proper indentation, 2) the text is offset above and below by a blank line or a content line built for underlying. 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Continuation lines}
+Continuation lines can be used with precise alignment for readability. For example: 
+\begin{verbatim}   
+avmu(ji,jj,jk) = avmu(ji,jj,jk) * ( un(ji,jj,jk-1) - un(ji,jj,jk) )   &
+   &                            * ( ub(ji,jj,jk-1) - ub(ji,jj,jk) )   &
+   &           / (  fse3uw_n(ji,jj,jk)         &
+   &              * fse3uw_b(ji,jj,jk) )
+\end{verbatim}    
+Code lines, which are continuation lines of assignment statements, must begin to the right of the column of the assignment operator. Due to the possibility of automatic indentation in some editor (emacs for example), use a ``\&'' as first character of the continuing lines to maintain the alignment. 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Declaration of arguments and local variables}
+
+In a routine, input arguments and local variables are declared 1 per line, with a comment field on the same line as the declaration. Multiple comment lines describing a single variable are acceptable if needed. For example: 
+\begin{verbatim}  
+INTEGER             ::   kstp   ! ocean time-step index
+\end{verbatim}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{F90 Standard}
+NEMO software adheres to the FORTRAN 95 language standard and does not rely on any specific language or vendor extensions.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Free-Form Source}
+Free-form source will be used. The F90/95 standard allows lines of up to 132 characters, but a self-imposed limit of 80 should enhance readability, or print source files with two columns per page. Multi-line comments that extend to column 100 are unacceptable.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Indentation}
+Code as well as comment lines within loops, if-blocks, continuation lines, MODULE or SUBROUTINE statements will be indented 3 characters for readability. (except for CONTAINS that remains at first column) 
+\begin{verbatim}  
+MODULE mod1 
+   REAL(wp) xx 
+CONTAINS 
+   SUBROUTINE sub76( px, py, pz, pw, pa,   & 
+      &              pb, pc, pd, pe      ) 
+      <instruction> 
+   END SUBROUTINE sub76 
+END MODULE mod1 
+\end{verbatim}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Loops}
+Loops, if explicit, should be structured with the do-end do construct as opposed to numbered loops. Nevertheless non-numeric labels can be used for a big iterative loop of a recursive algorithm. In the case of a long loop, a self-descriptive label can be used (i.e. not just a number).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: files}
+A file containing a module will have the same name as the module it contains (because dependency rules used by "make" programs are based on file names).
+\footnote{For example, if routine A "USE"s module B, then "make" must be told of the dependency relation which requires B to be compiled before A. If one can assume that module B resides in file B.o, building a tool to generate this dependency rule (e.g. A.o: B.o) is quite simple. Put another way, it is difficult (to say nothing of CPU-intensive) to search an entire source tree to find the file in which module B resides for each routine or module which "USE"s B.}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: modules}
+Use a meaningful English name and the ``3 letters'' naming convention: first 3 letters for the code section, and last 3 to describe the module. For example, zdftke, where ``zdf'' stands for vertical diffusion, and ``tke'' for turbulent kinetic energy. 
+\\
+Note that by implication multiple modules are not allowed in a single file. 
+The use of common blocks is deprecated in Fortran 90 and their use in NEMO is strongly discouraged. Modules are a better way to declare static data. Among the advantages of modules is the ability to freely mix data of various types, and to limit access to contained variables through the use of the ONLY and PRIVATE attributes. 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Naming Conventions: variables}
+All variable should be named as explicitly as possible in English. The naming convention concerns prefix letters of these name, in  order to identify the variable type and status.\\
+Never use a FORTRAN keyword as a routine or variable name. \\
+The table below lists the starting letter(s) to be used for variable naming, depending on their type and status:
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]
+\begin{center}
+\begin{tabular}{|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|p{50pt}|}
+\hline  Type \par / Status &   integer&   real&   logical &   character&   double \par precision&   complex \\  
+\hline
+public  \par or  \par module variable& 
+\textbf{m n} \par \textit{but not } \par \textbf{nn\_}& 
+\textbf{a b e f g h o} \textbf{q} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& 
+\textbf{l} \par \textit{but not} \par \textbf{lp ld ll ln\_}& 
+\textbf{c} \par \textit{but not} \par \textbf{cp cd cl cn\_}& 
+\textbf{d} \par \textit{but not} \par \textbf{dp dd dl dn\_}& 
+\textbf{y} \par \textit{but not} \par \textbf{yp yd yl} \\
+\hline
+dummy \par argument& 
+\textbf{k} \par \textit{but not} \par \textbf{kf}& 
+\textbf{p} \par \textit{but not}  \par \textbf{pp pf}& 
+\textbf{ld}& 
+\textbf{cd}& 
+\textbf{dd}& 
+\textbf{yd} \\
+\hline
+local \par variable& 
+\textbf{i}& 
+\textbf{z}& 
+\textbf{ll}& 
+\textbf{cl}& 
+\textbf{cd}& 
+\textbf{yl} \\
+\hline
+loop \par control& 
+\textbf{j} \par \textit{but not } \par \textbf{jp}& 
+& 
+& 
+& 
+& 
+ \\
+\hline
+parameter& 
+\textbf{jp}& 
+\textbf{pp}& 
+\textbf{lp}& 
+\textbf{cp}& 
+\textbf{dp}& 
+\textbf{yp} \\
+\hline
+
+namelist&
+\textbf{nn\_}& 
+\textbf{rn\_}& 
+\textbf{ln\_}& 
+\textbf{cn\_}& 
+\textbf{dn\_}& 
+\\
+\hline
+CPP \par macro& 
+\textbf{kf}& 
+\textbf{sf} \par & 
+& 
+& 
+& 
+ \\
+\hline
+\end{tabular}
+\label{tab1}
+\end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Operators}
+Use of the operators $<, >, <=, >=, ==, /= $ is strongly recommended instead of their deprecated counterparts, $lt., .gt., .le., .ge., .eq., and .ne. $ The motivation is readability. In general use the notation: \\
+$<Blank><Operator><Blank>$
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Pre processor}
+Where the use of a language pre-processor is required, it will be the C pre-processor (cpp).\\
+The cpp key is the main feature used, allowing to ignore some useless parts of the code at compilation step. \\
+The advantage is to reduce the memory use; the drawback is that compilation of this part of the code isn't checked. \\
+The cpp key feature should only be used for a few limited options, if it reduces the memory usage. In all cases, a logical variable and a FORTRAN $IF$ should be preferred.
+When using a cpp key $key\_optionname$, a corresponding logical variable $lk\_optionname$ should be declared to allow FORTRAN $IF$ tests in the code and  a FORTRAN module with the same name (i.e. $optionname.F90$) should
+ be defined. This module is the only place where a ``\#if defined'' command appears, selecting either the whole FORTRAN code or a dummy module. For example, the TKE vertical physics, the module name is $zdftke.F90$, the CPP key is $key\_zdftke$ and the associated logical is $lk\_zdftke$. 
+
+The following syntax:
+\begin{verbatim} 
+#if defined key_optionname 
+!! Part of code conditionally compiled if cpp key key_optionname is active
+#endif
+\end{verbatim} 
+Is to be used rather than the \#ifdef abbreviate form since it may have conflicts with some Unix scripts.
+
+Tests on cpp keys included in NEMO at compilation step:
+\begin{itemize}
+\item The CPP keys used are compared to the previous list of cpp keys (the compilation will stop if trying to specify a Ònon-existing keyÓ)
+\item If a change occurs in the CPP keys used for a given experiment, the whole compilation phase is done again.
+\end{itemize}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Content rules}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Configurations}
+The configuration defines the domain and the grid on which NEMO is running. It may be useful to associate a cpp key and some variables to a given configuration, although the part of the code changed under each of those keys should be minimized. As an example, the "ORCA2" configuration (global ocean, 2 degrees grid size) is associated with the cpp key $key\_orca2$ for which 
+\begin{verbatim} 
+cp_cfg = "orca"
+jp_cfg = 2
+\end{verbatim} 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Constants}
+Physical constants (e.g. pi, gas constants) must never be hardwired into the executable portion of a code. Instead, a mnemonically named variable or parameter should be set to the appropriate value, in the setup routine for the package\index{package}. We realize than many parameterizations rely on empirically derived constants or fudge factors, which are not easy to name. In these cases it is not forbidden to leave such factors coded as "magic numbers" buried in executable code, but comments should be included referring to the source of the empirical formula. Hard-coded numbers should never be passed through argument lists. 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Declaration for variables and constants}
+
+\subsubsection{Rules :}
+Variables used as constants should be declared with attribute PARAMETER and used always without copying to local variables, inorder to prevent from using different values for the same constant or changing it accidentally. 
+\begin{itemize}
+\item Usage of the DIMENSION statement or attribute is required in declaration statements
+\item The ``::'' notation is quite useful to show that this program unit declaration part is  written in standard FORTRAN syntax, even if there are no attributes to clarify the  declaration section. Always use the notation $<$blank$>$::$<$three blanks$>$ to improve readability. 
+\item Declare the length of a character variable using the CHARACTER (len=xxx) syntax
+\footnote { The len specifier is important because it is possible to have several kinds for characters  (e.g. Unicode using two bytes per character, or there might be a different kind for Japanese e.g. NEC). }
+
+\item For all global data (in contrast to module data, that is all data that can be access by other module) must be accompanied with a comment field  on the same line. 
+\footnote {This allows a easy research of where and how a variable is declared using the unix command: ``grep var *90 |grep !:''. }
+\\
+For example:
+\begin{verbatim}
+REAL(wp), DIMENSION(jpi,jpj,jpk) ::  ua  &  !: i-horizontal velocity (m/s) 
+\end{verbatim}
+\end{itemize}
+
+\subsubsection{Implicit None:}
+ All subroutines and functions will include an IMPLICIT NONE statement. 
+Thus all variables must be explicitly typed. It also allows the compiler to detect typographical errors in variable names. 
+For modules, one IMPLICIT NONE statement in the modules definition section is needed. This also removes the need to have IMPLICIT NONE statements in any routines that are CONTAIN'd in the module.
+Improper data initialisation is another common source of errors. 
+\footnote{A variable could contain an initial value you did not expect. This can happen for several reasons, e.g. the variable has never been assigned a value, its value is outdated, memory has been allocated for a pointer but you have forgotten to initialise the variable pointed to.} 
+To avoid problems, initialise variables as close as possible to where they are first used. 
+
+\subsubsection{Attributes:}
+$PRIVATE / PUBLIC$ : 
+All resources of a module are $PUBLIC$ by default.
+A reason to store multiple routines and their data in a single module is that the scope of the data defined in the module can be limited to the routines which are in the same module. This is accomplished with the $PRIVATE$ attribute.\\
+$INTENT$ :
+All dummy arguments of a routine must include the $INTENT$ clause in their declaration in order to improve control of variables in routine calls. 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Headers}
+Prologues are not used in NEMO for now, although it may become an interesting tool in combination with ProTeX auto documentation script in the future. 
+Rules to code the headers and layout of a module or a routine are illustrated in the example module available with the code : {\it NEMO/OPA\_SRC/module\_example}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Interface blocks}
+Explicit interface blocks are required between routines if optional or keyword arguments are to be used. They also allow the compiler to check that the type, shape and number of arguments specified in the CALL are the same as those specified in the subprogram itself. FORTRAN 95 compilers can automatically provide explicit interface blocks  for routines contained in a module. 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{I/O Error Conditions}
+I/O statements which need to check an error condition will use the $iostat=<integer variable>$ construct instead of the outmoded end= and err=. \\
+Note that a 0 value means success, a positive value means an error has occurred, and a negative value means the end of record or end of file was encountered. 
+ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{PRINT - ASCII output files}
+Output listing and errors are directed to $numout$ logical unit =6 and produces a file called $ocean.output$  (use ln\_prt to have one output per process in  MPP). Logical $lwp$ variable allows for less verbose outputs.
+To output an error from a routine, one can use the following template:
+\begin{verbatim}
+      IF( nstop /= 0 .AND. lwp ) THEN   ! error print
+         WRITE(numout,cform_err)
+         WRITE(numout,*) nstop, ' error have been found'
+      ENDIF
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Precision}
+Parameterizations should not rely on vendor-supplied flags to supply a default floating point precision or integer size. The F95$ KIND$ feature should be used instead. In order to improve portability between 32 and 64 bit platforms, it is necessary to make use of kinds by using a specific module ($OPA\_SRC/par\_kind.F90$)  declaring the "kind definitions" to obtain the required numerical precision and range as well as the size of INTEGER. It should be noted that numerical constants need to have a suffix of \_$kindvalue$ to have the according size. \\
+Thus $wp$ being the "working precision" as declared in $OPA\_SRC/par\_kind.F90$, declaring real array $zpc$ will take the form:
+\begin{verbatim}
+      REAL(wp), DIMENSION(jpi,jpj,jpk) ::  zpc      ! power consumption
+\end{verbatim}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Structures}
+The TYPE structure allowing to declare some variables is more often used in NEMO, especially in the modules dealing with reading fields, or interfaces.For example
+\begin{verbatim}
+ ! Definition of a tracer as a structure
+      TYPE PTRACER
+         CHARACTER(len = 20)  :: sname  !: short name
+         CHARACTER(len = 80 ) :: lname  !: long name
+         CHARACTER(len = 20 ) :: unit   !: unit
+         LOGICAL              :: lini   !: read in a file or not
+         LOGICAL              :: lsav   !: ouput the tracer or not
+      END TYPE PTRACER
+
+      TYPE(PTRACER) , DIMENSION(jptra) :: tracer
+\end{verbatim}
+ 
+ Missing rule on structure name??
+ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Packages coding rules}
+ 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Bounds checking}
+NEMO is able to run when an array bounds checking option is enabled (provided the cpp key $key\_vectopt\_loop$ is not defined). \\
+Thus, constructs of the  following form are disallowed: 
+\begin{verbatim}
+REAL(wp) :: arr(1) 
+\end{verbatim}
+where "arr" is an input argument into which the user wishes to index beyond 1. Use of the (*) construct in array dimensioning  is forbidden also because it effectively disables array bounds checking.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Communication}
+A package should refer only to its own modules and subprograms and to those intrinsic functions included in the Fortran standard.\\
+All communication with the package will be through the argument list or namelist input.
+\footnote { The point behind this rule is that packages should not have to know details of the surrounding model data structures, or the names of variables outside of the package. A notable exception to this rule is model resolution parameters. The reason for the exception is to allow compile-time array sizing inside the package. This is often important for efficiency.}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Error conditions}
+When an error condition occurs inside a package, a message describing what went wrong will be printed (see PRINT - ASCII output files). The name of the routine in which the error occurred must be included. It is acceptable to terminate execution within a package, but the developer may instead wish to return an error flag through the argument list, see $stpctl.F90$.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Memory management}
+
+The main action is to identify and declare which arrays are PUBLIC and
+which are PRIVATE.\\ As of version 3.3.1 of NEMO, the use of static
+arrays (size fixed at compile time) has been deprecated.  All module
+arrays are now declared ALLOCATABLE and allocated in either the
+$<$module\_name$>$\_alloc() or $<$module\_name$>$\_init()
+routines. The success or otherwise of each ALLOCATE must be checked
+using the $Stat=<integer\ variable>$ optional argument.\\
+
+In addition to arrays contained within modules, many routines in NEMO
+require local, ``workspace'' arrays to hold the intermediate results
+of calculations. In previous versions of NEMO, these arrays were
+declared in such a way as to be automatically allocated on the stack
+when the routine was called.  An example of an automatic array is:
+\begin{verbatim}
+SUBROUTINE sub(n) 
+   REAL :: a(n) 
+   ... 
+END SUBROUTINE sub 
+\end{verbatim}
+The downside of this approach is that the program will crash if it
+runs out of stack space and the reason for the crash might not be
+obvious to the user.
+
+Therefore, as of version 3.3.1, the use of automatic arrays is
+deprecated. Instead, a new module, ``wrk\_nemo,'' has been introduced
+which contains 1-,2-,3- and 4-dimensional workspace arrays for use in
+subroutines. These workspace arrays should be used in preference to
+declaring new, local (allocatable) arrays whenever possible. The only
+exceptions to this are when workspace arrays with lower bounds other
+than 1 and/or with extent(s) greater than those in the {\it wrk\_nemo}
+module are required.\\
+
+The 2D, 3D and 4D workspace arrays in {\it wrk\_nemo} have extents
+$jpi$, $jpj$, $jpk$ and $jpts$ ($x$, $y$, $z$ and tracers) in the first,
+second, third and fourth dimensions, respectively. The 1D arrays are
+allocated with extent MAX($jpi\times jpj, jpk\times jpj, jpi\times
+jpk$).\\
+
+The REAL (KIND=$wp$) workspace arrays in {\it wrk\_nemo} are named
+e.g. $wrk\_1d\_1$, $wrk\_4d\_2$ etc. and should be accessed by USE'ing
+the {\it wrk\_nemo} module. Since these arrays are available to any
+routine, some care must be taken that a given workspace array is not
+already being used somewhere up the call stack. To help with this,
+{\it wrk\_nemo} also contains some utility routines; {\it
+  wrk\_in\_use()} and {\it wrk\_not\_released()}. The former first
+checks that the requested arrays are not already in use and then sets
+internal flags to show that they are now in use. The {\it
+  wrk\_not\_released()} routine un-sets those internal flags. A
+subroutine using this functionality for two, 3D workspace arrays named
+$zwrk1$ and $zwrk2$ will look something like:
+\begin{verbatim}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released 
+   USE wrk_nemo, ONLY: zwrk1 => wrk_3d_5, zwrk2 => wrk_3d_6
+   !
+   IF(wrk_in_use(3, 5,6)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   ... 
+   ...
+   IF(wrk_not_released(3, 5,6)THEN
+      CALL ctl_stop('sub: failed to release workspace arrays.')
+   END IF
+   !
+END SUBROUTINE sub 
+\end{verbatim}
+The first argument to each of the utility routines is the
+dimensionality of the required workspace (1--4). Following this there
+must be one or more integers identifying which workspaces are to be
+used/released.
+Note that, in the interests of keeping the code as simple as possible,
+there is no use of POINTERs etc. in the {\it wrk\_nemo}
+module. Therefore it is the responsibility of the developer to ensure
+that the arguments to {\it wrk\_in\_use()} and {\it
+  wrk\_not\_released()} match the workspace arrays actually being used
+by the subroutine.\\
+
+If a workspace array is required that has extent(s) less than those of
+the arrays in the {\it wrk\_nemo} module then the advantages of
+implicit loops and bounds checking may be retained by defining a
+pointer to a sub-array as follows:
+\begin{verbatim}
+SUBROUTINE sub()
+   USE wrk_nemo, ONLY: wrk_in_use, wrk_not_released 
+   USE wrk_nemo, ONLY: wrk_3d_5
+   !
+   REAL(wp), DIMENSION(:,:,:), POINTER :: zwrk1
+   !
+   IF(wrk_in_use(3, 5)THEN
+      CALL ctl_stop('sub: requested workspace arrays unavailable.')
+      RETURN
+   END IF
+   !
+   zwrk1 => wrk_3d_5(1:10,1:10,1:10)
+   ... 
+END SUBROUTINE sub 
+\end{verbatim}
+Here, instead of ``use associating'' the variable $zwrk1$ with the
+array $wrk\_3d\_5$ (as in the first example), it is explicitly
+declared as a pointer to a 3D array. It is then associated with a
+sub-array of $wrk\_3d\_5$ once the call to {\it wrk\_in\_use()} has
+completed successfully. Note that in F95 (to which NEMO conforms) it
+is not possible for either the upper or lower array bounds of the
+pointer object to differ from those of the target array.\\
+
+In addition to the REAL (KIND=$wp$) workspace arrays, {\it wrk\_nemo}
+also contains 2D integer arrays and 2D REAL arrays with extent ($jpi$,
+$jpk$), {\it i.e.} $xz$. The utility routines for the integer
+workspaces are {\it iwrk\_in\_use()} and {\it iwrk\_not\_released()}
+while those for the $xz$ workspaces are {\it wrk\_in\_use\_xz()}
+and {\it wrk\_not\_released\_xz()}.
+
+Should a call to one of the {\it wrk\_in\_use()} family of utilities
+fail, an error message is printed along with a table showing which of
+the workspace arrays are currently in use. This should enable the
+developer to choose alternatives for use in the subroutine being
+worked on.\\
+
+When compiling NEMO for production runs, the calls to {\it
+  wrk\_in\_use()}/{\it wrk\_not\_released()} can be reduced to stubs
+that just return $.$FALSE$.$ by setting the cpp key
+{\it key\_no\_workspace\_check}. These stubs may then be inlined (and
+thus effectively removed altogether) by setting appropriate compiler
+flags (e.g. ``-finline'' for the Intel compiler or ``-Q'' for the IBM
+compiler).
+
+ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Optimisation}
+
+Considering the new computer architecture, optimisation cannot be considered independently from the computer type.
+In NEMO, portability is a priority, before any too specific optimisation.
+Some tools are available to help: \\
+For vector computers: 
+\begin{itemize} 
+\item  using $key\_vectopt\_loop$ allows to unroll a loop
+\end{itemize}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Package attribute: $PRIVATE, PUBLIC, USE, ONLY$}
+Module variables and routines should be encapsulated by using the PRIVATE attribute. What shall be used outside the module can be declared PUBLIC instead. Use USE with the ONLY attribute to specify which of the variables, type definitions etc. defined in a module are to be made available to the using routine. 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection {Parallelism: using MPI}
+NEMO is written in order to be able to run on one processor, or on one or more using MPI (i.e. activating the cpp key $key\_mpp\_mpi$. The domain decomposition divides the global domain in cubes (see NEMO reference manual). Whilst coding a new development, the MPI compatibility has to be taken in account (see $LBC/lib\_mpp.F90$) and should be tested. By default, the $x$-$z$ part of the decomposition is chosen to be as square as possible. However, this may be overriden by specifying the number of subdomains in latitude and longitude in the nammpp section of the namelist file.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Features to be avoided}
+
+The code must follow the current standards of FORTRAN and ANSI C.  In particular, the code should not produce any WARNING at compiling phase, so that users can be easily alerted of potential bugs when some appear in their new developments. ). 
+Below is a list of features to avoid:
+\begin{itemize}
+\item COMMON blocks (use the declaration part of MODULEs instead)
+\item EQUIVALENCE (use POINTERs or derived data types instead to form data structures)
+\item Assigned and computed GOTOs (use the CASE construct instead)
+\item Arithmetic IF statements ( use the block IF, ELSE, ELSEIF, ENDIF or SELECT CASE construct instead) 
+\item Labeled DO constructs  (use unlabeled END DO instead) 
+\item FORMAT statements (use character parameters or explicit format- specifiers inside the READ or WRITE statement instead)
+\item GOTO and CONTINUE statement (use IF, CASE, DO WHILE, EXIT or CYCLE statements or a contained 
+\item PAUSE 
+\item ENTRY statements: a subprogram must only have one entry point. 
+\item RETURN Ð it is obsolete and so not necessary at the end of program units
+\item STATEMENT FUNCTION 
+ \item Avoid functions with side effects.
+\footnote{ First, the code is easier to understand, if you can rely on the rule that functions don't change their arguments, second, some compilers generate more efficient code for PURE (in FORTRAN 95 there are the attributes PURE and ELEMENTAL) functions, because they can store the arguments in different places. This is especially important on massive parallel and as well on vector machines. }
+\item DATA and BLOCK DATA - (use initialisers)
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% \printindex
+% \input NEMO_coding.conv.ind
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.bib	(revision 10321)
@@ -0,0 +1,3361 @@
+This file was created with JabRef 2.2.
+Encoding: UTF8
+
+@STRING{AP = {Academic Press}}
+
+@STRING{AREPS = {Annual Review of Earth Planetary Science}}
+
+@STRING{ARFM = {Annual Review of Fluid Mechanics}}
+
+@STRING{ASL = {Atmospheric Science Letters}}
+
+@STRING{AW = {Addison-Wesley}}
+
+@STRING{CP = {Clarendon Press}}
+
+@STRING{CD = {Clim. Dyn.}}
+
+@STRING{CUP = {Cambridge University Press}}
+
+@STRING{CSR = {Cont. Shelf Res.}}
+
+@STRING{D = {Dover Publications}}
+
+@STRING{DAO = {Dyn. Atmos. Ocean}}
+
+@STRING{DSR = {Deep-Sea Res.}}
+
+@STRING{E = {Eyrolles}}
+
+@STRING{EFM ={Environ. Fluid Mech.}}
+
+@STRING{GRL = {Geophys. Res. Let.}}
+
+@STRING{I = {Interscience}}
+
+@STRING{JAOT = {J. Atmos. Ocean Tech.}}
+
+@STRING{JAS = {J. Atmos. Sc.}}
+
+@STRING{JC = {J. Climate}}
+
+@STRING{JCP = {J. Comput. Phys.}}
+
+@STRING{JFM = {J. Fluid Mech.}}
+
+@STRING{JGR = {J. Geophys. Res}}
+
+@STRING{JHUP = {The Johns Hopkins University Press}}
+
+@STRING{JMR = {J. Mar. Res.}}
+
+@STRING{JMS = {J. Mar. Sys.}}
+
+@STRING{JMSJ = {J. Met. Soc. Japan}}
+
+@STRING{JPO = {J. Phys. Oceanogr.}}
+
+@STRING{JSC = {J. Supercomputing.}}
+
+@STRING{JWS = {John Wiley and Sons}}
+
+@STRING{M = {Macmillan}}
+
+@STRING{MGH = {McGraw-Hill}}
+
+@STRING{MWR = {Mon. Wea. Rev.}}
+
+@STRING{Nature = {Nat.}}
+
+@STRING{NH = {North-Holland}}
+
+@STRING{Ocean = {Oceanology}}
+
+@STRING{OD = {Ocean Dyn.}}
+
+@STRING{OM = {Ocean Modelling}}
+
+@STRING{OS = {Ocean Sc.}}
+
+@STRING{OUP = {Oxford University Press}}
+
+@STRING{PH = {Prentice-Hall}}
+
+@STRING{PO = {Prog. Oceangr.}}
+
+@STRING{PP = {Pergamon Press}}
+
+@STRING{PRSL = {Proceedings of the Royal Society of London}}
+
+@STRING{QJRMS = {Quart. J. Roy. Meteor. Soc.}}
+
+@STRING{Recherche = {La Recherche}}
+
+@STRING{RGSP = {Rev. Geophys. Space Phys.}}
+
+@STRING{Science = {Science}}
+
+@STRING{SV = {Springer-Verlag}}
+
+@STRING{Tellus = {Tellus}}
+
+%% No dash for repeated names
+@IEEEtranBSTCTL{IEEEexample:BSTcontrol,
+  CTLdash_repeated_names = "no"
+}
+
+@ARTICLE{Adcroft_Campin_OM04,
+  author = {A. Adcroft and J.-M. Campin},
+  title = {Re-scaled height coordinates for accurate representation of free-surface flows in ocean circulation models},
+  journal = OM,
+  year = {2004},
+  volume = {7},
+  pages = {269--284},
+  doi = {10.1016/j.ocemod.2003.09.003},
+}
+
+@ARTICLE{Arakawa1966,
+  author = {A. Arakawa},
+  title = {Computational design for long term numerical integration of the equations 
+    of fluid motion, two-dimensional incompressible flow, Part. I.},
+  journal = JCP,
+  year = {1966},
+  volume = {I},
+  pages = {119--149}
+}
+
+@ARTICLE{Arakawa_Hsu_MWR90,
+  author = {A. Arakawa and Y.-J. G. Hsu},
+  title = {Energy Conserving and Potential-Enstrophy Dissipating Schemes for the Shallow Water Equations},
+  journal = MWR,
+  year = {1990},
+  volume = {118},  number = {10},
+  pages = {1960--1969},
+}
+
+@ARTICLE{Arakawa_Lamb_MWR81,
+  author = {Arakawa, Akio and Lamb, Vivian R.},
+  title = {A Potential Enstrophy and Energy Conserving Scheme for the Shallow
+           Water Equations},
+  journal = MWR,
+  year = {1981},
+  volume = {109},  number = {1},
+  pages = {18--36}
+}
+
+@ARTICLE{Arbic2004,
+  author = {B. Arbic and S. Garner and R. Hallberg and H. Simmons},
+  title = {The accuracy of surface elevations in forward global barotropic and baroclinic tide models},
+  journal = DSR,
+  year = {2004},
+  volume = {51},
+  pages = {3069-3101}
+}
+
+@ARTICLE{Arbic2010,
+  author = {Arbic, Wallcraft, Metzger},
+  title = {Concurrent simulation of the eddying general circulation and tides in a global ocean model},
+  journal = OM,
+  year = {2010},
+  volume = {32},  number = {3-4},
+  pages = {175-187}
+}
+
+@ARTICLE{Arhan2006,
+  author = {M. Arhan and A.M. Treguier and B. Bourles and S. Michel},
+  title = {Diagnosing the annual cycle of the Equatorial Undercurrent in the
+	Atlantic Ocean from a general circulation model},
+  journal = JPO,
+  year = {2006},
+  volume = {36},
+  pages = {1502--1522}
+}
+
+@ARTICLE{Artale_al_JGR02,
+  author={V. Artale and D. Iudicone and R. Santoleri and V. Rupolo and S. Marullo
+          and F. {D'O}rtenzio},
+  title={Role of surface fluxes in ocean general circulation models using satellite
+          sea surface temperature: Validation of and sensitivity to the forcing
+          frequency of the Mediterranean thermohaline circulation},
+  journal=JGR,
+  year={2002},
+  volume={107},
+  pages={1978-2012},
+  doi = {10.1029/2000JC000452},
+}
+
+@ARTICLE{ASSELIN_MWR72,
+  author = {R. Asselin},
+  title = {Frequency Filter for Time Integrations},
+  journal = MWR,
+  year = {1972},
+  volume = {100},  number = {6},
+  pages = {487--490}
+}
+
+@ARTICLE{Atmadipoera_al_DSR09,
+  author = {A. Atmadipoera and R. Molcard and G. Madec and S.Wijffels and J.
+	Sprintall and A. Koch-Larrouy and I. Jaya and A. Supangat},
+  title = {Characteristics and Variability of the Indonesian Throughflow Water
+	at the Outflow Straits},
+  journal = DSR,
+  year = {2009},
+  volume = {56},  number = {11},
+  pages = {1942--1954},
+  doi = {10.1016/j.dsr.2009.06.004},
+}
+
+@ARTICLE{Aumont_al_GBC99,
+  author = {O. Aumont and P. Monfray and J. C. Orr and G. Madec and E. Maier-Reimer},
+  title = {Nutrient trapping in the equatorial Pacific: The ocean circulation solution},
+  journal = GBC,
+  year = {1999},
+  volume = {13},
+  pages = {351--369}
+}
+
+@ARTICLE{Aumont_al_CD98,
+  author = {O. Aumont and J.C. Orr and D. Jamous and P. Monfray and O. Marti and G. Madec},
+  title = {A degradation approach to accelerate simulations to steady state
+	in a 3-D tracer transport model of the global ocean},
+  journal = CD,
+  year = {1998},
+  volume = {14},
+  pages = {101--116}
+}
+
+@ARTICLE{Axell_JGR02,
+  author = {L. B. Axell},
+  title = {Wind-driven internal waves and Langmuir circulations in a numerical ocean model of the southern Baltic Sea},
+  journal = JGR,
+  year = {2002},
+  volume = {107},
+  doi = {10.1029/2001JC000922},
+}
+
+@ARTICLE{Axell_Liungman_EFM01,
+  author = {L. B. Axell and O. Liungman},
+  title = {A one-equation turbulence model for geophysical applications: 
+  Comparison with data and the k-$\epsilon$ model},
+  journal = EFM,
+  year = {2001},
+  volume = {1}, pages = {71--106},
+  doi = {10.1029/2001JC000922},
+}
+
+@ARTICLE{Ayina_al_JC06,
+  author = {L.-H. Ayina and A. Bentamy and A. Munes-Mestaz and G. Madec},
+  title = {The Impact of Satellite Winds and Latent Heat Fluxes in a Numerical
+	Simulation of the Tropical Pacific Ocean},
+  journal = JC,
+  year = {2006},
+  volume = {19},
+  pages = {5889--5902}
+}
+
+@ARTICLE{Barnier_al_OD06,
+  author = {B. Barnier and G. Madec and T. Penduff and J.-M. Molines and A.-M.
+	Treguier and J. Le Sommer and A. Beckmann and A. Biastoch and C. Boning 
+	and J. Dengg and C. Derval and E. Durand and S. Gulev and
+	E. Remy and C. Talandier and S. Theetten and M. Maltrud and J. McClean and B. De Cuevas},
+  title = {Impact of partial steps and momentum advection schemes in a global
+	ocean circulation model at eddy-permitting resolution.},
+  journal = OD,
+  year = {2006},
+  volume = {56},
+  pages = {543--567},
+  doi = {10.1007/s10236-006-0082-1},
+}
+
+@INCOLLECTION{Barnier1996,
+  author = {B. Barnier and P. Marchesiello and A.P. de Miranda},
+  title = {Modeling the ocean circulation in the South Atlantic: A strategy for dealing with open boundaries},
+  booktitle = {The South Atlantic: Present and Past Circulation},
+  publisher = {Springer-Verlag, Berlin},
+  year = {1996},
+  editor = {G.Wefer and W.H. Berger and G Siedler and D. Webb},
+  pages = {289-304}
+}
+
+@ARTICLE{Barnier1998,
+  author = {B. Barnier and P. Marchesiello and A. P. de Miranda and J.M. Molines
+	and M. Coulibaly},
+  title = {A sigma-coordinate primitive equation model for studying the circulation
+	in the South Atlantic I, Model configuration with error estimates},
+  journal = DSR,
+  year = {1998},
+  volume = {45},
+  pages = {543--572}
+}
+
+@ARTICLE{Barthelet_al_CRAS98,
+  author = {P. Barthelet and S. Bony and P. Braconnot and A. Braum and D. Cariolle
+	and E. Cohen-Solal and J.-L. Dufresne and P. Delecluse and M. D\'{e}qu\'{e}
+	and L. Fairhead and M.-A. Filiberti and M. Forichon and J.-Y. Grandpeix
+	and E. Guilyardi and M.-N. Houssais and M. Imbard and H. Le Treut
+	and C. Lévy and Z.X. Li and G. Madec and P. Marquet and O. Marti
+	and S. Planton and L. Terray and O. Thual and S. Valcke},
+  title = {Global coupled simulations of climate change due to increased atmospheric CO2 concentration},
+  journal = {C. R. Acad. Sci Paris},
+  year = {1998},
+  volume = {326},
+  pages = {677--684}
+}
+
+@ARTICLE{Beckmann2003,
+  author = {A. Beckmann and H. Goosse},
+  title = {A parameterization of ice shelf-ocean interaction for climate models},
+  journal = OM,
+  year = {2003},
+  volume = {5},
+  pages = {157--170}
+}
+
+@ARTICLE{Beckmann1998,
+  author = {A. Beckmann},
+  title = {The representation of bottom boundary layer processes in numerical
+	ocean circulation models.},
+  journal = {Ocean modelling and parameterization, E. P. Chassignet and J. Verron
+	(eds.), NATO Science Series, Kluwer Academic Publishers},
+  year = {1998}
+}
+
+@ARTICLE{Beckmann_Doscher1997,
+  author = {A. Beckmann and R. D\"{o}scher},
+  title = {A method for improved representation of dense water spreading over
+	topography in geopotential-coordinate models},
+  journal = JPO,
+  year = {1997},
+  volume = {27},
+  pages = {581--591}
+}
+
+@ARTICLE{Beckmann1993,
+  author = {A. Beckmann and D. B. Haidvogel},
+  title = {Numerical Simulation of Flow around a Tall Isolated Seamount. 
+   Part I - Problem Formulation and Model Accuracy},
+  journal = JPO,
+  year = {1993},
+  volume = {23},  number = {8},
+  pages = {1736--1753}
+}
+
+@ARTICLE{Bernie_al_CD07,
+  author = {D. Bernie and E. Guilyardi and G. Madec and J. M. Slingo and S. J. Woolnough},
+  title = {Impact of resolving the diurnal cycle in an ocean--atmosphere GCM. Part 1: a diurnally forced OGCM},
+  journal = CD,
+  year = {2007},
+  volume = {29},  number = {6},
+  pages = {575--590}
+}
+
+@ARTICLE{Bernie_al_CD08,
+  author = {D. Bernie and E. Guilyardi and G. Madec and J. M. Slingo and S. J. Woolnough},
+  title = {Impact of resolving the diurnal cycle in an ocean--atmosphere GCM. Part 2: A diurnally coupled CGCM},
+  journal = CD,
+  year = {2008},
+  volume = {31},  number = {7},
+  pages = {909--925},
+  doi = {10.1007/s00382-008-0429-z},
+}
+
+@ARTICLE{Bernie_al_JC05,
+  author = {D. J. Bernie and S. J. Woolnough and J. M. Slingo and E. Guilyardi},
+  title = {Modelling diurnal and intraseasonal variability of the ocean mixed
+	layer},
+  journal = JC,
+  year = {2005},
+  volume = {18},  number = {8},
+  pages = {1190--1200}
+}
+
+@ARTICLE{Bessiere_al_GRL08,
+  author = {L. Bessi\'{e}res and G. Madec and F. Lyard},
+  title = {Global Tidal Residual Mean Circulation: Does it Affect a Climate OGCM?},
+  journal = GRL,
+  year = {2008},
+  volume = {35},
+  pages = {L03609},
+  doi = {10.1029/2007GL032644},
+}
+
+@ARTICLE{Biastoch_al_JC08,
+  author = {A. Biastoch and C. W. Böning and J. Getzlaff and J.-M. Molines and G. Madec},
+  title = {Causes of interannual – decadal variability in the meridional overturning
+	circulation of the mid-latitude North Atlantic Ocean},
+  journal = JC,
+  year = {2008},
+  volume = {21},  number = {24},
+  pages = {6599-6615},
+  doi = {10.1175/2008JCLI2404.1},
+}
+
+@ARTICLE{Bignami_al_JGR95,
+  author = {F. Bignami and S. Marullo and R. Santoleri and M. E. Schiano},
+  title = {Longwave radiation budget in the Mediterranean Sea}, 
+  journal = JGR,
+  year = {1995},
+  volume = {100},  number = {C2},
+  pages = {2501--2514},
+  doi = {10.1029/94JC02496},
+}
+
+@ARTICLE{Blanke_al_JPO99,
+  author = {B. Blanke and M. Arhan and G. Madec and S. Roche},
+  title = {Warm Water Paths in the Equatorial Atlantic as Diagnosed with a General Circulation Model},
+  journal = JPO,
+  year = {1999},
+  volume = {29},  number = {11},
+  pages = {2753-2768}
+}
+
+@ARTICLE{Blanke1993,
+  author = {B. Blanke and P. Delecluse},
+  title = {Low frequency variability of the tropical Atlantic ocean simulated
+	by a general circulation model with mixed layer physics},
+  journal = JPO,
+  year = {1993},
+  volume = {23},
+  pages = {1363--1388}
+}
+
+@ARTICLE{blanke_al_JC97,
+  author = {B. Blanke and J. D. Neelin and D. Gutzler},
+  title = {Estimating the effect of stochastic wind forcing on ENSO irregularity},
+  journal = JC,
+  year = {1997},
+  volume = {10},
+  pages = {1473--1486}
+}
+
+@ARTICLE{Blanke_Raynaud_JPO97,
+  author = {B. Blanke and S. Raynaud},
+  title = {Kinematics of the Pacific Equatorial Undercurrent: An Eulerian and
+	Lagrangian Approach from GCM Results},
+  journal = JPO,
+  year = {1997},
+  volume = {27},  number = {6},
+  pages = {1038--1053}
+}
+
+@ARTICLE{Blanke_al_JPO01,
+  author = {B. Blanke and S. Speich and G. Madec and K. Döös},
+  title = {A global Diagnostic of interocean mass transfers},
+  journal = JPO,
+  year = {2001},
+  volume = {31},  number = {6},
+  pages = {1623--1632}
+}
+
+@ARTICLE{Blanke_al_GRL02,
+  author = {B. Blanke and S. Speich and G. Madec and R. Maug\'{e}},
+  title = {A global diagnostic of interior ocean ventilation},
+  journal = GRL,
+  year = {2002},
+  volume = {29},  number = {8},
+  pages = {1081--1084}
+}
+
+@ARTICLE{Blayo2005,
+  author = {E. Blayo and L. Debreu},
+  title = {Revisiting open boundary conditions from the point of view of characteristic
+	variables},
+  journal = OM,
+  year = {2005},
+  volume = {9},
+  pages = {231--252}
+}
+
+@ARTICLE{Bloom_al_MWR96,
+  author = {S. C. Bloom and L. L. Takacs and A. M. Da Silva and D. Ledvina},
+  title = {Data assimilation using incremental analysis updates},
+  journal = MWR,
+  year = {1996},
+  volume = {124},
+  pages = {1256--1271}
+}
+
+@ARTICLE{Bopp_al_GBC01,
+  author = {L. Bopp and P. Monfray and O. Aumont and J.-L. Dufresne and H. Le Treut 
+    and G. Madec and L. Terray and J.C. Orr},
+  title = {Potential impact of climate change on marine export production},
+  journal = GBC,
+  year = {2001},
+  volume = {15},  number = {1},
+  pages = {81--101}
+}
+
+@article{bouffard_Boegman_DAO2013,
+	author = {D. Bouffard and L. Boegman},
+	title = {A diapycnal diffusivity model for stratified environmental flows},
+	volume = {61-62},
+	issn = {03770265},
+	doi = {10.1016/j.dynatmoce.2013.02.002},
+	journal = DAO,
+	year = {2013},
+	pages = {14--34},
+}
+
+@ARTICLE{Bougeault1989,
+  author = {P. Bougeault and P. Lacarrere},
+  title = {Parameterization of Orography-Induced Turbulence in a Mesobeta--Scale
+	Model},
+  journal = MWR,
+  year = {1989},
+  volume = {117},  number = {8},
+  pages = {1872--1890},
+}
+
+@ARTICLE{Bouillon_al_OM09,
+  author = {S. Bouillon and M.A. Morales Maqueda and V. Legat and T. Fichefet},
+  title = {An Elastic-Viscous-Plastic Sea Ice Model formulated on Arakawa B and C Grids},
+  journal = OM,
+  year = {2009},
+  volume = {27},
+  pages = {174--184},
+  doi = {10.1016/j.ocemod.2009.01.004},
+}
+
+@ARTICLE{Boulanger_al_GRL01,
+  author = {J.-P. Boulanger and E. Durand and J.-P. Duvel and C. Menkes and P.
+	Delecluse and M. Imbard and M. Lengaigne and G. Madec and S. Masson},
+  title = {Role of non-linear oceanic processes in the response to westerly
+	wind events: new implications for the 1997 El Niño onset},
+  journal = GRL,
+  year = {2001},
+  volume = {28},  number = {8},
+  pages = {1603--1606}
+}
+
+@article{Brankart_OM2013,
+author = "J.-M. Brankart",
+title = "Impact of uncertainties in the horizontal density gradient upon low resolution global ocean modelling ",
+journal = OM,
+year = "2013",
+volume = "66", pages = "64--76",
+issn = "1463-5003",
+doi = "http://dx.doi.org/10.1016/j.ocemod.2013.02.004",
+}
+
+@Article{Brankart_al_GMD2015,
+AUTHOR = {Brankart, J.-M. and Candille, G. and Garnier, F. and Calone, C. and Melet, A. and Bouttier, P.-A. and Brasseur, P. and Verron, J.},
+TITLE = {A generic approach to explicit simulation of uncertainty in the NEMO ocean model},
+JOURNAL = {Geoscientific Model Development},
+VOLUME = {8},
+YEAR = {2015},
+NUMBER = {5},
+PAGES = {1285--1297},
+DOI = {10.5194/gmd-8-1285-2015}
+}
+
+@ARTICLE{Breivik_al_OM2016,
+   AUTHOR = {{\O}yvind Breivik and Jean-Raymond Bidlot and Peter A.E.M. Janssen},
+   YEAR = {2016},
+   TITLE = "{A Stokes drift approximation based on the Phillips spectrum}",
+   JOURNAL = {OM},
+   VOLUME = {100},
+   DOI = {10.1016/j.ocemod.2016.01.005},
+   PAGES = {49--56, arXiv:1601.08092}
+}
+
+@ARTICLE{Brodeau_al_OM09,
+  author = {L. Brodeau and B. Barnier and A.-M. Tr\'{e}guier and T. Penduff and S. Gulev},
+  title = {An ERA40-based atmospheric forcing for global ocean circulation models},
+  journal = OM,
+  year = {2009},
+  volume = {31},  number = {3-4},
+  pages = {88--104}
+}
+
+
+@ARTICLE{de_Boyer_Montegut_al_JGR04,
+  author = {C. de Boyer Mont\'{e}gut and G. Madec and A.S. Fischer and A. Lazar and D. Iudicone},
+  title = {Mixed layer depth over the global ocean: An examination of profile
+	data and a profile-based climatology},
+  journal = JGR,
+  year = {2004},
+  volume = {109},
+  pages = {C12003},
+  doi = {10.1029/2004JC002378},
+}
+
+@ARTICLE{de_Boyer_Montegut_al_JC07,
+  author = {C. de Boyer Mont\'{e}gut and J. Vialard and F. Durand and G. Madec},
+  title = {Simulated seasonal and interannual variability of mixed layer heat
+	budget in the northern Indian Ocean},
+  journal = JC,
+  year = {2007},
+  volume = {20},  number = {13},
+  pages = {3249--3268}
+}
+
+@ARTICLE{Brown_Campana_MWR78,
+  author = {J. A. Brown and K. A. Campana},
+  title = {An Economical Time-Differencing System for Numerical Weather Prediction},
+  journal = MWR,
+  year = {1978},
+  volume = {106},  number = {8},
+  pages = {1125--1136},
+}
+
+@ARTICLE{Bryan1997,
+  author = {K. Bryan},
+  title = {A Numerical Method for the Study of the Circulation of the World Ocean},
+  journal = JCP,
+  year = {1997},
+  volume = {135},  number = {2}
+}
+
+@ARTICLE{Bryan1984,
+  author = {K. Bryan},
+  title = {Accelerating the convergence to equilibrium of ocean-climate models},
+  journal = JPO,
+  year = {1984},
+  volume = {14},
+  pages = {666--673}
+}
+
+@ARTICLE{Bryden1973,
+  author = {H. L. Bryden},
+  title = {New polynomials for thermal expansion, adiabatic temperature gradient
+    and potential temperature of sea water},
+  journal = DSR,
+  year = {1973},
+  volume = {20},
+  pages = {401--408}
+}
+
+@ARTICLE{Burchard_OM02,
+  author = {Hans Burchard},
+  title = {Energy-conserving discretisation of turbulent shear and buoyancy
+	production},
+  journal = OM,
+  year = {2002},
+  volume = {4},  number = {3-4},
+  pages = {347--361},
+  doi = {10.1016/S1463-5003(02)00009-4},
+}
+
+@ARTICLE{Campin2004,
+  author = {J.-M. Campin and A. Adcroft and C. Hill and J. Marshall},
+  title = {Conservation of properties in a free-surface model},
+  journal = OM,
+  year = {2004},
+  volume = {6},  number = {3-4},
+  pages = {221--244}
+}
+
+@ARTICLE{Campin_al_OM08,
+  author = {J.-M. Campin and J. Marshall and D. Ferreira},
+  title = {Sea ice-ocean coupling using a rescaled vertical coordinate z*},
+  journal = OM,
+  year = {2008},
+  volume = {24},  number = {1-2},
+  pages = {1--14},
+  doi = {10.1016/j.ocemod.2008.05.005},
+}
+
+@ARTICLE{Campin_Goosse_Tel99,
+  author = {J.-M. Campin and H. Goosse},
+  title = {Parameterization of density-driven downsloping flow for a coarse-resolution ocean model in z-coordinate},
+  journal = {Tellus},
+  year = {1999},
+  volume = {51},
+  pages = {412--430}
+}
+
+@ARTICLE{Carrere_Lyard_GRL03,
+  author = {L. Carr\`{e}re and F. Lyard},
+  title = {Modelling the barotropic response of the global ocean to atmospheric
+	wind and pressure forcing - comparisons with observations},
+  journal = GRL,
+  year = {2003},
+  volume = {30},  number = {6},
+  doi = {10.1029/2002GL016473},
+}
+
+@ARTICLE{Castellari_al_JMS1998,
+  author = {S> Castellari and  N. Pinardi and K. Leaman },
+  title = {A model study of air-sea interactions in the Mediterranean Sea.},
+  journal = JMS,
+  year = {1998},
+  volume = {18},
+  pages = {89--114}
+}
+
+@TECHREPORT{Chanut2005,
+ author = {J. Chanut},
+ title = {Nesting code for NEMO},
+ year = {2005},
+ institution = {European Union: Marine Environment and Security for the European Area (MERSEA) Integrated Project},
+note = {MERSEA-WP09-MERCA-TASK-9.1.1}
+} 
+
+@ARTICLE{Chassignet_al_JPO03,
+  author = {Eric P. Chassignet and Linda T. Smith and George R. Halliwell},
+  title = {North Atlantic Simulations with the Hybrid Coordinate Ocean Model
+	(HYCOM): Impact of the Vertical Coordinate Choice, Reference Pressure, and Thermobaricity},
+  journal = JPO,
+  year = {2003},
+  volume = {33},
+  pages = {2504-2526}
+}
+
+@ARTICLE{Covey_al_CD00,
+  author = {C. Covey and A. Abe-Ouchi and G.J. Boer and B.A. Boville and U. Cubasch
+	and L. Fairhead and G.M. Flato and H. Gordon and E. Guilyardi and X. Jiang 
+	and T.C. Johns and H. Le Treut and G. Madec and G.A. Meehl and R. Miller 
+	and A. Noda and S. B. Power and E. Roeckner and G. Russell and E.K. Schneider 
+	and R.J. Stouffer and L. Terray and J.-S. von Storch},
+  title = {The seasonal cycle in coupled ocean-atmosphere general circulation models},
+  journal = CD,
+  year = {2000},
+  volume = {16},
+  pages = {775--787}
+}
+
+@ARTICLE{Canuto_2001,
+  author = {V. M. Canuto and A. Howard and Y. Cheng and M. S. Dubovikov},
+  title = {Ocean turbulence. PartI: One-point closure model-momentum and heat vertical diffusivities},
+  journal = JPO,
+  year = {2001},
+  volume = {24},  number = {12},
+  pages = {2546--2559}
+}
+
+@ARTICLE{Cox1987,
+  author = {M. Cox},
+  title = {Isopycnal diffusion in a z-coordinate ocean model},
+  journal = OM,
+  year = {1987},
+  volume = {74},
+  pages = {1--9}
+}
+
+@ARTICLE{Craig_Banner_JPO94,
+  author = {P. D. Craig and M. L. Banner},
+  title = {Modeling wave-enhanced turbulence in the ocean surface layer},
+  journal = JPO,
+  year = {1994},
+  volume = {24},  number = {12},
+  pages = {2546--2559}
+}
+
+@ARTICLE{Craik_Leibovich_JFM76,
+  author = {A. D. D. Craik and S. Leibovich},
+  title = {A rational model for Langmuir circulations},
+  journal = JFM,
+  year = {1976},
+  volume = {73}, 
+  pages = {401--426}
+}
+
+@ARTICLE{Cravatte_al_OM07,
+  author = {Cravatte, S. and G. Madec and T. Izumo and C. Menkes and A. Bozec},
+  title = {Progress in the 3-D circulation of the eastern equatorial Pacific
+	in a climate ocean model},
+  journal = OM,
+  year = {2007},
+  volume = {17},  number = {1},
+  pages = {28--48}
+}
+
+@BOOK{Daley_Barker_Bk01,
+  author = {R. Daley and E. Barker},
+  title = {NAVDAS Source Book 2001},
+  publisher = {NRL/PU/7530-01-441, Available from the Naval Research Laboratory, Monterey, CA., 93943-5502},
+  year = {2001},
+  pages = {163pp}
+}
+
+@ARTICLE{D'Alessio_al_JPO98,
+  author = {S. J. D. D'Alessio and K. Abdella and N. A. McFarlane},
+  title = {A new second-order turbulence closure scheme for modeling the oceanic mixed layer},
+  journal = JPO,
+  year = {1998},
+  volume = {28},
+  pages = {1624--1641}
+}
+
+
+@ARTICLE{Danabasoglu_al_2008,
+	author = {G. Danabasoglu and R. Ferrari and J. C. McWilliams},
+	title = {Sensitivity of an ocean general circulation model to a parameterization of near-surface eddy fluxes},
+	volume = {21},
+	year = {2008},
+	doi = {10.1175/2007JCLI1508.1},
+	journal = {J. Climate},
+	pages = {1192--1208},
+}
+@ARTICLE{Dandonneau_al_S04,
+  author = {Y. Dandonneau and C. Menkes and T. Gorgues and G. Madec},
+  title = {Reply to Peter Killworth, 2004 : '' Comment on the Oceanic Rossby
+	Waves acting as a “Hay Rake” for ecosystem by-products ''},
+  journal = {Science},
+  year = {2004},
+  volume = {304},
+  pages = {390}
+}
+
+@ARTICLE{Davies_QJRMS76,
+ author = {H.C. Davies},
+ title = {A lateral boundary formulation for multi-level prediction models},
+ year = {1976},
+ journal = QJRMS,
+ volume = {102},
+ pages = {405--418}
+}
+
+@ARTICLE{Debreu_al_CG2008,
+  author = {L. Debreu and C. Vouland and E. Blayo},
+  title = {AGRIF: Adaptive Grid Refinement In Fortran},
+  journal = {Computers and Geosciences},
+  year = {2008},
+  volume = {34},
+  pages = {8--13}
+}
+
+@article{de_lavergne_JPO2016_mixing,
+	author = {C. de Lavergne and G. Madec and J. Le Sommer and A. J. G. Nurser and A. C. Naveira Garabato },
+	title = {On Antarctic Bottom Water consumption in the abyssal ocean},
+	issn = {0022-3670},
+	doi= {10.1175/JPO-D-14-0201.1},
+	abstract = {In studies of ocean mixing, it is generally assumed that small-scale turbulent overturns lose 15-20 \% of their energy in eroding the background stratification. Accumulating evidence that this energy fraction, or mixing efficiency Rf, significantly varies depending on flow properties challenges this assumption, however. Here, we examine the implications of a varying mixing efficiency for ocean energetics and deep water mass transformation. Combining current parameterizations of internal wave-driven mixing with a recent model expressing Rf as a function of a turbulence intensity parameter Reb = εν/νN2, we show that accounting for reduced mixing efficiencies in regions of weak stratification or energetic turbulence (high Reb) strongly limits the ability of breaking internal waves to supply oceanic potential energy and drive abyssal upwelling. Moving from a fixed Rf = 1/6 to a variable efficiency Rf(Reb) causes Antarctic Bottom Water upwelling induced by locally-dissipating internal tides and lee waves to fall from 9 to 4 Sv, and the corresponding potential energy source to plunge from 97 to 44 GW. When adding the contribution of remotely-dissipating internal tides under idealized distributions of energy dissipation, the total rate of Antarctic Bottom Water upwelling is reduced by about a factor of 2, reaching 5-15 Sv compared to 10-33 Sv for a fixed efficiency. Our results suggest that distributed mixing, overflow-related boundary processes and geothermal heating are more effective in consuming abyssal waters than topographically-enhanced mixing by breaking internal waves. Our calculations also point to the importance of accurately constraining Rf(Reb) and including the effect in ocean models.},
+	journal = {Journal of Physical Oceanography},
+	year = {2016},
+	volume = {46},  pages = {635-–661}
+}
+
+@article{de_lavergne_JPO2016_efficiency,
+	author = {C. de Lavergne and G. Madec and J. Le Sommer and A. J. G. Nurser and A. C. Naveira Garabato },
+	title = {The impact of a variable mixing efficiency on the abyssal overturning},
+	issn = {0022-3670},
+	doi = {10.1175/JPO-D-14-0259.1},
+	abstract = {In studies of ocean mixing, it is generally assumed that small-scale turbulent overturns lose 15-20 \% of their energy in eroding the background stratification. Accumulating evidence that this energy fraction, or mixing efficiency Rf, significantly varies depending on flow properties challenges this assumption, however. Here, we examine the implications of a varying mixing efficiency for ocean energetics and deep water mass transformation. Combining current parameterizations of internal wave-driven mixing with a recent model expressing Rf as a function of a turbulence intensity parameter Reb = εν/νN2, we show that accounting for reduced mixing efficiencies in regions of weak stratification or energetic turbulence (high Reb) strongly limits the ability of breaking internal waves to supply oceanic potential energy and drive abyssal upwelling. Moving from a fixed Rf = 1/6 to a variable efficiency Rf(Reb) causes Antarctic Bottom Water upwelling induced by locally-dissipating internal tides and lee waves to fall from 9 to 4 Sv, and the corresponding potential energy source to plunge from 97 to 44 GW. When adding the contribution of remotely-dissipating internal tides under idealized distributions of energy dissipation, the total rate of Antarctic Bottom Water upwelling is reduced by about a factor of 2, reaching 5-15 Sv compared to 10-33 Sv for a fixed efficiency. Our results suggest that distributed mixing, overflow-related boundary processes and geothermal heating are more effective in consuming abyssal waters than topographically-enhanced mixing by breaking internal waves. Our calculations also point to the importance of accurately constraining Rf(Reb) and including the effect in ocean models.},
+	journal = {Journal of Physical Oceanography},
+	year = {2016},
+	volume = {46},  pages = {663-–681}
+}
+
+@ARTICLE{Delecluse_Madec_Bk00,
+  author = {P. Delecluse and G. Madec},
+  title = {Ocean modelling and the role of the ocean in the climate system},
+  journal = {In \textit{Modeling the Earth's Climate and its Variability}, Les
+	Houches, Session, LXVII 1997,
+	Eds. W. R. Holland, S. Joussaume and F. David, Elsevier Science},
+  year = {2000},
+  pages = {237--313}
+}
+
+@PHDTHESIS{Demange_PhD2014,
+  author = {J. Demange},
+  title = {Sch\'{e}mas num\'{e}riques d'advection et de propagation d’ondes de gravit\'{e} 
+           dans les mod\`{e}les de circulation oc\'{e}anique.},
+  school = {Doctorat es Applied Mathematiques, Grenoble University, France},
+  year = {2014},
+  pages = {138pp}
+}
+
+@ARTICLE{Dobricic_al_OS07,
+  author = {S. Dobricic and N. Pinardi and M. Adani and M. Tonani and 
+            C. Fratianni and A. Bonazzi and V. Fernandez},
+  title = {Daily oceanographic analysis by the Mediterranean basin scale 
+           assimilation system},
+  journal = OS,
+  year = {2007},
+  volume = {3},
+  pages = {149-157}
+}
+
+@ARTICLE{Doney_al_GBC04,
+  author = {S.C. Doney and K. Lindsay and K. Caldeira and J.−M. Campin and H.
+	Drange and J.−C. Dutay and M. Follows and Y. Gao and A. Gnanadesikan
+	and N. Gruber and A. Ishida and F. Joos and G. Madec and E. Maier−Reimer
+	and J.C. Marshall and R.J. Matear and P. Monfray and A. Mouchet and
+	R. Najjar and J.C. Orr and G.−K. Plattner and J. Sarmiento and R.
+	Schlitzer and R. Slater and I.J. Totterdell and M.−F. Weirig and
+	Y. Yamanaka and A. Yoo},
+  title = {Evaluating global ocean carbon models: the importance of realistic
+	physics},
+  journal = GBC,
+  year = {2004},
+  volume = {18},
+  pages = {GB3017},
+  doi = {10.1029/2003GB002150},
+}
+
+@ARTICLE{Dorscher_Beckmann_JAOT00,
+  author = {R. D\"{o}scher and A. Beckmann},
+  title = {Effects of a Bottom Boundary Layer Parameterization in a Coarse-Resolution
+	Model of the North Atlantic Ocean},
+  journal = JAOT,
+  year = {2000},
+  volume = {17},
+  pages = {698--707}
+}
+
+@ARTICLE{Drijfhout_JPO94,
+  author = {S. S. Drijfhout},
+  title = {Heat transport by Mesoscale Eddies in an Ocean Circulation Model},
+  journal = JPO,
+  year = {1994},
+  volume = {24},
+  pages = {353--369}
+}
+
+@ARTICLE{Dukowicz1994,
+  author = {J. K. Dukowicz and R. D. Smith},
+  title = {Implicit free-surface method for the Bryan-Cox-Semtner ocean model},
+  journal = JGR,
+  year = {1994},
+  volume = {99},
+  pages = {7991--8014}
+}
+
+@ARTICLE{Durand_al_JC07,
+  author = {F. Durand and D. Shankar and C. de Boyer Mont\'{e}gut and S.S.C.
+	Shenoi and B. Blanke and G. Madec},
+  title = {Modeling the barrier-layer formation in the South-Eastern Arabian
+	Sea},
+  journal = JC,
+  year = {2007},
+  volume = {20},  number = {10},
+  pages = {2109--2120}
+}
+
+@ARTICLE{Durand_al_GRL04,
+  author = {F. Durand and S. R. Shetye and J. Vialard and D. Shankar and S.S.C.
+	Shenoi and C. Eth\'{e} and G. Madec},
+  title = {Impact of temperature inversions on SST evolution in the South−Eastern
+	Arabian Sea during the pre−summer monsoon season},
+  journal = GRL,
+  year = {2004},
+  volume = {31},
+  pages = {L01305},
+  doi = {10.1029/2003GL018906},
+}
+
+@INCOLLECTION{Durran2001,
+  author = {D.R. Durran },
+  title = {Open boundary conditions: fact and fiction},
+  booktitle = {Advances in Mathematical Modelling of Atmosphere and Ocean Dynamics},
+  publisher = {Kluwer Academic Publishers},
+  year = {2001},
+  editor = {P.F. Hodnett}
+}
+
+@ARTICLE{Dutay_al_OM02,
+  author = {J.-C. Dutay and J.L. Bullister and S.C. Doney and J.C. Orr and R.
+	Najjar and K. Caldeira and J.-M. Campin and H. Drange and M. Follows
+	and Y. Gao and N. Gruber and M. W. Hecht and A. Ishida and F. Joos
+	and K. Lindsay and G. Madec and E. Maier-Reimer and J.C. Mashall
+	and R. J. Matear and P. Monfray and G.-K. Plattner and J. Sarmiento
+	and R. Schlitzer and R. Slater and I.J. Totterdell and M.-F. Weirig
+	and Y. Yamanaka and A. Tool},
+  title = {Evaluation of ocean model ventilation with CFC-11: comparison of
+	13 global ocean models},
+  journal = OM,
+  year = {2002},
+  volume = {4},
+  pages = {89--120}
+}
+
+@ARTICLE{Dutay_al_EFM09,
+  author = {J.-C. Dutay and J. Emile-Geay and D. Iudicone and P. Jean-Baptiste
+	and G. Madec and C. Carouge},
+  title = {Helium Isotopic Constraints on Simulated Ocean Circulations - Implications
+	for abyssal theories},
+  journal = EFM,
+  year = {2009},
+  volume = {10},  number = {1-2},
+  pages = {257--273},
+  doi = {10.1007/s10652-009-9159-y}
+}
+
+@ARTICLE{Dutay.J.C2004,
+  author = {J. -C. Dutay and P. J. -Baptiste and J. -M. Campin and A. Ishida
+	and E. M. -Reimer and R. J. Matear and A. Mouchet and I. J. Totterdell
+	and Y. Yamanaka and K. Rodgers and G. Madec and J.C. Orr},
+  title = {Evaluation of OCMIP-2 ocean models deep circulation with mantle helium-3},
+  journal = JMS,
+  year = {2004},
+  pages = {1--22}
+}
+
+@ARTICLE{D'Ortenzio_al_GRL05,
+  author = {F. D\'Ortenzio and D. Iudicone and C. de Boyer Mont\'{e}gut and P.
+	Testor and D. Antoine and S. Marullo and R. Santoleri and G. Madec},
+  title = {Seasonal variability of the mixed layer depth in the Mediterranean
+	Sea : a new climatology based on analysis of individual profiles},
+  journal = GRL,
+  year = {2005},
+  volume = {32},
+  pages = {L12605},
+  doi = {10.1029/2005GL022463},
+}
+
+@ARTICLE{Egbert_Ray_JGR01,
+  author = {G.B. Egbert and R.D. Ray},
+  title = {Estimates of M2 tidal energy dissipation from TOPEX/POSEIDON altimeter
+	data},
+  journal = JGR,
+  year = {2001},
+  volume = {106},
+  pages = {22475--22502}
+}
+
+@ARTICLE{Egbert_Ray_Nat00,
+  author = {G.B. Egbert and R.D Ray},
+  title = {Significant dissipation of tidal energy in the deep ocean inferred
+	from satellite altimeter data},
+  journal = {Nature},
+  year = {2000},
+  volume = {405},
+  pages = {775--778}
+}
+
+@ARTICLE{Eiseman1980,
+  author = {P. R. Eiseman and A. P. Stone},
+  title = {Conservation lows of fluid dynamics -- A survey},
+  journal = {SIAM Review},
+  year = {1980},
+  volume = {22},
+  pages = {12--27}
+}
+
+@ARTICLE{Emile-Geay_Madec_OS09,
+  author = {J. Emile-Geay and G. Madec},
+  title = {Geothermal heating, diapycnal mixing and the abyssal circulation},
+  journal = OS,
+  year = {2009},
+  volume = {5},
+  pages = {281--325}
+}
+
+@ARTICLE{Engerdahl_Tel95,
+ author = {H. Engerdahl},
+ year = {1995},
+ title = {Use of the flow relaxation scheme in a three-dimensional baroclinic ocean model with realistic topography},
+ journal = {Tellus},
+ volume = {47A},
+ pages = {365--382}
+}
+
+@ARTICLE{EUROMODEL_OA95,
+  author = {EUROMODEL Group (P.M. Lehucher, L. Beautier, M. Chartier, F. Martel,
+	L. Mortier, P. Brehmer, C. Millot, C. Alberola, M. Benzhora, I. Taupier-Letage,
+	G. Chabert d'Hieres, H. Didelle, P. Gleizon, D. Obaton, M. Cr\'{e}pon,
+	C. Herbaut, G. Madec, S. Speich, J. Nihoul, J. M. Beckers, P. Brasseur,
+	E. Deleersnijder, S. Djenidi, J. Font, A. Castellon, E. Garcia-Ladona,
+	M. J. Lopez-Garcia, M. Manriquez, M. Maso, J. Salat, J. Tintore,
+	S. Alonso, D. Gomis, A. Viudez, M. Astraldi, D. Bacciola, M. Borghini,
+	F. Dell'amico, C. Galli, E. Lazzoni, G. P. Gasparini, S. Sparnocchia,
+	and A. Harzallah, 1995 : Progress from 1989 to 1992 in understanding
+	the circulation of the Western Mediterranean Sea. Oceanologica Acta,
+	18, 2, 255-271.},
+  title = {EUROMODEL Group (P.M. Lehucher, L. Beautier, M. Chartier, F. Martel,
+	L. Mortier, P. Brehmer, C. Millot, C. Alberola, M. Benzhora, I. Taupier-Letage,
+	G. Chabert d'Hieres, H. Didelle, P. Gleizon, D. Obaton, M. Cr\'{e}pon,
+	C. Herbaut, G. Madec, S. Speich, J. Nihoul, J. M. Beckers, P. Brasseur,
+	E. Deleersnijder, S. Djenidi, J. Font, A. Castellon, E. Garcia-Ladona,
+	M. J. Lopez-Garcia, M. Manriquez, M. Maso, J. Salat, J. Tintore,
+	S. Alonso, D. Gomis, A. Viudez, M. Astraldi, D. Bacciola, M. Borghini,
+	F. Dell'amico, C. Galli, E. Lazzoni, G. P. Gasparini, S. Sparnocchia,
+	and A. Harzallah, 1995 : Progress from 1989 to 1992 in understanding
+	the circulation of the Western Mediterranean Sea.},
+  journal = {Oceanologica Acta},
+  year = {1995},
+  volume = {18},  number = {2},
+  pages = {255--271}
+}
+
+@PHDTHESIS{Farge1987,
+  author = {M. Farge},
+  title = {Dynamique non lineaire des ondes et des tourbillons dans les equations de Saint Venant},
+  school = {Doctorat es Mathematiques, Paris VI University, France},
+  year = {1987},
+  pages = {401pp}
+}
+
+@ARTICLE{Farrow1995,
+  author = {D. E. Farrow and D. P. Stevens},
+  title = {A new tracer advection scheme for Bryan--Cox type ocean general circulation
+	models},
+  journal = JPO,
+  year = {1995},
+  volume = {25},
+  pages = {1731--1741.}
+}
+
+@ARTICLE{Flather1976,
+ author = {R.A. Flather},
+ year = {1976},
+ title = {A tidal model of the north-west European continental shelf},
+ journal = {Memoires de la Societ\'{e} Royale des Sciences de Li\`{e}ge},
+ volume = {6},
+ pages = {141--164}
+}
+
+@ARTICLE{Flather_JPO94,
+ author = {R.A. Flather},
+ year = {1994},
+ title = {A storm surge prediction model for the northern Bay of Bengal with application to the cyclone disaster in April 1991},
+ journal = JPO,
+ volume = {24},
+ pages = {172--190}
+}
+
+@ARTICLE{Fujio1991,
+  author = {S. Fujio and N. Imasato},
+  title = {Diagnostic calculation for circulation and water mass movement in
+	the deep Pacific},
+  journal = JGR,
+  year = {1991},
+  volume = {96},
+  pages = {759--774}
+}
+
+@ARTICLE{Galperin_al_JAS88,
+  author = {B. Galperin and L. H. Kantha and S. Hassid and A. Rosati},
+  title = {A quasi-equilibrium turbulent energy model for geophysical flows},
+  journal = JAS,
+  year = {1988},
+  volume = {45},
+  pages = {55--62}
+}
+
+@ARTICLE{Gargett1984,
+  author = {A. E. Gargett},
+  title = {Vertical eddy diffusivity in the ocean interior},
+  journal = JMR,
+  year = {1984},
+  volume = {42}
+}
+
+@ARTICLE{Gaspar1990,
+  author = {P. Gaspar and Y. Gr{\'e}goris and J.-M. Lefevre},
+  title = {A simple eddy kinetic energy model for simulations of the oceanic vertical mixing\: 
+    Tests at Station Papa and long-term upper ocean study site},
+  journal = JGR,
+  year = {1990},
+  volume = {95},  number = {C9}
+}
+
+@ARTICLE{Gent1990,
+  author = {P. R. Gent and J. C. Mcwilliams},
+  title = {Isopycnal Mixing in Ocean Circulation Models},
+  journal = JPO,
+  year = {1990},
+  volume = {20},  number = {1},
+  pages = {150--155},
+}
+
+@Article{Gentemann_al_JGR09,
+  author = 	 {C. L. Gentemann  and P. J. Minnett and B. Ward},
+  title =        {Profiles of Ocean Surface heating ({POSH}): A new model 
+                  of upper ocean diurnal warming},
+  journal = 	 JGR,
+  year = 	 {2009},
+  Volume = 	 {114},
+  Pages = 	 {C07017},
+  doi = 	 {10.1029/2008JC004825},
+  OPTannote = 	 {}
+}
+
+@ARTICLE{Gerdes1993a,
+  author = {R. Gerdes},
+  title = {A primitive equation ocean circulation model using a general vertical
+	coordinate transformation 1. Description and testing of the model},
+  journal = JGR,
+  year = {1993},
+  volume = {98}
+}
+
+@ARTICLE{Gerdes1993b,
+  author = {R. Gerdes},
+  title = {A primitive equation ocean circulation model using a general vertical
+	coordinate transformation 2. Application to an overflow problem},
+  journal = JGR,
+  year = {1993},
+  volume = {98},
+  pages = {14703--14726}
+}
+
+@ARTICLE{Gerdes1991,
+	Author = {Gerdes, R{\"u}diger and K{\"o}berle, Cornelia and Willebrand, J{\"u}rgen},
+	Doi = {10.1007/BF00210006},
+	Journal = {Clim. Dynamics},
+	Number = {4},
+	Pages = {211--226},
+	Title = {The influence of numerical advection schemes on the results of ocean general circulation models},
+	Volume = {5},
+	Year = {1991},
+}
+@TECHREPORT{Gibson_TR86,
+  author = {J. K. Gibson},
+  title = {Standard software development and maintenance},
+  institution = {Operational Dep., ECMWF, Reading, UK.},
+  year = {1986}
+}
+
+@BOOK{Gill1982,
+  title = {Atmosphere-Ocean Dynamics},
+  publisher = {International Geophysics Series, Academic Press, New-York},
+  year = {1982},
+  author = {A. E. Gill}
+}
+
+@article{goff_JGR2010,
+	author = {J. A. Goff},
+	title = {Global prediction of abyssal hill root-mean-square heights from small-scale altimetric gravity variability},
+	issn = {2156-2202},
+	doi = {10.1029/2010JB007867},
+	abstract = {Abyssal hills, which are pervasive landforms on the seafloor of the Earth's oceans, represent a potential tectonic record of the history of mid-ocean ridge spreading. However, the most detailed global maps of the seafloor, derived from the satellite altimetry-based gravity field, cannot be used to deterministically characterize such small-scale ({\textless}10 km) morphology. Nevertheless, the small-scale variability of the gravity field can be related to the statistical properties of abyssal hill morphology using the upward continuation formulation. In this paper, I construct a global prediction of abyssal hill root-mean-square (rms) heights from the small-scale variability of the altimetric gravity field. The abyssal hill-related component of the gravity field is derived by first masking distinct features, such as seamounts, mid-ocean ridges, and continental margins, and then applying a newly designed adaptive directional filter algorithm to remove fracture zone/discontinuity fabric. A noise field is derived empirically by correlating the rms variability of the small-scale gravity field to the altimetric noise field in regions of very low relief, and the noise variance is subtracted from the small-scale gravity variance. Suites of synthetically derived, abyssal hill formed gravity fields are generated as a function of water depth, basement rms heights, and sediment thickness and used to predict abyssal hill seafloor rms heights from corrected small-scale gravity rms height. The resulting global prediction of abyssal hill rms heights is validated qualitatively by comparing against expected variations in abyssal hill morphology and quantitatively by comparing against actual measurements of rms heights. Although there is scatter, the prediction appears unbiased.},
+	volume = {115},
+	number = {B12},
+	journal = {Journal of Geophysical Research: Solid Earth},
+	year = {2010},
+	pages = {B12104},
+}
+
+@ARTICLE{Goosse_al_JGR99,
+  author = {H. Goosse and E. Deleersnijder and T. Fichefet and M. England},
+  title = {Sensitivity of a global coupled ocean-sea ice model to the parameterization of vertical mixing},
+  journal = JGR,
+  year = {1999},
+  volume = {104},
+  pages = {13,681--13,695}
+}
+
+@ARTICLE{Gorgues_al_GRL07,
+  author = {T. Gorgues and C. Menkes and O. Aumont and K. Rodgers and G. Madec and Y. Dandonneau},
+  title = {Indonesian Throughflow control of the eastern equatorial Pacific biogeochemistry},
+  journal = GRL,
+  year = {2007},
+  volume = {34},
+  pages = {L05609},
+  doi = {10.1029/2006GL028210},
+}
+
+@ARTICLE{Graham_McDougall_JPO13,
+  author = {F.S. Graham and T.J. McDougall},
+  title = {Quantifying the nonconservative production of conservative temperature, potential temperature, and entropy},
+  journal = JPO,
+  year = {2013},
+  volume = {43},
+  pages = {838--862},
+  doi = {10.1175/JPO-D-11-0188.1}
+}
+
+@ARTICLE{Greatbatch_JGR94,
+  author = {R. J. Greatbatch},
+  title = {A note on the representation of steric sea level in models that conserve
+	volume rather than mass},
+  journal = JGR,
+  year = {1994},
+  volume = {99},  number = {C6},
+  pages = {12,767--12,771}
+}
+
+@BOOK{Griffies_Bk04,
+  title = {Fundamentals of ocean climate models},
+  publisher = {Princeton University Press, 434pp},
+  year = {2004},
+  author = {S.M. Griffies}
+}
+
+@ARTICLE{Griffies_JPO98,
+  author = {S.M. Griffies},
+  title = {The Gent-McWilliams skew-flux},
+  journal = JPO,
+  year = {1998},
+  volume = {28},
+  pages = {831--841}
+}
+
+@ARTICLE{Griffies_al_OM09,
+  author = {S.M. Griffies and A. Biastoch and C. Boning and F. Bryan and G. Danabasoglu
+	and E. P. Chassignet and M. H. England and R. Gerdes and H. Haak
+	and R. W. Hallberg and W. Hazeleger and J. Jungclaus and W. G. Large
+	and G. Madec and A. Pirani and B. L. Samuels and M. Scheinert and
+	A. Sen Gupta and C. A. Severijns and H. L. Simmons and A.-M. Treguier
+	and M. Winton and S. Yeager and J. Yin},
+  title = {Coordinated Ocean-ice Reference Experiments (COREs)},
+  journal = OM,
+  year = {2009},
+  volume = {26},  number = {1-2},
+  pages = {1--46},
+  doi = {10.1016/j.ocemod.2008.08.007},
+}
+
+@ARTICLE{Griffies_al_OS05,
+  author = {S.M. Griffies and A. Gnanadesikan and K.W. Dixon and J.P. Dunne and
+	R. Gerdes and M.J. Harrison and A. Rosati and J.L. Russell and B.L.
+	Samuels and M.J. Spelman and M. Winton and R. Zhang},
+  title = {Formulation of an ocean model for global climate simulations},
+  journal = OS,
+  year = {2005},
+  volume = {1},
+  pages = {45--79}
+  }
+
+@ARTICLE{Griffies_al_JPO98,
+  author = {S.M. Griffies and A. Gnanadesikan and R.C. Pacanowski and V.D. Larichev
+	and J.K. Dukowicz and R.D. Smith},
+  title = {Isoneutral Diffusion in a z-Coordinate Ocean Model},
+  journal = JPO,
+  year = {1998},
+  volume = {28},  number = {5},
+  pages = {805--830},
+}
+
+@ARTICLE{Griffies_al_MWR01,
+  author = {S.M. Griffies and R.C. Pacanowski and M. Schmidt and V. Balaji},
+  title = {Tracer Conservation with an Explicit Free Surface Method for z-Coordinate
+	Ocean Models},
+  journal = MWR,
+  year = {2001},
+  volume = {129},  number = {5},
+  pages = {1081--1098},
+}
+
+@ARTICLE{Griffies_Hallberg_MWR00,
+  author = {S.M. Griffies and R.W. Hallberg},
+  title = {Biharmonic friction with a Smagorinsky-like viscosity for use in large-scale eddy-permitting ocean models},
+  journal = MWR,
+  year = {2000},
+  volume = {128},  
+  pages = {2935–-2946},
+  doi = {10.1175/1520-0493(2000)128}
+}
+
+@ARTICLE{Guilyardi_al_JC04,
+  author = {E. Guilyardi and S. Gualdi and J. M. Slingo and A. Navarra and P. Delecluse 
+    and J. Cole and G. Madec and M. Roberts and M. Latif and L. Terray},
+  title = {Representing El Ni\~{n}o in coupled ocean-atmosphere GCMs: the dominant role of the atmospheric component},
+  journal = JC,
+  year = {2004},
+  volume = {17},
+  pages = {4623--4629}
+}
+
+@ARTICLE{Guilyardi_Madec_CD98,
+  author = {E. Guilyardi and G. Madec},
+  title = {Performance of the OPA-ARPEGE-T21 global ocean-atmosphere coupled model},
+  journal = CD,
+  year = {1997},
+  volume = {13},
+  pages = {149--165}
+}
+
+@ARTICLE{Guilyardi_al_CD01,
+  author = {E. Guilyardi and G. Madec and L. Terray},
+  title = {The role of lateral ocean physics in the upper ocean thermal balance of a coupled ocean-atmosphere GCM},
+  journal = CD,
+  year = {2001},
+  volume = {17},
+  pages = {589--599},
+  number = {8}
+}
+
+@ARTICLE{Guilyardi_al_CRAS95,
+  author = {E. Guilyardi and G. Madec and L. Terray and M. D\'{e}qu\'{e} and
+	M. Pontaud and M. Imbard and D. Stephenson and M.-A. Filiberti and
+	D. Cariolle and P. Delecluse and O. Thual},
+  title = {Simulation couplée océan-atmosphère de la variabilité du climat},
+  journal = {C. R. Acad. Sci Paris},
+  year = {1995},
+  volume = {320},  number = {s\'{e}rie IIa},
+  pages = {683--690}
+}
+
+@ARTICLE{Guyon_al_EP99,
+  author = {M. Guyon and G. Madec and F.-X. Roux and M. Imbard},
+  title = {A Parallel ocean model for high resolution studies},
+  journal = {Lecture Notes in Computer Science},
+  year = {1999},
+  volume = {Euro-Par'99},
+  pages = {603--607}
+}
+
+@ARTICLE{Guyon_al_CalPar99,
+  author = {M. Guyon and G. Madec and F.-X. Roux and M. Imbard and C. Herbaut
+	and P. Fronier},
+  title = {Parallelization of the OPA ocean model},
+  journal = {Calculateurs Paralleles},
+  year = {1999},
+  volume = {11},  number = {4},
+  pages = {499--517}
+}
+
+@BOOK{Haltiner1980,
+  title = {Numerical prediction and dynamic meteorology},
+  publisher = {John Wiley {\&} Sons Eds., second edition},
+  year = {1980},
+  author = {G. J. Haltiner and R. T. Williams},
+  pages = {477pp}
+}
+
+@ARTICLE{Haney1991,
+  author = {R. L. Haney},
+  title = {On the Pressure Gradient Force over Steep Topography in Sigma Coordinate Ocean Models},
+  journal = JPO,
+  year = {1991},
+  volume = {21},  number = {4},
+  pages = {610--619},
+}
+
+@ARTICLE{Hazeleger_Drijfhout_JPO98,
+  author = {W. Hazeleger and S. S. Drijfhout},
+  title = {Mode water variability in a model of the subtropical gyre: response to anomalous forcing},
+  journal = JPO,
+  year = {1998},
+  volume = {28},
+  pages = {266--288},
+}
+
+@ARTICLE{Hazeleger_Drijfhout_JPO99,
+  author = {W. Hazeleger and S. S. Drijfhout},
+  title = {Stochastically forced mode water variability},
+  journal = JPO,
+  year = {1999},
+  volume = {29},
+  pages = {1772--1786},
+}
+
+@ARTICLE{Hazeleger_Drijfhout_JGR00,
+  author = {W. Hazeleger and S. S. Drijfhout},
+  title = {A model study on internally generated variability in subtropical mode water formation},
+  journal = JGR,
+  year = {2000},
+  volume = {105},
+  pages = {13,965--13,979},
+}
+@ARTICLE{Hazeleger_Drijfhout_JPO00,
+  author = {W. Hazeleger and S. S. Drijfhout},
+  title = {Eddy subduction in a model of the subtropical gyre},
+  journal = JPO,
+  year = {2000},
+  volume = {30},
+  pages = {677--695},
+}
+
+@ARTICLE{Hellerman_Rosenstein_JPO83,
+  author = {S. Hellerman and  M. Rosenstein },
+  title = {Normal monthly wind stress over the world ocean with error estimates},
+  journal = JPO,
+  year = {1983},
+  volume = {13},
+  pages = {1093--1104},
+}
+
+@ARTICLE{He_Ding_JSC01,
+  author = {Y. He and C. H. Q. Ding},
+  title = {Using Accurate Arithmetics to Improve Numerical Reproducibility and Stability in Parallel Applications},
+  journal = JSC,
+  year = {2001},
+  volume = {18},
+  pages = {259--277},
+}
+
+@ARTICLE{Hirt_al_JCP74,
+  author = {C. W. Hirt and A. A. Amsden and J. L. Cook},
+  title = {An Arbitrary Lagrangian--Eulerian Computing Method for All Flow Speeds},
+  journal = JCP,
+  year = {1974},
+  volume = {14},
+  pages = {227--253}
+}
+
+@ARTICLE{Hofmeister_al_OM09,
+  author = {R. Hofmeister and H. Burchard and J.-M. Beckers},
+  title = {Non-uniform adaptive vertical grids for 3D numerical ocean models},
+  journal = OM,
+  year = {2009},
+  volume = {33},
+  pages = {70--86},
+  doi = {10.1016/j.ocemod.2009.12.003},
+  issn = {1463-5003},
+}
+
+@ARTICLE{Holland1999, 
+  author = {D. Holland and A. Jenkins},
+  title = {Modeling Thermodynamic Ice-Ocean Interactions at the Base of an Ice Shelf},
+  journal = JPO,
+  year = {1999},
+  volume = {29},  
+  pages = {1787--1800},
+}
+
+@ARTICLE{HollowayOM86,
+  author = {Greg Holloway},
+  title = {A Shelf Wave/Topographic Pump Drives Mean Coastal Circulation (part I)},
+  journal = OM,
+  year = {1986},
+  volume = {68},  
+}
+
+@ARTICLE{HollowayJPO92,
+  author = {Greg Holloway},
+  title = {Representing Topographic Stress for Large-Scale Ocean Models},
+  journal = JPO,
+  year = {1992},
+  volume = {22},  
+  pages = {1033--1046},
+}
+
+@ARTICLE{HollowayJPO94,
+  author = {Michael Eby and Greg Holloway},
+  title = {Sensitivity of a Large-Scale Ocean Model to a Parameterization of Topographic Stress},
+  journal = JPO,
+  year = {1994},
+  volume = {24},  
+  pages = {2577--2587},
+}
+
+@ARTICLE{HollowayJGR09,
+  author = {Greg Holloway and Zeliang Wang},
+  title = {Representing eddy stress in an Arctic Ocean model},
+  journal = JGR,
+  year = {2009},
+  doi = {10.1029/2008JC005169},  
+}
+
+@ARTICLE{HollowayOM08,
+  author = {Mathew Maltrud and Greg Holloway},
+  title = {Implementing biharmonic neptune in a global eddying ocean model},
+  journal = OM,
+  year = {2008},
+  volume = {21},  
+  pages = {22--34},
+}
+
+@ARTICLE{Hordoir_al_CD08,
+  author = {R. Hordoir and J. Polcher and J.-C. Brun-Cottan and G. Madec},
+  title = {Towards a parametrization of river discharges into ocean general
+	circulation models: a closure through energy conservation},
+  journal = CD,
+  year = {2008},
+  volume = {31},  number = {7-8},
+  pages = {891--908},
+  doi = {10.1007/s00382-008-0416-4},
+}
+
+@ARTICLE{Hsu1990,
+  author = {Hsu, Yueh-Jiuan G. and Arakawa, Akio},
+  title = {Numerical Modeling of the Atmosphere with an Isentropic Vertical Coordinate},
+  journal = MWR,
+  year = {1990},
+  volume = {118},  number = {10},
+  pages = {1933--1959},
+}
+
+@ARTICLE{Huang_JPO93,
+  author = {R.X. Huang},
+  title = {Real freshwater flux as a natural boundary condition for the salinity
+	balance and thermohaline circulation forced by evaporation and precipitation},
+  journal = JPO,
+  year = {1993},
+  volume = {23},
+  pages = {2428--2446}
+}
+
+@TECHREPORT{Hunke2008,
+  author = {E.C. Hunke and W.H. Lipscomb},
+  title = {CICE: the Los Alamos sea ice model documentation and software user's manual, 
+        Version 4.0},
+  institution = { Los Alamos National Laboratory, N.M.},
+  publisher = {LA-CC-06-012, Los Alamos National Laboratory, N.M.},
+  year = {2008}
+}
+
+@TechReport{Hunter2006,
+  Title                    = {Specification for Test Models of Ice Shelf Cavities},
+  Author                   = {J. R. Hunter},
+  Institution              = {Antarctic Climate \& Ecosystems Cooperative Research Centre Private Bag 80, Hobart, Tasmania 7001},
+  Year                     = {2006},
+}
+
+@TECHREPORT{TEOS10,
+  author = {IOC and SCOR and IAPSO},
+  title = {The international thermodynamic equation of seawater - 2010: Calculation and use of thermodynamic properties},
+  institution = {Intergovernmental Oceanographic Commission},
+  publisher = {Manuals and Guides No. 56, UNESCO (English)},
+  year = {2010},
+  pages = {196pp},
+  url = {http://www.teos-10.org/pubs/TEOS-10_Manual.pdf}
+}
+
+@ARTICLE{Iudicone_al_JPO08b,
+  author = {D. Iudicone and G. Madec and B. Blanke and S. Speich},
+  title = {The role of Southern Ocean surface forcings and mixing in the global conveyor},
+  journal = JPO,
+  year = {2008},
+  volume = {38},
+  pages = {1377--1400}
+}
+
+@ARTICLE{Iudicone_al_JPO08a,
+  author = {D. Iudicone and G. Madec and T. J. McDougall},
+  title = {Diagnosing water transformations and the key role of light penetration},
+  journal = JPO,
+  year = {2008},
+  volume = {38},
+  pages = {1357--1376}
+}
+
+@ARTICLE{Iudicone_al_JPO07,
+  author = {D. Iudicone and K. Rodgers and R. Schopp and G. Madec},
+  title = {An Exchange window for the Antarctic Intermediate Water Injection into the South Pacific},
+  journal = JPO,
+  year = {2007},
+  volume = {37},
+  pages = {31--49}
+}
+
+@ARTICLE{Iudicone_al_JPO08c,
+  author = {D. Iudicone and S. Speich and G. Madec and B. Blanke},
+  title = {The global Conveyor Belt in a Southern Ocean perspective},
+  journal = JPO,
+  year = {2008},
+  volume = {38},
+  pages = {1401--1425}
+}
+
+@ARTICLE{Izumo_al_CD10,
+  author = {T. Izumo and S.Masson and J. Vialard and C. de Boyer Montegut and
+	S. K. Behera and G. Madec and K. Takahashi and T. Yamagata},
+  title = {Interannual variations of low-frequency Madden-Julian Oscillation in autral summer: Observations},
+  journal = CD,
+  year = {2010},
+  volume = {35},  number = {4},
+  pages = {669--683},
+  doi = {10.1007/s00382-009-0655-z}
+}
+
+@ARTICLE{JackMcD1995,
+  author = {D. R. Jackett and T. J. McDougall},
+  title = {Minimal adjustment of hydrographic data to achieve static stability},
+  journal = JAOT,
+  year = {1995},
+  volume = {12},
+  pages = {381--389}
+}
+
+@article{Jackson_Rehmann_JPO2014,
+	author = {P. R. Jackson and C. R. Rehmann},
+	title = {Experiments on differential scalar mixing in turbulence in a sheared, stratified flow},
+	journal = JPO,
+	volume = {44},
+	issn = {0022-3670},
+	doi = {10.1175/JPO-D-14-0027.1},
+	number = {10},
+	year = {2014},
+	pages = {2661--2680},
+}
+
+@ARTICLE{Jayne_St_Laurent_GRL01,
+  author = {S.R. Jayne and L.C. {St. Laurent}},
+  title = {Parameterizing tidal disspiation over rough topography},
+  journal = GRL,
+  pages = {811--814}
+}
+
+@ARTICLE{Jenkins1991,
+  author = {A. Jenkins},
+  title = {A one-dimensional model of ice shelf-ocean interaction},
+  journal = JGR,
+  year = {1991},
+  volume = {96},  number = {C11},
+  pages = {2298--2312}
+}
+
+@ARTICLE{Jenkins2001,
+  author = {A. Jenkins},
+  title = {The Role of Meltwater Advection in the Formulation of Conservative Boundary Conditions at an Ice-Ocean Interface},
+  journal = JPO,
+  year = {2001},
+  volume = {31},
+  pages = {285--296}
+}
+
+@ARTICLE{Jenkins2010,
+  author = {A. Jenkins},
+  title = {observation and parameterization of ablation at the base of Ronne Ice Shelf, Antarctica},
+  journal = JPO,
+  year = {2010},
+  volume = {40},  number = {10},
+  pages = {2298--2312}
+}
+
+@BOOK{Jerlov_Bk68,
+  title = {Optical Oceanography},
+  publisher = {Elsevier},
+  year = {1968},
+  author = {N. G. Jerlov},
+  pages = {194pp}
+}
+
+@ARTICLE{Jones_MWR99,
+  author = {P. W. Jones},
+  title = {First- and second-order conservative remapping schemes for grids in spherical coordinates},
+  journal = MWR,
+  year = {1999},
+  volume = {127},
+  pages = {2204--2210}
+}
+
+@BOOK{Jones_Bk01,
+  title = {A User's Guide for SCRIP: A Spherical Coordinate Remapping and Interpolation Package. Version 1.4},
+  publisher = {Los Alamos National Laboratory},
+  year = {2001},
+  author = {P. W. Jones},
+  pages = {27pp},
+  url = {http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf}
+}
+
+@TECHREPORT{Jones_1998,
+  title = {A User's Guide for SCRIP: A Spherical Coordinate Remapping and Interpolation Package. Version 1.4},
+  institution = {Los Alamos National Laboratory},
+  year = {1998},
+  author = {P. W. Jones},
+  url = {http://climate.lanl.gov/Software/SCRIP/SCRIPusers.pdf}
+} 
+
+@ARTICLE{Kantha_Clayson_1994,
+  author = {L. H. Kantha and C. A. Clayson},
+  title = {An improved mixed layer model for geophysical applications},
+  journal = JGR,
+  year = {1994},
+  volume = {99},
+  pages = {25,235--25,266}
+}
+
+@ARTICLE{Kantha_Carniel_CSR05,
+  author = {L. Kantha and S. Carniel},
+  title = {Comment on ''Generic length-scale equation for geophysical turbulence models'' by L. Umlauf and H. Burchard},
+  journal = JMS, 
+  year = {2005},
+  volume = {61},
+  pages = {693--702}
+}
+
+@ARTICLE{Kasahara_MWR74,
+  author = {A. Kasahara},
+  title = {Various vertical coordinate systems used for numerical weather prediction},
+  journal = MWR,
+  year = {1974},
+  volume = {102},
+  pages = {509--522}
+}
+
+@ARTICLE{Killworth_al_JPO91,
+  author = {P.D. Killworth and D. Stainforth and D.J. Webb and S.M. Paterson},
+  title = {The Development of a Free-Surface Bryan-Cox-Semtner Ocean Model},
+  journal = JPO,
+  year = {1991},
+  volume = {21},  number = {9},
+  pages = {1333--1348}
+}
+
+@INPROCEEDINGS{Killworth1989,
+  author = {P. D. Killworth},
+  title = {On the parameterization of deep convection in ocean models},
+  booktitle = {Parameterization of small-scale processes},
+  year = {1989},
+  editor = {Hawaiian winter workshop},
+  month = {January 17-20},
+  organization = {University of Hawaii at Manoa}
+}
+
+@ARTICLE{Killworth1992,
+  author = {P. D. Killworth},
+  title = {An equivalent-barotropic mode in the fine resolution Antarctic model},
+  journal = JPO,
+  year = {1992},
+  volume = {22},
+  pages = {1379--1387}
+}
+
+@ARTICLE{Koch-Larrouy_al_CD10,
+  author = {A. Koch-Larrouy and M. Lengaigne and P. Terray and G. Madec and S. Masson},
+  title = {Tidal mixing in the Indonesian Seas and its effect on the tropical climate system},
+  journal = CD,
+  year = {2010},
+  volume = {34},  number = {6},
+  pages = {891--904},
+  doi = {10.1007/s00382-009-0642-4},
+}
+
+@ARTICLE{Koch-Larrouy_al_OD08b,
+  author = {A. Koch-Larrouy and G. Madec and B. Blanke and R. Molcard},
+  title = {Water mass transformation along the Indonesian throughflow in an OGCM},
+  journal = OD,
+  year = {2008},
+  volume = {58},  number = {3-4},
+  pages = {289--309},
+  doi = {10.1007/s10236-008-0155-4},
+}
+
+@ARTICLE{Koch-Larrouy_al_GRL07,
+  author = {A. Koch-Larrouy and G. Madec and P. Bouruet-Aubertot and T. Gerkema and L. Bessieres and R. Molcard},
+  title = {Tidal mixing in the Indonesian Seas and its effect on the tropical climate system},
+  journal = GRL,
+  year = {2007},
+  volume = {34},
+  pages = {L04604},
+  doi = {10.1029/2006GL028405},
+}
+
+@ARTICLE{Koch-Larrouy_al_OD08a,
+  author = {A. Koch-Larrouy and G. Madec and D. Iudicone and A. Atmadipoera and R. Molcard},
+  title = {Physical processes contributing to the water mass transformation of the Indonesian Throughflow},
+  journal = OD,
+  year = {2008},
+  volume = {58},  number = {3-4},
+  pages = {275--288},
+  doi = {10.1007/s10236-008-0154-5},
+}
+
+@ARTICLE{Kolmogorov1942,
+  author = {A. N. Kolmogorov},
+  title = {The equation of turbulent motion in an incompressible fluid},
+  journal = {Izv. Akad. Nauk SSSR, Ser. Fiz.},
+  year = {1942},
+  volume = {6},
+  pages = {56--58}
+}
+@ARTICLE{Kondo1975,
+  author = {J. Kondo},
+  title = {Air-sea bulk transfer coefficients in diabatic conditions},
+  journal = {Boundary-Layer Meteorol},
+  year = {1975},
+  volume = {9},
+  pages = {91--112}
+}
+
+@article{Lemarie_OM2012,
+author = "F. Lemari\'{e} and L. Debreu and A.F. Shchepetkin and J.C. McWilliams",
+title = "On the stability and accuracy of the harmonic and biharmonic isoneutral mixing operators in ocean models ",
+journal = OM,
+year = "2012",
+volume = "52–53", pages = "9--35",
+issn = "1463-5003",
+doi = "http://dx.doi.org/10.1016/j.ocemod.2012.04.007",
+}
+
+
+@ARTICLE{Lemarie_OM2015,
+  author = {F. Lemari\'{e} and L. Debreu and J. Demange and  G. Madec and J.M. Molines and M. Honnorat},
+  title = {Stability Constraints for Oceanic Numerical Models: 
+           Implications for the Formulation of time and space Discretizations},
+  journal = OM,
+  year = {2015},
+  volume = {92}, 
+  pages = {124--148},
+  doi = {10.1016/j.ocemod.2015.06.006},
+}
+
+@ARTICLE{Lermusiaux2001,
+  author = {P. F. J. Lermusiaux},
+  title = {Evolving the subspace of three-dimensional miltiscale ocean variability: Massachusetts Bay},
+  journal = JMS,
+  year = {2001},
+  volume = {29},
+  pages = {385--422}
+}
+
+@PHDTHESIS{Levy_PhD96,
+  author = {M. L\'{e}vy},
+  title = {Mod\'{e}lisation des processus biog\'{e}ochimiques en M\'{e}diterran\'{e}e
+	        nord-occidentale. Cycle saisonnier et variabilit\'{e} m\'{e}so\'{e}chelle},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France, 207pp},
+  year = {1996}
+}
+
+@ARTICLE{Levy_al_GRL01,
+  author = {M. L\'{e}vy and A. Estubier and G Madec},
+  title = {Choice of an advection scheme for biogeochemical models},
+  journal = GRL,
+  year = {2001},
+  volume = {28}
+}
+
+@ARTICLE{Levy_al_OM10,
+  author = {M. L\'{e}vy and P. Klein and A.-M. Tr\'{e}guier and D. Iovino and
+	G. Madec and S. Masson and T. Takahashi},
+  title = {Impacts of sub-mesoscale physics on idealized gyres},
+  journal = OM,
+  year = {2010},
+  volume = {34},  number = {1-2},
+  doi = {10.1016/j.ocemod.2010.04.001},
+}
+
+@ARTICLE{Levy_al_JMS99,
+  author = {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
+  title = {The onset of a bloom after deep winter convection in the Northwestern
+	Mediterranean Sea: mesoscale process study with a primitive equation
+	model},
+  journal = JMS,
+  year = {1999},
+  volume = {16},  number = {1-2},
+  pages = {7--21}
+}
+
+@ARTICLE{Levy_al_DSR98,
+  author = {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
+  title = {The onset of the spring bloom in the MEDOC area: mesoscale spatial
+	variability},
+  journal = DSR,
+  year = {1998},
+  volume = {I},  number = {46},
+  pages = {1137--1160}
+}
+
+@ARTICLE{Levy_al_DSR00,
+  author = {M. L\'{e}vy and L. M\'{e}mery and G. Madec},
+  title = {Combined effects of mesoscale processes and atmospheric high-frequency
+	variability on the spring bloom in the MEDOC area},
+  journal = DSR,
+  year = {2000},
+  volume = {47},
+  pages = {527--531}
+}
+
+@BOOK{Large_Yeager_Rep04,
+  title = {Diurnal to decadal global forcing for ocean and sea-ice models: the data sets and flux climatologies},
+  publisher = {NCAR Technical Note, NCAR/TN-460+STR, CGD Division of the National Center for Atmospheric Research},
+  year = {2004},
+  author = {W. G. Large and S. Yeager}}
+
+@ARTICLE{Large_al_RG94,
+  author = {W. G. Large and J. C. McWilliams and S. C. Doney},
+  title = {Oceanic vertical mixing - a review and a model with a nonlocal boundary layer parameterization},
+  journal = {Reviews of Geophysics},
+  year = {1994},
+  volume = {32},
+  pages = {363--404},
+  doi = {10.1029/94RG01872},
+}
+
+@ARTICLE{Latif_al_JC06,
+  author = {M. Latif and C. Böning and J. Willebrand and A. Biastoch and J. Dengg
+	and N. Keenlyside and U. Schweckendiek and G. Madec},
+  title = {Is the Thermohaline Circulation Changing?},
+  journal = JC,
+  year = {2006},
+  volume = {19},
+  pages = {4631--4637}
+}
+
+@PHDTHESIS{Lazar_PhD97,
+  author = {A. Lazar},
+  title = {La branche froide de la circulation thermohaline - sensibilit\'{e}
+	\`{a} la diffusion turbulente dans un mod\`{e}le de circulation g\'{e}n\'{e}rale
+	id\'{e}alis\'{e}e},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France, 200pp},
+  year = {1997}
+}
+
+@ARTICLE{Lazar_al_JPO99,
+  author = {A. Lazar and G. Madec and P. Delecluse},
+  title = {The Deep Interior Downwelling, the Veronis Effect, and Mesoscale
+	Tracer Transport Parameterizations in an OGCM},
+  journal = JPO,
+  year = {1999},
+  volume = {29},  number = {11},
+  pages = {2945--2961},
+}
+
+@ARTICLE{Le_Sommer_al_OM09,
+  author = {J. {Le Sommer} and T. Penduff and S. Theetten and G. Madec and B.
+	Barnier},
+  title = {How momentum advection schemes influence current-topography interactions
+	at eddy permitting resolution},
+  journal = OM,
+  year = {2009},
+  volume = {29},  number = {1},
+  pages = {1--14},
+  doi = {10.1016/j.ocemod.2008.11.007},
+}
+
+@PHDTHESIS{Leclair_PhD2010,
+  author = {M. Leclair},
+  title = {introduction d'une coordonn\'{e}e verticale arbitrairement Lagrangienne
+	Eul\'{e}rienne dans le code NEMO, 180pp.},
+  school = {Universit\'{e} Pierre and Marie Curie},
+  year = {2010}
+}
+
+@ARTICLE{Leclair_Madec_OM09,
+  author = {M. Leclair and G. Madec},
+  title = {A conservative leap-frog time stepping method},
+  journal = OM,
+  year = {2009},
+  volume = {30},  number = {2-3},
+  pages = {88-94},
+  doi = {10.1016/j.ocemod.2009.06.006},
+}
+
+@ARTICLE{Leclair_Madec_OM11,
+  author = {M. Leclair and G. Madec},
+  title = {$\tilde{z}$-coordinate, an Arbitrary Lagrangian-Eulerian coordinate separating high and low frequency},
+  journal = OM,
+  year = {2011},
+  volume = {37},  pages = {139--152}, 
+  doi = {10.1016/j.ocemod.2011.02.001},
+}
+
+@ARTICLE{Lele_JCP1992,
+  author = {S.K. Lele},
+  title = {Compact finite difference schemes with spectral-like resolution},
+  journal = JCP,
+  year = {1992},
+  volume = {103}, pages = {16--42}
+}
+
+@ARTICLE{Lengaigne_al_JC03,
+  author = {M. Lengaigne and J.-P. Boulanger and C. Menkes and G. Madec and P.
+	Delecluse and E. Guilyardi, and J. Slingo},
+  title = {The March 1997 Westerly Wind Event and the onset of the 1997/98 El
+	Niño: Understanding the role of the atmospheric},
+  journal = JC,
+  year = {2003},
+  volume = {16},  number = {20}, pages = {3330--3343}
+}
+
+@ARTICLE{Lengaigne_al_JGR02,
+  author = {M. Lengaigne and J.-P. Boulanger and C. Menkes and S. Masson and
+	G. Madec and P. Delecluse},
+  title = {Ocean response to the March 1997 Westerly Wind Event},
+  journal = JGR,
+  year = {2002},
+  doi = {10.1029/2001JC000841},
+}
+
+@ARTICLE{Lengaigne_al_JGR03,
+  author = {M. Lengaigne and G. Madec and G. Alory and C. Menkes},
+  title = {Sensitivity of the tropical Pacific Ocean to isopycnal diffusion
+	on tracer and dynamics},
+  journal = JGR,
+  year = {2003},
+  volume = {108},  number = {C11},
+  pages = {3345},
+  doi = {10.1029/2002JC001704},
+}
+
+@ARTICLE{Lengaigne_al_GRL09,
+  author = {M. Lengaigne and G. Madec and L. Bopp and C. Menkes and O. Aumont and P. Cadule},
+  title = {Bio-physical feedbacks in the Arctic Ocean using an Earth System model},
+  journal = GRL,
+  year = {2009},
+  volume = {36},  
+  pages = {L21602},
+  doi = {10.1029/2009GL040145},
+}
+
+@ARTICLE{Lengaigne_al_CD07,
+  author = {M. Lengaigne and C. Menkes and O. Aumont and T. Gorgues and L. Bopp and J.-M. Andr\'{e} G. Madec},
+  title = {Bio-physical feedbacks on the tropical Pacific climate in a Coupled
+	General Circulation Model},
+  journal = CD,
+  year = {2007},
+  volume = {28},
+  pages = {503--516}
+}
+
+@ARTICLE{Leonard1991,
+  author = {B. P. Leonard},
+  title = {The ULTIMATE conservative difference scheme applied to unsteady one--dimensional advection},
+  journal = {Computer Methods in Applied Mechanics and Engineering},
+  year = {1991},
+  pages = {17--74}
+}
+
+@TECHREPORT{Leonard_Rep88,
+  author = {B. P. Leonard},
+  title = {Universal limiter for transient interpolation modelling of the advective transport equations},
+  institution = {Technical Memorandum TM-100916 ICOMP-88-11, NASA},
+  year = {1988}
+}
+
+@ARTICLE{Leonard1979,
+  author = {B. P. Leonard},
+  title = {A stable and accurate convective modelling procedure based on quadratic
+	upstream interpolation},
+  journal = {Computer Methods in Applied Mechanics and Engineering},
+  year = {1979},
+  volume = {19},
+  pages = {59--98},
+}
+
+@TECHREPORT{Levier2007,
+  author = {B. Levier and A.-M. Tr\'{e}guier and G. Madec and V. Garnier},
+  title = {Free surface and variable volume in the NEMO code},
+  institution = {MERSEA MERSEA IP report WP09-CNRS-STR-03-1A, 47pp, available on the
+	NEMO web site},
+  year = {2007}
+}
+
+@BOOK{levitus82,
+  title = {Climatological Atlas of the world ocean},
+  publisher = {NOAA professional paper No. 13, 174pp},
+  year = {1982},
+  author = {S Levitus },
+  pages = {173 pp}
+}
+
+@ARTICLE{Li_al_OM2017},
+   AUTHOR = {Q Li and B Fox-Kemper and {\O} Breivik and A Webb},
+   YEAR = {2017},
+   TITLE = {Statistical Models of Global Langmuir Mixing}, 
+   JOURNAL = {OM},
+   VOLUME = {113},
+   ISSUE = {May},
+   PAGES = {95--114},
+   DOI = {10.1016/j.ocemod.2017.03.016}
+}
+
+@ARTICLE{Li_Garrett_JMR93,
+  author = {M. Li and C. Garrett},
+  title = {Cell merging and the jet/downwelling ratio in Langmuir circulation},
+  journal = JMR,
+  year = {1993},
+  volume = {51},
+  pages = {737--769}
+}
+
+@ARTICLE{Losch2008,
+  author = {M. Losch},
+  title = {Modeling ice shelf cavities in a z coordinate ocean general circulation model},
+  journal = JGR,
+  year = {2008},
+  volume = {113},  number = {C13},
+}
+
+@TECHREPORT{Lott1989,
+  author = {F. Lott and G. Madec},
+  title = {Implementation of bottom topography in the Ocean General Circulation
+	Model OPA of the LODYC: formalism and experiments.},
+  institution = {LODYC, France, 36pp.},
+  year = {1989},
+  number = {3}
+}
+
+@ARTICLE{Lott_al_OM90,
+  author = {F. Lott and G. Madec and J. Verron},
+  title = {Topographic experiments in an Ocean General Circulation Model},
+  journal = OM,
+  year = {1990},
+  volume = {88},
+  pages = {1--4}
+}
+
+@ARTICLE{Luo_al_JC05,
+  author = {J.-J. Luo and S. Masson and E. Roeckner and G. Madec and T. Yamagata},
+  title = {Reducing climatology bias in an ocean-atmosphere CGCM with improved
+	coupling physics},
+  journal = JC,
+  year = {2005},
+  volume = {18},  number = {13},
+  pages = {2344--2360}
+}
+
+@BOOK{Madec_Bk08,
+  title = {NEMO ocean engine},
+  publisher = {Note du P\^ole de mod\'{e}lisation, Institut Pierre-Simon Laplace
+	(IPSL), France, No 27, ISSN No 1288-1619},
+  year = {2008},
+  author = {G. Madec}
+}
+
+@BOOK{Madec_HDR01,
+  title = {Le Cycle des Masses d'Eau Oc\'{e}aniqueset sa variabilit\'{e} dans le Syst\'{e}me Climatique},
+  year = {2001},
+  author = {G. Madec},
+  pages = {63pp.},
+  series = {Habilitation \'{a} Diriger des Recherches, Universit\'{e} Pierre et Marie Curie}
+}
+
+@PHDTHESIS{Madec_PhD90,
+  author = {G. Madec},
+  title = {La formation d'eau profonde et son impact sur la circulation r\'{e}gionale
+	en M\'{e}diterran\'{e}e Occidentale - une approche num\'{e}rique},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France, 194pp.},
+  year = {1990},
+  month = {2 mai}
+}
+
+@ARTICLE{Madec_al_DAO91,
+  author = {G. Madec and M. Chartier and M. Cr\'{e}pon},
+  title = {Effect of thermohaline forcing variability on deep water formation
+	in the Northwestern Mediterranean Sea - a high resulution three-dimensional
+	study},
+  journal = DAO,
+  year = {1991},
+  volume = {15},
+  pages = {301--332}
+}
+
+@ARTICLE{Madec_al_JPO91,
+  author = {G. Madec and M. Chartier and P. Delecluse and M. Cr\'{e}pon},
+  title = {A three-dimensional numerical study of deep water formation in the Northwestern Mediterranean Sea .},
+  journal = JPO,
+  year = {1991},
+  volume = {21},
+  pages = {1349--1371}
+}
+
+@INBOOK{Madec_Crepon_Bk91,
+  chapter = {Thermohaline-driven deep water formation in the Northwestern Mediterranean
+	Sea},
+  pages = {241--265},
+  title = {Deep convection and deep water formation in the oceans},
+  publisher = {Elsevier Oceanographic Series, P.C. Chu and J.C. Gascard (Eds.)},
+  year = {1991},
+  author = {G. Madec and M. Cr\'{e}pon}
+}
+
+@ARTICLE{Madec1997,
+  author = {G. Madec and P. Delecluse},
+  title = {The OPA/ARPEGE and OPA/LMD Global Ocean-Atmosphere Coupled Model},
+  journal = {Int. WOCE Newsletter},
+  year = {1997},
+  volume = {26},
+  pages = {12--15}
+}
+
+@TECHREPORT{Madec1998,
+  author = {G. Madec and P. Delecluse and M. Imbard and C. Levy},
+  title = {OPA 8 Ocean General Circulation Model - Reference Manual},
+  institution = {LODYC/IPSL Note 11},
+  year = {1998}
+}
+
+@ARTICLE{Madec_Imbard_CD96,
+  author = {G Madec and M Imbard},
+  title = {A global ocean mesh to overcome the north pole singularity},
+  journal = CD,
+  year = {1996},
+  volume = {12},
+  pages = {381--388}
+}
+
+@ARTICLE{Madec_al_JPO96,
+  author = {G. Madec and F. Lott and P. Delecluse and M. Cr\'{e}pon},
+  title = {Large-Scale Preconditioning of Deep-Water Formation in the Northwestern
+	Mediterranean Sea},
+  journal = JPO,
+  year = {1996},
+  volume = {26},  number = {8},
+  pages = {1393--1408},
+}
+
+@ARTICLE{Madec_al_OM88,
+  author = {G. Madec and C. Rahier and M. Chartier},
+  title = {A comparison of two-dimensional elliptic solvers for the streamfunction
+	in a multilevel OGCM},
+  journal = OM,
+  year = {1988},
+  volume = {78},
+  pages = {1-6}
+}
+
+@ARTICLE{Maes_al_CD98,
+  author = {C. Maes and P. Delecluse and G. Madec},
+  title = {Impact of westerly wind bursts on the warm pool of the TOGA-COARE
+	domain in an OGCM},
+  journal = CD,
+  year = {1998},
+  volume = {14},
+  pages = {55--70}
+}
+
+@ARTICLE{Maes_al_MWR97,
+  author = {C. Maes and G. Madec and P. Delecluse},
+  title = {Sensitivity of an Equatorial Pacific OGCM to the lateral diffusion},
+  journal = MWR,
+  year = {1997},
+  volume = {125},  number = {5},
+  pages = {958--971}
+}
+
+@ARTICLE{Maggiore_al_PCE98,
+  author = {A. Maggiore and  M. Zavatarelli and M. G. Angelucci and N. Pinardi},
+  title = {Surface heat and water fluxes in the Adriatic Sea: seasonal and interannual variability},
+  journal = {Phys Chem Earth},
+  year = {1998},
+  volume = {23},
+  pages = {561--567}
+}
+
+@ARTICLE{Maltrud1998,
+  author = {M. E. Maltrud and R. D. Smith and A. J. Semtner and R. C. Malone},
+  title = {Global eddy-resolving ocean simulations driven by 1985-1995 atmospheric
+	winds},
+  journal = JGR,
+  year = {1998},
+  volume = {103},  number = {C13},
+  pages = {30,825--30,854}
+}
+
+@ARTICLE{Marchesiello2001,
+  author = { P. Marchesiello and J. Mc Williams and A. Shchepetkin },
+  title = {Open boundary conditions for long-term integrations of Regional Oceanic
+	Models},
+  journal = OM,
+  year = {2001},
+  volume = {3},
+  pages = {1--20}
+}
+
+@ARTICLE{Marsaleix_al_OM08,
+  author = {P. Marsaleix and F. Auclair and J. W. Floor and M. J. Herrmann and
+	C. Estournel and I. Pairaud and C. Ulses},
+  title = {Energy conservation issues in sigma-coordinate free-surface ocean
+	models},
+  journal = OM,
+  year = {2008},
+  volume = {20},  number = {1},
+  pages = {61--89},
+  doi = {10.1016/j.ocemod.2007.07.005},
+}
+
+@Article{Marsh_GMD2015,
+AUTHOR = {R. Marsh and V. O. Ivchenko and N. Skliris and S. Alderson and G. R. Bigg and G. Madec and A. T. Blaker and Y. Aksenov and B. Sinha and A. C. Coward and J. Le Sommer and N. Merino and V. B. Zalesny},
+TITLE = {NEMO-ICB (v1.0): interactive icebergs in the NEMO ocean model globally configured at eddy-permitting resolution},
+JOURNAL = {Geoscientific Model Development},
+VOLUME = {8},
+YEAR = {2015},
+NUMBER = {5},
+PAGES = {1547--1562},
+DOI = {10.5194/gmd-8-1547-2015}
+}
+
+@article{Martin_Adcroft_OM10,
+author = {T. Martin and A. Adcroft},
+title = {Parameterizing the fresh-water flux from land ice to ocean with interactive icebergs in a coupled climate model},
+journal = OM,
+year = {2010},
+volume = {34}, number = {3--4},
+pages = {111--124},
+issn = {1463-5003},
+doi = {10.1016/j.ocemod.2010.05.001},
+}
+
+@BOOK{MIT-GCM_2004,
+  title = {MIT-gcm User Manual},
+  year = {2004},
+  editor = {MIT Department of EAPS},
+  author = {J. Marshall and A. Adcroft and J.-M. Campin and P. Heimbach and A.
+	Molod and S. Dutkiewicz and H. Hill and M. Losch and B. Fox-Kemper
+	and D. Menemenlis and D. Ferreira and E. Hill and M. Follows and
+	C. Hill and C. Evangelinos and G. Forget}
+	}
+
+@PHDTHESIS{Marti_PhD92,
+  author = {O. Marti},
+  title = {Etude de l'oc\'{e}an mondial : mod\'{e}lisation de la circulation
+	et du transport de traceurs anthropog\'{e}niques},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France, 201pp},
+  year = {1992}
+}
+
+@ARTICLE{Marti_al_CD10,
+  author = {O. Marti and P. Braconnot and J.-L. Dufresne and J. Bellier and R.
+	Benshila and S. Bony and P. Brockmann and P. Cadule and A. Caubel
+	and F Codron and S. Denvil and L. Fairhead and T. Fichefet and M.-A.
+	Filiberti and M.-A. Foujols and P. Friedlingstein and H. Goosse and
+	J.-Y. Grandpeix and E. Guilyardi and F. Hourdin and G. Krinner and
+	C. L\'{e}vy and G. Madec and J. Mignot and I. Musat and D. Swingedouw
+	and C. Talandier},
+  title = {Key features of the IPSL ocean atmosphere model and its sensitivity
+	to atmospheric resolution},
+  journal = CD,
+  year = {2010},
+  volume = {34},  number = {1},
+  pages = {1--26},
+  doi = {10.1007/s00382-009-0640-6},
+}
+
+@ARTICLE{Marti_al_JGR92,
+  author = {O. Marti and G. Madec and P. Delecluse},
+  title = {Comment on "Net diffusivity in ocean general circulation models with
+	nonuniform grids" by F. L. Yin and I. Y. Fung},
+  journal = JGR,
+  year = {1992},
+  volume = {97},
+  pages = {12,763--12,766}
+}
+
+@INBOOK{Masson_al_Bk08,
+  chapter = {OPA9 - French experiments on the Earth Simulator and Teraflop Workbench
+	tunings},
+  pages = {25-34},
+  title = {In High Performance computing on Vector System 2007, Stuttgart, Germany},
+  publisher = {Springer-Verlag},
+  year = {2008},
+  editor = {Resch M, Roller S, Lammers P, Furui T, Galle M, Bez W},
+  author = {S. Masson and M.-A. Foujols and P. Klein and G. Madec and L. Hua and M. Levy 
+  and H. Sasaki and K. Takahashi and F. Svensson},
+  doi = {10.1007/978-3-540-74384-2},
+}
+
+@ARTICLE{Masson_al_GRL05,
+  author = {S. Masson and J.-J. Luo and G. Madec and J. Vialard and F. Durand
+	and S. Gualdi and E. Guilyardi and S. Behera and P. Delecluse and
+	A. Navarra and T. Yamagata},
+  title = {Impact of barrier layer on winter-spring variability of the South-Eastern
+	Arabian Sea},
+  journal = GRL,
+  year = {2005},
+  volume = {32},
+  pages = {L07703},
+  doi = {10.1029/2004GL021980},
+}
+
+@ARTICLE{McDougall1987,
+  author = {T. J. McDougall},
+  title = {Neutral Surfaces},
+  journal = JPO,
+  year = {1987},
+  volume = {17},  number = {11},
+  pages = {1950--1964},
+}
+
+@ARTICLE{McDougall_Taylor_JMR84,
+  author = {T. J. McDougall and J. R. Taylor},
+  title = {Flux measurements across a finger interface at low values of the stability ratio},
+  journal = JMR,
+  year = {1984},
+  volume = {42},
+  pages = {1--14}
+}
+
+@ARTICLE{Mellor_Blumberg_JPO04,
+author = {G. Mellor and A. Blumberg},
+title = {Wave Breaking and Ocean Surface Layer Thermal Response},
+journal = JPO,
+volume = {34}, number = {3},
+pages = {693--698},
+year = {2004},
+doi = {10.1175/2517.1},
+}
+
+@ARTICLE{Mellor_Yamada_1982,
+  author = {G. L. Mellor and T. Yamada},
+  title = {Development of a turbulence closure model for geophysical fluid problems},
+  journal = RGSP,
+  year = {1982},
+  volume = {20},
+  pages = {851--875}
+}
+
+@ARTICLE{Menkes_al_JPO06,
+  author = {C. Menkes and J. Vialard and S C. Kennan and J.-P. Boulanger and G. Madec},
+  title = {A modelling study of the three-dimensional heat budget of Tropical
+	 Instability Waves in the Equatorial Pacific},
+  journal = JPO,
+  year = {2006},
+  volume = {36},  number = {5},
+  pages = {847--865}
+}
+
+@ARTICLE{Merryfield1999,
+  author = {W. J. Merryfield and G. Holloway and A. E. Gargett},
+  title = {A Global Ocean Model with Double-Diffusive Mixing},
+  journal = JPO,
+  year = {1999},
+  volume = {29},  number = {6},
+  pages = {1124--1142}
+}
+
+@BOOK{Mesinger_Arakawa_Bk76,
+  title = {Numerical methods used in Atmospheric models},
+  publisher = {GARP Publication Series No 17},
+  year = {1976},
+  author = {F. Mesinger and A. Arakawa}
+}
+
+@ARTICLE{Morel_JGR88,
+  author = {A. Morel},
+  title = {Optical modeling of the upper ocean in relation to its biogenous matter content (Case I waters)},
+  journal = JGR,
+  year = {1988},
+  volume = {93},
+  pages = {10,749--10,768}
+}
+
+@ARTICLE{Morel_Berthon_LO89,
+  author = {A. Morel and J.-F. Berthon},
+  title = {Surface pigments, algal biomass profiles, and potential production of the euphotic layer: 
+           Relationships reinvestigated in view of remote-sensing applications},
+  journal = {Limnol. Oceanogr.},
+  year = {1989},
+  volume = {34(8)},
+  pages = {1545--1562}
+}
+
+@ARTICLE{Morel_Maritorena_JGR01,
+  author = {A. Morel and S. Maritorena},
+  title = {Bio-optical properties of oceanic waters: a reappraisal},
+  journal = JGR,
+  year = {2001},
+  volume = {106}, number = {C4},
+  pages = {7163--7180}
+}
+
+@ARTICLE{Moun_al_JPO02,
+  author = {J.N. Moum and D.R. Caldwell and J.D. Nash and G.D. Gunderson},
+  title = {Observations of boundary mixing over the continental slope},
+  journal = JPO,
+  year = {2002},
+  volume = {32}, number = {7},
+  pages = {2113--2130}
+}
+
+@ARTICLE{Murray_JCP96,
+  author = {R. J. Murray},
+  title = {Explicit Generation of Orthogonal Grids for Ocean Models},
+  journal = JCP,
+  year = {1996},
+  volume = {126},  number = {2},
+  pages = {251--273},
+}
+
+@ARTICLE{Oddo_al_OS09,
+  author = {P. Oddo and M. Adani and N. Pinardi and C. Fratianni and M. Tonani and D. Pettenuzzo},
+  title = {A nested Atlantic-Mediterranean Sea general circulation model for operational forecasting},
+  journal = OS,
+  year = {2009},
+  volume = {5},
+  pages = {1--13},
+}
+
+@PHDTHESIS{Olivier_PhD01,
+  author = {F. Olivier},
+  title = {Etude de l'activit\'{e} biologique et de la circulation oc\'{e}anique
+	dans un jet g\'{e}ostrophique: le front Alm\'{e}ria-Oran},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France},
+  year = {2001}
+}
+
+@ARTICLE{Osborn_JPO80,
+  author = {T.R. Osborn},
+  title = {Estimates of the local rate of vertical diffusion from dissipation measurements},
+  journal = JPO,
+  year = {1980},
+  volume = {10},
+  pages = {83--89}
+}
+
+@ARTICLE{Pacanowski_Philander_JPO81,
+  author = {R.C. Pacanowski and S.G.H. Philander},
+  title = {Parameterization of Vertical Mixing in Numerical Models of Tropical Oceans},
+  journal = JPO,
+  year = {1981},
+  volume = {11},  number = {11},
+  pages = {1443--1451}
+}
+
+@ARTICLE{Pacanowski_Gnanadesikan_MWR98,
+  author = {R. C. Pacanowski and A. Gnanadesikan},
+  title = {Transient response in a z-level ocean model that resolves topography with partial-cells},
+  journal = MWR,
+  year = {1998},
+  volume = {126},
+  pages = {3248--3270}
+}
+
+@ARTICLE{Park_al_JC09,
+  author = {W. Park and N. Keenlyside and M. Latif and A. Str\¨{o}h and R. Redler and E. Roeckner and G. Madec},
+  title = {Tropical Pacific Climate and its Response to Global Warming in the
+	Kiel Climate Model},
+  journal = JC,
+  year = {2009},
+  volume = {22},  number = {1},
+  pages = {71--92},
+  doi = {10.1175/2008JCLI2261.1},
+}
+
+@ARTICLE{Paulson1977,
+  author = {C. A. Paulson and J. J. Simpson},
+  title = {Irradiance Measurements in the Upper Ocean},
+  journal = JPO,
+  year = {1977},
+  volume = {7},  number = {6},
+  pages = {952--956}
+}
+
+@ARTICLE{Payne_JAS72,
+  author = {R. E. Payne},
+  title = {Albedo of the Sea Surface},
+  journal = JAS,
+  year = {1972},
+  volume = {29},
+  pages = {959--970}
+}
+
+@ARTICLE{Penduff_al_OM06,
+  author = {T. Penduff and B. Barnier and J.-M. Molines and G. Madec},
+  title = {On the use of current meter data to assess the realism of ocean model simulations},
+  journal = OM,
+  year = {2006},
+  volume = {11},  number = {3--4},
+  pages = {399--416}
+}
+
+@ARTICLE{Penduff_al_JGR00,
+  author = {T. Penduff and B. Barnier and A. Colin de Verdi\`{e}re},
+  title = {Self-adapting open boundaries for a regional model of the eastern North Atlantic},
+  journal = JGR,
+  year = {2000},
+  volume = {105},
+  pages = {11,279--11,297}
+}
+
+@ARTICLE{Penduff_al_OS07,
+  author = {T. Penduff and J. Le Sommer and B. Barnier and A.M. Treguier and J. Molines and G. Madec},
+  title = {Influence of numerical schemes on current-topography interactions
+	in 1/4$^{\circ}$ global ocean simulations},
+  journal = OS,
+  year = {2007},
+  volume = {3},
+  pages = {509--524}
+}
+
+@ARTICLE{Phillips1959,
+  author = {R. S. Phillips},
+  title = {Dissipative Operators and Hyperbolic Systems of Partial Differential Equations},
+  journal = {Transactions of the American Mathematical Society},
+  year = {1959},
+  volume = {90},  number = {2},
+  pages = {193--254},
+  doi = {10.2307/1993202},
+}
+
+@ARTICLE{Le_Quere_al_GBC00,
+  author = {C. Le Qu\'{e}r\'{e} and J. C. Orr and P. Monfray and O. Aumont and G. Madec},
+  title = {Interannual variability of the global and regional sea-air flux of C02 from 1979 to 1993},
+  journal = GBC,
+  year = {2000},
+  volume = {14},
+  pages = {1247--1266}
+}
+
+@ARTICLE{Raynaud_al_GRL00,
+  author = {S. Raynaud and S. Speich and E. Guilyardi and G. Madec},
+  title = {Impact of the ocean lateral diffusion on the ENSO-like variability of a global coupled GCM},
+  journal = GRL,
+  year = {2000},
+  volume = {27},  number = {19},
+  pages = {3041--3044}
+}
+
+@ARTICLE{Redi_JPO82,
+  author = {M. H. Redi},
+  title = {Oceanic isopycnal mixing by coordinate rotation},
+  journal = JPO,
+  year = {1982},
+  volume = {13},
+  pages = {1154--1158}
+}
+
+@ARTICLE{Reed_JPO77,
+  author = {R. K. Reed},
+  title = {On estimating insolation over the ocean},
+  journal = JPO,
+  year = {1977},
+  volume = {1},
+  pages = {874--971}
+}
+
+@ARTICLE{Reverdin1991,
+  author = {G. Reverdin and P. Delecluse and C. L\'{e}vy and P. Andrich and A. Morli\`{e}re and J. M. Verstraete},
+  title = {The near surface tropical Atlantic in 1982-1984 : results from a numerical simulation and a data analysis},
+  journal = PO,
+  year = {1991},
+  volume = {27},
+  pages = {273--340}
+}
+
+@BOOK{Richtmyer1967,
+  title = {Difference methods for initial-value problems},
+  publisher = {Interscience Publisher, Second Edition},
+  year = {1967},
+  author = {R. D. Richtmyer and K. W. Morton},
+  pages = {405pp}
+}
+
+@ARTICLE{Robert_JMSJ66,
+  author = {A. J. Robert},
+  title = {The integration of a Low order spectral form of the primitive meteorological equations},
+  journal = JMSJ,
+  year = {1966},
+  volume = {44},  number = {2}
+}
+
+@ARTICLE{Rodgers_al_GRL04,
+  author = {K. Rodgers and O. Aumont and G. Madec and C. Menkes},
+  title = {Radiocarbon as a thermocline proxy for the eastern equatorial Pacific},
+  journal = GRL,
+  year = {2004},
+  volume = {31},
+  pages = {L14314},
+  doi = {10.1029/2004GL019764},
+}
+
+@ARTICLE{Rodgers_al_GRL03,
+  author = {K. Rodgers and B. Blanke and G. Madec and O. Aumont and P. Ciais and J.-C. Dutay},
+  title = {Extratropical sources of equatorial pacific upwelling in an OGCM},
+  journal = GRL,
+  year = {2003},
+  volume = {30},  number = {2},
+  doi = {10.1029/2002GL016003},
+}
+
+@Article{Rodgers_2014,
+AUTHOR = {Rodgers, K. B. and Aumont, O. and Mikaloff Fletcher, S. E. and Plancherel, Y. and Bopp, L. and de Boyer Mont\'egut, C. and Iudicone, D. and Keeling, R. F. and Madec, G. and Wanninkhof, R.},
+TITLE = {Strong sensitivity of Southern Ocean carbon uptake and nutrient cycling to wind stirring},
+JOURNAL = {Biogeosciences},
+VOLUME = {11},
+YEAR = {2014},
+NUMBER = {15},
+PAGES = {4077--4098},
+DOI = {10.5194/bg-11-4077-2014}
+}
+
+@ARTICLE{Rodi_1987,
+  author = {W. Rodi},
+  title = {Examples of calculation methods for flow and mixing in stratified fluids},
+  journal = JGR,
+  year = {1987},
+  volume = {92},  number = {C5},
+  pages = {5305--5328}
+}
+
+@INCOLLECTION{Roed1986,
+  author = {L.P. Roed and C.K. Cooper},
+  title = {Open boundary conditions in numerical ocean models},
+  booktitle = {Advanced Physical Oceanography Numerical Modelling},
+  publisher = { NATO ASI Series, vol. 186.},
+  year = {1986},
+  editor = {J.J. O'Brien}
+}
+
+@article{Roquet_OM2015,
+author = "F. Roquet and G. Madec and T.J. McDougall and P.M. Barker",
+title = "Accurate polynomial expressions for the density and specific volume of seawater using the TEOS-10 standard ",
+journal = OM,
+volume = "90",
+pages = "29--43",
+year = "2015",
+issn = "1463-5003",
+doi = "10.1016/j.ocemod.2015.04.002",
+}
+
+@article{Roquet_JPO2015,
+author = "F. Roquet and G. Madec and L. Brodeau and J. Nycander",
+title = "Defining a Simplified Yet Realistic Equation of State for Seawater",
+journal = JPO,
+volume = "45",
+pages = "2564--2579",
+year = "2015",
+doi = "10.1175/JPO-D-15-0080.1",
+}
+
+@ARTICLE{Roullet_Madec_JGR00,
+  author = {G. Roullet and G. Madec},
+  title = {salt conservation, free surface, and varying levels: a new formulation
+	for ocean general circulation models},
+  journal = JGR,
+  year = {2000},
+  volume = {105},
+  pages = {23,927--23,942}
+}
+
+@ARTICLE{Rousset_GMD2015,
+  author = {C. Rousset and M. Vancoppenolle and G. Madec and T. Fichefet and S. Flavoni 
+            and A. Barth\'{e}lemy and R. Benshila and J. Chanut and C. L\'{e}vy and S. Masson and F. Vivier },
+  title  = {The Louvain-La-Neuve sea-ice model LIM3.6: Global and regional capabilities},
+  journal= {Geoscientific Model Development},
+  year = {2015},
+  volume = {8}, pages={2991--3005},
+  doi = {10.5194/gmd-8-2991-2015},
+}
+
+@ARTICLE{Sadourny1975,
+  author = {R. Sadourny},
+  title = {The Dynamics of Finite-Difference Models of the Shallow-Water Equations},
+  journal = JAS,
+  year = {1975},
+  volume = {32},  number = {4},
+  pages = {680--689},
+}
+
+@ARTICLE{Sarmiento1982,
+  author = {J. L. Sarmiento and K. Bryan},
+  title = {Ocean transport model for the North Atlantic},
+  journal = JGR,
+  year = {1982},
+  volume = {87},
+  pages = {394--409}
+}
+
+@ARTICLE{Saunders_JAS82,
+  author={P. M. Saunders},
+  title={{The Temperature at the Ocean-air Interface}},
+  journal=JAS,
+  year={1967},
+  volume={24},
+  pages={269-273},
+  doi = {10.1175/1520-0469(1967)024<0269:TTATOA>2.0.CO;2},
+}
+
+@BOOK{Shchepetkin_McWilliams_Bk08,
+  author = {A. F. Shchepetkin and J. C. McWilliams},
+  title = {Handbook of Numerical Analysis, Vol. XIV: Computational Methods for the Ocean and the Atmosphere, pp 121-183},
+  publisher = {P. G. Ciarlet, editor, R. Temam and J. Tribbia, guest eds., Elsevier Science},
+  year = {2008},
+  pages = {784}
+}
+
+@ARTICLE{Shchepetkin_McWilliams_OM05,
+  author = {A. F. Shchepetkin and J. C. McWilliams},
+  title = {The regional oceanic modeling system (ROMS) - a split-explicit, free-surface,
+	topography-following-coordinate oceanic modelr},
+  journal = OM,
+  year = {2005},
+  volume = {9},  number = {4},
+  pages = {347--404}
+}
+
+@ARTICLE{Sacha2003,
+  author = {A. F. Shchepetkin and J. C. McWilliams},
+  title = {A method for computing horizontal pressure-gradient force in an oceanic
+	model with a nonaligned vertical coordinate},
+  journal = JGR,
+  year = {2003},
+  volume = {108},  number = {C3},
+  pages = {3090},
+  doi = {10.1029/2001JC001047},
+}
+
+@ARTICLE{Shchepetkin1996,
+  author = {A. F. Shchepetkin and J. J. O'Brien},
+  title = {A Physically Consistent Formulation of Lateral Friction in Shallow-Water Equation Ocean Models},
+  journal = MWR,
+  year = {1996},
+  volume = {124},  number = {6},
+  pages = {1285--1300}
+}
+
+@ARTICLE{Siddorn_Furner_OM12,
+  author = {J. Siddorn and R. Furner},
+  title = {An analytical stretching function that combines the best attributes of geopotential and terrain-following vertical coordinates},
+  journal = OM,
+  year = {2012},
+  pages = {submitted},
+}
+
+@ARTICLE{Simmons_al_OM04,
+  author = {H. L. Simmons and S. R. Jayne and L. C. {St. Laurent} and A. J. Weaver},
+  title = {Tidally driven mixing in a numerical model of the ocean general circulation},
+  journal = OM,
+  year = {2004},
+  pages = {245--263},
+}
+
+@INBOOK{Smagorinsky_93,
+  author = {Smagorinsky, J.},
+  chapter = {Some historical remarks on the use of non-linear viscosities},
+  title = {Large Eddy Simulation of Complex Engineering and Geophysical Flows},
+  pages = {3--36},
+  year = {1993},
+  publisher = {Cambridge University Press, B. Galperin and S. A. Orszag (eds.)},
+}
+
+@ARTICLE{Song_Haidvogel_JCP94,
+  author = {Y. Song and D. Haidvogel},
+  title = {A semi-implicit ocean circulation model using a generalized topography-following coordinate system},
+  journal = JCP,
+  year = {1994},
+  volume = {115},  number = {1},
+  pages = {228--244}
+}
+
+@ARTICLE{Song1998,
+  author = {Y. T. Song},
+  title = {A General Pressure Gradient Formulation for Ocean Models. Part I: Scheme Design and Diagnostic Analysis},
+  journal = MWR,
+  year = {1998},
+  volume = {126},  number = {12},
+  pages = {3213--3230}
+}
+
+@ARTICLE{SongWright1998,
+  author = {Y. T. Song and D. G. Wright},
+  title = {A General Pressure Gradient Formulation for Ocean Models. 
+    Part II: Energy, Momentum, and Bottom Torque Consistency},
+  journal = MWR,
+  year = {1998},
+  volume = {126},  number = {12},
+  pages = {3231--3247}
+}
+
+@ARTICLE{Speer_al_Tel00,
+  author = {K. Speer and E. Guilyardi and G. Madec},
+  title = {Southern Ocean transformation in a coupled model with and without eddy mass fluxes},
+  journal = {Tellus},
+  year = {2000},
+  volume = {52A},  number = {5},
+  pages = {554--565}
+}
+
+@PHDTHESIS{Speich_PhD92,
+  author = {S. Speich},
+  title = {Etude du for\c{c}age de la circulation g\'{e}n\'{e}rale oc\'{e}anique
+	par les d\'{e}troits - cas de la mer d'Alboran},
+  school = {Universit\'{e} Pierre et Marie Curie, Paris, France},
+  year = {1992}
+}
+
+@ARTICLE{Speich_al_GRL01,
+  author = {S. Speich and B. Blanke and G. Madec},
+  title = {Warm and cold water paths of an OGCM thermohaline conveyor belt},
+  journal = GRL,
+  year = {2001},
+  volume = {28},  number = {2},
+  pages = {311--314}
+}
+
+@ARTICLE{Speich_al_JPO96,
+  author = {S. Speich and G. Madec and M. Cr\'{e}pon},
+  title = {The circulation in the Alboran Sea - a sensitivity study},
+  journal = JPO,
+  year = {1996},
+  volume = {26},  number = {3},
+  pages = {320--340}
+}
+
+@ARTICLE{St_Laurent_Garrett_JPO02,
+  author = {L.C. {St. Laurent} and C. Garrett},
+  title = {The role of internal tides in mixing the deep ocean},
+  journal = JPO,
+  pages = {2882--2899}
+}
+
+@ARTICLE{St_Laurent_Nash_DSR04,
+  author = {L.C. {St. Laurent} and J. D. Nash},
+  title = {An examination of the radiative and dissipative properties of deep ocean internal tides},
+  journal = DSR,
+  year = {2004},
+  volume = {II},  number = {51},
+  pages = {3029--3042},
+  doi = {10.1016/j.dsr2.2004.09.008},
+}
+
+@ARTICLE{St_Laurent_al_GRL02,
+  author = {L.C. {St. Laurent} and H.L. Simmons and S.R. Jayne},
+  title = {Estimating tidally driven mixing in the deep ocean},
+  journal = GRL,
+  year = {2002},
+  volume = {29},
+  pages = {2106},
+  doi = {10.1029/2002GL015633},
+}
+
+@ARTICLE{Stacey_JPO99,
+  author = {M. W. Stacey},
+  title = {Simulations of the wind-forced near-surface circulation in Knight Inlet: 
+             A parameterization of the roughness length},
+  journal = JPO,
+  year = {1999},
+  volume = {29},
+  pages = {1363--1367},
+}
+
+@ARTICLE{Steele2001,
+  author = {M. Steele and R. Morley and W. Ermold},
+  title = {PHC- A Global Ocean Hydrography with a High-Quality Arctic Ocean},
+  journal = JC,
+  year = {2001},
+  volume = {14},  number = {9},
+  pages = {2079--2087},
+}
+
+@ARTICLE{Stein_Stein_Nat92,
+  author = {C. A. Stein and S. Stein},
+  title = {A model for the global variation in oceanic depth and heat flow with lithospheric age},
+  journal = {Nature},
+  year = {1992},
+  volume = {359},
+  pages = {123--129}
+}
+
+@ARTICLE{Takaya_al_JGR10,
+  author = {Y. Takaya and J-R. Bidlot and A. C. M. Beljaars and 
+                  P. A. E. M. Janssen},
+  title = {Refinements to a prognostic scheme of sea surface skin temperature},
+  journal = JGR,
+  year   = 	 {2010},
+  Volume = 	 {115},
+  Pages  = 	 {C06009},
+  doi    = {10.1029/2009JC005985},
+}
+
+@ARTICLE{Talagrand_JAS72,
+  author = {O. Talagrand},
+  title = {On the damping of high-frequency motions in four-dimensional 
+           assimilation of meteorological data},
+  journal = JAS,
+  year = {1972},
+  volume = {29},
+  pages = {1571-1574}
+}
+
+@ARTICLE{Thiem_Berntsen_OM06,
+  author = {O. Thiem and J. Berntsen},
+  title = {Internal pressure errors in sigma-coordinate ocean models due to anisotropy},
+  journal = OM,
+  year = {2006},
+  volume = {12},  number = {1-2},
+}
+
+@ARTICLE{Timmermann_al_OM05,
+  author = {R. Timmermann and H. Goosse and G. Madec and T. Fichefet and C. \'{E}the and V. Duli\`{e}re},
+  title = {On the representation of high latitude processes in the ORCA-LIM global coupled sea ice-ocean model},
+  journal = OM,
+  year = {2005},
+  volume = {8},
+  pages = {175--201}
+}
+
+@ARTICLE{Tonani_al_OS08,
+  author = {M. Tonani and N. Pinardi and S. Dobricic and I. Pujol and C. Fratianni},
+  title = {A high-resolution free-surface model of the Mediterranean Sea},
+  journal = OS,
+  year = {2008},
+  volume = {4},
+  pages = {1--14}
+}
+
+@ARTICLE{Treguier_JGR92,
+  author = {A.M. Tr\'{e}guier},
+  title = {Kinetic energy analysis of an eddy resolving, primitive equation North Atlantic model},
+  journal = JGR,
+  year = {1992},
+  volume = {97},
+  pages = {687--701}
+}
+
+@ARTICLE{Treguier_al_JGR01,
+  author = {A.M. Tr\'{e}guier and B. Barnier and A.P. de Miranda and J.M. Molines
+    and N. Grima and M. Imbard and G. Madec and C. Messager and T. Reynaud and S. Michel},
+  title = {An Eddy Permitting model of the Atlantic circulation: evaluating open boundary conditions},
+  journal = JGR,
+  year = {2001},
+  volume = {106},
+  pages = {22,115--22,129}
+}
+
+@ARTICLE{Treguier_al_DSR03,
+  author = {A.-M. Tr\'{e}guier and O. Boedel and B. Barnier and G. Madec},
+  title = {Agulhas eddy fluxes in a 1/6^o Atlantic model},
+  journal = DSR,
+  year = {2003},
+  pages = {251--280}
+}
+
+@ARTICLE{Treguier1996,
+  author = {A.-M. Tr\'{e}guier and J. Dukowicz and K. Bryan},
+  title = {Properties of nonuniform grids used in ocean general circulation models},
+  journal = JGR,
+  year = {1996},
+  volume = {101},
+  pages = {20,877--20,881}
+}
+
+@ARTICLE{Treguier_al_OS07,
+  author = {A.-M. Tr\'{e}guier and M. H. England and S. R. Rintoul and G. Madec and J. Le Sommer and J.-M. Molines},
+  title = {Southern Ocean overturning across streamlines in an eddying simulation of the Antarctic Circumpolar Current},
+  journal = OS,
+  year = {2007},
+  volume = {4},
+  pages = {653--698}
+}
+
+@ARTICLE{Treguier_al_OD06,
+  author = {A.-M. Tr\'{e}guier and C. Gourcuff and P. Lherminier and H. Mercier and B. Barnier 
+  and G. Madec and J.-M. Molines and T. Penduff and L. Czeschel and C. Böning},
+  title = {Internal and forced variability along a section between Greenland
+	and Portugal in the CLIPPER Atlantic model},
+  journal = OD,
+  year = {2006},
+  volume = {56},
+  pages = {568--580},
+  doi = {10.1007/s10236-006-0069-y},
+}
+
+@ARTICLE{Treguier1997,
+  author = {A. M. Tr\'{e}guier and I. M. Held and V. D. Larichev},
+  title = {Parameterization of Quasigeostrophic Eddies in Primitive Equation Ocean Models},
+  journal = JPO,
+  year = {1997},
+  volume = {27},  number = {4},
+  pages = {567--580}
+}
+
+@ARTICLE{Tu_Tsuang_GRL05,
+  title={{Cool-skin simulation by a one-column ocean model}},
+  author={{C-Y}. Tu  and {B-J}. Tsuang},
+  journal=GRL,
+  year={2005},
+  volume={32},
+  pages={L22602},
+  doi = {10.1029/2005GL024252},
+}
+
+@ARTICLE{Umlauf_Burchard_JMS03,
+  author = {L. Umlauf and H. Burchard},
+  title = {A generic length-scale equation for geophysical turbulence models},
+  journal = JMS, 
+  year = {2003},
+  volume = {61},  number = {2},
+  pages = {235--265}
+}
+
+@ARTICLE{Umlauf_Burchard_CSR05,
+  author = {L. Umlauf and H. Burchard},
+  title = {Second-order turbulence closure models for geophysical boundary layers. A review of recent work},
+  journal = JMS, 
+  year = {2005},
+  volume = {25},
+  pages = {795--827}
+}
+
+@BOOK{UNESCO1983,
+  title = {Algorithms for computation of fundamental property of sea water},
+  publisher = {Techn. Paper in Mar. Sci, 44, UNESCO},
+  year = {1983},
+  author = {UNESCO}
+}
+
+@TECHREPORT{OASIS2006,
+  author = {S. Valcke},
+  title = {OASIS3 User Guide (prism\_2-5)},
+  institution = {PRISM Support Initiative Report No 3, CERFACS, Toulouse, France},
+  year = {2006},
+  pages = {64pp}
+}
+
+@TECHREPORT{Valcke_al_Rep00,
+  author = {S. Valcke and L. Terray and A. Piacentini },
+  title = {The OASIS Coupled User Guide Version 2.4},
+  institution = {CERFACS},
+  year = {2000},
+  number = {TR/CMGC/00-10}
+}
+
+@ARTICLE{Vancoppenolle_al_OM09b,
+  author = {M. Vancoppenolle and T. Fichefet and H. Goosse},
+  title = {Simulating the mass balance and salinity of Arctic and Antarctic sea ice. 2. 
+     Importance of sea ice salinity variations},
+  journal = OM,
+  year = {2009},
+  volume = {27},
+  pages = {54--69}
+}
+
+@book{Vallis06,
+author = {Vallis, G. K.},
+title = {Atmospheric and Oceanic Fluid Dynamics},
+publisher = {Cambridge University Press},
+address = {Cambridge, U.K.},
+year = {2006},
+pages = {745},
+}
+
+@ARTICLE{Vancoppenolle_al_OM09a,
+  author = {M. Vancoppenolle and T. Fichefet and H. Goosse and S. Bouillon and
+	G. Madec and M. A. Morales Maqueda},
+  title = {Simulating the mass balance and salinity of Arctic and Antarctic
+	sea ice. 1. Model description and validation},
+  journal = OM,
+  year = {2009},
+  volume = {27},
+  pages = {33--53},
+  doi = {10.1016/j.ocemod.2008.10.005},
+}
+
+@ARTICLE{Vialard_al_JPO01,
+  author = {J. Vialard and C. Menkes and J.-P. Boulanger and P. Delecluse and
+	E. Guilyardi and M.J. McPhaden and G. Madec},
+  title = {A Model Study of Oceanic Mechanisms Affecting Equatorial Pacific
+	Sea Surface Temperature During the 1997-98 El Niño},
+  journal = JPO,
+  year = {2001},
+  volume = {31},  number = {7},
+  pages = {1649--1675}
+}
+
+@ARTICLE{Warner_al_OM05,
+  author = {J. C. Warner and C. R. Sherwood and H. G. Arango and R. P. Signell},
+  title = {Performance of four turbulence closure models implemented using a generic length scale method},
+  journal = OM,
+  year = {2005},
+  volume = {8},
+  pages = {81--113},
+  doi = {10.1016/j.ocemod.2003.12.003},
+}
+
+@ARTICLE{Weatherly_JMR84,
+  author = {G. L. Weatherly},
+  title = {An estimate of bottom frictional dissipation by Gulf Stream fluctuations},
+  journal = JMR,
+  year = {1984},
+  volume = {42},  number = {2},
+  pages = {289--301}
+}
+
+@ARTICLE{Weaver_Eby_JPO97,
+  author = {A. J. Weaver and M. Eby},
+  title = {On the numerical implementation of advection schemes for use in conjuction
+	with various mixing parameterizations in the GFDL ocean model},
+  journal = JPO,
+  year = {1997},
+  volume = {27}
+}
+
+@ARTICLE{Webb_al_JAOT98,
+  author = {D. J. Webb and B. A. de Cuevas and C. S. Richmond},
+  title = {Improved Advection Schemes for Ocean Models},
+  journal = JAOT,
+  year = {1998},
+  volume = {15},  number = {5},
+  pages = {1171--1187},
+}
+
+@ARTICLE{White_al_JCP09,
+  author = {L. White and A. Adcroft and R. Hallberg},
+  title = {High-order regridding-remapping schemes for continuous isopycnal
+	and generalized coordinates in ocean models},
+  journal = JC,
+  year = {2009},
+  volume = {228},
+  pages = {8665--8692}
+}
+
+@ARTICLE{Wilcox_1988,
+  author = {D. C. Wilcox},
+  title = {Reassessment of the scale-determining equation for advanced turbulence models},
+  journal = {AIAA journal},
+  year = {1988},
+  volume = {26},  number = {11},
+  pages = {1299--1310}
+}
+
+@ARTICLE{Willebrand_al_PO01,
+  author = {J. Willebrand and B. Barnier and C. Boning and C. Dieterich and P.
+	D. Killworth and C. Le Provost and Y. Jia and J.-M. Molines and A. L. New},
+  title = {Circulation characteristics in three eddy-permitting models of the North Atlantic},
+  journal = PO,
+  year = {2001},
+  volume = {48},  number = {2},
+  pages = {123--161}
+}
+
+@ARTICLE{Williams_al_DAO09,
+  author = {P.D. Williams and E. Guilyardi and G. Madec and S. Gualdi and E. Scoccimarro},
+  title = {The role of mean ocean salinity on climate},
+  journal = DAO,
+  year = {2010},
+  volume = {49},  number = {2-3},
+  pages = {108--123},
+  doi = {10.1016/j.dynatmoce.2009.02.001},
+}
+
+@ARTICLE{Williams_al_GRL07,
+  author = {P.D. Williams and E. Guilyardi and R. Sutton and J.M. Gregory and G. Madec},
+  title = {A new feedback on climate change from the hydrological cycle},
+  journal = GRL,
+  year = {2007},
+  volume = {34},
+  pages = {L08706},
+  doi = {10.1029/2007GL029275},
+}
+
+@ARTICLE{Williams_al_CD06,
+  author = {P.D. Williams and E. Guilyardi and R. Sutton and J.M. Gregory and G. Madec},
+  title = {On the climate response of the low-latitude Pacific ocean to changes in the global freshwater cycle},
+  journal = CD,
+  year = {2006},
+  volume = {27},
+  pages = {593--611}
+}
+
+@ARTICLE{Zalesak_JCP79,
+  author = {S. T. Zalesak},
+  title = {Fully multidimensional flux corrected transport algorithms for fluids},
+  journal = JCP,
+  year = {1979},
+  volume = {31}
+}
+
+@ARTICLE{Zhang_Endoh_JGR92,
+  author = {Zhang, R.-H. and Endoh, M.},
+  title = {A free surface general circulation model for the tropical Pacific Ocean},
+  journal = JGR,
+  year = {1992},
+  volume = {97},
+  pages = {11,237--11,255}
+}
+
+@comment{jabref-meta: groupsversion:3;}
+
+@comment{jabref-meta: groupstree:
+0 AllEntriesGroup:;
+1 ExplicitGroup:El Nino\;2\;blanketal97\;;
+2 ExplicitGroup:97/98 event\;0\;;
+2 ExplicitGroup:Forecast\;0\;;
+2 ExplicitGroup:GHG change\;0\;;
+2 ExplicitGroup:in GCMs\;0\;;
+2 ExplicitGroup:in MIPs\;0\;;
+2 ExplicitGroup:momentum balance\;0\;;
+2 ExplicitGroup:Obs analysis\;0\;;
+2 ExplicitGroup:Paleo\;0\;;
+2 ExplicitGroup:Previous events\;0\;;
+2 ExplicitGroup:Reviews\;0\;;
+2 ExplicitGroup:Simple models\;0\;Zhang_Endoh_JGR92\;;
+2 ExplicitGroup:SPL, SC, mean\;0\;;
+2 ExplicitGroup:Teleconnections\;0\;;
+2 ExplicitGroup:Low freq\;0\;;
+2 ExplicitGroup:Theory\;0\;;
+2 ExplicitGroup:Energetics\;0\;;
+1 ExplicitGroup:Diurnal in tropics\;0\;;
+1 ExplicitGroup:Indian\;0\;;
+1 ExplicitGroup:Atlantic\;0\;;
+1 ExplicitGroup:MJO, IO, TIW\;2\;;
+2 ExplicitGroup:Obs\;0\;;
+2 ExplicitGroup:GCM\;0\;;
+2 ExplicitGroup:Mechanims\;0\;;
+2 ExplicitGroup:TIW\;0\;;
+1 ExplicitGroup:Observations\;2\;;
+2 ExplicitGroup:ERBE\;0\;;
+2 ExplicitGroup:Tropical\;0\;;
+2 ExplicitGroup:Global\;0\;;
+2 ExplicitGroup:Clouds\;0\;;
+2 ExplicitGroup:Scale interactions\;0\;;
+1 ExplicitGroup:Mechanisms\;2\;;
+2 ExplicitGroup:CRF\;0\;;
+2 ExplicitGroup:Water vapor\;0\;;
+2 ExplicitGroup:Atmos mechanisms\;0\;;
+1 ExplicitGroup:GCMs\;2\;;
+2 ExplicitGroup:Uncertainty\;0\;;
+2 ExplicitGroup:Momentum balance\;0\;;
+1 ExplicitGroup:Climate change\;0\;;
+2 ExplicitGroup:IPCC AR4\;0\;;
+1 ExplicitGroup:Analysis tools\;0\;;
+1 KeywordGroup:EG publis\;0\;author\;guilyardi\;0\;0\;;
+}
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.cfg	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.cfg	(revision 10321)
@@ -0,0 +1,10 @@
+\Preamble{xhtml,mathml}
+
+\Configure{@HEAD}{%
+\HCode{<script type="text/javascript"
+   src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=MML_CHTML">
+ </script>\Hnewline}}
+
+\begin{document}
+
+\EndPreamble
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.ist
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.ist	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.ist	(revision 10321)
@@ -0,0 +1,3 @@
+delim_0 "\\dotfill"
+delim_1 "\\dotfill"
+delim_2 "\\dotfill"
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.sty
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.sty	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.sty	(revision 10321)
@@ -0,0 +1,171 @@
+%% ==============================================================================
+%% NEMO_manual.sty: all customizations (packages, )
+%% ==============================================================================
+
+
+%% LaTeX packages
+%% ==============================================================================
+
+\usepackage{natbib}           %% bib
+\usepackage{caption}          %% caption
+\usepackage{xcolor}           %% color
+\usepackage{silence}          %% compilation
+\usepackage{times}            %% font
+\usepackage{hyperref}         %% hyper
+\usepackage{idxlayout}        %% index
+\usepackage{enumitem}         %% list
+\usepackage{minted}           %% listing
+\usepackage{amsmath}          %% maths
+\usepackage{fancyhdr}         %% page
+\usepackage{minitoc}          %% toc
+\usepackage{subfiles}         %% subdocs
+\usepackage[utf8]{inputenc}   %% input encoding
+
+%% Extensions in bundle package
+
+\usepackage{amssymb, graphicx, makeidx, tabularx, xspace}
+
+
+%% Configuration
+
+\captionsetup{margin=10pt, font={small}, labelsep=colon, labelfont={bf}}
+\graphicspath{{../../../figures/}}
+\hypersetup{
+	pdftitle={NEMO ocean engine}, pdfauthor={Gurvan Madec, and the NEMO team},
+	colorlinks
+}
+\idxlayout{font=footnotesize, columns=3}
+\renewcommand{\bibfont}{\footnotesize}
+\renewcommand{\bibsep}{3pt}
+
+
+%% Styles
+%% ==============================================================================
+
+\pagestyle{fancy}
+\bibliographystyle{../main/ametsoc}
+
+
+%% Additionnal fonts
+
+\DeclareMathAlphabet{\mathpzc}{OT1}{pzc}{m}{it}
+
+
+%% Page layout
+
+\fancyhf{}
+\fancyhead[LE,RO]{\bfseries\thepage}
+\fancyhead[LO]{\bfseries\hspace{-0em}\rightmark}
+\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}}
+\fancyhead[RE]{\bfseries\leftmark}
+\renewcommand{\chaptermark}[1]{\markboth{#1}{}}
+\renewcommand{\headrulewidth}{0.5pt}
+\renewcommand{\footrulewidth}{0pt  }
+\addtolength{\headheight}{2.6pt}
+
+
+%% Catcodes
+
+\makeatletter
+\def\LigneVerticale{\vrule height 5cm depth 2cm\hspace{0.1cm}\relax}
+\def\LignesVerticales{\let\LV\LigneVerticale\LV\LV\LV\LV\LV\LV\LV\LV\LV\LV}
+\def\GrosCarreAvecUnChiffre#1{
+	\rlap{\vrule height 0.8cm width 1cm depth 0.2cm}
+	\rlap{\hbox to 1cm{\hss\mbox{\color{white} #1}\hss}}
+ 	\vrule height 0pt width 1cm depth 0pt
+}
+\def\@makechapterhead#1{
+	\hbox{
+		\huge\LignesVerticales\hspace{-0.5cm}
+		\GrosCarreAvecUnChiffre{\thechapter}\hspace{0.2cm}
+		\hbox{#1}
+	}
+	\par\vskip
+1cm
+}
+\def\@makeschapterhead#1{
+	\hbox{
+		\huge\LignesVerticales
+		\hbox{#1}
+	}
+	\par\vskip
+2cm
+}
+\def\cleardoublepage{\clearpage\if@twoside \ifodd\c@page\else
+  \hbox{}
+  \vspace*{\fill}
+  \vspace{\fill}
+  \thispagestyle{empty}
+  \newpage
+  \if@twocolumn\hbox{}\newpage\fi\fi\fi}
+\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname the#1\endcsname\quad}}
+\makeatother
+
+
+%% Macros (to check)
+
+\def\deg{$^{\circ}$}
+\def\degC{$^{\circ}C$}
+\def\degK{$^{\circ}K$}
+\def\degN{$^{\circ}N$}
+\def\degS{$^{\circ}S$}
+
+\def\half{\textstyle\frac{1}{2}}
+\def\hhalf{\scriptstyle\frac{1}{2}}
+
+\def\quarter{\textstyle\frac{1}{4}}
+\def\qquarter{\scriptstyle\frac{1}{4}}
+\def\squarter{\sfrac{1}{4}}
+\def\stwelfth{\sfrac{1}{12}}
+\def\sthirtysixth{\sfrac{1}{36}}
+
+\def\bgamma\boldsymbol{\gamma}
+\def\rdt{\Delta t}
+
+
+%% New commands
+
+\newcommand{\gmcomment}[1]{}
+\newcommand{\sfcomment}[1]{}
+\newcommand{\sgacomment}[1]{}
+
+\newcommand{\nl}[1]{\texttt{\small{\textcolor{blue}{#1}}}}
+\newcommand{\NEMO}{\textit{NEMO}\xspace}
+
+\newcommand{\hf}[1]{\textit{#1.h90}\index{h90 file!#1}}
+\newcommand{\ifile}[1]{\textit{#1.nc}\index{Input NetCDF files!#1.nc}}
+\newcommand{\jp}[1]{\textit{#1}\index{Model parameters!#1}}
+\newcommand{\key}[1]{\textbf{key\_#1}\index{CPP keys!key\_#1}}
+\newcommand{\mdl}[1]{\textit{#1.F90}\index{Modules!#1}}
+\newcommand{\ngn}[1]{\textit{#1}\index{Namelist Group Name!#1}}
+\newcommand{\np}[1]{\textit{#1}\index{Namelist variables!#1}}
+\newcommand{\rou}[1]{\textit{#1}\index{Routines!#1}}
+
+\newcommand{\grad}{\nabla}
+\newcommand{\gradh}{\nabla_h}
+
+\newcommand{\ew}[3]{{e_{3#1}}_{\,#2}^{\,#3} }
+\newcommand{\vect}[1]{\ensuremath{\mathbf{#1}}}
+\newcommand{\Div}{\grad\cdot}
+\newcommand{\curl}{\nabla \times}
+\newcommand{\pd}[2][]{\frac{\partial #1}{\partial #2}}
+\newcommand{\alpbet} {\left(\alpha / \beta \right)}
+
+\newcommand{\triad}[6][]{\ensuremath{{}_{#2}^{#3}{\mathbb{#4}_{#1}}_{#5}^{\,#6}}}
+\newcommand{\triadd}[5]{\ensuremath{{}_{#1}^{#2}{\mathbb{#3}}_{#4}^{\,#5}}}
+\newcommand{\triadt}[5]{\ensuremath{{}_{#1}^{#2}{\tilde{\mathbb{#3}}}_{#4}^{\,#5}}}
+\newcommand{\rtriad}[2][]{\ensuremath{\triad[#1]{i}{k}{#2}{i_p}{k_p}}}
+\newcommand{\rtriadt}[1]{\ensuremath{\triadt{i}{k}{#1}{i_p}{k_p}}}
+
+\newcommand{\Alts}{{A}}
+\newcommand{\Alt}{{A^{lT}}}
+
+\newcommand{\rMLt}[1][i]{\tilde{r}_{\mathrm{ML}\,#1}}
+\newcommand{\rML}[1][i]{r_{\mathrm{ML}\,#1}}
+
+\newcommand{\mygstrut}[2]{\rule[#1 em]{0pt}{#2 em}}
+\newcommand{\mystrut}{\rule[-.9 em]{0pt}{1.79 em}}
+
+\newcommand{\doi}[1]{\href{http://dx.doi.org/#1}{full-text}}
+
+\newcommand{\nlst}[1]{\forfile{../../../namelists/#1}}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_manual.tex	(revision 10321)
@@ -0,0 +1,159 @@
+%% ==============================================================================
+%% NEMO_book.tex: build the NEMO Reference Manual
+%% ==============================================================================
+
+
+%% Run ../build_NEMO_manual.sh to generate the PDF version (with pdflatex)
+
+%% Document layout
+%% ==============================================================================
+
+\documentclass[a4paper, 11pt]{book}
+
+
+%% Preamble
+%% ==============================================================================
+
+%% Custom style
+\usepackage{../main/NEMO_manual}
+\usepackage{../main/NEMO_minted}
+
+\makeindex
+
+
+%% 
+%% ==============================================================================
+
+\begin{document}
+
+
+%% Frontmatter
+%% ==============================================================================
+
+%% Frontpage
+
+\title{
+\vspace{-6.0cm}\includegraphics[width=1.1\textwidth]{logo_ALL}				\\
+\vspace{ 5.1cm}\includegraphics[width=0.9\textwidth]{NEMO_logo_Black}	\\
+\vspace{ 1.4cm}\rule{345pt}{1.5pt}													\\
+\vspace{0.45cm}{\Huge NEMO ocean engine}											\\
+\rule{345pt}{1.5pt}
+}
+
+\author{
+\Large Gurvan Madec, and the NEMO team					                                             \\
+\texttt{\small\href{mailto:gurvan.madec@locean-ipsl.umpc.fr}{gurvan.madec@locean-ipsl.umpc.fr}}	\\
+}
+
+\date{
+Decembre 2017																											\\
+{\small  -- version 4.0 alpha --}																				\\
+~																															\\
+\textit{\small Note du P\^ole de mod\'{e}lisation de l'Institut Pierre-Simon Laplace No 27 }	\\
+\vspace{0.45cm}{ ISSN No 1288-1619.}
+}
+%\date{\today}
+
+\maketitle
+\frontmatter
+
+
+%% ToC i.e. Table of Contents
+
+\dominitoc
+\tableofcontents
+
+
+%% Mainmatter
+%% ==============================================================================
+
+\mainmatter
+
+
+%% Abstract - Foreword
+
+\subfile{../subfiles/abstract_foreword}
+
+
+% Introduction
+
+\subfile{../subfiles/introduction}
+
+
+% Chapters
+
+\subfile{../subfiles/chap_model_basics}
+
+\subfile{../subfiles/chap_time_domain}   % Time discretisation (time stepping strategy)
+
+\subfile{../subfiles/chap_DOM}           % Space discretisation
+
+\subfile{../subfiles/chap_TRA}           % Tracer advection/diffusion equation
+
+\subfile{../subfiles/chap_DYN}           % Dynamics : momentum equation
+
+\subfile{../subfiles/chap_SBC}           % Surface Boundary Conditions
+
+\subfile{../subfiles/chap_LBC}           % Lateral Boundary Conditions
+
+\subfile{../subfiles/chap_LDF}           % Lateral diffusion
+
+\subfile{../subfiles/chap_ZDF}           % Vertical diffusion
+
+\subfile{../subfiles/chap_DIA}           % Outputs and Diagnostics
+
+\subfile{../subfiles/chap_OBS}           % Observation operator
+
+\subfile{../subfiles/chap_ASM}           % Assimilation increments
+
+\subfile{../subfiles/chap_STO}           % Stochastic param.
+
+\subfile{../subfiles/chap_misc}          % Miscellaneous topics
+
+\subfile{../subfiles/chap_CONFIG}        % Predefined configurations
+
+
+%% Appendix
+
+\appendix
+
+\subfile{../subfiles/annex_A}					% Generalised vertical coordinate
+
+\subfile{../subfiles/annex_B}					% Diffusive operator
+
+\subfile{../subfiles/annex_C}					% Discrete invariants of the eqs.
+
+\subfile{../subfiles/annex_iso}				% Isoneutral diffusion using triads
+
+\subfile{../subfiles/annex_D}					% Coding rules
+
+%% Not included
+%\subfile{../subfiles/chap_conservation}	%
+%\subfile{../subfiles/annex_E}				% Notes on some on going staff
+%\subfile{../subfiles/annex_Fox-Kemper}	% Notes on Fox-Kemper
+%\subfile{../subfiles/annex_EVP}				% Notes on EVP
+
+
+%% Backmatter
+%% ==============================================================================
+
+\backmatter
+
+
+%% Bibliography
+
+\cleardoublepage
+\phantomsection
+\addcontentsline{toc}{chapter}{Bibliography}
+\bibliography{../main/NEMO_manual}
+
+
+%% Index
+
+\cleardoublepage
+\phantomsection
+\addcontentsline{toc}{chapter}{Index}
+\printindex
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_minted.sty
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_minted.sty	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/NEMO_minted.sty	(revision 10321)
@@ -0,0 +1,44 @@
+%% ==============================================================================
+%% minted.sty: syntax highlighting configuration
+%% ==============================================================================
+
+
+%% Global highlighting style
+%% ==============================================================================
+
+\setminted{style=emacs, fontsize=\scriptsize, breaklines, frame=leftline}
+
+
+%% Specific per language
+
+\setminted[xml]{style=borland}
+
+
+%% Oneliner
+%% ==============================================================================
+
+\newmint[forline]{fortran}{}   % \forline|...|
+\newmint[xmlline]{xml}{}       % \xmlline|...|
+\newmint[cmd]{console}{}       % \cmd|...|
+
+
+%% Multi-lines
+%% ==============================================================================
+
+\newminted[forlines]{fortran}{}         % \begin{forlines}
+\newminted[xmllines]{xml}{}             % \begin{xmllines}
+\newminted[cmds]{console}{}             % \begin{cmds}
+\newminted[clines]{c}{fontsize=\tiny}   % \begin{clines}
+
+
+%% File
+
+\newmintedfile[forfile]{fortran}{fontsize=\tiny}   % \forfile{../namelists/nam...}
+
+
+%% Inline
+%% ==============================================================================
+
+\newmintinline[forcode]{fortran}{fontsize=auto, frame=lines}   % \forcode{...}
+\newmintinline[xmlcode]{xml}{    fontsize=auto, frame=lines}   % \xmlcode{...}
+\newmintinline[snippet]{console}{fontsize=auto, frame=lines}   % \snippet{...}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/ametsoc.bst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/ametsoc.bst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/main/ametsoc.bst	(revision 10321)
@@ -0,0 +1,1662 @@
+%%
+%% This is file `ametsoc7.bst',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% merlin.mbs  (with options: `ay,nat,nm-rev1,ed-rev,jnrlst,nmdash,nmd-3,dt-beg,yr-com,yrp-col,thtit-a,vol-2bf,vnum-sp,volp-com,pgsep-s,num-xser,numser,ser-vol,bkpg-x,pg-bk,pre-edn,agu-doi,doi,edparc,bkedcap,edby,edbyy,blk-tit,in-x,pp,ed,abr,ednx,ord,jabr,eprint,url,url-nt,em-it,nfss,')
+%% ----------------------------------------
+%% *** Bibliography style file for ALL AMS Journals...version 1.0  ***
+%% *** Brian Papa - American Meteorological Society ***
+%% 
+%% Copyright 1994-2004 Patrick W Daly
+ % ===============================================================
+ % IMPORTANT NOTICE:
+ % This bibliographic style (bst) file has been generated from one or
+ % more master bibliographic style (mbs) files, listed above.
+ %
+ % This generated file can be redistributed and/or modified under the terms
+ % of the LaTeX Project Public License Distributed from CTAN
+ % archives in directory macros/latex/base/lppl.txt; either
+ % version 1 of the License, or any later version.
+ % ===============================================================
+ % Name and version information of the main mbs file:
+ % \ProvidesFile{merlin.mbs}[2004/02/09 4.13 (PWD, AO, DPC)]
+ %   For use with BibTeX version 0.99a or later
+ %-------------------------------------------------------------------
+ % This bibliography style file is intended for texts in ENGLISH
+ % This is an author-year citation style bibliography. As such, it is
+ % non-standard LaTeX, and requires a special package file to function properly.
+ % Such a package is    natbib.sty   by Patrick W. Daly
+ % The form of the \bibitem entries is
+ %   \bibitem[Jones et al.(1990)]{key}...
+ %   \bibitem[Jones et al.(1990)Jones, Baker, and Smith]{key}...
+ % The essential feature is that the label (the part in brackets) consists
+ % of the author names, as they should appear in the citation, with the year
+ % in parentheses following. There must be no space before the opening
+ % parenthesis!
+ % With natbib v5.3, a full list of authors may also follow the year.
+ % In natbib.sty, it is possible to define the type of enclosures that is
+ % really wanted (brackets or parentheses), but in either case, there must
+ % be parentheses in the label.
+ % The \cite command functions as follows:
+ %   \citet{key} ==>>                Jones et al. (1990)
+ %   \citet*{key} ==>>               Jones, Baker, and Smith (1990)
+ %   \citep{key} ==>>                (Jones et al., 1990)
+ %   \citep*{key} ==>>               (Jones, Baker, and Smith, 1990)
+ %   \citep[chap. 2]{key} ==>>       (Jones et al., 1990, chap. 2)
+ %   \citep[e.g.][]{key} ==>>        (e.g. Jones et al., 1990)
+ %   \citep[e.g.][p. 32]{key} ==>>   (e.g. Jones et al., p. 32)
+ %   \citeauthor{key} ==>>           Jones et al.
+ %   \citeauthor*{key} ==>>          Jones, Baker, and Smith
+ %   \citeyear{key} ==>>             1990
+ %---------------------------------------------------------------------
+
+ENTRY
+  { address
+    archive
+    author
+    booktitle
+    chapter
+    doi
+    edition
+    editor
+    eid
+    eprint
+    howpublished
+    department
+    institution
+    journal
+    key
+    month
+    note
+    number
+    organization
+    pages
+    publisher
+    school
+    series
+    title
+    type
+    url
+    volume
+    year
+  }
+  {}
+  { label extra.label sort.label short.list }
+INTEGERS { output.state before.all mid.sentence after.sentence after.block }
+FUNCTION {init.state.consts}
+{ #0 'before.all :=
+  #1 'mid.sentence :=
+  #2 'after.sentence :=
+  #3 'after.block :=
+}
+STRINGS { s t}
+FUNCTION {output.nonnull}
+{ 's :=
+  output.state mid.sentence =
+    { ", " * write$ }
+    { output.state after.block =
+        { add.period$ write$
+          newline$
+          "\newblock " write$
+        }
+        { output.state before.all =
+            'write$
+            { add.period$ " " * write$ }
+          if$
+        }
+      if$
+      mid.sentence 'output.state :=
+    }
+  if$
+  s
+}
+FUNCTION {output}
+{ duplicate$ empty$
+    'pop$
+    'output.nonnull
+  if$
+}
+FUNCTION {output.check}
+{ 't :=
+  duplicate$ empty$
+    { pop$ "empty " t * " in " * cite$ * warning$ }
+    'output.nonnull
+  if$
+}
+FUNCTION {fin.entry}
+{ add.period$
+  write$
+  newline$
+}
+
+FUNCTION {new.block}
+{ output.state before.all =
+    'skip$
+    { after.block 'output.state := }
+  if$
+}
+FUNCTION {new.sentence}
+{ output.state after.block =
+    'skip$
+    { output.state before.all =
+        'skip$
+        { after.sentence 'output.state := }
+      if$
+    }
+  if$
+}
+FUNCTION {add.blank}
+{  " " * before.all 'output.state :=
+}
+
+FUNCTION {date.block}
+{
+  ":" *
+  add.blank
+}
+
+FUNCTION {not}
+{   { #0 }
+    { #1 }
+  if$
+}
+FUNCTION {and}
+{   'skip$
+    { pop$ #0 }
+  if$
+}
+FUNCTION {or}
+{   { pop$ #1 }
+    'skip$
+  if$
+}
+FUNCTION {new.block.checkb}
+{ empty$
+  swap$ empty$
+  and
+    'skip$
+    'new.block
+  if$
+}
+FUNCTION {field.or.null}
+{ duplicate$ empty$
+    { pop$ "" }
+    'skip$
+  if$
+}
+FUNCTION {emphasize}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textit{" swap$ * "}" * }
+  if$
+}
+FUNCTION {bolden}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textbf{" swap$ * "}" * }
+  if$
+}
+FUNCTION {tie.or.space.prefix}
+{ duplicate$ text.length$ #3 <
+    { "~" }
+    { " " }
+  if$
+  swap$
+}
+
+FUNCTION {capitalize}
+{ "u" change.case$ "t" change.case$ }
+
+FUNCTION {space.word}
+{ " " swap$ * " " * }
+ % Here are the language-specific definitions for explicit words.
+ % Each function has a name bbl.xxx where xxx is the English word.
+ % The language selected here is ENGLISH
+FUNCTION {bbl.and}
+{ "and"}
+
+FUNCTION {bbl.etal}
+{ "et~al." }
+
+FUNCTION {bbl.editors}
+{ "Eds." }
+
+FUNCTION {bbl.editor}
+{ "Ed." }
+
+FUNCTION {bbl.edby}
+{ "edited by" }
+
+FUNCTION {bbl.edition}
+{ "ed." }
+
+FUNCTION {bbl.volume}
+{ "Vol." }
+
+FUNCTION {bbl.of}
+{ "of" }
+
+FUNCTION {bbl.number}
+{ "No." }
+
+FUNCTION {bbl.nr}
+{ "No." }
+
+FUNCTION {bbl.in}
+{ "in" }
+
+FUNCTION {bbl.pages}
+{ "pp." }
+
+FUNCTION {bbl.page}
+{ "p." }
+
+FUNCTION {bbl.chapter}
+{ "chap." }
+
+FUNCTION {bbl.techrep}
+{ "Tech. Rep." }
+
+FUNCTION {bbl.mthesis}
+{ "Master's thesis" }
+
+FUNCTION {bbl.phdthesis}
+{ "Ph.D. thesis" }
+
+FUNCTION {bbl.first}
+{ "1st" }
+
+FUNCTION {bbl.second}
+{ "2d" }
+
+FUNCTION {bbl.third}
+{ "3d" }
+
+FUNCTION {bbl.fourth}
+{ "4th" }
+
+FUNCTION {bbl.fifth}
+{ "5th" }
+
+FUNCTION {bbl.st}
+{ "st" }
+
+FUNCTION {bbl.nd}
+{ "d" }
+
+FUNCTION {bbl.rd}
+{ "d" }
+
+FUNCTION {bbl.th}
+{ "th" }
+
+MACRO {jan} {"Jan."}
+
+MACRO {feb} {"Feb."}
+
+MACRO {mar} {"Mar."}
+
+MACRO {apr} {"Apr."}
+
+MACRO {may} {"May"}
+
+MACRO {jun} {"Jun."}
+
+MACRO {jul} {"Jul."}
+
+MACRO {aug} {"Aug."}
+
+MACRO {sep} {"Sep."}
+
+MACRO {oct} {"Oct."}
+
+MACRO {nov} {"Nov."}
+
+MACRO {dec} {"Dec."}
+
+FUNCTION {eng.ord}
+{ duplicate$ "1" swap$ *
+  #-2 #1 substring$ "1" =
+     { bbl.th * }
+     { duplicate$ #-1 #1 substring$
+       duplicate$ "1" =
+         { pop$ bbl.st * }
+         { duplicate$ "2" =
+             { pop$ bbl.nd * }
+             { "3" =
+                 { bbl.rd * }
+                 { bbl.th * }
+               if$
+             }
+           if$
+          }
+       if$
+     }
+   if$
+}
+
+MACRO {acmcs} {"ACM Comput. Surv."}
+
+MACRO {acta} {"Acta Inf."}
+
+MACRO {cacm} {"Commun. ACM"}
+
+MACRO {ibmjrd} {"IBM J. Res. Dev."}
+
+MACRO {ibmsj} {"IBM Syst.~J."}
+
+MACRO {ieeese} {"IEEE Trans. Software Eng."}
+
+MACRO {ieeetc} {"IEEE Trans. Comput."}
+
+MACRO {ieeetcad}
+ {"IEEE Trans. Comput. Aid. Des."}
+
+MACRO {ipl} {"Inf. Process. Lett."}
+
+MACRO {jacm} {"J.~ACM"}
+
+MACRO {jcss} {"J.~Comput. Syst. Sci."}
+
+MACRO {scp} {"Sci. Comput. Program."}
+
+MACRO {sicomp} {"SIAM J. Comput."}
+
+MACRO {tocs} {"ACM Trans. Comput. Syst."}
+
+MACRO {tods} {"ACM Trans. Database Syst."}
+
+MACRO {tog} {"ACM Trans. Graphic."}
+
+MACRO {toms} {"ACM Trans. Math. Software"}
+
+MACRO {toois} {"ACM Trans. Office Inf. Syst."}
+
+MACRO {toplas} {"ACM Trans. Progr. Lang. Syst."}
+
+MACRO {tcs} {"Theor. Comput. Sci."}
+
+FUNCTION {bibinfo.check}
+{ swap$
+  duplicate$ missing$
+    {
+      pop$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ pop$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {bibinfo.warn}
+{ swap$
+  duplicate$ missing$
+    {
+      swap$ "missing " swap$ * " in " * cite$ * warning$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ "empty " swap$ * " in " * cite$ * warning$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.eprint}
+{ eprint duplicate$ empty$
+    'skip$
+    { "\eprint"
+      archive empty$
+        'skip$
+        { "[" * archive * "]" * }
+      if$
+      "{" * swap$ * "}" *
+    }
+  if$
+}
+STRINGS  { bibinfo}
+INTEGERS { nameptr namesleft numnames }
+
+FUNCTION {format.names}
+{ 'bibinfo :=
+  duplicate$ empty$ 'skip$ {
+  's :=
+  "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      duplicate$ #1 >
+        { "{f.~}{vv~}{ll}{, jj}" }
+        { "{vv~}{ll}{, f.}{, jj}" }
+      if$
+      format.name$
+      bibinfo bibinfo.check
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              numnames #2 >
+                { "," * }
+                'skip$
+              if$
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+  } if$
+}
+FUNCTION {format.names.ed}
+{
+  format.names
+}
+FUNCTION {format.key}
+{ empty$
+    { key field.or.null }
+    { "" }
+  if$
+}
+
+FUNCTION {format.authors}
+{ author "author" format.names
+}
+FUNCTION {get.bbl.editor}
+{ editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ }
+
+FUNCTION {format.editors}
+{ editor "editor" format.names duplicate$ empty$ 'skip$
+    {
+      "," *
+      " " *
+      get.bbl.editor
+      capitalize
+   "(" swap$ * ")" *
+      *
+    }
+  if$
+}
+FUNCTION {format.book.pages}
+{ pages "pages" bibinfo.check
+  duplicate$ empty$ 'skip$
+    { " " * bbl.pages * }
+  if$
+}
+FUNCTION {format.doi}
+{ doi "doi" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      "\doi{" swap$ * "}" *
+    }
+  if$
+}
+FUNCTION {format.note}
+{
+  url empty$
+    'skip$
+    { "\urlprefix\url{" url * "}" * output }
+  if$
+ note empty$
+    { "" }
+    { note #1 #1 substring$
+      duplicate$ "{" =
+        'skip$
+        { output.state mid.sentence =
+          { "l" }
+          { "u" }
+        if$
+        change.case$
+        }
+      if$
+      note #2 global.max$ substring$ * "note" bibinfo.check
+    }
+  if$
+}
+
+FUNCTION {format.title}
+{ title
+  duplicate$ empty$ 'skip$
+    { "t" change.case$ }
+  if$
+  "title" bibinfo.check
+}
+FUNCTION {format.full.names}
+{'s :=
+ "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv~}{ll}" format.name$
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  numnames #2 >
+                    { "," * }
+                    'skip$
+                  if$
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {author.editor.key.full}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.full.names }
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {author.key.full}
+{ author empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {editor.key.full}
+{ editor empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { editor format.full.names }
+  if$
+}
+
+FUNCTION {make.full.names}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.full
+    { type$ "proceedings" =
+        'editor.key.full
+        'author.key.full
+      if$
+    }
+  if$
+}
+
+FUNCTION {output.bibitem}
+{ newline$
+  "\bibitem[{" write$
+  label write$
+  ")" make.full.names duplicate$ short.list =
+     { pop$ }
+     { * }
+   if$
+  "}]{" * write$
+  cite$ write$
+  "}" write$
+  newline$
+  ""
+  before.all 'output.state :=
+}
+
+FUNCTION {if.digit}
+{ duplicate$ "0" =
+  swap$ duplicate$ "1" =
+  swap$ duplicate$ "2" =
+  swap$ duplicate$ "3" =
+  swap$ duplicate$ "4" =
+  swap$ duplicate$ "5" =
+  swap$ duplicate$ "6" =
+  swap$ duplicate$ "7" =
+  swap$ duplicate$ "8" =
+  swap$ "9" = or or or or or or or or or
+}
+FUNCTION {n.separate}
+{ 't :=
+  ""
+  #0 'numnames :=
+  { t empty$ not }
+  { t #-1 #1 substring$ if.digit
+      { numnames #1 + 'numnames := }
+      { #0 'numnames := }
+    if$
+    t #-1 #1 substring$ swap$ *
+    t #-2 global.max$ substring$ 't :=
+    numnames #5 =
+      { duplicate$ #1 #2 substring$ swap$
+        #3 global.max$ substring$
+        "\," swap$ * *
+      }
+      'skip$
+    if$
+  }
+  while$
+}
+FUNCTION {n.dashify}
+{
+  n.separate
+  't :=
+  ""
+    { t empty$ not }
+    { t #1 #1 substring$ "-" =
+        { t #1 #2 substring$ "--" = not
+            { "--" *
+              t #2 global.max$ substring$ 't :=
+            }
+            {   { t #1 #1 substring$ "-" = }
+                { "-" *
+                  t #2 global.max$ substring$ 't :=
+                }
+              while$
+            }
+          if$
+        }
+        { t #1 #1 substring$ *
+          t #2 global.max$ substring$ 't :=
+        }
+      if$
+    }
+  while$
+}
+
+FUNCTION {word.in}
+{ "" }
+
+FUNCTION {format.date}
+{ year "year" bibinfo.check duplicate$ empty$
+    {
+      "empty year in " cite$ * "; set to ????" * warning$
+       pop$ "????"
+    }
+    'skip$
+  if$
+  extra.label *
+  before.all 'output.state :=
+  ", " swap$ *
+}
+FUNCTION {format.btitle}
+{ title "title" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      emphasize
+    }
+  if$
+}
+FUNCTION {either.or.check}
+{ empty$
+    'pop$
+    { "can't use both " swap$ * " fields in " * cite$ * warning$ }
+  if$
+}
+FUNCTION {format.bvolume}
+{ volume empty$
+    { "" }
+    { bbl.volume volume tie.or.space.prefix
+      "volume" bibinfo.check * *
+      series "series" bibinfo.check
+      duplicate$ empty$ 'pop$
+%%% NO ITALIC SERIES        { emphasize ", " * swap$ * }
+      {", " * swap$ * }
+      if$
+      "volume and number" number either.or.check
+    }
+  if$
+}
+FUNCTION {format.number.series}
+{ volume empty$
+    { number empty$
+        { series field.or.null }
+        { series empty$
+            { number "number" bibinfo.check }
+            { output.state mid.sentence =
+                { bbl.number }
+                { bbl.number capitalize }
+              if$
+              number tie.or.space.prefix "number" bibinfo.check * *
+              bbl.in space.word *
+              series "series" bibinfo.check *
+            }
+          if$
+        }
+      if$
+    }
+    { "" }
+  if$
+}
+FUNCTION {is.num}
+{ chr.to.int$
+  duplicate$ "0" chr.to.int$ < not
+  swap$ "9" chr.to.int$ > not and
+}
+
+FUNCTION {extract.num}
+{ duplicate$ 't :=
+  "" 's :=
+  { t empty$ not }
+  { t #1 #1 substring$
+    t #2 global.max$ substring$ 't :=
+    duplicate$ is.num
+      { s swap$ * 's := }
+      { pop$ "" 't := }
+    if$
+  }
+  while$
+  s empty$
+    'skip$
+    { pop$ s }
+  if$
+}
+
+FUNCTION {convert.edition}
+{ extract.num "l" change.case$ 's :=
+  s "first" = s "1" = or
+    { bbl.first 't := }
+    { s "second" = s "2" = or
+        { bbl.second 't := }
+        { s "third" = s "3" = or
+            { bbl.third 't := }
+            { s "fourth" = s "4" = or
+                { bbl.fourth 't := }
+                { s "fifth" = s "5" = or
+                    { bbl.fifth 't := }
+                    { s #1 #1 substring$ is.num
+                        { s eng.ord 't := }
+                        { edition 't := }
+                      if$
+                    }
+                  if$
+                }
+              if$
+            }
+          if$
+        }
+      if$
+    }
+  if$
+  t
+}
+
+FUNCTION {format.edition}
+{ edition duplicate$ empty$ 'skip$
+    {
+      convert.edition
+      output.state mid.sentence =
+        { "l" }
+        { "t" }
+      if$ change.case$
+      "edition" bibinfo.check
+      " " * bbl.edition *
+    }
+  if$
+}
+INTEGERS { multiresult }
+FUNCTION {multi.page.check}
+{ 't :=
+  #0 'multiresult :=
+    { multiresult not
+      t empty$ not
+      and
+    }
+    { t #1 #1 substring$
+      duplicate$ "-" =
+      swap$ duplicate$ "," =
+      swap$ "+" =
+      or or
+        { #1 'multiresult := }
+        { t #2 global.max$ substring$ 't := }
+      if$
+    }
+  while$
+  multiresult
+}
+FUNCTION {format.pages}
+{ pages duplicate$ empty$ 'skip$
+    { duplicate$ multi.page.check
+        {
+          n.dashify
+        }
+        {
+        }
+      if$
+      "pages" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.journal.pages}
+{ pages duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$
+        { pop$ pop$ format.pages }
+        {
+          ", " *
+          swap$
+          n.dashify
+          "pages" bibinfo.check
+          *
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.journal.eid}
+{ eid "eid" bibinfo.check
+  duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$ 'skip$
+      {
+          ", " *
+      }
+      if$
+      swap$ *
+    }
+  if$
+}
+FUNCTION {format.vol.num.pages}
+{ volume field.or.null
+  duplicate$ empty$ 'skip$
+    {
+      "volume" bibinfo.check
+    }
+  if$
+  number "number" bibinfo.check duplicate$ empty$ 'skip$
+    {
+      swap$ duplicate$ empty$
+        { "there's a number but no volume in " cite$ * warning$ }
+        'skip$
+      if$
+      swap$
+      "~(" swap$ * ")" *
+    }
+  if$ *
+  bolden
+  eid empty$
+    { format.journal.pages }
+    { format.journal.eid }
+  if$
+}
+
+FUNCTION {format.chapter.pages}
+{ chapter empty$
+    'format.pages
+    { type empty$
+        { bbl.chapter }
+        { type "l" change.case$
+          "type" bibinfo.check
+        }
+      if$
+      chapter tie.or.space.prefix
+      "chapter" bibinfo.check
+      * *
+      pages empty$
+        'skip$
+        { ", " * format.pages * }
+      if$
+    }
+  if$
+}
+
+FUNCTION {format.booktitle}
+{
+  booktitle "booktitle" bibinfo.check
+  emphasize
+}
+FUNCTION {format.in.ed.booktitle}
+{ format.booktitle duplicate$ empty$ 'skip$
+    {
+      editor "editor" format.names.ed duplicate$ empty$ 'pop$
+        {
+          get.bbl.editor
+          swap$ "," *
+          " " * swap$ *
+          swap$
+          "," *
+          " " * swap$
+          * }
+      if$
+      word.in swap$ *
+    }
+  if$
+}
+FUNCTION {format.thesis.type}
+{ type duplicate$ empty$
+    'pop$
+    { swap$ pop$
+      "t" change.case$ "type" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.tr.number}
+{ number "number" bibinfo.check
+  type duplicate$ empty$
+    { pop$ bbl.techrep }
+    'skip$
+  if$
+  "type" bibinfo.check
+  swap$ duplicate$ empty$
+    { pop$ "t" change.case$ }
+    { tie.or.space.prefix * * }
+  if$
+}
+FUNCTION {format.article.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.book.crossref}
+{ volume duplicate$ empty$
+    { "empty volume in " cite$ * "'s crossref of " * crossref * warning$
+      pop$ word.in
+    }
+    { bbl.volume
+      capitalize
+      swap$ tie.or.space.prefix "volume" bibinfo.check * * bbl.of space.word *
+    }
+  if$
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.incoll.inproc.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.org.or.pub}
+{ 't :=
+  ""
+  address empty$ t empty$ and
+    'skip$
+    {
+      t empty$
+        { address "address" bibinfo.check *
+        }
+        { t *
+          address empty$
+            'skip$
+            { ", " * address "address" bibinfo.check * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.publisher.address}
+{ publisher "publisher" bibinfo.warn format.org.or.pub
+}
+
+FUNCTION {format.organization.address}
+{ organization "organization" bibinfo.check format.org.or.pub
+}
+
+STRINGS {oldname}
+
+FUNCTION {name.or.dash}
+{ 's :=
+   oldname empty$
+     { s 'oldname := s }
+     { s oldname =
+         { "---{}---{}---" }
+         { s 'oldname := s }
+       if$
+     }
+   if$
+}
+
+FUNCTION {article}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    {
+      journal
+      "journal" bibinfo.check
+      emphasize
+      "journal" output.check
+      format.vol.num.pages output
+  format.doi output
+    }
+    { format.article.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {book}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      add.blank
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    { format.bvolume output
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {booklet}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  address "address" bibinfo.check output
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {inbook}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    {
+      format.bvolume output
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {incollection}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      format.publisher.address output      
+      format.bvolume output
+      format.number.series output
+      format.edition output
+      format.chapter.pages output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.chapter.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {inproceedings}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      publisher empty$
+        { format.organization.address output }
+        { organization "organization" bibinfo.check output
+          format.publisher.address output
+        }
+      if$
+      format.bvolume output
+      format.pages output
+      format.number.series output
+      howpublished "howpublished" bibinfo.check output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {conference} { inproceedings }
+FUNCTION {manual}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  new.sentence
+  organization "organization" bibinfo.check output
+  address "address" bibinfo.check output
+  format.edition output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {mastersthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.mthesis format.thesis.type output.nonnull
+  department "department" bibinfo.warn output
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {misc}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title output
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {phdthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.phdthesis format.thesis.type output.nonnull
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {proceedings}
+{ output.bibitem
+  format.editors output
+  editor format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  format.bvolume output
+  format.number.series output
+  publisher empty$
+    { format.organization.address output }
+    { organization "organization" bibinfo.check output
+      format.publisher.address output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {techreport}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  format.tr.number output.nonnull
+  institution "institution" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {unpublished}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  format.doi output
+  format.note "note" output.check
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {default.type} { misc }
+READ
+FUNCTION {sortify}
+{ purify$
+  "l" change.case$
+}
+INTEGERS { len }
+FUNCTION {chop.word}
+{ 's :=
+  'len :=
+  s #1 len substring$ =
+    { s len #1 + global.max$ substring$ }
+    's
+  if$
+}
+FUNCTION {format.lab.names}
+{ 's :=
+  "" 't :=
+  s #1 "{vv~}{ll}" format.name$
+  s num.names$ duplicate$
+  #2 >
+    { pop$
+      " " * bbl.etal *
+    }
+    { #2 <
+        'skip$
+        { s #2 "{ff }{vv }{ll}{ jj}" format.name$ "others" =
+            {
+              " " * bbl.etal *
+            }
+            { bbl.and space.word * s #2 "{vv~}{ll}" format.name$
+              * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+
+FUNCTION {author.key.label}
+{ author empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {author.editor.key.label}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.lab.names }
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {editor.key.label}
+{ editor empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { editor format.lab.names }
+  if$
+}
+
+FUNCTION {calc.short.authors}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.label
+    { type$ "proceedings" =
+        'editor.key.label
+        'author.key.label
+      if$
+    }
+  if$
+  'short.list :=
+}
+
+FUNCTION {calc.label}
+{ calc.short.authors
+  short.list
+  "("
+  *
+  year duplicate$ empty$
+     { pop$ "????" }
+     { purify$ #-1 #4 substring$ }
+  if$
+  *
+  'label :=
+}
+
+FUNCTION {sort.format.names}
+{ 's :=
+  #1 'nameptr :=
+  ""
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv{ } }{ll{ }}{  f{ }}{  jj{ }}"
+      format.name$ 't :=
+      nameptr #1 >
+        {
+          "   "  *
+          namesleft #1 = t "others" = and
+            { "zzzzz" * }
+            { t sortify * }
+          if$
+        }
+        { t sortify * }
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {sort.format.title}
+{ 't :=
+  "A " #2
+    "An " #3
+      "The " #4 t chop.word
+    chop.word
+  chop.word
+  sortify
+  #1 global.max$ substring$
+}
+FUNCTION {author.sort}
+{ author empty$
+    { key empty$
+        { "to sort, need author or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {author.editor.sort}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { "to sort, need author, editor, or key in " cite$ * warning$
+              ""
+            }
+            { key sortify }
+          if$
+        }
+        { editor sort.format.names }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {editor.sort}
+{ editor empty$
+    { key empty$
+        { "to sort, need editor or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { editor sort.format.names }
+  if$
+}
+FUNCTION {presort}
+{ calc.label
+  label sortify
+  "    "
+  *
+  type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.sort
+    { type$ "proceedings" =
+        'editor.sort
+        'author.sort
+      if$
+    }
+  if$
+  #1 entry.max$ substring$
+  'sort.label :=
+  sort.label
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+
+ITERATE {presort}
+SORT
+STRINGS { last.label next.extra }
+INTEGERS { last.extra.num number.label }
+FUNCTION {initialize.extra.label.stuff}
+{ #0 int.to.chr$ 'last.label :=
+  "" 'next.extra :=
+  #0 'last.extra.num :=
+  #0 'number.label :=
+}
+FUNCTION {forward.pass}
+{ last.label label =
+    { last.extra.num #1 + 'last.extra.num :=
+      last.extra.num int.to.chr$ 'extra.label :=
+    }
+    { "a" chr.to.int$ 'last.extra.num :=
+      "" 'extra.label :=
+      label 'last.label :=
+    }
+  if$
+  number.label #1 + 'number.label :=
+}
+FUNCTION {reverse.pass}
+{ next.extra "b" =
+    { "a" 'extra.label := }
+    'skip$
+  if$
+  extra.label 'next.extra :=
+  extra.label
+  duplicate$ empty$
+    'skip$
+    { "{\natexlab{" swap$ * "}}" * }
+  if$
+  'extra.label :=
+  label extra.label * 'label :=
+}
+EXECUTE {initialize.extra.label.stuff}
+ITERATE {forward.pass}
+REVERSE {reverse.pass}
+FUNCTION {bib.sort.order}
+{ sort.label
+  "    "
+  *
+  year field.or.null sortify
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+ITERATE {bib.sort.order}
+SORT
+FUNCTION {begin.bib}
+{ preamble$ empty$
+    'skip$
+    { preamble$ write$ newline$ }
+  if$
+  "\begin{thebibliography}{" number.label int.to.str$ * "}" *
+  write$ newline$
+  "\providecommand{\natexlab}[1]{#1}"
+  write$ newline$
+  "\providecommand{\url}[1]{\texttt{#1}}"
+  write$ newline$
+  "\providecommand{\urlprefix}{URL }"
+  write$ newline$
+  "\expandafter\ifx\csname urlstyle\endcsname\relax"
+  write$ newline$
+  "  \providecommand{\doi}[1]{doi:\discretionary{}{}{}#1}\else"
+  write$ newline$
+  "  \providecommand{\doi}{doi:\discretionary{}{}{}\begingroup \urlstyle{rm}\Url}\fi"
+  write$ newline$
+  "\providecommand{\eprint}[2][]{\url{#2}}"
+  write$ newline$
+}
+EXECUTE {begin.bib}
+EXECUTE {init.state.consts}
+ITERATE {call.type$}
+FUNCTION {end.bib}
+{ newline$
+  "\end{thebibliography}" write$ newline$
+}
+EXECUTE {end.bib}
+%% End of customized bst file
+%%
+%% End of file `ametsoc7.bst'.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/abstract_foreword.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/abstract_foreword.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/abstract_foreword.tex	(revision 10321)
@@ -0,0 +1,55 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% Abstract
+% ================================================================
+
+\chapter*{Abstract}
+
+\vspace{-40pt}
+
+{\small
+The ocean engine of NEMO (Nucleus for European Modelling of the Ocean) is a primitive 
+equation model adapted to regional and global ocean circulation problems. It is intended to 
+be a flexible tool for studying the ocean and its interactions with the others components of 
+the earth climate system over a wide range of space and time scales. 
+Prognostic variables are the three-dimensional velocity field, a non-linear sea surface height, 
+the \textit{Conservative} Temperature and the \textit{Absolute} Salinity. 
+In the horizontal direction, the model uses a curvilinear orthogonal grid and in the vertical direction, 
+a full or partial step $z$-coordinate, or $s$-coordinate, or a mixture of the two. 
+The distribution of variables is a three-dimensional Arakawa C-type grid. 
+Various physical choices are available to describe ocean physics, including TKE, and GLS vertical physics. 
+Within NEMO, the ocean is interfaced with a sea-ice model (LIM or CICE), passive tracer and 
+biogeochemical models (TOP) and, via the OASIS coupler, with several atmospheric general circulation models. 
+It also support two-way grid embedding via the AGRIF software.
+} 
+
+% ================================================================
+% Disclaimer
+% ================================================================
+\chapter*{Disclaimer}
+
+Like all components of NEMO, the ocean component is developed under the \href{http://www.cecill.info/}{CECILL license}, 
+which is a French adaptation of the GNU GPL (General Public License). Anyone may use it 
+freely for research purposes, and is encouraged to communicate back to the NEMO team 
+its own developments and improvements. The model and the present document have been 
+made available as a service to the community. We cannot certify that the code and its manual 
+are free of errors. Bugs are inevitable and some have undoubtedly survived the testing phase. 
+Users are encouraged to bring them to our attention. The author assumes no responsibility 
+for problems, errors, or incorrect usage of NEMO.
+
+\vspace{1cm}
+NEMO reference in papers and other publications is as follows:
+\vspace{0.5cm}
+
+Madec, G., and the NEMO team, 2008: NEMO ocean engine. 
+\textit{Note du P\^ole de mod\'{e}lisation}, Institut Pierre-Simon Laplace (IPSL), France, 
+No 27, ISSN No 1288-1619.\\
+
+
+\vspace{0.5cm}
+Additional information can be found on \href{http://www.nemo-ocean.eu/}{www.nemo-ocean.eu}.
+\vspace{0.5cm}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_A.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_A.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_A.tex	(revision 10321)
@@ -0,0 +1,536 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% Chapter Ñ Appendix A : Curvilinear s-Coordinate Equations
+% ================================================================
+\chapter{Curvilinear $s-$Coordinate Equations}
+\label{apdx:A}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Chain rule
+% ================================================================
+\section{Chain rule for $s-$coordinates}
+\label{sec:A_chain}
+
+In order to establish the set of Primitive Equation in curvilinear $s$-coordinates
+($i.e.$ an orthogonal curvilinear coordinate in the horizontal and an Arbitrary Lagrangian 
+Eulerian (ALE) coordinate in the vertical), we start from the set of equations established 
+in \autoref{subsec:PE_zco_Eq} for the special case $k = z$ and thus $e_3 = 1$, and we introduce 
+an arbitrary vertical coordinate $a = a(i,j,z,t)$. Let us define a new vertical scale factor by 
+$e_3 = \partial z / \partial s$ (which now depends on $(i,j,z,t)$) and the horizontal 
+slope of $s-$surfaces by :
+\begin{equation} \label{apdx:A_s_slope}
+\sigma _1 =\frac{1}{e_1 }\;\left. {\frac{\partial z}{\partial i}} \right|_s 
+\quad \text{and} \quad 
+\sigma _2 =\frac{1}{e_2 }\;\left. {\frac{\partial z}{\partial j}} \right|_s 
+\end{equation}
+
+The chain rule to establish the model equations in the curvilinear $s-$coordinate 
+system is:
+\begin{equation} \label{apdx:A_s_chain_rule}
+\begin{aligned}
+&\left. {\frac{\partial \bullet }{\partial t}} \right|_z  =
+\left. {\frac{\partial \bullet }{\partial t}} \right|_s 
+	 -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial t} \\
+&\left. {\frac{\partial \bullet }{\partial i}} \right|_z  =
+  \left. {\frac{\partial \bullet }{\partial i}} \right|_s 
+  	  -\frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial i}=
+	  \left. {\frac{\partial \bullet }{\partial i}} \right|_s 
+	  -\frac{e_1 }{e_3 }\sigma _1 \frac{\partial \bullet }{\partial s} \\
+&\left. {\frac{\partial \bullet }{\partial j}} \right|_z  =
+\left. {\frac{\partial \bullet }{\partial j}} \right|_s 
+	- \frac{\partial \bullet }{\partial s}\;\frac{\partial s}{\partial j}=
+\left. {\frac{\partial \bullet }{\partial j}} \right|_s 
+	- \frac{e_2 }{e_3 }\sigma _2 \frac{\partial \bullet }{\partial s} \\
+&\;\frac{\partial \bullet }{\partial z}  \;\; = \frac{1}{e_3 }\frac{\partial \bullet }{\partial s} \\
+\end{aligned}
+\end{equation}
+
+In particular applying the time derivative chain rule to $z$ provides the expression 
+for $w_s$,  the vertical velocity of the $s-$surfaces referenced to a fix z-coordinate:
+\begin{equation} \label{apdx:A_w_in_s}
+w_s   =  \left.   \frac{\partial z }{\partial t}   \right|_s 
+				= \frac{\partial z}{\partial s} \; \frac{\partial s}{\partial t} 
+			    = e_3 \, \frac{\partial s}{\partial t} 
+\end{equation}
+
+
+% ================================================================
+% continuity equation
+% ================================================================
+\section{Continuity equation in $s-$coordinates}
+\label{sec:A_continuity}
+
+Using (\autoref{apdx:A_s_chain_rule}) and the fact that the horizontal scale factors 
+$e_1$ and $e_2$ do not depend on the vertical coordinate, the divergence of 
+the velocity relative to the ($i$,$j$,$z$) coordinate system is transformed as follows
+in order to obtain its expression in the curvilinear $s-$coordinate system:
+
+\begin{subequations} 
+\begin{align*} {\begin{array}{*{20}l} 
+\nabla \cdot {\rm {\bf U}} 
+&= \frac{1}{e_1 \,e_2 }  \left[ \left. {\frac{\partial (e_2 \,u)}{\partial i}} \right|_z 
+						+\left. {\frac{\partial(e_1 \,v)}{\partial j}} \right|_z  \right]
++ \frac{\partial w}{\partial z} 		\\
+\\
+&     = \frac{1}{e_1 \,e_2 }  \left[ 
+		  \left.   \frac{\partial (e_2 \,u)}{\partial i}    \right|_s       
+		  - \frac{e_1 }{e_3 } \sigma _1 \frac{\partial (e_2 \,u)}{\partial s}
+		+ \left.   \frac{\partial (e_1 \,v)}{\partial j}    \right|_s       
+		  - \frac{e_2 }{e_3 } \sigma _2 \frac{\partial (e_1 \,v)}{\partial s}	\right]
+	+ \frac{\partial w}{\partial s} \; \frac{\partial s}{\partial z}                        \\
+\\
+&     = \frac{1}{e_1 \,e_2 }   \left[ 
+		  \left.   \frac{\partial (e_2 \,u)}{\partial i}    \right|_s       
+		+ \left.   \frac{\partial (e_1 \,v)}{\partial j}    \right|_s       	\right]
+	+ \frac{1}{e_3 }\left[        \frac{\partial w}{\partial s}
+						-  \sigma _1 \frac{\partial u}{\partial s}
+						-  \sigma _2 \frac{\partial v}{\partial s}      \right]          \\
+\\
+&     = \frac{1}{e_1 \,e_2 \,e_3 }   \left[ 
+		  \left.   \frac{\partial (e_2 \,e_3 \,u)}{\partial i}    \right|_s  
+		  -\left.    e_2 \,u    \frac{\partial e_3 }{\partial i}     \right|_s      
+		+ \left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j}    \right|_s
+		  - \left.    e_1 v      \frac{\partial e_3 }{\partial j}    \right|_s   \right]          \\
+& \qquad \qquad \qquad \qquad \qquad \qquad \qquad \qquad \qquad
+	+ \frac{1}{e_3 } \left[        \frac{\partial w}{\partial s}
+						-  \sigma _1 \frac{\partial u}{\partial s}
+						-  \sigma _2 \frac{\partial v}{\partial s}      \right]      \\
+%
+\intertext{Noting that $
+  \frac{1}{e_1} \left.{ \frac{\partial e_3}{\partial i}} \right|_s 
+=\frac{1}{e_1} \left.{ \frac{\partial^2 z}{\partial i\,\partial s}} \right|_s 
+=\frac{\partial}{\partial s} \left( {\frac{1}{e_1 } \left.{ \frac{\partial z}{\partial i} }\right|_s } \right)
+=\frac{\partial \sigma _1}{\partial s}
+$ and $
+\frac{1}{e_2 }\left. {\frac{\partial e_3 }{\partial j}} \right|_s 
+=\frac{\partial \sigma _2}{\partial s}
+$, it becomes:}
+%
+\nabla \cdot {\rm {\bf U}} 
+& = \frac{1}{e_1 \,e_2 \,e_3 }  \left[   
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]        \\ 
+& \qquad \qquad \qquad \qquad \quad
+ +\frac{1}{e_3 }\left[ {\frac{\partial w}{\partial s}-u\frac{\partial \sigma _1 }{\partial s}-v\frac{\partial \sigma _2 }{\partial s}-\sigma _1 \frac{\partial u}{\partial s}-\sigma _2 \frac{\partial v}{\partial s}} \right] \\ 
+\\
+& = \frac{1}{e_1 \,e_2 \,e_3 }  \left[   
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]      
+   + \frac{1}{e_3 } \; \frac{\partial}{\partial s}   \left[  w -  u\;\sigma _1  - v\;\sigma _2  \right]
+\end{array} } 		
+\end{align*}
+\end{subequations}
+
+Here, $w$ is the vertical velocity relative to the $z-$coordinate system. 
+Introducing the dia-surface velocity component, $\omega $, defined as 
+the volume flux across the moving $s$-surfaces per unit horizontal area:
+\begin{equation} \label{apdx:A_w_s}
+\omega  = w - w_s - \sigma _1 \,u - \sigma _2 \,v    \\
+\end{equation}
+with $w_s$ given by \autoref{apdx:A_w_in_s}, we obtain the expression for 
+the divergence of the velocity in the curvilinear $s-$coordinate system:
+\begin{subequations} 
+\begin{align*} {\begin{array}{*{20}l} 
+\nabla \cdot {\rm {\bf U}} 
+&= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]      
++ \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
++ \frac{1}{e_3 } \frac{\partial w_s       }{\partial s}    \\
+\\
+&= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]      
++ \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
++ \frac{1}{e_3 } \frac{\partial}{\partial s}  \left(  e_3 \; \frac{\partial s}{\partial t}   \right)   \\
+\\
+&= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]      
++ \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
++ \frac{\partial}{\partial s} \frac{\partial s}{\partial t}
++ \frac{1}{e_3 } \frac{\partial s}{\partial t} \frac{\partial e_3}{\partial s}     \\
+\\
+&= \frac{1}{e_1 \,e_2 \,e_3 }    \left[ 
+		  \left.  \frac{\partial (e_2 \,e_3 \,u)}{\partial i} \right|_s 
+		+\left.  \frac{\partial (e_1 \,e_3 \,v)}{\partial j} \right|_s        \right]      
++ \frac{1}{e_3 } \frac{\partial \omega }{\partial s} 
++ \frac{1}{e_3 } \frac{\partial e_3}{\partial t}     \\
+\end{array} } 		
+\end{align*}
+\end{subequations}
+
+As a result, the continuity equation \autoref{eq:PE_continuity} in the 
+$s-$coordinates is:
+\begin{equation} \label{apdx:A_sco_Continuity}
+\frac{1}{e_3 } \frac{\partial e_3}{\partial t} 
++ \frac{1}{e_1 \,e_2 \,e_3 }\left[ 
+			{\left. {\frac{\partial (e_2 \,e_3 \,u)}{\partial i}} \right|_s 
+		    +  \left. {\frac{\partial (e_1 \,e_3 \,v)}{\partial j}} \right|_s } \right]
+ +\frac{1}{e_3 }\frac{\partial \omega }{\partial s} = 0   
+\end{equation}
+A additional term has appeared that take into account the contribution of the time variation 
+of the vertical coordinate to the volume budget.
+
+
+% ================================================================
+% momentum equation
+% ================================================================
+\section{Momentum equation in $s-$coordinate}
+\label{sec:A_momentum}
+
+Here we only consider the first component of the momentum equation, 
+the generalization to the second one being straightforward.
+
+$\ $\newline    % force a new ligne
+
+$\bullet$ \textbf{Total derivative in vector invariant form}
+
+Let us consider \autoref{eq:PE_dyn_vect}, the first component of the momentum 
+equation in the vector invariant form. Its total $z-$coordinate time derivative, 
+$\left. \frac{D u}{D t} \right|_z$ can be transformed as follows in order to obtain 
+its expression in the curvilinear $s-$coordinate system:
+
+\begin{subequations} 
+\begin{align*} {\begin{array}{*{20}l} 
+\left. \frac{D u}{D t} \right|_z 
+&= \left. {\frac{\partial u }{\partial t}} \right|_z 
+   - \left. \zeta \right|_z v 
+  + \frac{1}{2e_1} \left.{ \frac{\partial (u^2+v^2)}{\partial i}} \right|_z 
+  + w \;\frac{\partial u}{\partial z} \\
+\\
+&= \left. {\frac{\partial u }{\partial t}} \right|_z 
+   - \left. \zeta \right|_z v 
+  +  \frac{1}{e_1 \,e_2 }\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} }\right|_z 
+                                             -\left.{ \frac{\partial (e_1 \,u)}{\partial j} }\right|_z } \right] \; v     
+  +  \frac{1}{2e_1} \left.{ \frac{\partial (u^2+v^2)}{\partial i} } \right|_z 
+  +  w \;\frac{\partial u}{\partial z}      \\
+%
+\intertext{introducing the chain rule (\autoref{apdx:A_s_chain_rule}) }
+%
+&= \left. {\frac{\partial u }{\partial t}} \right|_z       
+   - \frac{1}{e_1\,e_2}\left[ { \left.{ \frac{\partial (e_2 \,v)}{\partial i} } \right|_s 
+                                          -\left.{ \frac{\partial (e_1 \,u)}{\partial j} } \right|_s } \right.
+                                          \left. {-\frac{e_1}{e_3}\sigma _1 \frac{\partial (e_2 \,v)}{\partial s}
+                                                   +\frac{e_2}{e_3}\sigma _2 \frac{\partial (e_1 \,u)}{\partial s}} \right] \; v  \\ 
+& \qquad \qquad \qquad \qquad
+ { + \frac{1}{2e_1} \left(                                  \left.  \frac{\partial (u^2+v^2)}{\partial i} \right|_s 
+                                    - \frac{e_1}{e_3}\sigma _1 \frac{\partial (u^2+v^2)}{\partial s}               \right)
+   + \frac{w}{e_3 } \;\frac{\partial u}{\partial s} }    \\
+\\
+&= \left. {\frac{\partial u }{\partial t}} \right|_z       
+  + \left. \zeta \right|_s \;v
+  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s      \\
+&\qquad \qquad \qquad \quad
+  + \frac{w}{e_3 } \;\frac{\partial u}{\partial s}
+   - \left[   {\frac{\sigma _1 }{e_3 }\frac{\partial v}{\partial s}
+               - \frac{\sigma_2 }{e_3 }\frac{\partial u}{\partial s}}   \right]\;v      
+   - \frac{\sigma _1 }{2e_3 }\frac{\partial (u^2+v^2)}{\partial s}      \\
+\\
+&= \left. {\frac{\partial u }{\partial t}} \right|_z       
+  + \left. \zeta \right|_s \;v
+  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s      \\
+&\qquad \qquad \qquad \quad
+ + \frac{1}{e_3} \left[    {w\frac{\partial u}{\partial s}
+	                        +\sigma _1 v\frac{\partial v}{\partial s} - \sigma _2 v\frac{\partial u}{\partial s}
+	                        - \sigma _1 u\frac{\partial u}{\partial s} - \sigma _1 v\frac{\partial v}{\partial s}} \right] \\
+\\
+&= \left. {\frac{\partial u }{\partial t}} \right|_z       
+  + \left. \zeta \right|_s \;v
+  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s  
+  + \frac{1}{e_3} \left[  w - \sigma _2 v - \sigma _1 u  \right] 
+		  			 \; \frac{\partial u}{\partial s}   \\
+%
+\intertext{Introducing $\omega$, the dia-a-surface velocity given by (\autoref{apdx:A_w_s}) }
+%
+&= \left. {\frac{\partial u }{\partial t}} \right|_z       
+  + \left. \zeta \right|_s \;v
+  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s  
+  + \frac{1}{e_3 } \left( \omega - w_s \right) \frac{\partial u}{\partial s}   \\
+\end{array} } 		
+\end{align*}
+\end{subequations}
+%
+Applying the time derivative chain rule (first equation of (\autoref{apdx:A_s_chain_rule}))
+to $u$ and using (\autoref{apdx:A_w_in_s}) provides the expression of the last term 
+of the right hand side,
+\begin{equation*} {\begin{array}{*{20}l} 
+w_s  \;\frac{\partial u}{\partial s} 
+	= \frac{\partial s}{\partial t} \;  \frac{\partial u }{\partial s}
+	= \left. {\frac{\partial u }{\partial t}} \right|_s  - \left. {\frac{\partial u }{\partial t}} \right|_z \quad , 
+\end{array} } 		
+\end{equation*}
+leads to the $s-$coordinate formulation of the total $z-$coordinate time derivative, 
+$i.e.$ the total $s-$coordinate time derivative :
+\begin{align} \label{apdx:A_sco_Dt_vect}
+\left. \frac{D u}{D t} \right|_s 
+  = \left. {\frac{\partial u }{\partial t}} \right|_s       
+  + \left. \zeta \right|_s \;v
+  + \frac{1}{2\,e_1}\left. {\frac{\partial (u^2+v^2)}{\partial i}} \right|_s  
+  + \frac{1}{e_3 } \omega \;\frac{\partial u}{\partial s}   
+\end{align}
+Therefore, the vector invariant form of the total time derivative has exactly the same 
+mathematical form in $z-$ and $s-$coordinates. This is not the case for the flux form
+as shown in next paragraph.
+
+$\ $\newline    % force a new ligne
+
+$\bullet$ \textbf{Total derivative in flux form}
+
+Let us start from the total time derivative in the curvilinear $s-$coordinate system 
+we have just establish. Following the procedure used to establish (\autoref{eq:PE_flux_form}), 
+it can be transformed into :
+%\begin{subequations} 
+\begin{align*} {\begin{array}{*{20}l} 
+\left. \frac{D u}{D t} \right|_s  &= \left. {\frac{\partial u }{\partial t}} \right|_s  
+           					    & -  \zeta \;v 
+           					+ \frac{1}{2\;e_1 } \frac{\partial \left( {u^2+v^2} \right)}{\partial i}
+                                                 + \frac{1}{e_3} \omega \;\frac{\partial u}{\partial s}          \\
+\\
+  &= \left. {\frac{\partial u }{\partial t}} \right|_s  
+          &+\frac{1}{e_1\;e_2}  \left(    \frac{\partial \left( {e_2 \,u\,u } \right)}{\partial i}
+		                                    + \frac{\partial \left( {e_1 \,u\,v } \right)}{\partial j}     \right)
+            + \frac{1}{e_3 } \frac{\partial \left( {\omega\,u} \right)}{\partial s}                                \\ 
+\\
+        &&- \,u \left[     \frac{1}{e_1 e_2 } \left(    \frac{\partial(e_2 u)}{\partial i}
+				  	  	                 + \frac{\partial(e_1 v)}{\partial j}    \right)
+                          + \frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right]      \\
+\\
+        &&- \frac{v}{e_1 e_2 }\left(    v	\;\frac{\partial e_2 }{\partial i}
+				 	           -u	\;\frac{\partial e_1 }{\partial j} 	\right)                             \\
+\end{array} } 		
+\end{align*}
+%
+Introducing the vertical scale factor inside the horizontal derivative of the first two terms 
+($i.e.$ the horizontal divergence), it becomes :
+\begin{subequations} 
+\begin{align*} {\begin{array}{*{20}l} 
+%\begin{align*} {\begin{array}{*{20}l} 
+%{\begin{array}{*{20}l} 
+\left. \frac{D u}{D t} \right|_s  
+   &= \left. {\frac{\partial u }{\partial t}} \right|_s  
+   &+ \frac{1}{e_1\,e_2\,e_3}  \left(  \frac{\partial( e_2 e_3 \,u^2 )}{\partial i}
+			                  		  + \frac{\partial( e_1 e_3 \,u v )}{\partial j}     
+	     							   -  e_2 u u \frac{\partial e_3}{\partial i}
+							  -  e_1 u v \frac{\partial e_3 }{\partial j}    \right)
+	    + \frac{1}{e_3} \frac{\partial \left( {\omega\,u} \right)}{\partial s}                                  \\
+\\
+           && - \,u \left[  \frac{1}{e_1 e_2 e_3} \left(   \frac{\partial(e_2 e_3 \, u)}{\partial i} 
+			   							 + \frac{\partial(e_1 e_3 \, v)}{\partial j}  
+	                							 -  e_2 u \;\frac{\partial e_3 }{\partial i}
+				 	  	                      -  e_1 v \;\frac{\partial e_3 }{\partial j}   \right)
+             -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right]                      \\
+\\
+            && - \frac{v}{e_1 e_2 }\left( 	v  \;\frac{\partial e_2 }{\partial i}
+				     	              -u  \;\frac{\partial e_1 }{\partial j} 	\right)                      \\
+\\
+   &= \left. {\frac{\partial u }{\partial t}} \right|_s  
+   &+ \frac{1}{e_1\,e_2\,e_3}  \left(  \frac{\partial( e_2 e_3 \,u\,u )}{\partial i}
+			                  		  + \frac{\partial( e_1 e_3 \,u\,v )}{\partial j}    \right)
+     + \frac{1}{e_3 } \frac{\partial \left( {\omega\,u} \right)}{\partial s}                               \\
+\\
+&& - \,u \left[  \frac{1}{e_1 e_2 e_3} \left(   \frac{\partial(e_2 e_3 \, u)}{\partial i} 
+									+ \frac{\partial(e_1 e_3 \, v)}{\partial j}  \right)
+        -\frac{1}{e_3}        \frac{\partial \omega}{\partial s}                       \right]                  
+     - \frac{v}{e_1 e_2 }\left( 	v   \;\frac{\partial e_2 }{\partial i}
+				            	      -u   \;\frac{\partial e_1 }{\partial j} 	\right)                  \\
+%
+\intertext {Introducing a more compact form for the divergence of the momentum fluxes, 
+and using (\autoref{apdx:A_sco_Continuity}), the $s-$coordinate continuity equation, 
+it becomes : }
+%
+   &= \left. {\frac{\partial u }{\partial t}} \right|_s  
+   &+ \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s
+     + \,u \frac{1}{e_3 } \frac{\partial e_3}{\partial t}    
+      - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
+				             -u  \;\frac{\partial e_1 }{\partial j} 	\right) \\
+\end{array} } 		
+\end{align*}
+\end{subequations}
+which leads to the $s-$coordinate flux formulation of the total $s-$coordinate time derivative, 
+$i.e.$ the total $s-$coordinate time derivative in flux form :
+\begin{flalign}\label{apdx:A_sco_Dt_flux}
+\left. \frac{D u}{D t} \right|_s   = \frac{1}{e_3}  \left. \frac{\partial ( e_3\,u)}{\partial t} \right|_s  
+           + \left.  \nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right)    \right|_s
+           - \frac{v}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
+				 	          -u  \;\frac{\partial e_1 }{\partial j}            \right)
+\end{flalign}
+which is the total time derivative expressed in the curvilinear $s-$coordinate system.
+It has the same form as in the $z-$coordinate but for the vertical scale factor 
+that has appeared inside the time derivative which comes from the modification 
+of (\autoref{apdx:A_sco_Continuity}), the continuity equation.
+
+$\ $\newline    % force a new ligne
+
+$\bullet$ \textbf{horizontal pressure gradient}
+
+The horizontal pressure gradient term can be transformed as follows:
+\begin{equation*}
+\begin{split}
+ -\frac{1}{\rho _o \, e_1 }\left. {\frac{\partial p}{\partial i}} \right|_z
+ & =-\frac{1}{\rho _o e_1 }\left[ {\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{e_1 }{e_3 }\sigma _1 \frac{\partial p}{\partial s}} \right] \\
+& =-\frac{1}{\rho _o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s +\frac{\sigma _1 }{\rho _o \,e_3 }\left( {-g\;\rho \;e_3 } \right) \\
+&=-\frac{1}{\rho _o \,e_1 }\left. {\frac{\partial p}{\partial i}} \right|_s -\frac{g\;\rho }{\rho _o }\sigma _1
+\end{split}
+\end{equation*}
+Applying similar manipulation to the second component and replacing 
+$\sigma _1$ and $\sigma _2$ by their expression \autoref{apdx:A_s_slope}, it comes:
+\begin{equation} \label{apdx:A_grad_p_1}
+\begin{split}
+ -\frac{1}{\rho _o \, e_1 } \left. {\frac{\partial p}{\partial i}} \right|_z
+&=-\frac{1}{\rho _o \,e_1 } \left(     \left.              {\frac{\partial p}{\partial i}} \right|_s 
+                                                  + g\;\rho  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right) \\
+%
+ -\frac{1}{\rho _o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z
+&=-\frac{1}{\rho _o \,e_2 } \left(    \left.               {\frac{\partial p}{\partial j}} \right|_s 
+                                                   + g\;\rho \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right) \\
+\end{split}
+\end{equation}
+
+An additional term appears in (\autoref{apdx:A_grad_p_1}) which accounts for the 
+tilt of $s-$surfaces with respect to geopotential $z-$surfaces.
+
+As in $z$-coordinate, the horizontal pressure gradient can be split in two parts
+following \citet{Marsaleix_al_OM08}. Let defined a density anomaly, $d$, by $d=(\rho - \rho_o)/ \rho_o$,
+and a hydrostatic pressure anomaly, $p_h'$, by $p_h'= g \; \int_z^\eta d \; e_3 \; dk$. 
+The pressure is then given by:
+\begin{equation*} 
+\begin{split}
+p &= g\; \int_z^\eta \rho \; e_3 \; dk = g\; \int_z^\eta \left(  \rho_o \, d + 1 \right) \; e_3 \; dk   \\
+   &= g \, \rho_o \; \int_z^\eta d \; e_3 \; dk + g \, \int_z^\eta e_3 \; dk    
+\end{split}
+\end{equation*}
+Therefore, $p$ and $p_h'$ are linked through:
+\begin{equation} \label{apdx:A_pressure}
+   p = \rho_o \; p_h' + g \, ( z + \eta )
+\end{equation}
+and the hydrostatic pressure balance expressed in terms of $p_h'$ and $d$ is:
+\begin{equation*} 
+\frac{\partial p_h'}{\partial k} = - d \, g \, e_3
+\end{equation*}
+
+Substituing \autoref{apdx:A_pressure} in \autoref{apdx:A_grad_p_1} and using the definition of 
+the density anomaly it comes the expression in two parts:
+\begin{equation} \label{apdx:A_grad_p_2}
+\begin{split}
+ -\frac{1}{\rho _o \, e_1 } \left. {\frac{\partial p}{\partial i}} \right|_z
+&=-\frac{1}{e_1 } \left(     \left.              {\frac{\partial p_h'}{\partial i}} \right|_s 
+                                       + g\; d  \;\left. {\frac{\partial z}{\partial i}} \right|_s    \right)  - \frac{g}{e_1 } \frac{\partial \eta}{\partial i} \\
+%
+ -\frac{1}{\rho _o \, e_2 }\left. {\frac{\partial p}{\partial j}} \right|_z
+&=-\frac{1}{e_2 } \left(    \left.               {\frac{\partial p_h'}{\partial j}} \right|_s 
+                                        + g\; d \;\left. {\frac{\partial z}{\partial j}} \right|_s   \right)  - \frac{g}{e_2 } \frac{\partial \eta}{\partial j}\\
+\end{split}
+\end{equation}
+This formulation of the pressure gradient is characterised by the appearance of a term depending on the 
+the sea surface height only (last term on the right hand side of expression \autoref{apdx:A_grad_p_2}).
+This term will be loosely termed \textit{surface pressure gradient}
+whereas the first term will be termed the 
+\textit{hydrostatic pressure gradient} by analogy to the $z$-coordinate formulation. 
+In fact, the the true surface pressure gradient is $1/\rho_o \nabla (\rho \eta)$, and 
+$\eta$ is implicitly included in the computation of $p_h'$ through the upper bound of 
+the vertical integration.
+ 
+
+$\ $\newline    % force a new ligne
+
+$\bullet$ \textbf{The other terms of the momentum equation}
+
+The coriolis and forcing terms as well as the the vertical physics remain unchanged 
+as they involve neither time nor space derivatives. The form of the lateral physics is 
+discussed in \autoref{apdx:B}.
+
+
+$\ $\newline    % force a new ligne
+
+$\bullet$ \textbf{Full momentum equation}
+
+To sum up, in a curvilinear $s$-coordinate system, the vector invariant momentum equation 
+solved by the model has the same mathematical expression as the one in a curvilinear 
+$z-$coordinate, except for the pressure gradient term :
+\begin{subequations} \label{apdx:A_dyn_vect}
+\begin{multline} \label{apdx:A_PE_dyn_vect_u}
+ \frac{\partial u}{\partial t}=
+	+   \left( {\zeta +f} \right)\,v                                    
+	-   \frac{1}{2\,e_1} \frac{\partial}{\partial i} \left(  u^2+v^2   \right) 
+	-   \frac{1}{e_3} \omega \frac{\partial u}{\partial k}       \\
+        -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right)  
+        -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i}
+	+   D_u^{\vect{U}}  +   F_u^{\vect{U}}
+\end{multline}
+\begin{multline} \label{apdx:A_dyn_vect_v}
+\frac{\partial v}{\partial t}=
+	-   \left( {\zeta +f} \right)\,u   
+	-   \frac{1}{2\,e_2 }\frac{\partial }{\partial j}\left(  u^2+v^2  \right)     	
+	-   \frac{1}{e_3 } \omega \frac{\partial v}{\partial k}         \\
+        -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right)  
+        -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j}
+	+  D_v^{\vect{U}}  +   F_v^{\vect{U}}
+\end{multline}
+\end{subequations}
+whereas the flux form momentum equation differ from it by the formulation of both
+the time derivative and the pressure gradient term  :
+\begin{subequations} \label{apdx:A_dyn_flux}
+\begin{multline} \label{apdx:A_PE_dyn_flux_u}
+ \frac{1}{e_3} \frac{\partial \left(  e_3\,u  \right) }{\partial t} =
+	\nabla \cdot \left(   {{\rm {\bf U}}\,u}   \right) 
+	+   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
+				 	                        -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,v     \\                               
+        -   \frac{1}{e_1 } \left(    \frac{\partial p_h'}{\partial i} + g\; d  \; \frac{\partial z}{\partial i}    \right)  
+        -   \frac{g}{e_1 } \frac{\partial \eta}{\partial i}
+	+   D_u^{\vect{U}}  +   F_u^{\vect{U}}
+\end{multline}
+\begin{multline} \label{apdx:A_dyn_flux_v}
+ \frac{1}{e_3}\frac{\partial \left(  e_3\,v  \right) }{\partial t}=
+	-  \nabla \cdot \left(   {{\rm {\bf U}}\,v}   \right) 
+	+   \left\{ {f + \frac{1}{e_1 e_2 }\left(    v  \;\frac{\partial e_2 }{\partial i}
+				 	                         -u  \;\frac{\partial e_1 }{\partial j}            \right)} \right\} \,u     \\                               
+        -   \frac{1}{e_2 } \left(    \frac{\partial p_h'}{\partial j} + g\; d  \; \frac{\partial z}{\partial j}    \right)  
+        -   \frac{g}{e_2 } \frac{\partial \eta}{\partial j}
+	+  D_v^{\vect{U}}  +   F_v^{\vect{U}}
+\end{multline}
+\end{subequations}
+Both formulation share the same hydrostatic pressure balance expressed in terms of
+hydrostatic pressure and density anomalies, $p_h'$ and $d=( \frac{\rho}{\rho_o}-1 )$:
+\begin{equation} \label{apdx:A_dyn_zph}
+\frac{\partial p_h'}{\partial k} = - d \, g \, e_3
+\end{equation}
+
+It is important to realize that the change in coordinate system has only concerned
+the position on the vertical. It has not affected (\textbf{i},\textbf{j},\textbf{k}), the 
+orthogonal curvilinear set of unit vectors. ($u$,$v$) are always horizontal velocities
+so that their evolution is driven by \emph{horizontal} forces, in particular 
+the pressure gradient. By contrast, $\omega$ is not $w$, the third component of the velocity,
+but the dia-surface velocity component, $i.e.$ the volume flux across the moving 
+$s$-surfaces per unit horizontal area. 
+
+
+% ================================================================
+% Tracer equation
+% ================================================================
+\section{Tracer equation}
+\label{sec:A_tracer}
+
+The tracer equation is obtained using the same calculation as for the continuity 
+equation and then regrouping the time derivative terms in the left hand side :
+
+\begin{multline} \label{apdx:A_tracer}
+ \frac{1}{e_3} \frac{\partial \left(  e_3 T  \right)}{\partial t} 
+ 	= -\frac{1}{e_1 \,e_2 \,e_3} 
+		\left[           \frac{\partial }{\partial i} \left( {e_2 \,e_3 \;Tu} \right) 
+		             +   \frac{\partial }{\partial j} \left( {e_1 \,e_3 \;Tv} \right)               \right]       \\
+ 	+  \frac{1}{e_3}  \frac{\partial }{\partial k} \left(                   Tw  \right)  
+	 +  D^{T} +F^{T}
+\end{multline}
+
+
+The expression for the advection term is a straight consequence of (A.4), the 
+expression of the 3D divergence in the $s-$coordinates established above. 
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_B.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_B.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_B.tex	(revision 10321)
@@ -0,0 +1,368 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter Ñ Appendix B : Diffusive Operators
+% ================================================================
+\chapter{Appendix B : Diffusive Operators}
+\label{apdx:B}
+\minitoc
+
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Horizontal/Vertical 2nd Order Tracer Diffusive Operators
+% ================================================================
+\section{Horizontal/Vertical $2^{nd}$ order tracer diffusive operators}
+\label{sec:B_1}
+
+\subsubsection*{In z-coordinates}
+In $z$-coordinates, the horizontal/vertical second order tracer diffusion operator
+is given by:
+\begin{eqnarray} \label{apdx:B1}
+ &D^T = \frac{1}{e_1 \, e_2}      \left[
+  \left. \frac{\partial}{\partial i} \left( 	\frac{e_2}{e_1}A^{lT} \;\left. \frac{\partial T}{\partial i} \right|_z   \right)   \right|_z      \right.
+  						     \left.
++ \left. \frac{\partial}{\partial j} \left(  \frac{e_1}{e_2}A^{lT} \;\left. \frac{\partial T}{\partial j} \right|_z   \right)   \right|_z      \right]
++ \frac{\partial }{\partial z}\left( {A^{vT} \;\frac{\partial T}{\partial z}} \right)
+\end{eqnarray}
+
+\subsubsection*{In generalized vertical coordinates}
+In $s$-coordinates, we defined the slopes of $s$-surfaces, $\sigma_1$ and
+$\sigma_2$ by \autoref{apdx:A_s_slope} and the vertical/horizontal ratio of diffusion
+coefficient by $\epsilon = A^{vT} / A^{lT}$. The diffusion operator is given by:
+
+\begin{equation} \label{apdx:B2}
+D^T = \left. \nabla \right|_s \cdot
+           \left[ A^{lT} \;\Re \cdot \left. \nabla \right|_s T  \right] \\
+\;\;\text{where} \;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-\sigma _1 } \hfill \\
+ 0 \hfill & 1 \hfill & {-\sigma _2 } \hfill \\
+ {-\sigma _1 } \hfill & {-\sigma _2 } \hfill & {\varepsilon +\sigma _1
+^2+\sigma _2 ^2} \hfill \\
+\end{array} }} \right)
+\end{equation}
+or in expanded form:
+\begin{subequations}
+\begin{align*} {\begin{array}{*{20}l}
+D^T=& \frac{1}{e_1\,e_2\,e_3 }\;\left[ {\ \ \ \ e_2\,e_3\,A^{lT} \;\left.
+{\frac{\partial }{\partial i}\left( {\frac{1}{e_1}\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma _1 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.  \\
+&\qquad \quad \ \ \ +e_1\,e_3\,A^{lT} \;\left. {\frac{\partial }{\partial j}\left( {\frac{1}{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s -\frac{\sigma _2 }{e_3 }\;\frac{\partial T}{\partial s}} \right)} \right|_s \\
+&\qquad \quad \ \ \ + e_1\,e_2\,A^{lT} \;\frac{\partial }{\partial s}\left( {-\frac{\sigma _1 }{e_1 }\;\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{\sigma _2 }{e_2 }\;\left. {\frac{\partial T}{\partial j}} \right|_s } \right.
+ \left. {\left. {+\left( {\varepsilon +\sigma _1^2+\sigma _2 ^2} \right)\;\frac{1}{e_3 }\;\frac{\partial T}{\partial s}} \right)\;\;} \right]
+\end{array} }
+\end{align*}
+\end{subequations}
+
+Equation \autoref{apdx:B2} is obtained from \autoref{apdx:B1} without any
+additional assumption. Indeed, for the special case $k=z$ and thus $e_3 =1$,
+we introduce an arbitrary vertical coordinate $s = s (i,j,z)$ as in \autoref{apdx:A}
+and use \autoref{apdx:A_s_slope} and \autoref{apdx:A_s_chain_rule}.
+Since no cross horizontal derivative $\partial _i \partial _j $ appears in
+\autoref{apdx:B1}, the ($i$,$z$) and ($j$,$z$) planes are independent.
+The derivation can then be demonstrated for the ($i$,$z$)~$\to$~($j$,$s$)
+transformation without any loss of generality:
+
+\begin{subequations}
+\begin{align*} {\begin{array}{*{20}l}
+D^T&=\frac{1}{e_1\,e_2} \left. {\frac{\partial }{\partial i}\left( {\frac{e_2}{e_1}A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_z } \right)} \right|_z
+                     +\frac{\partial }{\partial z}\left( {A^{vT}\;\frac{\partial T}{\partial z}} \right)     \\
+ \\
+%
+&=\frac{1}{e_1\,e_2 }\left[ {\left. {\;\frac{\partial }{\partial i}\left( {\frac{e_2}{e_1}A^{lT}\;\left( {\left. {\frac{\partial T}{\partial i}} \right|_s
+                                                    -\frac{e_1\,\sigma _1 }{e_3 }\frac{\partial T}{\partial s}} \right)} \right)} \right|_s } \right. \\
+& \qquad \qquad \left. { -\frac{e_1\,\sigma _1 }{e_3 }\frac{\partial }{\partial s}\left( {\frac{e_2 }{e_1 }A^{lT}\;\left. {\left( {\left. {\frac{\partial T}{\partial i}} \right|_s -\frac{e_1 \,\sigma _1 }{e_3 }\frac{\partial T}{\partial s}} \right)} \right|_s } \right)\;} \right]
+\shoveright{ +\frac{1}{e_3 }\frac{\partial }{\partial s}\left[ {\frac{A^{vT}}{e_3 }\;\frac{\partial T}{\partial s}} \right]}  \qquad \qquad \qquad \\
+ \\
+%
+&=\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s -\left. {\frac{e_2 }{e_1}A^{lT}\;\frac{\partial e_3 }{\partial i}} \right|_s \left. {\frac{\partial T}{\partial i}} \right|_s } \right. \\
+&  \qquad \qquad \quad \left. {-e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma _1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s -e_1 \,\sigma _1 \frac{\partial }{\partial s}\left( {\frac{e_2 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\
+&  \qquad \qquad \quad \shoveright{ -e_1 \,\sigma _1 \frac{\partial }{\partial s}\left( {-\frac{e_2 \,\sigma _1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)\;\,\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\quad} \right] }\\
+\end{array} } 		\\
+%
+ {\begin{array}{*{20}l}
+\intertext{Noting that $\frac{1}{e_1} \left. \frac{\partial e_3 }{\partial i} \right|_s = \frac{\partial \sigma _1 }{\partial s}$, it becomes:}
+%
+& =\frac{1}{e_1\,e_2\,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2\,e_3 }{e_1}\,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. -\, {e_3 \frac{\partial }{\partial i}\left( {\frac{e_2 \,\sigma _1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
+& \qquad \qquad \quad -e_2 A^{lT}\;\frac{\partial \sigma _1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s -e_1 \,\sigma_1 \frac{\partial }{\partial s}\left( {\frac{e_2 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\
+& \qquad \qquad \quad\shoveright{ \left. { +e_1 \,\sigma _1 \frac{\partial }{\partial s}\left( {\frac{e_2 \,\sigma _1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial z}} \right)\;\;\;} \right] }\\
+\\
+&=\frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)} \right|_s \left. {-\frac{\partial }{\partial i}\left( {e_2 \,\sigma _1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
+& \qquad \qquad \quad \left. {+\frac{e_2 \,\sigma _1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s} \;\frac{\partial e_3 }{\partial i}}  \right|_s -e_2 A^{lT}\;\frac{\partial \sigma _1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s \\
+& \qquad \qquad \quad-e_2 \,\sigma _1 \frac{\partial}{\partial s}\left( {A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma _1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}} \right) \\
+& \qquad \qquad \quad\shoveright{ \left. {-\frac{\partial \left( {e_1 \,e_2 \,\sigma _1 } \right)}{\partial s} \left( {\frac{\sigma _1 }{e_3}A^{lT}\;\frac{\partial T}{\partial s}} \right) + \frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 }{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right]}
+\end{array} } \\
+{\begin{array}{*{20}l}
+%
+\intertext{using the same remark as just above, it becomes:}
+%
+&= \frac{1}{e_1 \,e_2 \,e_3 } \left[ {\left. {\;\;\;\frac{\partial }{\partial i} \left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma _1 A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right.\;\;\; \\
+& \qquad \qquad \quad+\frac{e_1 \,e_2 \,\sigma _1 }{e_3 }A^{lT}\;\frac{\partial T}{\partial s}\;\frac{\partial \sigma _1 }{\partial s} - \frac {\sigma _1 }{e_3} A^{lT} \;\frac{\partial \left( {e_1 \,e_2 \,\sigma _1 } \right)}{\partial s}\;\frac{\partial T}{\partial s} \\
+& \qquad \qquad \quad-e_2 \left( {A^{lT}\;\frac{\partial \sigma _1 }{\partial s}\left. {\frac{\partial T}{\partial i}} \right|_s +\frac{\partial }{\partial s}\left( {\sigma _1 A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right)-\frac{\partial \sigma _1 }{\partial s}\;A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s } \right) \\
+& \qquad \qquad \quad\shoveright{\left. {+\frac{\partial }{\partial s}\left( {\frac{e_1 \,e_2 \,\sigma _1 ^2}{e_3 }A^{lT}\;\frac{\partial T}{\partial s}+\frac{e_1 \,e_2}{e_3 }A^{vT}\;\frac{\partial T}{\partial s}} \right)\;\;\;} \right] }
+ \end{array} } \\
+{\begin{array}{*{20}l}
+%
+\intertext{Since the horizontal scale factors do not depend on the vertical coordinate,
+the last term of the first line and the first term of the last line cancel, while
+the second line reduces to a single vertical derivative, so it becomes:}
+%
+& =\frac{1}{e_1 \,e_2 \,e_3 }\left[ {\left. {\;\;\;\frac{\partial }{\partial i}\left( {\frac{e_2 \,e_3 }{e_1 }A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s -e_2 \,\sigma _1 \,A^{lT}\;\frac{\partial T}{\partial s}} \right)} \right|_s } \right. \\
+& \qquad \qquad \quad \shoveright{ \left. {+\frac{\partial }{\partial s}\left( {-e_2 \,\sigma _1 \,A^{lT}\;\left. {\frac{\partial T}{\partial i}} \right|_s +A^{lT}\frac{e_1 \,e_2 }{e_3 }\;\left( {\varepsilon +\sigma _1 ^2} \right)\frac{\partial T}{\partial s}} \right)\;\;\;} \right]}
+ \\
+%
+\intertext{in other words, the horizontal/vertical Laplacian operator in the ($i$,$s$) plane takes the following form:}
+\end{array} } \\
+%
+{\frac{1}{e_1\,e_2\,e_3}}
+\left( {{\begin{array}{*{30}c}
+{\left. {\frac{\partial \left( {e_2 e_3 \bullet } \right)}{\partial i}} \right|_s } \hfill \\
+{\frac{\partial \left( {e_1 e_2 \bullet } \right)}{\partial s}} \hfill \\
+\end{array}}}\right)
+\cdot \left[ {A^{lT}
+\left( {{\begin{array}{*{30}c}
+ {1} \hfill & {-\sigma_1 } \hfill \\
+ {-\sigma_1} \hfill & {\varepsilon + \sigma_1^2} \hfill \\
+\end{array} }} \right)
+\cdot
+\left( {{\begin{array}{*{30}c}
+{\frac{1}{e_1 }\;\left. {\frac{\partial \bullet }{\partial i}} \right|_s } \hfill \\
+{\frac{1}{e_3 }\;\frac{\partial \bullet }{\partial s}} \hfill \\
+\end{array}}}       \right) \left( T \right)} \right]
+\end{align*}
+\end{subequations}
+\addtocounter{equation}{-2}
+
+% ================================================================
+% Isopycnal/Vertical 2nd Order Tracer Diffusive Operators
+% ================================================================
+\section{Iso/Diapycnal $2^{nd}$ order tracer diffusive operators}
+\label{sec:B_2}
+
+\subsubsection*{In z-coordinates}
+
+The iso/diapycnal diffusive tensor $\textbf {A}_{\textbf I}$ expressed in the ($i$,$j$,$k$)
+curvilinear coordinate system in which the equations of the ocean circulation model are
+formulated, takes the following form \citep{Redi_JPO82}:
+
+\begin{equation} \label{apdx:B3}
+\textbf {A}_{\textbf I} = \frac{A^{lT}}{\left( {1+a_1 ^2+a_2 ^2} \right)}
+\left[ {{\begin{array}{*{20}c}
+ {1+a_1 ^2} \hfill & {-a_1 a_2 } \hfill & {-a_1 } \hfill \\
+ {-a_1 a_2 } \hfill & {1+a_2 ^2} \hfill & {-a_2 } \hfill \\
+ {-a_1 } \hfill & {-a_2 } \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\
+\end{array} }} \right]
+\end{equation}
+where ($a_1$, $a_2$) are the isopycnal slopes in ($\textbf{i}$,
+$\textbf{j}$) directions, relative to geopotentials:
+\begin{equation*}
+a_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1}
+\qquad , \qquad
+a_2 =\frac{e_3 }{e_2 }\left( {\frac{\partial \rho }{\partial j}}
+\right)\left( {\frac{\partial \rho }{\partial k}} \right)^{-1}
+\end{equation*}
+
+In practice, isopycnal slopes are generally less than $10^{-2}$ in the ocean, so
+$\textbf {A}_{\textbf I}$ can be simplified appreciably \citep{Cox1987}:
+\begin{subequations} \label{apdx:B4}
+\begin{equation} \label{apdx:B4a}
+{\textbf{A}_{\textbf{I}}} \approx A^{lT}\;\Re\;\text{where} \;\Re =
+\left[ {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-a_1 } \hfill \\
+ 0 \hfill & 1 \hfill & {-a_2 } \hfill \\
+ {-a_1 } \hfill & {-a_2 } \hfill & {\varepsilon +a_1 ^2+a_2 ^2} \hfill \\
+\end{array} }} \right],
+\end{equation}
+and the iso/dianeutral diffusive operator in $z$-coordinates is then
+\begin{equation}\label{apdx:B4b}
+ D^T = \left. \nabla \right|_z \cdot
+           \left[ A^{lT} \;\Re \cdot \left. \nabla \right|_z T  \right]. \\
+\end{equation}
+\end{subequations}
+
+
+Physically, the full tensor \autoref{apdx:B3}
+represents strong isoneutral diffusion on a plane parallel to the isoneutral
+surface and weak dianeutral diffusion perpendicular to this plane.
+However, the approximate `weak-slope' tensor \autoref{apdx:B4a} represents strong
+diffusion along the isoneutral surface, with weak
+\emph{vertical}  diffusion -- the principal axes of the tensor are no
+longer orthogonal. This simplification also decouples
+the ($i$,$z$) and ($j$,$z$) planes of the tensor. The weak-slope operator therefore takes the same
+form, \autoref{apdx:B4}, as \autoref{apdx:B2}, the diffusion operator for geopotential
+diffusion written in non-orthogonal $i,j,s$-coordinates. Written out
+explicitly,
+
+\begin{multline} \label{apdx:B_ldfiso}
+ D^T=\frac{1}{e_1 e_2 }\left\{
+ {\;\frac{\partial }{\partial i}\left[ {A_h \left( {\frac{e_2}{e_1}\frac{\partial T}{\partial i}-a_1 \frac{e_2}{e_3}\frac{\partial T}{\partial k}} \right)} \right]}
+ {+\frac{\partial}{\partial j}\left[ {A_h \left( {\frac{e_1}{e_2}\frac{\partial T}{\partial j}-a_2 \frac{e_1}{e_3}\frac{\partial T}{\partial k}} \right)} \right]\;} \right\} \\
+\shoveright{+\frac{1}{e_3 }\frac{\partial }{\partial k}\left[ {A_h \left( {-\frac{a_1 }{e_1 }\frac{\partial T}{\partial i}-\frac{a_2 }{e_2 }\frac{\partial T}{\partial j}+\frac{\left( {a_1 ^2+a_2 ^2+\varepsilon} \right)}{e_3 }\frac{\partial T}{\partial k}} \right)} \right]}. \\
+\end{multline}
+
+
+The isopycnal diffusion operator \autoref{apdx:B4},
+\autoref{apdx:B_ldfiso} conserves tracer quantity and dissipates its
+square. The demonstration of the first property is trivial as \autoref{apdx:B4} is the divergence
+of fluxes. Let us demonstrate the second one:
+\begin{equation*}
+\iiint\limits_D T\;\nabla .\left( {\textbf{A}}_{\textbf{I}} \nabla T \right)\,dv
+          = -\iiint\limits_D \nabla T\;.\left( {\textbf{A}}_{\textbf{I}} \nabla T \right)\,dv,
+\end{equation*}
+and since
+\begin{subequations}
+\begin{align*} {\begin{array}{*{20}l}
+\nabla T\;.\left( {{\rm {\bf A}}_{\rm {\bf I}} \nabla T}
+\right)&=A^{lT}\left[ {\left( {\frac{\partial T}{\partial i}} \right)^2-2a_1
+\frac{\partial T}{\partial i}\frac{\partial T}{\partial k}+\left(
+{\frac{\partial T}{\partial j}} \right)^2} \right. \\
+&\qquad \qquad \qquad
+{ \left. -\,{2a_2 \frac{\partial T}{\partial j}\frac{\partial T}{\partial k}+\left( {a_1 ^2+a_2 ^2+\varepsilon} \right)\left( {\frac{\partial T}{\partial k}} \right)^2} \right]} \\
+&=A_h \left[ {\left( {\frac{\partial T}{\partial i}-a_1 \frac{\partial
+          T}{\partial k}} \right)^2+\left( {\frac{\partial T}{\partial
+          j}-a_2 \frac{\partial T}{\partial k}} \right)^2}
+  +\varepsilon \left(\frac{\partial T}{\partial k}\right) ^2\right]      \\
+& \geq 0
+\end{array} }
+\end{align*}
+\end{subequations}
+\addtocounter{equation}{-1}
+ the property becomes obvious.
+
+\subsubsection*{In generalized vertical coordinates}
+
+Because the weak-slope operator \autoref{apdx:B4}, \autoref{apdx:B_ldfiso} is decoupled
+in the ($i$,$z$) and ($j$,$z$) planes, it may be transformed into
+generalized $s$-coordinates in the same way as \autoref{sec:B_1} was transformed into
+\autoref{sec:B_2}. The resulting operator then takes the simple form
+
+\begin{equation} \label{apdx:B_ldfiso_s}
+D^T = \left. \nabla \right|_s \cdot
+           \left[ A^{lT} \;\Re \cdot \left. \nabla \right|_s T  \right] \\
+\;\;\text{where} \;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-r _1 } \hfill \\
+ 0 \hfill & 1 \hfill & {-r _2 } \hfill \\
+ {-r _1 } \hfill & {-r _2 } \hfill & {\varepsilon +r _1
+^2+r _2 ^2} \hfill \\
+\end{array} }} \right),
+\end{equation}
+
+where ($r_1$, $r_2$) are the isopycnal slopes in ($\textbf{i}$,
+$\textbf{j}$) directions, relative to $s$-coordinate surfaces:
+\begin{equation*}
+r_1 =\frac{e_3 }{e_1 }\left( {\frac{\partial \rho }{\partial i}} \right)\left( {\frac{\partial \rho }{\partial s}} \right)^{-1}
+\qquad , \qquad
+r_2 =\frac{e_3 }{e_2 }\left( {\frac{\partial \rho }{\partial j}}
+\right)\left( {\frac{\partial \rho }{\partial s}} \right)^{-1}.
+\end{equation*}
+
+To prove  \autoref{apdx:B5}  by direct re-expression of \autoref{apdx:B_ldfiso} is
+straightforward, but laborious. An easier way is first to note (by reversing the
+derivation of \autoref{sec:B_2} from \autoref{sec:B_1} ) that the
+weak-slope operator may be \emph{exactly} reexpressed in 
+non-orthogonal $i,j,\rho$-coordinates as
+
+\begin{equation} \label{apdx:B5}
+D^T = \left. \nabla \right|_\rho \cdot
+           \left[ A^{lT} \;\Re \cdot \left. \nabla \right|_\rho T  \right] \\
+\;\;\text{where} \;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill &0 \hfill \\
+ 0 \hfill & 1 \hfill & 0 \hfill \\
+0 \hfill & 0 \hfill & \varepsilon \hfill \\
+\end{array} }} \right).
+\end{equation}
+Then direct transformation from $i,j,\rho$-coordinates to
+$i,j,s$-coordinates gives \autoref{apdx:B_ldfiso_s} immediately.
+
+Note that the weak-slope approximation is only made in
+transforming from the (rotated,orthogonal) isoneutral axes to the
+non-orthogonal $i,j,\rho$-coordinates. The further transformation
+into $i,j,s$-coordinates is exact, whatever the steepness of
+the  $s$-surfaces, in the same way as the transformation of
+horizontal/vertical Laplacian diffusion in $z$-coordinates,
+\autoref{sec:B_1} onto $s$-coordinates is exact, however steep the $s$-surfaces.
+
+
+% ================================================================
+% Lateral/Vertical Momentum Diffusive Operators
+% ================================================================
+\section{Lateral/Vertical momentum diffusive operators}
+\label{sec:B_3}
+
+The second order momentum diffusion operator (Laplacian) in the $z$-coordinate
+is found by applying \autoref{eq:PE_lap_vector}, the expression for the Laplacian
+of a vector,  to the horizontal velocity vector :
+\begin{align*}
+\Delta {\textbf{U}}_h
+&=\nabla \left( {\nabla \cdot {\textbf{U}}_h } \right)-
+\nabla \times \left( {\nabla \times {\textbf{U}}_h } \right)    \\
+\\
+&=\left( {{\begin{array}{*{20}c}
+ {\frac{1}{e_1 }\frac{\partial \chi }{\partial i}} \hfill \\
+ {\frac{1}{e_2 }\frac{\partial \chi }{\partial j}} \hfill \\
+ {\frac{1}{e_3 }\frac{\partial \chi }{\partial k}} \hfill \\
+\end{array} }} \right)-\left( {{\begin{array}{*{20}c}
+ {\frac{1}{e_2 }\frac{\partial \zeta }{\partial j}-\frac{1}{e_3
+}\frac{\partial }{\partial k}\left( {\frac{1}{e_3 }\frac{\partial
+u}{\partial k}} \right)} \hfill \\
+ {\frac{1}{e_3 }\frac{\partial }{\partial k}\left( {-\frac{1}{e_3
+}\frac{\partial v}{\partial k}} \right)-\frac{1}{e_1 }\frac{\partial \zeta
+}{\partial i}} \hfill \\
+ {\frac{1}{e_1 e_2 }\left[ {\frac{\partial }{\partial i}\left( {\frac{e_2
+}{e_3 }\frac{\partial u}{\partial k}} \right)-\frac{\partial }{\partial
+j}\left( {-\frac{e_1 }{e_3 }\frac{\partial v}{\partial k}} \right)} \right]}
+\hfill \\
+\end{array} }} \right)
+\\
+\\
+&=\left( {{\begin{array}{*{20}c}
+{\frac{1}{e_1 }\frac{\partial \chi }{\partial i}-\frac{1}{e_2 }\frac{\partial \zeta }{\partial j}} \\
+{\frac{1}{e_2 }\frac{\partial \chi }{\partial j}+\frac{1}{e_1 }\frac{\partial \zeta }{\partial i}} \\
+0 \\
+\end{array} }} \right)
++\frac{1}{e_3 }
+\left( {{\begin{array}{*{20}c}
+{\frac{\partial }{\partial k}\left( {\frac{1}{e_3 }\frac{\partial u}{\partial k}} \right)} \\
+{\frac{\partial }{\partial k}\left( {\frac{1}{e_3 }\frac{\partial v}{\partial k}} \right)} \\
+{\frac{\partial \chi }{\partial k}-\frac{1}{e_1 e_2 }\left( {\frac{\partial ^2\left( {e_2 \,u} \right)}{\partial i\partial k}+\frac{\partial ^2\left( {e_1 \,v} \right)}{\partial j\partial k}} \right)} \\
+\end{array} }} \right)
+\end{align*}
+Using \autoref{eq:PE_div}, the definition of the horizontal divergence, the third
+componant of the second vector is obviously zero and thus :
+\begin{equation*}
+\Delta {\textbf{U}}_h = \nabla _h \left( \chi \right) - \nabla _h \times \left( \zeta \right) + \frac {1}{e_3 } \frac {\partial }{\partial k} \left( {\frac {1}{e_3 } \frac{\partial {\textbf{ U}}_h }{\partial k}} \right)
+\end{equation*}
+
+Note that this operator ensures a full separation between the vorticity and horizontal
+divergence fields (see \autoref{apdx:C}). It is only equal to a Laplacian
+applied to each component in Cartesian coordinates, not on the sphere.
+
+The horizontal/vertical second order (Laplacian type) operator used to diffuse
+horizontal momentum in the $z$-coordinate therefore takes the following form :
+\begin{equation} \label{apdx:B_Lap_U}
+ {\textbf{D}}^{\textbf{U}} =
+ 	  \nabla _h \left( {A^{lm}\;\chi } \right)
+	- \nabla _h \times \left( {A^{lm}\;\zeta \;{\textbf{k}}} \right)
+	+ \frac{1}{e_3 }\frac{\partial }{\partial k}\left( {\frac{A^{vm}\;}{e_3 }
+				\frac{\partial {\rm {\bf U}}_h }{\partial k}} \right) \\
+\end{equation}
+that is, in expanded form:
+\begin{align*}
+D^{\textbf{U}}_u
+& = \frac{1}{e_1} \frac{\partial \left( {A^{lm}\chi   } \right)}{\partial i}
+     -\frac{1}{e_2} \frac{\partial \left( {A^{lm}\zeta } \right)}{\partial j}
+     +\frac{1}{e_3} \frac{\partial u}{\partial k}      \\
+D^{\textbf{U}}_v
+& = \frac{1}{e_2 }\frac{\partial \left( {A^{lm}\chi   } \right)}{\partial j}
+     +\frac{1}{e_1 }\frac{\partial \left( {A^{lm}\zeta } \right)}{\partial i}
+     +\frac{1}{e_3} \frac{\partial v}{\partial k}
+\end{align*}
+
+Note Bene: introducing a rotation in \autoref{apdx:B_Lap_U} does not lead to a
+useful expression for the iso/diapycnal Laplacian operator in the $z$-coordinate.
+Similarly, we did not found an expression of practical use for the geopotential
+horizontal/vertical Laplacian operator in the $s$-coordinate. Generally,
+\autoref{apdx:B_Lap_U} is used in both $z$- and $s$-coordinate systems, that is
+a Laplacian diffusion is applied on momentum along the coordinate directions.
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_C.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_C.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_C.tex	(revision 10321)
@@ -0,0 +1,1535 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter Ñ Appendix C : Discrete Invariants of the Equations
+% ================================================================
+\chapter{Discrete Invariants of the Equations}
+\label{apdx:C}
+\minitoc
+
+%%%  Appendix put in gmcomment as it has not been updated for z* and s coordinate
+%I'm writting this appendix. It will be available in a forthcoming release of the documentation
+
+%\gmcomment{
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Introduction / Notations
+% ================================================================
+\section{Introduction / Notations}
+\label{sec:C.0}
+
+Notation used in this appendix in the demonstations :
+
+fluxes at the faces of a $T$-box:
+\begin{equation*}
+U = e_{2u}\,e_{3u}\; u  \qquad  V = e_{1v}\,e_{3v}\; v  \qquad W = e_{1w}\,e_{2w}\; \omega     \\
+\end{equation*}
+
+volume of cells at $u$-, $v$-, and $T$-points:
+\begin{equation*}
+b_u = e_{1u}\,e_{2u}\,e_{3u}  \qquad  b_v = e_{1v}\,e_{2v}\,e_{3v}  \qquad b_t = e_{1t}\,e_{2t}\,e_{3t}     \\
+\end{equation*}
+
+partial derivative notation: $\partial_\bullet = \frac{\partial}{\partial \bullet}$
+
+$dv=e_1\,e_2\,e_3 \,di\,dj\,dk$  is the volume element, with only $e_3$ that depends on time.
+$D$ and $S$ are the ocean domain volume and surface, respectively. 
+No wetting/drying is allow ($i.e.$ $\frac{\partial S}{\partial t} = 0$) 
+Let $k_s$ and $k_b$ be the ocean surface and bottom, resp. 
+($i.e.$ $s(k_s) = \eta$ and $s(k_b)=-H$, where $H$ is the bottom depth).
+\begin{flalign*}
+ z(k) = \eta - \int\limits_{\tilde{k}=k}^{\tilde{k}=k_s}  e_3(\tilde{k}) \;d\tilde{k}
+        = \eta - \int\limits_k^{k_s}  e_3 \;d\tilde{k} 
+\end{flalign*}
+
+Continuity equation with the above notation:
+\begin{equation*}
+\frac{1}{e_{3t}} \partial_t (e_{3t})+ \frac{1}{b_t}  \biggl\{  \delta_i [U] + \delta_j [V] + \delta_k [W] \biggr\} = 0
+\end{equation*}
+
+A quantity, $Q$ is conserved when its domain averaged time change is zero, that is when:
+\begin{equation*}
+\partial_t \left( \int_D{ Q\;dv } \right) =0
+\end{equation*}
+Noting that the coordinate system used ....  blah blah
+\begin{equation*}
+\partial_t \left( \int_D {Q\;dv} \right) =  \int_D { \partial_t \left( e_3 \, Q \right) e_1e_2\;di\,dj\,dk }
+                                                       =  \int_D { \frac{1}{e_3} \partial_t \left( e_3 \, Q \right) dv } =0
+\end{equation*}
+equation of evolution of $Q$ written as the time evolution of the vertical content of $Q$
+like for tracers, or momentum in flux form, the quadratic quantity $\frac{1}{2}Q^2$ is conserved when :
+\begin{flalign*}
+\partial_t \left(   \int_D{ \frac{1}{2} \,Q^2\;dv }   \right)
+=&  \int_D{ \frac{1}{2} \partial_t \left( \frac{1}{e_3}\left( e_3 \, Q \right)^2 \right) e_1e_2\;di\,dj\,dk } \\
+=&  \int_D {         Q   \;\partial_t\left( e_3 \, Q \right) e_1e_2\;di\,dj\,dk }  
+-  \int_D { \frac{1}{2} Q^2 \,\partial_t  (e_3) \;e_1e_2\;di\,dj\,dk } \\
+\end{flalign*}
+that is in a more compact form :
+\begin{flalign} \label{eq:Q2_flux}
+\partial_t \left( \int_D {\frac{1}{2} Q^2\;dv} \right)
+=&                   \int_D { \frac{Q}{e_3}  \partial_t \left( e_3 \, Q \right) dv }  
+  -   \frac{1}{2} \int_D {  \frac{Q^2}{e_3} \partial_t (e_3) \;dv }
+\end{flalign}
+equation of evolution of $Q$ written as the time evolution of $Q$
+like for momentum in vector invariant form, the quadratic quantity $\frac{1}{2}Q^2$ is conserved when :
+\begin{flalign*}
+\partial_t \left( \int_D {\frac{1}{2} Q^2\;dv} \right)
+=&  \int_D { \frac{1}{2} \partial_t \left( e_3 \, Q^2 \right) \;e_1e_2\;di\,dj\,dk } \\
+=& \int_D {         Q      \partial_t Q  \;e_1e_2e_3\;di\,dj\,dk }  
++  \int_D { \frac{1}{2} Q^2 \, \partial_t e_3  \;e_1e_2\;di\,dj\,dk } \\
+\end{flalign*}
+that is in a more compact form :
+\begin{flalign} \label{eq:Q2_vect}
+\partial_t \left( \int_D {\frac{1}{2} Q^2\;dv} \right)
+=& \int_D {         Q   \,\partial_t Q  \;dv }  
++   \frac{1}{2} \int_D { \frac{1}{e_3} Q^2 \partial_t e_3 \;dv }
+\end{flalign}
+
+
+% ================================================================
+% Continuous Total energy Conservation
+% ================================================================
+\section{Continuous conservation}
+\label{sec:C.1}
+
+
+The discretization of pimitive equation in $s$-coordinate ($i.e.$ time and space varying 
+vertical coordinate) must be chosen so that the discrete equation of the model satisfy 
+integral constrains on energy and enstrophy. 
+
+
+Let us first establish those constraint in the continuous world.
+The total energy ($i.e.$ kinetic plus potential energies) is conserved :
+\begin{flalign} \label{eq:Tot_Energy}
+  \partial_t \left( \int_D \left( \frac{1}{2} {\textbf{U}_h}^2 +  \rho \, g \, z \right) \;dv \right)  = & 0
+\end{flalign}
+under the following assumptions: no dissipation, no forcing 
+(wind, buoyancy flux, atmospheric pressure variations), mass 
+conservation, and closed domain. 
+
+This equation can be transformed to obtain several sub-equalities. 
+The transformation for the advection term depends on whether 
+the vector invariant form or the flux form is used for the momentum equation.
+Using \autoref{eq:Q2_vect} and introducing \autoref{apdx:A_dyn_vect} in \autoref{eq:Tot_Energy} 
+for the former form and
+Using \autoref{eq:Q2_flux} and introducing \autoref{apdx:A_dyn_flux} in \autoref{eq:Tot_Energy} 
+for the latter form  leads to:
+
+\begin{subequations} \label{eq:E_tot}
+
+advection term (vector invariant form):
+\begin{equation} \label{eq:E_tot_vect_vor_1}
+\int\limits_D  \zeta \; \left( \textbf{k} \times \textbf{U}_h  \right) \cdot \textbf{U}_h  \;  dv   = 0   \\
+\end{equation}
+%
+\begin{equation} \label{eq:E_tot_vect_adv_1}
+   \int\limits_D  \textbf{U}_h \cdot \nabla_h \left( \frac{{\textbf{U}_h}^2}{2} \right)     dv 
++ \int\limits_D  \textbf{U}_h \cdot \nabla_z \textbf{U}_h  \;dv    
+-  \int\limits_D { \frac{{\textbf{U}_h}^2}{2} \frac{1}{e_3} \partial_t e_3 \;dv }   = 0   \\
+\end{equation}
+
+advection term (flux form):
+\begin{equation} \label{eq:E_tot_flux_metric}
+\int\limits_D  \frac{1} {e_1 e_2 } \left( v \,\partial_i e_2 - u \,\partial_j e_1  \right)\; 
+ \left(  \textbf{k} \times \textbf{U}_h  \right) \cdot \textbf{U}_h  \;  dv   = 0   \\
+\end{equation}
+
+\begin{equation} \label{eq:E_tot_flux_adv}
+   \int\limits_D \textbf{U}_h \cdot     \left(                 {{\begin{array} {*{20}c}
+\nabla \cdot \left( \textbf{U}\,u \right) \hfill \\
+\nabla \cdot \left( \textbf{U}\,v \right) \hfill \\       \end{array}} }           \right)   \;dv 
++   \frac{1}{2} \int\limits_D {  {\textbf{U}_h}^2 \frac{1}{e_3} \partial_t e_3 \;dv } =\;0  \\
+\end{equation}
+
+coriolis term
+\begin{equation} \label{eq:E_tot_cor}
+\int\limits_D  f   \; \left( \textbf{k} \times \textbf{U}_h  \right) \cdot \textbf{U}_h  \;  dv   = 0   \\
+\end{equation}
+
+pressure gradient:
+\begin{equation} \label{eq:E_tot_pg_1}
+   - \int\limits_D  \left. \nabla p \right|_z \cdot \textbf{U}_h \;dv 
+= - \int\limits_D \nabla \cdot \left( \rho \,\textbf {U} \right)\;g\;z\;\;dv
+   + \int\limits_D g\, \rho \; \partial_t z  \;dv   \\
+\end{equation}
+\end{subequations}
+
+where $\nabla_h = \left. \nabla \right|_k$ is the gradient along the $s$-surfaces.
+
+blah blah....
+$\ $\newline    % force a new ligne
+The prognostic ocean dynamics equation can be summarized as follows:
+\begin{equation*}
+\text{NXT} = \dbinom	{\text{VOR} + \text{KEG} + \text {ZAD} }
+						{\text{COR} + \text{ADV}                       }
+			+ \text{HPG} + \text{SPG} + \text{LDF} + \text{ZDF}
+\end{equation*}
+$\ $\newline    % force a new ligne
+
+Vector invariant form:
+\begin{subequations} \label{eq:E_tot_vect}
+\begin{equation} \label{eq:E_tot_vect_vor_2}
+\int\limits_D   \textbf{U}_h \cdot \text{VOR} \;dv   = 0   \\
+\end{equation}
+\begin{equation} \label{eq:E_tot_vect_adv_2}
+   \int\limits_D  \textbf{U}_h \cdot \text{KEG}  \;dv 
++ \int\limits_D  \textbf{U}_h \cdot \text{ZAD}  \;dv    
+-  \int\limits_D { \frac{{\textbf{U}_h}^2}{2} \frac{1}{e_3} \partial_t e_3 \;dv }   = 0   \\
+\end{equation}
+\begin{equation} \label{eq:E_tot_pg_2}
+   - \int\limits_D  \textbf{U}_h \cdot (\text{HPG}+ \text{SPG}) \;dv 
+= - \int\limits_D \nabla \cdot \left( \rho \,\textbf {U} \right)\;g\;z\;\;dv
+   + \int\limits_D g\, \rho \; \partial_t z  \;dv   \\
+\end{equation}
+\end{subequations}
+
+Flux form:
+\begin{subequations} \label{eq:E_tot_flux}
+\begin{equation} \label{eq:E_tot_flux_metric_2}
+\int\limits_D  \textbf{U}_h \cdot \text {COR} \;  dv   = 0   \\
+\end{equation}
+\begin{equation} \label{eq:E_tot_flux_adv_2}
+   \int\limits_D \textbf{U}_h \cdot \text{ADV}   \;dv 
++   \frac{1}{2} \int\limits_D {  {\textbf{U}_h}^2 \frac{1}{e_3} \partial_t e_3  \;dv } =\;0  \\
+\end{equation}
+\begin{equation} \label{eq:E_tot_pg_3}
+   - \int\limits_D  \textbf{U}_h \cdot (\text{HPG}+ \text{SPG}) \;dv 
+= - \int\limits_D \nabla \cdot \left( \rho \,\textbf {U} \right)\;g\;z\;\;dv
+   + \int\limits_D g\, \rho \; \partial_t  z  \;dv   \\
+\end{equation}
+\end{subequations}
+
+
+$\ $\newline    % force a new ligne
+
+
+\autoref{eq:E_tot_pg_3} is the balance between the conversion KE to PE and PE to KE. 
+Indeed the left hand side of \autoref{eq:E_tot_pg_3} can be transformed as follows:
+\begin{flalign*}
+\partial_t  \left( \int\limits_D { \rho \, g \, z  \;dv} \right) 
+&= + \int\limits_D \frac{1}{e_3} \partial_t (e_3\,\rho) \;g\;z\;\;dv
+     +  \int\limits_D g\, \rho \; \partial_t z  \;dv   &&&\\
+&= - \int\limits_D \nabla \cdot \left( \rho \,\textbf {U} \right)\;g\;z\;\;dv
+     + \int\limits_D g\, \rho \; \partial_t z \;dv   &&&\\
+&= + \int\limits_D  \rho \,g \left( \textbf {U}_h \cdot \nabla_h z + \omega \frac{1}{e_3} \partial_k z \right)  \;dv
+     + \int\limits_D g\, \rho \; \partial_t z \;dv   &&&\\
+&= + \int\limits_D  \rho \,g \left( \omega + \partial_t z + \textbf {U}_h \cdot \nabla_h z  \right)  \;dv  &&&\\
+&=+  \int\limits_D g\, \rho \; w \; dv   &&&\\
+\end{flalign*}
+where the last equality is obtained by noting that the brackets is exactly the expression of $w$, 
+the vertical velocity referenced to the fixe $z$-coordinate system (see \autoref{apdx:A_w_s}). 
+ 
+The left hand side of \autoref{eq:E_tot_pg_3} can be transformed as follows:
+\begin{flalign*}
+- \int\limits_D  \left. \nabla p \right|_z & \cdot \textbf{U}_h \;dv  
+= - \int\limits_D  \left( \nabla_h p + \rho \, g \nabla_h z \right) \cdot \textbf{U}_h \;dv   &&&\\
+\allowdisplaybreaks
+&= - \int\limits_D  \nabla_h  p \cdot \textbf{U}_h \;dv   - \int\limits_D  \rho \, g \, \nabla_h z \cdot \textbf{U}_h \;dv   &&&\\
+\allowdisplaybreaks
+&= +\int\limits_D p \,\nabla_h \cdot \textbf{U}_h \;dv   + \int\limits_D  \rho \, g \left( \omega - w + \partial_t z \right) \;dv   &&&\\
+\allowdisplaybreaks
+&= -\int\limits_D p \left( \frac{1}{e_3} \partial_t e_3 + \frac{1}{e_3} \partial_k \omega  \right) \;dv
+    +\int\limits_D  \rho \, g \left( \omega - w + \partial_t z \right) \;dv   &&&\\
+\allowdisplaybreaks
+&= -\int\limits_D \frac{p}{e_3} \partial_t e_3  \;dv    
+     +\int\limits_D \frac{1}{e_3} \partial_k p\; \omega \;dv
+    +\int\limits_D  \rho \, g \left( \omega - w + \partial_t z \right) \;dv   &&&\\
+&= -\int\limits_D \frac{p}{e_3} \partial_t e_3  \;dv    
+     -\int\limits_D \rho \, g \, \omega \;dv
+    +\int\limits_D  \rho \, g \left( \omega - w + \partial_t z \right) \;dv   &&&\\
+&= - \int\limits_D \frac{p}{e_3} \partial_t e_3 \; \;dv    
+     - \int\limits_D  \rho \, g \, w \;dv 
+     + \int\limits_D   \rho \, g \, \partial_t z \;dv   &&&\\
+\allowdisplaybreaks
+\intertext{introducing the hydrostatic balance $\partial_k p=-\rho \,g\,e_3$ in the last term,
+it becomes:}
+&= - \int\limits_D \frac{p}{e_3} \partial_t e_3 \;dv    
+     - \int\limits_D  \rho \, g \, w \;dv 
+     - \int\limits_D  \frac{1}{e_3} \partial_k p\, \partial_t z \;dv   &&&\\
+&= - \int\limits_D \frac{p}{e_3} \partial_t e_3 \;dv    
+     - \int\limits_D  \rho \, g \, w \;dv 
+     + \int\limits_D \,\frac{p}{e_3}\partial_t ( \partial_k z )  dv   &&&\\
+% 
+&= - \int\limits_D  \rho \, g \, w \;dv   &&&\\
+\end{flalign*}
+
+
+%gm comment
+\gmcomment{
+%
+The last equality comes from the following equation,
+\begin{flalign*}
+\int\limits_D p \frac{1}{e_3} \frac{\partial e_3}{\partial t}\; \;dv    
+     = \int\limits_D   \rho \, g \, \frac{\partial z }{\partial t} \;dv \quad,  \\ 
+\end{flalign*}
+that can be demonstrated as follows:
+
+\begin{flalign*}
+\int\limits_D   \rho \, g \, \frac{\partial z }{\partial t} \;dv   
+&= \int\limits_D    \rho \, g \, \frac{\partial \eta}{\partial t} \;dv   
+  -  \int\limits_D    \rho \, g \, \frac{\partial}{\partial t} \left(  \int\limits_k^{k_s}  e_3 \;d\tilde{k} \right) \;dv   &&&\\
+&= \int\limits_D    \rho \, g \, \frac{\partial \eta}{\partial t} \;dv   
+  -  \int\limits_D    \rho \, g    \left(  \int\limits_k^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k} \right) \;dv   &&&\\
+%
+\allowdisplaybreaks
+\intertext{The second term of the right hand side can be transformed by applying the integration by part rule: 
+$\left[ a\,b \right]_{k_b}^{k_s} = \int_{k_b}^{k_s}  a\,\frac{\partial b}{\partial k}       \;dk
+                                               + \int_{k_b}^{k_s}      \frac{\partial a}{\partial k} \,b \;dk $
+to the following function: $a=  \int_k^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k}$ 
+and $b=  \int_k^{k_s}  \rho \, e_3 \;d\tilde{k}$
+(note that $\frac{\partial}{\partial k} \left(  \int_k^{k_s}  a \;d\tilde{k}  \right) = - a$ as $k$ is the lower bound of the integral).
+This leads to:  }
+\end{flalign*}
+\begin{flalign*}
+&\left[ \int\limits_{k}^{k_s}  \frac{\partial e_3}{\partial t} \,dk \cdot \int\limits_{k}^{k_s}  \rho \, e_3 \,dk   \right]_{k_b}^{k_s}
+=-\int\limits_{k_b}^{k_s} \left(  \int\limits_k^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k} \right)  \rho \,e_3 \;dk
+  -\int\limits_{k_b}^{k_s}  \frac{\partial e_3}{\partial t}  \left(  \int\limits_k^{k_s}  \rho \, e_3 \;d\tilde{k} \right)   dk
+&&&\\
+\allowdisplaybreaks
+\intertext{Noting that $\frac{\partial \eta}{\partial t} 
+		= \frac{\partial}{\partial t}  \left( \int_{k_b}^{k_s}   e_3  \;d\tilde{k}  \right)
+		= \int_{k_b}^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k}$
+and 
+		$p(k) = \int_k^{k_s}  \rho \,g \, e_3 \;d\tilde{k} $, 
+but also that $\frac{\partial \eta}{\partial t}$ does not depends on $k$, it comes:
+}
+& - \int\limits_{k_b}^{k_s}  \rho \, \frac{\partial \eta}{\partial t} \, e_3 \;dk
+= - \int\limits_{k_b}^{k_s} \left(  \int\limits_k^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k} \right)   \, \rho \, g   e_3\;dk
+   - \int\limits_{k_b}^{k_s}  \frac{\partial e_3}{\partial t} \frac{p}{g}         \;dk       &&&\\
+\end{flalign*}
+Mutliplying by $g$ and integrating over the $(i,j)$ domain it becomes:
+\begin{flalign*}
+\int\limits_D  \rho \, g \, \left(  \int\limits_k^{k_s}  \frac{\partial e_3}{\partial t} \;d\tilde{k} \right)    \;dv
+=  \int\limits_D  \rho \, g \, \frac{\partial \eta}{\partial t} dv
+  - \int\limits_D  \frac{p}{e_3}\frac{\partial e_3}{\partial t}         \;dv
+\end{flalign*}
+Using this property, we therefore have:
+\begin{flalign*}
+\int\limits_D   \rho \, g \, \frac{\partial z }{\partial t} \;dv   
+&= \int\limits_D    \rho \, g \, \frac{\partial \eta}{\partial t}   \;dv   
+  - \left(  \int\limits_D  \rho \, g \, \frac{\partial \eta}{\partial t} dv
+           - \int\limits_D  \frac{p}{e_3}\frac{\partial e_3}{\partial t}   \;dv  \right)    &&&\\
+%
+&=\int\limits_D \frac{p}{e_3} \frac{\partial (e_3\,\rho)}{\partial t}\; \;dv     
+\end{flalign*}
+% end gm comment
+}
+%
+
+
+% ================================================================
+% Discrete Total energy Conservation : vector invariant form
+% ================================================================
+\section{Discrete total energy conservation: vector invariant form}
+\label{sec:C.2}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Total energy conservation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Total energy conservation}
+\label{subsec:C_KE+PE_vect}
+
+The discrete form of the total energy conservation, \autoref{eq:Tot_Energy}, is given by:
+\begin{flalign*}
+\partial_t  \left(  \sum\limits_{i,j,k} \biggl\{ \frac{u^2}{2} \,b_u + \frac{v^2}{2}\, b_v +  \rho \, g \, z_t \,b_t  \biggr\} \right) &=0  \\
+\end{flalign*}
+which in vector invariant forms, it leads to:
+\begin{equation} \label{eq:KE+PE_vect_discrete}   \begin{split}
+                        \sum\limits_{i,j,k} \biggl\{   u\,                        \partial_t u         \;b_u 
+                                                              + v\,                        \partial_t v          \;b_v  \biggr\}
+  + \frac{1}{2} \sum\limits_{i,j,k} \biggl\{  \frac{u^2}{e_{3u}}\partial_t e_{3u} \;b_u 
+                                                             +  \frac{v^2}{e_{3v}}\partial_t e_{3v} \;b_v   \biggr\}      \\
+= - \sum\limits_{i,j,k} \biggl\{ \frac{1}{e_{3t}}\partial_t (e_{3t} \rho) \, g \, z_t \;b_t  \biggr\} 
+     - \sum\limits_{i,j,k} \biggl\{ \rho \,g\,\partial_t (z_t) \,b_t  \biggr\}                                
+\end{split} \end{equation}
+
+Substituting the discrete expression of the time derivative of the velocity either in vector invariant,
+leads to the discrete equivalent of the four equations \autoref{eq:E_tot_flux}. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       Vorticity term (coriolis + vorticity part of the advection)
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Vorticity term (coriolis + vorticity part of the advection)}
+\label{subsec:C_vor}
+
+Let $q$, located at $f$-points, be either the relative ($q=\zeta / e_{3f}$), or  
+the planetary ($q=f/e_{3f}$), or the total potential vorticity ($q=(\zeta +f) /e_{3f}$). 
+Two discretisation of the vorticity term (ENE and EEN) allows the conservation of 
+the kinetic energy.
+% -------------------------------------------------------------------------------------------------------------
+%       Vorticity Term with ENE scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Vorticity term with ENE scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
+\label{subsec:C_vorENE} 
+
+For the ENE scheme, the two components of the vorticity term are given by :
+\begin{equation*}
+- e_3 \, q \;{\textbf{k}}\times {\textbf {U}}_h    \equiv 
+	\left( {{  \begin{array} {*{20}c}
+		+ \frac{1} {e_{1u}} \; 
+		\overline {\, q \ \overline {\left( e_{1v}\,e_{3v}\,v \right)}^{\,i+1/2}} ^{\,j}        \hfill \\
+		- \frac{1} {e_{2v}} \; 
+		\overline {\, q \ \overline {\left( e_{2u}\,e_{3u}\,u \right)}^{\,j+1/2}} ^{\,i}       \hfill \\
+	\end{array}} }    \right)
+\end{equation*}
+
+This formulation does not conserve the enstrophy but it does conserve the 
+total kinetic energy. Indeed, the kinetic energy tendency associated to the 
+vorticity term and averaged over the ocean domain can be transformed as
+follows:
+\begin{flalign*}
+&\int\limits_D -  \left(  e_3 \, q \;\textbf{k} \times \textbf{U}_h  \right) \cdot \textbf{U}_h  \;  dv &&  \\
+& \qquad \qquad {\begin{array}{*{20}l} 
+&\equiv \sum\limits_{i,j,k} 	\biggl\{ 	
+	  \frac{1} {e_{1u}} \overline { \,q\ \overline{ V }^{\,i+1/2}} ^{\,j} \, u \; b_u 
+	- \frac{1} {e_{2v}}\overline { \, q\ \overline{ U }^{\,j+1/2}} ^{\,i} \, v \; b_v \; \biggr\}    \\ 
+&\equiv  \sum\limits_{i,j,k} 	\biggl\{ 	
+	  \overline { \,q\ \overline{ V }^{\,i+1/2}}^{\,j} \; U 
+	- \overline { \,q\ \overline{ U }^{\,j+1/2}}^{\,i} \; V  \; \biggr\}     \\
+&\equiv \sum\limits_{i,j,k} q \  \biggl\{  \overline{ V }^{\,i+1/2}\; \overline{ U }^{\,j+1/2}        
+		                                        - \overline{ U }^{\,j+1/2}\; \overline{ V }^{\,i+1/2}         \biggr\}  \quad  \equiv 0
+\end{array} } 		
+\end{flalign*}
+In other words, the domain averaged kinetic energy does not change due to the vorticity term.
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Vorticity Term with EEN scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Vorticity term with EEN scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
+\label{subsec:C_vorEEN_vect} 
+
+With the EEN scheme, the vorticity terms are represented as: 
+\begin{equation} \tag{\ref{eq:dynvor_een}}
+\left\{ {    \begin{aligned}
+ +q\,e_3 \, v 	&\equiv +\frac{1}{e_{1u} }   \sum_{\substack{i_p,\,k_p}} 
+                         {^{i+1/2-i_p}_j}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{1v} e_{3v} \ v  \right)^{i+i_p-1/2}_{j+j_p}   \\
+ - q\,e_3 \, u     &\equiv -\frac{1}{e_{2v} }    \sum_{\substack{i_p,\,k_p}} 
+                         {^i_{j+1/2-j_p}}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{2u} e_{3u} \ u  \right)^{i+i_p}_{j+j_p-1/2}   \\
+\end{aligned}   } \right.
+\end{equation} 
+where the indices $i_p$ and $j_p$ take the following value: 
+$i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$,
+and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by: 
+\begin{equation} \tag{\ref{eq:Q_triads}}
+_i^j \mathbb{Q}^{i_p}_{j_p}
+= \frac{1}{12} \ \left(   q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p}  \right)
+\end{equation}
+
+This formulation does conserve the total kinetic energy. Indeed,
+\begin{flalign*}
+&\int\limits_D - \textbf{U}_h \cdot   \left(  \zeta \;\textbf{k} \times \textbf{U}_h  \right)  \;  dv &&  \\
+\equiv \sum\limits_{i,j,k} &	\biggl\{ 
+	    \left[  \sum_{\substack{i_p,\,k_p}} 
+                         {^{i+1/2-i_p}_j}\mathbb{Q}^{i_p}_{j_p} \; V^{i+1/2-i_p}_{j+j_p} \right] U^{i+1/2}_{j}    %   &&\\
+	  - \left[  \sum_{\substack{i_p,\,k_p}} 
+                         {^i_{j+1/2-j_p}}\mathbb{Q}^{i_p}_{j_p} \; U^{i+i_p}_{j+1/2-j_p}  \right] V^{i}_{j+1/2}    \biggr\}     && \\
+\\
+\equiv \sum\limits_{i,j,k} &  \sum_{\substack{i_p,\,k_p}} \biggl\{  \ \  
+                         {^{i+1/2-i_p}_j}\mathbb{Q}^{i_p}_{j_p} \; V^{i+1/2-i_p}_{j+j_p}  \, U^{i+1/2}_{j}     %  &&\\
+                       - {^i_{j+1/2-j_p}}\mathbb{Q}^{i_p}_{j_p} \; U^{i+i_p}_{j+1/2-j_p} \, V^{i}_{j+1/2}     \ \;     \biggr\}     &&  \\
+%
+\allowdisplaybreaks
+\intertext{ Expending the summation on $i_p$ and $k_p$, it becomes:}
+%
+\equiv \sum\limits_{i,j,k} & \biggl\{  \ \  
+                    {^{i+1}_j     }\mathbb{Q}^{-1/2}_{+1/2} \;V^{i+1}_{j+1/2} \; U^{\,i+1/2}_{j}      
+                -  {^i_{j}\quad}\mathbb{Q}^{-1/2}_{+1/2} \; U^{i-1/2}_{j}    \; V^{\,i}_{j+1/2}         &&  \\
+        &       + {^{i+1}_j     }\mathbb{Q}^{-1/2}_{-1/2} \; V^{i+1}_{j-1/2} \; U^{\,i+1/2}_{j}        
+                  - {^i_{j+1}     }\mathbb{Q}^{-1/2}_{-1/2} \; U^{i-1/2}_{j+1} \; V^{\,i}_{j+1/2}        \biggr.     &&  \\
+        &       + {^{i}_j\quad}\mathbb{Q}^{+1/2}_{+1/2} \; V^{i}_{j+1/2}   \; U^{\,i+1/2}_{j}      
+                  - {^i_{j}\quad}\mathbb{Q}^{+1/2}_{+1/2} \; U^{i+1/2}_{j}   \; V^{\,i}_{j+1/2}          \biggr.        &&  \\
+        &       + {^{i}_j\quad}\mathbb{Q}^{+1/2}_{-1/2} \; V^{i}_{j-1/2}     \; U^{\,i+1/2}_{j}       
+                 -  {^i_{j+1}     }\mathbb{Q}^{+1/2}_{-1/2} \; U^{i+1/2}_{j+1}\; V^{\,i}_{j+1/2}  \ \;     \biggr\}     &&  \\
+%
+\allowdisplaybreaks
+\intertext{The summation is done over all $i$ and $j$ indices, it is therefore possible to introduce 
+a shift of $-1$ either in $i$ or $j$ direction in some of the term of the summation (first term of the 
+first and second lines, second term of the second and fourth lines). By doning so, we can regroup 
+all the terms of the summation by triad at a ($i$,$j$) point. In other words, we regroup all the terms 
+in the neighbourhood  that contain a triad at the same ($i$,$j$) indices. It becomes: }
+\allowdisplaybreaks
+%
+\equiv \sum\limits_{i,j,k} & \biggl\{  \ \  
+             {^{i}_j}\mathbb{Q}^{-1/2}_{+1/2}  \left[  V^{i}_{j+1/2}\, U^{\,i-1/2}_{j}    
+                                                                       -  U^{i-1/2}_{j} \, V^{\,i}_{j+1/2}      \right]    &&  \\
+ &       + {^{i}_j}\mathbb{Q}^{-1/2}_{-1/2}  \left[  V^{i}_{j-1/2} \, U^{\,i-1/2}_{j}        
+                                                                     -    U^{i-1/2}_{j} \, V^{\,i}_{j-1/2}      \right]    \biggr.   &&  \\
+ &      + {^{i}_j}\mathbb{Q}^{+1/2}_{+1/2}  \left[  V^{i}_{j+1/2} \, U^{\,i+1/2}_{j}      
+                                                                     -    U^{i+1/2}_{j} \, V^{\,i}_{j+1/2}     \right]  \biggr.  &&  \\
+ &     + {^{i}_j}\mathbb{Q}^{+1/2}_{-1/2}  \left[   V^{i}_{j-1/2} \, U^{\,i+1/2}_{j}                                                                     
+                                                                    -    U^{i+1/2}_{j-1} \, V^{\,i}_{j-1/2}  \right]  \ \;   \biggr\}   \qquad
+\equiv \ 0   &&
+\end{flalign*}
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Gradient of Kinetic Energy / Vertical Advection
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Gradient of kinetic energy / Vertical advection}
+\label{subsec:C_zad} 
+
+The change of Kinetic Energy (KE) due to the vertical advection is exactly 
+balanced by the change of KE due to the horizontal gradient of KE~:
+\begin{equation*}
+    \int_D \textbf{U}_h \cdot \frac{1}{e_3 } \omega \partial_k \textbf{U}_h \;dv
+=  -   \int_D \textbf{U}_h \cdot \nabla_h \left( \frac{1}{2}\;{\textbf{U}_h}^2 \right)\;dv
+   +   \frac{1}{2} \int_D {  \frac{{\textbf{U}_h}^2}{e_3} \partial_t ( e_3) \;dv }  \\
+\end{equation*}
+Indeed, using successively \autoref{eq:DOM_di_adj} ($i.e.$ the skew symmetry 
+property of the $\delta$ operator) and the continuity equation, then 
+\autoref{eq:DOM_di_adj} again, then the commutativity of operators 
+$\overline {\,\cdot \,}$ and $\delta$, and finally \autoref{eq:DOM_mi_adj} 
+($i.e.$ the symmetry property of the $\overline {\,\cdot \,}$ operator) 
+applied in the horizontal and vertical directions, it becomes:
+\begin{flalign*}
+& - \int_D \textbf{U}_h \cdot \text{KEG}\;dv 	
+= - \int_D \textbf{U}_h \cdot \nabla_h \left( \frac{1}{2}\;{\textbf{U}_h}^2 \right)\;dv    &&&\\
+%
+\equiv  & -  \sum\limits_{i,j,k} \frac{1}{2}  \biggl\{	
+	\frac{1} {e_{1u}}  \delta_{i+1/2}   \left[   \overline {u^2}^{\,i} + \overline {v^2}^{\,j}   \right]  u \ b_u 
+     + \frac{1} {e_{2v}}  \delta_{j+1/2}   \left[   \overline {u^2}^{\,i} + \overline {v^2}^{\,j}   \right]  v \ b_v   \biggr\}  	&&&  \\ 
+%
+\equiv & + \sum\limits_{i,j,k} \frac{1}{2}  \left(   \overline {u^2}^{\,i} + \overline {v^2}^{\,j}   \right)\;
+                                                              \biggl\{ \delta_{i} \left[  U   \right] +  \delta_{j} \left[  V  \right]    \biggr\}       &&&  \\ 
+\allowdisplaybreaks
+%
+\equiv   & - \sum\limits_{i,j,k}  \frac{1}{2}
+	\left(       \overline {u^2}^{\,i} + \overline {v^2}^{\,j}   \right)  \;  
+	\biggl\{   \frac{b_t}{e_{3t}} \partial_t (e_{3t})  +  \delta_k \left[  W   \right]    \biggr\}    &&&\\
+\allowdisplaybreaks
+%
+\equiv & +  \sum\limits_{i,j,k} \frac{1}{2} \delta_{k+1/2}   \left[ \overline{ u^2}^{\,i} + \overline{ v^2}^{\,j}   \right] \;  W 
+	       -  \sum\limits_{i,j,k} \frac{1}{2} \left(   \overline {u^2}^{\,i} + \overline {v^2}^{\,j}   \right) \;\partial_t b_t   &&& \\
+\allowdisplaybreaks
+%
+\equiv   & + \sum\limits_{i,j,k} \frac{1} {2} \left(    \overline{\delta_{k+1/2} \left[ u^2 \right]}^{\,i} 
+	                                                                + \overline{\delta_{k+1/2} \left[ v^2 \right]}^{\,j}    \right) \; W     
+	       -  \sum\limits_{i,j,k}  \left(  \frac{u^2}{2}\,\partial_t \overline{b_t}^{\,{i+1/2}}
+	                                              + \frac{v^2}{2}\,\partial_t \overline{b_t}^{\,{j+1/2}}   \right)    &&& \\
+\allowdisplaybreaks
+\intertext{Assuming that $b_u= \overline{b_t}^{\,i+1/2}$ and $b_v= \overline{b_t}^{\,j+1/2}$, or at least that the time
+derivative of these two equations is satisfied, it becomes:}
+%
+\equiv &     \sum\limits_{i,j,k} \frac{1} {2}
+	\biggl\{ \; \overline{W}^{\,i+1/2}\;\delta_{k+1/2} \left[ u^2 \right]    
+	            + \overline{W}^{\,j+1/2}\;\delta_{k+1/2} \left[ v^2 \right]  \;  \biggr\}   
+	       -  \sum\limits_{i,j,k}  \left(  \frac{u^2}{2}\,\partial_t b_u
+	                                             + \frac{v^2}{2}\,\partial_t b_v   \right)    &&& \\
+\allowdisplaybreaks
+%	
+\equiv &     \sum\limits_{i,j,k} 
+	\biggl\{ \; \overline{W}^{\,i+1/2}\; \overline {u}^{\,k+1/2}\; \delta_{k+1/2}[ u ]    
+	            + \overline{W}^{\,j+1/2}\; \overline {v}^{\,k+1/2}\; \delta_{k+1/2}[ v ]  \;  \biggr\} 
+	       -  \sum\limits_{i,j,k}  \left(  \frac{u^2}{2}\,\partial_t b_u
+	                                             + \frac{v^2}{2}\,\partial_t b_v   \right)    &&& \\
+%
+\allowdisplaybreaks
+\equiv  &  \sum\limits_{i,j,k}  
+	\biggl\{ \; \frac{1} {b_u } \; \overline { \overline{W}^{\,i+1/2}\,\delta_{k+1/2}  \left[ u \right] }^{\,k} \;u\;b_u  
+                    + \frac{1} {b_v } \; \overline { \overline{W}^{\,j+1/2} \delta_{k+1/2}  \left[ v \right]  }^{\,k} \;v\;b_v  \; \biggr\}  
+	       -  \sum\limits_{i,j,k}  \left(  \frac{u^2}{2}\,\partial_t b_u
+	                                             + \frac{v^2}{2}\,\partial_t b_v   \right)    &&& \\
+%
+\intertext{The first term provides the discrete expression for the vertical advection of momentum (ZAD), 
+while the second term corresponds exactly to \autoref{eq:KE+PE_vect_discrete}, therefore:}
+\equiv&                   \int\limits_D \textbf{U}_h \cdot \text{ZAD} \;dv  
+           + \frac{1}{2} \int_D { {\textbf{U}_h}^2 \frac{1}{e_3} \partial_t  (e_3)  \;dv }    &&&\\
+\equiv&                   \int\limits_D \textbf{U}_h \cdot w \partial_k \textbf{U}_h \;dv  
+           + \frac{1}{2} \int_D { {\textbf{U}_h}^2 \frac{1}{e_3} \partial_t  (e_3)  \;dv }    &&&\\
+\end{flalign*}
+
+There is two main points here. First, the satisfaction of this property links the choice of 
+the discrete formulation of the vertical advection and of the horizontal gradient 
+of KE. Choosing one imposes the other. For example KE can also be discretized 
+as $1/2\,({\overline u^{\,i}}^2 + {\overline v^{\,j}}^2)$. This leads to the following 
+expression for the vertical advection:
+\begin{equation*}
+\frac{1} {e_3 }\; \omega\; \partial_k \textbf{U}_h
+\equiv \left( {{\begin{array} {*{20}c}
+\frac{1} {e_{1u}\,e_{2u}\,e_{3u}} \;  \overline{\overline {e_{1t}\,e_{2t} \,\omega\;\delta_{k+1/2} 
+\left[ \overline u^{\,i+1/2} \right]}}^{\,i+1/2,k}  \hfill \\
+\frac{1} {e_{1v}\,e_{2v}\,e_{3v}} \;   \overline{\overline {e_{1t}\,e_{2t} \,\omega \;\delta_{k+1/2}
+\left[ \overline v^{\,j+1/2} \right]}}^{\,j+1/2,k} \hfill \\
+\end{array}} } \right)
+\end{equation*}
+a formulation that requires an additional horizontal mean in contrast with 
+the one used in NEMO. Nine velocity points have to be used instead of 3. 
+This is the reason why it has not been chosen.
+
+Second, as soon as the chosen $s$-coordinate depends on time, an extra constraint
+arises on the time derivative of the volume at $u$- and $v$-points:
+\begin{flalign*}
+e_{1u}\,e_{2u}\,\partial_t (e_{3u}) =\overline{ e_{1t}\,e_{2t}\;\partial_t (e_{3t}) }^{\,i+1/2}    \\
+e_{1v}\,e_{2v}\,\partial_t (e_{3v})  =\overline{ e_{1t}\,e_{2t}\;\partial_t (e_{3t}) }^{\,j+1/2}
+\end{flalign*}
+which is (over-)satified by defining the vertical scale factor as follows:
+\begin{flalign} \label{eq:e3u-e3v}
+e_{3u} = \frac{1}{e_{1u}\,e_{2u}}\;\overline{ e_{1t}^{ }\,e_{2t}^{ }\,e_{3t}^{ } }^{\,i+1/2}    \\
+e_{3v} = \frac{1}{e_{1v}\,e_{2v}}\;\overline{ e_{1t}^{ }\,e_{2t}^{ }\,e_{3t}^{ } }^{\,j+1/2} 
+\end{flalign}
+
+Blah blah required on the the step representation of bottom topography.....
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Pressure Gradient Term
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Pressure gradient term}
+\label{subsec:C.2.6}
+
+\gmcomment{
+A pressure gradient has no contribution to the evolution of the vorticity as the 
+curl of a gradient is zero. In the $z$-coordinate, this property is satisfied locally 
+on a C-grid with 2nd order finite differences (property \autoref{eq:DOM_curl_grad}). 
+}
+
+When the equation of state is linear ($i.e.$ when an advection-diffusion equation 
+for density can be derived from those of temperature and salinity) the change of 
+KE due to the work of pressure forces is balanced by the change of potential 
+energy due to buoyancy forces: 
+\begin{equation*}
+- \int_D  \left. \nabla p \right|_z \cdot \textbf{U}_h \;dv 
+= - \int_D \nabla \cdot \left( \rho \,\textbf {U} \right) \,g\,z \;dv
+  + \int_D g\, \rho \; \partial_t (z)  \;dv
+\end{equation*}
+
+This property can be satisfied in a discrete sense for both $z$- and $s$-coordinates. 
+Indeed, defining the depth of a $T$-point, $z_t$, as the sum of the vertical scale 
+factors at $w$-points starting from the surface, the work of pressure forces can be 
+written as:
+\begin{flalign*}
+&- \int_D  \left. \nabla p \right|_z \cdot \textbf{U}_h \;dv   
+\equiv \sum\limits_{i,j,k} \biggl\{ \;  - \frac{1} {e_{1u}}   \Bigl( 
+\delta_{i+1/2} [p_t] - g\;\overline \rho^{\,i+1/2}\;\delta_{i+1/2} [z_t]     \Bigr)  \; u\;b_u  
+	&&  \\ & \qquad \qquad  \qquad \qquad  \qquad \quad \ \,
+					 	      - \frac{1} {e_{2v}}    \Bigl( 
+\delta_{j+1/2} [p_t] - g\;\overline \rho^{\,j+1/2}\delta_{j+1/2} [z_t]      \Bigr)  \; v\;b_v \;  \biggr\}   && \\ 
+%
+\allowdisplaybreaks
+\intertext{Using successively \autoref{eq:DOM_di_adj}, $i.e.$ the skew symmetry property of 
+the $\delta$ operator, \autoref{eq:wzv}, the continuity equation, \autoref{eq:dynhpg_sco}, 
+the hydrostatic equation in the $s$-coordinate, and $\delta_{k+1/2} \left[ z_t \right] \equiv e_{3w} $,
+which comes from the definition of $z_t$, it becomes: }
+\allowdisplaybreaks
+%
+\equiv& +  \sum\limits_{i,j,k}   g  \biggl\{ 
+		\overline\rho^{\,i+1/2}\,U\,\delta_{i+1/2}[z_t]    
+	+  	\overline\rho^{\,j+1/2}\,V\,\delta_{j+1/2}[z_t]     
+	+\Bigl(  \delta_i[U] + \delta_j [V]  \Bigr)\;\frac{p_t}{g} \biggr\}  &&\\
+%
+\equiv& +  \sum\limits_{i,j,k}   g   \biggl\{ 
+		\overline\rho^{\,i+1/2}\,U\,\delta_{i+1/2}[z_t]    
+	+  	\overline\rho^{\,j+1/2}\,V\,\delta_{j+1/2}[z_t]     
+	 -       \left(   \frac{b_t}{e_{3t}} \partial_t (e_{3t})  +  \delta_k \left[ W \right]    \right) \frac{p_t}{g}    \biggr\}   &&&\\ 
+%
+\equiv& +  \sum\limits_{i,j,k}  g   \biggl\{ 
+		\overline\rho^{\,i+1/2}\,U\,\delta_{i+1/2}[z_t]    
+	+  	\overline\rho^{\,j+1/2}\,V\,\delta_{j+1/2}[z_t]     
+	+	\frac{W}{g}\;\delta_{k+1/2} [p_t] 
+	 -        \frac{p_t}{g}\,\partial_t b_t    \biggr\}    &&&\\
+%
+\equiv& +  \sum\limits_{i,j,k}  g   \biggl\{ 
+		\overline\rho^{\,i+1/2}\,U\,\delta_{i+1/2}[z_t]    
+	+  	\overline\rho^{\,j+1/2}\,V\,\delta_{j+1/2}[z_t]     
+	- 	W\;e_{3w} \overline \rho^{\,k+1/2}         
+	 -        \frac{p_t}{g}\,\partial_t b_t    \biggr\}    &&&\\
+%
+\equiv& +  \sum\limits_{i,j,k}    g   \biggl\{ 
+		\overline\rho^{\,i+1/2}\,U\,\delta_{i+1/2}[z_t]    
+	+  	\overline\rho^{\,j+1/2}\,V\,\delta_{j+1/2}[z_t]     
+	+ 	W\; \overline \rho^{\,k+1/2}\;\delta_{k+1/2} [z_t]   
+	 -        \frac{p_t}{g}\,\partial_t b_t    \biggr\}    &&&\\
+%
+\allowdisplaybreaks
+%
+\equiv& - \sum\limits_{i,j,k}   g \; z_t      \biggl\{ 
+		\delta_i 	\left[ U\;	\overline \rho^{\,i+1/2} 	\right]
+	+ 	\delta_j 	\left[ V\;	\overline \rho^{\,j+1/2} 	\right]
+	+ 	\delta_k 	\left[ W\;	\overline \rho^{\,k+1/2} 	\right]       \biggr\}    
+             - \sum\limits_{i,j,k}       \biggl\{ p_t\;\partial_t b_t    \biggr\}   &&&\\	
+%
+\equiv& + \sum\limits_{i,j,k}   g \; z_t    \biggl\{      \partial_t ( e_{3t} \,\rho)    \biggr\}  \; b_t    
+             -  \sum\limits_{i,j,k}                 \biggl\{  p_t\;\partial_t b_t                     \biggr\}              &&&\\	
+%
+\end{flalign*}
+The first term is exactly the first term of the right-hand-side of \autoref{eq:KE+PE_vect_discrete}.
+It remains to demonstrate that the last term, which is obviously a discrete analogue of 
+$\int_D \frac{p}{e_3} \partial_t (e_3)\;dv$ is equal to the last term of \autoref{eq:KE+PE_vect_discrete}.
+In other words, the following property must be satisfied:
+\begin{flalign*}
+           \sum\limits_{i,j,k}  \biggl\{  p_t\;\partial_t b_t                  \biggr\}        
+\equiv  \sum\limits_{i,j,k}  \biggl\{ \rho \,g\,\partial_t (z_t) \,b_t  \biggr\}                                
+\end{flalign*}
+
+Let introduce $p_w$ the pressure at $w$-point such that $\delta_k [p_w] = - \rho \,g\,e_{3t}$. 
+The right-hand-side of the above equation can be transformed as follows:
+
+\begin{flalign*}
+               \sum\limits_{i,j,k}  \biggl\{ \rho \,g\,\partial_t (z_t) \,b_t  \biggr\}  
+&\equiv   - \sum\limits_{i,j,k}  \biggl\{ \delta_k [p_w]\,\partial_t (z_t) \,e_{1t}\,e_{2t}  \biggr\}        &&&\\
+%
+&\equiv  + \sum\limits_{i,j,k}  \biggl\{  p_w\, \delta_{k+1/2} [\partial_t (z_t)] \,e_{1t}\,e_{2t}  \biggr\}  
+  \equiv  + \sum\limits_{i,j,k}  \biggl\{  p_w\, \partial_t (e_{3w}) \,e_{1t}\,e_{2t}  \biggr\}        &&&\\
+&\equiv  + \sum\limits_{i,j,k}  \biggl\{  p_w\, \partial_t (b_w) \biggr\}  
+ %
+% & \equiv     \sum\limits_{i,j,k} \biggl\{  \frac{1}{e_{3t}} \delta_k [p_w]\;\partial_t (z_t) \,b_w   \right)   \biggr\}           &&&\\
+% & \equiv     \sum\limits_{i,j,k} \biggl\{   p_w\;\partial_t \left(    \delta_k [z_t]   \right)  e_{1w}\,e_{2w}   \biggr\}           &&&\\
+% & \equiv     \sum\limits_{i,j,k} \biggl\{   p_w\;\partial_t b_w   \biggr\}          
+\end{flalign*}
+therefore, the balance to be satisfied is:
+\begin{flalign*}
+           \sum\limits_{i,j,k}  \biggl\{  p_t\;\partial_t (b_t) \biggr\}  \equiv  \sum\limits_{i,j,k}  \biggl\{  p_w\, \partial_t (b_w) \biggr\}  
+\end{flalign*}
+which is a purely vertical balance:
+\begin{flalign*}
+           \sum\limits_{k}  \biggl\{  p_t\;\partial_t (e_{3t}) \biggr\}  \equiv  \sum\limits_{k}  \biggl\{  p_w\, \partial_t (e_{3w}) \biggr\}  
+\end{flalign*}
+Defining $p_w = \overline{p_t}^{\,k+1/2}$
+
+%gm comment
+\gmcomment{
+\begin{flalign*}
+ \sum\limits_{i,j,k} \biggl\{   p_t\;\partial_t b_t   \biggr\}                                &&&\\
+ %
+ & \equiv     \sum\limits_{i,j,k} \biggl\{  \frac{1}{e_{3t}} \delta_k [p_w]\;\partial_t (z_t) \,b_w    \biggr\}           &&&\\
+ & \equiv     \sum\limits_{i,j,k} \biggl\{   p_w\;\partial_t \left(    \delta_{k+1/2} [z_t]   \right)  e_{1w}\,e_{2w}   \biggr\}           &&&\\
+ & \equiv     \sum\limits_{i,j,k} \biggl\{   p_w\;\partial_t b_w   \biggr\}          
+\end{flalign*}
+
+
+\begin{flalign*}
+\int\limits_D   \rho \, g \, \frac{\partial z }{\partial t} \;dv
+\equiv&  \sum\limits_{i,j,k}   \biggl\{  \frac{1}{e_{3t}} \frac{\partial e_{3t}}{\partial t} p   \biggr\} \; b_t   &&&\\
+\equiv&  \sum\limits_{i,j,k}   \biggl\{      \biggr\} \; b_t   &&&\\
+\end{flalign*}
+
+%
+\begin{flalign*}
+\equiv& - \int_D \nabla \cdot \left( \rho \,\textbf {U} \right)\;g\;z\;\;dv
+   + \int\limits_D g\, \rho \; \frac{\partial z}{\partial t}  \;dv     &&& \\
+\end{flalign*}
+%
+}
+%end gm comment
+
+
+Note that this property strongly constrains the discrete expression of both 
+the depth of $T-$points and of the term added to the pressure gradient in the
+$s$-coordinate. Nevertheless, it is almost never satisfied since a linear equation 
+of state is rarely used.
+
+
+
+
+
+
+
+% ================================================================
+% Discrete Total energy Conservation : flux form
+% ================================================================
+\section{Discrete total energy conservation: flux form}
+\label{sec:C.3}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Total energy conservation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Total energy conservation}
+\label{subsec:C_KE+PE_flux}
+
+The discrete form of the total energy conservation, \autoref{eq:Tot_Energy}, is given by:
+\begin{flalign*}
+\partial_t \left(  \sum\limits_{i,j,k} \biggl\{ \frac{u^2}{2} \,b_u + \frac{v^2}{2}\, b_v +  \rho \, g \, z_t \,b_t  \biggr\} \right) &=0  \\
+\end{flalign*}
+which in flux form, it leads to:
+\begin{flalign*}
+                        \sum\limits_{i,j,k} \biggl\{  \frac{u    }{e_{3u}}\,\frac{\partial (e_{3u}u)}{\partial t} \,b_u 
+                                                             +  \frac{v    }{e_{3v}}\,\frac{\partial (e_{3v}v)}{\partial t} \,b_v  \biggr\}
+&  -  \frac{1}{2} \sum\limits_{i,j,k} \biggl\{  \frac{u^2}{e_{3u}}\frac{\partial    e_{3u}    }{\partial t} \,b_u 
+                                                             +  \frac{v^2}{e_{3v}}\frac{\partial    e_{3v}    }{\partial t} \,b_v   \biggr\}      \\
+&= - \sum\limits_{i,j,k} \biggl\{ \frac{1}{e_3t}\frac{\partial e_{3t} \rho}{\partial t} \, g \, z_t \,b_t  \biggr\} 
+     - \sum\limits_{i,j,k} \biggl\{ \rho \,g\,\frac{\partial z_t}{\partial t} \,b_t  \biggr\}                                     \\
+\end{flalign*}
+
+Substituting the discrete expression of the time derivative of the velocity either in vector invariant or in flux form,
+leads to the discrete equivalent of the 
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Coriolis and advection terms: flux form
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Coriolis and advection terms: flux form}
+\label{subsec:C.3.2}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Coriolis plus ``metric'' Term
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Coriolis plus ``metric'' term}
+\label{subsec:C.3.3} 
+
+In flux from the vorticity term reduces to a Coriolis term in which the Coriolis 
+parameter has been modified to account for the ``metric'' term. This altered 
+Coriolis parameter is discretised at an f-point. It is given by: 
+\begin{equation*}
+f+\frac{1} {e_1 e_2 } \left( v \frac{\partial e_2 } {\partial i} - u \frac{\partial e_1 } {\partial j}\right)\;
+\equiv \;
+f+\frac{1} {e_{1f}\,e_{2f}} \left( \overline v^{\,i+1/2} \delta_{i+1/2} \left[ e_{2u} \right] 
+                                               -\overline u^{\,j+1/2} \delta_{j+1/2} \left[ e_{1u}  \right] \right)
+\end{equation*}
+
+Either the ENE or EEN scheme is then applied to obtain the vorticity term in flux form. 
+It therefore conserves the total KE. The derivation is the same as for the 
+vorticity term in the vector invariant form (\autoref{subsec:C_vor}).
+
+% -------------------------------------------------------------------------------------------------------------
+%       Flux form advection
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Flux form advection}
+\label{subsec:C.3.4} 
+
+The flux form operator of the momentum advection is evaluated using a 
+centered second order finite difference scheme. Because of the flux form, 
+the discrete operator does not contribute to the global budget of linear 
+momentum. Because of the centered second order scheme, it conserves 
+the horizontal kinetic energy, that is :
+
+\begin{equation} \label{eq:C_ADV_KE_flux}
+ -  \int_D \textbf{U}_h \cdot     \left(                 {{\begin{array} {*{20}c}
+\nabla \cdot \left( \textbf{U}\,u \right) \hfill \\
+\nabla \cdot \left( \textbf{U}\,v \right) \hfill \\       \end{array}} }           \right)   \;dv 
+-   \frac{1}{2} \int_D {  {\textbf{U}_h}^2 \frac{1}{e_3} \frac{\partial  e_3 }{\partial t} \;dv } =\;0
+\end{equation}
+
+Let us first consider the first term of the scalar product ($i.e.$ just the the terms 
+associated with the i-component of the advection) :
+\begin{flalign*}
+&  - \int_D u \cdot \nabla \cdot \left(   \textbf{U}\,u   \right) \; dv   \\
+%
+\equiv& - \sum\limits_{i,j,k} \biggl\{    \frac{1} {b_u}    \biggl(   
+      \delta_{i+1/2}  \left[   \overline {U}^{\,i}      \;\overline u^{\,i}          \right]   
+   + \delta_j           \left[   \overline {V}^{\,i+1/2}\;\overline u^{\,j+1/2}   \right]   
+   + \delta_k          \left[   \overline {W}^{\,i+1/2}\;\overline u^{\,k+1/2} \right]  \biggr)   \;   \biggr\} \, b_u \;u &&&  \\ 
+%
+\equiv& - \sum\limits_{i,j,k} 
+	\biggl\{ 
+      \delta_{i+1/2} \left[   \overline {U}^{\,i}\;  \overline u^{\,i}  \right]
+   + \delta_j          \left[   \overline {V}^{\,i+1/2}\;\overline u^{\,j+1/2}   \right]
+   + \delta_k         \left[   \overline {W}^{\,i+12}\;\overline u^{\,k+1/2}  \right]
+   	\; \biggr\} \; u     \\
+%
+\equiv& + \sum\limits_{i,j,k}
+	\biggl\{ 
+	   \overline {U}^{\,i}\;	\overline u^{\,i} 	\delta_i \left[ u \right] 
+        + \overline {V}^{\,i+1/2}\;	\overline u^{\,j+1/2} 	\delta_{j+1/2} \left[ u \right] 
+        + \overline {W}^{\,i+1/2}\;	\overline u^{\,k+1/2}	\delta_{k+1/2} 	\left[ u \right]     \biggr\}     && \\
+%
+\equiv& + \frac{1}{2} \sum\limits_{i,j,k}    \biggl\{ 
+	    \overline{U}^{\,i} 		\delta_i 		\left[ u^2 \right] 
+	 + \overline{V}^{\,i+1/2} 	\delta_{j+/2} 	\left[ u^2 \right]
+	 + \overline{W}^{\,i+1/2} 	\delta_{k+1/2} 	\left[ u^2 \right]      \biggr\} && \\
+%
+\equiv& -  \sum\limits_{i,j,k}    \frac{1}{2}   \bigg\{ 
+	    U  \; \delta_{i+1/2}    \left[ \overline {u^2}^{\,i} \right]
+         + V  \; \delta_{j+1/2}    \left[ \overline {u^2}^{\,i} \right]
+	 + W \; \delta_{k+1/2}   \left[ \overline {u^2}^{\,i} \right]     \biggr\}    &&& \\
+%
+\equiv& - \sum\limits_{i,j,k}  \frac{1}{2}  \overline {u^2}^{\,i}     \biggl\{ 
+	   \delta_{i+1/2} 	\left[ U  \right]
+	+ \delta_{j+1/2} 	\left[ V  \right]
+	+ \delta_{k+1/2} 	\left[ W \right]     \biggr\}    &&& \\
+%
+\equiv& + \sum\limits_{i,j,k}  \frac{1}{2}  \overline {u^2}^{\,i} 
+	\biggl\{     \left(   \frac{1}{e_{3t}} \frac{\partial e_{3t}}{\partial t}   \right) \; b_t     \biggr\}    &&& \\
+\end{flalign*}
+Applying similar manipulation applied to the second term of the scalar product 
+leads to :
+\begin{equation*}
+ -  \int_D \textbf{U}_h \cdot     \left(                 {{\begin{array} {*{20}c}
+\nabla \cdot \left( \textbf{U}\,u \right) \hfill \\
+\nabla \cdot \left( \textbf{U}\,v \right) \hfill \\       \end{array}} }           \right)   \;dv     
+\equiv + \sum\limits_{i,j,k}  \frac{1}{2}  \left( \overline {u^2}^{\,i} + \overline {v^2}^{\,j} \right)
+	\biggl\{     \left(   \frac{1}{e_{3t}} \frac{\partial e_{3t}}{\partial t}   \right) \; b_t     \biggr\}    
+\end{equation*}
+which is the discrete form of 
+$ \frac{1}{2} \int_D u \cdot \nabla \cdot \left(   \textbf{U}\,u   \right) \; dv $. 
+\autoref{eq:C_ADV_KE_flux} is thus satisfied.
+
+
+When the UBS scheme is used to evaluate the flux form momentum advection, 
+the discrete operator does not contribute to the global budget of linear momentum 
+(flux form). The horizontal kinetic energy is not conserved, but forced to decay 
+($i.e.$ the scheme is diffusive). 
+
+
+
+
+
+
+
+
+
+
+% ================================================================
+% Discrete Enstrophy Conservation
+% ================================================================
+\section{Discrete enstrophy conservation}
+\label{sec:C.4}
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Vorticity Term with ENS scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Vorticity term with ENS scheme  (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
+\label{subsec:C_vorENS} 
+
+In the ENS scheme, the vorticity term is descretized as follows:
+\begin{equation} \tag{\ref{eq:dynvor_ens}}
+\left\{   \begin{aligned}
++\frac{1}{e_{1u}} & \overline{q}^{\,i}  & {\overline{ \overline{\left( e_{1v}\,e_{3v}\;  v \right) } } }^{\,i, j+1/2}    \\
+- \frac{1}{e_{2v}} & \overline{q}^{\,j}  & {\overline{ \overline{\left( e_{2u}\,e_{3u}\; u \right) } } }^{\,i+1/2, j}  
+\end{aligned}  \right.
+\end{equation} 
+
+The scheme does not allow but the conservation of the total kinetic energy but the conservation 
+of $q^2$, the potential enstrophy for a horizontally non-divergent flow ($i.e.$ when $\chi$=$0$). 
+Indeed, using the symmetry or skew symmetry properties of the operators ( \autoref{eq:DOM_mi_adj} 
+and \autoref{eq:DOM_di_adj}), it can be shown that:
+\begin{equation} \label{eq:C_1.1}
+\int_D {q\,\;{\textbf{k}}\cdot \frac{1} {e_3} \nabla \times \left( {e_3 \, q \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} \equiv 0
+\end{equation}
+where $dv=e_1\,e_2\,e_3 \; di\,dj\,dk$ is the volume element. Indeed, using 
+\autoref{eq:dynvor_ens}, the discrete form of the right hand side of \autoref{eq:C_1.1} 
+can be transformed as follow:
+\begin{flalign*} 
+&\int_D q \,\; \textbf{k} \cdot \frac{1} {e_3 } \nabla \times 
+	\left(  e_3 \, q \; \textbf{k} \times  \textbf{U}_h   \right)\;   dv       \\
+%
+& \qquad {\begin{array}{*{20}l} 
+&\equiv \sum\limits_{i,j,k} 
+q \ \left\{  \delta_{i+1/2}  \left[ - \,\overline {q}^{\,i}\;  \overline{\overline  U }^{\,i,j+1/ 2} \right]  
+             - \delta_{j+1/2} \left[	 \overline {q}^{\,j}\;  \overline{\overline  V }^{\,i+1/2, j} \right]     \right\}    \\ 
+%
+&\equiv \sum\limits_{i,j,k} 
+	\left\{   \delta_i [q] \; \overline{q}^{\,i} \; \overline{  \overline U  }^{\,i,j+1/2} 
+		+ \delta_j [q] \; \overline{q}^{\,j} \; \overline{\overline V }^{\,i+1/2,j}        \right\}       &&  \\ 
+%
+&\equiv \,\frac{1} {2} \sum\limits_{i,j,k}  
+	\left\{         \delta_i  \left[ q^2 \right] \; \overline{\overline U }^{\,i,j+1/2} 
+		      + \delta_j  \left[ q^2 \right] \; \overline{\overline V }^{\,i+1/2,j}      \right\}    &&  \\ 
+%
+&\equiv - \frac{1} {2} \sum\limits_{i,j,k} 	q^2 \;
+	\left\{    \delta_{i+1/2}   \left[   \overline{\overline{ U }}^{\,i,j+1/2}    \right]  
+	         + \delta_{j+1/2}  \left[   \overline{\overline{ V }}^{\,i+1/2,j}     \right]    \right\}    && \\ 
+\end{array} } 		
+%
+\allowdisplaybreaks
+\intertext{ Since $\overline {\;\cdot \;} $ and $\delta $ operators commute: $\delta_{i+1/2} 
+\left[ {\overline a^{\,i}} \right] = \overline {\delta_i \left[ a \right]}^{\,i+1/2}$, 
+and introducing the horizontal divergence $\chi $, it becomes: }
+\allowdisplaybreaks
+%
+& \qquad {\begin{array}{*{20}l} 
+&\equiv \sum\limits_{i,j,k} - \frac{1} {2} q^2 \; \overline{\overline{ e_{1t}\,e_{2t}\,e_{3t}^{}\, \chi}}^{\,i+1/2,j+1/2} 
+\quad \equiv 0 &&
+\end{array} } 		
+\end{flalign*}
+The later equality is obtain only when the flow is horizontally non-divergent, $i.e.$ $\chi$=$0$. 
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Vorticity Term with EEN scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Vorticity Term with EEN scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.})}
+\label{subsec:C_vorEEN} 
+
+With the EEN scheme, the vorticity terms are represented as: 
+\begin{equation} \tag{\ref{eq:dynvor_een}}
+\left\{ {    \begin{aligned}
+ +q\,e_3 \, v 	&\equiv +\frac{1}{e_{1u} }   \sum_{\substack{i_p,\,k_p}} 
+                         {^{i+1/2-i_p}_j}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{1v} e_{3v} \ v  \right)^{i+i_p-1/2}_{j+j_p}   \\
+ - q\,e_3 \, u     &\equiv -\frac{1}{e_{2v} }    \sum_{\substack{i_p,\,k_p}} 
+                         {^i_{j+1/2-j_p}}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{2u} e_{3u} \ u  \right)^{i+i_p}_{j+j_p-1/2}   \\
+\end{aligned}   } \right.
+\end{equation} 
+where the indices $i_p$ and $k_p$ take the following value: 
+$i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$,
+and the vorticity triads, ${^i_j}\mathbb{Q}^{i_p}_{j_p}$, defined at $T$-point, are given by: 
+\begin{equation} \tag{\ref{eq:Q_triads}}
+_i^j \mathbb{Q}^{i_p}_{j_p}
+= \frac{1}{12} \ \left(   q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p}  \right)
+\end{equation}
+
+
+This formulation does conserve the potential enstrophy for a horizontally non-divergent flow ($i.e.$ $\chi=0$). 
+
+Let consider one of the vorticity triad, for example ${^{i}_j}\mathbb{Q}^{+1/2}_{+1/2} $, 
+similar manipulation can be done for the 3 others. The discrete form of the right hand 
+side of \autoref{eq:C_1.1} applied to this triad only can be transformed as follow:
+
+\begin{flalign*} 
+&\int_D {q\,\;{\textbf{k}}\cdot \frac{1} {e_3} \nabla \times \left( {e_3 \, q \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} \\
+%
+\equiv& \sum\limits_{i,j,k} 
+ {q} \    \biggl\{ \;\;
+	\delta_{i+1/2} \left[   -\, {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}  \; U^{i+1/2}_{j}}    \right]  
+      - \delta_{j+1/2} \left[       {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}  \; V^{i}_{j+1/2}}    \right] 
+	\;\;\biggr\}        &&  \\ 
+%
+\equiv& \sum\limits_{i,j,k} 
+	\biggl\{   \delta_i [q] \  {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}  \; U^{i+1/2}_{j}}
+		   + \delta_j [q] \  {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}  \; V^{i}_{j+1/2}}   \biggr\}
+		&& \\ 
+%
+... & &&\\
+&Demonstation \ to \ be \ done... &&\\
+... & &&\\
+%
+\equiv& \frac{1} {2} \sum\limits_{i,j,k}  
+	\biggl\{	\delta_i    \Bigl[    \left(  {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}} \right)^2   \Bigr]\;
+			\overline{\overline {U}}^{\,i,j+1/2} 
+		      + \delta_j 	\Bigl[    \left( {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}} \right)^2     \Bigr]\; 
+			\overline{\overline {V}}^{\,i+1/2,j} 
+	\biggr\} 
+	&&  \\ 
+%
+\equiv& - \frac{1} {2} \sum\limits_{i,j,k} 	\left( {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}} \right)^2\;
+	\biggl\{    \delta_{i+1/2} 
+	      \left[   \overline{\overline {U}}^{\,i,j+1/2}    \right]  
+	            + \delta_{j+1/2}
+		\left[   \overline{\overline {V}}^{\,i+1/2,j}     \right]  
+	\biggr\}    && \\ 
+%
+\equiv& \sum\limits_{i,j,k} - \frac{1} {2} \left( {{^i_j}\mathbb{Q}^{+1/2}_{+1/2}} \right)^2
+                                                            \; \overline{\overline{ b_t^{}\, \chi}}^{\,i+1/2,\,j+1/2}  &&\\
+%
+\ \ \equiv& \ 0     &&\\
+\end{flalign*}
+
+
+
+
+
+% ================================================================
+% Conservation Properties on Tracers
+% ================================================================
+\section{Conservation properties on tracers}
+\label{sec:C.5}
+
+
+All the numerical schemes used in NEMO are written such that the tracer content 
+is conserved by the internal dynamics and physics (equations in flux form). 
+For advection, only the CEN2 scheme ($i.e.$ $2^{nd}$ order finite different scheme) 
+conserves the global variance of tracer. Nevertheless the other schemes ensure 
+that the global variance decreases ($i.e.$ they are at least slightly diffusive). 
+For diffusion, all the schemes ensure the decrease of the total tracer variance, 
+except the iso-neutral operator. There is generally no strict conservation of mass, 
+as the equation of state is non linear with respect to $T$ and $S$. In practice, 
+the mass is conserved to a very high accuracy. 
+% -------------------------------------------------------------------------------------------------------------
+%       Advection Term
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Advection term}
+\label{subsec:C.5.1}
+
+conservation of a tracer, $T$:
+\begin{equation*}
+\frac{\partial }{\partial t} \left(   \int_D {T\;dv}   \right) 
+=  \int_D { \frac{1}{e_3}\frac{\partial \left( e_3 \, T \right)}{\partial t} \;dv }=0
+\end{equation*}
+
+conservation of its variance:
+\begin{flalign*} 
+\frac{\partial }{\partial t} \left( \int_D {\frac{1}{2} T^2\;dv} \right)
+=&  \int_D { \frac{1}{e_3} Q      \frac{\partial \left( e_3 \, T \right) }{\partial t} \;dv }  
+-   \frac{1}{2} \int_D {  T^2 \frac{1}{e_3} \frac{\partial  e_3 }{\partial t} \;dv }
+\end{flalign*}
+
+
+Whatever the advection scheme considered it conserves of the tracer content as all 
+the scheme are written in flux form. Indeed,  let $T$ be the tracer and $\tau_u$, $\tau_v$, 
+and $\tau_w$ its interpolated values at velocity point (whatever the interpolation is), 
+the conservation of the tracer content due to the advection tendency is obtained as follows: 
+\begin{flalign*}
+&\int_D { \frac{1}{e_3}\frac{\partial \left( e_3 \, T \right)}{\partial t} \;dv } = - \int_D \nabla \cdot \left( T \textbf{U} \right)\;dv    &&&\\
+&\equiv - \sum\limits_{i,j,k}    \biggl\{
+	 \frac{1} {b_t}  \left(  \delta_i    \left[   U \;\tau_u   \right]
+	                             + \delta_j    \left[   V  \;\tau_v   \right] \right) 
+	+ \frac{1} {e_{3t}} \delta_k \left[ w\;\tau_w \right]    \biggl\}  b_t   &&&\\
+%
+&\equiv - \sum\limits_{i,j,k}     \left\{
+	    \delta_i  \left[   U \;\tau_u   \right]
+         + \delta_j  \left[   V  \;\tau_v   \right]
+ 	 + \delta_k \left[ W \;\tau_w \right] \right\}   && \\
+&\equiv 0 &&&
+\end{flalign*}
+
+The conservation of the variance of tracer due to the advection tendency 
+can be achieved only with the CEN2 scheme, $i.e.$ when 
+$\tau_u= \overline T^{\,i+1/2}$, $\tau_v= \overline T^{\,j+1/2}$, and $\tau_w= \overline T^{\,k+1/2}$. 
+It can be demonstarted as follows:
+\begin{flalign*}
+&\int_D { \frac{1}{e_3} Q      \frac{\partial \left( e_3 \, T \right) }{\partial t} \;dv }
+= - \int\limits_D \tau\;\nabla \cdot \left( T\; \textbf{U} \right)\;dv &&&\\
+\equiv& - \sum\limits_{i,j,k} T\;
+	\left\{
+	   \delta_i  \left[ U  \overline T^{\,i+1/2}  \right]
+	+ \delta_j  \left[ V  \overline T^{\,j+1/2}  \right]
+	+ \delta_k \left[ W \overline T^{\,k+1/2} \right]          \right\} && \\
+\equiv& + \sum\limits_{i,j,k} 
+	\left\{     U  \overline T^{\,i+1/2} \,\delta_{i+1/2}  \left[ T \right] 
+                 +  V  \overline T^{\,j+1/2} \;\delta_{j+1/2}  \left[ T \right]
+                 +  W \overline T^{\,k+1/2}\;\delta_{k+1/2} \left[ T \right]     \right\}      &&\\
+\equiv&  + \frac{1} {2}  \sum\limits_{i,j,k}
+	\Bigl\{   U  \;\delta_{i+1/2} \left[ T^2 \right]
+                 + V  \;\delta_{j+1/2}  \left[ T^2 \right]
+                 + W \;\delta_{k+1/2} \left[ T^2 \right]   \Bigr\}     && \\ 
+\equiv& - \frac{1} {2}  \sum\limits_{i,j,k} T^2
+	\Bigl\{    \delta_i  \left[ U  \right]
+                  + \delta_j  \left[ V  \right]
+                  + \delta_k \left[ W \right]     \Bigr\}      &&&  \\
+\equiv& + \frac{1} {2}  \sum\limits_{i,j,k} T^2
+	\Bigl\{   \frac{1}{e_{3t}} \frac{\partial e_{3t}\,T }{\partial t}     \Bigr\}      &&& \\
+\end{flalign*}
+which is the discrete form of $ \frac{1}{2} \int_D {  T^2 \frac{1}{e_3} \frac{\partial  e_3 }{\partial t} \;dv }$.
+
+% ================================================================
+% Conservation Properties on Lateral Momentum Physics
+% ================================================================
+\section{Conservation properties on lateral momentum physics}
+\label{sec:dynldf_properties}
+
+
+The discrete formulation of the horizontal diffusion of momentum ensures the 
+conservation of potential vorticity and the horizontal divergence, and the 
+dissipation of the square of these quantities ($i.e.$ enstrophy and the 
+variance of the horizontal divergence) as well as the dissipation of the 
+horizontal kinetic energy. In particular, when the eddy coefficients are 
+horizontally uniform, it ensures a complete separation of vorticity and 
+horizontal divergence fields, so that diffusion (dissipation) of vorticity 
+(enstrophy) does not generate horizontal divergence (variance of the 
+horizontal divergence) and \textit{vice versa}. 
+
+These properties of the horizontal diffusion operator are a direct consequence 
+of properties \autoref{eq:DOM_curl_grad} and \autoref{eq:DOM_div_curl}. 
+When the vertical curl of the horizontal diffusion of momentum (discrete sense) 
+is taken, the term associated with the horizontal gradient of the divergence is 
+locally zero. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation of Potential Vorticity
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Conservation of potential vorticity}
+\label{subsec:C.6.1}
+
+The lateral momentum diffusion term conserves the potential vorticity :
+\begin{flalign*}
+&\int \limits_D \frac{1} {e_3 } \textbf{k} \cdot \nabla \times 
+	\Bigl[    \nabla_h  \left( A^{\,lm}\;\chi  \right)
+	        - \nabla_h \times \left( A^{\,lm}\;\zeta \; \textbf{k} \right)    \Bigr]\;dv   \\ 
+%\end{flalign*}
+%%%%%%%%%%  recheck here....  (gm)
+%\begin{flalign*}
+=& \int \limits_D  -\frac{1} {e_3 } \textbf{k} \cdot \nabla \times 
+	\Bigl[ \nabla_h \times \left( A^{\,lm}\;\zeta \; \textbf{k} \right)  \Bigr]\;dv  \\ 
+%\end{flalign*}
+%\begin{flalign*}
+\equiv& \sum\limits_{i,j}
+	\left\{
+	  \delta_{i+1/2} \left[  \frac {e_{2v}} {e_{1v}\,e_{3v}}  \delta_i \left[ A_f^{\,lm} e_{3f} \zeta  \right]  \right]
+ 	+ \delta_{j+1/2} \left[  \frac {e_{1u}} {e_{2u}\,e_{3u}}  \delta_j \left[ A_f^{\,lm} e_{3f} \zeta  \right]  \right]
+	\right\} 	 \\ 
+%
+\intertext{Using \autoref{eq:DOM_di_adj}, it follows:}
+%
+\equiv& \sum\limits_{i,j,k} 
+	-\,\left\{
+	   \frac{e_{2v}} {e_{1v}\,e_{3v}}  \delta_i	\left[ A_f^{\,lm} e_{3f} \zeta  \right]\;\delta_i \left[ 1\right]
+	 + \frac{e_{1u}} {e_{2u}\,e_{3u}}  \delta_j 	\left[ A_f^{\,lm} e_{3f} \zeta  \right]\;\delta_j \left[ 1\right]
+	\right\} \quad \equiv 0 
+	 \\ 
+\end{flalign*}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Dissipation of Horizontal Kinetic Energy
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Dissipation of horizontal kinetic energy}
+\label{subsec:C.6.2}
+
+The lateral momentum diffusion term dissipates the horizontal kinetic energy:
+%\begin{flalign*}
+\begin{equation*}
+\begin{split}
+\int_D \textbf{U}_h \cdot 
+	\left[ \nabla_h 		\right.   &     \left.       \left( A^{\,lm}\;\chi \right)      
+	- \nabla_h \times  \left( A^{\,lm}\;\zeta \;\textbf{k} \right)     \right] \; dv    \\
+\\  %%%
+\equiv& \sum\limits_{i,j,k} 
+	\left\{
+	  \frac{1} {e_{1u}}               \delta_{i+1/2} \left[  A_T^{\,lm}          \chi     \right]
+	- \frac{1} {e_{2u}\,e_{3u}}  \delta_j           \left[ A_f^{\,lm} e_{3f} \zeta   \right]
+	\right\} \; e_{1u}\,e_{2u}\,e_{3u} \;u     \\
+&\;\; + 	\left\{
+	   \frac{1} {e_{2u}}             \delta_{j+1/2}	\left[ A_T^{\,lm}          \chi    \right] 
+	+ \frac{1} {e_{1v}\,e_{3v}} \delta_i            \left[ A_f^{\,lm} e_{3f} \zeta  \right] 
+	\right\} \; e_{1v}\,e_{2u}\,e_{3v} \;v     \qquad \\ 
+\\  %%%
+\equiv& \sum\limits_{i,j,k} 
+ 	\Bigl\{
+	  e_{2u}\,e_{3u} \;u\;  \delta_{i+1/2} \left[ A_T^{\,lm}           \chi    \right]
+	- e_{1u}             \;u\;  \delta_j           \left[ A_f^{\,lm} e_{3f} \zeta  \right]
+	 \Bigl\} 
+	 \\ 
+&\;\; + \Bigl\{
+	   e_{1v}\,e_{3v} \;v\;  \delta_{j+1/2}  \left[ A_T^{\,lm}           \chi    \right]
+	+ e_{2v}             \;v\;  \delta_i            \left[ A_f^{\,lm} e_{3f} \zeta  \right]
+	\Bigl\}      \\ 
+\\  %%%
+\equiv& \sum\limits_{i,j,k} 
+	- \Bigl(
+	  \delta_i   \left[  e_{2u}\,e_{3u} \;u  \right]
+	+ \delta_j  \left[  e_{1v}\,e_{3v}  \;v  \right] 
+	     \Bigr) \;  A_T^{\,lm} \chi   \\ 
+&\;\; - \Bigl(
+	  \delta_{i+1/2}  \left[  e_{2v}  \;v  \right]
+	- \delta_{j+1/2}  \left[  e_{1u} \;u  \right] 
+	     \Bigr)\;  A_f^{\,lm} e_{3f} \zeta      \\ 
+\\  %%%
+\equiv& \sum\limits_{i,j,k} 
+	- A_T^{\,lm}  \,\chi^2   \;e_{1t}\,e_{2t}\,e_{3t}
+	- A_f ^{\,lm}  \,\zeta^2 \;e_{1f }\,e_{2f }\,e_{3f}  
+\quad \leq 0       \\
+\end{split}
+\end{equation*}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Dissipation of Enstrophy
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Dissipation of enstrophy}
+\label{subsec:C.6.3}
+
+The lateral momentum diffusion term dissipates the enstrophy when the eddy 
+coefficients are horizontally uniform:
+\begin{flalign*}
+&\int\limits_D  \zeta \; \textbf{k} \cdot \nabla \times 
+	\left[   \nabla_h \left( A^{\,lm}\;\chi  \right)
+	       - \nabla_h \times \left( A^{\,lm}\;\zeta \; \textbf{k} \right)   \right]\;dv &&&\\
+&\quad = A^{\,lm} \int \limits_D \zeta \textbf{k} \cdot \nabla \times 
+ 	\left[    \nabla_h \times \left( \zeta \; \textbf{k} \right)   \right]\;dv &&&\\
+&\quad \equiv A^{\,lm} \sum\limits_{i,j,k}  \zeta \;e_{3f} 
+	\left\{     \delta_{i+1/2} \left[  \frac{e_{2v}} {e_{1v}\,e_{3v}} \delta_i \left[ e_{3f} \zeta  \right]   \right]
+	          + \delta_{j+1/2} \left[  \frac{e_{1u}} {e_{2u}\,e_{3u}} \delta_j \left[ e_{3f} \zeta  \right]   \right]      \right\}   &&&\\ 
+%
+\intertext{Using \autoref{eq:DOM_di_adj}, it follows:}
+%
+&\quad \equiv  - A^{\,lm} \sum\limits_{i,j,k} 
+	\left\{    \left(  \frac{1} {e_{1v}\,e_{3v}}  \delta_i \left[ e_{3f} \zeta  \right]  \right)^2   b_v
+	         + \left(  \frac{1} {e_{2u}\,e_{3u}}  \delta_j \left[ e_{3f} \zeta  \right] \right)^2   b_u  \right\}  \quad \leq \;0    &&&\\
+\end{flalign*}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation of Horizontal Divergence
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Conservation of horizontal divergence}
+\label{subsec:C.6.4}
+
+When the horizontal divergence of the horizontal diffusion of momentum 
+(discrete sense) is taken, the term associated with the vertical curl of the 
+vorticity is zero locally, due to \autoref{eq:DOM_div_curl}. 
+The resulting term conserves the $\chi$ and dissipates $\chi^2$ 
+when the eddy coefficients are horizontally uniform.
+\begin{flalign*}
+& \int\limits_D  \nabla_h \cdot 
+	\Bigl[     \nabla_h \left( A^{\,lm}\;\chi \right)
+	          - \nabla_h \times \left( A^{\,lm}\;\zeta \;\textbf{k} \right)    \Bigr]  dv
+= \int\limits_D  \nabla_h \cdot \nabla_h \left( A^{\,lm}\;\chi  \right)   dv   \\
+%
+&\equiv \sum\limits_{i,j,k} 
+	\left\{   \delta_i \left[ A_u^{\,lm} \frac{e_{2u}\,e_{3u}} {e_{1u}}  \delta_{i+1/2} \left[ \chi \right]  \right]
+	        + \delta_j \left[ A_v^{\,lm} \frac{e_{1v}\,e_{3v}} {e_{2v}}  \delta_{j+1/2} \left[ \chi \right]  \right]    \right\}    \\ 
+%
+\intertext{Using \autoref{eq:DOM_di_adj}, it follows:}
+%
+&\equiv \sum\limits_{i,j,k} 
+	- \left\{   \frac{e_{2u}\,e_{3u}} {e_{1u}}  A_u^{\,lm} \delta_{i+1/2} \left[ \chi \right] \delta_{i+1/2} \left[ 1 \right] 
+	          + \frac{e_{1v}\,e_{3v}} {e_{2v}}  A_v^{\,lm} \delta_{j+1/2} \left[ \chi \right] \delta_{j+1/2} \left[ 1 \right]    \right\} 
+	\quad \equiv 0      \\ 
+\end{flalign*}
+
+% -------------------------------------------------------------------------------------------------------------
+%       Dissipation of Horizontal Divergence Variance
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Dissipation of horizontal divergence variance}
+\label{subsec:C.6.5}
+
+\begin{flalign*}
+&\int\limits_D \chi \;\nabla_h \cdot 
+	\left[    \nabla_h              \left( A^{\,lm}\;\chi                    \right)
+	        - \nabla_h   \times  \left( A^{\,lm}\;\zeta \;\textbf{k} \right)    \right]\;  dv
+ = A^{\,lm}   \int\limits_D \chi \;\nabla_h \cdot \nabla_h \left( \chi \right)\;  dv    \\ 
+%
+&\equiv A^{\,lm}  \sum\limits_{i,j,k}  \frac{1} {e_{1t}\,e_{2t}\,e_{3t}}  \chi 
+	\left\{
+	   \delta_i  \left[   \frac{e_{2u}\,e_{3u}} {e_{1u}}  \delta_{i+1/2} \left[ \chi \right]   \right]
+	+ \delta_j  \left[   \frac{e_{1v}\,e_{3v}} {e_{2v}}   \delta_{j+1/2} \left[ \chi \right]   \right]
+	\right\} \;   e_{1t}\,e_{2t}\,e_{3t}    \\ 
+%
+\intertext{Using \autoref{eq:DOM_di_adj}, it turns out to be:}
+%
+&\equiv - A^{\,lm} \sum\limits_{i,j,k}
+	\left\{    \left(  \frac{1} {e_{1u}}  \delta_{i+1/2}  \left[ \chi \right]  \right)^2  b_u
+            + \left(  \frac{1} {e_{2v}}  \delta_{j+1/2}  \left[ \chi \right]  \right)^2  b_v    \right\}    
+\quad \leq 0             \\
+\end{flalign*}
+
+% ================================================================
+% Conservation Properties on Vertical Momentum Physics
+% ================================================================
+\section{Conservation properties on vertical momentum physics}
+\label{sec:C.7}
+
+As for the lateral momentum physics, the continuous form of the vertical diffusion 
+of momentum satisfies several integral constraints. The first two are associated 
+with the conservation of momentum and the dissipation of horizontal kinetic energy:
+\begin{align*}
+ \int\limits_D   \frac{1} {e_3 }\; \frac{\partial } {\partial k} 
+       \left(   \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}   \right)\;  dv 
+	\qquad \quad &= \vec{\textbf{0}}    \\
+%
+\intertext{and}
+%
+\int\limits_D 
+	\textbf{U}_h \cdot   \frac{1} {e_3 }\; \frac{\partial } {\partial k}
+	\left(   \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}   \right)\; dv    \quad &\leq 0     \\
+\end{align*}
+
+The first property is obvious. The second results from:
+\begin{flalign*}
+\int\limits_D 
+	\textbf{U}_h \cdot   \frac{1} {e_3 }\; \frac{\partial } {\partial k}
+	\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}   \right)\;dv    &&&\\
+\end{flalign*}
+\begin{flalign*}
+&\equiv \sum\limits_{i,j,k} 
+	\left( 
+	   u\; \delta_k \left[ \frac{A_u^{\,vm}} {e_{3uw}} \delta_{k+1/2}  \left[ u \right]  \right]\;  e_{1u}\,e_{2u} 
+	+ v\; \delta_k \left[ \frac{A_v^{\,vm}} {e_{3vw}} \delta_{k+1/2}   \left[ v \right]  \right]\;  e_{1v}\,e_{2v} \right)   &&&\\ 
+%
+\intertext{since the horizontal scale factor does not depend on $k$, it follows:}
+%
+&\equiv - \sum\limits_{i,j,k} 
+	\left(  \frac{A_u^{\,vm}} {e_{3uw}} \left( \delta_{k+1/2} \left[ u \right] \right)^2\; e_{1u}\,e_{2u} 
+	      + \frac{A_v^{\,vm}} {e_{3vw}}  \left( \delta_{k+1/2} \left[ v \right] \right)^2\; e_{1v}\,e_{2v}  \right)
+\quad \leq 0   &&&\\
+\end{flalign*}
+
+The vorticity is also conserved. Indeed:
+\begin{flalign*}
+\int \limits_D 
+	\frac{1} {e_3 } \textbf{k} \cdot \nabla \times 
+		\left( \frac{1} {e_3 }\; \frac{\partial } {\partial k}  \left( 
+		        \frac{A^{\,vm}} {e_3}\; \frac{\partial \textbf{U}_h } {\partial k}  
+		  \right)  \right)\; dv   &&&\\ 
+\end{flalign*}
+\begin{flalign*}
+\equiv \sum\limits_{i,j,k}  \frac{1} {e_{3f}}\; \frac{1} {e_{1f}\,e_{2f}}
+	\bigg\{    \biggr.   \quad
+	\delta_{i+1/2} 
+		&\left(   \frac{e_{2v}} {e_{3v}} \delta_k  \left[  \frac{1} {e_{3vw}} \delta_{k+1/2} \left[ v \right]  \right]  \right)   &&\\
+	\biggl. 
+	- \delta_{j+1/2} 
+		&\left(   \frac{e_{1u}} {e_{3u}} \delta_k \left[  \frac{1} {e_{3uw}}\delta_{k+1/2} \left[ u \right]  \right]   \right)
+	\biggr\} \;
+	e_{1f}\,e_{2f}\,e_{3f} \; \equiv 0   && \\
+\end{flalign*}
+
+If the vertical diffusion coefficient is uniform over the whole domain, the 
+enstrophy is dissipated, $i.e.$
+\begin{flalign*}
+\int\limits_D \zeta \, \textbf{k} \cdot \nabla \times 
+	\left(   \frac{1} {e_3}\; \frac{\partial } {\partial k}
+		\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}   \right)   \right)\; dv = 0   &&&\\
+\end{flalign*}
+
+This property is only satisfied in $z$-coordinates:
+\begin{flalign*}
+\int\limits_D \zeta \, \textbf{k} \cdot \nabla \times 
+	\left(  \frac{1} {e_3}\; \frac{\partial } {\partial k}
+		\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}  \right)   \right)\; dv   &&& \\ 
+\end{flalign*}
+\begin{flalign*}
+\equiv \sum\limits_{i,j,k} \zeta \;e_{3f} \;
+	\biggl\{ 	\biggr.	\quad
+	\delta_{i+1/2} 
+		&\left(   \frac{e_{2v}} {e_{3v}} \delta_k \left[ \frac{A_v^{\,vm}} {e_{3vw}} \delta_{k+1/2}[v]  \right]   \right)   &&\\
+	- \delta_{j+1/2} 
+		&\biggl.
+		\left(   \frac{e_{1u}} {e_{3u}} \delta_k \left[ \frac{A_u^{\,vm}} {e_{3uw}} \delta_{k+1/2} [u]  \right]    \right) \biggr\}   &&\\ 
+\end{flalign*}
+\begin{flalign*}
+\equiv \sum\limits_{i,j,k} \zeta \;e_{3f} 
+	\biggl\{		\biggr.	\quad
+	\frac{1} {e_{3v}} \delta_k 
+		&\left[ \frac{A_v^{\,vm}} {e_{3vw}} \delta_{k+1/2} \left[ \delta_{i+1/2} \left[ e_{2v}\,v \right] \right]   \right]    &&\\ 
+ 	 \biggl. 
+	- \frac{1} {e_{3u}} \delta_k 
+		&\left[  \frac{A_u^{\,vm}} {e_{3uw}} \delta_{k+1/2} \left[ \delta_{j+1/2} \left[ e_{1u}\,u \right] \right]  \right]  \biggr\}  &&\\ 
+\end{flalign*}
+Using the fact that the vertical diffusion coefficients are uniform, and that in 
+$z$-coordinate, the vertical scale factors do not depend on $i$ and $j$ so 
+that: $e_{3f} =e_{3u} =e_{3v} =e_{3t} $ and $e_{3w} =e_{3uw} =e_{3vw} $, 
+it follows:
+\begin{flalign*}
+\equiv A^{\,vm} \sum\limits_{i,j,k} \zeta \;\delta_k 
+	\left[   \frac{1} {e_{3w}} \delta_{k+1/2} \Bigl[   \delta_{i+1/2} \left[ e_{2v}\,v \right]
+		                          - \delta_{j+1/ 2} \left[ e_{1u}\,u \right]   \Bigr]    \right]    &&&\\
+\end{flalign*}
+\begin{flalign*}
+\equiv - A^{\,vm} \sum\limits_{i,j,k} \frac{1} {e_{3w}}
+	\left( \delta_{k+1/2} \left[ \zeta  \right] \right)^2 \; e_{1f}\,e_{2f}  \; \leq 0    &&&\\
+\end{flalign*}
+Similarly, the horizontal divergence is obviously conserved:
+
+\begin{flalign*}
+\int\limits_D \nabla \cdot 
+\left( \frac{1} {e_3 }\; \frac{\partial } {\partial k}
+		\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k} \right) \right)\; dv = 0    &&&\\
+\end{flalign*}
+and the square of the horizontal divergence decreases ($i.e.$ the horizontal 
+divergence is dissipated) if the vertical diffusion coefficient is uniform over the 
+whole domain:
+
+\begin{flalign*}
+\int\limits_D \chi \;\nabla \cdot 
+\left( \frac{1} {e_3 }\; \frac{\partial } {\partial k}
+		\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k}  \right) \right)\;  dv = 0  &&&\\
+\end{flalign*}
+This property is only satisfied in the $z$-coordinate:
+\begin{flalign*}
+\int\limits_D \chi \;\nabla \cdot 
+\left( \frac{1} {e_3 }\; \frac{\partial } {\partial k}
+		\left( \frac{A^{\,vm}} {e_3 }\; \frac{\partial \textbf{U}_h } {\partial k} \right)  \right)\; dv    &&&\\
+\end{flalign*}
+\begin{flalign*}
+\equiv \sum\limits_{i,j,k} \frac{\chi } {e_{1t}\,e_{2t}}
+	\biggl\{ 	\Biggr.	\quad
+	\delta_{i+1/2} 
+		&\left(   \frac{e_{2u}} {e_{3u}} \delta_k 
+		   	\left[ \frac{A_u^{\,vm}} {e_{3uw}} \delta_{k+1/2} [u] \right] \right)    &&\\ 
+ 	\Biggl. 
+	+ \delta_{j+1/2} 
+		&\left( \frac{e_{1v}} {e_{3v}} \delta_k 
+			\left[ \frac{A_v^{\,vm}} {e_{3vw}} \delta_{k+1/2} [v] \right]   \right)
+	\Biggr\} \;  e_{1t}\,e_{2t}\,e_{3t}   &&\\ 
+\end{flalign*}
+
+\begin{flalign*}
+\equiv A^{\,vm} \sum\limits_{i,j,k}  \chi \,
+	\biggl\{	\biggr.	\quad
+	\delta_{i+1/2}
+		&\left( 
+		   \delta_k \left[ 
+			\frac{1} {e_{3uw}} \delta_{k+1/2} \left[ e_{2u}\,u \right] \right]   \right)    && \\ 
+	\biggl. 
+	+ \delta_{j+1/2} 
+		&\left(    \delta_k \left[ 
+			\frac{1} {e_{3vw}} \delta_{k+1/2} \left[ e_{1v}\,v \right] \right]   \right)   \biggr\}    && \\ 
+\end{flalign*}
+
+\begin{flalign*}
+\equiv -A^{\,vm} \sum\limits_{i,j,k} 
+\frac{\delta_{k+1/2} \left[ \chi \right]} {e_{3w}}\; \biggl\{ 
+	\delta_{k+1/2} \Bigl[
+		   \delta_{i+1/2} \left[ e_{2u}\,u \right]
+		+ \delta_{j+1/2} \left[ e_{1v}\,v \right]  \Bigr]    \biggr\}    &&&\\
+\end{flalign*}
+
+\begin{flalign*}
+\equiv -A^{\,vm} \sum\limits_{i,j,k}
+ \frac{1} {e_{3w}} \delta_{k+1/2} \left[ \chi \right]\; \delta_{k+1/2} \left[ e_{1t}\,e_{2t} \;\chi \right]   &&&\\
+\end{flalign*}
+
+\begin{flalign*}
+\equiv -A^{\,vm} \sum\limits_{i,j,k} 
+\frac{e_{1t}\,e_{2t}} {e_{3w}}\; \left( \delta_{k+1/2} \left[ \chi \right]  \right)^2     \quad  \equiv 0    &&&\\
+\end{flalign*}
+
+% ================================================================
+% Conservation Properties on Tracer Physics
+% ================================================================
+\section{Conservation properties on tracer physics}
+\label{sec:C.8}
+
+The numerical schemes used for tracer subgridscale physics are written such 
+that the heat and salt contents are conserved (equations in flux form). 
+Since a flux form is used to compute the temperature and salinity, 
+the quadratic form of these quantities ($i.e.$ their variance) globally tends to diminish. 
+As for the advection term, there is conservation of mass only if the Equation Of Seawater is linear. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation of Tracers
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Conservation of tracers}
+\label{subsec:C.8.1}
+
+constraint of conservation of tracers:
+\begin{flalign*}
+&\int\limits_D  \nabla  \cdot \left( A\;\nabla T \right)\;dv  &&&\\ 
+\\
+&\equiv \sum\limits_{i,j,k} 
+	\biggl\{ 	\biggr.
+	\delta_i 
+		\left[ 
+		A_u^{\,lT} \frac{e_{2u}\,e_{3u}} {e_{1u}} \delta_{i+1/2} 
+			\left[ T \right]
+		\right]
+	+ \delta_j 
+		\left[ 
+		A_v^{\,lT} \frac{e_{1v}\,e_{3v}} {e_{2v}} \delta_{j+1/2} 
+			\left[ T \right] 
+		\right]
+	&&\\  & \qquad \qquad \qquad \qquad \qquad \qquad \quad \;\;\;
+	+ \delta_k 
+		\left[ 
+		A_w^{\,vT} \frac{e_{1t}\,e_{2t}} {e_{3t}} \delta_{k+1/2} 
+			\left[ T \right] 
+		\right]
+	\biggr\}   \quad  \equiv 0
+	&&\\ 
+\end{flalign*}
+
+In fact, this property simply results from the flux form of the operator. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       Dissipation of Tracer Variance
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Dissipation of tracer variance}
+\label{subsec:C.8.2}
+
+constraint on the dissipation of tracer variance:
+\begin{flalign*}
+\int\limits_D T\;\nabla & \cdot \left( A\;\nabla T \right)\;dv	&&&\\ 
+&\equiv   \sum\limits_{i,j,k} \; T
+\biggl\{  \biggr.
+     \delta_i \left[ A_u^{\,lT} \frac{e_{2u}\,e_{3u}} {e_{1u}} \delta_{i+1/2} \left[T\right] \right]
+& + \delta_j \left[ A_v^{\,lT} \frac{e_{1v} \,e_{3v}} {e_{2v}} \delta_{j+1/2} \left[T\right] \right] 
+		\quad&& \\ 
+ \biggl. 
+&&+ \delta_k \left[A_w^{\,vT}\frac{e_{1t}\,e_{2t}} {e_{3t}}\delta_{k+1/2}\left[T\right]\right]
+\biggr\} && 
+\end{flalign*}
+\begin{flalign*}
+\equiv - \sum\limits_{i,j,k} 
+	\biggl\{ 	\biggr.	\quad
+	&    A_u^{\,lT} \left( \frac{1} {e_{1u}} \delta_{i+1/2} \left[ T \right]  \right)^2   e_{1u}\,e_{2u}\,e_{3u}    && \\
+	& + A_v^{\,lT} \left( \frac{1} {e_{2v}} \delta_{j+1/2} \left[ T \right]  \right)^2   e_{1v}\,e_{2v}\,e_{3v}     && \\ \biggl. 
+	& + A_w^{\,vT} \left( \frac{1} {e_{3w}} \delta_{k+1/2} \left[ T \right]   \right)^2    e_{1w}\,e_{2w}\,e_{3w}   \biggr\} 
+	\quad      \leq 0      && \\ 
+\end{flalign*}
+
+
+%%%%  end of appendix in gm comment
+%}
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_D.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_D.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_D.tex	(revision 10321)
@@ -0,0 +1,206 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Appendix D Ñ Coding Rules
+% ================================================================
+\chapter{Coding Rules}
+\label{apdx:D}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+$\ $\newline    % force a new ligne
+
+
+A "model life" is more than ten years. Its software, composed of a few 
+hundred modules, is used by many people who are scientists or students 
+and do not necessarily know every aspect of computing very well. 
+Moreover, a well thought-out program is easier to read and understand, 
+less difficult to modify, produces fewer bugs and is easier to maintain. 
+Therefore, it is essential that the model development follows some rules :
+
+- well planned and designed
+
+- well written
+
+- well documented (both on- and off-line)
+
+- maintainable
+
+- easily portable
+
+- flexible.
+
+To satisfy part of these aims, \NEMO is written with a coding standard which 
+is close to the ECMWF rules, named DOCTOR \citep{Gibson_TR86}. 
+These rules present some advantages like :
+
+- to provide a well presented program
+
+- to use rules for variable names which allow recognition of their type 
+(integer, real, parameter, local or shared variables, etc. ). 
+
+This facilitates both the understanding and the debugging of an algorithm.
+
+% ================================================================
+% The program structure
+% ================================================================
+\section{Program structure}
+\label{sec:D_structure}
+
+Each program begins with a set of headline comments containing :
+
+- the program title
+
+- the purpose of the routine
+
+- the method and algorithms used
+
+- the detail of input and output interfaces
+
+- the external routines and functions used (if they exist)
+
+- references (if they exist)
+
+- the author name(s), the date of creation and any updates.
+
+- Each program is split into several well separated sections and 
+sub-sections with an underlined title and specific labelled statements.
+
+- A program has not more than 200 to 300 lines.
+
+A template of a module style can be found on the NEMO depository 
+in the following file : NEMO/OPA\_SRC/module\_example.
+% ================================================================
+% Coding conventions
+% ================================================================
+\section{Coding conventions}
+\label{sec:D_coding}
+
+- Use of the universal language \textsc{Fortran} 90, and try to avoid obsolescent
+features like statement functions, do not use GO TO and EQUIVALENCE statements.
+
+- A continuation line begins with the character {\&} indented by three spaces 
+compared to the previous line, while the previous line ended with the character {\&}.
+
+- All the variables must be declared. The code is usually compiled with implicit none.
+ 
+- Never use continuation lines in the declaration of a variable. When searching a 
+variable in the code through a \textit{grep} command, the declaration line will be found.
+
+- In the declaration of a PUBLIC variable, the comment part at the end of the line 
+should start with the two characters "\verb?!:?". the following UNIX command, \\
+\verb?grep var_name *90 \ grep \!: ? \\
+will display the module name and the line where the var\_name declaration is.
+
+- Always use a three spaces indentation in DO loop, CASE, or IF-ELSEIF-ELSE-ENDIF 
+statements.
+
+- use a space after a comma, except when it appears to separate the indices of an array.
+
+- use call to ctl\_stop routine instead of just a STOP.
+
+
+\newpage
+% ================================================================
+% Naming Conventions
+% ================================================================
+\section{Naming conventions}
+\label{sec:D_naming}
+
+The purpose of the naming conventions is to use prefix letters to classify 
+model variables. These conventions allow the variable type to be easily 
+known and rapidly identified. The naming conventions are summarised 
+in the Table below:
+
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]  \label{tab:VarName}
+\begin{center}
+\begin{tabular}{|p{45pt}|p{35pt}|p{45pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|p{40pt}|}
+\hline  Type \par / Status &   integer&   real&   logical &   character  & structure &   double \par precision&   complex \\  
+\hline
+public  \par or  \par module variable& 
+\textbf{m n} \par \textit{but not} \par \textbf{nn\_ np\_}& 
+\textbf{a b e f g h o q r} \par \textbf{t} \textit{to} \textbf{x} \par but not \par \textbf{fs rn\_}& 
+\textbf{l} \par \textit{but not} \par \textbf{lp ld} \par \textbf{ ll ln\_}& 
+\textbf{c} \par \textit{but not} \par \textbf{cp cd} \par \textbf{cl cn\_}& 
+\textbf{s} \par \textit{but not} \par \textbf{sd sd} \par \textbf{sl sn\_}& 
+\textbf{d} \par \textit{but not} \par \textbf{dp dd} \par \textbf{dl dn\_}& 
+\textbf{y} \par \textit{but not} \par \textbf{yp yd} \par \textbf{yl yn} \\
+\hline
+dummy \par argument& 
+\textbf{k} \par \textit{but not} \par \textbf{kf}& 
+\textbf{p} \par \textit{but not} \par \textbf{pp pf}& 
+\textbf{ld}& 
+\textbf{cd}& 
+\textbf{sd}& 
+\textbf{dd}& 
+\textbf{yd} \\
+\hline
+local \par variable& 
+\textbf{i}& 
+\textbf{z}& 
+\textbf{ll}& 
+\textbf{cl}& 
+\textbf{sl}& 
+\textbf{dl}& 
+\textbf{yl} \\
+\hline
+loop \par control& 
+\textbf{j} \par \textit{but not} \par \textbf{jp}& 
+& 
+& 
+&
+& 
+& 
+ \\
+\hline
+parameter& 
+\textbf{jp np\_}& 
+\textbf{pp}& 
+\textbf{lp}& 
+\textbf{cp}& 
+\textbf{sp}& 
+\textbf{dp}& 
+\textbf{yp} \\
+\hline
+
+namelist&
+\textbf{nn\_}& 
+\textbf{rn\_}& 
+\textbf{ln\_}& 
+\textbf{cn\_}& 
+\textbf{sn\_}& 
+\textbf{dn\_}& 
+\textbf{yn\_}
+\\
+\hline
+CPP \par macro& 
+\textbf{kf}& 
+\textbf{fs} \par & 
+& 
+&
+& 
+& 
+ \\
+\hline
+\end{tabular}
+\label{tab:tab1}
+\end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+N.B.   Parameter here, in not only parameter in the \textsc{Fortran} acceptation, it is also used for code variables 
+that are read in namelist and should never been modified during a simulation. 
+It is the case, for example, for the size of a domain (jpi,jpj,jpk).
+
+\newpage
+% ================================================================
+% The program structure
+% ================================================================
+%\section{Program structure}
+%abel{sec:Apdx_D_structure}
+
+%To be done....
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_E.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_E.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_E.tex	(revision 10321)
@@ -0,0 +1,809 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Appendix E : Note on some algorithms
+% ================================================================
+\chapter{Note on some algorithms}
+\label{apdx:E}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+ 
+ This appendix some on going consideration on algorithms used or planned to be used
+in \NEMO. 
+
+$\ $\newline    % force a new ligne
+
+% -------------------------------------------------------------------------------------------------------------
+%        UBS scheme  
+% -------------------------------------------------------------------------------------------------------------
+\section{Upstream Biased Scheme (UBS) (\protect\np{ln\_traadv\_ubs}\forcode{ = .true.})}
+\label{sec:TRA_adv_ubs}
+
+The UBS advection scheme is an upstream biased third order scheme based on 
+an upstream-biased parabolic interpolation. It is also known as Cell Averaged 
+QUICK scheme (Quadratic Upstream Interpolation for Convective 
+Kinematics). For example, in the $i$-direction :
+\begin{equation} \label{eq:tra_adv_ubs2}
+\tau _u^{ubs} = \left\{	 \begin{aligned}
+  & \tau _u^{cen4} + \frac{1}{12} \,\tau"_i	   & \quad \text{if }\ u_{i+1/2} \geqslant 0 \\
+  & \tau _u^{cen4} - \frac{1}{12} \,\tau"_{i+1} & \quad \text{if }\ u_{i+1/2}       <       0
+  						 \end{aligned}    \right.
+\end{equation}
+or equivalently, the advective flux is
+\begin{equation} \label{eq:tra_adv_ubs2}
+U_{i+1/2} \ \tau _u^{ubs} 
+=U_{i+1/2} \ \overline{ T_i - \frac{1}{6}\,\tau"_i }^{\,i+1/2}
+- \frac{1}{2}\, |U|_{i+1/2} \;\frac{1}{6} \;\delta_{i+1/2}[\tau"_i]
+\end{equation}
+where $U_{i+1/2} = e_{1u}\,e_{3u}\,u_{i+1/2}$ and 
+$\tau "_i =\delta _i \left[ {\delta _{i+1/2} \left[ \tau \right]} \right]$. 
+By choosing this expression for $\tau "$ we consider a fourth order approximation 
+of $\partial_i^2$ with a constant i-grid spacing ($\Delta i=1$). 
+
+Alternative choice: introduce the scale factors:  
+$\tau "_i =\frac{e_{1T}}{e_{2T}\,e_{3T}}\delta _i \left[ \frac{e_{2u} e_{3u} }{e_{1u} }\delta _{i+1/2}[\tau] \right]$.
+
+
+This results in a dissipatively dominant (i.e. hyper-diffusive) truncation 
+error \citep{Shchepetkin_McWilliams_OM05}. The overall performance of the 
+advection scheme is similar to that reported in \cite{Farrow1995}. 
+It is a relatively good compromise between accuracy and smoothness. It is 
+not a \emph{positive} scheme meaning false extrema are permitted but the 
+amplitude of such are significantly reduced over the centred second order 
+method. Nevertheless it is not recommended to apply it to a passive tracer 
+that requires positivity. 
+
+The intrinsic diffusion of UBS makes its use risky in the vertical direction 
+where the control of artificial diapycnal fluxes is of paramount importance. 
+It has therefore been preferred to evaluate the vertical flux using the TVD 
+scheme when \np{ln\_traadv\_ubs}\forcode{ = .true.}.
+
+For stability reasons, in \autoref{eq:tra_adv_ubs}, the first term which corresponds 
+to a second order centred scheme is evaluated using the \textit{now} velocity 
+(centred in time) while the second term which is the diffusive part of the scheme, 
+is evaluated using the \textit{before} velocity (forward in time. This is discussed 
+by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme. UBS and QUICK 
+schemes only differ by one coefficient. Substituting 1/6 with 1/8 in 
+(\autoref{eq:tra_adv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
+This option is not available through a namelist parameter, since the 1/6 
+coefficient is hard coded. Nevertheless it is quite easy to make the 
+substitution in \mdl{traadv\_ubs} module and obtain a QUICK scheme
+
+NB 1: When a high vertical resolution $O(1m)$ is used, the model stability can 
+be controlled by vertical advection (not vertical diffusion which is usually 
+solved using an implicit scheme). Computer time can be saved by using a 
+time-splitting technique on vertical advection. This possibility have been 
+implemented and validated in ORCA05-L301. It is not currently offered in the 
+current reference version. 
+
+NB 2 : In a forthcoming release four options will be proposed for the 
+vertical component used in the UBS scheme. $\tau _w^{ubs}$ will be 
+evaluated using either \textit{(a)} a centred $2^{nd}$ order scheme , 
+or  \textit{(b)} a TVD scheme, or  \textit{(c)} an interpolation based on conservative 
+parabolic splines following \citet{Shchepetkin_McWilliams_OM05} implementation of UBS in ROMS, 
+or  \textit{(d)} an UBS. The $3^{rd}$ case has dispersion properties similar to an 
+eight-order accurate conventional scheme.
+
+NB 3 : It is straight forward to rewrite \autoref{eq:tra_adv_ubs} as follows:
+\begin{equation} \label{eq:tra_adv_ubs2}
+\tau _u^{ubs} = \left\{	 \begin{aligned}
+	& \tau _u^{cen4} + \frac{1}{12} \tau"_i		& \quad \text{if }\ u_{i+1/2} \geqslant 0 \\
+	& \tau _u^{cen4} - \frac{1}{12} \tau"_{i+1}	& \quad \text{if }\ u_{i+1/2}       <       0
+  						 \end{aligned}    \right.
+\end{equation}
+or equivalently 
+\begin{equation} \label{eq:tra_adv_ubs2}
+\begin{split}
+e_{2u} e_{3u}\,u_{i+1/2} \ \tau _u^{ubs} 
+&= e_{2u} e_{3u}\,u_{i+1/2} \ \overline{ T - \frac{1}{6}\,\tau"_i }^{\,i+1/2} \\
+& - \frac{1}{2} e_{2u} e_{3u}\,|u|_{i+1/2} \;\frac{1}{6} \;\delta_{i+1/2}[\tau"_i]
+\end{split}
+\end{equation}
+\autoref{eq:tra_adv_ubs2} has several advantages. First it clearly evidence that 
+the UBS scheme is based on the fourth order scheme to which is added an 
+upstream biased diffusive term. Second, this emphasises that the $4^{th}$ order 
+part have to be evaluated at \emph{now} time step, not only the $2^{th}$ order 
+part as stated above using \autoref{eq:tra_adv_ubs}. Third, the diffusive term is 
+in fact a biharmonic operator with a eddy coefficient with is simply proportional 
+to the velocity.
+
+laplacian diffusion:
+\begin{equation} \label{eq:tra_ldf_lap}
+\begin{split}
+D_T^{lT} =\frac{1}{e_{1T} \; e_{2T}\;  e_{3T} } &\left[ {\quad \delta _i 
+\left[ {A_u^{lT} \frac{e_{2u} e_{3u} }{e_{1u} }\;\delta _{i+1/2} 
+\left[ T \right]} \right]} \right.
+\\
+&\ \left. {+\; \delta _j \left[ 
+{A_v^{lT} \left( {\frac{e_{1v} e_{3v} }{e_{2v} }\;\delta _{j+1/2} \left[ T 
+\right]} \right)} \right]\quad } \right]
+\end{split}
+\end{equation}
+
+bilaplacian:
+\begin{equation} \label{eq:tra_ldf_lap}
+\begin{split}
+D_T^{lT} =&-\frac{1}{e_{1T} \; e_{2T}\;  e_{3T}} \\
+& \delta _i \left[  \sqrt{A_u^{lT}}\ \frac{e_{2u}\,e_{3u}}{e_{1u}}\;\delta _{i+1/2} 
+		  \left[ \frac{1}{e_{1T}\,e_{2T}\, e_{3T}}
+    \delta _i \left[ \sqrt{A_u^{lT}}\ \frac{e_{2u}\,e_{3u}}{e_{1u}}\;\delta _{i+1/2} 
+    		  [T] \right] \right] \right]
+\end{split}
+\end{equation}
+with ${A_u^{lT}}^2 = \frac{1}{12} {e_{1u}}^3\ |u|$, 
+$i.e.$ $A_u^{lT} = \frac{1}{\sqrt{12}} \,e_{1u}\ \sqrt{ e_{1u}\,|u|\,}$
+it comes :
+\begin{equation} \label{eq:tra_ldf_lap}
+\begin{split}
+D_T^{lT} =&-\frac{1}{12}\,\frac{1}{e_{1T} \; e_{2T}\;  e_{3T}} \\
+& \delta _i \left[ e_{2u}\,e_{3u}\,\sqrt{ e_{1u}\,|u|\,}\;\delta _{i+1/2} 
+		 \left[ \frac{1}{e_{1T}\,e_{2T}\, e_{3T}} 
+    \delta _i \left[ e_{2u}\,e_{3u}\,\sqrt{ e_{1u}\,|u|\,}\;\delta _{i+1/2} 
+    		[T] \right] \right] \right]
+\end{split}
+\end{equation}
+if the velocity is uniform ($i.e.$ $|u|=cst$) then the diffusive flux is
+\begin{equation} \label{eq:tra_ldf_lap}
+\begin{split}
+F_u^{lT} = - \frac{1}{12}
+ e_{2u}\,e_{3u}\,|u| \;\sqrt{ e_{1u}}\,\delta _{i+1/2} 
+		 \left[ \frac{1}{e_{1T}\,e_{2T}\, e_{3T}} 
+    \delta _i \left[ e_{2u}\,e_{3u}\,\sqrt{ e_{1u}}\:\delta _{i+1/2} 
+    		[T] \right] \right]
+\end{split}
+\end{equation}
+beurk....  reverte the logic: starting from the diffusive part of the advective flux it comes:
+
+\begin{equation} \label{eq:tra_adv_ubs2}
+\begin{split}
+F_u^{lT}
+&= - \frac{1}{2} e_{2u} e_{3u}\,|u|_{i+1/2} \;\frac{1}{6} \;\delta_{i+1/2}[\tau"_i]
+\end{split}
+\end{equation}
+if the velocity is uniform ($i.e.$ $|u|=cst$) and choosing $\tau "_i =\frac{e_{1T}}{e_{2T}\,e_{3T}}\delta _i \left[ \frac{e_{2u} e_{3u} }{e_{1u} } \delta _{i+1/2}[\tau] \right]$
+
+sol 1 coefficient at T-point ( add $e_{1u}$ and $e_{1T}$ on both side of first $\delta$):
+\begin{equation} \label{eq:tra_adv_ubs2}
+\begin{split}
+F_u^{lT}
+&= - \frac{1}{12} \frac{e_{2u} e_{3u}}{e_{1u}}\;\delta_{i+1/2}\left[ \frac{e_{1T}^3\,|u|}{e_{1T}e_{2T}\,e_{3T}}\,\delta _i \left[ \frac{e_{2u} e_{3u} }{e_{1u} } \delta _{i+1/2}[\tau] \right] \right]
+\end{split}
+\end{equation}
+which leads to ${A_T^{lT}}^2 = \frac{1}{12} {e_{1T}}^3\ \overline{|u|}^{\,i+1/2}$
+
+sol 2 coefficient at u-point: split $|u|$ into $\sqrt{|u|}$ and $e_{1T}$ into $\sqrt{e_{1u}}$
+\begin{equation} \label{eq:tra_adv_ubs2}
+\begin{split}
+F_u^{lT}
+&= - \frac{1}{12} {e_{1u}}^1 \sqrt{e_{1u}|u|} \frac{e_{2u} e_{3u}}{e_{1u}}\;\delta_{i+1/2}\left[ \frac{1}{e_{2T}\,e_{3T}}\,\delta _i \left[ \sqrt{e_{1u}|u|} \frac{e_{2u} e_{3u} }{e_{1u} } \delta _{i+1/2}[\tau] \right] \right] \\
+&= - \frac{1}{12} e_{1u} \sqrt{e_{1u}|u|\,} \frac{e_{2u} e_{3u}}{e_{1u}}\;\delta_{i+1/2}\left[ \frac{1}{e_{1T}\,e_{2T}\,e_{3T}}\,\delta _i \left[ e_{1u} \sqrt{e_{1u}|u|\,} \frac{e_{2u} e_{3u} }{e_{1u}} \delta _{i+1/2}[\tau] \right] \right]
+\end{split}
+\end{equation}
+which leads to ${A_u^{lT}} = \frac{1}{12} {e_{1u}}^3\ |u|$
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Leap-Frog energetic  
+% -------------------------------------------------------------------------------------------------------------
+\section{Leapfrog energetic}
+\label{sec:LF}
+
+We adopt the following semi-discrete notation for time derivative. Given the values of a variable $q$ at successive time step, the time derivation and averaging operators at the mid time step are:
+\begin{subequations} \label{eq:dt_mt}
+\begin{align}
+ \delta _{t+\rdt/2} [q]     &=  \  \ \,   q^{t+\rdt}  - q^{t}		\\
+ \overline q^{\,t+\rdt/2} &= \left\{ q^{t+\rdt} + q^{t} \right\} \; / \; 2
+\end{align}
+\end{subequations}
+As for space operator, the adjoint of the derivation and averaging time operators are 
+$\delta_t^*=\delta_{t+\rdt/2}$ and $\overline{\cdot}^{\,t\,*}= \overline{\cdot}^{\,t+\Delta/2}$
+, respectively. 
+
+The Leap-frog time stepping given by \autoref{eq:DOM_nxt} can be defined as:
+\begin{equation} \label{eq:LF}
+   \frac{\partial q}{\partial t} 
+   		\equiv \frac{1}{\rdt} \overline{ \delta _{t+\rdt/2}[q]}^{\,t} 
+		=         \frac{q^{t+\rdt}-q^{t-\rdt}}{2\rdt}
+\end{equation} 
+Note that \autoref{chap:LF} shows that the leapfrog time step is $\rdt$, not $2\rdt$ 
+as it can be found sometime in literature. 
+The leap-Frog time stepping is a second order centered scheme. As such it respects 
+the quadratic invariant in integral forms, $i.e.$ the following continuous property,
+\begin{equation} \label{eq:Energy}
+\int_{t_0}^{t_1} {q\, \frac{\partial q}{\partial t} \;dt} 
+	=\int_{t_0}^{t_1} {\frac{1}{2}\, \frac{\partial q^2}{\partial t} \;dt} 
+	=  \frac{1}{2} \left( {q_{t_1}}^2 - {q_{t_0}}^2 \right) ,
+\end{equation}
+is satisfied in discrete form. Indeed, 
+\begin{equation} \begin{split}
+\int_{t_0}^{t_1} {q\, \frac{\partial q}{\partial t} \;dt} 
+	&\equiv \sum\limits_{0}^{N} 
+			{\frac{1}{\rdt} q^t \ \overline{ \delta _{t+\rdt/2}[q]}^{\,t} \ \rdt} 
+	   \equiv \sum\limits_{0}^{N}  { q^t \ \overline{ \delta _{t+\rdt/2}[q]}^{\,t} } \\
+	&\equiv \sum\limits_{0}^{N}  { \overline{q}^{\,t+\Delta/2}{ \delta _{t+\rdt/2}[q]}}
+	   \equiv \sum\limits_{0}^{N}  { \frac{1}{2} \delta _{t+\rdt/2}[q^2] }\\
+	&\equiv \sum\limits_{0}^{N}  { \frac{1}{2} \delta _{t+\rdt/2}[q^2] }
+	   \equiv \frac{1}{2} \left( {q_{t_1}}^2 - {q_{t_0}}^2 \right)
+\end{split} \end{equation}
+NB here pb of boundary condition when applying the adjoin! In space, setting to 0 
+the quantity in land area is sufficient to get rid of the boundary condition 
+(equivalently of the boundary value of the integration by part). In time this boundary 
+condition is not physical and \textbf{add something here!!!}
+
+
+
+
+
+
+% ================================================================
+% Iso-neutral diffusion : 
+% ================================================================
+
+\section{Lateral diffusion operator}
+
+% ================================================================
+% Griffies' iso-neutral diffusion operator : 
+% ================================================================
+\subsection{Griffies iso-neutral diffusion operator}
+
+Let try to define a scheme that get its inspiration from the \citet{Griffies_al_JPO98}
+scheme, but is formulated within the \NEMO framework ($i.e.$ using scale 
+factors rather than grid-size and having a position of $T$-points that is not 
+necessary in the middle of vertical velocity points, see \autoref{fig:zgr_e3}).
+
+In the formulation \autoref{eq:tra_ldf_iso} introduced in 1995 in OPA, the ancestor of \NEMO, 
+the off-diagonal terms of the small angle diffusion tensor contain several double 
+spatial averages of a gradient, for example $\overline{\overline{\delta_k \cdot}}^{\,i,k}$. 
+It is apparent that the combination of a $k$ average and a $k$ derivative of the tracer 
+allows for the presence of grid point oscillation structures that will be invisible 
+to the operator. These structures are \textit{computational modes}. They
+will not be damped by the iso-neutral operator, and even possibly amplified by it. 
+In other word, the operator applied to a tracer does not warranties the decrease of 
+its global average variance. To circumvent this, we have introduced a smoothing of 
+the slopes of the iso-neutral surfaces (see \autoref{chap:LDF}). Nevertheless, this technique 
+works fine for $T$ and $S$ as they are active tracers ($i.e.$ they enter the computation 
+of density), but it does not work for a passive tracer.   \citep{Griffies_al_JPO98} introduce 
+a different way to discretise the off-diagonal terms that nicely solve the problem. 
+The idea is to get rid of combinations of an averaged in one direction combined 
+with a derivative in the same direction by considering triads. For example in the 
+(\textbf{i},\textbf{k}) plane, the four triads are defined at the $(i,k)$ $T$-point as follows:
+\begin{equation} \label{eq:Gf_triads}
+_i^k \mathbb{T}_{i_p}^{k_p} (T)
+= \frac{1}{4} \ {b_u}_{\,i+i_p}^{\,k}  \  A_i^k  	\left(  
+                                                     \frac{ \delta_{i + i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} } 
+-\ {_i^k \mathbb{R}_{i_p}^{k_p}} \ \frac{ \delta_{k+k_p} [T^i] }{ {e_{3w}}_{\,i}^{\,k+k_p} } 
+									  \right)
+\end{equation}
+where the indices $i_p$ and $k_p$ define the four triads and take the following value: 
+$i_p = -1/2$ or $1/2$ and $k_p = -1/2$ or $1/2$, 
+$b_u= e_{1u}\,e_{2u}\,e_{3u}$ is the volume of $u$-cells, 
+$A_i^k$ is the lateral eddy diffusivity coefficient defined at $T$-point,
+and $_i^k \mathbb{R}_{i_p}^{k_p}$ is the slope associated with each triad :
+\begin{equation} \label{eq:Gf_slopes}
+_i^k \mathbb{R}_{i_p}^{k_p} 
+=\frac{ {e_{3w}}_{\,i}^{\,k+k_p}} { {e_{1u}}_{\,i+i_p}^{\,k}} \ \frac 
+{\left(\alpha / \beta \right)_i^k  \ \delta_{i + i_p}[T^k] - \delta_{i + i_p}[S^k] }
+{\left(\alpha / \beta \right)_i^k  \ \delta_{k+k_p}[T^i ] - \delta_{k+k_p}[S^i ] }
+\end{equation}
+Note that in \autoref{eq:Gf_slopes} we use the ratio $\alpha / \beta$ instead of 
+multiplying the temperature derivative by $\alpha$ and the salinity derivative 
+by $\beta$. This is more efficient as the ratio $\alpha / \beta$ can to be 
+evaluated directly.
+
+Note that in \autoref{eq:Gf_triads}, we chose to use ${b_u}_{\,i+i_p}^{\,k}$ instead of 
+${b_{uw}}_{\,i+i_p}^{\,k+k_p}$. This choice has been motivated by the decrease 
+of tracer variance and the presence of partial cell at the ocean bottom 
+(see \autoref{apdx:Gf_operator}).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht] \begin{center}
+\includegraphics[width=0.70\textwidth]{Fig_ISO_triad}
+\caption{  \protect\label{fig:ISO_triad}   
+Triads used in the Griffies's like iso-neutral diffision scheme for 
+$u$-component (upper panel) and $w$-component (lower panel).}
+\end{center}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The four iso-neutral fluxes associated with the triads are defined at $T$-point. 
+They take the following expression :
+\begin{flalign} \label{eq:Gf_fluxes}
+\begin{split}
+{_i^k {\mathbb{F}_u}_{i_p}^{k_p} } (T) 
+   &= \ \; \qquad  \quad    { _i^k \mathbb{T}_{i_p}^{k_p} }(T) \;\ / \ { {e_{1u}}_{\,i+i_p}^{\,k}}    \\
+{_i^k {\mathbb{F}_w}_{i_p}^{k_p} } (T)
+   &=  -\; { _i^k \mathbb{R}_{i_p}^{k_p} }
+				 \ \; { _i^k \mathbb{T}_{i_p}^{k_p} }(T) \;\ / \ { {e_{3w}}_{\,i}^{\,k+k_p}}
+\end{split}
+\end{flalign}
+
+The resulting iso-neutral fluxes at $u$- and $w$-points are then given by the 
+sum of the fluxes that cross the $u$- and $w$-face (\autoref{fig:ISO_triad}):
+\begin{flalign} \label{eq:iso_flux} 
+\textbf{F}_{iso}(T) 
+&\equiv  \sum_{\substack{i_p,\,k_p}} 
+   \begin{pmatrix} 
+      {_{i+1/2-i_p}^k {\mathbb{F}_u}_{i_p}^{k_p} } (T)      \\
+      \\
+      {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p} } (T)      \\   
+   \end{pmatrix}    \notag \\
+&  \notag \\
+&\equiv  \sum_{\substack{i_p,\,k_p}} 
+   \begin{pmatrix} 
+      && { _{i+1/2-i_p}^k \mathbb{T}_{i_p}^{k_p} }(T) \;\ / \ { {e_{1u}}_{\,i+1/2}^{\,k} }    \\
+      \\
+      & -\; { _i^{k+1/2-k_p} \mathbb{R}_{i_p}^{k_p} }
+        & {_i^{k+1/2-k_p} \mathbb{T}_{i_p}^{k_p} }(T) \;\ / \ { {e_{3w}}_{\,i}^{\,k+1/2} }   \\   
+   \end{pmatrix}      % \\
+% &\\
+% &\equiv  \sum_{\substack{i_p,\,k_p}} 
+%    \begin{pmatrix} 
+%       \qquad  \qquad  \qquad 
+%       \frac{1}{ {e_{1u}}_{\,i+1/2}^{\,k} }  \ \;  
+%        { _{i+1/2-i_p}^k \mathbb{T}_{i_p}^{k_p} }(T)\\
+%       \\
+%       -\frac{1}{ {e_{3w}}_{\,i}^{\,k+1/2} }  \ \; 
+%        { _i^{k+1/2-k_p} \mathbb{R}_{i_p}^{k_p} } \ \;  
+%                  {_i^{k+1/2-k_p} \mathbb{T}_{i_p}^{k_p} }(T)\\   
+%    \end{pmatrix}      
+\end{flalign}
+resulting in a iso-neutral diffusion tendency on temperature given by the divergence 
+of the sum of all the four triad fluxes :
+\begin{equation} \label{eq:Gf_operator}
+D_l^T = \frac{1}{b_T}  \sum_{\substack{i_p,\,k_p}} \left\{  
+		 \delta_{i} \left[{_{i+1/2-i_p}^k {\mathbb{F}_u }_{i_p}^{k_p}} \right] 
+	     + \delta_{k} \left[ {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}} \right]   \right\}
+\end{equation}
+where $b_T= e_{1T}\,e_{2T}\,e_{3T}$ is the volume of $T$-cells. 
+
+This expression of the iso-neutral diffusion has been chosen in order to satisfy 
+the following six properties:
+\begin{description}
+\item[$\bullet$ horizontal diffusion] The discretization of the diffusion operator 
+recovers the traditional five-point Laplacian in the limit of flat iso-neutral direction :
+\begin{equation} \label{eq:Gf_property1a}
+D_l^T = \frac{1}{b_T}  \ \delta_{i} 
+	\left[ \frac{e_{2u}\,e_{3u}}{e_{1u}} \; \overline{A}^{\,i} \; \delta_{i+1/2}[T] \right] 
+\qquad  \text{when} \quad 
+	{ _i^k \mathbb{R}_{i_p}^{k_p} }=0
+\end{equation}
+
+\item[$\bullet$ implicit treatment in the vertical]  In the diagonal term associated 
+with the vertical divergence of the iso-neutral fluxes (i.e. the term associated 
+with a second order vertical derivative) appears only tracer values associated 
+with a single water column. This is of paramount importance since it means
+that the implicit in time algorithm for solving the vertical diffusion equation can 
+be used to evaluate this term. It is a necessity since the vertical eddy diffusivity 
+associated with this term,  
+\begin{equation}
+	 \sum_{\substack{i_p, \,k_p}} \left\{  
+		A_i^k \; \left(_i^k \mathbb{R}_{i_p}^{k_p}\right)^2
+	\right\} 
+\end{equation}
+can be quite large.
+
+\item[$\bullet$ pure iso-neutral operator]  The iso-neutral flux of locally referenced 
+potential density is zero, $i.e.$
+\begin{align} \label{eq:Gf_property2}
+\begin{matrix}
+&{_i^k {\mathbb{F}_u}_{i_p}^{k_p} (\rho)} 
+	&=    &\alpha_i^k   &{_i^k {\mathbb{F}_u}_{i_p}^{k_p} } (T) 
+	&- \ \;  \beta _i^k    &{_i^k {\mathbb{F}_u}_{i_p}^{k_p} } (S) & = \ 0   \\
+&{_i^k {\mathbb{F}_w}_{i_p}^{k_p} (\rho)} 
+	&=    &\alpha_i^k   &{_i^k {\mathbb{F}_w}_{i_p}^{k_p} } (T) 
+	&- \  \; \beta _i^k    &{_i^k {\mathbb{F}_w}_{i_p}^{k_p} } (S)  &= \ 0
+\end{matrix}
+\end{align}
+This result is trivially obtained using the \autoref{eq:Gf_triads} applied to $T$ and $S$ 
+and the definition of the triads' slopes \autoref{eq:Gf_slopes}.
+
+\item[$\bullet$ conservation of tracer] The iso-neutral diffusion term conserve the 
+total tracer content, $i.e.$
+\begin{equation} \label{eq:Gf_property1}
+\sum_{i,j,k} \left\{ D_l^T \ b_T \right\} = 0
+\end{equation}
+This property is trivially satisfied since the iso-neutral diffusive operator 
+is written in flux form.
+
+\item[$\bullet$ decrease of tracer variance] The iso-neutral diffusion term does 
+not increase the total tracer variance, $i.e.$
+\begin{equation} \label{eq:Gf_property1}
+\sum_{i,j,k} \left\{ T \ D_l^T \ b_T \right\} \leq 0
+\end{equation}
+The property is demonstrated in the \autoref{apdx:Gf_operator}. It is a 
+key property for a diffusion term. It means that the operator is also a dissipation 
+term, $i.e.$ it is a sink term for the square of the quantity on which it is applied. 
+It therfore ensure that, when the diffusivity coefficient is large enough, the field 
+on which it is applied become free of grid-point noise.
+
+\item[$\bullet$ self-adjoint operator] The iso-neutral diffusion operator is self-adjoint, 
+$i.e.$
+\begin{equation} \label{eq:Gf_property1}
+\sum_{i,j,k} \left\{ S \ D_l^T \ b_T \right\} = \sum_{i,j,k} \left\{ D_l^S \ T \ b_T \right\} 
+\end{equation}
+In other word, there is no needs to develop a specific routine from the adjoint of this 
+operator. We just have to apply the same routine. This properties can be demonstrated 
+quite easily in a similar way the "non increase of tracer variance" property has been 
+proved (see \autoref{apdx:Gf_operator}).
+\end{description}
+
+
+$\ $\newline      %force an empty line
+% ================================================================
+% Skew flux formulation for Eddy Induced Velocity : 
+% ================================================================
+\subsection{Eddy induced velocity and skew flux formulation}
+
+When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined), 
+an additional advection term is added. The associated velocity is the so called 
+eddy induced velocity, the formulation of which depends on the slopes of iso-
+neutral surfaces. Contrary to the case of iso-neutral mixing, the slopes used 
+here are referenced to the geopotential surfaces, $i.e.$ \autoref{eq:ldfslp_geo} 
+is used in $z$-coordinate, and the sum \autoref{eq:ldfslp_geo}
++ \autoref{eq:ldfslp_iso} in $z^*$ or $s$-coordinates. 
+
+The eddy induced velocity is given by: 
+\begin{equation} \label{eq:eiv_v}
+\begin{split}
+ u^* & = - \frac{1}{e_2\,e_{3}}          \;\partial_k \left( e_2 \, A_e \; r_i  \right)   
+          = - \frac{1}{e_3}                     \;\partial_k \left(           A_e \; r_i  \right)            \\
+ v^* & = - \frac{1}{e_1\,e_3}\;             \partial_k \left( e_1 \, A_e \; r_j  \right)   
+          = - \frac{1}{e_3}                     \;\partial_k \left(           A_e \; r_j  \right)             \\
+w^* & =    \frac{1}{e_1\,e_2}\; \left\{   \partial_i  \left( e_2 \, A_e \; r_i  \right) 
+					              + \partial_j  \left( e_1 \, A_e \;r_j   \right) \right\}   \\
+\end{split}
+\end{equation}
+where $A_{e}$ is the eddy induced velocity coefficient, and $r_i$ and $r_j$ the 
+slopes between the iso-neutral and the geopotential surfaces.
+%%gm wrong: to be modified with 2 2D streamfunctions
+ In other words,
+the eddy induced velocity can be derived from a vector streamfuntion, $\phi$, which
+is given by $\phi = A_e\,\textbf{r}$ as $\textbf{U}^*  = \textbf{k} \times \nabla \phi$
+%%end gm
+
+A traditional way to implement this additional advection is to add it to the eulerian 
+velocity prior to compute the tracer advection. This allows us to take advantage of 
+all the advection schemes offered for the tracers (see \autoref{sec:TRA_adv}) and not just 
+a $2^{nd}$ order advection scheme. This is particularly useful for passive tracers 
+where \emph{positivity} of the advection scheme is of paramount importance. 
+% give here the expression using the triads. It is different from the one given in \autoref{eq:ldfeiv}
+% see just below a copy of this equation:
+%\begin{equation} \label{eq:ldfeiv}
+%\begin{split}
+% u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\
+% v^* & = \frac{1}{e_{1u}e_{3v}}\; \delta_k \left[e_{1v} \, A_{vw}^{eiv} \; \overline{r_{2w}}^{\,j+1/2} \right]\\
+%w^* & = \frac{1}{e_{1w}e_{2w}}\; \left\{ \delta_i \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right] + %\delta_j \left[e_{1v} \, A_{vw}^{eiv} \; \overline{r_{2w}}^{\,j+1/2} \right] \right\} \\
+%\end{split}
+%\end{equation}
+\begin{equation} \label{eq:eiv_vd}  
+\textbf{F}_{eiv}^T   \equiv   \left( \begin{aligned}                                
+ \sum_{\substack{i_p,\,k_p}} &
+ +{e_{2u}}_{i+1/2-i_p}^{k}                                  \ \ {A_{e}}_{i+1/2-i_p}^{k} 
+\ \ \ { _{i+1/2-i_p}^k \mathbb{R}_{i_p}^{k_p} }    \ \ \delta_{k+k_p}[T_{i+1/2-i_p}]      \\
+    \\
+ \sum_{\substack{i_p,\,k_p}} &
+ - {e_{2u}}_i^{k+1/2-k_p}                                      \ {A_{e}}_i^{k+1/2-k_p} 
+\ \ { _i^{k+1/2-k_p} \mathbb{R}_{i_p}^{k_p} }    \ \delta_{i+i_p}[T^{k+1/2-k_p}]    \\   
+\end{aligned}   \right)
+\end{equation}
+
+\citep{Griffies_JPO98} introduces another way to implement the eddy induced advection, 
+the so-called skew form. It is based on a transformation of the advective fluxes 
+using the non-divergent nature of the eddy induced velocity. 
+For example in the (\textbf{i},\textbf{k}) plane, the tracer advective fluxes can be 
+transformed as follows:
+\begin{flalign*}
+\begin{split}
+\textbf{F}_{eiv}^T = 
+\begin{pmatrix} 
+ 	        {e_{2}\,e_{3}\;  u^*} 	 	\\
+ 		{e_{1}\,e_{2}\; w^*}	 \\
+\end{pmatrix}   \;   T
+&=
+\begin{pmatrix} 
+ 	        { - \partial_k \left( e_{2} \, A_{e} \; r_i \right) \; T \;} 	 	\\
+ 		{+ \partial_i  \left( e_{2} \, A_{e} \; r_i \right) \; T \;}	 \\
+\end{pmatrix} 			\\
+&=			
+\begin{pmatrix} 
+ 	        { - \partial_k \left( e_{2} \, A_{e} \; r_i  \; T \right) \;}  \\
+ 		{+ \partial_i  \left( e_{2} \, A_{e} \; r_i  \; T \right) \;}	 \\
+\end{pmatrix} 			
+ + 
+\begin{pmatrix} 
+ 	        {+ e_{2} \, A_{e} \; r_i  \; \partial_k T}  \\
+ 		{ - e_{2} \, A_{e} \; r_i  \; \partial_i  T}	 \\
+\end{pmatrix} 	 
+\end{split}
+\end{flalign*}
+and since the eddy induces velocity field is no-divergent, we end up with the skew 
+form of the eddy induced advective fluxes:
+\begin{equation} \label{eq:eiv_skew_continuous}
+\textbf{F}_{eiv}^T = \begin{pmatrix} 
+ 	        {+ e_{2} \, A_{e} \; r_i  \; \partial_k T}   \\
+ 		{ - e_{2} \, A_{e} \; r_i  \; \partial_i  T}	 \\
+                                 \end{pmatrix}
+\end{equation}
+The tendency associated with eddy induced velocity is then simply the divergence 
+of the \autoref{eq:eiv_skew_continuous} fluxes. It naturally conserves the tracer 
+content, as it is expressed in flux form and, as the advective form, it preserve the 
+tracer variance. Another interesting property of \autoref{eq:eiv_skew_continuous} 
+form is that when $A=A_e$, a simplification occurs in the sum of the iso-neutral 
+diffusion and eddy induced velocity terms:
+\begin{flalign} \label{eq:eiv_skew+eiv_continuous}
+\textbf{F}_{iso}^T + \textbf{F}_{eiv}^T &= 
+\begin{pmatrix} 
+ 	        + \frac{e_2\,e_3\,}{e_1} A \;\partial_i T -  e_2 \, A \; r_i                              \;\partial_k T   \\
+ 		-  e_2 \, A_{e} \; r_i           \;\partial_i T + \frac{e_1\,e_2}{e_3} \, A \; r_i^2 \;\partial_k T   \\
+\end{pmatrix}
++
+\begin{pmatrix} 
+ 	        {+ e_{2} \, A_{e} \; r_i  \; \partial_k T}   \\
+ 		{ - e_{2} \, A_{e} \; r_i  \; \partial_i  T}	 \\
+\end{pmatrix}      \\
+&= \begin{pmatrix} 
+ 	        + \frac{e_2\,e_3\,}{e_1} A \;\partial_i T    \\
+ 		-  2\; e_2 \, A_{e} \; r_i      \;\partial_i T + \frac{e_1\,e_2}{e_3} \, A \; r_i^2 \;\partial_k T   \\
+\end{pmatrix}
+\end{flalign}
+The horizontal component reduces to the one use for an horizontal laplacian 
+operator and the vertical one keep the same complexity, but not more. This property
+has been used to reduce the computational time \citep{Griffies_JPO98}, but it is 
+not of practical use as usually $A \neq A_e$. Nevertheless this property can be used to 
+choose a discret form of  \autoref{eq:eiv_skew_continuous} which is consistent with the 
+iso-neutral operator \autoref{eq:Gf_operator}. Using the slopes \autoref{eq:Gf_slopes} 
+and defining $A_e$ at $T$-point($i.e.$ as $A$, the eddy diffusivity coefficient),
+the resulting discret form is given by:
+\begin{equation} \label{eq:eiv_skew}  
+\textbf{F}_{eiv}^T   \equiv   \frac{1}{4} \left( \begin{aligned}                                
+ \sum_{\substack{i_p,\,k_p}} &
+ +{e_{2u}}_{i+1/2-i_p}^{k}                                  \ \ {A_{e}}_{i+1/2-i_p}^{k} 
+\ \ \ { _{i+1/2-i_p}^k \mathbb{R}_{i_p}^{k_p} }    \ \ \delta_{k+k_p}[T_{i+1/2-i_p}]      \\
+    \\
+ \sum_{\substack{i_p,\,k_p}} &
+ - {e_{2u}}_i^{k+1/2-k_p}                                      \ {A_{e}}_i^{k+1/2-k_p} 
+\ \ { _i^{k+1/2-k_p} \mathbb{R}_{i_p}^{k_p} }    \ \delta_{i+i_p}[T^{k+1/2-k_p}]    \\   
+\end{aligned}   \right)
+\end{equation}
+Note that \autoref{eq:eiv_skew} is valid in $z$-coordinate with or without partial cells. 
+In $z^*$ or $s$-coordinate, the slope between the level and the geopotential surfaces 
+must be added to $\mathbb{R}$ for the discret form to be exact. 
+
+Such a choice of discretisation is consistent with the iso-neutral operator as it uses the 
+same definition for the slopes. It also ensures the conservation of the tracer variance 
+(see Appendix \autoref{apdx:eiv_skew}), $i.e.$ it does not include a diffusive component 
+but is a "pure" advection term.
+
+
+
+
+$\ $\newpage      %force an empty line
+% ================================================================
+% Discrete Invariants of the iso-neutral diffrusion 
+% ================================================================
+\subsection{Discrete invariants of the iso-neutral diffrusion}
+\label{subsec:Gf_operator}
+
+Demonstration of the decrease of the tracer variance in the (\textbf{i},\textbf{j}) plane. 
+
+This part will be moved in an Appendix.
+
+The continuous property to be demonstrated is :
+\begin{align*}
+\int_D  D_l^T \; T \;dv   \leq 0
+\end{align*}
+The discrete form of its left hand side is obtained using \autoref{eq:iso_flux}
+
+\begin{align*}
+&\int_D  D_l^T \; T \;dv \equiv  \sum_{i,k} \left\{ T \ D_l^T \ b_T \right\}    \\
+&\equiv + \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{  
+		\delta_{i} \left[{_{i+1/2-i_p}^k {\mathbb{F}_u }_{i_p}^{k_p}} \right] 
+	     + \delta_{k} \left[ {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}} \right]  \ T \right\}    \\
+&\equiv  - \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{  
+                {_{i+1/2-i_p}^k {\mathbb{F}_u }_{i_p}^{k_p}} \ \delta_{i+1/2} [T]
+             + {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}}  \ \delta_{k+1/2} [T]   \right\}      \\
+&\equiv -\sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{  
+	\frac{ _{i+1/2-i_p}^k \mathbb{T}_{i_p}^{k_p} (T) }{ {e_{1u}}_{\,i+1/2}^{\,k} }  \ \delta_{i+1/2} [T]
+ - { _i^{k+1/2-k_p} \mathbb{R}_{i_p}^{k_p} } \ \; 
+	\frac{ _i^{k+1/2-k_p} \mathbb{T}_{i_p}^{k_p} (T) }{ {e_{3w}}_{\,i}^{\,k+1/2}  } \ \delta_{k+1/2} [T]   
+	                                                                    \right\}      \\
+%
+\allowdisplaybreaks
+\intertext{ Expending the summation on $i_p$ and $k_p$, it becomes:}
+%
+&\equiv -\sum_{i,k}
+\begin{Bmatrix}  
+&\ \ \Bigl(  { _{i+1}^{k} \mathbb{T}_{-1/2}^{-1/2} (T) } 
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_{i}^{k+1} \mathbb{R}_{-1/2}^{-1/2}} 
+&      {_{i}^{k+1} \mathbb{T}_{-1/2}^{-1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)
+& \\
+&+\Bigl( \ \;\; { _i^k \mathbb{T}_{+1/2}^{-1/2} (T) }  
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_i^{k+1} \mathbb{R}_{+1/2}^{-1/2}}
+& { _i^{k+1} \mathbb{T}_{+1/2}^{-1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}      \Bigr)
+& \\
+&+\Bigl(  { _{i+1}^{k} \mathbb{T}_{-1/2}^{+1/2} (T) } 
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ \ \;\;{_{i}^{k} \mathbb{R}_{-1/2}^{+1/2}} 
+&      \ \;\;{_{i}^{k} \mathbb{T}_{-1/2}^{+1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)
+& \\
+&+\Bigl( \ \;\; { _{i}^{k} \mathbb{T}_{+1/2}^{+1/2} (T) } 
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ \ \;\;{_{i}^{k} \mathbb{R}_{+1/2}^{+1/2}} 
+&      \ \;\;{_{i}^{k} \mathbb{T}_{+1/2}^{+1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)   \\
+\end{Bmatrix}
+%
+\allowdisplaybreaks
+\intertext{The summation is done over all $i$ and $k$ indices, it is therefore possible to introduce a shift of $-1$ either in $i$ or $k$ direction in order to regroup all the terms of the summation by triad at a ($i$,$k$) point. In other words, we regroup all the terms in the neighbourhood  that contain a triad at the same ($i$,$k$) indices. It becomes: }
+%
+&\equiv -\sum_{i,k}
+\begin{Bmatrix}  
+&\ \ \Bigl(  {_i^k \mathbb{T}_{-1/2}^{-1/2} (T) } 
+&\frac{ \delta_{i -1/2} [T] }{{e_{1u} }_{\,i-1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{-1/2}^{-1/2}} 
+&      {_i^k \mathbb{T}_{-1/2}^{-1/2} (T) }   
+&\frac{ \delta_{k-1/2} [T] }{{e_{3w}}_{\,i}^{\,k-1/2}}     \Bigr)
+& \\
+&+\Bigl(  { _i^k \mathbb{T}_{+1/2}^{-1/2} (T) }  
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{+1/2}^{-1/2}}
+&      { _i^k \mathbb{T}_{+1/2}^{-1/2} (T) }   
+&\frac{ \delta_{k-1/2} [T] }{{e_{3w}}_{\,i}^{\,k-1/2}}      \Bigr)
+& \\
+&+\Bigl(  {_i^k \mathbb{T}_{-1/2}^{+1/2} (T) } 
+&\frac{ \delta_{i -1/2} [T] }{{e_{1u} }_{\,i-1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{-1/2}^{+1/2}} 
+&      {_i^k \mathbb{T}_{-1/2}^{+1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)
+& \\
+&+\Bigl( { _i^k \mathbb{T}_{+1/2}^{+1/2} (T) } 
+&\frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{+1/2}^{+1/2}} 
+&      {_i^k \mathbb{T}_{+1/2}^{+1/2} (T) }   
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)   \\
+\end{Bmatrix}   \\
+%
+\allowdisplaybreaks
+\intertext{Then outing in factor the triad in each of the four terms of the summation and substituting the triads by their expression given in \autoref{eq:Gf_triads}. It becomes: }
+%
+&\equiv -\sum_{i,k}
+\begin{Bmatrix}  
+&\ \ \Bigl(  \frac{ \delta_{i -1/2} [T] }{{e_{1u} }_{\,i-1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{-1/2}^{-1/2}} 
+&\frac{ \delta_{k-1/2} [T] }{{e_{3w}}_{\,i}^{\,k-1/2}}     \Bigr)^2
+& \frac{1}{4} \ {b_u}_{\,i-1/2}^{\,k}  \  A_i^k
+& \\
+&+\Bigl(  \frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{+1/2}^{-1/2}}
+&\frac{ \delta_{k-1/2} [T] }{{e_{3w}}_{\,i}^{\,k-1/2}}      \Bigr)^2
+& \frac{1}{4} \ {b_u}_{\,i+1/2}^{\,k}  \  A_i^k
+& \\
+&+\Bigl(  \frac{ \delta_{i -1/2} [T] }{{e_{1u} }_{\,i-1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{-1/2}^{+1/2}} 
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)^2
+& \frac{1}{4} \ {b_u}_{\,i-1/2}^{\,k}  \  A_i^k
+& \\
+&+\Bigl( \frac{ \delta_{i +1/2} [T] }{{e_{1u} }_{\,i+1/2}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{+1/2}^{+1/2}} 
+&\frac{ \delta_{k+1/2} [T] }{{e_{3w}}_{\,i}^{\,k+1/2}}     \Bigr)^2
+& \frac{1}{4} \ {b_u}_{\,i+1/2}^{\,k}  \  A_i^k      \\
+\end{Bmatrix}   \\
+& \\
+%
+&\equiv - \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{  
+\begin{matrix}  
+&\Bigl( \frac{ \delta_{i +i_p} [T] }{{e_{1u} }_{\,i+i_p}^{\,k}} 
+& -\ \ {_i^k \mathbb{R}_{i_p}^{k_p}} 
+&\frac{ \delta_{k+k_p} [T] }{{e_{3w}}_{\,i}^{\,k+k_p}}     \Bigr)^2
+& \frac{1}{4} \ {b_u}_{\,i+i_p}^{\,k}  \  A_i^k   \ \ 
+\end{matrix}
+ \right\}   
+\quad   \leq 0
+\end{align*} 
+The last inequality is obviously obtained as we succeed in obtaining a negative summation of square quantities.
+
+Note that, if instead of multiplying $D_l^T$ by $T$, we were using another tracer field, let say $S$, then the previous demonstration would have let to:
+\begin{align*}
+\int_D  S \; D_l^T  \;dv &\equiv  \sum_{i,k} \left\{ S \ D_l^T \ b_T \right\}    \\
+&\equiv - \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{  
+\left( \frac{ \delta_{i +i_p} [S] }{{e_{1u} }_{\,i+i_p}^{\,k}} 
+ - {_i^k \mathbb{R}_{i_p}^{k_p}} 
+\frac{ \delta_{k+k_p} [S] }{{e_{3w}}_{\,i}^{\,k+k_p}}     \right)  \right.    
+\\   & \qquad \qquad \qquad \ \left.
+\left( \frac{ \delta_{i +i_p} [T] }{{e_{1u} }_{\,i+i_p}^{\,k}} 
+ - {_i^k \mathbb{R}_{i_p}^{k_p}} 
+\frac{ \delta_{k+k_p} [T] }{{e_{3w}}_{\,i}^{\,k+k_p}}     \right) 
+ \frac{1}{4} \ {b_u}_{\,i+i_p}^{\,k}  \  A_i^k   \
+ \right\}   
+%
+\allowdisplaybreaks
+\intertext{which, by applying the same operation as before but in reverse order, leads to: }
+%
+&\equiv  \sum_{i,k} \left\{ D_l^S \ T \ b_T \right\}   
+\end{align*} 
+This means that the iso-neutral operator is self-adjoint. There is no need to develop a specific to obtain it.
+
+
+
+$\ $\newpage      %force an empty line
+% ================================================================
+% Discrete Invariants of the skew flux formulation
+% ================================================================
+\subsection{Discrete invariants of the skew flux formulation}
+\label{subsec:eiv_skew}
+
+
+Demonstration for the conservation of the tracer variance in the (\textbf{i},\textbf{j}) plane. 
+
+This have to be moved in an Appendix.
+
+The continuous property to be demonstrated is :
+\begin{align*}
+\int_D \nabla \cdot \textbf{F}_{eiv}(T) \; T \;dv  \equiv 0
+\end{align*}
+The discrete form of its left hand side is obtained using \autoref{eq:eiv_skew}
+\begin{align*}
+ \sum\limits_{i,k} \sum_{\substack{i_p,\,k_p}}  \Biggl\{   \;\;
+ \delta_i  &\left[                                                    
+{e_{2u}}_{i+i_p+1/2}^{k}                                  \;\ \ {A_{e}}_{i+i_p+1/2}^{k} 
+\ \ \ { _{i+i_p+1/2}^k \mathbb{R}_{-i_p}^{k_p} }   \quad \delta_{k+k_p}[T_{i+i_p+1/2}]         
+   \right] \; T_i^k      \\
+- \delta_k &\left[ 
+{e_{2u}}_i^{k+k_p+1/2}                                     \ \ {A_{e}}_i^{k+k_p+1/2} 
+\ \ { _i^{k+k_p+1/2} \mathbb{R}_{i_p}^{-k_p} }   \ \ \delta_{i+i_p}[T^{k+k_p+1/2}]   
+   \right] \; T_i^k      \         \Biggr\}   
+\end{align*}
+apply the adjoint of delta operator, it becomes
+\begin{align*}
+ \sum\limits_{i,k} \sum_{\substack{i_p,\,k_p}}  \Biggl\{   \;\;
+  &\left(                                                    
+{e_{2u}}_{i+i_p+1/2}^{k}                                  \;\ \ {A_{e}}_{i+i_p+1/2}^{k} 
+\ \ \ { _{i+i_p+1/2}^k \mathbb{R}_{-i_p}^{k_p} }   \quad \delta_{k+k_p}[T_{i+i_p+1/2}]         
+   \right) \; \delta_{i+1/2}[T^{k}]      \\
+- &\left( 
+{e_{2u}}_i^{k+k_p+1/2}                                     \ \ {A_{e}}_i^{k+k_p+1/2} 
+\ \ { _i^{k+k_p+1/2} \mathbb{R}_{i_p}^{-k_p} }   \ \ \delta_{i+i_p}[T^{k+k_p+1/2}]   
+     \right) \; \delta_{k+1/2}[T_{i}]       \         \Biggr\}       
+\end{align*}
+Expending the summation on $i_p$ and $k_p$, it becomes:
+\begin{align*}
+ \begin{matrix}  
+&\sum\limits_{i,k}   \Bigl\{ 
+  &+{e_{2u}}_{i+1}^{k}                             &{A_{e}}_{i+1    }^{k} 
+  &\ {_{i+1}^k \mathbb{R}_{- 1/2}^{-1/2}} &\delta_{k-1/2}[T_{i+1}]    &\delta_{i+1/2}[T^{k}]   &\\
+&&+{e_{2u}}_i^{k\ \ \ \:}                            &{A_{e}}_{i}^{k\ \ \ \:}      
+  &\ {\ \ \;_i^k \mathbb{R}_{+1/2}^{-1/2}}  &\delta_{k-1/2}[T_{i\ \ \ \;}]  &\delta_{i+1/2}[T^{k}] &\\
+&&+{e_{2u}}_{i+1}^{k}                             &{A_{e}}_{i+1    }^{k} 
+  &\ {_{i+1}^k \mathbb{R}_{- 1/2}^{+1/2}} &\delta_{k+1/2}[T_{i+1}]     &\delta_{i+1/2}[T^{k}] &\\
+&&+{e_{2u}}_i^{k\ \ \ \:}                            &{A_{e}}_{i}^{k\ \ \ \:}       
+    &\ {\ \ \;_i^k \mathbb{R}_{+1/2}^{+1/2}} &\delta_{k+1/2}[T_{i\ \ \ \;}] &\delta_{i+1/2}[T^{k}] &\\
+%
+&&-{e_{2u}}_i^{k+1}                                &{A_{e}}_i^{k+1} 
+  &{_i^{k+1} \mathbb{R}_{-1/2}^{- 1/2}}   &\delta_{i-1/2}[T^{k+1}]      &\delta_{k+1/2}[T_{i}] &\\   
+&&-{e_{2u}}_i^{k\ \ \ \:}                             &{A_{e}}_i^{k\ \ \ \:} 
+  &{\ \ \;_i^k  \mathbb{R}_{-1/2}^{+1/2}}   &\delta_{i-1/2}[T^{k\ \ \ \:}]  &\delta_{k+1/2}[T_{i}] &\\
+&&-{e_{2u}}_i^{k+1    }                             &{A_{e}}_i^{k+1} 
+  &{_i^{k+1} \mathbb{R}_{+1/2}^{- 1/2}}   &\delta_{i+1/2}[T^{k+1}]      &\delta_{k+1/2}[T_{i}] &\\   
+&&-{e_{2u}}_i^{k\ \ \ \:}                             &{A_{e}}_i^{k\ \ \ \:} 
+  &{\ \ \;_i^k  \mathbb{R}_{+1/2}^{+1/2}}   &\delta_{i+1/2}[T^{k\ \ \ \:}]  &\delta_{k+1/2}[T_{i}] 
+&\Bigr\}  \\
+\end{matrix}   
+\end{align*}
+The two terms associated with the triad ${_i^k \mathbb{R}_{+1/2}^{+1/2}}$ are the 
+same but of opposite signs, they cancel out. 
+Exactly the same thing occurs for the triad ${_i^k \mathbb{R}_{-1/2}^{-1/2}}$. 
+The two terms associated with the triad ${_i^k \mathbb{R}_{+1/2}^{-1/2}}$ are the 
+same but both of opposite signs and shifted by 1 in $k$ direction. When summing over $k$ 
+they cancel out with the neighbouring grid points. 
+Exactly the same thing occurs for the triad ${_i^k \mathbb{R}_{-1/2}^{+1/2}}$ in the 
+$i$ direction. Therefore the sum over the domain is zero, $i.e.$ the variance of the 
+tracer is preserved by the discretisation of the skew fluxes.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_iso.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_iso.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/annex_iso.tex	(revision 10321)
@@ -0,0 +1,1189 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Iso-neutral diffusion :
+% ================================================================
+\chapter[Iso-Neutral Diffusion and Eddy Advection using Triads]
+			{\texorpdfstring{Iso-Neutral Diffusion and\\ Eddy Advection using Triads}{Iso-Neutral Diffusion and Eddy Advection using Triads}}
+\label{apdx:triad}
+\minitoc
+\pagebreak
+\section{Choice of \protect\ngn{namtra\_ldf} namelist parameters}
+%-----------------------------------------nam_traldf------------------------------------------------------
+
+\nlst{namtra_ldf}
+%---------------------------------------------------------------------------------------------------------
+
+Two scheme are available to perform the iso-neutral diffusion. 
+If the namelist logical \np{ln\_traldf\_triad} is set true, 
+\NEMO updates both active and passive tracers using the Griffies triad representation 
+of iso-neutral diffusion and the eddy-induced advective skew (GM) fluxes. 
+If the namelist logical \np{ln\_traldf\_iso} is set true, 
+the filtered version of Cox's original scheme (the Standard scheme) is employed (\autoref{sec:LDF_slp}). 
+In the present implementation of the Griffies scheme, 
+the advective skew fluxes are implemented even if \np{ln\_traldf\_eiv} is false.
+
+Values of iso-neutral diffusivity and GM coefficient are set as
+described in \autoref{sec:LDF_coef}. Note that when GM fluxes are used, 
+the eddy-advective (GM) velocities are output for diagnostic purposes using xIOS, 
+even though the eddy advection is accomplished by means of the skew fluxes.
+
+
+The options specific to the Griffies scheme include:
+\begin{description}[font=\normalfont]
+\item[\np{ln\_triad\_iso}] See \autoref{sec:taper}. If this is set false (the default), then
+  `iso-neutral' mixing is accomplished within the surface mixed-layer
+  along slopes linearly decreasing with depth from the value immediately below
+  the mixed-layer to zero (flat) at the surface (\autoref{sec:lintaper}). 
+  This is the same treatment as used in the default implementation \autoref{subsec:LDF_slp_iso}; \autoref{fig:eiv_slp}.  
+  Where \np{ln\_triad\_iso} is set true, the vertical skew flux is further reduced 
+  to ensure no vertical buoyancy flux, giving an almost pure
+  horizontal diffusive tracer flux within the mixed layer. This is similar to
+  the tapering suggested by \citet{Gerdes1991}. See \autoref{subsec:Gerdes-taper}
+\item[\np{ln\_botmix\_triad}] See \autoref{sec:iso_bdry}. 
+  If this is set false (the default) then the lateral diffusive fluxes
+  associated with triads partly masked by topography are neglected. 
+  If it is set true, however, then these lateral diffusive fluxes are applied, 
+  giving smoother bottom tracer fields at the cost of introducing diapycnal mixing.
+\item[\np{rn\_sw\_triad}]  blah blah to be added....
+\end{description}
+The options shared with the Standard scheme include:
+\begin{description}[font=\normalfont]
+\item[\np{ln\_traldf\_msc}]   blah blah to be added
+\item[\np{rn\_slpmax}]  blah blah to be added
+\end{description}
+
+\section{Triad formulation of iso-neutral diffusion}
+\label{sec:iso}
+We have implemented into \NEMO a scheme inspired by \citet{Griffies_al_JPO98}, 
+but formulated within the \NEMO framework, using scale factors rather than grid-sizes.
+
+\subsection{Iso-neutral diffusion operator}
+The iso-neutral second order tracer diffusive operator for small
+angles between iso-neutral surfaces and geopotentials is given by
+\autoref{eq:iso_tensor_1}:
+\begin{subequations} \label{eq:iso_tensor_1}
+  \begin{equation}
+    D^{lT}=-\Div\vect{f}^{lT}\equiv
+    -\frac{1}{e_1e_2e_3}\left[\pd{i}\left (f_1^{lT}e_2e_3\right) +
+      \pd{j}\left (f_2^{lT}e_2e_3\right) + \pd{k}\left (f_3^{lT}e_1e_2\right)\right],
+  \end{equation}
+  where the diffusive flux per unit area of physical space
+  \begin{equation}
+    \vect{f}^{lT}=-\Alt\Re\cdot\grad T,
+  \end{equation}
+  \begin{equation}
+    \label{eq:iso_tensor_2}
+    \mbox{with}\quad \;\;\Re =
+    \begin{pmatrix}
+       1   &  0   & -r_1           \mystrut \\
+       0   &  1   & -r_2           \mystrut \\
+      -r_1 & -r_2 &  r_1 ^2+r_2 ^2 \mystrut
+    \end{pmatrix}
+    \quad \text{and} \quad\grad T=
+    \begin{pmatrix}
+      \frac{1}{e_1} \pd[T]{i} \mystrut \\
+      \frac{1}{e_2} \pd[T]{j} \mystrut \\
+      \frac{1}{e_3} \pd[T]{k} \mystrut
+    \end{pmatrix}.
+  \end{equation}
+\end{subequations}
+% \left( {{\begin{array}{*{20}c}
+%  1 \hfill & 0 \hfill & {-r_1 } \hfill \\
+%  0 \hfill & 1 \hfill & {-r_2 } \hfill \\
+%  {-r_1 } \hfill & {-r_2 } \hfill & {r_1 ^2+r_2 ^2} \hfill \\
+% \end{array} }} \right)
+ Here \autoref{eq:PE_iso_slopes} 
+\begin{align*}
+  r_1 &=-\frac{e_3 }{e_1 } \left( \frac{\partial \rho }{\partial i}
+  \right)
+  \left( {\frac{\partial \rho }{\partial k}} \right)^{-1} \\
+  &=-\frac{e_3 }{e_1 } \left( -\alpha\frac{\partial T }{\partial i} +
+    \beta\frac{\partial S }{\partial i} \right) \left(
+    -\alpha\frac{\partial T }{\partial k} + \beta\frac{\partial S
+    }{\partial k} \right)^{-1}
+\end{align*}
+is the $i$-component of the slope of the iso-neutral surface relative to the computational
+surface, and $r_2$ is the $j$-component.
+
+We will find it useful to consider the fluxes per unit area in $i,j,k$
+space; we write
+\begin{equation}
+  \label{eq:Fijk}
+  \vect{F}_{\mathrm{iso}}=\left(f_1^{lT}e_2e_3, f_2^{lT}e_1e_3, f_3^{lT}e_1e_2\right).
+\end{equation}
+Additionally, we will sometimes write the contributions towards the
+fluxes $\vect{f}$ and $\vect{F}_{\mathrm{iso}}$ from the component
+$R_{ij}$ of $\Re$ as $f_{ij}$, $F_{\mathrm{iso}\: ij}$, with
+$f_{ij}=R_{ij}e_i^{-1}\partial T/\partial x_i$ (no summation) etc.
+
+The off-diagonal terms of the small angle diffusion tensor
+\autoref{eq:iso_tensor_1}, \autoref{eq:iso_tensor_2} produce skew-fluxes along the
+$i$- and $j$-directions resulting from the vertical tracer gradient:
+\begin{align}
+  \label{eq:i13c}
+  f_{13}=&+\Alt r_1\frac{1}{e_3}\frac{\partial T}{\partial k},\qquad f_{23}=+\Alt r_2\frac{1}{e_3}\frac{\partial T}{\partial k}\\
+\intertext{and in the k-direction resulting from the lateral tracer gradients}
+  \label{eq:i31c}
+ f_{31}+f_{32}=& \Alt r_1\frac{1}{e_1}\frac{\partial T}{\partial i}+\Alt r_2\frac{1}{e_1}\frac{\partial T}{\partial i}
+\end{align}
+
+The vertical diffusive flux associated with the $_{33}$
+component of the small angle diffusion tensor is
+\begin{equation}
+  \label{eq:i33c}
+  f_{33}=-\Alt(r_1^2 +r_2^2) \frac{1}{e_3}\frac{\partial T}{\partial k}.
+\end{equation}
+
+Since there are no cross terms involving $r_1$ and $r_2$ in the above, we can
+consider the iso-neutral diffusive fluxes separately in the $i$-$k$ and $j$-$k$
+planes, just adding together the vertical components from each
+plane. The following description will describe the fluxes on the $i$-$k$
+plane.
+
+There is no natural discretization for the $i$-component of the
+skew-flux, \autoref{eq:i13c}, as
+although it must be evaluated at $u$-points, it involves vertical
+gradients (both for the tracer and the slope $r_1$), defined at
+$w$-points. Similarly, the vertical skew flux, \autoref{eq:i31c}, is evaluated at
+$w$-points but involves horizontal gradients defined at $u$-points.
+
+\subsection{Standard discretization}
+The straightforward approach to discretize the lateral skew flux
+\autoref{eq:i13c} from tracer cell $i,k$ to $i+1,k$, introduced in 1995
+into OPA, \autoref{eq:tra_ldf_iso}, is to calculate a mean vertical
+gradient at the $u$-point from the average of the four surrounding
+vertical tracer gradients, and multiply this by a mean slope at the
+$u$-point, calculated from the averaged surrounding vertical density
+gradients. The total area-integrated skew-flux (flux per unit area in
+$ijk$ space) from tracer cell $i,k$
+to $i+1,k$, noting that the $e_{{3}_{i+1/2}^k}$ in the area
+$e{_{3}}_{i+1/2}^k{e_{2}}_{i+1/2}i^k$ at the $u$-point cancels out with
+the $1/{e_{3}}_{i+1/2}^k$ associated with the vertical tracer
+gradient, is then \autoref{eq:tra_ldf_iso}
+\begin{equation*}
+  \left(F_u^{13} \right)_{i+\hhalf}^k = \Alts_{i+\hhalf}^k
+  {e_{2}}_{i+1/2}^k \overline{\overline
+    r_1} ^{\,i,k}\,\overline{\overline{\delta_k T}}^{\,i,k},
+\end{equation*}
+where
+\begin{equation*}
+  \overline{\overline
+   r_1} ^{\,i,k} = -\frac{{e_{3u}}_{i+1/2}^k}{{e_{1u}}_{i+1/2}^k}
+  \frac{\delta_{i+1/2} [\rho]}{\overline{\overline{\delta_k \rho}}^{\,i,k}},
+\end{equation*}
+and here and in the following we drop the $^{lT}$ superscript from
+$\Alt$ for simplicity.
+Unfortunately the resulting combination $\overline{\overline{\delta_k
+    \bullet}}^{\,i,k}$ of a $k$ average and a $k$ difference %of the tracer
+reduces to $\bullet_{k+1}-\bullet_{k-1}$, so two-grid-point oscillations are
+invisible to this discretization of the iso-neutral operator. These
+\emph{computational modes} will not be damped by this operator, and
+may even possibly be amplified by it.  Consequently, applying this
+operator to a tracer does not guarantee the decrease of its
+global-average variance. To correct this, we introduced a smoothing of
+the slopes of the iso-neutral surfaces (see \autoref{chap:LDF}). This
+technique works for $T$ and $S$ in so far as they are active tracers
+($i.e.$ they enter the computation of density), but it does not work
+for a passive tracer.
+
+\subsection{Expression of the skew-flux in terms of triad slopes}
+\citep{Griffies_al_JPO98} introduce a different discretization of the
+off-diagonal terms that nicely solves the problem.
+% Instead of multiplying the mean slope calculated at the $u$-point by
+% the mean vertical gradient at the $u$-point,
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[tb] \begin{center}
+    \includegraphics[width=1.05\textwidth]{Fig_GRIFF_triad_fluxes}
+    \caption{ \protect\label{fig:ISO_triad}
+      (a) Arrangement of triads $S_i$ and tracer gradients to
+           give lateral tracer flux from box $i,k$ to $i+1,k$
+      (b) Triads $S'_i$ and tracer gradients to give vertical tracer flux from
+            box $i,k$ to $i,k+1$.}
+ \end{center} \end{figure}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+They get the skew flux from the products of the vertical gradients at
+each $w$-point surrounding the $u$-point with the corresponding `triad'
+slope calculated from the lateral density gradient across the $u$-point
+divided by the vertical density gradient at the same $w$-point as the
+tracer gradient. See \autoref{fig:ISO_triad}a, where the thick lines
+denote the tracer gradients, and the thin lines the corresponding
+triads, with slopes $s_1, \dotsc s_4$. The total area-integrated
+skew-flux from tracer cell $i,k$ to $i+1,k$
+\begin{multline}
+  \label{eq:i13}
+  \left( F_u^{13}  \right)_{i+\frac{1}{2}}^k = \Alts_{i+1}^k a_1 s_1
+  \delta _{k+\frac{1}{2}} \left[ T^{i+1}
+  \right]/e_{{3w}_{i+1}}^{k+\frac{1}{2}}  + \Alts _i^k a_2 s_2 \delta
+  _{k+\frac{1}{2}} \left[ T^i
+  \right]/e_{{3w}_{i+1}}^{k+\frac{1}{2}} \\
+   +\Alts _{i+1}^k a_3 s_3 \delta _{k-\frac{1}{2}} \left[ T^{i+1}
+  \right]/e_{{3w}_{i+1}}^{k+\frac{1}{2}}  +\Alts _i^k a_4 s_4 \delta
+  _{k-\frac{1}{2}} \left[ T^i \right]/e_{{3w}_{i+1}}^{k+\frac{1}{2}},
+\end{multline}
+where the contributions of the triad fluxes are weighted by areas
+$a_1, \dotsc a_4$, and $\Alts$ is now defined at the tracer points
+rather than the $u$-points. This discretization gives a much closer
+stencil, and disallows the two-point computational modes.
+
+ The vertical skew flux \autoref{eq:i31c} from tracer cell $i,k$ to $i,k+1$ at the
+$w$-point $i,k+\hhalf$ is constructed similarly (\autoref{fig:ISO_triad}b)
+by multiplying lateral tracer gradients from each of the four
+surrounding $u$-points by the appropriate triad slope:
+\begin{multline}
+  \label{eq:i31}
+  \left( F_w^{31} \right) _i ^{k+\frac{1}{2}} =  \Alts_i^{k+1} a_{1}'
+  s_{1}' \delta _{i-\frac{1}{2}} \left[ T^{k+1} \right]/{e_{3u}}_{i-\frac{1}{2}}^{k+1}
+   +\Alts_i^{k+1} a_{2}' s_{2}' \delta _{i+\frac{1}{2}} \left[ T^{k+1} \right]/{e_{3u}}_{i+\frac{1}{2}}^{k+1}\\
+  + \Alts_i^k a_{3}' s_{3}' \delta _{i-\frac{1}{2}} \left[ T^k\right]/{e_{3u}}_{i-\frac{1}{2}}^k
+  +\Alts_i^k a_{4}' s_{4}' \delta _{i+\frac{1}{2}} \left[ T^k \right]/{e_{3u}}_{i+\frac{1}{2}}^k.
+\end{multline}
+
+We notate the triad slopes $s_i$ and $s'_i$ in terms of the `anchor point' $i,k$
+(appearing in both the vertical and lateral gradient), and the $u$- and
+$w$-points $(i+i_p,k)$, $(i,k+k_p)$ at the centres of the `arms' of the
+triad as follows (see also \autoref{fig:ISO_triad}):
+\begin{equation}
+  \label{eq:R}
+  _i^k \mathbb{R}_{i_p}^{k_p}
+  =-\frac{ {e_{3w}}_{\,i}^{\,k+k_p}} { {e_{1u}}_{\,i+i_p}^{\,k}}
+  \
+  \frac
+  { \alpha_i^k  \ \delta_{i+i_p}[T^k] - \beta_i^k \ \delta_{i+i_p}[S^k] }
+  { \alpha_i^k  \ \delta_{k+k_p}[T^i] - \beta_i^k \ \delta_{k+k_p}[S^i] }.
+\end{equation}
+In calculating the slopes of the local neutral surfaces, 
+the expansion coefficients $\alpha$ and $\beta$ are evaluated at the anchor points of the triad, 
+while the metrics are calculated at the $u$- and $w$-points on the arms.
+
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[tb] \begin{center}
+    \includegraphics[width=0.80\textwidth]{Fig_GRIFF_qcells}
+    \caption{   \protect\label{fig:qcells}
+    Triad notation for quarter cells. $T$-cells are inside
+      boxes, while the  $i+\half,k$ $u$-cell is shaded in green and the
+      $i,k+\half$ $w$-cell is shaded in pink.}
+  \end{center} \end{figure}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Each triad $\{_i^{k}\:_{i_p}^{k_p}\}$ is associated (\autoref{fig:qcells}) with the quarter
+cell that is the intersection of the $i,k$ $T$-cell, the $i+i_p,k$ $u$-cell and the $i,k+k_p$ $w$-cell. 
+Expressing the slopes $s_i$ and $s'_i$ in \autoref{eq:i13} and \autoref{eq:i31} in this notation, 
+we have $e.g.$ \ $s_1=s'_1={\:}_i^k \mathbb{R}_{1/2}^{1/2}$. 
+Each triad slope $_i^k\mathbb{R}_{i_p}^{k_p}$ is used once (as an $s$) 
+to calculate the lateral flux along its $u$-arm, at $(i+i_p,k)$, 
+and then again as an $s'$ to calculate the vertical flux along its $w$-arm at $(i,k+k_p)$. 
+Each vertical area $a_i$ used to calculate the lateral flux and horizontal area $a'_i$ used 
+to calculate the vertical flux can also be identified as the area across the $u$- and $w$-arms 
+of a unique triad, and we notate these areas, similarly to the triad slopes, 
+as $_i^k{\mathbb{A}_u}_{i_p}^{k_p}$, $_i^k{\mathbb{A}_w}_{i_p}^{k_p}$, 
+where $e.g.$ in \autoref{eq:i13} $a_{1}={\:}_i^k{\mathbb{A}_u}_{1/2}^{1/2}$, 
+and in \autoref{eq:i31} $a'_{1}={\:}_i^k{\mathbb{A}_w}_{1/2}^{1/2}$.
+
+\subsection{Full triad fluxes}
+A key property of iso-neutral diffusion is that it should not affect
+the (locally referenced) density. In particular there should be no
+lateral or vertical density flux. The lateral density flux disappears so long as the
+area-integrated lateral diffusive flux from tracer cell $i,k$ to
+$i+1,k$ coming from the $_{11}$ term of the diffusion tensor takes the
+form
+\begin{equation}
+  \label{eq:i11}
+  \left( F_u^{11} \right) _{i+\frac{1}{2}} ^{k} =
+  - \left( \Alts_i^{k+1} a_{1} + \Alts_i^{k+1} a_{2} + \Alts_i^k
+    a_{3} + \Alts_i^k a_{4} \right)
+  \frac{\delta _{i+1/2} \left[ T^k\right]}{{e_{1u}}_{\,i+1/2}^{\,k}},
+\end{equation}
+where the areas $a_i$ are as in \autoref{eq:i13}. In this case,
+separating the total lateral flux, the sum of \autoref{eq:i13} and
+\autoref{eq:i11}, into triad components, a lateral tracer
+flux
+\begin{equation}
+  \label{eq:latflux-triad}
+  _i^k {\mathbb{F}_u}_{i_p}^{k_p} (T) = - \Alts_i^k{ \:}_i^k{\mathbb{A}_u}_{i_p}^{k_p}
+  \left(
+    \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -\ {_i^k\mathbb{R}_{i_p}^{k_p}} \
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right)
+\end{equation}
+can be identified with each triad. Then, because the
+same metric factors ${e_{3w}}_{\,i}^{\,k+k_p}$ and
+${e_{1u}}_{\,i+i_p}^{\,k}$ are employed for both the density gradients
+in $ _i^k \mathbb{R}_{i_p}^{k_p}$ and the tracer gradients, the lateral
+density flux associated with each triad separately disappears.
+\begin{equation}
+  \label{eq:latflux-rho}
+  {\mathbb{F}_u}_{i_p}^{k_p} (\rho)=-\alpha _i^k {\:}_i^k {\mathbb{F}_u}_{i_p}^{k_p} (T) + \beta_i^k {\:}_i^k {\mathbb{F}_u}_{i_p}^{k_p} (S)=0
+\end{equation}
+Thus the total flux $\left( F_u^{31} \right) ^i _{i,k+\frac{1}{2}} +
+\left( F_u^{11} \right) ^i _{i,k+\frac{1}{2}}$ from tracer cell $i,k$
+to $i+1,k$ must also vanish since it is a sum of four such triad fluxes.
+
+The squared slope $r_1^2$ in the expression \autoref{eq:i33c} for the
+$_{33}$ component is also expressed in terms of area-weighted
+squared triad slopes, so the area-integrated vertical flux from tracer
+cell $i,k$ to $i,k+1$ resulting from the $r_1^2$ term is
+\begin{equation}
+  \label{eq:i33}
+  \left( F_w^{33} \right) _i^{k+\frac{1}{2}} =
+    - \left( \Alts_i^{k+1} a_{1}' s_{1}'^2
+    + \Alts_i^{k+1} a_{2}' s_{2}'^2
+    + \Alts_i^k a_{3}' s_{3}'^2
+    + \Alts_i^k a_{4}' s_{4}'^2 \right)\delta_{k+\frac{1}{2}} \left[ T^{i+1} \right],
+\end{equation}
+where the areas $a'$ and slopes $s'$ are the same as in
+\autoref{eq:i31}.
+Then, separating the total vertical flux, the sum of \autoref{eq:i31} and
+\autoref{eq:i33}, into triad components,  a vertical flux
+\begin{align}
+  \label{eq:vertflux-triad}
+  _i^k {\mathbb{F}_w}_{i_p}^{k_p} (T)
+  &= \Alts_i^k{\: }_i^k{\mathbb{A}_w}_{i_p}^{k_p}
+  \left(
+    {_i^k\mathbb{R}_{i_p}^{k_p}}\frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -\ \left({_i^k\mathbb{R}_{i_p}^{k_p}}\right)^2 \
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right) \\
+  &= - \left(\left.{ }_i^k{\mathbb{A}_w}_{i_p}^{k_p}\right/{ }_i^k{\mathbb{A}_u}_{i_p}^{k_p}\right)
+   {_i^k\mathbb{R}_{i_p}^{k_p}}{\: }_i^k{\mathbb{F}_u}_{i_p}^{k_p} (T) \label{eq:vertflux-triad2}
+\end{align}
+may be associated with each triad. Each vertical density flux $_i^k {\mathbb{F}_w}_{i_p}^{k_p} (\rho)$
+associated with a triad then separately disappears (because the
+lateral flux $_i^k{\mathbb{F}_u}_{i_p}^{k_p} (\rho)$
+disappears). Consequently the total vertical density flux $\left( F_w^{31} \right)_i ^{k+\frac{1}{2}} +
+\left( F_w^{33} \right)_i^{k+\frac{1}{2}}$ from tracer cell $i,k$
+to $i,k+1$ must also vanish since it is a sum of four such triad
+fluxes.
+
+We can explicitly identify (\autoref{fig:qcells}) the triads associated with the $s_i$, $a_i$, and $s'_i$, $a'_i$ used in the definition of
+the $u$-fluxes and $w$-fluxes in
+\autoref{eq:i31}, \autoref{eq:i13}, \autoref{eq:i11} \autoref{eq:i33} and
+\autoref{fig:ISO_triad} to  write out the iso-neutral fluxes at $u$- and
+$w$-points as sums of the triad fluxes that cross the $u$- and $w$-faces:
+%(\autoref{fig:ISO_triad}):
+\begin{flalign} \label{eq:iso_flux} \vect{F}_{\mathrm{iso}}(T) &\equiv
+  \sum_{\substack{i_p,\,k_p}}
+  \begin{pmatrix}
+    {_{i+1/2-i_p}^k {\mathbb{F}_u}_{i_p}^{k_p} } (T)      \\
+    \\
+    {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p} } (T)      \\
+  \end{pmatrix}.
+\end{flalign}
+
+\subsection{Ensuring the scheme does not increase tracer variance}
+\label{subsec:variance}
+
+We now require that this operator should not increase the
+globally-integrated tracer variance.
+%This changes according to
+% \begin{align*}
+% &\int_D  D_l^T \; T \;dv \equiv  \sum_{i,k} \left\{ T \ D_l^T \ b_T \right\}    \\
+% &\equiv + \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{
+% 		\delta_{i} \left[{_{i+1/2-i_p}^k {\mathbb{F}_u }_{i_p}^{k_p}} \right]
+% 	     + \delta_{k} \left[ {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}} \right]  \ T \right\}    \\
+% &\equiv  - \sum_{i,k} \sum_{\substack{i_p,\,k_p}} \left\{
+%                 {_{i+1/2-i_p}^k {\mathbb{F}_u }_{i_p}^{k_p}} \ \delta_{i+1/2} [T]
+%              + {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}}  \ \delta_{k+1/2} [T]   \right\}      \\
+% \end{align*}
+Each triad slope $_i^k\mathbb{R}_{i_p}^{k_p}$ drives a lateral flux
+$_i^k{\mathbb{F}_u}_{i_p}^{k_p} (T)$ across the $u$-point $i+i_p,k$ and
+a vertical flux $_i^k{\mathbb{F}_w}_{i_p}^{k_p} (T)$ across the
+$w$-point $i,k+k_p$.  The lateral flux drives a net rate of change of
+variance, summed over the two $T$-points $i+i_p-\half,k$ and $i+i_p+\half,k$, of
+\begin{multline}
+  {b_T}_{i+i_p-1/2}^k\left(\frac{\partial T}{\partial t}T\right)_{i+i_p-1/2}^k+
+  \quad {b_T}_{i+i_p+1/2}^k\left(\frac{\partial T}{\partial
+      t}T\right)_{i+i_p+1/2}^k \\
+ \begin{aligned}
+  &= -T_{i+i_p-1/2}^k{\;} _i^k{\mathbb{F}_u}_{i_p}^{k_p} (T) \quad + \quad  T_{i+i_p+1/2}^k
+  {\;}_i^k{\mathbb{F}_u}_{i_p}^{k_p} (T) \\
+  &={\;} _i^k{\mathbb{F}_u}_{i_p}^{k_p} (T)\,\delta_{i+ i_p}[T^k], \label{eq:dvar_iso_i}
+ \end{aligned}
+\end{multline}
+while the vertical flux similarly drives a net rate of change of
+variance summed over the $T$-points $i,k+k_p-\half$ (above) and
+$i,k+k_p+\half$ (below) of
+\begin{equation}
+\label{eq:dvar_iso_k}
+  _i^k{\mathbb{F}_w}_{i_p}^{k_p} (T) \,\delta_{k+ k_p}[T^i].
+\end{equation}
+The total variance tendency driven by the triad is the sum of these
+two. Expanding $_i^k{\mathbb{F}_u}_{i_p}^{k_p} (T)$ and
+$_i^k{\mathbb{F}_w}_{i_p}^{k_p} (T)$ with \autoref{eq:latflux-triad} and
+\autoref{eq:vertflux-triad}, it is
+\begin{multline*}
+-\Alts_i^k\left \{
+{ } _i^k{\mathbb{A}_u}_{i_p}^{k_p}
+  \left(
+    \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    - {_i^k\mathbb{R}_{i_p}^{k_p}} \
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }\right)\,\delta_{i+ i_p}[T^k] \right.\\
+- \left. { } _i^k{\mathbb{A}_w}_{i_p}^{k_p}
+  \left(
+    \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -{\:}_i^k\mathbb{R}_{i_p}^{k_p}
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right) {\,}_i^k\mathbb{R}_{i_p}^{k_p}\delta_{k+ k_p}[T^i]
+\right \}.
+\end{multline*}
+The key point is then that if we require
+$_i^k{\mathbb{A}_u}_{i_p}^{k_p}$ and $_i^k{\mathbb{A}_w}_{i_p}^{k_p}$
+to be related to a triad volume $_i^k\mathbb{V}_{i_p}^{k_p}$ by
+\begin{equation}
+  \label{eq:V-A}
+  _i^k\mathbb{V}_{i_p}^{k_p}
+  ={\;}_i^k{\mathbb{A}_u}_{i_p}^{k_p}\,{e_{1u}}_{\,i + i_p}^{\,k}
+  ={\;}_i^k{\mathbb{A}_w}_{i_p}^{k_p}\,{e_{3w}}_{\,i}^{\,k + k_p},
+\end{equation}
+the variance tendency reduces to the perfect square
+\begin{equation}
+  \label{eq:perfect-square}
+  -\Alts_i^k{\:} _i^k\mathbb{V}_{i_p}^{k_p}
+  \left(
+    \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -{\:}_i^k\mathbb{R}_{i_p}^{k_p}
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right)^2\leq 0.
+\end{equation}
+Thus, the constraint \autoref{eq:V-A} ensures that the fluxes (\autoref{eq:latflux-triad}, \autoref{eq:vertflux-triad}) associated
+with a given slope triad $_i^k\mathbb{R}_{i_p}^{k_p}$ do not increase
+the net variance. Since the total fluxes are sums of such fluxes from
+the various triads, this constraint, applied to all triads, is
+sufficient to ensure that the globally integrated variance does not
+increase.
+
+The expression \autoref{eq:V-A} can be interpreted as a discretization
+of the global integral
+\begin{equation}
+  \label{eq:cts-var}
+  \frac{\partial}{\partial t}\int\!\half T^2\, dV =
+  \int\!\mathbf{F}\cdot\nabla T\, dV,
+\end{equation}
+where, within each triad volume $_i^k\mathbb{V}_{i_p}^{k_p}$, the
+lateral and vertical fluxes/unit area
+\[
+\mathbf{F}=\left(
+\left.{}_i^k{\mathbb{F}_u}_{i_p}^{k_p} (T)\right/{}_i^k{\mathbb{A}_u}_{i_p}^{k_p},
+\left.{\:}_i^k{\mathbb{F}_w}_{i_p}^{k_p} (T)\right/{}_i^k{\mathbb{A}_w}_{i_p}^{k_p}
+ \right)
+\]
+and the gradient
+ \[\nabla T = \left(
+\left.\delta_{i+ i_p}[T^k] \right/ {e_{1u}}_{\,i + i_p}^{\,k},
+\left.\delta_{k+ k_p}[T^i] \right/ {e_{3w}}_{\,i}^{\,k + k_p}
+\right)
+\]
+
+\subsection{Triad volumes in Griffes's scheme and in \NEMO}
+To complete the discretization we now need only specify the triad
+volumes $_i^k\mathbb{V}_{i_p}^{k_p}$. \citet{Griffies_al_JPO98} identify
+these $_i^k\mathbb{V}_{i_p}^{k_p}$ as the volumes of the quarter
+cells, defined in terms of the distances between $T$, $u$,$f$ and
+$w$-points. This is the natural discretization of
+\autoref{eq:cts-var}. The \NEMO model, however, operates with scale
+factors instead of grid sizes, and scale factors for the quarter
+cells are not defined. Instead, therefore we simply choose
+\begin{equation}
+  \label{eq:V-NEMO}
+  _i^k\mathbb{V}_{i_p}^{k_p}=\quarter {b_u}_{i+i_p}^k,
+\end{equation}
+as a quarter of the volume of the $u$-cell inside which the triad
+quarter-cell lies. This has the nice property that when the slopes
+$\mathbb{R}$ vanish, the lateral flux from tracer cell $i,k$ to
+$i+1,k$ reduces to the classical form
+\begin{equation}
+  \label{eq:lat-normal}
+-\overline\Alts_{\,i+1/2}^k\;
+\frac{{b_u}_{i+1/2}^k}{{e_{1u}}_{\,i + i_p}^{\,k}}
+\;\frac{\delta_{i+ 1/2}[T^k] }{{e_{1u}}_{\,i + i_p}^{\,k}}
+ = -\overline\Alts_{\,i+1/2}^k\;\frac{{e_{1w}}_{\,i + 1/2}^{\,k}\:{e_{1v}}_{\,i + 1/2}^{\,k}\;\delta_{i+ 1/2}[T^k]}{{e_{1u}}_{\,i + 1/2}^{\,k}}.
+\end{equation}
+In fact if the diffusive coefficient is defined at $u$-points, so that
+we employ $\Alts_{i+i_p}^k$ instead of  $\Alts_i^k$ in the definitions of the
+triad fluxes \autoref{eq:latflux-triad} and \autoref{eq:vertflux-triad},
+we can replace $\overline{A}_{\,i+1/2}^k$ by $A_{i+1/2}^k$ in the above.
+
+\subsection{Summary of the scheme}
+The iso-neutral fluxes at $u$- and
+$w$-points are the sums of the triad fluxes that cross the $u$- and
+$w$-faces \autoref{eq:iso_flux}:
+\begin{subequations}\label{eq:alltriadflux}
+  \begin{flalign}\label{eq:vect_isoflux}
+    \vect{F}_{\mathrm{iso}}(T) &\equiv
+    \sum_{\substack{i_p,\,k_p}}
+    \begin{pmatrix}
+      {_{i+1/2-i_p}^k {\mathbb{F}_u}_{i_p}^{k_p} } (T)      \\
+      \\
+      {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p} } (T) 
+    \end{pmatrix},
+  \end{flalign}
+  where \autoref{eq:latflux-triad}:
+  \begin{align}
+    \label{eq:triadfluxu}
+    _i^k {\mathbb{F}_u}_{i_p}^{k_p} (T) &= - \Alts_i^k{
+      \:}\frac{{{}_i^k\mathbb{V}}_{i_p}^{k_p}}{{e_{1u}}_{\,i + i_p}^{\,k}}
+    \left(
+      \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+      -\ {_i^k\mathbb{R}_{i_p}^{k_p}} \
+      \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+    \right),\\
+    \intertext{and}
+    _i^k {\mathbb{F}_w}_{i_p}^{k_p} (T)
+    &= \Alts_i^k{\: }\frac{{{}_i^k\mathbb{V}}_{i_p}^{k_p}}{{e_{3w}}_{\,i}^{\,k+k_p}}
+    \left(
+      {_i^k\mathbb{R}_{i_p}^{k_p}}\frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+      -\ \left({_i^k\mathbb{R}_{i_p}^{k_p}}\right)^2 \
+      \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+    \right),\label{eq:triadfluxw}
+  \end{align}
+  with \autoref{eq:V-NEMO}
+  \begin{equation}
+    \label{eq:V-NEMO2}
+    _i^k{\mathbb{V}}_{i_p}^{k_p}=\quarter {b_u}_{i+i_p}^k.
+  \end{equation}
+\end{subequations}
+
+ The divergence of the expression \autoref{eq:iso_flux} for the fluxes gives the iso-neutral diffusion tendency at
+each tracer point:
+\begin{equation} \label{eq:iso_operator} D_l^T = \frac{1}{b_T}
+  \sum_{\substack{i_p,\,k_p}} \left\{ \delta_{i} \left[{_{i+1/2-i_p}^k
+        {\mathbb{F}_u }_{i_p}^{k_p}} \right] + \delta_{k} \left[
+      {_i^{k+1/2-k_p} {\mathbb{F}_w}_{i_p}^{k_p}} \right] \right\}
+\end{equation}
+where $b_T= e_{1T}\,e_{2T}\,e_{3T}$ is the volume of $T$-cells.
+The diffusion scheme satisfies the following six properties:
+\begin{description}
+\item[$\bullet$ horizontal diffusion] The discretization of the
+  diffusion operator recovers \autoref{eq:lat-normal} the traditional five-point Laplacian in
+  the limit of flat iso-neutral direction :
+  \begin{equation} \label{eq:iso_property0} D_l^T = \frac{1}{b_T} \
+    \delta_{i} \left[ \frac{e_{2u}\,e_{3u}}{e_{1u}} \;
+      \overline\Alts^{\,i} \; \delta_{i+1/2}[T] \right] \qquad
+    \text{when} \quad { _i^k \mathbb{R}_{i_p}^{k_p} }=0
+  \end{equation}
+
+\item[$\bullet$ implicit treatment in the vertical] Only tracer values
+  associated with a single water column appear in the expression
+  \autoref{eq:i33} for the $_{33}$ fluxes, vertical fluxes driven by
+  vertical gradients. This is of paramount importance since it means
+  that a time-implicit algorithm can be used to solve the vertical
+  diffusion equation. This is necessary
+ since the vertical eddy
+  diffusivity associated with this term,
+  \begin{equation}
+    \frac{1}{b_w}\sum_{\substack{i_p, \,k_p}} \left\{
+      {\:}_i^k\mathbb{V}_{i_p}^{k_p} \: \Alts_i^k \: \left(_i^k \mathbb{R}_{i_p}^{k_p}\right)^2
+    \right\}  =
+    \frac{1}{4b_w}\sum_{\substack{i_p, \,k_p}} \left\{
+      {b_u}_{i+i_p}^k\: \Alts_i^k \: \left(_i^k \mathbb{R}_{i_p}^{k_p}\right)^2
+    \right\},
+ \end{equation}
+  (where $b_w= e_{1w}\,e_{2w}\,e_{3w}$ is the volume of $w$-cells) can be quite large.
+
+\item[$\bullet$ pure iso-neutral operator] The iso-neutral flux of
+  locally referenced potential density is zero. See
+  \autoref{eq:latflux-rho} and \autoref{eq:vertflux-triad2}.
+
+\item[$\bullet$ conservation of tracer] The iso-neutral diffusion
+  conserves tracer content, $i.e.$
+  \begin{equation} \label{eq:iso_property1} \sum_{i,j,k} \left\{ D_l^T \
+      b_T \right\} = 0
+  \end{equation}
+  This property is trivially satisfied since the iso-neutral diffusive
+  operator is written in flux form.
+
+\item[$\bullet$ no increase of tracer variance] The iso-neutral diffusion
+  does not increase the tracer variance, $i.e.$
+  \begin{equation} \label{eq:iso_property2} \sum_{i,j,k} \left\{ T \ D_l^T
+      \ b_T \right\} \leq 0
+  \end{equation}
+  The property is demonstrated in
+  \autoref{subsec:variance} above. It is a key property for a diffusion
+  term. It means that it is also a dissipation term, $i.e.$ it
+  dissipates the square of the quantity on which it is applied.  It
+  therefore ensures that, when the diffusivity coefficient is large
+  enough, the field on which it is applied becomes free of grid-point
+  noise.
+
+\item[$\bullet$ self-adjoint operator] The iso-neutral diffusion
+  operator is self-adjoint, $i.e.$
+  \begin{equation} \label{eq:iso_property3} \sum_{i,j,k} \left\{ S \ D_l^T
+      \ b_T \right\} = \sum_{i,j,k} \left\{ D_l^S \ T \ b_T \right\}
+  \end{equation}
+  In other word, there is no need to develop a specific routine from
+  the adjoint of this operator. We just have to apply the same
+  routine. This property can be demonstrated similarly to the proof of
+  the `no increase of tracer variance' property. The contribution by a
+  single triad towards the left hand side of \autoref{eq:iso_property3}, can
+  be found by replacing $\delta[T]$ by $\delta[S]$ in \autoref{eq:dvar_iso_i}
+  and \autoref{eq:dvar_iso_k}. This results in a term similar to
+  \autoref{eq:perfect-square},
+\begin{equation}
+  \label{eq:TScovar}
+  - \Alts_i^k{\:} _i^k\mathbb{V}_{i_p}^{k_p}
+  \left(
+    \frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -{\:}_i^k\mathbb{R}_{i_p}^{k_p}
+    \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right)
+  \left(
+    \frac{ \delta_{i+ i_p}[S^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }
+    -{\:}_i^k\mathbb{R}_{i_p}^{k_p}
+    \frac{ \delta_{k+k_p} [S^i] }{{e_{3w}}_{\,i}^{\,k+k_p} }
+  \right).
+\end{equation}
+This is symmetrical in $T $ and $S$, so exactly the same term arises
+from the discretization of this triad's contribution towards the
+RHS of \autoref{eq:iso_property3}.
+\end{description}
+
+\subsection{Treatment of the triads at the boundaries}\label{sec:iso_bdry}
+The triad slope can only be defined where both the grid boxes centred at
+the end of the arms exist. Triads that would poke up
+through the upper ocean surface into the atmosphere, or down into the
+ocean floor, must be masked out. See \autoref{fig:bdry_triads}. Surface layer triads
+$\triad{i}{1}{R}{1/2}{-1/2}$ (magenta) and
+$\triad{i+1}{1}{R}{-1/2}{-1/2}$ (blue) that require density to be
+specified above the ocean surface are masked (\autoref{fig:bdry_triads}a): this ensures that lateral
+tracer gradients produce no flux through the ocean surface. However,
+to prevent surface noise, it is customary to retain the $_{11}$ contributions towards
+the lateral triad fluxes $\triad[u]{i}{1}{F}{1/2}{-1/2}$ and
+$\triad[u]{i+1}{1}{F}{-1/2}{-1/2}$; this drives diapycnal tracer
+fluxes. Similar comments apply to triads that would intersect the
+ocean floor (\autoref{fig:bdry_triads}b). Note that both near bottom
+triad slopes $\triad{i}{k}{R}{1/2}{1/2}$ and
+$\triad{i+1}{k}{R}{-1/2}{1/2}$ are masked when either of the $i,k+1$
+or $i+1,k+1$ tracer points is masked, i.e.\ the $i,k+1$ $u$-point is
+masked. The associated lateral fluxes (grey-black dashed line) are
+masked if \np{ln\_botmix\_triad}\forcode{ = .false.}, but left unmasked,
+giving bottom mixing, if \np{ln\_botmix\_triad}\forcode{ = .true.}.
+
+The default option \np{ln\_botmix\_triad}\forcode{ = .false.} is suitable when the
+bbl mixing option is enabled (\key{trabbl}, with \np{nn\_bbl\_ldf}\forcode{ = 1}),
+or  for simple idealized  problems. For setups with topography without
+bbl mixing, \np{ln\_botmix\_triad}\forcode{ = .true.} may be necessary.
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[h] \begin{center}
+    \includegraphics[width=0.60\textwidth]{Fig_GRIFF_bdry_triads}
+    \caption{  \protect\label{fig:bdry_triads}
+      (a) Uppermost model layer $k=1$ with $i,1$ and $i+1,1$ tracer
+      points (black dots), and $i+1/2,1$ $u$-point (blue square). Triad
+      slopes $\triad{i}{1}{R}{1/2}{-1/2}$ (magenta) and $\triad{i+1}{1}{R}{-1/2}{-1/2}$
+      (blue) poking through the ocean surface are masked (faded in
+      figure). However, the lateral $_{11}$ contributions towards
+      $\triad[u]{i}{1}{F}{1/2}{-1/2}$ and $\triad[u]{i+1}{1}{F}{-1/2}{-1/2}$
+      (yellow line) are still applied, giving diapycnal diffusive
+      fluxes.\newline
+      (b) Both near bottom triad slopes $\triad{i}{k}{R}{1/2}{1/2}$ and
+      $\triad{i+1}{k}{R}{-1/2}{1/2}$ are masked when either of the $i,k+1$
+      or $i+1,k+1$ tracer points is masked, i.e.\ the $i,k+1$ $u$-point
+      is masked. The associated lateral fluxes (grey-black dashed
+      line) are masked if \protect\np{botmix\_triad}\forcode{ = .false.}, but left
+      unmasked, giving bottom mixing, if \protect\np{botmix\_triad}\forcode{ = .true.}}
+ \end{center} \end{figure}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+\subsection{ Limiting of the slopes within the interior}\label{sec:limit}
+As discussed in \autoref{subsec:LDF_slp_iso}, iso-neutral slopes relative to
+geopotentials must be bounded everywhere, both for consistency with the small-slope
+approximation and for numerical stability \citep{Cox1987,
+  Griffies_Bk04}. The bound chosen in \NEMO is applied to each
+component of the slope separately and has a value of $1/100$ in the ocean interior.
+%, ramping linearly down above 70~m depth to zero at the surface
+It is of course relevant to the iso-neutral slopes $\tilde{r}_i=r_i+\sigma_i$ relative to
+geopotentials (here the $\sigma_i$ are the slopes of the coordinate surfaces relative to
+geopotentials) \autoref{eq:PE_slopes_eiv} rather than the slope $r_i$ relative to coordinate
+surfaces, so we require
+\begin{equation*}
+  |\tilde{r}_i|\leq \tilde{r}_\mathrm{max}=0.01.
+\end{equation*}
+and then recalculate the slopes $r_i$ relative to coordinates.
+Each individual triad slope
+ \begin{equation}
+   \label{eq:Rtilde}
+_i^k\tilde{\mathbb{R}}_{i_p}^{k_p} = {}_i^k\mathbb{R}_{i_p}^{k_p}  + \frac{\delta_{i+i_p}[z_T^k]}{{e_{1u}}_{\,i + i_p}^{\,k}}
+ \end{equation}
+is limited like this and then the corresponding
+$_i^k\mathbb{R}_{i_p}^{k_p} $ are recalculated and combined to form the fluxes.
+Note that where the slopes have been limited, there is now a non-zero
+iso-neutral density flux that drives dianeutral mixing.  In particular this iso-neutral density flux
+is always downwards, and so acts to reduce gravitational potential energy.
+
+\subsection{Tapering within the surface mixed layer}\label{sec:taper}
+Additional tapering of the iso-neutral fluxes is necessary within the
+surface mixed layer. When the Griffies triads are used, we offer two
+options for this.
+
+\subsubsection{Linear slope tapering within the surface mixed layer}\label{sec:lintaper}
+This is the option activated by the default choice
+\np{ln\_triad\_iso}\forcode{ = .false.}. Slopes $\tilde{r}_i$ relative to
+geopotentials are tapered linearly from their value immediately below the mixed layer to zero at the
+surface, as described in option (c) of \autoref{fig:eiv_slp}, to values
+\begin{subequations}
+  \begin{equation}
+   \label{eq:rmtilde}
+     \rMLt =
+  -\frac{z}{h}\left.\tilde{r}_i\right|_{z=-h}\quad \text{ for  } z>-h,
+  \end{equation}
+and then the $r_i$ relative to vertical coordinate surfaces are appropriately
+adjusted to
+  \begin{equation}
+   \label{eq:rm}
+ \rML =\rMLt -\sigma_i \quad \text{ for  } z>-h.
+  \end{equation}
+\end{subequations}
+Thus the diffusion operator within the mixed layer is given by:
+\begin{equation} \label{eq:iso_tensor_ML}
+D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
+\mbox{with}\quad \;\;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-\rML[1]}\hfill \\
+ 0 \hfill & 1 \hfill & {-\rML[2]} \hfill \\
+ {-\rML[1]}\hfill &   {-\rML[2]} \hfill & {\rML[1]^2+\rML[2]^2} \hfill
+\end{array} }} \right)
+\end{equation}
+
+This slope tapering gives a natural connection between tracer in the
+mixed-layer and in isopycnal layers immediately below, in the
+thermocline. It is consistent with the way the $\tilde{r}_i$ are
+tapered within the mixed layer (see \autoref{sec:taperskew} below)
+so as to ensure a uniform GM eddy-induced velocity throughout the
+mixed layer. However, it gives a downwards density flux and so acts so
+as to reduce potential energy in the same way as does the slope
+limiting discussed above in \autoref{sec:limit}.
+ 
+As in \autoref{sec:limit} above, the tapering
+\autoref{eq:rmtilde} is applied separately to each triad
+$_i^k\tilde{\mathbb{R}}_{i_p}^{k_p}$, and the
+$_i^k\mathbb{R}_{i_p}^{k_p}$ adjusted. For clarity, we assume
+$z$-coordinates in the following; the conversion from
+$\mathbb{R}$ to $\tilde{\mathbb{R}}$ and back to $\mathbb{R}$ follows exactly as described
+above by \autoref{eq:Rtilde}.
+\begin{enumerate}
+\item Mixed-layer depth is defined so as to avoid including regions of weak
+vertical stratification in the slope definition.
+ At each $i,j$ (simplified to $i$ in
+\autoref{fig:MLB_triad}), we define the mixed-layer by setting
+the vertical index of the tracer point immediately below the mixed
+layer, $k_{\mathrm{ML}}$, as the maximum $k$ (shallowest tracer point)
+such that the potential density
+${\rho_0}_{i,k}>{\rho_0}_{i,k_{10}}+\Delta\rho_c$, where $i,k_{10}$ is
+the tracer gridbox within which the depth reaches 10~m. See the left
+side of \autoref{fig:MLB_triad}. We use the $k_{10}$-gridbox
+instead of the surface gridbox to avoid problems e.g.\ with thin
+daytime mixed-layers. Currently we use the same
+$\Delta\rho_c=0.01\;\mathrm{kg\:m^{-3}}$ for ML triad tapering as is
+used to output the diagnosed mixed-layer depth
+$h_{\mathrm{ML}}=|z_{W}|_{k_{\mathrm{ML}}+1/2}$, the depth of the $w$-point
+above the $i,k_{\mathrm{ML}}$ tracer point.
+
+\item We define `basal' triad slopes
+${\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}$ as the slopes
+of those triads whose vertical `arms' go down from the
+$i,k_{\mathrm{ML}}$ tracer point to the $i,k_{\mathrm{ML}}-1$ tracer point
+below. This is to ensure that the vertical density gradients
+associated with these basal triad slopes
+${\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}$ are
+representative of the thermocline. The four basal triads defined in the bottom part
+of \autoref{fig:MLB_triad} are then
+\begin{align}
+  {\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p} &=
+ {\:}^{k_{\mathrm{ML}}-k_p-1/2}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}, \label{eq:Rbase}
+\\
+\intertext{with e.g.\ the green triad}
+{\:}_i{\mathbb{R}_{\mathrm{base}}}_{1/2}^{-1/2}&=
+{\:}^{k_{\mathrm{ML}}}_i{\mathbb{R}_{\mathrm{base}}}_{\,1/2}^{-1/2}. \notag
+\end{align}
+The vertical flux associated with each of these triads passes through the $w$-point
+$i,k_{\mathrm{ML}}-1/2$ lying \emph{below} the $i,k_{\mathrm{ML}}$ tracer point,
+so it is this depth
+\begin{equation}
+  \label{eq:zbase}
+  {z_\mathrm{base}}_{\,i}={z_{w}}_{k_\mathrm{ML}-1/2}
+\end{equation}
+(one gridbox deeper than the
+diagnosed ML depth $z_{\mathrm{ML}})$ that sets the $h$ used to taper
+the slopes in \autoref{eq:rmtilde}.
+\item Finally, we calculate the adjusted triads
+${\:}_i^k{\mathbb{R}_{\mathrm{ML}}}_{\,i_p}^{k_p}$ within the mixed
+layer, by multiplying the appropriate
+${\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}$ by the ratio of
+the depth of the $w$-point ${z_w}_{k+k_p}$ to ${z_{\mathrm{base}}}_{\,i}$. For
+instance the green triad centred on $i,k$
+\begin{align}
+  {\:}_i^k{\mathbb{R}_{\mathrm{ML}}}_{\,1/2}^{-1/2} &=
+\frac{{z_w}_{k-1/2}}{{z_{\mathrm{base}}}_{\,i}}{\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,1/2}^{-1/2}
+\notag \\
+\intertext{and more generally}
+ {\:}_i^k{\mathbb{R}_{\mathrm{ML}}}_{\,i_p}^{k_p} &=
+\frac{{z_w}_{k+k_p}}{{z_{\mathrm{base}}}_{\,i}}{\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}.\label{eq:RML}
+\end{align}
+\end{enumerate}
+
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[h]
+%  \fcapside {
+    \caption{\protect\label{fig:MLB_triad} Definition of
+      mixed-layer depth and calculation of linearly tapered
+      triads. The figure shows a water column at a given $i,j$
+      (simplified to $i$), with the ocean surface at the top. Tracer points are denoted by
+      bullets, and black lines the edges of the tracer cells; $k$
+      increases upwards. \newline
+      \hspace{5 em}We define the mixed-layer by setting the vertical index
+      of the tracer point immediately below the mixed layer,
+      $k_{\mathrm{ML}}$, as the maximum $k$ (shallowest tracer point)
+      such that ${\rho_0}_{i,k}>{\rho_0}_{i,k_{10}}+\Delta\rho_c$,
+      where $i,k_{10}$ is the tracer gridbox within which the depth
+      reaches 10~m. We calculate the triad slopes within the mixed
+      layer by linearly tapering them from zero (at the surface) to
+      the `basal' slopes, the slopes of the four triads passing through the
+      $w$-point $i,k_{\mathrm{ML}}-1/2$ (blue square),
+      ${\:}_i{\mathbb{R}_{\mathrm{base}}}_{\,i_p}^{k_p}$. Triads with
+    different $i_p,k_p$, denoted by different colours, (e.g. the green
+    triad $i_p=1/2,k_p=-1/2$) are tapered to the appropriate basal triad.}
+%}
+  {\includegraphics[width=0.60\textwidth]{Fig_GRIFF_MLB_triads}}
+\end{figure}
+% >>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+\subsubsection{Additional truncation of skew iso-neutral flux components}
+\label{subsec:Gerdes-taper}
+The alternative option is activated by setting \np{ln\_triad\_iso} =
+  true. This retains the same tapered slope $\rML$  described above for the
+calculation of the $_{33}$ term of the iso-neutral diffusion tensor (the
+vertical tracer flux driven by vertical tracer gradients), but
+replaces the $\rML$ in the skew term by
+\begin{equation}
+  \label{eq:rm*}
+  \rML^*=\left.\rMLt^2\right/\tilde{r}_i-\sigma_i,
+\end{equation}
+giving a ML diffusive operator
+\begin{equation} \label{eq:iso_tensor_ML2}
+D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad
+\mbox{with}\quad \;\;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-\rML[1]^*}\hfill \\
+ 0 \hfill & 1 \hfill & {-\rML[2]^*} \hfill \\
+ {-\rML[1]^*}\hfill &   {-\rML[2]^*} \hfill & {\rML[1]^2+\rML[2]^2} \hfill \\
+\end{array} }} \right).
+\end{equation}
+This operator
+\footnote{To ensure good behaviour where horizontal density
+  gradients are weak, we in fact follow \citet{Gerdes1991} and set
+$\rML^*=\mathrm{sgn}(\tilde{r}_i)\min(|\rMLt^2/\tilde{r}_i|,|\tilde{r}_i|)-\sigma_i$.}
+then has the property it gives no vertical density flux, and so does
+not change the potential energy.
+This approach is similar to multiplying the iso-neutral  diffusion
+coefficient by $\tilde{r}_{\mathrm{max}}^{-2}\tilde{r}_i^{-2}$ for steep
+slopes, as suggested by \citet{Gerdes1991} (see also \citet{Griffies_Bk04}).
+Again it is applied separately to each triad $_i^k\mathbb{R}_{i_p}^{k_p}$
+
+In practice, this approach gives weak vertical tracer fluxes through
+the mixed-layer, as well as vanishing density fluxes. While it is
+theoretically advantageous that it does not change the potential
+energy, it may give a discontinuity between the
+fluxes within the mixed-layer (purely horizontal) and just below (along
+iso-neutral surfaces).
+% This may give strange looking results,
+% particularly where the mixed-layer depth varies strongly laterally.
+% ================================================================
+% Skew flux formulation for Eddy Induced Velocity :
+% ================================================================
+\section{Eddy induced advection formulated as a skew flux}\label{sec:skew-flux}
+
+\subsection{Continuous skew flux formulation}\label{sec:continuous-skew-flux}
+
+ When Gent and McWilliams's [1990] diffusion is used,
+an additional advection term is added. The associated velocity is the so called
+eddy induced velocity, the formulation of which depends on the slopes of iso-
+neutral surfaces. Contrary to the case of iso-neutral mixing, the slopes used
+here are referenced to the geopotential surfaces, $i.e.$ \autoref{eq:ldfslp_geo}
+is used in $z$-coordinate, and the sum \autoref{eq:ldfslp_geo}
++ \autoref{eq:ldfslp_iso} in $z^*$ or $s$-coordinates.
+
+The eddy induced velocity is given by:
+\begin{subequations} \label{eq:eiv}
+\begin{equation}\label{eq:eiv_v}
+\begin{split}
+ u^* & = - \frac{1}{e_{3}}\;          \partial_i\psi_1,  \\
+ v^* & = - \frac{1}{e_{3}}\;          \partial_j\psi_2,    \\
+w^* & =    \frac{1}{e_{1}e_{2}}\; \left\{ \partial_i  \left( e_{2} \, \psi_1\right)
+							    + \partial_j  \left( e_{1} \, \psi_2\right) \right\},
+\end{split}
+\end{equation}
+where the streamfunctions $\psi_i$ are given by
+\begin{equation} \label{eq:eiv_psi}
+\begin{split}
+\psi_1 & = A_{e} \; \tilde{r}_1,   \\
+\psi_2 & = A_{e} \; \tilde{r}_2,
+\end{split}
+\end{equation}
+\end{subequations}
+with $A_{e}$ the eddy induced velocity coefficient, and $\tilde{r}_1$ and $\tilde{r}_2$ the slopes between the iso-neutral and the geopotential surfaces.
+
+The traditional way to implement this additional advection is to add
+it to the Eulerian velocity prior to computing the tracer
+advection. This is implemented if \key{traldf\_eiv} is set in the
+default implementation, where \np{ln\_traldf\_triad} is set
+false. This allows us to take advantage of all the advection schemes
+offered for the tracers (see \autoref{sec:TRA_adv}) and not just a $2^{nd}$
+order advection scheme. This is particularly useful for passive
+tracers where \emph{positivity} of the advection scheme is of
+paramount importance.
+
+However, when \np{ln\_traldf\_triad} is set true, \NEMO instead
+implements eddy induced advection according to the so-called skew form
+\citep{Griffies_JPO98}. It is based on a transformation of the advective fluxes
+using the non-divergent nature of the eddy induced velocity.
+For example in the (\textbf{i},\textbf{k}) plane, the tracer advective
+fluxes per unit area in $ijk$ space can be
+transformed as follows:
+\begin{flalign*}
+\begin{split}
+\textbf{F}_{\mathrm{eiv}}^T =
+\begin{pmatrix}
+ 	        {e_{2}\,e_{3}\;  u^*} 	 	\\
+ 		{e_{1}\,e_{2}\; w^*}	 \\
+\end{pmatrix}   \;   T
+&=
+\begin{pmatrix}
+ 	        { - \partial_k \left( e_{2} \,\psi_1 \right) \; T \;} 	 	\\
+ 		{+ \partial_i  \left( e_{2} \, \psi_1 \right) \; T \;}	 \\
+\end{pmatrix} 			\\
+&=
+\begin{pmatrix}
+ 	        { - \partial_k \left( e_{2} \, \psi_1  \; T \right) \;}  \\
+ 		{+ \partial_i  \left( e_{2} \,\psi_1 \; T \right) \;}	 \\
+\end{pmatrix}
+ +
+\begin{pmatrix}
+ 	        {+ e_{2} \, \psi_1  \; \partial_k T}  \\
+ 		{ - e_{2} \, \psi_1  \; \partial_i  T}	 \\
+\end{pmatrix}
+\end{split}
+\end{flalign*}
+and since the eddy induced velocity field is non-divergent, we end up with the skew
+form of the eddy induced advective fluxes per unit area in $ijk$ space:
+\begin{equation} \label{eq:eiv_skew_ijk}
+\textbf{F}_\mathrm{eiv}^T = \begin{pmatrix}
+ 	        {+ e_{2} \, \psi_1  \; \partial_k T}   \\
+ 		{ - e_{2} \, \psi_1  \; \partial_i  T}	 \\
+                                 \end{pmatrix}
+\end{equation}
+The total fluxes per unit physical area are then
+\begin{equation}\label{eq:eiv_skew_physical}
+\begin{split}
+ f^*_1 & = \frac{1}{e_{3}}\; \psi_1 \partial_k T   \\
+ f^*_2 & = \frac{1}{e_{3}}\; \psi_2 \partial_k T   \\
+ f^*_3 & =  -\frac{1}{e_{1}e_{2}}\; \left\{ e_{2} \psi_1 \partial_i T
+   + e_{1} \psi_2 \partial_j T \right\}. \\
+\end{split}
+\end{equation}
+Note that  \autoref{eq:eiv_skew_physical} takes the same form whatever the
+vertical coordinate, though of course the slopes
+$\tilde{r}_i$ which define the $\psi_i$ in \autoref{eq:eiv_psi} are relative to geopotentials.
+The tendency associated with eddy induced velocity is then simply the convergence
+of the fluxes (\autoref{eq:eiv_skew_ijk}, \autoref{eq:eiv_skew_physical}), so
+\begin{equation} \label{eq:skew_eiv_conv}
+\frac{\partial T}{\partial t}= -\frac{1}{e_1 \, e_2 \, e_3 }      \left[
+  \frac{\partial}{\partial i} \left( e_2 \psi_1 \partial_k T\right)
+  + \frac{\partial}{\partial j} \left( e_1  \;
+    \psi_2 \partial_k T\right)
+ -  \frac{\partial}{\partial k} \left( e_{2} \psi_1 \partial_i T
+   + e_{1} \psi_2 \partial_j T \right)  \right]
+\end{equation}
+ It naturally conserves the tracer content, as it is expressed in flux
+ form. Since it has the same divergence as the advective form it also
+ preserves the tracer variance.
+
+\subsection{Discrete skew flux formulation}
+The skew fluxes in (\autoref{eq:eiv_skew_physical}, \autoref{eq:eiv_skew_ijk}), like the off-diagonal terms
+(\autoref{eq:i13c}, \autoref{eq:i31c}) of the small angle diffusion tensor, are best
+expressed in terms of the triad slopes, as in \autoref{fig:ISO_triad}
+and (\autoref{eq:i13}, \autoref{eq:i31}); but now in terms of the triad slopes
+$\tilde{\mathbb{R}}$ relative to geopotentials instead of the
+$\mathbb{R}$ relative to coordinate surfaces. The discrete form of
+\autoref{eq:eiv_skew_ijk} using the slopes \autoref{eq:R} and
+defining $A_e$ at $T$-points is then given by:
+
+
+\begin{subequations}\label{eq:allskewflux}
+  \begin{flalign}\label{eq:vect_skew_flux}
+    \vect{F}_{\mathrm{eiv}}(T) &\equiv
+    \sum_{\substack{i_p,\,k_p}}
+    \begin{pmatrix}
+      {_{i+1/2-i_p}^k {\mathbb{S}_u}_{i_p}^{k_p} } (T)      \\
+      \\
+      {_i^{k+1/2-k_p} {\mathbb{S}_w}_{i_p}^{k_p} } (T)      \\
+    \end{pmatrix},
+  \end{flalign}
+  where the skew flux in the $i$-direction associated with a given
+  triad is (\autoref{eq:latflux-triad}, \autoref{eq:triadfluxu}):
+  \begin{align}
+    \label{eq:skewfluxu}
+    _i^k {\mathbb{S}_u}_{i_p}^{k_p} (T) &= + \quarter {A_e}_i^k{
+      \:}\frac{{b_u}_{i+i_p}^k}{{e_{1u}}_{\,i + i_p}^{\,k}}
+     \ {_i^k\tilde{\mathbb{R}}_{i_p}^{k_p}} \
+      \frac{ \delta_{k+k_p} [T^i] }{{e_{3w}}_{\,i}^{\,k+k_p} },
+   \\
+    \intertext{and \autoref{eq:triadfluxw} in the $k$-direction, changing the sign
+      to be consistent with \autoref{eq:eiv_skew_ijk}:}
+    _i^k {\mathbb{S}_w}_{i_p}^{k_p} (T)
+    &= -\quarter {A_e}_i^k{\: }\frac{{b_u}_{i+i_p}^k}{{e_{3w}}_{\,i}^{\,k+k_p}}
+     {_i^k\tilde{\mathbb{R}}_{i_p}^{k_p}}\frac{ \delta_{i+ i_p}[T^k] }{ {e_{1u}}_{\,i + i_p}^{\,k} }.\label{eq:skewfluxw}
+  \end{align}
+\end{subequations}
+
+Such a discretisation is consistent with the iso-neutral
+operator as it uses the same definition for the slopes.  It also
+ensures the following two key properties.
+
+\subsubsection{No change in tracer variance}
+The discretization conserves tracer variance, $i.e.$ it does not
+include a diffusive component but is a `pure' advection term. This can
+be seen
+%either from Appendix \autoref{apdx:eiv_skew} or
+by considering the
+fluxes associated with a given triad slope
+$_i^k{\mathbb{R}}_{i_p}^{k_p} (T)$. For, following
+\autoref{subsec:variance} and \autoref{eq:dvar_iso_i}, the
+associated horizontal skew-flux $_i^k{\mathbb{S}_u}_{i_p}^{k_p} (T)$
+drives a net rate of change of variance, summed over the two
+$T$-points $i+i_p-\half,k$ and $i+i_p+\half,k$, of
+\begin{equation}
+\label{eq:dvar_eiv_i}
+  _i^k{\mathbb{S}_u}_{i_p}^{k_p} (T)\,\delta_{i+ i_p}[T^k],
+\end{equation}
+while the associated vertical skew-flux gives a variance change summed over the
+$T$-points $i,k+k_p-\half$ (above) and $i,k+k_p+\half$ (below) of
+\begin{equation}
+\label{eq:dvar_eiv_k}
+  _i^k{\mathbb{S}_w}_{i_p}^{k_p} (T) \,\delta_{k+ k_p}[T^i].
+\end{equation}
+Inspection of the definitions (\autoref{eq:skewfluxu}, \autoref{eq:skewfluxw})
+shows that these two variance changes (\autoref{eq:dvar_eiv_i}, \autoref{eq:dvar_eiv_k})
+sum to zero. Hence the two fluxes associated with each triad make no
+net contribution to the variance budget.
+
+\subsubsection{Reduction in gravitational PE}
+The vertical density flux associated with the vertical skew-flux
+always has the same sign as the vertical density gradient; thus, so
+long as the fluid is stable (the vertical density gradient is
+negative) the vertical density flux is negative (downward) and hence
+reduces the gravitational PE.
+
+For the change in gravitational PE driven by the $k$-flux is
+\begin{align}
+  \label{eq:vert_densityPE}
+  g {e_{3w}}_{\,i}^{\,k+k_p}{\mathbb{S}_w}_{i_p}^{k_p} (\rho)
+  &=g {e_{3w}}_{\,i}^{\,k+k_p}\left[-\alpha _i^k {\:}_i^k
+    {\mathbb{S}_w}_{i_p}^{k_p} (T) + \beta_i^k {\:}_i^k
+    {\mathbb{S}_w}_{i_p}^{k_p} (S) \right]. \notag \\
+\intertext{Substituting  ${\:}_i^k {\mathbb{S}_w}_{i_p}^{k_p}$ from
+  \autoref{eq:skewfluxw}, gives}
+% and separating out
+% $\rtriadt{R}=\rtriad{R} + \delta_{i+i_p}[z_T^k]$,
+% gives two terms. The
+% first $\rtriad{R}$ term (the only term for $z$-coordinates) is:
+ &=-\quarter g{A_e}_i^k{\: }{b_u}_{i+i_p}^k {_i^k\tilde{\mathbb{R}}_{i_p}^{k_p}}
+\frac{ -\alpha _i^k\delta_{i+ i_p}[T^k]+ \beta_i^k\delta_{i+ i_p}[S^k]} { {e_{1u}}_{\,i + i_p}^{\,k} } \notag \\
+ &=+\quarter g{A_e}_i^k{\: }{b_u}_{i+i_p}^k
+     \left({_i^k\mathbb{R}_{i_p}^{k_p}}+\frac{\delta_{i+i_p}[z_T^k]}{{e_{1u}}_{\,i + i_p}^{\,k}}\right) {_i^k\mathbb{R}_{i_p}^{k_p}}
+\frac{-\alpha_i^k \delta_{k+ k_p}[T^i]+ \beta_i^k\delta_{k+ k_p}[S^i]} {{e_{3w}}_{\,i}^{\,k+k_p}},
+\end{align}
+using the definition of the triad slope $\rtriad{R}$,
+\autoref{eq:R} to express $-\alpha _i^k\delta_{i+ i_p}[T^k]+
+\beta_i^k\delta_{i+ i_p}[S^k]$ in terms of  $-\alpha_i^k \delta_{k+
+  k_p}[T^i]+ \beta_i^k\delta_{k+ k_p}[S^i]$.
+
+Where the coordinates slope, the $i$-flux gives a PE change
+\begin{multline}
+  \label{eq:lat_densityPE}
+ g \delta_{i+i_p}[z_T^k]
+\left[
+-\alpha _i^k {\:}_i^k {\mathbb{S}_u}_{i_p}^{k_p} (T) + \beta_i^k {\:}_i^k {\mathbb{S}_u}_{i_p}^{k_p} (S)
+\right] \\
+= +\quarter g{A_e}_i^k{\: }{b_u}_{i+i_p}^k
+     \frac{\delta_{i+i_p}[z_T^k]}{{e_{1u}}_{\,i + i_p}^{\,k}}
+\left({_i^k\mathbb{R}_{i_p}^{k_p}}+\frac{\delta_{i+i_p}[z_T^k]}{{e_{1u}}_{\,i + i_p}^{\,k}}\right)
+\frac{-\alpha_i^k \delta_{k+ k_p}[T^i]+ \beta_i^k\delta_{k+ k_p}[S^i]} {{e_{3w}}_{\,i}^{\,k+k_p}},
+\end{multline}
+(using \autoref{eq:skewfluxu}) and so the total PE change
+\autoref{eq:vert_densityPE} + \autoref{eq:lat_densityPE} associated with the triad fluxes is
+\begin{multline}
+  \label{eq:tot_densityPE}
+  g{e_{3w}}_{\,i}^{\,k+k_p}{\mathbb{S}_w}_{i_p}^{k_p} (\rho) +
+g\delta_{i+i_p}[z_T^k] {\:}_i^k {\mathbb{S}_u}_{i_p}^{k_p} (\rho) \\
+= +\quarter g{A_e}_i^k{\: }{b_u}_{i+i_p}^k
+     \left({_i^k\mathbb{R}_{i_p}^{k_p}}+\frac{\delta_{i+i_p}[z_T^k]}{{e_{1u}}_{\,i + i_p}^{\,k}}\right)^2
+\frac{-\alpha_i^k \delta_{k+ k_p}[T^i]+ \beta_i^k\delta_{k+ k_p}[S^i]} {{e_{3w}}_{\,i}^{\,k+k_p}}.
+\end{multline}
+Where the fluid is stable, with $-\alpha_i^k \delta_{k+ k_p}[T^i]+
+\beta_i^k\delta_{k+ k_p}[S^i]<0$, this PE change is negative.
+
+\subsection{Treatment of the triads at the boundaries}\label{sec:skew_bdry}
+Triad slopes \rtriadt{R} used for the calculation of the eddy-induced skew-fluxes
+are masked at the boundaries in exactly the same way as are the triad
+slopes \rtriad{R} used for the iso-neutral diffusive fluxes, as
+described in \autoref{sec:iso_bdry} and
+\autoref{fig:bdry_triads}. Thus surface layer triads
+$\triadt{i}{1}{R}{1/2}{-1/2}$ and $\triadt{i+1}{1}{R}{-1/2}{-1/2}$ are
+masked, and both near bottom triad slopes $\triadt{i}{k}{R}{1/2}{1/2}$
+and $\triadt{i+1}{k}{R}{-1/2}{1/2}$ are masked when either of the
+$i,k+1$ or $i+1,k+1$ tracer points is masked, i.e.\ the $i,k+1$
+$u$-point is masked. The namelist parameter \np{ln\_botmix\_triad} has
+no effect on the eddy-induced skew-fluxes.
+
+\subsection{Limiting of the slopes within the interior}\label{sec:limitskew}
+Presently, the iso-neutral slopes $\tilde{r}_i$ relative
+to geopotentials are limited to be less than $1/100$, exactly as in
+calculating the iso-neutral diffusion, \S \autoref{sec:limit}. Each
+individual triad \rtriadt{R} is so limited.
+
+\subsection{Tapering within the surface mixed layer}\label{sec:taperskew}
+The slopes $\tilde{r}_i$ relative to
+geopotentials (and thus the individual triads \rtriadt{R}) are always tapered linearly from their value immediately below the mixed layer to zero at the
+surface \autoref{eq:rmtilde}, as described in \autoref{sec:lintaper}. This is
+option (c) of \autoref{fig:eiv_slp}. This linear tapering for the
+slopes used to calculate the eddy-induced fluxes is
+unaffected by the value of \np{ln\_triad\_iso}.
+
+The justification for this linear slope tapering is that, for $A_e$
+that is constant or varies only in the horizontal (the most commonly
+used options in \NEMO: see \autoref{sec:LDF_coef}), it is
+equivalent to a horizontal eiv (eddy-induced velocity) that is uniform
+within the mixed layer \autoref{eq:eiv_v}. This ensures that the
+eiv velocities do not restratify the mixed layer \citep{Treguier1997,
+  Danabasoglu_al_2008}. Equivantly, in terms
+of the skew-flux formulation we use here, the
+linear slope tapering within the mixed-layer gives a linearly varying
+vertical flux, and so a tracer convergence uniform in depth (the
+horizontal flux convergence is relatively insignificant within the mixed-layer).
+
+\subsection{Streamfunction diagnostics}\label{sec:sfdiag}
+Where the namelist parameter \np{ln\_traldf\_gdia}\forcode{ = .true.}, diagnosed
+mean eddy-induced velocities are output. Each time step,
+streamfunctions are calculated in the $i$-$k$ and $j$-$k$ planes at
+$uw$ (integer +1/2 $i$, integer $j$, integer +1/2 $k$) and $vw$
+(integer $i$, integer +1/2 $j$, integer +1/2 $k$) points (see Table
+\autoref{tab:cell}) respectively. We follow \citep{Griffies_Bk04} and
+calculate the streamfunction at a given $uw$-point from the
+surrounding four triads according to:
+\begin{equation}
+  \label{eq:sfdiagi}
+  {\psi_1}_{i+1/2}^{k+1/2}={\quarter}\sum_{\substack{i_p,\,k_p}}
+  {A_e}_{i+1/2-i_p}^{k+1/2-k_p}\:\triadd{i+1/2-i_p}{k+1/2-k_p}{R}{i_p}{k_p}.
+\end{equation}
+The streamfunction $\psi_1$ is calculated similarly at $vw$ points.
+The eddy-induced velocities are then calculated from the
+straightforward discretisation of \autoref{eq:eiv_v}:
+\begin{equation}\label{eq:eiv_v_discrete}
+\begin{split}
+ {u^*}_{i+1/2}^{k} & = - \frac{1}{{e_{3u}}_{i}^{k}}\left({\psi_1}_{i+1/2}^{k+1/2}-{\psi_1}_{i+1/2}^{k+1/2}\right),   \\
+ {v^*}_{j+1/2}^{k} & = - \frac{1}{{e_{3v}}_{j}^{k}}\left({\psi_2}_{j+1/2}^{k+1/2}-{\psi_2}_{j+1/2}^{k+1/2}\right),   \\
+ {w^*}_{i,j}^{k+1/2} & =    \frac{1}{e_{1t}e_{2t}}\; \left\{
+ {e_{2u}}_{i+1/2}^{k+1/2} \,{\psi_1}_{i+1/2}^{k+1/2} -
+ {e_{2u}}_{i-1/2}^{k+1/2} \,{\psi_1}_{i-1/2}^{k+1/2} \right. + \\
+\phantom{=} & \qquad\qquad\left. {e_{2v}}_{j+1/2}^{k+1/2} \,{\psi_2}_{j+1/2}^{k+1/2} - {e_{2v}}_{j-1/2}^{k+1/2} \,{\psi_2}_{j-1/2}^{k+1/2} \right\},
+\end{split}
+\end{equation}
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ASM.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ASM.tex	(revision 10321)
@@ -0,0 +1,175 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter Assimilation increments (ASM)
+% ================================================================
+\chapter{Apply Assimilation Increments (ASM)}
+\label{chap:ASM}
+
+Authors: D. Lea,  M. Martin, K. Mogensen, A. Weaver, ...   % do we keep
+
+\minitoc
+
+
+\newpage
+$\ $\newline    % force a new line
+
+The ASM code adds the functionality to apply increments to the model variables: 
+temperature, salinity, sea surface height, velocity and sea ice concentration. 
+These are read into the model from a NetCDF file which may be produced by separate data
+assimilation code.  The code can also output model background fields which are used
+as an input to data assimilation code. This is all controlled by the namelist
+\textit{\ngn{nam\_asminc} }.  There is a brief description of all the namelist options
+provided.  To build the ASM code \key{asminc} must be set.
+
+%===============================================================
+
+\section{Direct initialization}
+\label{sec:ASM_DI}
+
+Direct initialization (DI) refers to the instantaneous correction
+of the model background state using the analysis increment.
+DI is used when \np{ln\_asmdin} is set to true.
+
+\section{Incremental analysis updates}
+\label{sec:ASM_IAU}
+
+Rather than updating the model state directly with the analysis increment,
+it may be preferable to introduce the increment gradually into the ocean
+model in order to minimize spurious adjustment processes. This technique
+is referred to as Incremental Analysis Updates (IAU) \citep{Bloom_al_MWR96}.
+IAU is a common technique used with 3D assimilation methods such as 3D-Var or OI.
+IAU is used when \np{ln\_asmiau} is set to true.
+
+With IAU, the model state trajectory ${\bf x}$ in the assimilation window 
+($t_{0} \leq t_{i} \leq t_{N}$)
+is corrected by adding the analysis increments for temperature, salinity, horizontal velocity and SSH
+as additional tendency terms to the prognostic equations:
+\begin{eqnarray}     \label{eq:wa_traj_iau}
+{\bf x}^{a}(t_{i}) = M(t_{i}, t_{0})[{\bf x}^{b}(t_{0})] 
+\; + \; F_{i} \delta \tilde{\bf x}^{a} 
+\end{eqnarray}
+where $F_{i}$ is a weighting function for applying the increments $\delta
+\tilde{\bf x}^{a}$ defined such that $\sum_{i=1}^{N} F_{i}=1$.
+${\bf x}^b$ denotes the model initial state and ${\bf x}^a$ is the model state
+after the increments are applied. 
+To control the adjustment time of the model to the increment,
+the increment can be applied over an arbitrary sub-window,
+$t_{m} \leq t_{i} \leq t_{n}$, of the main assimilation window,
+where $t_{0} \leq t_{m} \leq t_{i}$ and $t_{i} \leq t_{n} \leq t_{N}$,
+Typically the increments are spread evenly over the full window.
+In addition, two different weighting functions have been implemented.
+The first function employs constant weights, 
+\begin{eqnarray}    \label{eq:F1_i}
+F^{(1)}_{i}
+=\left\{ \begin{array}{ll}
+   0     &    {\rm if} \; \; \; t_{i} < t_{m}                \\
+   1/M &    {\rm if} \; \; \; t_{m} < t_{i} \leq t_{n} \\
+   0     &    {\rm if} \; \; \; t_{i} > t_{n}
+  \end{array} \right. 
+\end{eqnarray}
+where $M = m-n$.
+The second function employs peaked hat-like weights in order to give maximum 
+weight in the centre of the sub-window, with the weighting reduced 
+linearly to a small value at the window end-points:
+\begin{eqnarray}     \label{eq:F2_i}
+F^{(2)}_{i}
+=\left\{ \begin{array}{ll}
+   0                           &    {\rm if} \; \; \; t_{i}       <     t_{m}                        \\
+   \alpha \, i               &    {\rm if} \; \; \; t_{m}    \leq t_{i}    \leq   t_{M/2}   \\
+   \alpha \, (M - i +1) &    {\rm if} \; \; \; t_{M/2}  <    t_{i}    \leq   t_{n}       \\
+   0                            &   {\rm if} \; \; \; t_{i}        >    t_{n}
+  \end{array} \right.
+\end{eqnarray}
+where $\alpha^{-1} = \sum_{i=1}^{M/2} 2i$ and $M$ is assumed to be even. 
+The weights described by \autoref{eq:F2_i} provide a 
+smoother transition of the analysis trajectory from one assimilation cycle 
+to the next than that described by \autoref{eq:F1_i}.
+
+%==========================================================================
+% Divergence damping description %%%
+\section{Divergence damping initialisation}
+\label{sec:ASM_div_dmp}
+
+The velocity increments may be initialized by the iterative application of 
+a divergence damping operator. In iteration step $n$ new estimates of 
+velocity increments $u^{n}_I$ and $v^{n}_I$ are updated by:
+\begin{equation} \label{eq:asm_dmp}
+\left\{ \begin{aligned}
+ u^{n}_I = u^{n-1}_I + \frac{1}{e_{1u} } \delta _{i+1/2} \left( {A_D
+\;\chi^{n-1}_I } \right) \\
+\\
+ v^{n}_I = v^{n-1}_I + \frac{1}{e_{2v} } \delta _{j+1/2} \left( {A_D
+\;\chi^{n-1}_I } \right) \\
+\end{aligned} \right.,
+\end{equation}
+where
+\begin{equation} \label{eq:asm_div}
+\chi^{n-1}_I = \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
+                \left( {\delta _i \left[ {e_{2u}\,e_{3u}\,u^{n-1}_I} \right]
+                       +\delta _j \left[ {e_{1v}\,e_{3v}\,v^{n-1}_I} \right]} \right).
+\end{equation}
+By the application of \autoref{eq:asm_dmp} and \autoref{eq:asm_dmp} the divergence is filtered
+in each iteration, and the vorticity is left unchanged. In the presence of coastal boundaries
+with zero velocity increments perpendicular to the coast the divergence is strongly damped.
+This type of the initialisation reduces the vertical velocity magnitude  and alleviates the
+problem of the excessive unphysical vertical mixing in the first steps of the model 
+integration \citep{Talagrand_JAS72, Dobricic_al_OS07}. Diffusion coefficients are defined as 
+$A_D = \alpha e_{1t} e_{2t}$, where $\alpha = 0.2$. The divergence damping is activated by
+assigning to \np{nn\_divdmp} in the \textit{nam\_asminc} namelist a value greater than zero. 
+By choosing this value to be of the order of 100 the increments in the vertical velocity will 
+be significantly reduced.
+
+
+%==========================================================================
+
+\section{Implementation details}
+\label{sec:ASM_details}
+
+Here we show an example \ngn{namasm} namelist and the header of an example assimilation 
+increments file on the ORCA2 grid.
+
+%------------------------------------------namasm-----------------------------------------------------
+%
+\nlst{nam_asminc}
+%-------------------------------------------------------------------------------------------------------------
+
+The header of an assimilation increments file produced using the NetCDF tool
+\mbox{\textit{ncdump~-h}} is shown below
+
+\begin{clines}
+netcdf assim_background_increments {
+dimensions:
+        x = 182 ;
+        y = 149 ;
+        z = 31 ;
+        t = UNLIMITED ; // (1 currently)
+variables:
+        float nav_lon(y, x) ;
+        float nav_lat(y, x) ;
+        float nav_lev(z) ;
+        double time_counter(t) ;
+        double time ;
+        double z_inc_dateb ;
+        double z_inc_datef ;
+        double bckint(t, z, y, x) ;
+        double bckins(t, z, y, x) ;
+        double bckinu(t, z, y, x) ;
+        double bckinv(t, z, y, x) ;
+        double bckineta(t, y, x) ;
+
+// global attributes:
+                :DOMAIN_number_total = 1 ;
+                :DOMAIN_number = 0 ;
+                :DOMAIN_dimensions_ids = 1, 2 ;
+                :DOMAIN_size_global = 182, 149 ;
+                :DOMAIN_size_local = 182, 149 ;
+                :DOMAIN_position_first = 1, 1 ;
+                :DOMAIN_position_last = 182, 149 ;
+                :DOMAIN_halo_size_start = 0, 0 ;
+                :DOMAIN_halo_size_end = 0, 0 ;
+                :DOMAIN_type = "BOX" ;
+}
+\end{clines}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_CONFIG.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_CONFIG.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_CONFIG.tex	(revision 10321)
@@ -0,0 +1,306 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter � Configurations
+% ================================================================
+\chapter{Configurations}
+\label{chap:CFG}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Introduction
+% ================================================================
+\section{Introduction}
+\label{sec:CFG_intro}
+
+
+The purpose of this part of the manual is to introduce the \NEMO reference configurations. 
+These configurations are offered as means to explore various numerical and physical options, 
+thus allowing the user to verify that the code is performing in a manner consistent with that 
+we are running. This form of verification is critical as one adopts the code for his or her particular 
+research purposes. The reference configurations also provide a sense for some of the options available 
+in the code, though by no means are all options exercised in the reference configurations.
+
+%------------------------------------------namcfg----------------------------------------------------
+
+\nlst{namcfg}
+%-------------------------------------------------------------------------------------------------------------
+
+% ================================================================
+% 1D model configuration
+% ================================================================
+\section{C1D: 1D Water column model (\protect\key{c1d}) }
+\label{sec:CFG_c1d}
+
+$\ $\newline
+BE careful: to be re-written according to suppression of jpizoom and jpjzoom !!!!
+$\ $\newline
+
+The 1D model option simulates a stand alone water column within the 3D \NEMO system. 
+It can be applied to the ocean alone or to the ocean-ice system and can include passive tracers 
+or a biogeochemical model. It is set up by defining the position of the 1D water column in the grid 
+(see \textit{CONFIG/SHARED/namelist\_ref} ). 
+The 1D model is a very useful tool  
+\textit{(a)} to learn about the physics and numerical treatment of vertical mixing processes ; 
+\textit{(b)} to investigate suitable parameterisations of unresolved turbulence (surface wave
+breaking, Langmuir circulation, ...) ; 
+\textit{(c)} to compare the behaviour of different vertical mixing schemes  ; 
+\textit{(d)} to perform sensitivity studies on the vertical diffusion at a particular point of an ocean domain ; 
+\textit{(d)} to produce extra diagnostics, without the large memory requirement of the full 3D model.
+
+The methodology is based on the use of the zoom functionality over the smallest possible 
+domain : a 3x3 domain centered on the grid point of interest, 
+with some extra routines. There is no need to define a new mesh, bathymetry, 
+initial state or forcing, since the 1D model will use those of the configuration it is a zoom of. 
+The chosen grid point is set in \textit{\ngn{namcfg}} namelist by setting the \np{jpizoom} and \np{jpjzoom} 
+parameters to the indices of the location of the chosen grid point.
+
+The 1D model has some specifies. First, all the horizontal derivatives are assumed to be zero, and
+second, the two components of the velocity are moved on a $T$-point. 
+Therefore, defining \key{c1d} changes five main things in the code behaviour: 
+\begin{description}
+\item[(1)] the lateral boundary condition routine (\rou{lbc\_lnk}) set the value of the central column 
+of the 3x3 domain is imposed over the whole domain ; 
+\item[(3)] a call to \rou{lbc\_lnk} is systematically done when reading input data ($i.e.$ in \mdl{iom}) ; 
+\item[(3)] a simplified \rou{stp} routine is used (\rou{stp\_c1d}, see \mdl{step\_c1d} module) in which 
+both lateral tendancy terms and lateral physics are not called ; 
+\item[(4)] the vertical velocity is zero (so far, no attempt at introducing a Ekman pumping velocity 
+has been made) ; 
+\item[(5)] a simplified treatment of the Coriolis term is performed as $U$- and $V$-points are the same 
+(see \mdl{dyncor\_c1d}).
+\end{description}
+All the relevant \textit{\_c1d} modules can be found in the NEMOGCM/NEMO/OPA\_SRC/C1D directory of 
+the \NEMO distribution.
+
+% to be added:  a test case on the yearlong Ocean Weather Station (OWS) Papa dataset of Martin (1985)
+
+% ================================================================
+% ORCA family configurations
+% ================================================================
+\section{ORCA family: global ocean with tripolar grid}
+\label{sec:CFG_orca}
+
+The ORCA family is a series of global ocean configurations that are run together with 
+the LIM sea-ice model (ORCA-LIM) and possibly with PISCES biogeochemical model 
+(ORCA-LIM-PISCES), using various resolutions.
+An appropriate namelist is available in \path{CONFIG/ORCA2_LIM3_PISCES/EXP00/namelist_cfg} 
+for ORCA2.
+The domain of ORCA2 configuration is defined in \ifile{ORCA\_R2\_zps\_domcfg} file, this file is available in tar file in the wiki of NEMO : \\
+https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ReferenceConfigurations/ORCA2\_LIM3\_PISCES \\
+In this namelist\_cfg the name of domain input file is set in \ngn{namcfg} block of namelist. 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]   \begin{center}
+\includegraphics[width=0.98\textwidth]{Fig_ORCA_NH_mesh}
+\caption{  \protect\label{fig:MISC_ORCA_msh}     
+ORCA mesh conception. The departure from an isotropic Mercator grid start poleward of 20\degN.
+The two "north pole" are the foci of a series of embedded ellipses (blue curves) 
+which are determined analytically and form the i-lines of the ORCA mesh (pseudo latitudes). 
+Then, following \citet{Madec_Imbard_CD96}, the normal to the series of ellipses (red curves) is computed 
+which provide the j-lines of the mesh (pseudo longitudes).  }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%       ORCA tripolar grid
+% -------------------------------------------------------------------------------------------------------------
+\subsection{ORCA tripolar grid}
+\label{subsec:CFG_orca_grid}
+
+The ORCA grid is a tripolar is based on the semi-analytical method of \citet{Madec_Imbard_CD96}. 
+It allows to construct a global orthogonal curvilinear ocean mesh which has no singularity point inside 
+the computational domain since two north mesh poles are introduced and placed on lands.
+The method involves defining an analytical set of mesh parallels in the stereographic polar plan, 
+computing the associated set of mesh meridians, and projecting the resulting mesh onto the sphere. 
+The set of mesh parallels used is a series of embedded ellipses which foci are the two mesh north 
+poles (\autoref{fig:MISC_ORCA_msh}). The resulting mesh presents no loss of continuity in 
+either the mesh lines or the scale factors, or even the scale factor derivatives over the whole 
+ocean domain, as the mesh is not a composite mesh. 
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tbp]  \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_ORCA_NH_msh05_e1_e2}
+\includegraphics[width=0.80\textwidth]{Fig_ORCA_aniso}
+\caption {  \protect\label{fig:MISC_ORCA_e1e2}
+\textit{Top}: Horizontal scale factors ($e_1$, $e_2$) and 
+\textit{Bottom}: ratio of anisotropy ($e_1 / e_2$)
+for ORCA 0.5\deg ~mesh. South of 20\degN a Mercator grid is used ($e_1 = e_2$) 
+so that the anisotropy ratio is 1. Poleward of 20\degN, the two "north pole" 
+introduce a weak anisotropy over the ocean areas ($< 1.2$) except in vicinity of Victoria Island 
+(Canadian Arctic Archipelago). }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+The method is applied to Mercator grid ($i.e.$ same zonal and meridional grid spacing) poleward 
+of 20\degN, so that the Equator is a mesh line, which provides a better numerical solution 
+for equatorial dynamics. The choice of the series of embedded ellipses (position of the foci and 
+variation of the ellipses) is a compromise between maintaining  the ratio of mesh anisotropy 
+($e_1 / e_2$) close to one in the ocean (especially in area of strong eddy activities such as 
+the Gulf Stream) and keeping the smallest scale factor in the northern hemisphere larger 
+than the smallest one in the southern hemisphere.
+The resulting mesh is shown in \autoref{fig:MISC_ORCA_msh} and \autoref{fig:MISC_ORCA_e1e2} 
+for a half a degree grid (ORCA\_R05).
+The smallest ocean scale factor is found in along  Antarctica, while the ratio of anisotropy remains close to one except near the Victoria Island 
+in the Canadian Archipelago. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       ORCA-LIM(-PISCES) configurations
+% -------------------------------------------------------------------------------------------------------------
+\subsection{ORCA pre-defined resolution}
+\label{subsec:CFG_orca_resolution}
+
+
+The NEMO system is provided with five built-in ORCA configurations which differ in the 
+horizontal resolution. The value of the resolution is given by the resolution at the Equator 
+expressed in degrees. Each of configuration is set through the \textit{domain\_cfg} domain configuration file, 
+which sets the grid size and configuration name parameters. The NEMO System Team provides only ORCA2 domain input file "\ifile{ORCA\_R2\_zps\_domcfg}" file  (Tab. \autoref{tab:ORCA}).
+
+
+
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[!t]     \begin{center}
+\begin{tabular}{p{4cm} c c c c}
+Horizontal Grid         	             & \np{ORCA\_index} &  \np{jpiglo} & \np{jpjglo} &       \\  
+\hline  \hline
+\~4\deg	   &        4         &         92     &      76      &       \\
+\~2\deg        &        2         &       182     &    149      &        \\
+\~1\deg        &        1         &       362     &     292     &        \\
+\~0.5\deg     &        05       &       722     &     511     &        \\
+\~0.25\deg   &        025     &      1442    &   1021     &        \\
+%\key{orca\_r8}       &        8         &      2882    &   2042     &        \\
+%\key{orca\_r12}     &      12         &      4322    &   3062      &       \\
+\hline   \hline
+\end{tabular}
+\caption{ \protect\label{tab:ORCA}   
+Domain size of ORCA family configurations.
+The flag for configurations of ORCA family need to be set in \textit{domain\_cfg} file. }
+\end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+
+The ORCA\_R2 configuration has the following specificity : starting from a 2\deg~ORCA mesh, 
+local mesh refinements were applied to the Mediterranean, Red, Black and Caspian Seas, 
+so that the resolution is 1\deg \time 1\deg there. A local transformation were also applied 
+with in the Tropics in order to refine the meridional resolution up to 0.5\deg at the Equator.
+
+The ORCA\_R1 configuration has only a local tropical transformation  to refine the meridional 
+resolution up to 1/3\deg~at the Equator. Note that the tropical mesh refinements in ORCA\_R2 
+and R1 strongly increases the mesh anisotropy there.
+
+The ORCA\_R05 and higher global configurations do not incorporate any regional refinements.  
+
+For ORCA\_R1 and R025, setting the configuration key to 75 allows to use 75 vertical levels, 
+otherwise 46 are used. In the other ORCA configurations, 31 levels are used 
+(see \autoref{tab:orca_zgr} \sfcomment{HERE I need to put new table for ORCA2 values} and \autoref{fig:zgr}).
+
+Only the ORCA\_R2 is provided with all its input files in the \NEMO distribution. 
+It is very similar to that used as part of the climate model developed at IPSL for the 4th IPCC 
+assessment of climate change (Marti et al., 2009). It is also the basis for the \NEMO contribution 
+to the Coordinate Ocean-ice Reference Experiments (COREs) documented in \citet{Griffies_al_OM09}. 
+
+This version of ORCA\_R2 has 31 levels in the vertical, with the highest resolution (10m) 
+in the upper 150m (see \autoref{tab:orca_zgr} and \autoref{fig:zgr}). 
+The bottom topography and the coastlines are derived from the global atlas of Smith and Sandwell (1997). 
+The default forcing uses the boundary forcing from \citet{Large_Yeager_Rep04} (see \autoref{subsec:SBC_blk_core}), 
+which was developed for the purpose of running global coupled ocean-ice simulations 
+without an interactive atmosphere. This \citet{Large_Yeager_Rep04} dataset is available 
+through the \href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
+The "normal year" of \citet{Large_Yeager_Rep04} has been chosen of the \NEMO distribution 
+since release v3.3. 
+
+ORCA\_R2 pre-defined configuration can also be run with an AGRIF zoom over the Agulhas 
+current area ( \key{agrif}  defined) and, by setting the appropriate variables, see \path{CONFIG/SHARED/namelist_ref}
+a regional Arctic or peri-Antarctic configuration is extracted from an ORCA\_R2 or R05 configurations
+using sponge layers at open boundaries. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       GYRE family: double gyre basin
+% -------------------------------------------------------------------------------------------------------------
+\section{GYRE family: double gyre basin }
+\label{sec:CFG_gyre}
+
+The GYRE configuration \citep{Levy_al_OM10} has been built to simulate
+the seasonal cycle of a double-gyre box model. It consists in an idealized domain 
+similar to that used in the studies of \citet{Drijfhout_JPO94} and \citet{Hazeleger_Drijfhout_JPO98, 
+Hazeleger_Drijfhout_JPO99, Hazeleger_Drijfhout_JGR00, Hazeleger_Drijfhout_JPO00}, 
+over which an analytical seasonal forcing is applied. This allows to investigate the 
+spontaneous generation of a large number of interacting, transient mesoscale eddies 
+and their contribution to the large scale circulation. 
+
+The domain geometry is a closed rectangular basin on the $\beta$-plane centred 
+at $\sim$ 30\degN and rotated by 45\deg, 3180~km long, 2120~km wide 
+and 4~km deep (\autoref{fig:MISC_strait_hand}). 
+The domain is bounded by vertical walls and by a flat bottom. The configuration is 
+meant to represent an idealized North Atlantic or North Pacific basin. 
+The circulation is forced by analytical profiles of wind and buoyancy fluxes. 
+The applied forcings vary seasonally in a sinusoidal manner between winter 
+and summer extrema \citep{Levy_al_OM10}. 
+The wind stress is zonal and its curl changes sign at 22\degN and 36\degN. 
+It forces a subpolar gyre in the north, a subtropical gyre in the wider part of the domain 
+and a small recirculation gyre in the southern corner. 
+The net heat flux takes the form of a restoring toward a zonal apparent air 
+temperature profile. A portion of the net heat flux which comes from the solar radiation
+is allowed to penetrate within the water column. 
+The fresh water flux is also prescribed and varies zonally. 
+It is determined such as, at each time step, the basin-integrated flux is zero. 
+The basin is initialised at rest with vertical profiles of temperature and salinity 
+uniformly applied to the whole domain.
+
+The GYRE configuration is set like an analytical configuration. Through \np{ln\_read\_cfg}\forcode{ = .false.} in \textit{namcfg} namelist defined in the reference configuration \path{CONFIG/GYRE/EXP00/namelist_cfg} anaylitical definition of grid in GYRE is done in usrdef\_hrg, usrdef\_zgr routines. Its horizontal resolution 
+(and thus the size of the domain) is determined by setting \np{nn\_GYRE} in  \ngn{namusr\_def}: \\
+\np{jpiglo} $= 30 \times$ \np{nn\_GYRE} + 2   \\
+\np{jpjglo} $= 20 \times$ \np{nn\_GYRE} + 2   \\
+Obviously, the namelist parameters have to be adjusted to the chosen resolution, see the Configurations 
+pages on the NEMO web site (Using NEMO\/Configurations) .
+In the vertical, GYRE uses the default 30 ocean levels (\jp{jpk}\forcode{ = 31}) (\autoref{fig:zgr}).
+
+The GYRE configuration is also used in benchmark test as it is very simple to increase 
+its resolution and as it does not requires any input file. For example, keeping a same model size 
+on each processor while increasing the number of processor used is very easy, even though the 
+physical integrity of the solution can be compromised. Benchmark is activate via \np{ln\_bench}\forcode{ = .true.} in \ngn{namusr\_def} in namelist \path{CONFIG/GYRE/EXP00/namelist_cfg}.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]   \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_GYRE}
+\caption{  \protect\label{fig:GYRE}   
+Snapshot of relative vorticity at the surface of the model domain 
+in GYRE R9, R27 and R54. From \citet{Levy_al_OM10}.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%       AMM configuration
+% -------------------------------------------------------------------------------------------------------------
+\section{AMM: atlantic margin configuration}
+\label{sec:MISC_config_AMM}
+
+The AMM, Atlantic Margins Model, is a regional model covering the
+Northwest European Shelf domain on a regular lat-lon grid at
+approximately 12km horizontal resolution. The appropriate 
+\textit{\&namcfg} namelist  is available in \textit{CONFIG/AMM12/EXP00/namelist\_cfg}.
+It is used to build the correct dimensions of the AMM domain.
+
+This configuration tests several features of NEMO functionality specific
+to the shelf seas.
+In particular, the AMM uses $S$-coordinates in the vertical rather than
+$z$-coordinates and is forced with tidal lateral boundary conditions
+using a flather boundary condition from the BDY module.
+The AMM configuration  uses the GLS (\key{zdfgls}) turbulence scheme, the
+VVL non-linear free surface(\key{vvl}) and time-splitting
+(\key{dynspg\_ts}).
+
+In addition to the tidal boundary condition the model may also take
+open boundary conditions from a North Atlantic model. Boundaries may be
+completely omitted by setting \np{ln\_bdy} to false.
+Sample surface fluxes, river forcing and a sample initial restart file
+are included to test a realistic model run. The Baltic boundary is
+included within the river input file and is specified as a river source.
+Unlike ordinary river points the Baltic inputs also include salinity and
+temperature data.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIA.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIA.tex	(revision 10321)
@@ -0,0 +1,1878 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter I/O & Diagnostics
+% ================================================================
+\chapter{Output and Diagnostics (IOM, DIA, TRD, FLO)}
+\label{chap:DIA}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+% ================================================================
+%       Old Model Output 
+% ================================================================
+\section{Old model output (default)}
+\label{sec:DIA_io_old}
+
+The model outputs are of three types: the restart file, the output listing, and 
+the diagnostic output file(s).
+The restart file is used internally by the code when the user wants to start the model with 
+initial conditions defined by a previous simulation.
+It contains all the information that is necessary in order for there to be no changes in 
+the model results (even at the computer precision) between a run performed with several restarts and 
+the same run performed in one step.
+It should be noted that this requires that the restart file contains two consecutive time steps for 
+all the prognostic variables, and that it is saved in the same binary format as the one used by 
+the computer that is to read it (in particular, 32 bits binary IEEE format must not be used for this file).
+
+The output listing and file(s) are predefined but should be checked and eventually adapted to 
+the user's needs.
+The output listing is stored in the $ocean.output$ file.
+The information is printed from within the code on the logical unit $numout$.
+To locate these prints, use the UNIX command "\textit{grep -i numout}" in the source code directory.
+
+By default, diagnostic output files are written in NetCDF format.
+Since version 3.2, when defining \key{iomput}, an I/O server has been added which 
+provides more flexibility in the choice of the fields to be written as well as 
+how the writing work is distributed over the processors in massively parallel computing. 
+A complete description of the use of this I/O server is presented in the next section. 
+
+By default, \key{iomput} is not defined, NEMO produces NetCDF with the old IOIPSL library which 
+has been kept for compatibility and its easy installation.
+However, the IOIPSL library is quite inefficient on parallel machines and, since version 3.2, 
+many diagnostic options have been added presuming the use of \key{iomput}. 
+The usefulness of the default IOIPSL-based option is expected to reduce with each new release. 
+If \key{iomput} is not defined, output files and content are defined in the \mdl{diawri} module and 
+contain mean (or instantaneous if \key{diainstant} is defined) values over a regular period of 
+nn\_write time-steps (namelist parameter). 
+
+%\gmcomment{                    % start of gmcomment
+
+% ================================================================
+% Diagnostics
+% ================================================================
+\section{Standard model output (IOM)}
+\label{sec:DIA_iom}
+
+Since version 3.2, iomput is the NEMO output interface of choice. 
+It has been designed to be simple to use, flexible and efficient. 
+The two main purposes of iomput are: 
+
+\begin{enumerate}
+	\item The complete and flexible control of the output files through external XML files adapted by 
+			the user from standard templates.
+	\item To achieve high performance and scalable output through the optional distribution of 
+			all diagnostic output related tasks to dedicated processes.
+\end{enumerate}
+
+The first functionality allows the user to specify, without code changes or recompilation, 
+aspects of the diagnostic output stream, such as:
+
+\begin{itemize}
+	\item The choice of output frequencies that can be different for each file 
+			(including real months and years).
+	\item The choice of file contents; includes complete flexibility over which data are written in 
+			which files (the same data can be written in different files).
+	\item The possibility to split output files at a chosen frequency.
+	\item The possibility to extract a vertical or an horizontal subdomain.
+	\item The choice of the temporal operation to perform, 
+			e.g.: average, accumulate, instantaneous, min, max and once.
+	\item Control over metadata via a large XML "database" of possible output fields.
+\end{itemize}
+
+In addition, iomput allows the user to add in the code the output of any new variable (scalar, 2D or 
+3D) in a very easy way.
+All details of iomput functionalities are listed in the following subsections.
+Examples of the XML files that control the outputs can be found in: 
+\path{NEMOGCM/CONFIG/ORCA2_LIM/EXP00/iodef.xml}, \path{NEMOGCM/CONFIG/SHARED/field_def.xml} and 
+\path{NEMOGCM/CONFIG/SHARED/domain_def.xml}. \\
+
+The second functionality targets output performance when running in parallel (\key{mpp\_mpi}).
+Iomput provides the possibility to specify N dedicated I/O processes (in addition to 
+the NEMO processes) to collect and write the outputs.
+With an appropriate choice of N by the user, the bottleneck associated with the writing of 
+the output files can be greatly reduced.
+
+In version 3.6, the iom\_put interface depends on an external code called 
+\href{https://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/branchs/xios-1.0}{XIOS-1.0} 
+(use of revision 618 or higher is required).
+This new IO server can take advantage of the parallel I/O functionality of NetCDF4 to 
+create a single output file and therefore to bypass the rebuilding phase.
+Note that writing in parallel into the same NetCDF files requires that 
+your NetCDF4 library is linked to an HDF5 library that has been correctly compiled ($i.e.$ with 
+the configure option $--$enable-parallel).
+Note that the files created by iomput through XIOS are incompatible with NetCDF3.
+All post-processsing and visualization tools must therefore be compatible with 
+NetCDF4 and not only NetCDF3.
+
+Even if not using the parallel I/O functionality of NetCDF4, using N dedicated I/O servers, 
+where N is typically much less than the number of NEMO processors, 
+will reduce the number of output files created.
+This can greatly reduce the post-processing burden usually associated with using 
+large numbers of NEMO processors.
+Note that for smaller configurations, the rebuilding phase can be avoided, even without 
+a parallel-enabled NetCDF4 library, simply by employing only one dedicated I/O server.
+
+\subsection{XIOS: XML Inputs-Outputs Server}
+
+\subsubsection{Attached or detached mode?}
+
+Iomput is based on \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS}, 
+the io\_server developed by Yann Meurdesoif from IPSL.
+The behaviour of the I/O subsystem is controlled by settings in the external XML files listed above.
+Key settings in the iodef.xml file are the tags associated with each defined file.
+
+\xmlline|<variable id="using_server" type="bool"></variable>|
+
+The {\tt using\_server} setting determines whether or not the server will be used in 
+\textit{attached mode} (as a library) [{\tt> false <}] or in \textit{detached mode} (as 
+an external executable on N additional, dedicated cpus) [{\tt > true <}].
+The \textit{attached mode} is simpler to use but much less efficient for massively parallel applications.
+The type of each file can be either ''multiple\_file'' or ''one\_file''.
+
+In \textit{attached mode} and if the type of file is ''multiple\_file'', 
+then each NEMO process will also act as an IO server and produce its own set of output files.
+Superficially, this emulates the standard behaviour in previous versions.
+However, the subdomain written out by each process does not correspond to 
+the \forcode{jpi x jpj x jpk} domain actually computed by the process (although it may if \forcode{jpni=1}).
+Instead each process will have collected and written out a number of complete longitudinal strips.
+If the ''one\_file'' option is chosen then all processes will collect their longitudinal strips and 
+write (in parallel) to a single output file.
+
+In \textit{detached mode} and if the type of file is ''multiple\_file'', then 
+each stand-alone XIOS process will collect data for a range of complete longitudinal strips and 
+write to its own set of output files.
+If the ''one\_file'' option is chosen then all XIOS processes will collect their longitudinal strips and 
+write (in parallel) to a single output file. 
+Note running in detached mode requires launching a Multiple Process Multiple Data (MPMD) parallel job.
+The following subsection provides a typical example but the syntax will vary in 
+different MPP environments.
+
+\subsubsection{Number of cpu used by XIOS in detached mode}
+
+The number of cores used by the XIOS is specified when launching the model.
+The number of cores dedicated to XIOS should be from \texttildelow1/10 to \texttildelow1/50 of the number of 
+cores dedicated to NEMO.
+Some manufacturers suggest using O($\sqrt{N}$) dedicated IO processors for N processors but 
+this is a general recommendation and not specific to NEMO.
+It is difficult to provide precise recommendations because the optimal choice will depend on 
+the particular hardware properties of the target system 
+(parallel filesystem performance, available memory, memory bandwidth etc.) and 
+the volume and frequency of data to be created.
+Here is an example of 2 cpus for the io\_server and 62 cpu for nemo using mpirun:
+\cmd|mpirun -np 62 ./nemo.exe : -np 2 ./xios_server.exe|
+
+\subsubsection{Control of XIOS: the context in iodef.xml}
+
+As well as the {\tt using\_server} flag, other controls on the use of XIOS are set in 
+the XIOS context in iodef.xml.
+See the XML basics section below for more details on XML syntax and rules.
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|lXl|} \hline
+		variable name                                                           &
+		description                                                             &
+		example  \\	\hline	\hline
+		buffer\_size                                                            &
+		buffer size used by XIOS to send data from NEMO to XIOS. 
+		Larger is more efficient. 
+		Note that needed/used buffer sizes are summarized at the end of the job &
+		25000000 \\	\hline
+		buffer\_server\_factor\_size                                            &
+		ratio between NEMO and XIOS buffer size.
+		Should be 2.                                                            &
+		2        \\	\hline
+		info\_level                                                             &
+		verbosity level (0 to 100)                                              &
+		0        \\	\hline
+		using\_server                                                           &
+		activate attached(false) or detached(true) mode                         &
+		true     \\	\hline
+		using\_oasis                                                            &
+		XIOS is used with OASIS(true) or not (false)                            &
+		false    \\	\hline
+		oasis\_codes\_id                                                        &
+		when using oasis, define the identifier of NEMO in the namcouple. 
+		Note that the identifier of XIOS is xios.x                              &
+		oceanx   \\	\hline
+	\end{tabularx}
+\end{table}
+
+\subsection{Practical issues}
+
+\subsubsection{Installation}
+
+As mentioned, XIOS is supported separately and must be downloaded and compiled before 
+it can be used with NEMO.
+See the installation guide on the \href{http://forge.ipsl.jussieu.fr/ioserver/wiki}{XIOS} wiki for 
+help and guidance.
+NEMO will need to link to the compiled XIOS library.
+The 
+\href{https://forge.ipsl.jussieu.fr/nemo/wiki/Users/ModelInterfacing/InputsOutputs#Inputs-OutputsusingXIOS}
+{XIOS with NEMO}
+guide provides an example illustration of how this can be achieved.
+
+\subsubsection{Add your own outputs}
+
+It is very easy to add your own outputs with iomput.
+Many standard fields and diagnostics are already prepared ($i.e.$, steps 1 to 3 below have been done) and 
+simply need to be activated by including the required output in a file definition in iodef.xml (step 4).
+To add new output variables, all 4 of the following steps must be taken.
+
+\begin{enumerate}
+	\item[1.] in NEMO code, add a \forcode{CALL iom\_put( 'identifier', array )} where you want to 
+					output a 2D or 3D array.
+	\item[2.] If necessary, add \forcode{USE iom ! I/O manager library} to the list of used modules in 
+					the upper part of your module.
+	\item[3.] in the field\_def.xml file, add the definition of your variable using 
+					the same identifier you used in the f90 code (see subsequent sections for 
+					a details of the XML syntax and rules).
+For example:
+
+\begin{xmllines}
+<field_definition>
+	<field_group id="grid_T" grid_ref="grid_T_3D"> <!-- T grid -->
+	...
+		<field id="identifier" long_name="blabla" ... />   
+		...
+</field_definition> 
+\end{xmllines}
+
+Note your definition must be added to the field\_group whose reference grid is consistent with 
+the size of the array passed to iomput.
+The grid\_ref attribute refers to definitions set in iodef.xml which, in turn, reference grids and 
+axes either defined in the code (iom\_set\_domain\_attr and iom\_set\_axis\_attr in \mdl{iom}) or 
+defined in the domain\_def.xml file.
+$e.g.$:
+
+\begin{xmllines}
+<grid id="grid_T_3D" domain_ref="grid_T" axis_ref="deptht"/>
+\end{xmllines}
+
+Note, if your array is computed within the surface module each \np{nn\_fsbc} time\_step, 
+add the field definition within the field\_group defined with the id "SBC":
+\xmlcode{<field_group id="SBC" ...>} which has been defined with the correct frequency of 
+operations (iom\_set\_field\_attr in \mdl{iom})
+	\item[4.] add your field in one of the output files defined in iodef.xml 
+(again see subsequent sections for syntax and rules)
+
+\begin{xmllines}
+<file id="file1" .../>   
+...
+	<field field_ref="identifier" />   
+	...
+</file>   
+\end{xmllines}
+
+\end{enumerate}
+
+\subsection{XML fundamentals}
+
+\subsubsection{ XML basic rules}
+
+XML tags begin with the less-than character ("$<$") and end with the greater-than character ("$>$").
+You use tags to mark the start and end of elements, which are the logical units of information in 
+an XML document.
+In addition to marking the beginning of an element, XML start tags also provide a place to 
+specify attributes.
+An attribute specifies a single property for an element, using a name/value pair, for example: 
+\xmlcode{<a b="x" c="y" d="z"> ... </a>}.
+See \href{http://www.xmlnews.org/docs/xml-basics.html}{here} for more details.
+
+\subsubsection{Structure of the XML file used in NEMO}
+
+The XML file used in XIOS is structured by 7 families of tags: 
+context, axis, domain, grid, field, file and variable.
+Each tag family has hierarchy of three flavors (except for context):
+
+\begin{table} \scriptsize
+	\begin{tabular*}{\textwidth}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline
+		flavor  & description                                                                 &
+		example                          \\ \hline \hline
+		root    & declaration of the root element that can contain element groups or elements &
+		\xmlcode{<file_definition ... >} \\ \hline
+		group   & declaration of a group element that can contain element groups or elements  &
+		\xmlcode{<file_group      ... >} \\ \hline
+		element & declaration of an element that can contain elements                         &
+		\xmlcode{<file            ... >} \\ \hline
+	\end{tabular*}
+\end{table}
+
+Each element may have several attributes.
+Some attributes are mandatory, other are optional but have a default value and 
+other are completely optional.
+Id is a special attribute used to identify an element or a group of elements.
+It must be unique for a kind of element.
+It is optional, but no reference to the corresponding element can be done if it is not defined.
+
+The XML file is split into context tags that are used to isolate IO definition from different codes or 
+different parts of a code.
+No interference is possible between 2 different contexts.
+Each context has its own calendar and an associated timestep.
+In \NEMO, we used the following contexts (that can be defined in any order):
+
+\begin{table} \scriptsize
+	\begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline
+		context         &	description                                                                & 
+		example                              \\	\hline \hline
+		context xios    &	context containing information for XIOS                                    & 
+		\xmlcode{<context id="xios" ... >}   \\	\hline
+		context nemo    &	context containing IO information for NEMO (mother grid when using AGRIF)  & 
+		\xmlcode{<context id="nemo" ... >}   \\	\hline
+		context 1\_nemo &	context containing IO information for NEMO child grid 1 (when using AGRIF) & 
+		\xmlcode{<context id="1_nemo" ... >} \\	\hline
+		context n\_nemo &	context containing IO information for NEMO child grid n (when using AGRIF) & 
+		\xmlcode{<context id="n_nemo" ... >} \\	\hline
+	\end{tabular}
+\end{table}
+
+\noindent The xios context contains only 1 tag:
+
+\begin{table} \scriptsize
+	\begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline
+		context tag                                      & 
+		description                                      & 
+		example                              \\ \hline	\hline
+		variable\_definition                             & 
+		define variables needed by XIOS. 
+		This can be seen as a kind of namelist for XIOS. & 
+		\xmlcode{<variable_definition ... >} \\ \hline
+	\end{tabular}
+\end{table}
+
+\noindent Each context tag related to NEMO (mother or child grids) is divided into 5 parts 
+(that can be defined in any order):
+
+\begin{table} \scriptsize
+	\begin{tabular}{|p{0.15\textwidth}p{0.4\textwidth}p{0.35\textwidth}|} \hline
+		context tag        &	description                                                               & 
+		example                            \\ \hline \hline
+		field\_definition  &	define all variables that can potentially be outputted                    & 
+		\xmlcode{<field_definition ... >}  \\ \hline
+		file\_definition   &	define the netcdf files to be created and the variables they will contain & 
+		\xmlcode{<file_definition ... >}   \\ \hline
+		axis\_definition   &	define vertical axis                                                      & 
+		\xmlcode{<axis_definition ... >}   \\ \hline
+		domain\_definition &	define the horizontal grids                                               & 
+		\xmlcode{<domain_definition ... >} \\ \hline
+		grid\_definition   &	define the 2D and 3D grids (association of an axis and a domain)          & 
+		\xmlcode{<grid_definition ... >}   \\ \hline
+	\end{tabular}
+\end{table}
+
+\subsubsection{Nesting XML files}
+
+The XML file can be split in different parts to improve its readability and facilitate its use.
+The inclusion of XML files into the main XML file can be done through the attribute src:
+\xmlline|<context src="./nemo_def.xml" />|
+ 
+\noindent In NEMO, by default, the field and domain definition is done in 2 separate files:
+\path{NEMOGCM/CONFIG/SHARED/field_def.xml} and \path{NEMOGCM/CONFIG/SHARED/domain_def.xml} 
+that are included in the main iodef.xml file through the following commands:
+\begin{xmllines}
+<field_definition src="./field_def.xml" />
+<domain_definition src="./domain_def.xml" />
+\end{xmllines}
+
+\subsubsection{Use of inheritance}
+
+XML extensively uses the concept of inheritance.
+XML has a tree based structure with a parent-child oriented relation: 
+all children inherit attributes from parent, but an attribute defined in a child replace 
+the inherited attribute value. 
+Note that the special attribute ''id'' is never inherited. \\ \\
+example 1: Direct inheritance.
+
+\begin{xmllines}
+<field_definition operation="average" >
+	<field id="sst"                    />   <!-- averaged      sst --> 
+	<field id="sss" operation="instant"/>   <!-- instantaneous sss --> 
+</field_definition> 
+\end{xmllines}
+
+The field ''sst'' which is part (or a child) of the field\_definition will inherit the value ''average'' 
+of the attribute ''operation'' from its parent.
+Note that a child can overwrite the attribute definition inherited from its parents.
+In the example above, the field ''sss'' will for example output instantaneous values instead of 
+average values. \\ \\
+example 2: Inheritance by reference.
+
+\begin{xmllines}
+<field_definition>
+	<field id="sst" long_name="sea surface temperature" />
+	<field id="sss" long_name="sea surface salinity"    />
+</field_definition>
+<file_definition>
+	<file id="myfile" output_freq="1d" />   
+		<field field_ref="sst"                            />  <!-- default def -->
+		<field field_ref="sss" long_name="my description" />  <!-- overwrite   -->
+	</file>
+</file_definition> 
+\end{xmllines}
+
+Inherit (and overwrite, if needed) the attributes of a tag you are refering to.
+
+\subsubsection{Use of groups}
+
+Groups can be used for 2 purposes.
+Firstly, the group can be used to define common attributes to be shared by the elements of 
+the group through inheritance.
+In the following example, we define a group of field that will share a common grid ''grid\_T\_2D''.
+Note that for the field ''toce'', we overwrite the grid definition inherited from the group by 
+''grid\_T\_3D''.
+
+\begin{xmllines}
+<field_group id="grid_T" grid_ref="grid_T_2D">
+	<field id="toce" long_name="temperature"             unit="degC" grid_ref="grid_T_3D"/>
+	<field id="sst"  long_name="sea surface temperature" unit="degC"                     />
+	<field id="sss"  long_name="sea surface salinity"    unit="psu"                      />
+	<field id="ssh"  long_name="sea surface height"      unit="m"                        />
+	...
+\end{xmllines}
+
+Secondly, the group can be used to replace a list of elements.
+Several examples of groups of fields are proposed at the end of the file \path{CONFIG/SHARED/field_def.xml}.
+For example, a short list of the usual variables related to the U grid:
+
+\begin{xmllines}
+<field_group id="groupU" >
+	<field field_ref="uoce"  />
+	<field field_ref="suoce" />
+	<field field_ref="utau"  />
+</field_group>
+\end{xmllines}
+
+that can be directly included in a file through the following syntax:
+
+\begin{xmllines}
+<file id="myfile_U" output_freq="1d" />
+	<field_group group_ref="groupU" />
+	<field field_ref="uocetr_eff"   />  <!-- add another field -->
+</file>   
+\end{xmllines}
+
+\subsection{Detailed functionalities}
+
+The file \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml} provides several examples of the use of 
+the new functionalities offered by the XML interface of XIOS.
+
+\subsubsection{Define horizontal subdomains}
+
+Horizontal subdomains are defined through the attributs zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj of 
+the tag family domain.
+It must therefore be done in the domain part of the XML file. 
+For example, in \path{CONFIG/SHARED/domain_def.xml}, we provide the following example of a definition of 
+a 5 by 5 box with the bottom left corner at point (10,10).
+
+\begin{xmllines}
+<domain_group id="grid_T">
+	<domain id="myzoom" zoom_ibegin="10" zoom_jbegin="10" zoom_ni="5" zoom_nj="5" />
+\end{xmllines}
+
+The use of this subdomain is done through the redefinition of the attribute domain\_ref of 
+the tag family field.
+For example:
+
+\begin{xmllines}
+<file id="myfile_vzoom" output_freq="1d" >
+	<field field_ref="toce" domain_ref="myzoom"/>
+</file>
+\end{xmllines}
+
+Moorings are seen as an extrem case corresponding to a 1 by 1 subdomain. 
+The Equatorial section, the TAO, RAMA and PIRATA moorings are alredy registered in the code and 
+can therefore be outputted without taking care of their (i,j) position in the grid.
+These predefined domains can be activated by the use of specific domain\_ref:
+''EqT'', ''EqU'' or ''EqW'' for the equatorial sections and the mooring position for 
+TAO, RAMA and PIRATA followed by ''T'' (for example: ''8s137eT'', ''1.5s80.5eT'' ...)
+
+\begin{xmllines}
+<file id="myfile_vzoom" output_freq="1d" >
+	<field field_ref="toce" domain_ref="0n180wT"/>
+</file>
+\end{xmllines}
+
+Note that if the domain decomposition used in XIOS cuts the subdomain in several parts and if 
+you use the ''multiple\_file'' type for your output files, 
+you will endup with several files you will need to rebuild using unprovided tools (like ncpdq and ncrcat, 
+\href{http://nco.sourceforge.net/nco.html#Concatenation}{see nco manual}).
+We are therefore advising to use the ''one\_file'' type in this case.
+
+\subsubsection{Define vertical zooms}
+
+Vertical zooms are defined through the attributs zoom\_begin and zoom\_end of the tag family axis. 
+It must therefore be done in the axis part of the XML file. 
+For example, in \path{NEMOGCM/CONFIG/ORCA2_LIM/iodef_demo.xml}, we provide the following example:
+
+\begin{xmllines}
+<axis_group id="deptht" long_name="Vertical T levels" unit="m" positive="down" >
+	<axis id="deptht" />
+	<axis id="deptht_myzoom" zoom_begin="1" zoom_end="10" />
+\end{xmllines}
+
+The use of this vertical zoom is done through the redefinition of the attribute axis\_ref of 
+the tag family field.
+For example:
+
+\begin{xmllines}
+<file id="myfile_hzoom" output_freq="1d" >
+	<field field_ref="toce" axis_ref="deptht_myzoom"/>
+</file>
+\end{xmllines}
+
+\subsubsection{Control of the output file names}
+
+The output file names are defined by the attributs ''name'' and ''name\_suffix'' of the tag family file.
+For example:
+
+\begin{xmllines}
+<file_group id="1d" output_freq="1d" name="myfile_1d" > 
+	<file id="myfileA" name_suffix="_AAA" > <!-- will create file "myfile_1d_AAA"  -->
+		...
+	</file>
+	<file id="myfileB" name_suffix="_BBB" > <!-- will create file "myfile_1d_BBB" -->
+		...
+	</file>
+</file_group>
+\end{xmllines}
+
+However it is often very convienent to define the file name with the name of the experiment, 
+the output file frequency and the date of the beginning and the end of the simulation 
+(which are informations stored either in the namelist or in the XML file).
+To do so, we added the following rule: if the id of the tag file is ''fileN'' (where N = 1 to 999 on 
+1 to 3 digits) or one of the predefined sections or moorings (see next subsection), 
+the following part of the name and the name\_suffix (that can be inherited) will be automatically 
+replaced by:
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|lX|} \hline
+		\centering placeholder string &
+		automatically replaced by                          \\ \hline \hline
+		\centering @expname@          &
+		the experiment name (from cn\_exp in the namelist) \\ \hline
+		\centering @freq@             &
+		output frequency (from attribute output\_freq)     \\ \hline
+		\centering @startdate@        &
+		starting date of the simulation (from nn\_date0 in the restart or the namelist). \newline
+		\verb?yyyymmdd?          format                   \\ \hline
+		\centering @startdatefull@    &
+		starting date of the simulation (from nn\_date0 in the restart or the namelist). \newline
+		\verb?yyyymmdd_hh:mm:ss? format                    \\ \hline
+		\centering @enddate@          &
+		ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist). \newline
+		\verb?yyyymmdd?          format                    \\ \hline
+		\centering @enddatefull@      &
+		ending date of the simulation   (from nn\_date0 and nn\_itend  in the namelist). \newline
+		\verb?yyyymmdd_hh:mm:ss? format                    \\ \hline
+	\end{tabularx}
+\end{table}
+
+\noindent For example, 
+\xmlline|<file id="myfile_hzoom" name="myfile_@expname@_@startdate@_freq@freq@" output_freq="1d" >|
+
+\noindent with the namelist:
+\begin{forlines}
+cn_exp    = "ORCA2"
+nn_date0  = 19891231
+ln_rstart = .false.
+\end{forlines}
+
+\noindent will give the following file name radical:
+\ifile{myfile\_ORCA2\_19891231\_freq1d}
+
+\subsubsection{Other controls of the XML attributes from NEMO}
+
+The values of some attributes are defined by subroutine calls within NEMO 
+(calls to iom\_set\_domain\_attr, iom\_set\_axis\_attr and iom\_set\_field\_attr in \mdl{iom}). 
+Any definition given in the XML file will be overwritten. 
+By convention, these attributes are defined to ''auto'' (for string) or ''0000'' (for integer) in 
+the XML file (but this is not necessary). \\
+
+Here is the list of these attributes: \\
+
+\begin{table} \scriptsize
+\begin{tabularx}{\textwidth}{|X|c|c|c|}   \hline
+	tag ids affected by automatic definition of some of their attributes & 
+	name attribute                                                       & 
+	attribute value                      \\ \hline \hline
+	field\_definition                                                    & 
+	freq\_op                                                             & 
+	\np{rn\_rdt}                         \\ \hline
+	SBC                                                                  & 
+	freq\_op                                                             & 
+	\np{rn\_rdt} $\times$ \np{nn\_fsbc}  \\ \hline
+	ptrc\_T                                                              & 
+	freq\_op                                                             & 
+	\np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline
+	diad\_T                                                              & 
+	freq\_op                                                             & 
+	\np{rn\_rdt} $\times$ \np{nn\_dttrc} \\ \hline
+	EqT, EqU, EqW                                                        & 
+	jbegin, ni,                                                          & 
+	according to the grid                \\
+                                                                        & 
+	name\_suffix                                                         & 
+                                        \\ \hline
+	TAO, RAMA and PIRATA moorings                                        & 
+	zoom\_ibegin, zoom\_jbegin,                                          & 
+	according to the grid                \\
+                                                                        & 
+	name\_suffix                                                         & 
+                                        \\ \hline
+\end{tabularx}
+\end{table}
+
+\subsubsection{Advanced use of XIOS functionalities}
+
+\subsection{XML reference tables}
+\label{subsec:IOM_xmlref}
+
+\begin{enumerate}
+\item Simple computation: directly define the computation when refering to the variable in 
+the file definition.
+
+\begin{xmllines}
+<field field_ref="sst"  name="tosK"  unit="degK" > sst + 273.15 </field>
+<field field_ref="taum" name="taum2" unit="N2/m4" long_name="square of wind stress module" >	taum * taum </field>
+<field field_ref="qt"   name="stupid_check" > qt - qsr - qns </field>
+\end{xmllines}
+
+\item Simple computation: define a new variable and use it in the file definition.
+
+in field\_definition:
+
+\begin{xmllines}
+<field id="sst2" long_name="square of sea surface temperature" unit="degC2" >  sst * sst </field >
+\end{xmllines}
+
+in file\_definition:
+
+\begin{xmllines}
+<field field_ref="sst2" > sst2 </field>
+\end{xmllines}
+
+Note that in this case, the following syntaxe \xmlcode{<field field_ref="sst2" />} is not working as 
+sst2 won't be evaluated.
+
+\item Change of variable precision:
+
+\begin{xmllines}
+<!-- force to keep real 8 -->
+<field field_ref="sst" name="tos_r8" prec="8" />
+<!-- integer 2  with add_offset and scale_factor attributes -->
+<field field_ref="sss" name="sos_i2" prec="2" add_offset="20." scale_factor="1.e-3" />
+\end{xmllines}
+
+Note that, then the code is crashing, writting real4 variables forces a numerical convection from 
+real8 to real4 which will create an internal error in NetCDF and will avoid the creation of 
+the output files.
+Forcing double precision outputs with prec="8" (for example in the field\_definition) will 
+avoid this problem.
+
+\item add user defined attributes:
+
+\begin{xmllines}
+<file_group id="1d" output_freq="1d" output_level="10" enabled=".true."> <!-- 1d files --> 
+	<file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
+		<field field_ref="sst" name="tos" >
+			<variable id="my_attribute1" type="string"  > blabla </variable>
+			<variable id="my_attribute2" type="integer" > 3      </variable>
+			<variable id="my_attribute3" type="float"   > 5.0    </variable>
+		</field>
+		<variable id="my_global_attribute" type="string" > blabla_global </variable>
+	</file>
+</file_group> 
+\end{xmllines}
+
+\item use of the ``@'' function: example 1, weighted temporal average
+
+ - define a new variable in field\_definition
+
+\begin{xmllines}
+<field id="toce_e3t" long_name="temperature * e3t" unit="degC*m" grid_ref="grid_T_3D" >toce * e3t</field>
+\end{xmllines}
+
+ - use it when defining your file.
+
+\begin{xmllines}
+<file_group id="5d" output_freq="5d"  output_level="10" enabled=".true." >  <!-- 5d files -->  
+	<file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
+		<field field_ref="toce" operation="instant" freq_op="5d" > @toce_e3t / @e3t </field>
+	</file>
+</file_group> 
+\end{xmllines}
+
+The freq\_op="5d" attribute is used to define the operation frequency of the ``@'' function: here 5 day.
+The temporal operation done by the ``@'' is the one defined in the field definition: 
+here we use the default, average.
+So, in the above case, @toce\_e3t will do the 5-day mean of toce*e3t.
+Operation="instant" refers to the temporal operation to be performed on the field''@toce\_e3t / @e3t'': 
+here the temporal average is alreday done by the ``@'' function so we just use instant to do the ratio of 
+the 2 mean values.
+field\_ref="toce" means that attributes not explicitely defined, are inherited from toce field.
+Note that in this case, freq\_op must be equal to the file output\_freq.
+
+\item use of the ``@'' function: example 2, monthly SSH standard deviation
+
+ - define a new variable in field\_definition
+
+\begin{xmllines}
+<field id="ssh2" long_name="square of sea surface temperature" unit="degC2" > ssh * ssh </field >
+\end{xmllines}
+
+ - use it when defining your file.
+
+\begin{xmllines}
+<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->  
+	<file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
+		<field field_ref="ssh" name="sshstd" long_name="sea_surface_temperature_standard_deviation" 
+		operation="instant" freq_op="1m" >
+			sqrt( @ssh2 - @ssh * @ssh )
+		</field>
+	</file>
+</file_group> 
+\end{xmllines}
+
+The freq\_op="1m" attribute is used to define the operation frequency of the ``@'' function: here 1 month.
+The temporal operation done by the ``@'' is the one defined in the field definition: 
+here we use the default, average.
+So, in the above case, @ssh2 will do the monthly mean of ssh*ssh.
+Operation="instant" refers to the temporal operation to be performed on 
+the field ''sqrt( @ssh2 - @ssh * @ssh )'': 
+here the temporal average is alreday done by the ``@'' function so we just use instant.
+field\_ref="ssh" means that attributes not explicitely defined, are inherited from ssh field.
+Note that in this case, freq\_op must be equal to the file output\_freq.
+
+\item use of the ``@'' function: example 3, monthly average of SST diurnal cycle
+
+ - define 2 new variables in field\_definition
+
+\begin{xmllines}
+<field id="sstmax" field_ref="sst" long_name="max of sea surface temperature" operation="maximum" />
+<field id="sstmin" field_ref="sst" long_name="min of sea surface temperature" operation="minimum" />
+\end{xmllines}
+
+ - use these 2 new variables when defining your file.
+
+\begin{xmllines}
+<file_group id="1m" output_freq="1m"  output_level="10" enabled=".true." >  <!-- 1m files -->  
+	<file id="file1" name_suffix="_grid_T" description="ocean T grid variables" >
+		<field field_ref="sst" name="sstdcy" long_name="amplitude of sst diurnal cycle" operation="average" freq_op="1d" >
+			@sstmax - @sstmin
+		</field>
+	</file>
+</file_group> 
+\end{xmllines}
+
+\end{enumerate}
+
+The freq\_op="1d" attribute is used to define the operation frequency of the ``@'' function: here 1 day.
+The temporal operation done by the ``@'' is the one defined in the field definition: here maximum for 
+sstmax and minimum for sstmin.
+So, in the above case, @sstmax will do the daily max and @sstmin the daily min.
+Operation="average" refers to the temporal operation to be performed on the field ``@sstmax - @sstmin'': 
+here monthly mean (of daily max - daily min of the sst).
+field\_ref="sst" means that attributes not explicitely defined, are inherited from sst field.
+
+\subsubsection{Tag list per family}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|l|X|} \hline
+	tag name                                                                                     &
+	description                                                                                  &
+	accepted attribute                                                                           &
+	child of                                                                                     &
+	parent of                       \\ \hline \hline
+	simulation                                                                                   &
+	this tag is the root tag which encapsulates all the content of the XML file                  &
+	none                                                                                         &
+	none                                                                                         &
+	context                         \\ \hline
+	context                                                                                      &
+	encapsulates parts of the XML file dedicated to different codes or different parts of a code &
+	id (''xios'', ''nemo'' or ''n\_nemo'' for the nth AGRIF zoom), src, time\_origin             &
+	simulation                                                                                   &
+	all root tags: ... \_definition \\ \hline
+	\end{tabularx}
+	\caption{Context tags}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline
+	tag name                                                                                & 
+	description                                                                             & 
+	accepted attribute                                                                      & 
+	child of                                                                                & 
+	parent of             \\ \hline \hline
+	field\_definition                                                                       & 
+	encapsulates the definition of all the fields that can potentially be outputted         & 
+	axis\_ref, default\_value, domain\_ref, enabled, grid\_ref, level, operation, prec, src & 
+	context                                                                                 & 
+	field or field\_group \\ \hline
+	field\_group                                                                            & 
+	encapsulates a group of fields                                                          & 
+	axis\_ref, default\_value, domain\_ref, enabled, group\_ref, grid\_ref,
+	id, level, operation, prec, src                                                         & 
+	field\_definition, field\_group, file                                                   & 
+	field or field\_group \\ \hline
+	field                                                                                   & 
+	define a specific field                                                                 & 
+	axis\_ref, default\_value, domain\_ref, enabled, field\_ref, grid\_ref,
+	id, level, long\_name, name, operation, prec, standard\_name, unit                      & 
+	field\_definition, field\_group, file                                                   & 
+	none                  \\ \hline
+	\end{tabularx}
+	\caption{Field tags ("\tt{field\_*}")}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|l|} \hline
+	tag name                                                            & 
+	description                                                         & 
+	accepted attribute                                                  & 
+	child of                                                            & 
+	parent of           \\ \hline \hline
+	file\_definition                                                    & 
+	encapsulates the definition of all the files that will be outputted & 
+	enabled, min\_digits, name, name\_suffix, output\_level,
+	split\_freq\_format, split\_freq, sync\_freq, type, src             & 
+	context                                                             & 
+	file or file\_group \\ \hline
+	file\_group                                                         & 
+	encapsulates a group of files that will be outputted                & 
+	enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level,
+	split\_freq\_format, split\_freq, sync\_freq, type, src             & 
+	file\_definition, file\_group                                       & 
+	file or file\_group \\ \hline
+	file                                                                & 
+	define the contents of a file to be outputted                       & 
+	enabled, description, id, min\_digits, name, name\_suffix, output\_freq, output\_level,
+	split\_freq\_format, split\_freq, sync\_freq, type, src             & 
+	file\_definition, file\_group                                       & 
+	field               \\ \hline
+	\end{tabularx}
+	\caption{File tags ("\tt{file\_*}")}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline
+	tag name                                                                               & 
+	description                                                                            & 
+	accepted attribute                                                                     & 
+	child of                                                                               & 
+	parent of         \\ \hline \hline
+	axis\_definition                                                                       & 
+	define all the vertical axis potentially used by the variables                         & 
+	src                                                                                    & 
+	context                                                                                & 
+	axis\_group, axis \\ \hline
+	axis\_group                                                                            & 
+	encapsulates a group of vertical axis                                                  & 
+	id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
+	axis\_definition, axis\_group                                                          & 
+	axis\_group, axis \\ \hline
+	axis                                                                                   & 
+	define a vertical axis                                                                 & 
+	id, lon\_name, positive, src, standard\_name, unit, zoom\_begin, zoom\_end, zoom\_size & 
+	axis\_definition, axis\_group                                                          & 
+	none					\\ \hline
+	\end{tabularx}
+	\caption{Axis tags ("\tt{axis\_*}")}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline
+	tag name                                                            & 
+	description                                                         & 
+	accepted attribute                                                  & 
+	child of                                                            & 
+	parent of               \\ \hline \hline
+	domain\_\-definition                                                & 
+	define all the horizontal domains potentially used by the variables & 
+	src                                                                 & 
+	context                                                             & 
+	domain\_\-group, domain \\ \hline
+	domain\_group                                                       & 
+	encapsulates a group of horizontal domains                          & 
+	id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  & 
+	domain\_\-definition, domain\_group                                 & 
+	domain\_\-group, domain \\ \hline
+	domain                                                              & 
+	define an horizontal domain                                         & 
+	id, lon\_name, src, zoom\_ibegin, zoom\_jbegin, zoom\_ni, zoom\_nj  & 
+	domain\_\-definition, domain\_group                                 & 
+	none                    \\ \hline
+	\end{tabularx}
+	\caption{Domain tags ("\tt{domain\_*)}"}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|X|} \hline
+	tag name                                                                                     &
+	description                                                                                  &
+	accepted attribute                                                                           &
+	child of                                                                                     &
+	parent of                       \\ \hline \hline
+	grid\_definition                                                                               &
+	define all the grid (association of a domain and/or an axis) potentially used by the variables &
+	src                                                                                            &
+	context                                                                                        &
+	grid\_group, grid	\\ \hline
+	grid\_group                                                                                    &
+	encapsulates a group of grids                                                                  &
+	id, domain\_ref,axis\_ref                                                                      &
+	grid\_definition, grid\_group                                                                  &
+	grid\_group, grid	\\ \hline
+   grid                                                                                           &
+	define a grid                                                                                  &
+	id, domain\_ref,axis\_ref                                                                      &
+	grid\_definition, grid\_group                                                                  &
+	none 					\\ \hline
+	\end{tabularx}
+	\caption{Grid tags ("\tt{grid\_*}")}
+\end{table}
+
+\subsubsection{Attributes list per family}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|l|l|} \hline
+		attribute name                           & 
+		description                              & 
+		example                                  & 
+		accepted by            \\ \hline \hline
+		axis\_ref                                & 
+		refers to the id of a vertical axis      & 
+		axis\_ref="deptht"                       & 
+		field, grid families   \\	\hline
+		domain\_ref                              & 
+		refers to the id of a domain             & 
+		domain\_ref="grid\_T"                    & 
+		field or grid families \\ \hline
+		field\_ref                               & 
+		id of the field we want to add in a file & 
+		field\_ref="toce"                        & 
+		field                  \\ \hline
+		grid\_ref                                & 
+		refers to the id of a grid               & 
+		grid\_ref="grid\_T\_2D"                  & 
+		field family           \\ \hline
+		group\_ref                               & 
+		refer to a group of variables            & 
+		group\_ref="mooring"                     & 
+		field\_group           \\ \hline
+	\end{tabularx}
+	\caption{Reference attributes ("\tt{*\_ref}")}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|l|l|} \hline
+		attribute name                                     & 
+		description                                        & 
+		example                                            & 
+		accepted by   \\ \hline \hline
+		zoom\_ibegin                                       & 
+		starting point along x direction of the zoom.
+		Automatically defined for TAO/RAMA/PIRATA moorings & 
+		zoom\_ibegin="1"                                   & 
+		domain family \\ \hline
+		zoom\_jbegin                                       & 
+		starting point along y direction of the zoom.
+		Automatically defined for TAO/RAMA/PIRATA moorings & 
+		zoom\_jbegin="1"                                   & 
+		domain family \\ \hline
+		zoom\_ni                                           & 
+		zoom extent along x direction                      & 
+		zoom\_ni="1"                                       & 
+		domain family \\ \hline
+		zoom\_nj                                           & 
+		zoom extent along y direction                      & 
+		zoom\_nj="1"                                       & 
+		domain family \\ \hline
+	\end{tabularx}
+	\caption{Domain attributes ("\tt{zoom\_*}")}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|l|l|} \hline
+		attribute name                                                                                       &
+		description                                                                                          &
+		example                                                                                              &
+		accepted by                            \\ \hline \hline
+		min\_digits                                                                                          &
+		specify the minimum of digits used in the core number in the name of the NetCDF file                 &
+		min\_digits="4"                                                                                      &
+		file family                            \\ \hline
+		name\_suffix                                                                                         &
+		suffix to be inserted after the name and before the cpu number and the ''.nc'' termination of a file &
+		name\_suffix="\_myzoom"                                                                              &
+		file family                            \\ \hline
+		output\_level                                                                                        &
+		output priority of variables in a file: 0 (high) to 10 (low).
+		All variables listed in the file with a level smaller or equal to output\_level will be output.
+		Other variables won't be output even if they are listed in the file.                                 &
+		output\_level="10"                                                                                   &
+		file family                            \\ \hline
+		split\_freq                                                                                          &
+		frequency at which to temporally split output files.
+		Units can be ts (timestep), y, mo, d, h, mi, s.
+		Useful for long runs to prevent over-sized output files.                                             &
+		split\_freq="1mo"                                                                                    &
+		file family                            \\ \hline
+		split\_freq\-\_format                                                                                &
+		date format used in the name of temporally split output files.
+		Can be specified using the following syntaxes: \%y, \%mo, \%d, \%h \%mi and \%s                      &
+		split\_freq\_format= "\%y\%mo\%d"                                                                    &
+		file family                            \\ \hline
+		sync\_freq                                                                                           &
+		NetCDF file synchronization frequency (update of the time\_counter).
+		Units can be ts (timestep), y, mo, d, h, mi, s.                                                      &
+		sync\_freq="10d"                                                                                     &
+		file family                            \\ \hline
+		type (1)                                                                                             &
+		specify if the output files are to be split spatially (multiple\_file) or not (one\_file)            &
+		type="multiple\_file"                                                                                &
+		file familly                           \\ \hline
+	\end{tabularx}
+	\caption{File attributes}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|l|l|} \hline
+		attribute name                                                                                       &
+		description                                                                                          &
+		example                                                                                              &
+		accepted by                            \\ \hline \hline
+		default\_value                                                                                       &
+		missing\_value definition                                                                            &
+		default\_value="1.e20"                                                                               &
+		field family                           \\ \hline
+		level                                                                                                &
+		output priority of a field: 0 (high) to 10 (low)                                                     &
+		level="1"                                                                                            &
+		field family                           \\ \hline
+		operation                                                                                            &
+		type of temporal operation: average, accumulate, instantaneous, min, max and once                    &
+		operation="average"                                                                                  &
+		field family                           \\ \hline
+		output\_freq                                                                                         &
+		operation frequency. units can be ts (timestep), y, mo, d, h, mi, s.                                 &
+		output\_freq="1d12h"                                                                                 &
+		field family                           \\ \hline
+		prec                                                                                                 &
+		output precision: real 4 or real 8                                                                   &
+		prec="4"                                                                                             &
+		field family                           \\ \hline
+		long\_name                                                                                           &
+		define the long\_name attribute in the NetCDF file                                                   &
+		long\_name="Vertical T levels"                                                                       &
+		field                                  \\ \hline
+		standard\_name                                                                                       &
+		define the standard\_name attribute in the NetCDF file                                               &
+		standard\_name= "Eastward\_Sea\_Ice\_Transport"                                                      &
+		field                                  \\ \hline
+	\end{tabularx}
+	\caption{Field attributes}
+\end{table}
+
+\begin{table} \scriptsize
+	\begin{tabularx}{\textwidth}{|l|X|X|X|} \hline
+		attribute name                                                                                       &
+		description                                                                                          &
+		example                                                                                              &
+		accepted by                            \\ \hline \hline
+		enabled                                                                                              &
+		switch on/off the output of a field or a file                                                        &
+		enabled=".true."                                                                                     &
+		field, file families                   \\ \hline
+		description                                                                                          &
+		just for information, not used                                                                       &
+		description="ocean T grid variables"                                                                 &
+		all tags                               \\ \hline
+		id                                                                                                   &
+		allow to identify a tag                                                                              &
+		id="nemo"                                                                                            &
+		accepted by all tags except simulation \\ \hline
+		name                                                                                                 &
+		name of a variable or a file. If the name of a file is undefined, its id is used as a name           &
+		name="tos"                                                                                           &
+		field or file families                 \\ \hline
+		positive                                                                                             &
+		convention used for the orientation of vertival axis (positive downward in \NEMO).                   &
+		positive="down"                                                                                      &
+		axis family                            \\ \hline
+		src                                                                                                  &
+		allow to include a file                                                                              &
+		src="./field\_def.xml"                                                                               &
+		accepted by all tags except simulation \\ \hline
+		time\_origin                                                                                         &
+		specify the origin of the time counter                                                               &
+		time\_origin="1900-01-01 00:00:00"                                                                   &
+		context                                \\ \hline
+		type (2)                                                                                             &
+		define the type of a variable tag                                                                    &
+		type="boolean"                                                                                       &
+		variable                               \\ \hline
+		unit                                                                                                 &
+		unit of a variable or the vertical axis                                                              &
+		unit="m"                                                                                             &
+		field and axis families                \\ \hline
+	\end{tabularx}
+	\caption{Miscellaneous attributes}
+\end{table}
+
+\subsection{CF metadata standard compliance}
+
+Output from the XIOS-1.0 IO server is compliant with 
+\href{http://cfconventions.org/Data/cf-conventions/cf-conventions-1.5/build/cf-conventions.html}{version 1.5} 
+of the CF metadata standard. 
+Therefore while a user may wish to add their own metadata to the output files (as demonstrated in 
+example 4 of section \autoref{subsec:IOM_xmlref}) the metadata should, for the most part, comply with 
+the CF-1.5 standard.
+
+Some metadata that may significantly increase the file size (horizontal cell areas and 
+vertices) are controlled by the namelist parameter \np{ln\_cfmeta} in the \ngn{namrun} namelist.
+This must be set to true if these metadata are to be included in the output files.
+
+
+% ================================================================
+%       NetCDF4 support
+% ================================================================
+\section{NetCDF4 support (\protect\key{netcdf4})}
+\label{sec:DIA_nc4}
+
+Since version 3.3, support for NetCDF4 chunking and (loss-less) compression has been included.
+These options build on the standard NetCDF output and allow the user control over the size of 
+the chunks via namelist settings.
+Chunking and compression can lead to significant reductions in file sizes for a small runtime overhead.
+For a fuller discussion on chunking and other performance issues the reader is referred to 
+the NetCDF4 documentation found 
+\href{http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Chunking}{here}.
+
+The new features are only available when the code has been linked with a NetCDF4 library 
+(version 4.1 onwards, recommended) which has been built with HDF5 support 
+(version 1.8.4 onwards, recommended).
+Datasets created with chunking and compression are not backwards compatible with 
+NetCDF3 "classic" format but most analysis codes can be relinked simply with the new libraries and 
+will then read both NetCDF3 and NetCDF4 files.
+NEMO executables linked with NetCDF4 libraries can be made to produce NetCDF3 files by 
+setting the \np{ln\_nc4zip} logical to false in the \textit{namnc4} namelist:
+
+%------------------------------------------namnc4----------------------------------------------------
+
+\nlst{namnc4}
+%-------------------------------------------------------------------------------------------------------------
+
+If \key{netcdf4} has not been defined, these namelist parameters are not read.
+In this case, \np{ln\_nc4zip} is set false and dummy routines for 
+a few NetCDF4-specific functions are defined.
+These functions will not be used but need to be included so that compilation is possible with 
+NetCDF3 libraries.
+
+When using NetCDF4 libraries, \key{netcdf4} should be defined even if the intention is to 
+create only NetCDF3-compatible files.
+This is necessary to avoid duplication between the dummy routines and 
+the actual routines present in the library.
+Most compilers will fail at compile time when faced with such duplication.
+Thus when linking with NetCDF4 libraries the user must define \key{netcdf4} and 
+control the type of NetCDF file produced via the namelist parameter.
+
+Chunking and compression is applied only to 4D fields and there is no advantage in 
+chunking across more than one time dimension since previously written chunks would have to 
+be read back and decompressed before being added to.
+Therefore, user control over chunk sizes is provided only for the three space dimensions.
+The user sets an approximate number of chunks along each spatial axis.
+The actual size of the chunks will depend on global domain size for mono-processors or, 
+more likely, the local processor domain size for distributed processing.
+The derived values are subject to practical minimum values (to avoid wastefully small chunk sizes) and 
+cannot be greater than the domain size in any dimension.
+The algorithm used is:
+
+\begin{forlines}
+ichunksz(1) = MIN(idomain_size, MAX((idomain_size-1) / nn_nchunks_i + 1 ,16 ))
+ichunksz(2) = MIN(jdomain_size, MAX((jdomain_size-1) / nn_nchunks_j + 1 ,16 ))
+ichunksz(3) = MIN(kdomain_size, MAX((kdomain_size-1) / nn_nchunks_k + 1 , 1 ))
+ichunksz(4) = 1
+\end{forlines}
+
+\noindent As an example, setting:
+
+\begin{forlines}
+nn_nchunks_i=4, nn_nchunks_j=4 and nn_nchunks_k=31
+\end{forlines}
+
+\noindent for a standard ORCA2\_LIM configuration gives chunksizes of {\small\tt 46x38x1} respectively in 
+the mono-processor case (i.e. global domain of {\small\tt 182x149x31}).
+An illustration of the potential space savings that NetCDF4 chunking and compression provides is given in 
+table \autoref{tab:NC4} which compares the results of two short runs of 
+the ORCA2\_LIM reference configuration with a 4x2 mpi partitioning.
+Note the variation in the compression ratio achieved which reflects chiefly the dry to 
+wet volume ratio of each processing region.
+
+%------------------------------------------TABLE----------------------------------------------------
+\begin{table} \scriptsize \centering
+	\begin{tabular}{lrrr}
+		Filename                    & NetCDF3	& NetCDF4  & Reduction \\
+                                  & filesize	& filesize & \%        \\
+                                  & (KB)		& (KB)	  &           \\
+		ORCA2\_restart\_0000.nc     & 16420 	& 8860 	  & 47\%      \\
+		ORCA2\_restart\_0001.nc     & 16064 	& 11456    & 29\%      \\
+		ORCA2\_restart\_0002.nc     & 16064		& 9744	  & 40\%      \\
+		ORCA2\_restart\_0003.nc     & 16420		& 9404	  & 43\%      \\
+		ORCA2\_restart\_0004.nc     & 16200 	& 5844	  & 64\%      \\
+		ORCA2\_restart\_0005.nc     & 15848 	& 8172	  & 49\%      \\
+		ORCA2\_restart\_0006.nc     & 15848 	& 8012 	  & 50\%      \\
+		ORCA2\_restart\_0007.nc     & 16200 	& 5148 	  & 69\%      \\
+		ORCA2\_2d\_grid\_T\_0000.nc & 2200 		& 1504	  & 32\%      \\
+		ORCA2\_2d\_grid\_T\_0001.nc & 2200 		& 1748	  & 21\%      \\
+		ORCA2\_2d\_grid\_T\_0002.nc & 2200 		& 1592	  & 28\%      \\
+		ORCA2\_2d\_grid\_T\_0003.nc & 2200 		& 1540	  & 30\%      \\
+		ORCA2\_2d\_grid\_T\_0004.nc & 2200 		& 1204	  & 46\%      \\
+		ORCA2\_2d\_grid\_T\_0005.nc & 2200 		& 1444	  & 35\%      \\
+		ORCA2\_2d\_grid\_T\_0006.nc & 2200 		& 1428	  & 36\%      \\
+		ORCA2\_2d\_grid\_T\_0007.nc & 2200		& 1148	  & 48\%      \\
+		...                         & ...		& ...      & ...       \\
+		ORCA2\_2d\_grid\_W\_0000.nc & 4416		& 2240	  & 50\%      \\
+		ORCA2\_2d\_grid\_W\_0001.nc & 4416		& 2924	  & 34\%      \\
+		ORCA2\_2d\_grid\_W\_0002.nc & 4416		& 2512	  & 44\%      \\
+		ORCA2\_2d\_grid\_W\_0003.nc & 4416		& 2368	  & 47\%      \\
+		ORCA2\_2d\_grid\_W\_0004.nc & 4416		& 1432	  & 68\%      \\
+		ORCA2\_2d\_grid\_W\_0005.nc & 4416		& 1972	  & 56\%      \\
+		ORCA2\_2d\_grid\_W\_0006.nc & 4416		& 2028	  & 55\%      \\
+		ORCA2\_2d\_grid\_W\_0007.nc & 4416		& 1368	  & 70\%      \\
+	\end{tabular}
+	\caption{
+		\protect\label{tab:NC4}
+		Filesize comparison between NetCDF3 and NetCDF4 with chunking and compression}
+\end{table}
+%----------------------------------------------------------------------------------------------------
+
+When \key{iomput} is activated with \key{netcdf4} chunking and compression parameters for 
+fields produced via \np{iom\_put} calls are set via an equivalent and identically named namelist to 
+\textit{namnc4} in \np{xmlio\_server.def}.
+Typically this namelist serves the mean files whilst the \ngn{ namnc4} in 
+the main namelist file continues to serve the restart files.
+This duplication is unfortunate but appropriate since, if using io\_servers, the domain sizes of 
+the individual files produced by the io\_server processes may be different to those produced by 
+the invidual processing regions and different chunking choices may be desired.
+ 
+% -------------------------------------------------------------------------------------------------------------
+%       Tracer/Dynamics Trends
+% -------------------------------------------------------------------------------------------------------------
+\section{Tracer/Dynamics trends  (\protect\ngn{namtrd})}
+\label{sec:DIA_trd}
+
+%------------------------------------------namtrd----------------------------------------------------
+
+\nlst{namtrd} 
+%-------------------------------------------------------------------------------------------------------------
+
+Each trend of the dynamics and/or temperature and salinity time evolution equations can be send to 
+\mdl{trddyn} and/or \mdl{trdtra} modules (see TRD directory) just after their computation ($i.e.$ at 
+the end of each $dyn\cdots.F90$ and/or $tra\cdots.F90$ routines).
+This capability is controlled by options offered in \ngn{namtrd} namelist.
+Note that the output are done with xIOS, and therefore the \key{IOM} is required.
+
+What is done depends on the \ngn{namtrd} logical set to \forcode{.true.}:
+
+\begin{description}
+	\item[\np{ln\_glo\_trd}]: at each \np{nn\_trd} time-step a check of the basin averaged properties of 
+										the momentum and tracer equations is performed.
+										This also includes a check of $T^2$, $S^2$, $\tfrac{1}{2} (u^2+v2)$, and 
+										potential energy time evolution equations properties;
+	\item[\np{ln\_dyn\_trd}]: each 3D trend of the evolution of the two momentum components is output;
+	\item[\np{ln\_dyn\_mxl}]: each 3D trend of the evolution of the two momentum components averaged over 
+										the mixed layer is output;
+	\item[\np{ln\_vor\_trd}]: a vertical summation of the moment tendencies is performed, then 
+										the curl is computed to obtain the barotropic vorticity tendencies which 
+										are output;
+	\item[\np{ln\_KE\_trd}] : each 3D trend of the Kinetic Energy equation is output ;
+	\item[\np{ln\_tra\_trd}]: each 3D trend of the evolution of temperature and salinity is output ;
+	\item[\np{ln\_tra\_mxl}]: each 2D trend of the evolution of temperature and salinity averaged over 
+										the mixed layer is output;
+\end{description}
+
+Note that the mixed layer tendency diagnostic can also be used on biogeochemical models via 
+the \key{trdtrc} and \key{trdmld\_trc} CPP keys.
+
+\textbf{Note that} in the current version (v3.6), many changes has been introduced but not fully tested.
+In particular, options associated with \np{ln\_dyn\_mxl}, \np{ln\_vor\_trd}, and \np{ln\_tra\_mxl} are 
+not working, and none of the options have been tested with variable volume ($i.e.$ \key{vvl} defined).
+
+% -------------------------------------------------------------------------------------------------------------
+%       On-line Floats trajectories
+% -------------------------------------------------------------------------------------------------------------
+\section{FLO: On-Line Floats trajectories (\protect\key{floats})}
+\label{sec:FLO}
+%--------------------------------------------namflo-------------------------------------------------------
+
+\nlst{namflo} 
+%--------------------------------------------------------------------------------------------------------------
+
+The on-line computation of floats advected either by the three dimensional velocity field or 
+constraint to remain at a given depth ($w = 0$ in the computation) have been introduced in 
+the system during the CLIPPER project.
+Options are defined by \ngn{namflo} namelis variables.
+The algorithm used is based either on the work of \cite{Blanke_Raynaud_JPO97} (default option), or 
+on a $4^th$ Runge-Hutta algorithm (\np{ln\_flork4}\forcode{ = .true.}).
+Note that the \cite{Blanke_Raynaud_JPO97} algorithm have the advantage of providing trajectories which 
+are consistent with the numeric of the code, so that the trajectories never intercept the bathymetry.
+
+\subsubsection{Input data: initial coordinates}
+
+Initial coordinates can be given with Ariane Tools convention (IJK coordinates,
+(\np{ln\_ariane}\forcode{ = .true.}) ) or with longitude and latitude.
+
+In case of Ariane convention, input filename is \np{init\_float\_ariane}.
+Its format is: \\
+{\scriptsize \texttt{I J K nisobfl itrash itrash}}
+
+\noindent with:
+
+ - I,J,K  : indexes of initial position
+
+ - nisobfl: 0 for an isobar float, 1 for a float following the w velocity  
+
+ - itrash : set to zero; it is a dummy variable to respect Ariane Tools convention
+
+\noindent Example: \\
+\noindent {\scriptsize \texttt{
+100.00000  90.00000  -1.50000 1.00000   0.00000   \\
+102.00000  90.00000  -1.50000 1.00000   0.00000   \\
+104.00000  90.00000  -1.50000 1.00000   0.00000   \\
+106.00000  90.00000  -1.50000 1.00000   0.00000   \\
+108.00000  90.00000  -1.50000 1.00000   0.00000}} \\
+
+In the other case (longitude and latitude), input filename is init\_float.
+Its format is: \\
+{\scriptsize \texttt{Long Lat depth nisobfl ngrpfl itrash}}
+
+\noindent with:
+
+ - Long, Lat, depth  : Longitude, latitude, depth
+
+ - nisobfl: 0 for an isobar float, 1 for a float following the w velocity
+
+ - ngrpfl : number to identify searcher group
+
+ - itrash :set to 1; it is a dummy variable.
+
+\noindent Example: \\
+\noindent {\scriptsize \texttt{
+ 20.0 0.0 0.0 0 1 1    \\
+-21.0 0.0 0.0 0 1 1    \\
+-22.0 0.0 0.0 0 1 1    \\
+-23.0 0.0 0.0 0 1 1    \\
+-24.0 0.0 0.0 0 1 1 }} \\
+
+\np{jpnfl} is the total number of floats during the run.
+When initial positions are read in a restart file (\np{ln\_rstflo}\forcode{ = .true.} ), 
+\np{jpnflnewflo} can be added in the initialization file.
+
+\subsubsection{Output data}
+
+\np{nn\_writefl} is the frequency of writing in float output file and \np{nn\_stockfl} is 
+the frequency of creation of the float restart file.
+
+Output data can be written in ascii files (\np{ln\_flo\_ascii}\forcode{ = .true.}).
+In that case, output filename is trajec\_float.
+
+Another possiblity of writing format is Netcdf (\np{ln\_flo\_ascii}\forcode{ = .false.}).
+There are 2 possibilities:
+
+ - if (\key{iomput}) is used, outputs are selected in  iodef.xml.
+	Here it is an example of specification to put in files description section:
+
+\begin{xmllines}
+<group id="1d_grid_T" name="auto" description="ocean T grid variables" >   }
+	<file id="floats"  description="floats variables"> }
+		<field ref="traj_lon"   name="floats_longitude"   freq_op="86400" />}
+		<field ref="traj_lat"   name="floats_latitude"    freq_op="86400" />}
+		<field ref="traj_dep"   name="floats_depth"       freq_op="86400" />}
+		<field ref="traj_temp"  name="floats_temperature" freq_op="86400" />}
+		<field ref="traj_salt"  name="floats_salinity"    freq_op="86400" />}
+		<field ref="traj_dens"  name="floats_density"     freq_op="86400" />}
+		<field ref="traj_group" name="floats_group"       freq_op="86400" />}
+	</file>}
+</group>}
+\end{xmllines}
+
+ -  if (\key{iomput}) is not used, a file called \ifile{trajec\_float} will be created by IOIPSL library.
+
+See also \href{http://stockage.univ-brest.fr/~grima/Ariane/}{here} the web site describing 
+the off-line use of this marvellous diagnostic tool.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Harmonic analysis of tidal constituents
+% -------------------------------------------------------------------------------------------------------------
+\section{Harmonic analysis of tidal constituents (\protect\key{diaharm}) }
+\label{sec:DIA_diag_harm}
+
+%------------------------------------------namdia_harm----------------------------------------------------
+%
+\nlst{nam_diaharm}
+%----------------------------------------------------------------------------------------------------------
+
+A module is available to compute the amplitude and phase of tidal waves.
+This on-line Harmonic analysis is actived with \key{diaharm}.
+
+Some parameters are available in namelist \ngn{namdia\_harm} :
+
+ - \np{nit000\_han} is the first time step used for harmonic analysis
+
+ - \np{nitend\_han} is the  last time step used for harmonic analysis
+
+ - \np{nstep\_han}  is the  time step frequency for harmonic analysis
+
+ - \np{nb\_ana}     is the number of harmonics to analyse
+
+ - \np{tname}       is an array with names of tidal constituents to analyse
+
+\np{nit000\_han} and \np{nitend\_han} must be between \np{nit000} and \np{nitend} of the simulation.
+The restart capability is not implemented.
+
+The Harmonic analysis solve the following equation:
+
+\[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[A_{j}cos(\nu_{j}t_{j}-\phi_{j})] = e_{i}\]
+
+With $A_{j}$, $\nu_{j}$, $\phi_{j}$, the amplitude, frequency and phase for each wave and 
+$e_{i}$ the error.
+$h_{i}$ is the sea level for the time $t_{i}$ and $A_{0}$ is the mean sea level. \\
+We can rewrite this equation:
+
+\[h_{i} - A_{0} + \sum^{nb\_ana}_{j=1}[C_{j}cos(\nu_{j}t_{j})+S_{j}sin(\nu_{j}t_{j})] = e_{i}\]
+
+with $A_{j}=\sqrt{C^{2}_{j}+S^{2}_{j}}$ and $\phi_{j}=arctan(S_{j}/C_{j})$.
+
+We obtain in output $C_{j}$ and $S_{j}$ for each tidal wave.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Sections transports
+% -------------------------------------------------------------------------------------------------------------
+\section{Transports across sections (\protect\key{diadct}) }
+\label{sec:DIA_diag_dct}
+
+%------------------------------------------namdct----------------------------------------------------
+
+\nlst{namdct}
+%-------------------------------------------------------------------------------------------------------------
+
+A module is available to compute the transport of volume, heat and salt through sections. 
+This diagnostic is actived with \key{diadct}.
+
+Each section is defined by the coordinates of its 2 extremities.
+The pathways between them are contructed using tools which can be found in 
+\texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT} 
+and are written in a binary file 
+\texttt{section\_ijglobal.diadct\_ORCA2\_LIM} 
+which is later read in by NEMO to compute on-line transports.
+
+The on-line transports module creates three output ascii files:
+
+- \texttt{volume\_transport} for volume transports (unit: $10^{6} m^{3} s^{-1}$)
+
+- \texttt{heat\_transport}   for   heat transports (unit: $10^{15} W$)
+
+- \texttt{salt\_transport}   for   salt transports (unit: $10^{9}Kg s^{-1}$) \\
+
+Namelist variables in \ngn{namdct} control how frequently the flows are summed and the time scales over 
+which they are averaged, as well as the level of output for debugging:
+\np{nn\_dct}   : frequency of instantaneous transports computing
+\np{nn\_dctwri}: frequency of writing ( mean of instantaneous transports )
+\np{nn\_debug} : debugging of the section
+
+\subsubsection{Creating a binary file containing the pathway of each section}
+
+In \texttt{NEMOGCM/TOOLS/SECTIONS\_DIADCT/run}, 
+the file \textit{ {list\_sections.ascii\_global}} contains a list of all the sections that are to 
+be computed (this list of sections is based on MERSEA project metrics).
+
+Another file is available for the GYRE configuration (\texttt{ {list\_sections.ascii\_GYRE}}).
+
+Each section is defined by: \\
+\noindent {\scriptsize \texttt{long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name}} \\
+with:
+
+ - \texttt{long1 lat1}, coordinates of the  first extremity of the section;
+
+ - \texttt{long2 lat2}, coordinates of the second extremity of the section;
+
+ - \texttt{nclass}    the number of bounds of your classes (e.g. 3 bounds for 2 classes);
+
+ - \texttt{okstrpond} to compute    heat and       salt transports, \texttt{nostrpond} if no;
+
+ - \texttt{ice}       to compute surface and volume ice transports, \texttt{noice}     if no. \\
+
+\noindent The results of the computing of transports, and the directions of positive and 
+negative flow do not depend on the order of the 2 extremities in this file. \\
+
+\noindent If nclass $\neq$ 0,the next lines contain the class type and the nclass bounds: \\
+{\scriptsize \texttt{
+long1 lat1 long2 lat2 nclass (ok/no)strpond (no)ice section\_name \\
+classtype                                                         \\
+zbound1                                                           \\
+zbound2                                                           \\
+.                                                                 \\
+.                                                                 \\
+nclass-1                                                          \\
+nclass}}
+
+\noindent where \texttt{classtype} can be:
+
+ - \texttt{zsal}  for          salinity classes
+
+ - \texttt{ztem}  for       temperature classes
+
+ - \texttt{zlay}  for             depth classes
+
+ - \texttt{zsigi} for    insitu density classes
+
+ - \texttt{zsigp} for potential density classes \\
+  
+The script \texttt{job.ksh} computes the pathway for each section and 
+creates a binary file \texttt{section\_ijglobal.diadct\_ORCA2\_LIM} which is read by NEMO. \\
+
+It is possible to use this tools for new configuations: \texttt{job.ksh} has to be updated with 
+the coordinates file name and path. \\
+
+Examples of two sections, the ACC\_Drake\_Passage with no classes, and the ATL\_Cuba\_Florida with 
+4 temperature clases (5 class bounds), are shown: \\
+\noindent {\scriptsize \texttt{
+-68.    -54.5   -60.    -64.7  00 okstrpond noice ACC\_Drake\_Passage \\
+-80.5    22.5   -80.5    25.5  05 nostrpond noice ATL\_Cuba\_Florida  \\
+ztem                                                                  \\
+-2.0                                                                  \\
+ 4.5                                                                  \\
+ 7.0                                                                  \\
+12.0                                                                  \\
+40.0}}
+
+\subsubsection{To read the output files}
+
+The output format is: \\
+{\scriptsize \texttt{
+date, time-step number, section number,                \\
+section name, section slope coefficient, class number, \\
+class name, class bound 1 , classe bound2,             \\
+transport\_direction1, transport\_direction2,          \\
+transport\_total}}                                     \\
+
+For sections with classes, the first \texttt{nclass-1} lines correspond to the transport for 
+each class and the last line corresponds to the total transport summed over all classes.
+For sections with no classes, class number \texttt{1} corresponds to \texttt{total class} and 
+this class is called \texttt{N}, meaning \texttt{none}.
+
+- \texttt{transport\_direction1} is the positive part of the transport ($\geq$ 0).
+
+- \texttt{transport\_direction2} is the negative part of the transport ($\leq$ 0). \\
+
+\noindent The \texttt{section slope coefficient} gives information about the significance of 
+transports signs and direction: \\
+
+\begin{table} \scriptsize
+	\begin{tabular}{|l|l|l|l|l|} \hline
+		section slope coefficient      & section type & direction 1 & direction 2 & total transport
+		\\ \hline
+		0.                             & horizontal	 & northward	& southward   & postive: northward
+		\\ \hline
+		1000.                          & vertical     & eastward    & westward    & postive: eastward
+		\\ \hline
+		\texttt{$\neq$ 0, $\neq$ 1000.} & diagonal     & eastward    & westward	  & postive: eastward
+		\\ \hline
+	\end{tabular}
+\end{table}
+
+% ================================================================
+% Steric effect in sea surface height
+% ================================================================
+\section{Diagnosing the steric effect in sea surface height}
+\label{sec:DIA_steric}
+
+
+Changes in steric sea level are caused when changes in the density of the water column imply an 
+expansion or contraction of the column.
+It is essentially produced through surface heating/cooling and to a lesser extent through 
+non-linear effects of the equation of state (cabbeling, thermobaricity...).
+Non-Boussinesq models contain all ocean effects within the ocean acting on the sea level.
+In particular, they include the steric effect.
+In contrast, Boussinesq models, such as \NEMO, conserve volume, rather than mass, 
+and so do not properly represent expansion or contraction.
+The steric effect is therefore not explicitely represented.
+This approximation does not represent a serious error with respect to the flow field calculated by 
+the model \citep{Greatbatch_JGR94}, but extra attention is required when investigating sea level, 
+as steric changes are an important contribution to local changes in sea level on seasonal and 
+climatic time scales.
+This is especially true for investigation into sea level rise due to global warming. 
+
+Fortunately, the steric contribution to the sea level consists of a spatially uniform component that 
+can be diagnosed by considering the mass budget of the world ocean \citep{Greatbatch_JGR94}.
+In order to better understand how global mean sea level evolves and thus how the steric sea level can 
+be diagnosed, we compare, in the following, the non-Boussinesq and Boussinesq cases.
+
+Let denote
+$\mathcal{M}$ the total mass    of liquid seawater ($\mathcal{M} = \int_D \rho dv$), 
+$\mathcal{V}$ the total volume  of        seawater      ($\mathcal{V} = \int_D dv$), 
+$\mathcal{A}$ the total surface of       the ocean      ($\mathcal{A} = \int_S ds$), 
+$\bar{\rho}$ the global mean  seawater (\textit{in situ}) density 
+($\bar{\rho} = 1/\mathcal{V} \int_D \rho \,dv$), and
+$\bar{\eta}$ the global mean sea level 
+($\bar{\eta} = 1/\mathcal{A} \int_S \eta \,ds$).
+
+A non-Boussinesq fluid conserves mass. It satisfies the following relations:
+
+\[	\begin{split}
+		\mathcal{M} &=  \mathcal{V}  \;\bar{\rho} \\
+		\mathcal{V} &=  \mathcal{A}  \;\bar{\eta}
+	\end{split}  \label{eq:MV_nBq}
+\]
+
+Temporal changes in total mass is obtained from the density conservation equation :
+
+\[ \frac{1}{e_3} \partial_t ( e_3\,\rho) + \nabla( \rho \, \textbf{U} ) 
+	= \left. \frac{\textit{emp}}{e_3}\right|_\textit{surface}
+ \label{eq:Co_nBq} \]
+
+where $\rho$ is the \textit{in situ} density, and \textit{emp} the surface mass 
+exchanges with the other media of the Earth system (atmosphere, sea-ice, land). 
+Its global averaged leads to the total mass change 
+
+\[ \partial_t \mathcal{M} = \mathcal{A} \;\overline{\textit{emp}}
+ \label{eq:Mass_nBq} \]
+
+where $\overline{\textit{emp}} = \int_S \textit{emp}\,ds$ is the net mass flux through the ocean surface.
+Bringing \autoref{eq:Mass_nBq} and the time derivative of \autoref{eq:MV_nBq} together leads to 
+the evolution equation of the mean sea level
+
+\[ \partial_t \bar{\eta} = \frac{\overline{\textit{emp}}}{ \bar{\rho}} 
+                         - \frac{\mathcal{V}}{\mathcal{A}} \;\frac{\partial_t \bar{\rho} }{\bar{\rho}}
+ \label{eq:ssh_nBq} \]
+
+The first term in equation \autoref{eq:ssh_nBq} alters sea level by adding or 
+subtracting mass from the ocean. 
+The second term arises from temporal changes in the global mean density; $i.e.$ from steric effects. 
+
+In a Boussinesq fluid, $\rho$ is replaced by $\rho_o$ in all the equation except when 
+$\rho$ appears multiplied by the gravity ($i.e.$ in the hydrostatic balance of the primitive Equations).
+In particular, the mass conservation equation, \autoref{eq:Co_nBq}, degenerates into 
+the incompressibility equation:
+
+\[ \frac{1}{e_3} \partial_t ( e_3 ) + \nabla( \textbf{U} )
+   = \left. \frac{\textit{emp}}{\rho_o \,e_3}\right|_ \textit{surface}
+ \label{eq:Co_Bq} \]
+
+and the global average of this equation now gives the temporal change of the total volume,
+
+\[ \partial_t \mathcal{V} = \mathcal{A} \;\frac{\overline{\textit{emp}}}{\rho_o}
+ \label{eq:V_Bq} \]
+
+Only the volume is conserved, not mass, or, more precisely, the mass which is conserved is 
+the Boussinesq mass, $\mathcal{M}_o = \rho_o \mathcal{V}$.
+The total volume (or equivalently the global mean sea level) is altered only by net volume fluxes across 
+the ocean surface, not by changes in mean mass of the ocean: the steric effect is missing in 
+a Boussinesq fluid.
+
+Nevertheless, following \citep{Greatbatch_JGR94}, the steric effect on the volume can be diagnosed by 
+considering the mass budget of the ocean. 
+The apparent changes in $\mathcal{M}$, mass of the ocean, which are not induced by 
+surface mass flux must be compensated by a spatially uniform change in the mean sea level due to 
+expansion/contraction of the ocean \citep{Greatbatch_JGR94}.
+In others words, the Boussinesq mass, $\mathcal{M}_o$, can be related to $\mathcal{M}$, 
+the  total mass of the ocean seen by the Boussinesq model, via the steric contribution to the sea level, 
+$\eta_s$, a spatially uniform variable, as follows:
+
+\[ \mathcal{M}_o = \mathcal{M} + \rho_o \,\eta_s \,\mathcal{A}
+ \label{eq:M_Bq} \]
+
+Any change in $\mathcal{M}$ which cannot be explained by the net mass flux through 
+the ocean surface is converted into a mean change in sea level.
+Introducing the total density anomaly, $\mathcal{D}= \int_D d_a \,dv$, where 
+$d_a = (\rho -\rho_o ) / \rho_o$ is the density anomaly used in \NEMO (cf. \autoref{subsec:TRA_eos}) in 
+\autoref{eq:M_Bq} leads to a very simple form for the steric height:
+
+\[	\eta_s = - \frac{1}{\mathcal{A}} \mathcal{D}
+ \label{eq:steric_Bq} \]
+
+The above formulation of the steric height of a Boussinesq ocean requires four remarks.
+First, one can be tempted to define $\rho_o$ as the initial value of $\mathcal{M}/\mathcal{V}$,
+$i.e.$ set $\mathcal{D}_{t=0}=0$, so that the initial steric height is zero.
+We do not recommend that.
+Indeed, in this case $\rho_o$ depends on the initial state of the ocean.
+Since $\rho_o$ has a direct effect on the dynamics of the ocean (it appears in 
+the pressure gradient term of the momentum equation) it is definitively not a good idea when 
+inter-comparing experiments.
+We better recommend to fixe once for all $\rho_o$ to $1035\;Kg\,m^{-3}$.
+This value is a sensible choice for the reference density used in a Boussinesq ocean climate model since, 
+with the exception of only a small percentage of the ocean, density in the World Ocean varies by 
+no more than 2$\%$ from this value (\cite{Gill1982}, page 47).
+
+Second, we have assumed here that the total ocean surface, $\mathcal{A}$, does not change when 
+the sea level is changing as it is the case in all global ocean GCMs 
+(wetting and drying of grid point is not allowed).
+  
+Third, the discretisation of \autoref{eq:steric_Bq} depends on the type of 
+free surface which is considered.
+In the non linear free surface case, $i.e.$ \key{vvl} defined, it is given by
+
+\[ \eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t} e_{2t} e_{3t} }
+                   { \sum_{i,\,j,\,k}       e_{1t} e_{2t} e_{3t} }
+ \label{eq:discrete_steric_Bq_nfs} \]
+
+whereas in the linear free surface, the volume above the \textit{z=0} surface must be explicitly 
+taken into account to better approximate the total ocean mass and thus the steric sea level:
+
+\[	\eta_s = - \frac{ \sum_{i,\,j,\,k} d_a\; e_{1t}e_{2t}e_{3t} + \sum_{i,\,j} d_a\; e_{1t}e_{2t} \eta }
+                   { \sum_{i,\,j,\,k}       e_{1t}e_{2t}e_{3t} + \sum_{i,\,j}      e_{1t}e_{2t} \eta }
+ \label{eq:discrete_steric_Bq_fs} \]
+
+The fourth and last remark concerns the effective sea level and the presence of sea-ice.
+In the real ocean, sea ice (and snow above it)  depresses the liquid seawater through its mass loading.
+This depression is a result of the mass of sea ice/snow system acting on the liquid ocean.
+There is, however, no dynamical effect associated with these depressions in the liquid ocean sea level, 
+so that there are no associated ocean currents.
+Hence, the dynamically relevant sea level is the effective sea level, $i.e.$ the sea level as if 
+sea ice (and snow) were converted to liquid seawater \citep{Campin_al_OM08}.
+However, in the current version of \NEMO the sea-ice is levitating above the ocean without 
+mass exchanges between ice and ocean.
+Therefore the model effective sea level is always given by $\eta + \eta_s$, 
+whether or not there is sea ice present.
+
+In AR5 outputs, the thermosteric sea level is demanded.
+It is steric sea level due to changes in ocean density arising just from changes in temperature.
+It is given by:
+
+\[	\eta_s = - \frac{1}{\mathcal{A}} \int_D d_a(T,S_o,p_o) \,dv
+ \label{eq:thermosteric_Bq} \]
+
+where $S_o$ and $p_o$ are the initial salinity and pressure, respectively.
+
+Both steric and thermosteric sea level are computed in \mdl{diaar5} which needs
+the \key{diaar5} defined to be called.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Other Diagnostics
+% -------------------------------------------------------------------------------------------------------------
+\section{Other diagnostics (\protect\key{diahth}, \protect\key{diaar5})}
+\label{sec:DIA_diag_others}
+
+Aside from the standard model variables, other diagnostics can be computed on-line.
+The available ready-to-add diagnostics modules can be found in directory DIA.
+
+\subsection{Depth of various quantities (\protect\mdl{diahth})}
+
+Among the available diagnostics the following ones are obtained when defining the \key{diahth} CPP key: 
+
+- the mixed layer depth (based on a density criterion \citep{de_Boyer_Montegut_al_JGR04}) (\mdl{diahth})
+
+- the turbocline depth (based on a turbulent mixing coefficient criterion) (\mdl{diahth})
+
+- the depth of the 20\deg C isotherm (\mdl{diahth})
+
+- the depth of the thermocline (maximum of the vertical temperature gradient) (\mdl{diahth})
+
+% -----------------------------------------------------------
+%     Poleward heat and salt transports
+% -----------------------------------------------------------
+
+\subsection{Poleward heat and salt transports (\protect\mdl{diaptr})}
+
+%------------------------------------------namptr-----------------------------------------
+
+\nlst{namptr} 
+%-----------------------------------------------------------------------------------------
+
+The poleward heat and salt transports, their advective and diffusive component, and 
+the meriodional stream function can be computed on-line in \mdl{diaptr} \np{ln\_diaptr} to true 
+(see the \textit{\ngn{namptr} } namelist below).
+When \np{ln\_subbas}\forcode{ = .true.}, transports and stream function are computed for the Atlantic, 
+Indian, Pacific and Indo-Pacific Oceans (defined north of 30\deg S) as well as for the World Ocean.
+The sub-basin decomposition requires an input file (\ifile{subbasins}) which contains 
+three 2D mask arrays, the Indo-Pacific mask been deduced from the sum of the Indian and 
+Pacific mask (\autoref{fig:mask_subasins}).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] \begin{center}
+	\includegraphics[width=1.0\textwidth]{Fig_mask_subasins}
+	\caption{	\protect\label{fig:mask_subasins}
+		Decomposition of the World Ocean (here ORCA2) into sub-basin used in to compute the heat and 
+		salt transports as well as the meridional stream-function: Atlantic basin (red), 
+		Pacific basin (green), Indian basin (bleue), Indo-Pacific basin (bleue+green).
+		Note that semi-enclosed seas (Red, Med and Baltic seas) as well as Hudson Bay are removed from 
+		the sub-basins. Note also that the Arctic Ocean has been split into Atlantic and 
+		Pacific basins along the North fold line.}
+\end{center} \end{figure}  
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -----------------------------------------------------------
+%       CMIP specific diagnostics 
+% -----------------------------------------------------------
+\subsection{CMIP specific diagnostics (\protect\mdl{diaar5})}
+
+A series of diagnostics has been added in the \mdl{diaar5}.
+They corresponds to outputs that are required for AR5 simulations (CMIP5)
+(see also \autoref{sec:DIA_steric} for one of them).
+Activating those outputs requires to define the \key{diaar5} CPP key.
+
+% -----------------------------------------------------------
+%       25 hour mean and hourly Surface, Mid and Bed 
+% -----------------------------------------------------------
+\subsection{25 hour mean output for tidal models}
+
+%------------------------------------------nam_dia25h-------------------------------------
+
+\nlst{nam_dia25h}
+%-----------------------------------------------------------------------------------------
+
+A module is available to compute a crudely detided M2 signal by obtaining a 25 hour mean.
+The 25 hour mean is available for daily runs by summing up the 25 hourly instantananeous hourly values from
+midnight at the start of the day to midight at the day end.
+This diagnostic is actived with the logical  $ln\_dia25h$
+
+% -----------------------------------------------------------
+%     Top Middle and Bed hourly output
+% -----------------------------------------------------------
+\subsection{Top middle and bed hourly output}
+
+%------------------------------------------nam_diatmb-----------------------------------------------------
+
+\nlst{nam_diatmb}
+%----------------------------------------------------------------------------------------------------------
+
+A module is available to output the surface (top), mid water and bed diagnostics of a set of 
+standard variables.
+This can be a useful diagnostic when hourly or sub-hourly output is required in 
+high resolution tidal outputs.
+The tidal signal is retained but the overall data usage is cut to just three vertical levels.
+Also the bottom level is calculated for each cell.
+This diagnostic is actived with the logical  $ln\_diatmb$
+
+% -----------------------------------------------------------
+%     Courant numbers
+% -----------------------------------------------------------
+\subsection{Courant numbers}
+
+Courant numbers provide a theoretical indication of the model's numerical stability.
+The advective Courant numbers can be calculated according to
+
+\[	C_u = |u|\frac{\rdt}{e_{1u}}, \quad C_v = |v|\frac{\rdt}{e_{2v}}, \quad C_w = |w|\frac{\rdt}{e_{3w}}
+ \label{eq:CFL} \]
+
+in the zonal, meridional and vertical directions respectively.
+The vertical component is included although it is not strictly valid as the vertical velocity is 
+calculated from the continuity equation rather than as a prognostic variable.
+Physically this represents the rate at which information is propogated across a grid cell.
+Values greater than 1 indicate that information is propagated across more than one grid cell in 
+a single time step.
+
+The variables can be activated by setting the \np{nn\_diacfl} namelist parameter to 1 in 
+the \ngn{namctl} namelist.
+The diagnostics will be written out to an ascii file named cfl\_diagnostics.ascii.
+In this file the maximum value of $C_u$, $C_v$, and $C_w$ are printed at each timestep along with 
+the coordinates of where the maximum value occurs.
+At the end of the model run the maximum value of $C_u$, $C_v$, and $C_w$ for the whole model run is 
+printed along with the coordinates of each.
+The maximum values from the run are also copied to the ocean.output file. 
+
+% ================================================================
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIU.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DIU.tex	(revision 10321)
@@ -0,0 +1,167 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Diurnal SST models (DIU)
+% Edited by James While
+% ================================================================
+\chapter{Diurnal SST Models (DIU)}
+\label{chap:DIU}
+
+\minitoc
+
+
+\newpage
+$\ $\newline % force a new line
+
+Code to produce an estimate of the diurnal warming and cooling of the sea surface skin
+temperature (skin SST) is found in the DIU directory.  
+The skin temperature can be split into three parts:
+\begin{itemize}
+\item A foundation SST which is free from diurnal warming.
+\item A warm layer, typically ~3\,m thick, where heating from solar radiation can
+cause a warm stably stratified layer during the daytime
+\item A cool skin, a thin layer, approximately ~1\,mm thick, where long wave cooling
+is dominant and cools the immediate ocean surface.
+\end{itemize}
+
+Models are provided for both the warm layer, \mdfl{diurnal_bulk}, and the cool skin,
+\mdl{cool_skin}.  Foundation SST is not considered as it can be obtained
+either from the main NEMO model ($i.e.$ from the temperature of the top few model levels)
+or from some other source.  
+It must be noted that both the cool skin and warm layer models produce estimates of 
+the change in temperature ($\Delta T_{\rm{cs}}$ and $\Delta T_{\rm{wl}}$) 
+and both must be added to a foundation SST to obtain the true skin temperature.
+
+Both the cool skin and warm layer models are controlled through the namelist \ngn{namdiu}:
+
+\nlst{namdiu}
+This namelist contains only two variables:
+\begin{description}
+\item[\np{ln\_diurnal}] A logical switch for turning on/off both the cool skin and warm layer.
+\item[\np{ln\_diurnal\_only}] A logical switch which if \forcode{.true.} will run the diurnal model
+without the other dynamical parts of NEMO.  
+\np{ln\_diurnal\_only} must be \forcode{.false.} if \np{ln\_diurnal} is \forcode{.false.}.
+\end{description}
+
+Output for the diurnal model is through the variables `sst\_wl' (warm\_layer) and
+`sst\_cs' (cool skin).  These are 2-D variables which will be included in the model
+output if they are specified in the iodef.xml file.
+
+Initialisation is through the restart file.  Specifically the code will expect 
+the presence of the 2-D variable ``Dsst'' to initialise the warm layer.  
+The cool skin model, which is determined purely by the instantaneous fluxes, 
+has no initialisation variable.  
+
+%===============================================================
+\section{Warm layer model}
+\label{sec:warm_layer_sec}
+%===============================================================
+
+The warm layer is calculated using the model of \citet{Takaya_al_JGR10} (TAKAYA10 model
+hereafter).  This is a simple flux based model that is defined by the equations
+\begin{eqnarray}
+\frac{\partial{\Delta T_{\rm{wl}}}}{\partial{t}}&=&\frac{Q(\nu+1)}{D_T\rho_w c_p
+\nu}-\frac{(\nu+1)ku^*_{w}f(L_a)\Delta T}{D_T\Phi\!\left(\frac{D_T}{L}\right)} \mbox{,}
+\label{eq:ecmwf1} \\
+L&=&\frac{\rho_w c_p u^{*^3}_{w}}{\kappa g \alpha_w Q }\mbox{,}\label{eq:ecmwf2}
+\end{eqnarray}
+where $\Delta T_{\rm{wl}}$ is the temperature difference between the top of the warm
+layer and the depth $D_T=3$\,m at which there is assumed to be no diurnal signal. In
+equation (\autoref{eq:ecmwf1}) $\alpha_w=2\times10^{-4}$ is the thermal expansion
+coefficient of water, $\kappa=0.4$ is von K\'{a}rm\'{a}n's constant, $c_p$ is the heat
+capacity at constant pressure of sea water, $\rho_w$ is the
+water density, and $L$ is the Monin-Obukhov length. The tunable
+variable $\nu$ is a shape parameter that defines the expected
+subskin temperature profile via $T(z)=T(0)-\left(\frac{z}{D_T}\right)^\nu\Delta
+T_{\rm{wl}}$,
+where $T$ is the absolute temperature and $z\le D_T$ is the depth
+below the top of the warm layer.
+The influence of wind on TAKAYA10 comes through the magnitude of the friction velocity
+of the water
+$u^*_{w}$, which can be related to the 10\,m wind speed $u_{10}$ through the relationship
+$u^*_{w} = u_{10}\sqrt{\frac{C_d\rho_a}{\rho_w}}$, where $C_d$ is
+the drag coefficient, and $\rho_a$ is the density of air.  The symbol $Q$ in equation
+(\autoref{eq:ecmwf1}) is the instantaneous total thermal energy
+flux into
+the diurnal layer, $i.e.$
+\begin{equation}
+Q = Q_{\rm{sol}} + Q_{\rm{lw}} + Q_{\rm{h}}\mbox{,} \label{eq:e_flux_eqn}
+\end{equation}
+where $Q_{\rm{h}}$ is the sensible and latent heat flux, $Q_{\rm{lw}}$ is the long
+wave flux, and $Q_{\rm{sol}}$ is the solar flux absorbed
+within the diurnal warm layer. For $Q_{\rm{sol}}$ the 9 term
+representation of \citet{Gentemann_al_JGR09} is used.  In equation \autoref{eq:ecmwf1}
+the function $f(L_a)=\max(1,L_a^{\frac{2}{3}})$, where $L_a=0.3$\footnote{This
+is a global average value, more accurately $L_a$ could be computed as
+$L_a=(u^*_{w}/u_s)^{\frac{1}{2}}$, where $u_s$ is the stokes drift, but this is not
+currently done} is the turbulent Langmuir number and is a
+parametrization of the effect of waves.
+The function $\Phi\!\left(\frac{D_T}{L}\right)$ is the similarity function that
+parametrizes the stability of the water column and
+is given by:
+\begin{equation}
+\Phi(\zeta) = \left\{ \begin{array}{cc} 1 + \frac{5\zeta +
+4\zeta^2}{1+3\zeta+0.25\zeta^2} &(\zeta \ge 0) \\
+                                    (1 - 16\zeta)^{-\frac{1}{2}} & (\zeta < 0) \mbox{,}
+                                    \end{array} \right. \label{eq:stab_func_eqn}
+\end{equation}
+where $\zeta=\frac{D_T}{L}$.  It is clear that the first derivative of
+(\autoref{eq:stab_func_eqn}), and thus of (\autoref{eq:ecmwf1}),
+is discontinuous at $\zeta=0$ ($i.e.$ $Q\rightarrow0$ in equation (\autoref{eq:ecmwf2})).
+
+The two terms on the right hand side of (\autoref{eq:ecmwf1}) represent different processes.
+The first term is simply the diabatic heating or cooling of the
+diurnal warm
+layer due to thermal energy
+fluxes into and out of the layer.  The second term
+parametrizes turbulent fluxes of heat out of the diurnal warm layer due to wind
+induced mixing. In practice the second term acts as a relaxation
+on the temperature.
+
+%===============================================================
+
+\section{Cool skin model}
+\label{sec:cool_skin_sec}
+
+%===============================================================
+
+The cool skin is modelled using the framework of \citet{Saunders_JAS82} who used a
+formulation of the near surface temperature difference based upon the heat flux and
+the friction velocity $u^*_{w}$.  As the cool skin
+is so thin (~1\,mm) we ignore the solar flux component to the heat flux and the
+Saunders equation for the cool skin temperature difference $\Delta T_{\rm{cs}}$ becomes
+\begin{equation}
+\label{eq:sunders_eqn}
+\Delta T_{\rm{cs}}=\frac{Q_{\rm{ns}}\delta}{k_t} \mbox{,}
+\end{equation}
+where $Q_{\rm{ns}}$ is the, usually negative, non-solar heat flux into the ocean and
+$k_t$ is the thermal conductivity of sea water. $\delta$ is the thickness of the
+skin layer and is given by
+\begin{equation}
+\label{eq:sunders_thick_eqn}
+\delta=\frac{\lambda \mu}{u^*_{w}} \mbox{,}
+\end{equation}
+where $\mu$ is the kinematic viscosity of sea water and $\lambda$ is a constant of
+proportionality which \citet{Saunders_JAS82} suggested varied between 5 and 10.
+
+The value of $\lambda$ used in equation (\autoref{eq:sunders_thick_eqn}) is that of
+\citet{Artale_al_JGR02},
+which is shown in \citet{Tu_Tsuang_GRL05} to outperform a number of other
+parametrisations at both low and high wind speeds. Specifically,
+\begin{equation}
+\label{eq:artale_lambda_eqn}
+\lambda = \frac{ 8.64\times10^4 u^*_{w} k_t }{ \rho c_p h \mu \gamma }\mbox{,}
+\end{equation}
+where $h=10$\,m is a reference depth and
+$\gamma$ is a dimensionless function of wind speed $u$:
+\begin{equation}
+\label{eq:artale_gamma_eqn}
+\gamma = \left\{ \begin{matrix}
+                     0.2u+0.5\mbox{,} & u \le 7.5\,\mbox{ms}^{-1} \\
+                     1.6u-10\mbox{,} & 7.5 < u < 10\,\mbox{ms}^{-1} \\
+                     6\mbox{,} & \ge 10\,\mbox{ms}^{-1} \\
+                 \end{matrix}
+          \right.
+\end{equation}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DOM.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DOM.tex	(revision 10321)
@@ -0,0 +1,932 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter 2 ——— Space and Time Domain (DOM)
+% ================================================================
+\chapter{Space Domain (DOM)}
+\label{chap:DOM}
+\minitoc
+
+% Missing things:
+% 	- istate: description of the initial state   ==> this has to be put elsewhere..
+%                  perhaps in MISC ?  By the way the initialisation of T S and dynamics 
+%                  should be put outside of DOM routine (better with TRC staff and off-line
+%                  tracers)
+% 	-geo2ocean:  how to switch from geographic to mesh coordinate
+%     - domclo:  closed sea and lakes.... management of closea sea area : specific to global configuration, both forced and coupled
+
+
+\newpage
+$\ $\newline    % force a new line
+
+Having defined the continuous equations in \autoref{chap:PE} and chosen a time 
+discretization \autoref{chap:STP}, we need to choose a discretization on a grid, 
+and numerical algorithms. In the present chapter, we provide a general description 
+of the staggered grid used in \NEMO, and other information relevant to the main 
+directory routines as well as the DOM (DOMain) directory. 
+
+$\ $\newline    % force a new line
+
+% ================================================================
+% Fundamentals of the Discretisation
+% ================================================================
+\section{Fundamentals of the discretisation}
+\label{sec:DOM_basics}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Arrangement of Variables 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Arrangement of variables}
+\label{subsec:DOM_cell}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]    \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_cell}
+\caption{ \protect\label{fig:cell}    
+Arrangement of variables. $t$ indicates scalar points where temperature, 
+salinity, density, pressure and horizontal divergence are defined. ($u$,$v$,$w$) 
+indicates vector points, and $f$ indicates vorticity points where both relative and 
+planetary vorticities are defined}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The numerical techniques used to solve the Primitive Equations in this model are 
+based on the traditional, centred second-order finite difference approximation. 
+Special attention has been given to the homogeneity of the solution in the three 
+space directions. The arrangement of variables is the same in all directions. 
+It consists of cells centred on scalar points ($t$, $S$, $p$, $\rho$) with vector 
+points $(u, v, w)$ defined in the centre of each face of the cells (\autoref{fig:cell}). 
+This is the generalisation to three dimensions of the well-known ``C'' grid in 
+Arakawa's classification \citep{Mesinger_Arakawa_Bk76}. The relative and 
+planetary vorticity, $\zeta$ and $f$, are defined in the centre of each vertical edge 
+and the barotropic stream function $\psi$ is defined at horizontal points overlying 
+the $\zeta$ and $f$-points.
+
+The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined 
+by the transformation that gives ($\lambda$ ,$\varphi$ ,$z$) as a function of $(i,j,k)$. 
+The grid-points are located at integer or integer and a half value of $(i,j,k)$ as 
+indicated on \autoref{tab:cell}. In all the following, subscripts $u$, $v$, $w$, 
+$f$, $uw$, $vw$ or $fw$ indicate the position of the grid-point where the scale 
+factors are defined. Each scale factor is defined as the local analytical value 
+provided by \autoref{eq:scale_factors}. As a result, the mesh on which partial 
+derivatives $\frac{\partial}{\partial \lambda}, \frac{\partial}{\partial \varphi}$, and 
+$\frac{\partial}{\partial z} $ are evaluated is a uniform mesh with a grid size of unity. 
+Discrete partial derivatives are formulated by the traditional, centred second order 
+finite difference approximation while the scale factors are chosen equal to their 
+local analytical value. An important point here is that the partial derivative of the 
+scale factors must be evaluated by centred finite difference approximation, not 
+from their analytical expression. This preserves the symmetry of the discrete set 
+of equations and therefore satisfies many of the continuous properties (see 
+\autoref{apdx:C}). A similar, related remark can be made about the domain 
+size: when needed, an area, volume, or the total ocean depth must be evaluated 
+as the sum of the relevant scale factors (see \autoref{eq:DOM_bar}) in the next section). 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{table}[!tb]
+\begin{center} \begin{tabular}{|p{46pt}|p{56pt}|p{56pt}|p{56pt}|}
+\hline
+T	&$i$ 		& $j$		& $k$		 \\ \hline
+u	& $i+1/2$	& $j$		& $k$	 	\\ \hline
+v	& $i$	 	& $j+1/2$	& $k$	 	\\ \hline
+w	& $i$	 	& $j$		& $k+1/2$ 	\\ \hline
+f	& $i+1/2$ 	& $j+1/2$	& $k$	 	\\ \hline
+uw	& $i+1/2$ 	& $j$		& $k+1/2$ 	\\ \hline
+vw	& $i$	 	& $j+1/2$	& $k+1/2$ 	\\ \hline
+fw	& $i+1/2$ 	& $j+1/2$	& $k+1/2$ 	\\ \hline
+\end{tabular}
+\caption{ \protect\label{tab:cell}
+Location of grid-points as a function of integer or integer and a half value of the column, 
+line or level. This indexing is only used for the writing of the semi-discrete equation. 
+In the code, the indexing uses integer values only and has a reverse direction 
+in the vertical (see \autoref{subsec:DOM_Num_Index})}
+\end{center}
+\end{table}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Discrete operators}
+\label{subsec:DOM_operators}
+
+Given the values of a variable $q$ at adjacent points, the differencing and 
+averaging operators at the midpoint between them are:
+\begin{subequations} \label{eq:di_mi}
+\begin{align}
+ \delta _i [q]       &=  \  \    q(i+1/2)  - q(i-1/2)		\\
+ \overline q^{\,i} &= \left\{ q(i+1/2) + q(i-1/2) \right\} \; / \; 2
+\end{align}
+\end{subequations}
+
+Similar operators are defined with respect to $i+1/2$, $j$, $j+1/2$, $k$, and 
+$k+1/2$. Following \autoref{eq:PE_grad} and \autoref{eq:PE_lap}, the gradient of a 
+variable $q$ defined at a $t$-point has its three components defined at $u$-, $v$- 
+and $w$-points while its Laplacien is defined at $t$-point. These operators have 
+the following discrete forms in the curvilinear $s$-coordinate system:
+\begin{equation} \label{eq:DOM_grad}
+\nabla q\equiv 	\frac{1}{e_{1u} } \delta _{i+1/2 } [q] \;\,\mathbf{i}
+		+	\frac{1}{e_{2v} } \delta _{j+1/2 } [q] \;\,\mathbf{j}
+		+	\frac{1}{e_{3w}} \delta _{k+1/2} [q] \;\,\mathbf{k}
+\end{equation}
+\begin{multline} \label{eq:DOM_lap}
+\Delta q\equiv \frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
+       \;\left(          \delta_i  \left[ \frac{e_{2u}\,e_{3u}} {e_{1u}} \;\delta_{i+1/2} [q] \right]
++                        \delta_j  \left[ \frac{e_{1v}\,e_{3v}}  {e_{2v}} \;\delta_{j+1/2} [q] \right] \;  \right)		\\
++\frac{1}{e_{3t}} \delta_k \left[ \frac{1}{e_{3w} }                     \;\delta_{k+1/2} [q] \right]
+\end{multline}
+
+Following \autoref{eq:PE_curl} and \autoref{eq:PE_div}, a vector ${\rm {\bf A}}=\left( a_1,a_2,a_3\right)$ 
+defined at vector points $(u,v,w)$ has its three curl components defined at $vw$-, $uw$, 
+and $f$-points, and its divergence defined at $t$-points:
+\begin{eqnarray}  \label{eq:DOM_curl}
+ \nabla \times {\rm{\bf A}}\equiv &
+      \frac{1}{e_{2v}\,e_{3vw} } \ \left( \delta_{j +1/2} \left[e_{3w}\,a_3 \right] -\delta_{k+1/2} \left[e_{2v} \,a_2 \right] \right)  &\ \mathbf{i} \\ 
+ +& \frac{1}{e_{2u}\,e_{3uw}} \ \left( \delta_{k+1/2} \left[e_{1u}\,a_1  \right] -\delta_{i +1/2} \left[e_{3w}\,a_3 \right] \right)  &\ \mathbf{j} \\
+ +& \frac{1}{e_{1f} \,e_{2f}    } \ \left( \delta_{i +1/2} \left[e_{2v}\,a_2  \right] -\delta_{j +1/2} \left[e_{1u}\,a_1 \right] \right)  &\ \mathbf{k}
+ \end{eqnarray}
+\begin{eqnarray} \label{eq:DOM_div}
+\nabla \cdot \rm{\bf A} \equiv 
+    \frac{1}{e_{1t}\,e_{2t}\,e_{3t}} \left( \delta_i \left[e_{2u}\,e_{3u}\,a_1 \right]
+                                           +\delta_j \left[e_{1v}\,e_{3v}\,a_2 \right] \right)+\frac{1}{e_{3t} }\delta_k \left[a_3 \right]
+\end{eqnarray}
+
+The vertical average over the whole water column denoted by an overbar becomes 
+for a quantity $q$ which is a masked field (i.e. equal to zero inside solid area):
+\begin{equation} \label{eq:DOM_bar}
+\bar q 	=         \frac{1}{H}    \int_{k^b}^{k^o} {q\;e_{3q} \,dk} 
+		\equiv \frac{1}{H_q }\sum\limits_k {q\;e_{3q} }
+\end{equation}
+where $H_q$  is the ocean depth, which is the masked sum of the vertical scale 
+factors at $q$ points, $k^b$ and $k^o$ are the bottom and surface $k$-indices, 
+and the symbol $k^o$ refers to a summation over all grid points of the same type 
+in the direction indicated by the subscript (here $k$). 
+
+In continuous form, the following properties are satisfied:
+\begin{equation} \label{eq:DOM_curl_grad}
+\nabla \times \nabla q ={\rm {\bf {0}}}
+\end{equation}
+\begin{equation} \label{eq:DOM_div_curl}
+\nabla \cdot \left( {\nabla \times {\rm {\bf A}}} \right)=0
+\end{equation}
+
+It is straightforward to demonstrate that these properties are verified locally in 
+discrete form as soon as the scalar $q$ is taken at $t$-points and the vector 
+\textbf{A} has its components defined at vector points $(u,v,w)$.
+
+Let $a$ and $b$ be two fields defined on the mesh, with value zero inside 
+continental area. Using integration by parts it can be shown that the differencing 
+operators ($\delta_i$, $\delta_j$ and $\delta_k$) are skew-symmetric linear operators, 
+and further that the averaging operators $\overline{\,\cdot\,}^{\,i}$, 
+$\overline{\,\cdot\,}^{\,k}$ and $\overline{\,\cdot\,}^{\,k}$) are symmetric linear 
+operators, $i.e.$
+\begin{align} 
+\label{eq:DOM_di_adj}
+\sum\limits_i { a_i \;\delta _i \left[ b \right]} 
+	&\equiv -\sum\limits_i {\delta _{i+1/2} \left[ a \right]\;b_{i+1/2} }      \\
+\label{eq:DOM_mi_adj}
+\sum\limits_i { a_i \;\overline b^{\,i}} 
+	& \equiv \quad \sum\limits_i {\overline a ^{\,i+1/2}\;b_{i+1/2} } 
+\end{align}
+
+In other words, the adjoint of the differencing and averaging operators are 
+$\delta_i^*=\delta_{i+1/2}$ and 
+${(\overline{\,\cdot \,}^{\,i})}^*= \overline{\,\cdot\,}^{\,i+1/2}$, respectively. 
+These two properties will be used extensively in the \autoref{apdx:C} to 
+demonstrate integral conservative properties of the discrete formulation chosen.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Numerical Indexing 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Numerical indexing}
+\label{subsec:DOM_Num_Index}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]  \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_index_hor}
+\caption{   \protect\label{fig:index_hor}    
+Horizontal integer indexing used in the \textsc{Fortran} code. The dashed area indicates 
+the cell in which variables contained in arrays have the same $i$- and $j$-indices}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The array representation used in the \textsc{Fortran} code requires an integer 
+indexing while the analytical definition of the mesh (see \autoref{subsec:DOM_cell}) is 
+associated with the use of integer values for $t$-points and both integer and 
+integer and a half values for all the other points. Therefore a specific integer 
+indexing must be defined for points other than $t$-points ($i.e.$ velocity and 
+vorticity grid-points). Furthermore, the direction of the vertical indexing has 
+been changed so that the surface level is at $k=1$.
+
+% -----------------------------------
+%        Horizontal Indexing 
+% -----------------------------------
+\subsubsection{Horizontal indexing}
+\label{subsec:DOM_Num_Index_hor}
+
+The indexing in the horizontal plane has been chosen as shown in \autoref{fig:index_hor}. 
+For an increasing $i$ index ($j$ index), the $t$-point and the eastward $u$-point 
+(northward $v$-point) have the same index (see the dashed area in \autoref{fig:index_hor}). 
+A $t$-point and its nearest northeast $f$-point have the same $i$-and $j$-indices.
+
+% -----------------------------------
+%        Vertical indexing 
+% -----------------------------------
+\subsubsection{Vertical indexing}
+\label{subsec:DOM_Num_Index_vertical}
+
+In the vertical, the chosen indexing requires special attention since the 
+$k$-axis is re-orientated downward in the \textsc{Fortran} code compared 
+to the indexing used in the semi-discrete equations and given in \autoref{subsec:DOM_cell}. 
+The sea surface corresponds to the $w$-level $k=1$ which is the same index 
+as $t$-level just below (\autoref{fig:index_vert}). The last $w$-level ($k=jpk$) 
+either corresponds to the ocean floor or is inside the bathymetry while the last 
+$t$-level is always inside the bathymetry (\autoref{fig:index_vert}). Note that 
+for an increasing $k$ index, a $w$-point and the $t$-point just below have the 
+same $k$ index, in opposition to what is done in the horizontal plane where 
+it is the $t$-point and the nearest velocity points in the direction of the horizontal 
+axis that have the same $i$ or $j$ index (compare the dashed area in 
+\autoref{fig:index_hor} and \autoref{fig:index_vert}). Since the scale factors are 
+chosen to be strictly positive, a \emph{minus sign} appears in the \textsc{Fortran} 
+code \emph{before all the vertical derivatives} of the discrete equations given in 
+this documentation.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!pt]    \begin{center}
+\includegraphics[width=.90\textwidth]{Fig_index_vert}
+\caption{ \protect\label{fig:index_vert}     
+Vertical integer indexing used in the \textsc{Fortran } code. Note that 
+the $k$-axis is orientated downward. The dashed area indicates the cell in 
+which variables contained in arrays have the same $k$-index.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -----------------------------------
+%        Domain Size
+% -----------------------------------
+\subsubsection{Domain size}
+\label{subsec:DOM_size}
+
+The total size of the computational domain is set by the parameters \np{jpiglo}, 
+\np{jpjglo} and \np{jpkglo} in the $i$, $j$ and $k$ directions respectively. 
+%%%
+%%%
+%%%
+Parameters $jpi$ and $jpj$ refer to the size of each processor subdomain when the code is 
+run in parallel using domain decomposition (\key{mpp\_mpi} defined, see \autoref{sec:LBC_mpp}).
+
+
+$\ $\newline    % force a new line
+
+% ================================================================
+% Domain: List of fields needed
+% ================================================================
+\section{Needed fields}
+\label{sec:DOM_fields}
+The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined 
+by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
+The grid-points are located at integer or integer and a half values of as indicated 
+in \autoref{tab:cell}. The associated scale factors are defined using the  
+analytical first derivative of the transformation \autoref{eq:scale_factors}. 
+Necessary fields for configuration definition are: \\
+Geographic position :
+
+longitude : glamt , glamu , glamv and glamf  (at T, U, V and F point)
+
+latitude : gphit , gphiu , gphiv and gphif (at T, U, V and F point)\\
+Coriolis parameter (if domain not on the sphere): 
+
+ ff\_f  and  ff\_t (at T and F point)\\
+Scale factors : 
+ 
+ e1t, e1u, e1v and e1f (on i direction),
+
+ e2t, e2u, e2v and e2f (on j direction)
+
+ and ie1e2u\_v, e1e2u , e1e2v   
+ 
+e1e2u , e1e2v are u and v surfaces (if gridsize reduction in some straits)\\
+ie1e2u\_v is a flag to flag set u and  v surfaces are neither read nor computed.\\
+ 
+These fields can be read in an domain input file which name is setted in \np{cn\_domcfg} parameter specified in \ngn{namcfg}.
+
+\nlst{namcfg}
+or they can be defined in an analytical way in MY\_SRC directory of the configuration.
+For Reference Configurations of NEMO input domain files are supplied by NEMO System Team. For analytical definition of input fields two routines are supplied: \mdl{userdef\_hgr} and \mdl{userdef\_zgr}. They are an example of GYRE configuration parameters, and they are available in NEMO/OPA\_SRC/USR directory, they provide the horizontal and vertical mesh. 
+% -------------------------------------------------------------------------------------------------------------
+%        Needed fields 
+% -------------------------------------------------------------------------------------------------------------
+%\subsection{List of needed fields to build DOMAIN}
+%\label{subsec:DOM_fields_list}
+
+
+% ================================================================
+% Domain: Horizontal Grid (mesh) 
+% ================================================================
+\section{Horizontal grid mesh (\protect\mdl{domhgr})}
+\label{sec:DOM_hgr}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Coordinates and scale factors 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Coordinates and scale factors}
+\label{subsec:DOM_hgr_coord_e}
+
+The ocean mesh ($i.e.$ the position of all the scalar and vector points) is defined 
+by the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$. 
+The grid-points are located at integer or integer and a half values of as indicated 
+in \autoref{tab:cell}. The associated scale factors are defined using the 
+analytical first derivative of the transformation \autoref{eq:scale_factors}. These 
+definitions are done in two modules, \mdl{domhgr} and \mdl{domzgr}, which 
+provide the horizontal and vertical meshes, respectively. This section deals with 
+the horizontal mesh parameters.
+
+In a horizontal plane, the location of all the model grid points is defined from the 
+analytical expressions of the longitude $\lambda$ and  latitude $\varphi$ as a 
+function of  $(i,j)$. The horizontal scale factors are calculated using 
+\autoref{eq:scale_factors}. For example, when the longitude and latitude are 
+function of a single value ($i$ and $j$, respectively) (geographical configuration 
+of the mesh), the horizontal mesh definition reduces to define the wanted 
+$\lambda(i)$, $\varphi(j)$, and their derivatives $\lambda'(i)$ $\varphi'(j)$ in the 
+\mdl{domhgr} module. The model computes the grid-point positions and scale 
+factors in the horizontal plane as follows:
+\begin{flalign*}
+\lambda_t &\equiv \text{glamt}= \lambda(i)	  & \varphi_t &\equiv \text{gphit} = \varphi(j)\\
+\lambda_u &\equiv \text{glamu}= \lambda(i+1/2)& \varphi_u &\equiv \text{gphiu}= \varphi(j)\\
+\lambda_v &\equiv \text{glamv}= \lambda(i)       & \varphi_v &\equiv \text{gphiv} = \varphi(j+1/2)\\
+\lambda_f &\equiv \text{glamf }= \lambda(i+1/2)& \varphi_f &\equiv \text{gphif }= \varphi(j+1/2) 
+\end{flalign*}
+\begin{flalign*}
+e_{1t} &\equiv \text{e1t} = r_a |\lambda'(i)		\; \cos\varphi(j)  |&
+e_{2t} &\equiv \text{e2t} = r_a |\varphi'(j)|  \\
+e_{1u} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)	\; \cos\varphi(j)  |&
+e_{2u} &\equiv \text{e2t} = r_a |\varphi'(j)|\\
+e_{1v} &\equiv \text{e1t} = r_a |\lambda'(i)		\; \cos\varphi(j+1/2)  |&
+e_{2v} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|\\
+e_{1f} &\equiv \text{e1t} = r_a |\lambda'(i+1/2)\; \cos\varphi(j+1/2)  |&
+e_{2f} &\equiv \text{e2t} = r_a |\varphi'(j+1/2)|
+\end{flalign*}
+where the last letter of each computational name indicates the grid point 
+considered and $r_a$ is the earth radius (defined in \mdl{phycst} along with 
+all universal constants). Note that the horizontal position of and scale factors 
+at $w$-points are exactly equal to those of $t$-points, thus no specific arrays 
+are defined at $w$-points. 
+
+Note that the definition of the scale factors ($i.e.$ as the analytical first derivative 
+of the transformation that gives $(\lambda,\varphi,z)$ as a function of $(i,j,k)$) is 
+specific to the \NEMO model \citep{Marti_al_JGR92}. As an example, $e_{1t}$ is defined 
+locally at a $t$-point, whereas many other models on a C grid choose to define 
+such a scale factor as the distance between the $U$-points on each side of the 
+$t$-point. Relying on an analytical transformation has two advantages: firstly, there 
+is no ambiguity in the scale factors appearing in the discrete equations, since they 
+are first introduced in the continuous equations; secondly, analytical transformations 
+encourage good practice by the definition of smoothly varying grids (rather than 
+allowing the user to set arbitrary jumps in thickness between adjacent layers) 
+\citep{Treguier1996}. An example of the effect of such a choice is shown in 
+\autoref{fig:zgr_e3}.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]     \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_zgr_e3}
+\caption{ \protect\label{fig:zgr_e3}    
+Comparison of (a) traditional definitions of grid-point position and grid-size in the vertical, 
+and (b) analytically derived grid-point position and scale factors. 
+For both grids here,  the same $w$-point depth has been chosen but in (a) the 
+$t$-points are set half way between $w$-points while in (b) they are defined from 
+an analytical function: $z(k)=5\,(k-1/2)^3 - 45\,(k-1/2)^2 + 140\,(k-1/2) - 150$. 
+Note the resulting difference between the value of the grid-size $\Delta_k$ and 
+those of the scale factor $e_k$. }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        Choice of horizontal grid
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Choice of horizontal grid}
+\label{subsec:DOM_hgr_msh_choice}
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Grid files
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Output grid files}
+\label{subsec:DOM_hgr_files}
+
+All the arrays relating to a particular ocean model configuration (grid-point 
+position, scale factors, masks) can be saved in files if \np{nn\_msh} $\not= 0$ 
+(namelist variable in \ngn{namdom}). This can be particularly useful for plots and off-line 
+diagnostics. In some cases, the user may choose to make a local modification 
+of a scale factor in the code. This is the case in global configurations when 
+restricting the width of a specific strait (usually a one-grid-point strait that 
+happens to be too wide due to insufficient model resolution). An example 
+is Gibraltar Strait in the ORCA2 configuration. When such modifications are done, 
+the output grid written when \np{nn\_msh} $\not= 0$ is no more equal to the input grid.
+
+$\ $\newline    % force a new line
+
+% ================================================================
+% Domain: Vertical Grid (domzgr)
+% ================================================================
+\section{Vertical grid (\protect\mdl{domzgr})}
+\label{sec:DOM_zgr}
+%-----------------------------------------nam_zgr & namdom-------------------------------------------
+%
+%\nlst{namzgr} 
+
+\nlst{namdom} 
+%-------------------------------------------------------------------------------------------------------------
+
+Variables are defined through the \ngn{namzgr} and \ngn{namdom} namelists.
+In the vertical, the model mesh is determined by four things: 
+(1) the bathymetry given in meters ; 
+(2) the number of levels of the model (\jp{jpk}) ; 
+(3) the analytical transformation $z(i,j,k)$ and the vertical scale factors 
+(derivatives of the transformation) ; 
+and (4) the masking system, $i.e.$ the number of wet model levels at each 
+$(i,j)$ column of points.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]    \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_z_zps_s_sps}
+\caption{  \protect\label{fig:z_zps_s_sps}   
+The ocean bottom as seen by the model: 
+(a) $z$-coordinate with full step, 
+(b) $z$-coordinate with partial step, 
+(c) $s$-coordinate: terrain following representation, 
+(d) hybrid $s-z$ coordinate, 
+(e) hybrid $s-z$ coordinate with partial step, and 
+(f) same as (e) but in the non-linear free surface (\protect\np{ln\_linssh}\forcode{ = .false.}). 
+Note that the non-linear free surface can be used with any of the 
+5 coordinates (a) to (e).}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The choice of a vertical coordinate, even if it is made through \ngn{namzgr} namelist parameters, 
+must be done once of all at the beginning of an experiment. It is not intended as an 
+option which can be enabled or disabled in the middle of an experiment. Three main 
+choices are offered (\autoref{fig:z_zps_s_sps}a to c): $z$-coordinate with full step 
+bathymetry (\np{ln\_zco}\forcode{ = .true.}), $z$-coordinate with partial step bathymetry 
+(\np{ln\_zps}\forcode{ = .true.}), or generalized, $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}). 
+Hybridation of the three main coordinates are available: $s-z$ or $s-zps$ coordinate 
+(\autoref{fig:z_zps_s_sps}d and \autoref{fig:z_zps_s_sps}e). By default a non-linear free surface is used:
+the coordinate follow the time-variation of the free surface so that the transformation is time dependent: 
+$z(i,j,k,t)$ (\autoref{fig:z_zps_s_sps}f). When a linear free surface is assumed (\np{ln\_linssh}\forcode{ = .true.}), 
+the vertical coordinate are fixed in time, but the seawater can move up and down across the z=0 surface 
+(in other words, the top of the ocean in not a rigid-lid). 
+The last choice in terms of vertical coordinate concerns the presence (or not) in the model domain 
+of ocean cavities beneath ice shelves. Setting \np{ln\_isfcav} to true allows to manage ocean cavities, 
+otherwise they are filled in. This option is currently only available in $z$- or $zps$-coordinate,
+and partial step are also applied at the ocean/ice shelf interface. 
+
+Contrary to the horizontal grid, the vertical grid is computed in the code and no 
+provision is made for reading it from a file. The only input file is the bathymetry 
+(in meters) (\ifile{bathy\_meter}). 
+\footnote{N.B. in full step $z$-coordinate, a \ifile{bathy\_level} file can replace the 
+\ifile{bathy\_meter} file, so that the computation of the number of wet ocean point 
+in each water column is by-passed}. 
+If \np{ln\_isfcav}\forcode{ = .true.}, an extra file input file describing the ice shelf draft 
+(in meters) (\ifile{isf\_draft\_meter}) is needed.
+
+After reading the bathymetry, the algorithm for vertical grid definition differs 
+between the different options:
+\begin{description}
+\item[\textit{zco}] set a reference coordinate transformation $z_0 (k)$, and set $z(i,j,k,t)=z_0 (k)$.
+\item[\textit{zps}] set a reference coordinate transformation $z_0 (k)$, and 
+calculate the thickness of the deepest level at each $(i,j)$ point using the 
+bathymetry, to obtain the final three-dimensional depth and scale factor arrays.
+\item[\textit{sco}] smooth the bathymetry to fulfil the hydrostatic consistency 
+criteria and set the three-dimensional transformation.
+\item[\textit{s-z} and \textit{s-zps}] smooth the bathymetry to fulfil the hydrostatic 
+consistency criteria and set the three-dimensional transformation $z(i,j,k)$, and 
+possibly introduce masking of extra land points to better fit the original bathymetry file
+\end{description}
+%%%
+\gmcomment{   add the description of the smoothing:  envelop topography...}
+%%%
+
+Unless a linear free surface is used (\np{ln\_linssh}\forcode{ = .false.}), the arrays describing 
+the grid point depths and vertical scale factors are three set of three dimensional arrays $(i,j,k)$ 
+defined at \textit{before}, \textit{now} and \textit{after} time step. The time at which they are
+defined is indicated by a suffix:$\_b$, $\_n$, or $\_a$, respectively. They are updated at each model time step
+using a fixed reference coordinate system which computer names have a $\_0$ suffix. 
+When the linear free surface option is used (\np{ln\_linssh}\forcode{ = .true.}), \textit{before}, \textit{now} 
+and \textit{after} arrays are simply set one for all to their reference counterpart. 
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Meter Bathymetry
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Meter bathymetry}
+\label{subsec:DOM_bathy}
+
+Three options are possible for defining the bathymetry, according to the 
+namelist variable \np{nn\_bathy} (found in \ngn{namdom} namelist): 
+\begin{description}
+\item[\np{nn\_bathy}\forcode{ = 0}]: a flat-bottom domain is defined. The total depth $z_w (jpk)$ 
+is given by the coordinate transformation. The domain can either be a closed 
+basin or a periodic channel depending on the parameter \np{jperio}. 
+\item[\np{nn\_bathy}\forcode{ = -1}]: a domain with a bump of topography one third of the 
+domain width at the central latitude. This is meant for the "EEL-R5" configuration, 
+a periodic or open boundary channel with a seamount. 
+\item[\np{nn\_bathy}\forcode{ = 1}]: read a bathymetry and ice shelf draft (if needed).
+ The \ifile{bathy\_meter} file (Netcdf format) provides the ocean depth (positive, in meters)
+ at each grid point of the model grid. The bathymetry is usually built by interpolating a standard bathymetry product 
+($e.g.$ ETOPO2) onto the horizontal ocean mesh. Defining the bathymetry also 
+defines the coastline: where the bathymetry is zero, no model levels are defined 
+(all levels are masked).
+
+The \ifile{isfdraft\_meter} file (Netcdf format) provides the ice shelf draft (positive, in meters)
+ at each grid point of the model grid. This file is only needed if \np{ln\_isfcav}\forcode{ = .true.}. 
+Defining the ice shelf draft will also define the ice shelf edge and the grounding line position.
+\end{description}
+
+When a global ocean is coupled to an atmospheric model it is better to represent 
+all large water bodies (e.g, great lakes, Caspian sea...) even if the model 
+resolution does not allow their communication with the rest of the ocean. 
+This is unnecessary when the ocean is forced by fixed atmospheric conditions, 
+so these seas can be removed from the ocean domain. The user has the option 
+to set the bathymetry in closed seas to zero (see \autoref{sec:MISC_closea}), but the 
+code has to be adapted to the user's configuration. 
+
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate  and reference coordinate transformation
+% -------------------------------------------------------------------------------------------------------------
+\subsection[$Z$-coordinate (\protect\np{ln\_zco}\forcode{ = .true.}) and ref. coordinate]
+				{$Z$-coordinate (\protect\np{ln\_zco}\forcode{ = .true.}) and reference coordinate}
+\label{subsec:DOM_zco}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb]    \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_zgr}
+\caption{ \protect\label{fig:zgr}    
+Default vertical mesh for ORCA2: 30 ocean levels (L30). Vertical level functions for 
+(a) T-point depth and (b) the associated scale factor as computed 
+from \autoref{eq:DOM_zgr_ana_1} using \autoref{eq:DOM_zgr_coef} in $z$-coordinate.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The reference coordinate transformation $z_0 (k)$ defines the arrays $gdept_0$ 
+and $gdepw_0$ for $t$- and $w$-points, respectively. As indicated on 
+\autoref{fig:index_vert} \jp{jpk} is the number of $w$-levels. $gdepw_0(1)$ is the 
+ocean surface. There are at most \jp{jpk}-1 $t$-points inside the ocean, the 
+additional $t$-point at $jk=jpk$ is below the sea floor and is not used. 
+The vertical location of $w$- and $t$-levels is defined from the analytic expression 
+of the depth $z_0(k)$ whose analytical derivative with respect to $k$ provides the 
+vertical scale factors. The user must provide the analytical expression of both 
+$z_0$ and its first derivative with respect to $k$. This is done in routine \mdl{domzgr} 
+through statement functions, using parameters provided in the \ngn{namcfg} namelist. 
+
+It is possible to define a simple regular vertical grid by giving zero stretching (\np{ppacr=0}). 
+In that case, the parameters \jp{jpk} (number of $w$-levels) and \np{pphmax} 
+(total ocean depth in meters) fully define the grid. 
+
+For climate-related studies it is often desirable to concentrate the vertical resolution 
+near the ocean surface. The following function is proposed as a standard for a 
+$z$-coordinate (with either full or partial steps): 
+\begin{equation} \label{eq:DOM_zgr_ana_1}
+\begin{split}
+ z_0 (k) 	&= h_{sur} -h_0 \;k-\;h_1 \;\log \left[ {\,\cosh \left( {{(k-h_{th} )} / {h_{cr} }} \right)\,} \right] \\ 
+ e_3^0 (k) 	&= \left| -h_0 -h_1 \;\tanh \left( {{(k-h_{th} )} / {h_{cr} }} \right) \right| 
+\end{split}
+\end{equation}
+where $k=1$ to \jp{jpk} for $w$-levels and $k=1$ to $k=1$ for $T-$levels. Such an 
+expression allows us to define a nearly uniform vertical location of levels at the 
+ocean top and bottom with a smooth hyperbolic tangent transition in between 
+(\autoref{fig:zgr}).
+
+If the ice shelf cavities are opened (\np{ln\_isfcav}\forcode{ = .true.}), the definition of $z_0$ is the same. 
+However, definition of $e_3^0$ at $t$- and $w$-points is respectively changed to:
+\begin{equation} \label{eq:DOM_zgr_ana_2}
+\begin{split}
+ e_3^T(k) &= z_W (k+1) - z_W (k)   \\
+ e_3^W(k) &= z_T (k)   - z_T (k-1) \\
+\end{split}
+\end{equation}
+This formulation decrease the self-generated circulation into the ice shelf cavity 
+(which can, in extreme case, leads to blow up).\\
+
+ 
+The most used vertical grid for ORCA2 has $10~m$ ($500~m)$ resolution in the 
+surface (bottom) layers and a depth which varies from 0 at the sea surface to a 
+minimum of $-5000~m$. This leads to the following conditions:
+\begin{equation} \label{eq:DOM_zgr_coef}
+\begin{split}
+ e_3 (1+1/2)		&=10. \\ 
+ e_3 (jpk-1/2)	&=500. \\ 
+ z(1)			&=0. \\ 
+ z(jpk)			&=-5000. \\ 
+\end{split}
+\end{equation}
+
+With the choice of the stretching $h_{cr} =3$ and the number of levels 
+\jp{jpk}=$31$, the four coefficients $h_{sur}$, $h_{0}$, $h_{1}$, and $h_{th}$ in 
+\autoref{eq:DOM_zgr_ana_2} have been determined such that \autoref{eq:DOM_zgr_coef} is 
+satisfied, through an optimisation procedure using a bisection method. For the first 
+standard ORCA2 vertical grid this led to the following values: $h_{sur} =4762.96$, 
+$h_0 =255.58, h_1 =245.5813$, and $h_{th} =21.43336$. The resulting depths and 
+scale factors as a function of the model levels are shown in \autoref{fig:zgr} and 
+given in \autoref{tab:orca_zgr}. Those values correspond to the parameters 
+\np{ppsur}, \np{ppa0}, \np{ppa1}, \np{ppkth} in \ngn{namcfg} namelist. 
+
+Rather than entering parameters $h_{sur}$, $h_{0}$, and $h_{1}$ directly, it is 
+possible to recalculate them. In that case the user sets 
+\np{ppsur}\forcode{ = }\np{ppa0}\forcode{ = }\np{ppa1}\forcode{ = 999999}., in \ngn{namcfg} namelist, 
+and specifies instead the four following parameters:
+\begin{itemize}
+\item 	\np{ppacr}=$h_{cr} $: stretching factor (nondimensional). The larger 
+\np{ppacr}, the smaller the stretching. Values from $3$ to $10$ are usual.
+\item 	\np{ppkth}=$h_{th} $: is approximately the model level at which maximum 
+stretching occurs (nondimensional, usually of order 1/2 or 2/3 of \jp{jpk})
+\item 	\np{ppdzmin}: minimum thickness for the top layer (in meters)
+\item 	\np{pphmax}: total depth of the ocean (meters).
+\end{itemize}
+As an example, for the $45$ layers used in the DRAKKAR configuration those 
+parameters are: \jp{jpk}\forcode{ = 46}, \np{ppacr}\forcode{ = 9}, \np{ppkth}\forcode{ = 23.563}, \np{ppdzmin}\forcode{ = 6}m, \np{pphmax}\forcode{ = 5750}m.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{table}     \begin{center} \begin{tabular}{c||r|r|r|r}
+\hline
+\textbf{LEVEL}& \textbf{gdept\_1d}& \textbf{gdepw\_1d}& \textbf{e3t\_1d }& \textbf{e3w\_1d  } \\ \hline
+1	&	\textbf{  5.00}	&       0.00 &	\textbf{ 10.00} &	 10.00 \\	\hline
+2	&	\textbf{15.00}	& 	  10.00 &	\textbf{ 10.00} &	 10.00 \\	\hline
+3	&	\textbf{25.00}	&	  20.00 &	\textbf{ 10.00} & 	 10.00 \\	\hline
+4	&	\textbf{35.01}	&	  30.00 & 	\textbf{ 10.01} & 	 10.00 \\	\hline
+5	&	\textbf{45.01}	&	  40.01 &	\textbf{ 10.01} &	 10.01 \\	\hline
+6	&	\textbf{55.03}	&	  50.02 &	\textbf{ 10.02} & 	 10.02 \\	\hline
+7	&	\textbf{65.06}	&	  60.04 &	\textbf{ 10.04} &	 10.03 \\	\hline
+8	&	\textbf{75.13}	&	  70.09 &	\textbf{ 10.09} &	 10.06 \\	\hline
+9	&	\textbf{85.25}	&	  80.18 &	\textbf{ 10.17} &	 10.12 \\	\hline
+10	& 	\textbf{95.49}	& 	  90.35 &	\textbf{ 10.33} &	 10.24 \\	\hline
+11	& 	\textbf{105.97}	& 	 100.69 &	\textbf{ 10.65} &	 10.47 \\	\hline
+12	& 	\textbf{116.90}	& 	 111.36 &	\textbf{ 11.27} &	 10.91 \\	\hline
+13	& 	\textbf{128.70}	& 	 122.65 &	\textbf{ 12.47} &	 11.77 \\	\hline
+14	& 	\textbf{142.20}	& 	 135.16 &	\textbf{ 14.78} &	 13.43 \\	\hline
+15	& 	\textbf{158.96}	& 	 150.03 &	\textbf{ 19.23} &	 16.65 \\	\hline
+16	& 	\textbf{181.96}	& 	 169.42 &	\textbf{ 27.66} &	 22.78 \\	\hline
+17	& 	\textbf{216.65}	& 	 197.37 & 	\textbf{ 43.26} &	 34.30 \\ \hline
+18	& 	\textbf{272.48}	& 	 241.13 & 	\textbf{ 70.88} &	 55.21 \\ \hline
+19	& 	\textbf{364.30}	& 	 312.74 & 	\textbf{116.11} &	 90.99 \\ \hline
+20	& 	\textbf{511.53}	& 	 429.72 & 	\textbf{181.55} & 	146.43 \\ \hline
+21	& 	\textbf{732.20}	& 	 611.89 & 	\textbf{261.03} & 	220.35 \\ \hline
+22	& 	\textbf{1033.22}&	 872.87 & 	\textbf{339.39} & 	301.42 \\ \hline
+23	& 	\textbf{1405.70}&	1211.59 & \textbf{402.26} & 	373.31 \\ \hline
+24	& 	\textbf{1830.89}&	1612.98 & \textbf{444.87} & 	426.00 \\ \hline
+25	& 	\textbf{2289.77}&	2057.13 & \textbf{470.55} & 	459.47 \\ \hline
+26	& 	\textbf{2768.24}&	2527.22 & \textbf{484.95} & 	478.83 \\ \hline
+27	& 	\textbf{3257.48}&	3011.90 & \textbf{492.70} & 	489.44 \\ \hline
+28	& 	\textbf{3752.44}&	3504.46 & \textbf{496.78} & 	495.07 \\ \hline
+29	& 	\textbf{4250.40}&	4001.16 & \textbf{498.90} & 	498.02 \\ \hline
+30	& 	\textbf{4749.91}&	4500.02 & \textbf{500.00} &	499.54 \\ \hline
+31	& 	\textbf{5250.23}&	5000.00 &	\textbf{500.56} &	500.33 \\ \hline
+\end{tabular} \end{center} 
+\caption{ \protect\label{tab:orca_zgr}   
+Default vertical mesh in $z$-coordinate for 30 layers ORCA2 configuration as computed 
+from \autoref{eq:DOM_zgr_ana_2} using the coefficients given in \autoref{eq:DOM_zgr_coef}}
+\end{table}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        z-coordinate with partial step
+% -------------------------------------------------------------------------------------------------------------
+\subsection{$Z$-coordinate with partial step (\protect\np{ln\_zps}\forcode{ = .true.})}
+\label{subsec:DOM_zps}
+%--------------------------------------------namdom-------------------------------------------------------
+
+\nlst{namdom} 
+%--------------------------------------------------------------------------------------------------------------
+
+In $z$-coordinate partial step, the depths of the model levels are defined by the 
+reference analytical function $z_0 (k)$ as described in the previous 
+section, \emph{except} in the bottom layer. The thickness of the bottom layer is 
+allowed to vary as a function of geographical location $(\lambda,\varphi)$ to allow a 
+better representation of the bathymetry, especially in the case of small 
+slopes (where the bathymetry varies by less than one level thickness from 
+one grid point to the next). The reference layer thicknesses $e_{3t}^0$ have been 
+defined in the absence of bathymetry. With partial steps, layers from 1 to 
+\jp{jpk}-2 can have a thickness smaller than $e_{3t}(jk)$. The model deepest layer (\jp{jpk}-1) 
+is allowed to have either a smaller or larger thickness than $e_{3t}(jpk)$: the 
+maximum thickness allowed is $2*e_{3t}(jpk-1)$. This has to be kept in mind when 
+specifying values in \ngn{namdom} namelist, as the maximum depth \np{pphmax} 
+in partial steps: for example, with 
+\np{pphmax}$=5750~m$ for the DRAKKAR 45 layer grid, the maximum ocean depth 
+allowed is actually $6000~m$ (the default thickness $e_{3t}(jpk-1)$ being $250~m$). 
+Two variables in the namdom namelist are used to define the partial step 
+vertical grid. The mimimum water thickness (in meters) allowed for a cell 
+partially filled with bathymetry at level jk is the minimum of \np{rn\_e3zps\_min} 
+(thickness in meters, usually $20~m$) or $e_{3t}(jk)*$\np{rn\_e3zps\_rat} (a fraction, 
+usually 10\%, of the default thickness $e_{3t}(jk)$).
+
+\gmcomment{ \colorbox{yellow}{Add a figure here of pstep especially at last ocean level }  }
+
+% -------------------------------------------------------------------------------------------------------------
+%        s-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsection{$S$-coordinate (\protect\np{ln\_sco}\forcode{ = .true.})}
+\label{subsec:DOM_sco}
+%------------------------------------------nam_zgr_sco---------------------------------------------------
+%
+%\nlst{namzgr_sco} 
+%--------------------------------------------------------------------------------------------------------------
+Options are defined in \ngn{namzgr\_sco}.
+In $s$-coordinate (\np{ln\_sco}\forcode{ = .true.}), the depth and thickness of the model 
+levels are defined from the product of a depth field and either a stretching 
+function or its derivative, respectively:
+
+\begin{equation} \label{eq:DOM_sco_ana}
+\begin{split}
+ z(k) 		&= h(i,j) \; z_0(k)	\\
+ e_3(k)	&= h(i,j) \; z_0'(k)
+\end{split}
+\end{equation}
+
+where $h$ is the depth of the last $w$-level ($z_0(k)$) defined at the $t$-point 
+location in the horizontal and $z_0(k)$ is a function which varies from $0$ at the sea 
+surface to $1$ at the ocean bottom. The depth field $h$ is not necessary the ocean 
+depth, since a mixed step-like and bottom-following representation of the 
+topography can be used (\autoref{fig:z_zps_s_sps}d-e) or an envelop bathymetry can be defined (\autoref{fig:z_zps_s_sps}f).
+The namelist parameter \np{rn\_rmax} determines the slope at which the terrain-following coordinate intersects 
+the sea bed and becomes a pseudo z-coordinate. 
+The coordinate can also be hybridised by specifying \np{rn\_sbot\_min} and \np{rn\_sbot\_max} 
+as the minimum and maximum depths at which the terrain-following vertical coordinate is calculated.
+
+Options for stretching the coordinate are provided as examples, but care must be taken to ensure 
+that the vertical stretch used is appropriate for the application.
+
+The original default NEMO s-coordinate stretching is available if neither of the other options 
+are specified as true (\np{ln\_s\_SH94}\forcode{ = .false.} and \np{ln\_s\_SF12}\forcode{ = .false.}). 
+This uses a depth independent $\tanh$ function for the stretching \citep{Madec_al_JPO96}:
+
+\begin{equation}
+  z = s_{min}+C\left(s\right)\left(H-s_{min}\right)
+  \label{eq:SH94_1}
+\end{equation}
+
+where $s_{min}$ is the depth at which the $s$-coordinate stretching starts and 
+allows a $z$-coordinate to placed on top of the stretched coordinate, 
+and $z$ is the depth (negative down from the asea surface).
+
+\begin{equation}
+  s = -\frac{k}{n-1} \quad \text{ and } \quad 0 \leq k \leq n-1
+  \label{eq:DOM_s}
+\end{equation}
+
+\begin{equation} \label{eq:DOM_sco_function}
+\begin{split}
+C(s)	&=  \frac{ \left[	  \tanh{ \left( \theta \, (s+b) \right)} 
+	  	 			- \tanh{ \left(  \theta \, b      \right)}  \right]}
+		      {2\;\sinh \left( \theta \right)}
+\end{split}
+\end{equation}
+
+A stretching function, modified from the commonly used \citet{Song_Haidvogel_JCP94} 
+stretching (\np{ln\_s\_SH94}\forcode{ = .true.}), is also available and is more commonly used for shelf seas modelling:
+
+\begin{equation}
+  C\left(s\right) =   \left(1 - b \right)\frac{ \sinh\left( \theta s\right)}{\sinh\left(\theta\right)} +      \\
+  b\frac{ \tanh \left[ \theta \left(s + \frac{1}{2} \right)\right] - \tanh\left(\frac{\theta}{2}\right)}{ 2\tanh\left (\frac{\theta}{2}\right)}
+  \label{eq:SH94_2}
+\end{equation}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]    \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_sco_function}
+\caption{  \protect\label{fig:sco_function}   
+Examples of the stretching function applied to a seamount; from left to right: 
+surface, surface and bottom, and bottom intensified resolutions}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+where $H_c$ is the critical depth (\np{rn\_hc}) at which the coordinate transitions from 
+pure $\sigma$ to the stretched coordinate,  and $\theta$ (\np{rn\_theta}) and $b$ (\np{rn\_bb}) 
+are the surface and bottom control parameters such that $0\leqslant \theta \leqslant 20$, and 
+$0\leqslant b\leqslant 1$. $b$ has been designed to allow surface and/or bottom 
+increase of the vertical resolution (\autoref{fig:sco_function}).
+
+Another example has been provided at version 3.5 (\np{ln\_s\_SF12}) that allows 
+a fixed surface resolution in an analytical terrain-following stretching \citet{Siddorn_Furner_OM12}. 
+In this case the a stretching function $\gamma$ is defined such that:
+
+\begin{equation}
+z = -\gamma h \quad \text{ with } \quad 0 \leq \gamma \leq 1
+\label{eq:z}
+\end{equation}
+
+The function is defined with respect to $\sigma$, the unstretched terrain-following coordinate:
+
+\begin{equation} \label{eq:DOM_gamma_deriv}
+\gamma= A\left(\sigma-\frac{1}{2}\left(\sigma^{2}+f\left(\sigma\right)\right)\right)+B\left(\sigma^{3}-f\left(\sigma\right)\right)+f\left(\sigma\right)
+\end{equation}
+
+Where:
+\begin{equation} \label{eq:DOM_gamma}
+f\left(\sigma\right)=\left(\alpha+2\right)\sigma^{\alpha+1}-\left(\alpha+1\right)\sigma^{\alpha+2} \quad \text{ and } \quad \sigma = \frac{k}{n-1} 
+\end{equation}
+
+This gives an analytical stretching of $\sigma$ that is solvable in $A$ and $B$ as a function of 
+the user prescribed stretching parameter $\alpha$ (\np{rn\_alpha}) that stretches towards 
+the surface ($\alpha > 1.0$) or the bottom ($\alpha < 1.0$) and user prescribed surface (\np{rn\_zs}) 
+and bottom depths. The bottom cell depth in this example is given as a function of water depth:
+
+\begin{equation} \label{eq:DOM_zb}
+Z_b= h a + b
+\end{equation}
+
+where the namelist parameters \np{rn\_zb\_a} and \np{rn\_zb\_b} are $a$ and $b$ respectively.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]
+   \includegraphics[width=1.0\textwidth]{FIG_DOM_compare_coordinates_surface}
+        \caption{A comparison of the \citet{Song_Haidvogel_JCP94} $S$-coordinate (solid lines), a 50 level $Z$-coordinate (contoured surfaces) and the \citet{Siddorn_Furner_OM12} $S$-coordinate (dashed lines) in the surface 100m for a idealised bathymetry that goes from 50m to 5500m depth. For clarity every third coordinate surface is shown.}
+    \label{fig:fig_compare_coordinates_surface}
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+This gives a smooth analytical stretching in computational space that is constrained to given specified surface and bottom grid cell thicknesses in real space. This is not to be confused with the hybrid schemes that superimpose geopotential coordinates on terrain following coordinates thus creating a non-analytical vertical coordinate that therefore may suffer from large gradients in the vertical resolutions. This stretching is less straightforward to implement than the \citet{Song_Haidvogel_JCP94} stretching, but has the advantage of resolving diurnal processes in deep water and has generally flatter slopes.
+
+As with the \citet{Song_Haidvogel_JCP94} stretching the stretch is only applied at depths greater than the critical depth $h_c$. In this example two options are available in depths shallower than $h_c$, with pure sigma being applied if the \np{ln\_sigcrit} is true and pure z-coordinates if it is false (the z-coordinate being equal to the depths of the stretched coordinate at $h_c$.
+
+Minimising the horizontal slope of the vertical coordinate is important in terrain-following systems as large slopes lead to hydrostatic consistency. A hydrostatic consistency parameter diagnostic following \citet{Haney1991} has been implemented, and is output as part of the model mesh file at the start of the run.
+
+% -------------------------------------------------------------------------------------------------------------
+%        z*- or s*-coordinate
+% -------------------------------------------------------------------------------------------------------------
+\subsection{$Z^*$- or $S^*$-coordinate (\protect\np{ln\_linssh}\forcode{ = .false.}) }
+\label{subsec:DOM_zgr_star}
+
+This option is described in the Report by Levier \textit{et al.} (2007), available on the \NEMO web site. 
+
+%gm% key advantage: minimise the diffusion/dispertion associated with advection in response to high frequency surface disturbances
+
+% -------------------------------------------------------------------------------------------------------------
+%        level bathymetry and mask 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Level bathymetry and mask}
+\label{subsec:DOM_msk}
+
+Whatever the vertical coordinate used, the model offers the possibility of 
+representing the bottom topography with steps that follow the face of the 
+model cells (step like topography) \citep{Madec_al_JPO96}. The distribution of 
+the steps in the horizontal is defined in a 2D integer array, mbathy, which 
+gives the number of ocean levels ($i.e.$ those that are not masked) at each 
+$t$-point. mbathy is computed from the meter bathymetry using the definiton of 
+gdept as the number of $t$-points which gdept $\leq$ bathy.
+
+Modifications of the model bathymetry are performed in the \textit{bat\_ctl} 
+routine (see \mdl{domzgr} module) after mbathy is computed. Isolated grid points 
+that do not communicate with another ocean point at the same level are eliminated.
+
+As for the representation of bathymetry, a 2D integer array, misfdep, is created. 
+misfdep defines the level of the first wet $t$-point. All the cells between $k=1$ and $misfdep(i,j)-1$ are masked. 
+By default, misfdep(:,:)=1 and no cells are masked.
+
+In case of ice shelf cavities, modifications of the model bathymetry and ice shelf draft into 
+the cavities are performed in the \textit{zgr\_isf} routine. The compatibility between ice shelf draft and bathymetry is checked. 
+All the locations where the isf cavity is thinnest than \np{rn\_isfhmin} meters are grounded ($i.e.$ masked). 
+If only one cell on the water column is opened at $t$-, $u$- or $v$-points, the bathymetry or the ice shelf draft is dug to fit this constrain.
+If the incompatibility is too strong (need to dig more than 1 cell), the cell is masked.\\ 
+
+From the \textit{mbathy} and \textit{misfdep} array, the mask fields are defined as follows:
+\begin{align*}
+tmask(i,j,k) &= \begin{cases}   \; 0&   \text{ if $k < misfdep(i,j) $ } \\
+                                \; 1&   \text{ if $misfdep(i,j) \leq k\leq mbathy(i,j)$  }    \\
+                                \; 0&   \text{ if $k > mbathy(i,j)$  }    \end{cases}     \\
+umask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i+1,j,k)	\\
+vmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i,j+1,k)	\\
+fmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i+1,j,k)	\\
+             &    \ \ \, * tmask(i,j,k) \ * \ tmask(i+1,j,k) \\
+wmask(i,j,k) &=         \; tmask(i,j,k) \ * \ tmask(i,j,k-1) \text{ with } wmask(i,j,1) = tmask(i,j,1) 
+\end{align*}
+
+Note that, without ice shelves cavities, masks at $t-$ and $w-$points are identical with 
+the numerical indexing used (\autoref{subsec:DOM_Num_Index}). Nevertheless, $wmask$ are required 
+with oceean cavities to deal with the top boundary (ice shelf/ocean interface) 
+exactly in the same way as for the bottom boundary. 
+
+The specification of closed lateral boundaries requires that at least the first and last 
+rows and columns of the \textit{mbathy} array are set to zero. In the particular 
+case of an east-west cyclical boundary condition, \textit{mbathy} has its last 
+column equal to the second one and its first column equal to the last but one 
+(and so too the mask arrays) (see \autoref{fig:LBC_jperio}).
+
+
+% ================================================================
+% Domain: Initial State (dtatsd & istate)
+% ================================================================
+\section{Initial state (\protect\mdl{istate} and \protect\mdl{dtatsd})}
+\label{sec:DTA_tsd}
+%-----------------------------------------namtsd-------------------------------------------
+
+\nlst{namtsd} 
+%------------------------------------------------------------------------------------------
+
+Options are defined in \ngn{namtsd}.
+By default, the ocean start from rest (the velocity field is set to zero) and the initialization of 
+temperature and salinity fields is controlled through the \np{ln\_tsd\_ini} namelist parameter.
+\begin{description}
+\item[\np{ln\_tsd\_init}\forcode{ = .true.}] use a T and S input files that can be given on the model grid itself or 
+on their native input data grid. In the latter case, the data will be interpolated on-the-fly both in the 
+horizontal and the vertical to the model grid (see \autoref{subsec:SBC_iof}). The information relative to the 
+input files are given in the \np{sn\_tem} and \np{sn\_sal} structures. 
+The computation is done in the \mdl{dtatsd} module.
+\item[\np{ln\_tsd\_init}\forcode{ = .false.}] use constant salinity value of 35.5 psu and an analytical profile of temperature
+(typical of the tropical ocean), see \rou{istate\_t\_s} subroutine called from \mdl{istate} module.
+\end{description}
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DYN.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_DYN.tex	(revision 10321)
@@ -0,0 +1,1261 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter ——— Ocean Dynamics (DYN)
+% ================================================================
+\chapter{Ocean Dynamics (DYN)}
+\label{chap:DYN}
+\minitoc
+
+%\vspace{2.cm}
+$\ $\newline      %force an empty line
+
+Using the representation described in \autoref{chap:DOM}, several semi-discrete 
+space forms of the dynamical equations are available depending on the vertical 
+coordinate used and on the conservation properties of the vorticity term. In all 
+the equations presented here, the masking has been omitted for simplicity. 
+One must be aware that all the quantities are masked fields and that each time an
+average or difference operator is used, the resulting field is multiplied by a mask.
+
+The prognostic ocean dynamics equation can be summarized as follows:
+\begin{equation*}
+\text{NXT} = \dbinom	{\text{VOR} + \text{KEG} + \text {ZAD} }
+						{\text{COR} + \text{ADV}                       }
+			+ \text{HPG} + \text{SPG} + \text{LDF} + \text{ZDF}
+\end{equation*}
+NXT stands for next, referring to the time-stepping. The first group of terms on 
+the rhs of this equation corresponds to the Coriolis and advection 
+terms that are decomposed into either a vorticity part (VOR), a kinetic energy part (KEG) 
+and a vertical advection part (ZAD) in the vector invariant formulation, or a Coriolis 
+and advection part (COR+ADV) in the flux formulation. The terms following these 
+are the pressure gradient contributions (HPG, Hydrostatic Pressure Gradient, 
+and SPG, Surface Pressure Gradient); and contributions from lateral diffusion 
+(LDF) and vertical diffusion (ZDF), which are added to the rhs in the \mdl{dynldf} 
+and \mdl{dynzdf} modules. The vertical diffusion term includes the surface and 
+bottom stresses. The external forcings and parameterisations require complex 
+inputs (surface wind stress calculation using bulk formulae, estimation of mixing 
+coefficients) that are carried out in modules SBC, LDF and ZDF and are described 
+in \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively. 
+
+In the present chapter we also describe the diagnostic equations used to compute 
+the horizontal divergence, curl of the velocities (\emph{divcur} module) and 
+the vertical velocity (\emph{wzvmod} module).
+
+The different options available to the user are managed by namelist variables. 
+For term \textit{ttt} in the momentum equations, the logical namelist variables are \textit{ln\_dynttt\_xxx}, 
+where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 
+If a CPP key is used for this term its name is \key{ttt}. The corresponding 
+code can be found in the \textit{dynttt\_xxx} module in the DYN directory, and it is 
+usually computed in the \textit{dyn\_ttt\_xxx} subroutine.
+
+The user has the option of extracting and outputting each tendency term from the
+3D momentum equations (\key{trddyn} defined), as described in 
+\autoref{chap:MISC}.  Furthermore, the tendency terms associated with the 2D 
+barotropic vorticity balance (when \key{trdvor} is defined) can be derived from the 
+3D terms.
+%%%
+\gmcomment{STEVEN: not quite sure I've got the sense of the last sentence. does 
+MISC correspond to "extracting tendency terms" or "vorticity balance"?}
+
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Sea Surface Height evolution & Diagnostics variables
+% ================================================================
+\section{Sea surface height and diagnostic variables ($\eta$, $\zeta$, $\chi$, $w$)}
+\label{sec:DYN_divcur_wzv}
+
+%--------------------------------------------------------------------------------------------------------------
+%           Horizontal divergence and relative vorticity
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Horizontal divergence and relative vorticity (\protect\mdl{divcur})}
+\label{subsec:DYN_divcur}
+
+The vorticity is defined at an $f$-point ($i.e.$ corner point) as follows:
+\begin{equation} \label{eq:divcur_cur}
+\zeta =\frac{1}{e_{1f}\,e_{2f} }\left( {\;\delta _{i+1/2} \left[ {e_{2v}\;v} \right]
+						        -\delta _{j+1/2} \left[ {e_{1u}\;u} \right]\;} \right)
+\end{equation} 
+
+The horizontal divergence is defined at a $T$-point. It is given by:
+\begin{equation} \label{eq:divcur_div}
+\chi =\frac{1}{e_{1t}\,e_{2t}\,e_{3t} }
+		\left( {\delta _i \left[ {e_{2u}\,e_{3u}\,u} \right]
+		       +\delta _j \left[ {e_{1v}\,e_{3v}\,v} \right]} \right)
+\end{equation} 
+
+Note that although the vorticity has the same discrete expression in $z$- 
+and $s$-coordinates, its physical meaning is not identical. $\zeta$ is a pseudo 
+vorticity along $s$-surfaces (only pseudo because $(u,v)$ are still defined along 
+geopotential surfaces, but are not necessarily defined at the same depth).
+
+The vorticity and divergence at the \textit{before} step are used in the computation 
+of the horizontal diffusion of momentum. Note that because they have been 
+calculated prior to the Asselin filtering of the \textit{before} velocities, the 
+\textit{before} vorticity and divergence arrays must be included in the restart file 
+to ensure perfect restartability. The vorticity and divergence at the \textit{now} 
+time step are used for the computation of the nonlinear advection and of the 
+vertical velocity respectively. 
+
+%--------------------------------------------------------------------------------------------------------------
+%           Sea Surface Height evolution
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Horizontal divergence and relative vorticity (\protect\mdl{sshwzv})}
+\label{subsec:DYN_sshwzv}
+
+The sea surface height is given by :
+\begin{equation} \label{eq:dynspg_ssh}
+\begin{aligned}
+\frac{\partial \eta }{\partial t}
+&\equiv    \frac{1}{e_{1t} e_{2t} }\sum\limits_k { \left\{  \delta _i \left[ {e_{2u}\,e_{3u}\;u} \right]
+                                                                                  +\delta _j \left[ {e_{1v}\,e_{3v}\;v} \right]  \right\} } 
+           -    \frac{\textit{emp}}{\rho _w }   \\
+&\equiv    \sum\limits_k {\chi \ e_{3t}}  -  \frac{\textit{emp}}{\rho _w }
+\end{aligned}
+\end{equation}
+where \textit{emp} is the surface freshwater budget (evaporation minus precipitation), 
+expressed in Kg/m$^2$/s (which is equal to mm/s), and $\rho _w$=1,035~Kg/m$^3$ 
+is the reference density of sea water (Boussinesq approximation). If river runoff is 
+expressed as a surface freshwater flux (see \autoref{chap:SBC}) then \textit{emp} can be 
+written as the evaporation minus precipitation, minus the river runoff. 
+The sea-surface height is evaluated using exactly the same time stepping scheme 
+as the tracer equation \autoref{eq:tra_nxt}: 
+a leapfrog scheme in combination with an Asselin time filter, $i.e.$ the velocity appearing 
+in \autoref{eq:dynspg_ssh} is centred in time (\textit{now} velocity). 
+This is of paramount importance. Replacing $T$ by the number $1$ in the tracer equation and summing
+over the water column must lead to the sea surface height equation otherwise tracer content
+will not be conserved \citep{Griffies_al_MWR01, Leclair_Madec_OM09}.
+
+The vertical velocity is computed by an upward integration of the horizontal 
+divergence starting at the bottom, taking into account the change of the thickness of the levels :
+\begin{equation} \label{eq:wzv}
+\left\{   \begin{aligned}
+&\left. w \right|_{k_b-1/2} \quad= 0    \qquad \text{where } k_b \text{ is the level just above the sea floor }  	\\
+&\left. w \right|_{k+1/2}     = \left. w \right|_{k-1/2}  +  \left. e_{3t} \right|_{k}\;  \left. \chi \right|_k  
+                                         - \frac{1} {2 \rdt} \left(  \left. e_{3t}^{t+1}\right|_{k} - \left. e_{3t}^{t-1}\right|_{k}\right)
+\end{aligned}   \right.
+\end{equation}
+
+In the case of a non-linear free surface (\key{vvl}), the top vertical velocity is $-\textit{emp}/\rho_w$, 
+as changes in the divergence of the barotropic transport are absorbed into the change 
+of the level thicknesses, re-orientated downward.
+\gmcomment{not sure of this...  to be modified with the change in emp setting}
+In the case of a linear free surface, the time derivative in \autoref{eq:wzv} disappears.
+The upper boundary condition applies at a fixed level $z=0$. The top vertical velocity 
+is thus equal to the divergence of the barotropic transport ($i.e.$ the first term in the
+right-hand-side of \autoref{eq:dynspg_ssh}).
+
+Note also that whereas the vertical velocity has the same discrete 
+expression in $z$- and $s$-coordinates, its physical meaning is not the same: 
+in the second case, $w$ is the velocity normal to the $s$-surfaces. 
+Note also that the $k$-axis is re-orientated downwards in the \textsc{fortran} code compared 
+to the indexing used in the semi-discrete equations such as \autoref{eq:wzv} 
+(see \autoref{subsec:DOM_Num_Index_vertical}). 
+
+
+% ================================================================
+% Coriolis and Advection terms: vector invariant form
+% ================================================================
+\section{Coriolis and advection: vector invariant form}
+\label{sec:DYN_adv_cor_vect}
+%-----------------------------------------nam_dynadv----------------------------------------------------
+
+\nlst{namdyn_adv} 
+%-------------------------------------------------------------------------------------------------------------
+
+The vector invariant form of the momentum equations is the one most 
+often used in applications of the \NEMO ocean model. The flux form option 
+(see next section) has been present since version $2$. Options are defined
+through the \ngn{namdyn\_adv} namelist variables
+Coriolis and momentum advection terms are evaluated using a leapfrog 
+scheme, $i.e.$ the velocity appearing in these expressions is centred in 
+time (\textit{now} velocity). 
+At the lateral boundaries either free slip, no slip or partial slip boundary 
+conditions are applied following \autoref{chap:LBC}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Vorticity term 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Vorticity term (\protect\mdl{dynvor})}
+\label{subsec:DYN_vor}
+%------------------------------------------nam_dynvor----------------------------------------------------
+
+\nlst{namdyn_vor} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namdyn\_vor} namelist variables.
+Four discretisations of the vorticity term (\np{ln\_dynvor\_xxx}\forcode{ = .true.}) are available: 
+conserving potential enstrophy of horizontally non-divergent flow (ENS scheme) ; 
+conserving horizontal kinetic energy (ENE scheme) ; conserving potential enstrophy for 
+the relative vorticity term and horizontal kinetic energy for the planetary vorticity 
+term (MIX scheme) ; or conserving both the potential enstrophy of horizontally non-divergent 
+flow and horizontal kinetic energy (EEN scheme) (see \autoref{subsec:C_vorEEN}). In the 
+case of ENS, ENE or MIX schemes the land sea mask may be slightly modified to ensure the 
+consistency of vorticity term with analytical equations (\np{ln\_dynvor\_con}\forcode{ = .true.}).
+The vorticity terms are all computed in dedicated routines that can be found in 
+the \mdl{dynvor} module.
+
+%-------------------------------------------------------------
+%                 enstrophy conserving scheme
+%-------------------------------------------------------------
+\subsubsection{Enstrophy conserving scheme (\protect\np{ln\_dynvor\_ens}\forcode{ = .true.})}
+\label{subsec:DYN_vor_ens}
+
+In the enstrophy conserving case (ENS scheme), the discrete formulation of the 
+vorticity term provides a global conservation of the enstrophy 
+($ [ (\zeta +f ) / e_{3f} ]^2 $ in $s$-coordinates) for a horizontally non-divergent 
+flow ($i.e.$ $\chi$=$0$), but does not conserve the total kinetic energy. It is given by:
+\begin{equation} \label{eq:dynvor_ens}
+\left\{ 
+\begin{aligned}
+{+\frac{1}{e_{1u} } } & {\overline {\left( { \frac{\zeta +f}{e_{3f} }} \right)} }^{\,i} 
+                                & {\overline{\overline {\left( {e_{1v}\,e_{3v}\;v} \right)}} }^{\,i, j+1/2}    \\
+{- \frac{1}{e_{2v} } } & {\overline {\left( {\frac{\zeta +f}{e_{3f} }} \right)} }^{\,j}  
+                                & {\overline{\overline {\left( {e_{2u}\,e_{3u}\;u} \right)}} }^{\,i+1/2, j}  
+\end{aligned} 
+ \right.
+\end{equation} 
+
+%-------------------------------------------------------------
+%                 energy conserving scheme
+%-------------------------------------------------------------
+\subsubsection{Energy conserving scheme (\protect\np{ln\_dynvor\_ene}\forcode{ = .true.})}
+\label{subsec:DYN_vor_ene}
+
+The kinetic energy conserving scheme (ENE scheme) conserves the global 
+kinetic energy but not the global enstrophy. It is given by:
+\begin{equation} \label{eq:dynvor_ene}
+\left\{   \begin{aligned}
+{+\frac{1}{e_{1u}}\; {\overline {\left( {\frac{\zeta +f}{e_{3f} }} \right)
+                            \;  \overline {\left( {e_{1v}\,e_{3v}\;v} \right)} ^{\,i+1/2}} }^{\,j} }    \\
+{- \frac{1}{e_{2v}}\; {\overline {\left( {\frac{\zeta +f}{e_{3f} }} \right)
+                            \;  \overline {\left( {e_{2u}\,e_{3u}\;u} \right)} ^{\,j+1/2}} }^{\,i} }
+\end{aligned}    \right.
+\end{equation} 
+
+%-------------------------------------------------------------
+%                 mix energy/enstrophy conserving scheme
+%-------------------------------------------------------------
+\subsubsection{Mixed energy/enstrophy conserving scheme (\protect\np{ln\_dynvor\_mix}\forcode{ = .true.}) }
+\label{subsec:DYN_vor_mix}
+
+For the mixed energy/enstrophy conserving scheme (MIX scheme), a mixture of the 
+two previous schemes is used. It consists of the ENS scheme (\autoref{eq:dynvor_ens}) 
+for the relative vorticity term, and of the ENE scheme (\autoref{eq:dynvor_ene}) applied 
+to the planetary vorticity term.
+\begin{equation} \label{eq:dynvor_mix}
+\left\{ {     \begin{aligned}
+ {+\frac{1}{e_{1u} }\; {\overline {\left( {\frac{\zeta }{e_{3f} }} \right)} }^{\,i} 
+ \; {\overline{\overline {\left( {e_{1v}\,e_{3v}\;v} \right)}} }^{\,i,j+1/2} -\frac{1}{e_{1u} }
+ \; {\overline {\left( {\frac{f}{e_{3f} }} \right) 
+ \;\overline {\left( {e_{1v}\,e_{3v}\;v} \right)} ^{\,i+1/2}} }^{\,j} } \\
+{-\frac{1}{e_{2v} }\; {\overline {\left( {\frac{\zeta }{e_{3f} }} \right)} }^j
+ \; {\overline{\overline {\left( {e_{2u}\,e_{3u}\;u} \right)}} }^{\,i+1/2,j} +\frac{1}{e_{2v} }
+ \; {\overline {\left( {\frac{f}{e_{3f} }} \right)
+ \;\overline {\left( {e_{2u}\,e_{3u}\;u} \right)} ^{\,j+1/2}} }^{\,i} } \hfill
+\end{aligned}     } \right.
+\end{equation} 
+
+%-------------------------------------------------------------
+%                 energy and enstrophy conserving scheme
+%-------------------------------------------------------------
+\subsubsection{Energy and enstrophy conserving scheme (\protect\np{ln\_dynvor\_een}\forcode{ = .true.}) }
+\label{subsec:DYN_vor_een}
+
+In both the ENS and ENE schemes, it is apparent that the combination of $i$ and $j$ 
+averages of the velocity allows for the presence of grid point oscillation structures 
+that will be invisible to the operator. These structures are \textit{computational modes} 
+that will be at least partly damped by the momentum diffusion operator ($i.e.$ the 
+subgrid-scale advection), but not by the resolved advection term. The ENS and ENE schemes
+therefore do not contribute to dump any grid point noise in the horizontal velocity field.
+Such noise would result in more noise in the vertical velocity field, an undesirable feature. 
+This is a well-known characteristic of $C$-grid discretization where $u$ and $v$ are located 
+at different grid points, a price worth paying to avoid a double averaging in the pressure 
+gradient term as in the $B$-grid. 
+\gmcomment{ To circumvent this, Adcroft (ADD REF HERE) 
+Nevertheless, this technique strongly distort the phase and group velocity of Rossby waves....}
+
+A very nice solution to the problem of double averaging was proposed by \citet{Arakawa_Hsu_MWR90}. 
+The idea is to get rid of the double averaging by considering triad combinations of vorticity. 
+It is noteworthy that this solution is conceptually quite similar to the one proposed by
+\citep{Griffies_al_JPO98} for the discretization of the iso-neutral diffusion operator (see \autoref{apdx:C}).
+
+The \citet{Arakawa_Hsu_MWR90} vorticity advection scheme for a single layer is modified 
+for spherical coordinates as described by \citet{Arakawa_Lamb_MWR81} to obtain the EEN scheme. 
+First consider the discrete expression of the potential vorticity, $q$, defined at an $f$-point: 
+\begin{equation} \label{eq:pot_vor}
+q  = \frac{\zeta +f} {e_{3f} }
+\end{equation}
+where the relative vorticity is defined by (\autoref{eq:divcur_cur}), the Coriolis parameter 
+is given by $f=2 \,\Omega \;\sin \varphi _f $ and the layer thickness at $f$-points is: 
+\begin{equation} \label{eq:een_e3f}
+e_{3f} = \overline{\overline {e_{3t} }} ^{\,i+1/2,j+1/2}
+\end{equation}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]    \begin{center}
+\includegraphics[width=0.70\textwidth]{Fig_DYN_een_triad}
+\caption{ \protect\label{fig:DYN_een_triad}  
+Triads used in the energy and enstrophy conserving scheme (een) for 
+$u$-component (upper panel) and $v$-component (lower panel).}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+A key point in \autoref{eq:een_e3f} is how the averaging in the \textbf{i}- and \textbf{j}- directions is made. 
+It uses the sum of masked t-point vertical scale factor divided either 
+by the sum of the four t-point masks (\np{nn\_een\_e3f}\forcode{ = 1}), 
+or  just by $4$ (\np{nn\_een\_e3f}\forcode{ = .true.}).
+The latter case preserves the continuity of $e_{3f}$ when one or more of the neighbouring $e_{3t}$ 
+tends to zero and extends by continuity the value of $e_{3f}$ into the land areas. 
+This case introduces a sub-grid-scale topography at f-points (with a systematic reduction of $e_{3f}$ 
+when a model level intercept the bathymetry) that tends to reinforce the topostrophy of the flow 
+($i.e.$ the tendency of the flow to follow the isobaths) \citep{Penduff_al_OS07}. 
+
+Next, the vorticity triads, $ {^i_j}\mathbb{Q}^{i_p}_{j_p}$ can be defined at a $T$-point as 
+the following triad combinations of the neighbouring potential vorticities defined at f-points 
+(\autoref{fig:DYN_een_triad}): 
+\begin{equation} \label{eq:Q_triads}
+_i^j \mathbb{Q}^{i_p}_{j_p}
+= \frac{1}{12} \ \left(   q^{i-i_p}_{j+j_p} + q^{i+j_p}_{j+i_p} + q^{i+i_p}_{j-j_p}  \right)
+\end{equation}
+where the indices $i_p$ and $k_p$ take the values: $i_p = -1/2$ or $1/2$ and $j_p = -1/2$ or $1/2$. 
+
+Finally, the vorticity terms are represented as: 
+\begin{equation} \label{eq:dynvor_een}
+\left\{ {
+\begin{aligned}
+ +q\,e_3 \, v 	&\equiv +\frac{1}{e_{1u} }   \sum_{\substack{i_p,\,k_p}} 
+                         {^{i+1/2-i_p}_j}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{1v}\,e_{3v} \;v  \right)^{i+1/2-i_p}_{j+j_p}   \\
+ - q\,e_3 \, u     &\equiv -\frac{1}{e_{2v} }    \sum_{\substack{i_p,\,k_p}} 
+                         {^i_{j+1/2-j_p}}  \mathbb{Q}^{i_p}_{j_p}  \left( e_{2u}\,e_{3u} \;u  \right)^{i+i_p}_{j+1/2-j_p}   \\
+\end{aligned} 
+} \right.
+\end{equation} 
+
+This EEN scheme in fact combines the conservation properties of the ENS and ENE schemes. 
+It conserves both total energy and potential enstrophy in the limit of horizontally 
+nondivergent flow ($i.e.$ $\chi$=$0$) (see \autoref{subsec:C_vorEEN}). 
+Applied to a realistic ocean configuration, it has been shown that it leads to a significant 
+reduction of the noise in the vertical velocity field \citep{Le_Sommer_al_OM09}. 
+Furthermore, used in combination with a partial steps representation of bottom topography,
+it improves the interaction between current and topography, leading to a larger
+topostrophy of the flow  \citep{Barnier_al_OD06, Penduff_al_OS07}. 
+
+%--------------------------------------------------------------------------------------------------------------
+%           Kinetic Energy Gradient term
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Kinetic energy gradient term (\protect\mdl{dynkeg})}
+\label{subsec:DYN_keg}
+
+As demonstrated in \autoref{apdx:C}, there is a single discrete formulation 
+of the kinetic energy gradient term that, together with the formulation chosen for 
+the vertical advection (see below), conserves the total kinetic energy:
+\begin{equation} \label{eq:dynkeg}
+\left\{ \begin{aligned}
+ -\frac{1}{2 \; e_{1u} }  & \ \delta _{i+1/2} \left[ {\overline {u^2}^{\,i} + \overline{v^2}^{\,j}} \right]   \\
+ -\frac{1}{2 \; e_{2v} }  & \ \delta _{j+1/2} \left[ {\overline {u^2}^{\,i} + \overline{v^2}^{\,j}} \right]    
+\end{aligned} \right.
+\end{equation} 
+
+%--------------------------------------------------------------------------------------------------------------
+%           Vertical advection term
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Vertical advection term (\protect\mdl{dynzad}) }
+\label{subsec:DYN_zad}
+
+The discrete formulation of the vertical advection, together with the formulation 
+chosen for the gradient of kinetic energy (KE) term, conserves the total kinetic 
+energy. Indeed, the change of KE due to the vertical advection is exactly 
+balanced by the change of KE due to the gradient of KE (see \autoref{apdx:C}).
+\begin{equation} \label{eq:dynzad}
+\left\{ 		\begin{aligned}
+-\frac{1} {e_{1u}\,e_{2u}\,e_{3u}} &\ \overline{\ \overline{ e_{1t}\,e_{2t}\;w } ^{\,i+1/2}  \;\delta _{k+1/2} \left[ u \right]\  }^{\,k}  \\
+-\frac{1} {e_{1v}\,e_{2v}\,e_{3v}}  &\ \overline{\ \overline{ e_{1t}\,e_{2t}\;w } ^{\,j+1/2}  \;\delta _{k+1/2} \left[ u \right]\  }^{\,k} 
+\end{aligned}         \right.
+\end{equation} 
+When \np{ln\_dynzad\_zts}\forcode{ = .true.}, a split-explicit time stepping with 5 sub-timesteps is used 
+on the vertical advection term.
+This option can be useful when the value of the timestep is limited by vertical advection \citep{Lemarie_OM2015}. 
+Note that in this case, a similar split-explicit time stepping should be used on 
+vertical advection of tracer to ensure a better stability, 
+an option which is only available with a TVD scheme (see \np{ln\_traadv\_tvd\_zts} in \autoref{subsec:TRA_adv_tvd}).
+
+
+% ================================================================
+% Coriolis and Advection : flux form
+% ================================================================
+\section{Coriolis and advection: flux form}
+\label{sec:DYN_adv_cor_flux}
+%------------------------------------------nam_dynadv----------------------------------------------------
+
+\nlst{namdyn_adv} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namdyn\_adv} namelist variables.
+In the flux form (as in the vector invariant form), the Coriolis and momentum 
+advection terms are evaluated using a leapfrog scheme, $i.e.$ the velocity 
+appearing in their expressions is centred in time (\textit{now} velocity). At the 
+lateral boundaries either free slip, no slip or partial slip boundary conditions 
+are applied following \autoref{chap:LBC}.
+
+
+%--------------------------------------------------------------------------------------------------------------
+%           Coriolis plus curvature metric terms
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Coriolis plus curvature metric terms (\protect\mdl{dynvor}) }
+\label{subsec:DYN_cor_flux}
+
+In flux form, the vorticity term reduces to a Coriolis term in which the Coriolis 
+parameter has been modified to account for the "metric" term. This altered 
+Coriolis parameter is thus discretised at $f$-points. It is given by: 
+\begin{multline} \label{eq:dyncor_metric}
+f+\frac{1}{e_1 e_2 }\left( {v\frac{\partial e_2 }{\partial i}  -  u\frac{\partial e_1 }{\partial j}} \right)  \\
+   \equiv   f + \frac{1}{e_{1f} e_{2f} } \left( { \ \overline v ^{i+1/2}\delta _{i+1/2} \left[ {e_{2u} } \right]  
+                                                                 -  \overline u ^{j+1/2}\delta _{j+1/2} \left[ {e_{1u} } \right]  }  \ \right)
+\end{multline} 
+
+Any of the (\autoref{eq:dynvor_ens}), (\autoref{eq:dynvor_ene}) and (\autoref{eq:dynvor_een}) 
+schemes can be used to compute the product of the Coriolis parameter and the 
+vorticity. However, the energy-conserving scheme (\autoref{eq:dynvor_een}) has 
+exclusively been used to date. This term is evaluated using a leapfrog scheme, 
+$i.e.$ the velocity is centred in time (\textit{now} velocity).
+
+%--------------------------------------------------------------------------------------------------------------
+%           Flux form Advection term
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Flux form advection term (\protect\mdl{dynadv}) }
+\label{subsec:DYN_adv_flux}
+
+The discrete expression of the advection term is given by :
+\begin{equation} \label{eq:dynadv}
+\left\{ 
+\begin{aligned}
+\frac{1}{e_{1u}\,e_{2u}\,e_{3u}} 
+\left(      \delta _{i+1/2} \left[ \overline{e_{2u}\,e_{3u}\;u }^{i       }  \ u_t      \right]    
+          + \delta _{j       } \left[ \overline{e_{1u}\,e_{3u}\;v }^{i+1/2}  \ u_f      \right] \right.  \ \;   \\
+\left.   + \delta _{k      } \left[ \overline{e_{1w}\,e_{2w}\;w}^{i+1/2}  \ u_{uw} \right] \right)   \\
+\\
+\frac{1}{e_{1v}\,e_{2v}\,e_{3v}} 
+\left(     \delta _{i       } \left[ \overline{e_{2u}\,e_{3u }\;u }^{j+1/2} \ v_f       \right] 
+         + \delta _{j+1/2} \left[ \overline{e_{1u}\,e_{3u }\;v }^{i       } \ v_t       \right] \right.  \ \, \, \\
+\left.  + \delta _{k      } \left[ \overline{e_{1w}\,e_{2w}\;w}^{j+1/2} \ v_{vw}  \right] \right) \\
+\end{aligned}
+\right.
+\end{equation}
+
+Two advection schemes are available: a $2^{nd}$ order centered finite 
+difference scheme, CEN2, or a $3^{rd}$ order upstream biased scheme, UBS. 
+The latter is described in \citet{Shchepetkin_McWilliams_OM05}. The schemes are 
+selected using the namelist logicals \np{ln\_dynadv\_cen2} and \np{ln\_dynadv\_ubs}. 
+In flux form, the schemes differ by the choice of a space and time interpolation to 
+define the value of $u$ and $v$ at the centre of each face of $u$- and $v$-cells, 
+$i.e.$ at the $T$-, $f$-, and $uw$-points for $u$ and at the $f$-, $T$- and 
+$vw$-points for $v$. 
+
+%-------------------------------------------------------------
+%                 2nd order centred scheme
+%-------------------------------------------------------------
+\subsubsection{CEN2: $2^{nd}$ order centred scheme (\protect\np{ln\_dynadv\_cen2}\forcode{ = .true.})}
+\label{subsec:DYN_adv_cen2}
+
+In the centered $2^{nd}$ order formulation, the velocity is evaluated as the 
+mean of the two neighbouring points :
+\begin{equation} \label{eq:dynadv_cen2}
+\left\{ 		\begin{aligned}
+ u_T^{cen2} &=\overline u^{i }       \quad &  u_F^{cen2} &=\overline u^{j+1/2}  \quad &  u_{uw}^{cen2} &=\overline u^{k+1/2}   \\
+ v_F^{cen2} &=\overline v ^{i+1/2} \quad & v_F^{cen2} &=\overline v^j		\quad &  v_{vw}^{cen2} &=\overline v ^{k+1/2}  \\
+\end{aligned}      \right.
+\end{equation} 
+
+The scheme is non diffusive (i.e. conserves the kinetic energy) but dispersive 
+($i.e.$ it may create false extrema). It is therefore notoriously noisy and must be 
+used in conjunction with an explicit diffusion operator to produce a sensible solution. 
+The associated time-stepping is performed using a leapfrog scheme in conjunction 
+with an Asselin time-filter, so $u$ and $v$ are the \emph{now} velocities.
+
+%-------------------------------------------------------------
+%                 UBS scheme
+%-------------------------------------------------------------
+\subsubsection{UBS: Upstream Biased Scheme (\protect\np{ln\_dynadv\_ubs}\forcode{ = .true.})}
+\label{subsec:DYN_adv_ubs}
+
+The UBS advection scheme is an upstream biased third order scheme based on 
+an upstream-biased parabolic interpolation. For example, the evaluation of 
+$u_T^{ubs} $ is done as follows:
+\begin{equation} \label{eq:dynadv_ubs}
+u_T^{ubs} =\overline u ^i-\;\frac{1}{6} 	\begin{cases}
+		u"_{i-1/2}& 	\text{if $\ \overline{e_{2u}\,e_{3u} \ u}^i  \geqslant 0$ } 	\\
+		u"_{i+1/2}& 	\text{if $\ \overline{e_{2u}\,e_{3u} \ u}^i  < 0$ }
+\end{cases}
+\end{equation}
+where $u"_{i+1/2} =\delta _{i+1/2} \left[ {\delta _i \left[ u \right]} \right]$. This results 
+in a dissipatively dominant ($i.e.$ hyper-diffusive) truncation error \citep{Shchepetkin_McWilliams_OM05}. 
+The overall performance of the advection scheme is similar to that reported in 
+\citet{Farrow1995}. It is a relatively good compromise between accuracy and 
+smoothness. It is not a \emph{positive} scheme, meaning that false extrema are 
+permitted. But the amplitudes of the false extrema are significantly reduced over 
+those in the centred second order method. As the scheme already includes 
+a diffusion component, it can be used without explicit lateral diffusion on momentum 
+($i.e.$ \np{ln\_dynldf\_lap}\forcode{ = }\np{ln\_dynldf\_bilap}\forcode{ = .false.}), and it is recommended to do so.
+
+The UBS scheme is not used in all directions. In the vertical, the centred $2^{nd}$ 
+order evaluation of the advection is preferred, $i.e.$ $u_{uw}^{ubs}$ and 
+$u_{vw}^{ubs}$ in \autoref{eq:dynadv_cen2} are used. UBS is diffusive and is 
+associated with vertical mixing of momentum. \gmcomment{ gm  pursue the 
+sentence:Since vertical mixing of momentum is a source term of the TKE equation...  }
+
+For stability reasons, the first term in (\autoref{eq:dynadv_ubs}), which corresponds 
+to a second order centred scheme, is evaluated using the \textit{now} velocity 
+(centred in time), while the second term, which is the diffusion part of the scheme, 
+is evaluated using the \textit{before} velocity (forward in time). This is discussed 
+by \citet{Webb_al_JAOT98} in the context of the Quick advection scheme.
+
+Note that the UBS and QUICK (Quadratic Upstream Interpolation for Convective Kinematics) 
+schemes only differ by one coefficient. Replacing $1/6$ by $1/8$ in 
+(\autoref{eq:dynadv_ubs}) leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
+This option is not available through a namelist parameter, since the $1/6$ coefficient 
+is hard coded. Nevertheless it is quite easy to make the substitution in the
+\mdl{dynadv\_ubs} module and obtain a QUICK scheme.
+
+Note also that in the current version of \mdl{dynadv\_ubs}, there is also the 
+possibility of using a $4^{th}$ order evaluation of the advective velocity as in 
+ROMS. This is an error and should be suppressed soon.
+%%%
+\gmcomment{action :  this have to be done}
+%%%
+
+% ================================================================
+%           Hydrostatic pressure gradient term
+% ================================================================
+\section{Hydrostatic pressure gradient (\protect\mdl{dynhpg})}
+\label{sec:DYN_hpg}
+%------------------------------------------nam_dynhpg---------------------------------------------------
+
+\nlst{namdyn_hpg} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namdyn\_hpg} namelist variables.
+The key distinction between the different algorithms used for the hydrostatic 
+pressure gradient is the vertical coordinate used, since HPG is a \emph{horizontal} 
+pressure gradient, $i.e.$ computed along geopotential surfaces. As a result, any 
+tilt of the surface of the computational levels will require a specific treatment to 
+compute the hydrostatic pressure gradient.
+
+The hydrostatic pressure gradient term is evaluated either using a leapfrog scheme, 
+$i.e.$ the density appearing in its expression is centred in time (\emph{now} $\rho$), or 
+a semi-implcit scheme. At the lateral boundaries either free slip, no slip or partial slip 
+boundary conditions are applied.
+
+%--------------------------------------------------------------------------------------------------------------
+%           z-coordinate with full step
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Full step $Z$-coordinate (\protect\np{ln\_dynhpg\_zco}\forcode{ = .true.})}
+\label{subsec:DYN_hpg_zco}
+
+The hydrostatic pressure can be obtained by integrating the hydrostatic equation 
+vertically from the surface. However, the pressure is large at great depth while its 
+horizontal gradient is several orders of magnitude smaller. This may lead to large 
+truncation errors in the pressure gradient terms. Thus, the two horizontal components 
+of the hydrostatic pressure gradient are computed directly as follows:
+
+for $k=km$ (surface layer, $jk=1$ in the code)
+\begin{equation} \label{eq:dynhpg_zco_surf}
+\left\{ \begin{aligned}
+					\left. \delta _{i+1/2} \left[  p^h 			 \right] \right|_{k=km} 
+&= \frac{1}{2} g \ 	\left. \delta _{i+1/2} \left[  e_{3w} \ \rho \right] \right|_{k=km}   \\
+     					\left. \delta _{j+1/2} \left[  p^h  			 \right] \right|_{k=km} 
+&= \frac{1}{2} g \ 	\left. \delta _{j+1/2} \left[  e_{3w} \ \rho \right] \right|_{k=km}   \\
+\end{aligned} \right.
+\end{equation} 
+
+for $1<k<km$ (interior layer)
+\begin{equation} \label{eq:dynhpg_zco}
+\left\{ \begin{aligned}
+					\left. \delta _{i+1/2} \left[  p^h 			 \right] \right|_{k} 
+&=					\left. \delta _{i+1/2} \left[  p^h 			 \right] \right|_{k-1} 
++    \frac{1}{2}\;g\;	\left. \delta _{i+1/2} \left[  e_{3w} \ \overline {\rho}^{k+1/2} \right] \right|_{k}   \\
+     					\left. \delta _{j+1/2} \left[  p^h  			 \right] \right|_{k} 
+&=     				\left. \delta _{j+1/2} \left[  p^h  			 \right] \right|_{k-1} 
++    \frac{1}{2}\;g\;	\left. \delta _{j+1/2} \left[  e_{3w} \ \overline {\rho}^{k+1/2} \right] \right|_{k}   \\
+\end{aligned} \right.
+\end{equation} 
+
+Note that the $1/2$ factor in (\autoref{eq:dynhpg_zco_surf}) is adequate because of 
+the definition of $e_{3w}$ as the vertical derivative of the scale factor at the surface 
+level ($z=0$). Note also that in case of variable volume level (\key{vvl} defined), the 
+surface pressure gradient is included in \autoref{eq:dynhpg_zco_surf} and \autoref{eq:dynhpg_zco} 
+through the space and time variations of the vertical scale factor $e_{3w}$.
+
+%--------------------------------------------------------------------------------------------------------------
+%           z-coordinate with partial step
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Partial step $Z$-coordinate (\protect\np{ln\_dynhpg\_zps}\forcode{ = .true.})}
+\label{subsec:DYN_hpg_zps}
+
+With partial bottom cells, tracers in horizontally adjacent cells generally live at 
+different depths. Before taking horizontal gradients between these tracer points, 
+a linear interpolation is used to approximate the deeper tracer as if it actually lived 
+at the depth of the shallower tracer point. 
+
+Apart from this modification, the horizontal hydrostatic pressure gradient evaluated 
+in the $z$-coordinate with partial step is exactly as in the pure $z$-coordinate case. 
+As explained in detail in section \autoref{sec:TRA_zpshde}, the nonlinearity of pressure 
+effects in the equation of state is such that it is better to interpolate temperature and 
+salinity vertically before computing the density. Horizontal gradients of temperature 
+and salinity are needed for the TRA modules, which is the reason why the horizontal 
+gradients of density at the deepest model level are computed in module \mdl{zpsdhe} 
+located in the TRA directory and described in \autoref{sec:TRA_zpshde}.
+
+%--------------------------------------------------------------------------------------------------------------
+%           s- and s-z-coordinates
+%--------------------------------------------------------------------------------------------------------------
+\subsection{$S$- and $Z$-$S$-coordinates}
+\label{subsec:DYN_hpg_sco}
+
+Pressure gradient formulations in an $s$-coordinate have been the subject of a vast 
+number of papers ($e.g.$, \citet{Song1998, Shchepetkin_McWilliams_OM05}). 
+A number of different pressure gradient options are coded but the ROMS-like, density Jacobian with 
+cubic polynomial method is currently disabled whilst known bugs are under investigation.
+
+$\bullet$ Traditional coding (see for example \citet{Madec_al_JPO96}: (\np{ln\_dynhpg\_sco}\forcode{ = .true.})
+\begin{equation} \label{eq:dynhpg_sco}
+\left\{ \begin{aligned}
+ - \frac{1}    					{\rho_o \, e_{1u}} \;	\delta _{i+1/2} \left[  p^h  \right] 
++ \frac{g\; \overline {\rho}^{i+1/2}}	{\rho_o \, e_{1u}} \;	\delta _{i+1/2} \left[  z_t   \right]    \\
+ - \frac{1}    					{\rho_o \, e_{2v}} \;	\delta _{j+1/2} \left[  p^h  \right]  
++ \frac{g\; \overline {\rho}^{j+1/2}}	{\rho_o \, e_{2v}} \;	\delta _{j+1/2} \left[  z_t   \right]    \\
+\end{aligned} \right.
+\end{equation} 
+
+Where the first term is the pressure gradient along coordinates, computed as in 
+\autoref{eq:dynhpg_zco_surf} - \autoref{eq:dynhpg_zco}, and $z_T$ is the depth of 
+the $T$-point evaluated from the sum of the vertical scale factors at the $w$-point 
+($e_{3w}$).
+ 
+$\bullet$ Traditional coding with adaptation for ice shelf cavities (\np{ln\_dynhpg\_isf}\forcode{ = .true.}).
+This scheme need the activation of ice shelf cavities (\np{ln\_isfcav}\forcode{ = .true.}).
+
+$\bullet$ Pressure Jacobian scheme (prj) (a research paper in preparation) (\np{ln\_dynhpg\_prj}\forcode{ = .true.})
+
+$\bullet$ Density Jacobian with cubic polynomial scheme (DJC) \citep{Shchepetkin_McWilliams_OM05} 
+(\np{ln\_dynhpg\_djc}\forcode{ = .true.}) (currently disabled; under development)
+
+Note that expression \autoref{eq:dynhpg_sco} is commonly used when the variable volume formulation is
+activated (\key{vvl}) because in that case, even with a flat bottom, the coordinate surfaces are not
+horizontal but follow the free surface \citep{Levier2007}. The pressure jacobian scheme
+(\np{ln\_dynhpg\_prj}\forcode{ = .true.}) is available as an improved option to \np{ln\_dynhpg\_sco}\forcode{ = .true.} when
+\key{vvl} is active.  The pressure Jacobian scheme uses a constrained cubic spline to reconstruct
+the density profile across the water column. This method maintains the monotonicity between the
+density nodes  The pressure can be calculated by analytical integration of the density profile and a
+pressure Jacobian method is used to solve the horizontal pressure gradient. This method can provide
+a more accurate calculation of the horizontal pressure gradient than the standard scheme.
+
+\subsection{Ice shelf cavity}
+\label{subsec:DYN_hpg_isf}
+Beneath an ice shelf, the total pressure gradient is the sum of the pressure gradient due to the ice shelf load and
+ the pressure gradient due to the ocean load. If cavity opened (\np{ln\_isfcav}\forcode{ = .true.}) these 2 terms can be
+ calculated by setting \np{ln\_dynhpg\_isf}\forcode{ = .true.}. No other scheme are working with the ice shelf.\\
+
+$\bullet$ The main hypothesis to compute the ice shelf load is that the ice shelf is in an isostatic equilibrium.
+ The top pressure is computed integrating from surface to the base of the ice shelf a reference density profile 
+(prescribed as density of a water at 34.4 PSU and -1.9\degC) and corresponds to the water replaced by the ice shelf. 
+This top pressure is constant over time. A detailed description of this method is described in \citet{Losch2008}.\\
+
+$\bullet$ The ocean load is computed using the expression \autoref{eq:dynhpg_sco} described in \autoref{subsec:DYN_hpg_sco}. 
+
+%--------------------------------------------------------------------------------------------------------------
+%           Time-scheme
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Time-scheme (\protect\np{ln\_dynhpg\_imp}\forcode{ = .true./.false.})}
+\label{subsec:DYN_hpg_imp}
+
+The default time differencing scheme used for the horizontal pressure gradient is 
+a leapfrog scheme and therefore the density used in all discrete expressions given 
+above is the  \textit{now} density, computed from the \textit{now} temperature and 
+salinity. In some specific cases (usually high resolution simulations over an ocean 
+domain which includes weakly stratified regions) the physical phenomenon that 
+controls the time-step is internal gravity waves (IGWs). A semi-implicit scheme for 
+doubling the stability limit associated with IGWs can be used \citep{Brown_Campana_MWR78, 
+Maltrud1998}. It involves the evaluation of the hydrostatic pressure gradient as an 
+average over the three time levels $t-\rdt$, $t$, and $t+\rdt$ ($i.e.$  
+\textit{before},  \textit{now} and  \textit{after} time-steps), rather than at the central 
+time level $t$ only, as in the standard leapfrog scheme. 
+
+$\bullet$ leapfrog scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}):
+
+\begin{equation} \label{eq:dynhpg_lf}
+\frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \;
+	-\frac{1}{\rho _o \,e_{1u} }\delta _{i+1/2} \left[ {p_h^t } \right]
+\end{equation}
+
+$\bullet$ semi-implicit scheme (\np{ln\_dynhpg\_imp}\forcode{ = .true.}):
+\begin{equation} \label{eq:dynhpg_imp}
+\frac{u^{t+\rdt}-u^{t-\rdt}}{2\rdt} = \;\cdots \;
+	-\frac{1}{4\,\rho _o \,e_{1u} } \delta_{i+1/2} \left[ p_h^{t+\rdt} +2\,p_h^t +p_h^{t-\rdt}  \right]
+\end{equation}
+
+The semi-implicit time scheme \autoref{eq:dynhpg_imp} is made possible without 
+significant additional computation since the density can be updated to time level 
+$t+\rdt$ before computing the horizontal hydrostatic pressure gradient. It can 
+be easily shown that the stability limit associated with the hydrostatic pressure 
+gradient doubles using \autoref{eq:dynhpg_imp} compared to that using the 
+standard leapfrog scheme \autoref{eq:dynhpg_lf}. Note that \autoref{eq:dynhpg_imp} 
+is equivalent to applying a time filter to the pressure gradient to eliminate high 
+frequency IGWs. Obviously, when using \autoref{eq:dynhpg_imp}, the doubling of 
+the time-step is achievable only if no other factors control the time-step, such as 
+the stability limits associated with advection or diffusion.
+
+In practice, the semi-implicit scheme is used when \np{ln\_dynhpg\_imp}\forcode{ = .true.}. 
+In this case, we choose to apply the time filter to temperature and salinity used in 
+the equation of state, instead of applying it to the hydrostatic pressure or to the 
+density, so that no additional storage array has to be defined. The density used to 
+compute the hydrostatic pressure gradient (whatever the formulation) is evaluated 
+as follows:
+\begin{equation} \label{eq:rho_flt}
+	\rho^t = \rho( \widetilde{T},\widetilde {S},z_t)
+ \quad	  \text{with}	\quad 
+	\widetilde{X} = 1 / 4 \left(  X^{t+\rdt} +2 \,X^t + X^{t-\rdt}  \right)
+\end{equation}
+
+Note that in the semi-implicit case, it is necessary to save the filtered density, an 
+extra three-dimensional field, in the restart file to restart the model with exact 
+reproducibility. This option is controlled by  \np{nn\_dynhpg\_rst}, a namelist parameter.
+
+% ================================================================
+% Surface Pressure Gradient
+% ================================================================
+\section{Surface pressure gradient (\protect\mdl{dynspg})}
+\label{sec:DYN_spg}
+%-----------------------------------------nam_dynspg----------------------------------------------------
+
+\nlst{namdyn_spg} 
+%------------------------------------------------------------------------------------------------------------
+
+$\ $\newline      %force an empty line
+
+Options are defined through the \ngn{namdyn\_spg} namelist variables.
+The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). 
+The main distinction is between the fixed volume case (linear free surface) and the variable volume case 
+(nonlinear free surface, \key{vvl} is defined). In the linear free surface case (\autoref{subsec:PE_free_surface}) 
+the vertical scale factors $e_{3}$ are fixed in time, while they are time-dependent in the nonlinear case 
+(\autoref{subsec:PE_free_surface}). 
+With both linear and nonlinear free surface, external gravity waves are allowed in the equations, 
+which imposes a very small time step when an explicit time stepping is used. 
+Two methods are proposed to allow a longer time step for the three-dimensional equations: 
+the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt}), 
+and the split-explicit free surface described below. 
+The extra term introduced in the filtered method is calculated implicitly, 
+so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
+
+
+The form of the surface pressure gradient term depends on how the user wants to handle 
+the fast external gravity waves that are a solution of the analytical equation (\autoref{sec:PE_hor_pg}). 
+Three formulations are available, all controlled by a CPP key (ln\_dynspg\_xxx):
+an explicit formulation which requires a small time step ;
+a filtered free surface formulation which allows a larger time step by adding a filtering 
+term into the momentum equation ; 
+and a split-explicit free surface formulation, described below, which also allows a larger time step.
+
+The extra term introduced in the filtered method is calculated 
+implicitly, so that a solver is used to compute it. As a consequence the update of the $next$ 
+velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
+
+
+%--------------------------------------------------------------------------------------------------------------
+% Explicit free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Explicit free surface (\protect\key{dynspg\_exp})}
+\label{subsec:DYN_spg_exp}
+
+In the explicit free surface formulation (\key{dynspg\_exp} defined), the model time step 
+is chosen to be small enough to resolve the external gravity waves (typically a few tens of seconds). 
+The surface pressure gradient, evaluated using a leap-frog scheme ($i.e.$ centered in time),
+is thus simply given by :
+\begin{equation} \label{eq:dynspg_exp}
+\left\{ \begin{aligned}
+ - \frac{1}{e_{1u}\,\rho_o} \;	\delta _{i+1/2} \left[  \,\rho \,\eta\,  \right] 	\\
+ - \frac{1}{e_{2v}\,\rho_o} \;	\delta _{j+1/2} \left[  \,\rho \,\eta\,  \right]  
+\end{aligned} \right.
+\end{equation} 
+
+Note that in the non-linear free surface case ($i.e.$ \key{vvl} defined), the surface pressure 
+gradient is already included in the momentum tendency  through the level thickness variation 
+allowed in the computation of the hydrostatic pressure gradient. Thus, nothing is done in the \mdl{dynspg\_exp} module.
+
+%--------------------------------------------------------------------------------------------------------------
+% Split-explict free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Split-explicit free surface (\protect\key{dynspg\_ts})}
+\label{subsec:DYN_spg_ts}
+%------------------------------------------namsplit-----------------------------------------------------------
+%
+%\nlst{namsplit}
+%-------------------------------------------------------------------------------------------------------------
+
+The split-explicit free surface formulation used in \NEMO (\key{dynspg\_ts} defined),
+also called the time-splitting formulation, follows the one 
+proposed by \citet{Shchepetkin_McWilliams_OM05}. The general idea is to solve the free surface 
+equation and the associated barotropic velocity equations with a smaller time 
+step than $\rdt$, the time step used for the three dimensional prognostic 
+variables (\autoref{fig:DYN_dynspg_ts}). 
+The size of the small time step, $\rdt_e$ (the external mode or barotropic time step)
+ is provided through the \np{nn\_baro} namelist parameter as: 
+$\rdt_e = \rdt / nn\_baro$. This parameter can be optionally defined automatically (\np{ln\_bt\_nn\_auto}\forcode{ = .true.}) 
+considering that the stability of the barotropic system is essentially controled by external waves propagation. 
+Maximum Courant number is in that case time independent, and easily computed online from the input bathymetry.
+Therefore, $\rdt_e$ is adjusted so that the Maximum allowed Courant number is smaller than \np{rn\_bt\_cmax}.
+
+%%%
+The barotropic mode solves the following equations:
+\begin{subequations} \label{eq:BT}
+  \begin{equation}     \label{eq:BT_dyn}
+\frac{\partial {\rm \overline{{\bf U}}_h} }{\partial t}=
+ -f\;{\rm {\bf k}}\times {\rm \overline{{\bf U}}_h} 
+-g\nabla _h \eta -\frac{c_b^{\textbf U}}{H+\eta} \rm {\overline{{\bf U}}_h} + \rm {\overline{\bf G}}
+  \end{equation}
+
+  \begin{equation} \label{eq:BT_ssh}
+\frac{\partial \eta }{\partial t}=-\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]+P-E
+  \end{equation}
+\end{subequations}
+where $\rm {\overline{\bf G}}$ is a forcing term held constant, containing coupling term between modes, surface atmospheric forcing as well as slowly varying barotropic terms not explicitly computed to gain efficiency. The third term on the right hand side of \autoref{eq:BT_dyn} represents the bottom stress (see section \autoref{sec:ZDF_bfr}), explicitly accounted for at each barotropic iteration. Temporal discretization of the system above follows a three-time step Generalized Forward Backward algorithm detailed in \citet{Shchepetkin_McWilliams_OM05}. AB3-AM4 coefficients used in \NEMO follow the second-order accurate, "multi-purpose" stability compromise as defined in \citet{Shchepetkin_McWilliams_Bk08} (see their figure 12, lower left). 
+
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+\begin{figure}[!t]    \begin{center}
+\includegraphics[width=0.7\textwidth]{Fig_DYN_dynspg_ts}
+\caption{  \protect\label{fig:DYN_dynspg_ts}
+Schematic of the split-explicit time stepping scheme for the external 
+and internal modes. Time increases to the right. In this particular exemple, 
+a boxcar averaging window over $nn\_baro$ barotropic time steps is used ($nn\_bt\_flt=1$) and $nn\_baro=5$.
+Internal mode time steps (which are also the model time steps) are denoted 
+by $t-\rdt$, $t$ and $t+\rdt$. Variables with $k$ superscript refer to instantaneous barotropic variables, 
+$< >$ and $<< >>$ operator refer to time filtered variables using respectively primary (red vertical bars) and secondary weights (blue vertical bars). 
+The former are used to obtain time filtered quantities at $t+\rdt$ while the latter are used to obtain time averaged 
+transports to advect tracers.
+a) Forward time integration: \protect\np{ln\_bt\_fw}\forcode{ = .true.},  \protect\np{ln\_bt\_av}\forcode{ = .true.}.
+b) Centred time integration: \protect\np{ln\_bt\_fw}\forcode{ = .false.}, \protect\np{ln\_bt\_av}\forcode{ = .true.}.
+c) Forward time integration with no time filtering (POM-like scheme): \protect\np{ln\_bt\_fw}\forcode{ = .true.}, \protect\np{ln\_bt\_av}\forcode{ = .false.}. }
+\end{center}    \end{figure}
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+
+In the default case (\np{ln\_bt\_fw}\forcode{ = .true.}), the external mode is integrated 
+between \textit{now} and  \textit{after} baroclinic time-steps (\autoref{fig:DYN_dynspg_ts}a). To avoid aliasing of fast barotropic motions into three dimensional equations, time filtering is eventually applied on barotropic 
+quantities (\np{ln\_bt\_av}\forcode{ = .true.}). In that case, the integration is extended slightly beyond  \textit{after} time step to provide time filtered quantities. 
+These are used for the subsequent initialization of the barotropic mode in the following baroclinic step. 
+Since external mode equations written at baroclinic time steps finally follow a forward time stepping scheme, 
+asselin filtering is not applied to barotropic quantities. \\
+Alternatively, one can choose to integrate barotropic equations starting 
+from \textit{before} time step (\np{ln\_bt\_fw}\forcode{ = .false.}). Although more computationaly expensive ( \np{nn\_baro} additional iterations are indeed necessary), the baroclinic to barotropic forcing term given at \textit{now} time step 
+become centred in the middle of the integration window. It can easily be shown that this property 
+removes part of splitting errors between modes, which increases the overall numerical robustness.
+%references to Patrick Marsaleix' work here. Also work done by SHOM group.
+
+%%%
+
+As far as tracer conservation is concerned, barotropic velocities used to advect tracers must also be updated 
+at \textit{now} time step. This implies to change the traditional order of computations in \NEMO: most of momentum  
+trends (including the barotropic mode calculation) updated first, tracers' after. This \textit{de facto} makes semi-implicit hydrostatic 
+pressure gradient (see section \autoref{subsec:DYN_hpg_imp}) and time splitting not compatible. 
+Advective barotropic velocities are obtained by using a secondary set of filtering weights, uniquely defined from the filter 
+coefficients used for the time averaging (\citet{Shchepetkin_McWilliams_OM05}). Consistency between the time averaged continuity equation and the time stepping of tracers is here the key to obtain exact conservation.
+
+%%%
+
+One can eventually choose to feedback instantaneous values by not using any time filter (\np{ln\_bt\_av}\forcode{ = .false.}). 
+In that case, external mode equations are continuous in time, ie they are not re-initialized when starting a new 
+sub-stepping sequence. This is the method used so far in the POM model, the stability being maintained by refreshing at (almost) 
+each barotropic time step advection and horizontal diffusion terms. Since the latter terms have not been added in \NEMO for 
+computational efficiency, removing time filtering is not recommended except for debugging purposes. 
+This may be used for instance to appreciate the damping effect of the standard formulation on external gravity waves in idealized or weakly non-linear cases. Although the damping is lower than for the filtered free surface, it is still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave.
+
+%>>>>>===============
+\gmcomment{               %%% copy from griffies Book 
+
+\textbf{title: Time stepping the barotropic system }
+
+Assume knowledge of the full velocity and tracer fields at baroclinic time $\tau$. Hence, 
+we can update the surface height and vertically integrated velocity with a leap-frog 
+scheme using the small barotropic time step $\rdt$. We have 
+
+\begin{equation} \label{eq:DYN_spg_ts_eta}
+\eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1})
+	= 2 \rdt \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right] 
+\end{equation}
+\begin{multline} \label{eq:DYN_spg_ts_u}
+\textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1})  \\
+	= 2\rdt \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) 
+	- H(\tau) \nabla p_s^{(b)}(\tau,t_{n}) +\textbf{M}(\tau) \right]
+\end{multline}
+\
+
+In these equations, araised (b) denotes values of surface height and vertically integrated velocity updated with the barotropic time steps. The $\tau$ time label on $\eta^{(b)}$ 
+and $U^{(b)}$ denotes the baroclinic time at which the vertically integrated forcing $\textbf{M}(\tau)$ (note that this forcing includes the surface freshwater forcing), the tracer fields, the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over a single cycle. This is also the time 
+that sets the barotropic time steps via 
+\begin{equation} \label{eq:DYN_spg_ts_t}
+t_n=\tau+n\rdt   
+\end{equation}
+with $n$ an integer. The density scaled surface pressure is evaluated via 
+\begin{equation} \label{eq:DYN_spg_ts_ps}
+p_s^{(b)}(\tau,t_{n}) = \begin{cases}
+	g \;\eta_s^{(b)}(\tau,t_{n}) \;\rho(\tau)_{k=1}) / \rho_o  &      \text{non-linear case} \\
+	g \;\eta_s^{(b)}(\tau,t_{n})  &      \text{linear case} 
+	\end{cases}
+\end{equation}
+To get started, we assume the following initial conditions 
+\begin{equation} \label{eq:DYN_spg_ts_eta}
+\begin{split}
+\eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)}
+\\
+\eta^{(b)}(\tau,t_{n=1}) &= \eta^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0} 
+\end{split}
+\end{equation}
+with 
+\begin{equation} \label{eq:DYN_spg_ts_etaF}
+ \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\rdt,t_{n})
+\end{equation}
+the time averaged surface height taken from the previous barotropic cycle. Likewise, 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+\textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)}	\\
+\\
+\textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \rdt \ \text{RHS}_{n=0}  	
+\end{equation}
+with 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+ \overline{\textbf{U}^{(b)}(\tau)} 
+ 	= \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\rdt,t_{n})
+\end{equation}
+the time averaged vertically integrated transport. Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 
+
+Upon reaching $t_{n=N} = \tau + 2\rdt \tau$ , the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at baroclinic time $\tau + \rdt \tau$ 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+\textbf{U}(\tau+\rdt) = \overline{\textbf{U}^{(b)}(\tau+\rdt)} 
+ 	= \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n})
+\end{equation}
+The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using the following form 
+
+\begin{equation} \label{eq:DYN_spg_ts_ssh}
+\eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\rdt \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]  
+\end{equation}
+
+ The use of this "big-leap-frog" scheme for the surface height ensures compatibility between the mass/volume budgets and the tracer budgets. More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
+ 
+In general, some form of time filter is needed to maintain integrity of the surface 
+height field due to the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. We 
+have tried various forms of such filtering, with the following method discussed in 
+\cite{Griffies_al_MWR01} chosen due to its stability and reasonably good maintenance of 
+tracer conservation properties (see ??) 
+
+\begin{equation} \label{eq:DYN_spg_ts_sshf}
+\eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
+\end{equation}
+Another approach tried was 
+
+\begin{equation} \label{eq:DYN_spg_ts_sshf2}
+\eta^{F}(\tau-\Delta) = \eta(\tau) 
+	+ (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\rdt)
+				    + \overline{\eta^{(b)}}(\tau-\rdt) -2 \;\eta(\tau) \right]
+\end{equation}
+
+which is useful since it isolates all the time filtering aspects into the term multiplied 
+by $\alpha$. This isolation allows for an easy check that tracer conservation is exact when 
+eliminating tracer and surface height time filtering (see ?? for more complete discussion). However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended. 
+
+}            %%end gm comment (copy of griffies book)
+
+%>>>>>===============
+
+
+%--------------------------------------------------------------------------------------------------------------
+% Filtered free surface formulation
+%--------------------------------------------------------------------------------------------------------------
+\subsection{Filtered free surface (\protect\key{dynspg\_flt})}
+\label{subsec:DYN_spg_fltp}
+
+The filtered formulation follows the \citet{Roullet_Madec_JGR00} implementation. 
+The extra term introduced in the equations (see \autoref{subsec:PE_free_surface}) is solved implicitly. 
+The elliptic solvers available in the code are documented in \autoref{chap:MISC}.
+
+%% gm %%======>>>>   given here the discrete eqs provided to the solver
+\gmcomment{               %%% copy from chap-model basics 
+\begin{equation} \label{eq:spg_flt}
+\frac{\partial {\rm {\bf U}}_h }{\partial t}= {\rm {\bf M}}
+- g \nabla \left( \tilde{\rho} \ \eta \right) 
+- g \ T_c \nabla \left( \widetilde{\rho} \ \partial_t \eta \right) 
+\end{equation}
+where $T_c$, is a parameter with dimensions of time which characterizes the force, 
+$\widetilde{\rho} = \rho / \rho_o$ is the dimensionless density, and $\rm {\bf M}$ 
+represents the collected contributions of the Coriolis, hydrostatic pressure gradient, 
+non-linear and viscous terms in \autoref{eq:PE_dyn}.
+}   %end gmcomment
+
+Note that in the linear free surface formulation (\key{vvl} not defined), the ocean depth 
+is time-independent and so is the matrix to be inverted. It is computed once and for all and applies to all ocean time steps. 
+
+% ================================================================
+% Lateral diffusion term
+% ================================================================
+\section{Lateral diffusion term and operators (\protect\mdl{dynldf})}
+\label{sec:DYN_ldf}
+%------------------------------------------nam_dynldf----------------------------------------------------
+
+\nlst{namdyn_ldf} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namdyn\_ldf} namelist variables.
+The options available for lateral diffusion are to use either laplacian 
+(rotated or not) or biharmonic operators. The coefficients may be constant 
+or spatially variable; the description of the coefficients is found in the chapter 
+on lateral physics (\autoref{chap:LDF}). The lateral diffusion of momentum is 
+evaluated using a forward scheme, $i.e.$ the velocity appearing in its expression 
+is the \textit{before} velocity in time, except for the pure vertical component 
+that appears when a tensor of rotation is used. This latter term is solved 
+implicitly together with the vertical diffusion term (see \autoref{chap:STP}) 
+
+At the lateral boundaries either free slip, no slip or partial slip boundary 
+conditions are applied according to the user's choice (see \autoref{chap:LBC}).
+
+\gmcomment{
+Hyperviscous operators are frequently used in the simulation of turbulent flows to control 
+the dissipation of unresolved small scale features. 
+Their primary role is to provide strong dissipation at the smallest scale supported by the grid 
+while minimizing the impact on the larger scale features. 
+Hyperviscous operators are thus designed to be more scale selective than the traditional, 
+physically motivated Laplace operator. 
+In finite difference methods, the biharmonic operator is frequently the method of choice to achieve 
+this scale selective dissipation since its damping time ($i.e.$ its spin down time) 
+scale like $\lambda^{-4}$ for disturbances of wavelength $\lambda$ 
+(so that short waves damped more rapidelly than long ones), 
+whereas the Laplace operator damping time scales only like $\lambda^{-2}$.
+}
+
+% ================================================================
+\subsection[Iso-level laplacian (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})]
+				{Iso-level laplacian operator (\protect\np{ln\_dynldf\_lap}\forcode{ = .true.})}
+\label{subsec:DYN_ldf_lap}
+
+For lateral iso-level diffusion, the discrete operator is: 
+\begin{equation} \label{eq:dynldf_lap}
+\left\{ \begin{aligned}
+ D_u^{l{\rm {\bf U}}} =\frac{1}{e_{1u} }\delta _{i+1/2} \left[ {A_T^{lm} 
+\;\chi } \right]-\frac{1}{e_{2u} {\kern 1pt}e_{3u} }\delta _j \left[ 
+{A_f^{lm} \;e_{3f} \zeta } \right] \\ 
+\\
+ D_v^{l{\rm {\bf U}}} =\frac{1}{e_{2v} }\delta _{j+1/2} \left[ {A_T^{lm} 
+\;\chi } \right]+\frac{1}{e_{1v} {\kern 1pt}e_{3v} }\delta _i \left[ 
+{A_f^{lm} \;e_{3f} \zeta } \right] \\ 
+\end{aligned} \right.
+\end{equation} 
+
+As explained in \autoref{subsec:PE_ldf}, this formulation (as the gradient of a divergence 
+and curl of the vorticity) preserves symmetry and ensures a complete 
+separation between the vorticity and divergence parts of the momentum diffusion. 
+
+%--------------------------------------------------------------------------------------------------------------
+%           Rotated laplacian operator
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Rotated laplacian (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})]
+				{Rotated laplacian operator (\protect\np{ln\_dynldf\_iso}\forcode{ = .true.})}
+\label{subsec:DYN_ldf_iso}
+
+A rotation of the lateral momentum diffusion operator is needed in several cases: 
+for iso-neutral diffusion in the $z$-coordinate (\np{ln\_dynldf\_iso}\forcode{ = .true.}) and for 
+either iso-neutral (\np{ln\_dynldf\_iso}\forcode{ = .true.}) or geopotential 
+(\np{ln\_dynldf\_hor}\forcode{ = .true.}) diffusion in the $s$-coordinate. In the partial step 
+case, coordinates are horizontal except at the deepest level and no 
+rotation is performed when \np{ln\_dynldf\_hor}\forcode{ = .true.}. The diffusion operator 
+is defined simply as the divergence of down gradient momentum fluxes on each 
+momentum component. It must be emphasized that this formulation ignores 
+constraints on the stress tensor such as symmetry. The resulting discrete 
+representation is:
+\begin{equation} \label{eq:dyn_ldf_iso}
+\begin{split}
+ D_u^{l\textbf{U}} &= \frac{1}{e_{1u} \, e_{2u} \, e_{3u} }	\\
+&  \left\{\quad  {\delta _{i+1/2} \left[ {A_T^{lm}  \left( 
+	 {\frac{e_{2t} \; e_{3t} }{e_{1t} } \,\delta _{i}[u]
+	-e_{2t} \; r_{1t} \,\overline{\overline {\delta _{k+1/2}[u]}}^{\,i,\,k}}
+ \right)} \right]} 	\right.
+\\ 
+& \qquad +\ \delta_j \left[ {A_f^{lm} \left( {\frac{e_{1f}\,e_{3f} }{e_{2f} 
+}\,\delta _{j+1/2} [u] - e_{1f}\, r_{2f} 
+\,\overline{\overline {\delta _{k+1/2} [u]}} ^{\,j+1/2,\,k}} 
+\right)} \right] 
+\\ 
+&\qquad +\ \delta_k \left[ {A_{uw}^{lm} \left( {-e_{2u} \, r_{1uw} \,\overline{\overline 
+{\delta_{i+1/2} [u]}}^{\,i+1/2,\,k+1/2} } 
+\right.} \right. 
+\\ 
+&  \ \qquad \qquad \qquad \quad\ 
+- e_{1u} \, r_{2uw} \,\overline{\overline {\delta_{j+1/2} [u]}} ^{\,j,\,k+1/2}
+\\ 
+& \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 
++\frac{e_{1u}\, e_{2u} }{e_{3uw} }\,\left( {r_{1uw}^2+r_{2uw}^2} 
+\right)\,\delta_{k+1/2} [u]} \right)} \right]\;\;\;} \right\} 
+\\
+\\
+ D_v^{l\textbf{V}} &= \frac{1}{e_{1v} \, e_{2v} \, e_{3v} }    \\
+&  \left\{\quad  {\delta _{i+1/2} \left[ {A_f^{lm}  \left( 
+	 {\frac{e_{2f} \; e_{3f} }{e_{1f} } \,\delta _{i+1/2}[v]
+	-e_{2f} \; r_{1f} \,\overline{\overline {\delta _{k+1/2}[v]}}^{\,i+1/2,\,k}}
+ \right)} \right]} 	\right.
+\\ 
+& \qquad +\ \delta_j \left[ {A_T^{lm} \left( {\frac{e_{1t}\,e_{3t} }{e_{2t} 
+}\,\delta _{j} [v] - e_{1t}\, r_{2t} 
+\,\overline{\overline {\delta _{k+1/2} [v]}} ^{\,j,\,k}} 
+\right)} \right] 
+\\ 
+& \qquad +\ \delta_k \left[ {A_{vw}^{lm} \left( {-e_{2v} \, r_{1vw} \,\overline{\overline 
+{\delta_{i+1/2} [v]}}^{\,i+1/2,\,k+1/2} }\right.} \right. 
+\\
+&  \ \qquad \qquad \qquad \quad\ 
+- e_{1v} \, r_{2vw} \,\overline{\overline {\delta_{j+1/2} [v]}} ^{\,j+1/2,\,k+1/2}
+\\ 
+& \left. {\left. { \ \qquad \qquad \qquad \ \ \ \left. {\ 
++\frac{e_{1v}\, e_{2v} }{e_{3vw} }\,\left( {r_{1vw}^2+r_{2vw}^2} 
+\right)\,\delta_{k+1/2} [v]} \right)} \right]\;\;\;} \right\} 
+ \end{split}
+\end{equation}
+where $r_1$ and $r_2$ are the slopes between the surface along which the 
+diffusion operator acts and the surface of computation ($z$- or $s$-surfaces). 
+The way these slopes are evaluated is given in the lateral physics chapter 
+(\autoref{chap:LDF}).
+
+%--------------------------------------------------------------------------------------------------------------
+%           Iso-level bilaplacian operator
+%--------------------------------------------------------------------------------------------------------------
+\subsection[Iso-level bilaplacian (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})]
+				{Iso-level bilaplacian operator (\protect\np{ln\_dynldf\_bilap}\forcode{ = .true.})}
+\label{subsec:DYN_ldf_bilap}
+
+The lateral fourth order operator formulation on momentum is obtained by 
+applying \autoref{eq:dynldf_lap} twice. It requires an additional assumption on 
+boundary conditions: the first derivative term normal to the coast depends on 
+the free or no-slip lateral boundary conditions chosen, while the third 
+derivative terms normal to the coast are set to zero (see \autoref{chap:LBC}).
+%%%
+\gmcomment{add a remark on the the change in the position of the coefficient}
+%%%
+
+% ================================================================
+%           Vertical diffusion term
+% ================================================================
+\section{Vertical diffusion term (\protect\mdl{dynzdf})}
+\label{sec:DYN_zdf}
+%----------------------------------------------namzdf------------------------------------------------------
+
+\nlst{namzdf} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namzdf} namelist variables.
+The large vertical diffusion coefficient found in the surface mixed layer together 
+with high vertical resolution implies that in the case of explicit time stepping there 
+would be too restrictive a constraint on the time step. Two time stepping schemes 
+can be used for the vertical diffusion term : $(a)$ a forward time differencing 
+scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using a time splitting technique 
+(\np{nn\_zdfexp} $>$ 1) or $(b)$ a backward (or implicit) time differencing scheme 
+(\np{ln\_zdfexp}\forcode{ = .false.}) (see \autoref{chap:STP}). Note that namelist variables 
+\np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both tracers and dynamics. 
+
+The formulation of the vertical subgrid scale physics is the same whatever 
+the vertical coordinate is. The vertical diffusion operators given by 
+\autoref{eq:PE_zdf} take the following semi-discrete space form:
+\begin{equation} \label{eq:dynzdf}
+\left\{   \begin{aligned}
+D_u^{vm} &\equiv \frac{1}{e_{3u}} \ \delta _k \left[ \frac{A_{uw}^{vm} }{e_{3uw} }
+                              \ \delta _{k+1/2} [\,u\,]         \right]     \\
+\\
+D_v^{vm} &\equiv \frac{1}{e_{3v}} \ \delta _k \left[ \frac{A_{vw}^{vm} }{e_{3vw} }
+                              \ \delta _{k+1/2} [\,v\,]         \right]
+\end{aligned}   \right.
+\end{equation} 
+where $A_{uw}^{vm} $ and $A_{vw}^{vm} $ are the vertical eddy viscosity and 
+diffusivity coefficients. The way these coefficients are evaluated 
+depends on the vertical physics used (see \autoref{chap:ZDF}).
+
+The surface boundary condition on momentum is the stress exerted by 
+the wind. At the surface, the momentum fluxes are prescribed as the boundary 
+condition on the vertical turbulent momentum fluxes,
+\begin{equation} \label{eq:dynzdf_sbc}
+\left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{z=1}
+	 = \frac{1}{\rho _o} \binom{\tau _u}{\tau _v }
+\end{equation}
+where $\left( \tau _u ,\tau _v \right)$ are the two components of the wind stress 
+vector in the (\textbf{i},\textbf{j}) coordinate system. The high mixing coefficients 
+in the surface mixed layer ensure that the surface wind stress is distributed in 
+the vertical over the mixed layer depth. If the vertical mixing coefficient 
+is small (when no mixed layer scheme is used) the surface stress enters only 
+the top model level, as a body force. The surface wind stress is calculated 
+in the surface module routines (SBC, see \autoref{chap:SBC})
+
+The turbulent flux of momentum at the bottom of the ocean is specified through 
+a bottom friction parameterisation (see \autoref{sec:ZDF_bfr})
+
+% ================================================================
+% External Forcing
+% ================================================================
+\section{External forcings}
+\label{sec:DYN_forcing}
+
+Besides the surface and bottom stresses (see the above section) which are 
+introduced as boundary conditions on the vertical mixing, three other forcings 
+may enter the dynamical equations by affecting the surface pressure gradient. 
+
+(1) When \np{ln\_apr\_dyn}\forcode{ = .true.} (see \autoref{sec:SBC_apr}), the atmospheric pressure is taken 
+into account when computing the surface pressure gradient.
+
+(2) When \np{ln\_tide\_pot}\forcode{ = .true.} and \np{ln\_tide}\forcode{ = .true.} (see \autoref{sec:SBC_tide}), 
+the tidal potential is taken into account when computing the surface pressure gradient.
+
+(3) When \np{nn\_ice\_embd}\forcode{ = 2} and LIM or CICE is used ($i.e.$ when the sea-ice is embedded in the ocean), 
+the snow-ice mass is taken into account when computing the surface pressure gradient.
+
+
+\gmcomment{ missing : the lateral boundary condition !!!   another external forcing
+ }
+
+% ================================================================
+% Time evolution term 
+% ================================================================
+\section{Time evolution term (\protect\mdl{dynnxt})}
+\label{sec:DYN_nxt}
+
+%----------------------------------------------namdom----------------------------------------------------
+
+\nlst{namdom} 
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namdom} namelist variables.
+The general framework for dynamics time stepping is a leap-frog scheme, 
+$i.e.$ a three level centred time scheme associated with an Asselin time filter 
+(cf. \autoref{chap:STP}). The scheme is applied to the velocity, except when using 
+the flux form of momentum advection (cf. \autoref{sec:DYN_adv_cor_flux}) in the variable 
+volume case (\key{vvl} defined), where it has to be applied to the thickness 
+weighted velocity (see \autoref{sec:A_momentum})  
+
+$\bullet$ vector invariant form or linear free surface (\np{ln\_dynhpg\_vec}\forcode{ = .true.} ; \key{vvl} not defined):
+\begin{equation} \label{eq:dynnxt_vec}
+\left\{   \begin{aligned}
+&u^{t+\rdt} = u_f^{t-\rdt} + 2\rdt  \ \text{RHS}_u^t  	\\
+&u_f^t \;\quad = u^t+\gamma \,\left[ {u_f^{t-\rdt} -2u^t+u^{t+\rdt}} \right]
+\end{aligned}   \right.
+\end{equation} 
+
+$\bullet$ flux form and nonlinear free surface (\np{ln\_dynhpg\_vec}\forcode{ = .false.} ; \key{vvl} defined):
+\begin{equation} \label{eq:dynnxt_flux}
+\left\{   \begin{aligned}
+&\left(e_{3u}\,u\right)^{t+\rdt} = \left(e_{3u}\,u\right)_f^{t-\rdt} + 2\rdt \; e_{3u} \;\text{RHS}_u^t  	\\
+&\left(e_{3u}\,u\right)_f^t \;\quad = \left(e_{3u}\,u\right)^t
+  +\gamma \,\left[ {\left(e_{3u}\,u\right)_f^{t-\rdt} -2\left(e_{3u}\,u\right)^t+\left(e_{3u}\,u\right)^{t+\rdt}} \right]
+\end{aligned}   \right.
+\end{equation} 
+where RHS is the right hand side of the momentum equation, the subscript $f$ 
+denotes filtered values and $\gamma$ is the Asselin coefficient. $\gamma$ is 
+initialized as \np{nn\_atfp} (namelist parameter). Its default value is \np{nn\_atfp}\forcode{ = 10.e-3}.
+In both cases, the modified Asselin filter is not applied since perfect conservation 
+is not an issue for the momentum equations.
+
+Note that with the filtered free surface, the update of the \textit{after} velocities 
+is done in the \mdl{dynsp\_flt} module, and only array swapping
+and Asselin filtering is done in \mdl{dynnxt}.
+
+% ================================================================
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LBC.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LBC.tex	(revision 10321)
@@ -0,0 +1,648 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter — Lateral Boundary Condition (LBC) 
+% ================================================================
+\chapter{Lateral Boundary Condition (LBC)}
+\label{chap:LBC}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+
+
+%gm% add here introduction to this chapter
+
+% ================================================================
+% Boundary Condition at the Coast
+% ================================================================
+\section{Boundary condition at the coast (\protect\np{rn\_shlat})}
+\label{sec:LBC_coast}
+%--------------------------------------------nam_lbc-------------------------------------------------------
+
+\nlst{namlbc} 
+%--------------------------------------------------------------------------------------------------------------
+
+%The lateral ocean boundary conditions contiguous to coastlines are Neumann conditions for heat and salt (no flux across boundaries) and Dirichlet conditions for momentum (ranging from free-slip to "strong" no-slip). They are handled automatically by the mask system (see \autoref{subsec:DOM_msk}). 
+
+%OPA allows land and topography grid points in the computational domain due to the presence of continents or islands, and includes the use of a full or partial step representation of bottom topography. The computation is performed over the whole domain, i.e. we do not try to restrict the computation to ocean-only points. This choice has two motivations. Firstly, working on ocean only grid points overloads the code and harms the code readability. Secondly, and more importantly, it drastically reduces the vector portion of the computation, leading to a dramatic increase of CPU time requirement on vector computers.  The current section describes how the masking affects the computation of the various terms of the equations with respect to the boundary condition at solid walls. The process of defining which areas are to be masked is described in \autoref{subsec:DOM_msk}.
+
+Options are defined through the \ngn{namlbc} namelist variables.
+The discrete representation of a domain with complex boundaries (coastlines and 
+bottom topography) leads to arrays that include large portions where a computation 
+is not required as the model variables remain at zero. Nevertheless, vectorial 
+supercomputers are far more efficient when computing over a whole array, and the 
+readability of a code is greatly improved when boundary conditions are applied in 
+an automatic way rather than by a specific computation before or after each 
+computational loop. An efficient way to work over the whole domain while specifying 
+the boundary conditions, is to use multiplication by mask arrays in the computation. 
+A mask array is a matrix whose elements are $1$ in the ocean domain and $0$ 
+elsewhere. A simple multiplication of a variable by its own mask ensures that it will 
+remain zero over land areas. Since most of the boundary conditions consist of a 
+zero flux across the solid boundaries, they can be simply applied by multiplying 
+variables by the correct mask arrays, $i.e.$ the mask array of the grid point where 
+the flux is evaluated. For example, the heat flux in the \textbf{i}-direction is evaluated 
+at $u$-points. Evaluating this quantity as,
+
+\begin{equation} \label{eq:lbc_aaaa}
+\frac{A^{lT} }{e_1 }\frac{\partial T}{\partial i}\equiv \frac{A_u^{lT} 
+}{e_{1u} } \; \delta _{i+1 / 2} \left[ T \right]\;\;mask_u 
+\end{equation}
+(where mask$_{u}$ is the mask array at a $u$-point) ensures that the heat flux is 
+zero inside land and at the boundaries, since mask$_{u}$ is zero at solid boundaries 
+which in this case are defined at $u$-points (normal velocity $u$ remains zero at 
+the coast) (\autoref{fig:LBC_uv}). 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]     \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_LBC_uv}
+\caption{  \protect\label{fig:LBC_uv}
+Lateral boundary (thick line) at T-level. The velocity normal to the boundary is set to zero.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+For momentum the situation is a bit more complex as two boundary conditions 
+must be provided along the coast (one each for the normal and tangential velocities). 
+The boundary of the ocean in the C-grid is defined by the velocity-faces. 
+For example, at a given $T$-level, the lateral boundary (a coastline or an intersection 
+with the bottom topography) is made of segments joining $f$-points, and normal 
+velocity points are located between two $f-$points (\autoref{fig:LBC_uv}). 
+The boundary condition on the normal velocity (no flux through solid boundaries) 
+can thus be easily implemented using the mask system. The boundary condition 
+on the tangential velocity requires a more specific treatment. This boundary 
+condition influences the relative vorticity and momentum diffusive trends, and is 
+required in order to compute the vorticity at the coast. Four different types of 
+lateral boundary condition are available, controlled by the value of the \np{rn\_shlat} 
+namelist parameter. (The value of the mask$_{f}$ array along the coastline is set 
+equal to this parameter.) These are:
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!p] \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_LBC_shlat}
+\caption{     \protect\label{fig:LBC_shlat} 
+lateral boundary condition (a) free-slip ($rn\_shlat=0$) ; (b) no-slip ($rn\_shlat=2$) 
+; (c) "partial" free-slip ($0<rn\_shlat<2$) and (d) "strong" no-slip ($2<rn\_shlat$). 
+Implied "ghost" velocity inside land area is display in grey. }
+\end{center}    \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+\begin{description}
+
+\item[free-slip boundary condition (\np{rn\_shlat}\forcode{ = 0}): ]  the tangential velocity at the 
+coastline is equal to the offshore velocity, $i.e.$ the normal derivative of the 
+tangential velocity is zero at the coast, so the vorticity: mask$_{f}$ array is set 
+to zero inside the land and just at the coast (\autoref{fig:LBC_shlat}-a).
+
+\item[no-slip boundary condition (\np{rn\_shlat}\forcode{ = 2}): ] the tangential velocity vanishes 
+at the coastline. Assuming that the tangential velocity decreases linearly from 
+the closest ocean velocity grid point to the coastline, the normal derivative is 
+evaluated as if the velocities at the closest land velocity gridpoint and the closest 
+ocean velocity gridpoint were of the same magnitude but in the opposite direction 
+(\autoref{fig:LBC_shlat}-b). Therefore, the vorticity along the coastlines is given by: 
+
+\begin{equation*}
+\zeta \equiv 2 \left(\delta_{i+1/2} \left[e_{2v} v \right] - \delta_{j+1/2} \left[e_{1u} u \right] \right) / \left(e_{1f} e_{2f} \right) \ ,
+\end{equation*}
+where $u$ and $v$ are masked fields. Setting the mask$_{f}$ array to $2$ along 
+the coastline provides a vorticity field computed with the no-slip boundary condition, 
+simply by multiplying it by the mask$_{f}$ :
+\begin{equation} \label{eq:lbc_bbbb}
+\zeta \equiv \frac{1}{e_{1f} {\kern 1pt}e_{2f} }\left( {\delta _{i+1/2} 
+\left[ {e_{2v} \,v} \right]-\delta _{j+1/2} \left[ {e_{1u} \,u} \right]} 
+\right)\;\mbox{mask}_f 
+\end{equation}
+
+\item["partial" free-slip boundary condition (0$<$\np{rn\_shlat}$<$2): ] the tangential 
+velocity at the coastline is smaller than the offshore velocity, $i.e.$ there is a lateral 
+friction but not strong enough to make the tangential velocity at the coast vanish 
+(\autoref{fig:LBC_shlat}-c). This can be selected by providing a value of mask$_{f}$ 
+strictly inbetween $0$ and $2$.
+
+\item["strong" no-slip boundary condition (2$<$\np{rn\_shlat}): ] the viscous boundary 
+layer is assumed to be smaller than half the grid size (\autoref{fig:LBC_shlat}-d). 
+The friction is thus larger than in the no-slip case.
+
+\end{description}
+
+Note that when the bottom topography is entirely represented by the $s$-coor-dinates 
+(pure $s$-coordinate), the lateral boundary condition on tangential velocity is of much 
+less importance as it is only applied next to the coast where the minimum water depth 
+can be quite shallow.
+
+
+% ================================================================
+% Boundary Condition around the Model Domain
+% ================================================================
+\section{Model domain boundary condition (\protect\np{jperio})}
+\label{sec:LBC_jperio}
+
+At the model domain boundaries several choices are offered: closed, cyclic east-west, 
+cyclic north-south, a north-fold, and combination closed-north fold 
+or bi-cyclic east-west and north-fold. The north-fold boundary condition is associated with the 3-pole ORCA mesh. 
+
+% -------------------------------------------------------------------------------------------------------------
+%        Closed, cyclic (\np{jperio}\forcode{ = 0..2}) 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Closed, cyclic (\protect\np{jperio}\forcode{= [0127]})}
+\label{subsec:LBC_jperio012}
+
+The choice of closed or cyclic model domain boundary condition is made 
+by setting \np{jperio} to 0, 1, 2 or 7 in namelist \ngn{namcfg}. Each time such a boundary 
+condition is needed, it is set by a call to routine \mdl{lbclnk}. The computation of 
+momentum and tracer trends proceeds from $i=2$ to $i=jpi-1$ and from $j=2$ to 
+$j=jpj-1$, $i.e.$ in the model interior. To choose a lateral model boundary condition 
+is to specify the first and last rows and columns of the model variables. 
+
+\begin{description}
+
+\item[For closed boundary (\np{jperio}\forcode{ = 0})], solid walls are imposed at all model 
+boundaries: first and last rows and columns are set to zero.
+
+\item[For cyclic east-west boundary (\np{jperio}\forcode{ = 1})], first and last rows are set 
+to zero (closed) whilst the first column is set to the value of the last-but-one column 
+and the last column to the value of the second one (\autoref{fig:LBC_jperio}-a). 
+Whatever flows out of the eastern (western) end of the basin enters the western 
+(eastern) end.
+
+\item[For cyclic north-south boundary (\np{jperio}\forcode{ = 2})], first and last columns are set 
+to zero (closed) whilst the first row is set to the value of the last-but-one row 
+and the last row to the value of the second one (\autoref{fig:LBC_jperio}-a). 
+Whatever flows out of the northern (southern) end of the basin enters the southern  
+(northern) end.
+
+\item[Bi-cyclic east-west and north-south boundary (\np{jperio}\forcode{ = 7})] combines cases 1 and 2.
+
+\end{description}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]     \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_LBC_jperio}
+\caption{    \protect\label{fig:LBC_jperio}
+setting of (a) east-west cyclic  (b) symmetric across the equator boundary conditions.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        North fold (\textit{jperio = 3 }to $6)$ 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{North-fold (\protect\np{jperio}\forcode{ = 3..6})}
+\label{subsec:LBC_north_fold}
+
+The north fold boundary condition has been introduced in order to handle the north 
+boundary of a three-polar ORCA grid. Such a grid has two poles in the northern hemisphere 
+(\autoref{fig:MISC_ORCA_msh}, and thus requires a specific treatment illustrated in \autoref{fig:North_Fold_T}. 
+Further information can be found in \mdl{lbcnfd} module which applies the north fold boundary condition.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]    \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_North_Fold_T}
+\caption{    \protect\label{fig:North_Fold_T} 
+North fold boundary with a $T$-point pivot and cyclic east-west boundary condition 
+($jperio=4$), as used in ORCA 2, 1/4, and 1/12. Pink shaded area corresponds 
+to the inner domain mask (see text). }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% ====================================================================
+% Exchange with neighbouring processors 
+% ====================================================================
+\section{Exchange with neighbouring processors (\protect\mdl{lbclnk}, \protect\mdl{lib\_mpp})}
+\label{sec:LBC_mpp}
+
+For massively parallel processing (mpp), a domain decomposition method is used. 
+The basic idea of the method is to split the large computation domain of a numerical 
+experiment into several smaller domains and solve the set of equations by addressing 
+independent local problems. Each processor has its own local memory and computes 
+the model equation over a subdomain of the whole model domain. The subdomain 
+boundary conditions are specified through communications between processors 
+which are organized by explicit statements (message passing method). 
+
+A big advantage is that the method does not need many modifications of the initial 
+FORTRAN code. From the modeller's point of view, each sub domain running on 
+a processor is identical to the "mono-domain" code. In addition, the programmer 
+manages the communications between subdomains, and the code is faster when 
+the number of processors is increased. The porting of OPA code on an iPSC860 
+was achieved during Guyon's PhD [Guyon et al. 1994, 1995] in collaboration with 
+CETIIS and ONERA. The implementation in the operational context and the studies 
+of performance on a T3D and T3E Cray computers have been made in collaboration 
+with IDRIS and CNRS. The present implementation is largely inspired by Guyon's 
+work  [Guyon 1995].
+
+The parallelization strategy is defined by the physical characteristics of the 
+ocean model. Second order finite difference schemes lead to local discrete 
+operators that depend at the very most on one neighbouring point. The only 
+non-local computations concern the vertical physics (implicit diffusion, 
+turbulent closure scheme, ...) (delocalization over the whole water column), 
+and the solving of the elliptic equation associated with the surface pressure 
+gradient computation (delocalization over the whole horizontal domain). 
+Therefore, a pencil strategy is used for the data sub-structuration 
+: the 3D initial domain is laid out on local processor 
+memories following a 2D horizontal topological splitting. Each sub-domain 
+computes its own surface and bottom boundary conditions and has a side 
+wall overlapping interface which defines the lateral boundary conditions for 
+computations in the inner sub-domain. The overlapping area consists of the 
+two rows at each edge of the sub-domain. After a computation, a communication 
+phase starts: each processor sends to its neighbouring processors the update 
+values of the points corresponding to the interior overlapping area to its 
+neighbouring sub-domain ($i.e.$ the innermost of the two overlapping rows). 
+The communication is done through the Message Passing Interface (MPI). 
+The data exchanges between processors are required at the very 
+place where lateral domain boundary conditions are set in the mono-domain 
+computation : the \rou{lbc\_lnk} routine (found in \mdl{lbclnk} module) 
+which manages such conditions is interfaced with routines found in \mdl{lib\_mpp} module 
+when running on an MPP computer ($i.e.$ when \key{mpp\_mpi} defined). 
+It has to be pointed out that when using the MPP version of the model, 
+the east-west cyclic boundary condition is done implicitly, 
+whilst the south-symmetric boundary condition option is not available.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]    \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_mpp}
+\caption{   \protect\label{fig:mpp} 
+Positioning of a sub-domain when massively parallel processing is used. }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+In the standard version of \NEMO, the splitting is regular and arithmetic.
+The i-axis is divided by \jp{jpni} and the j-axis by \jp{jpnj} for a number of processors 
+\jp{jpnij} most often equal to $jpni \times jpnj$ (parameters set in 
+ \ngn{nammpp} namelist). Each processor is independent and without message passing 
+ or synchronous process, programs run alone and access just its own local memory. 
+ For this reason, the main model dimensions are now the local dimensions of the subdomain (pencil) 
+ that are named \jp{jpi}, \jp{jpj}, \jp{jpk}. These dimensions include the internal 
+ domain and the overlapping rows. The number of rows to exchange (known as 
+ the halo) is usually set to one (\jp{jpreci}=1, in \mdl{par\_oce}). The whole domain 
+ dimensions are named \np{jpiglo}, \np{jpjglo} and \jp{jpk}. The relationship between 
+ the whole domain and a sub-domain is:
+\begin{eqnarray} 
+      jpi & = & ( jpiglo-2*jpreci + (jpni-1) ) / jpni + 2*jpreci  \nonumber \\
+      jpj & = & ( jpjglo-2*jprecj + (jpnj-1) ) / jpnj + 2*jprecj  \label{eq:lbc_jpi}
+\end{eqnarray}
+where \jp{jpni}, \jp{jpnj} are the number of processors following the i- and j-axis.
+
+One also defines variables nldi and nlei which correspond to the internal domain bounds, 
+and the variables nimpp and njmpp which are the position of the (1,1) grid-point in the global domain. 
+An element of $T_{l}$, a local array (subdomain) corresponds to an element of $T_{g}$, 
+a global array (whole domain) by the relationship: 
+\begin{equation} \label{eq:lbc_nimpp}
+T_{g} (i+nimpp-1,j+njmpp-1,k) = T_{l} (i,j,k),
+\end{equation}
+with  $1 \leq i \leq jpi$, $1  \leq j \leq jpj $ , and  $1  \leq k \leq jpk$.
+
+Processors are numbered from 0 to $jpnij-1$, the number is saved in the variable 
+nproc. In the standard version, a processor has no more than four neighbouring 
+processors named nono (for north), noea (east), noso (south) and nowe (west) 
+and two variables, nbondi and nbondj, indicate the relative position of the processor :
+\begin{itemize}
+\item 		nbondi = -1 	an east neighbour, no west processor,
+\item 		nbondi =  0	an east neighbour, a west neighbour,
+\item 		nbondi =  1 	no east processor, a west neighbour,
+\item 		nbondi =  2 	no splitting following the i-axis.
+\end{itemize}
+During the simulation, processors exchange data with their neighbours. 
+If there is effectively a neighbour, the processor receives variables from this 
+processor on its overlapping row, and sends the data issued from internal 
+domain corresponding to the overlapping row of the other processor.
+
+
+The \NEMO model computes equation terms with the help of mask arrays (0 on land 
+points and 1 on sea points). It is easily readable and very efficient in the context of 
+a computer with vectorial architecture. However, in the case of a scalar processor, 
+computations over the land regions become more expensive in terms of CPU time. 
+It is worse when we use a complex configuration with a realistic bathymetry like the 
+global ocean where more than 50 \% of points are land points. For this reason, a 
+pre-processing tool can be used to choose the mpp domain decomposition with a 
+maximum number of only land points processors, which can then be eliminated (\autoref{fig:mppini2})
+(For example, the mpp\_optimiz tools, available from the DRAKKAR web site). 
+This optimisation is dependent on the specific bathymetry employed. The user 
+then chooses optimal parameters \jp{jpni}, \jp{jpnj} and \jp{jpnij} with 
+$jpnij < jpni \times jpnj$, leading to the elimination of $jpni \times jpnj - jpnij$ 
+land processors. When those parameters are specified in \ngn{nammpp} namelist, 
+the algorithm in the \rou{inimpp2} routine sets each processor's parameters (nbound, 
+nono, noea,...) so that the land-only processors are not taken into account. 
+
+\gmcomment{Note that the inimpp2 routine is general so that the original inimpp 
+routine should be suppressed from the code.}
+
+When land processors are eliminated, the value corresponding to these locations in 
+the model output files is undefined. Note that this is a problem for the meshmask file 
+which requires to be defined over the whole domain. Therefore, user should not eliminate 
+land processors when creating a meshmask file ($i.e.$ when setting a non-zero value to \np{nn\_msh}).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]     \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_mppini2}
+\caption {    \protect\label{fig:mppini2}
+Example of Atlantic domain defined for the CLIPPER projet. Initial grid is 
+composed of 773 x 1236 horizontal points. 
+(a) the domain is split onto 9 \time 20 subdomains (jpni=9, jpnj=20). 
+52 subdomains are land areas. 
+(b) 52 subdomains are eliminated (white rectangles) and the resulting number 
+of processors really used during the computation is jpnij=128.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+% ====================================================================
+% Unstructured open boundaries BDY 
+% ====================================================================
+\section{Unstructured open boundary conditions (BDY)}
+\label{sec:LBC_bdy}
+
+%-----------------------------------------nambdy--------------------------------------------
+
+\nlst{nambdy} 
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_index--------------------------------------------
+%
+%\nlst{nambdy_index}
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_dta--------------------------------------------
+
+\nlst{nambdy_dta} 
+%-----------------------------------------------------------------------------------------------
+%-----------------------------------------nambdy_dta--------------------------------------------
+%
+%\nlst{nambdy_dta2} 
+%-----------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{nambdy} \ngn{nambdy\_index} 
+\ngn{nambdy\_dta} \ngn{nambdy\_dta2} namelist variables.
+The BDY module is the core implementation of open boundary
+conditions for regional configurations. It implements the Flow
+Relaxation Scheme algorithm for temperature, salinity, velocities and
+ice fields, and the Flather radiation condition for the depth-mean
+transports. The specification of the location of the open boundary is
+completely flexible and allows for example the open boundary to follow
+an isobath or other irregular contour. 
+
+The BDY module was modelled on the OBC module (see NEMO 3.4) and shares many
+features and a similar coding structure \citep{Chanut2005}.
+
+Boundary data files used with earlier versions of NEMO may need
+to be re-ordered to work with this version. See the
+section on the Input Boundary Data Files for details.
+
+%----------------------------------------------
+\subsection{Namelists}
+\label{subsec:BDY_namelist}
+
+The BDY module is activated by setting \np{ln\_bdy} to true.
+It is possible to define more than one boundary ``set'' and apply
+different boundary conditions to each set. The number of boundary
+sets is defined by \np{nb\_bdy}.  Each boundary set may be defined
+as a set of straight line segments in a namelist
+(\np{ln\_coords\_file}\forcode{ = .false.}) or read in from a file
+(\np{ln\_coords\_file}\forcode{ = .true.}). If the set is defined in a namelist,
+then the namelists nambdy\_index must be included separately, one for
+each set. If the set is defined by a file, then a
+``\ifile{coordinates.bdy}'' file must be provided. The coordinates.bdy file
+is analagous to the usual NEMO ``\ifile{coordinates}'' file. In the example
+above, there are two boundary sets, the first of which is defined via
+a file and the second is defined in a namelist. For more details of
+the definition of the boundary geometry see section
+\autoref{subsec:BDY_geometry}.
+
+For each boundary set a boundary
+condition has to be chosen for the barotropic solution (``u2d'':
+sea-surface height and barotropic velocities), for the baroclinic
+velocities (``u3d''), and for the active tracers\footnote{The BDY
+  module does not deal with passive tracers at this version}
+(``tra''). For each set of variables there is a choice of algorithm
+and a choice for the data, eg. for the active tracers the algorithm is
+set by \np{nn\_tra} and the choice of data is set by
+\np{nn\_tra\_dta}. 
+
+The choice of algorithm is currently as follows:
+
+\mbox{}
+
+\begin{itemize}
+\item[0.] No boundary condition applied. So the solution will ``see''
+  the land points around the edge of the edge of the domain.
+\item[1.] Flow Relaxation Scheme (FRS) available for all variables. 
+\item[2.] Flather radiation scheme for the barotropic variables. The
+  Flather scheme is not compatible with the filtered free surface
+  ({\it dynspg\_ts}). 
+\end{itemize}
+
+\mbox{}
+
+The main choice for the boundary data is
+to use initial conditions as boundary data (\np{nn\_tra\_dta}\forcode{ = 0}) or to
+use external data from a file (\np{nn\_tra\_dta}\forcode{ = 1}). For the
+barotropic solution there is also the option to use tidal
+harmonic forcing either by itself or in addition to other external
+data. 
+
+If external boundary data is required then the nambdy\_dta namelist
+must be defined. One nambdy\_dta namelist is required for each boundary
+set in the order in which the boundary sets are defined in nambdy. In
+the example given, two boundary sets have been defined and so there
+are two nambdy\_dta namelists. The boundary data is read in using the
+fldread module, so the nambdy\_dta namelist is in the format required
+for fldread. For each variable required, the filename, the frequency
+of the files and the frequency of the data in the files is given. Also
+whether or not time-interpolation is required and whether the data is
+climatological (time-cyclic) data. Note that on-the-fly spatial
+interpolation of boundary data is not available at this version. 
+
+In the example namelists given, two boundary sets are defined. The
+first set is defined via a file and applies FRS conditions to
+temperature and salinity and Flather conditions to the barotropic
+variables. External data is provided in daily files (from a
+large-scale model). Tidal harmonic forcing is also used. The second
+set is defined in a namelist. FRS conditions are applied on
+temperature and salinity and climatological data is read from external
+files. 
+
+%----------------------------------------------
+\subsection{Flow relaxation scheme}
+\label{subsec:BDY_FRS_scheme}
+
+The Flow Relaxation Scheme (FRS) \citep{Davies_QJRMS76,Engerdahl_Tel95},
+applies a simple relaxation of the model fields to
+externally-specified values over a zone next to the edge of the model
+domain. Given a model prognostic variable $\Phi$ 
+\begin{equation}  \label{eq:bdy_frs1}
+\Phi(d) = \alpha(d)\Phi_{e}(d) + (1-\alpha(d))\Phi_{m}(d)\;\;\;\;\; d=1,N
+\end{equation}
+where $\Phi_{m}$ is the model solution and $\Phi_{e}$ is the specified
+external field, $d$ gives the discrete distance from the model
+boundary  and $\alpha$ is a parameter that varies from $1$ at $d=1$ to
+a small value at $d=N$. It can be shown that this scheme is equivalent
+to adding a relaxation term to the prognostic equation for $\Phi$ of
+the form:
+\begin{equation}  \label{eq:bdy_frs2}
+-\frac{1}{\tau}\left(\Phi - \Phi_{e}\right)
+\end{equation}
+where the relaxation time scale $\tau$ is given by a function of
+$\alpha$ and the model time step $\Delta t$:
+\begin{equation}  \label{eq:bdy_frs3}
+\tau = \frac{1-\alpha}{\alpha}  \,\rdt
+\end{equation}
+Thus the model solution is completely prescribed by the external
+conditions at the edge of the model domain and is relaxed towards the
+external conditions over the rest of the FRS zone. The application of
+a relaxation zone helps to prevent spurious reflection of outgoing
+signals from the model boundary. 
+
+The function $\alpha$ is specified as a $tanh$ function:
+\begin{equation}  \label{eq:bdy_frs4}
+\alpha(d) = 1 - \tanh\left(\frac{d-1}{2}\right),       \quad d=1,N
+\end{equation}
+The width of the FRS zone is specified in the namelist as 
+\np{nn\_rimwidth}. This is typically set to a value between 8 and 10. 
+
+%----------------------------------------------
+\subsection{Flather radiation scheme}
+\label{subsec:BDY_flather_scheme}
+
+The \citet{Flather_JPO94} scheme is a radiation condition on the normal, depth-mean
+transport across the open boundary. It takes the form
+\begin{equation}  \label{eq:bdy_fla1}
+U = U_{e} + \frac{c}{h}\left(\eta - \eta_{e}\right),
+\end{equation}
+where $U$ is the depth-mean velocity normal to the boundary and $\eta$
+is the sea surface height, both from the model. The subscript $e$
+indicates the same fields from external sources. The speed of external
+gravity waves is given by $c = \sqrt{gh}$, and $h$ is the depth of the
+water column. The depth-mean normal velocity along the edge of the
+model domain is set equal to the
+external depth-mean normal velocity, plus a correction term that
+allows gravity waves generated internally to exit the model boundary.
+Note that the sea-surface height gradient in \autoref{eq:bdy_fla1}
+is a spatial gradient across the model boundary, so that $\eta_{e}$ is
+defined on the $T$ points with $nbr=1$ and $\eta$ is defined on the
+$T$ points with $nbr=2$. $U$ and $U_{e}$ are defined on the $U$ or
+$V$ points with $nbr=1$, $i.e.$ between the two $T$ grid points.
+
+%----------------------------------------------
+\subsection{Boundary geometry}
+\label{subsec:BDY_geometry}
+
+Each open boundary set is defined as a list of points. The information
+is stored in the arrays $nbi$, $nbj$, and $nbr$ in the $idx\_bdy$
+structure.  The $nbi$ and $nbj$ arrays
+define the local $(i,j)$ indices of each point in the boundary zone
+and the $nbr$ array defines the discrete distance from the boundary
+with $nbr=1$ meaning that the point is next to the edge of the
+model domain and $nbr>1$ showing that the point is increasingly
+further away from the edge of the model domain. A set of $nbi$, $nbj$,
+and $nbr$ arrays is defined for each of the $T$, $U$ and $V$
+grids. Figure \autoref{fig:LBC_bdy_geom} shows an example of an irregular
+boundary. 
+
+The boundary geometry for each set may be defined in a namelist
+nambdy\_index or by reading in a ``\ifile{coordinates.bdy}'' file. The
+nambdy\_index namelist defines a series of straight-line segments for
+north, east, south and west boundaries. For the northern boundary,
+\np{nbdysegn} gives the number of segments, \np{jpjnob} gives the $j$
+index for each segment and \np{jpindt} and \np{jpinft} give the start
+and end $i$ indices for each segment with similar for the other
+boundaries. These segments define a list of $T$ grid points along the
+outermost row of the boundary ($nbr\,=\, 1$). The code deduces the $U$ and
+$V$ points and also the points for $nbr\,>\, 1$ if
+$nn\_rimwidth\,>\,1$.
+
+The boundary geometry may also be defined from a
+``\ifile{coordinates.bdy}'' file. Figure \autoref{fig:LBC_nc_header}
+gives an example of the header information from such a file. The file
+should contain the index arrays for each of the $T$, $U$ and $V$
+grids. The arrays must be in order of increasing $nbr$. Note that the
+$nbi$, $nbj$ values in the file are global values and are converted to
+local values in the code. Typically this file will be used to generate
+external boundary data via interpolation and so will also contain the
+latitudes and longitudes of each point as shown. However, this is not
+necessary to run the model. 
+
+For some choices of irregular boundary the model domain may contain
+areas of ocean which are not part of the computational domain. For
+example if an open boundary is defined along an isobath, say at the
+shelf break, then the areas of ocean outside of this boundary will
+need to be masked out. This can be done by reading a mask file defined
+as \np{cn\_mask\_file} in the nam\_bdy namelist. Only one mask file is
+used even if multiple boundary sets are defined.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]      \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_LBC_bdy_geom}
+\caption {      \protect\label{fig:LBC_bdy_geom}
+Example of geometry of unstructured open boundary}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+%----------------------------------------------
+\subsection{Input boundary data files}
+\label{subsec:BDY_data}
+
+The data files contain the data arrays
+in the order in which the points are defined in the $nbi$ and $nbj$
+arrays. The data arrays are dimensioned on: a time dimension;
+$xb$ which is the index of the boundary data point in the horizontal;
+and $yb$ which is a degenerate dimension of 1 to enable the file to be
+read by the standard NEMO I/O routines. The 3D fields also have a
+depth dimension. 
+
+At Version 3.4 there are new restrictions on the order in which the
+boundary points are defined (and therefore restrictions on the order
+of the data in the file). In particular:
+
+\mbox{}
+
+\begin{enumerate}
+\item The data points must be in order of increasing $nbr$, ie. all
+  the $nbr=1$ points, then all the $nbr=2$ points etc.
+\item All the data for a particular boundary set must be in the same
+  order. (Prior to 3.4 it was possible to define barotropic data in a
+  different order to the data for tracers and baroclinic velocities). 
+\end{enumerate}
+
+\mbox{}
+
+These restrictions mean that data files used with previous versions of
+the model may not work with version 3.4. A fortran utility
+{\it bdy\_reorder} exists in the TOOLS directory which will re-order the
+data in old BDY data files. 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]     \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_LBC_nc_header}
+\caption {     \protect\label{fig:LBC_nc_header} 
+Example of the header for a \protect\ifile{coordinates.bdy} file}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+%----------------------------------------------
+\subsection{Volume correction}
+\label{subsec:BDY_vol_corr}
+
+There is an option to force the total volume in the regional model to be constant, 
+similar to the option in the OBC module. This is controlled  by the \np{nn\_volctl} 
+parameter in the namelist. A value of \np{nn\_volctl}\forcode{ = 0} indicates that this option is not used. 
+If  \np{nn\_volctl}\forcode{ = 1} then a correction is applied to the normal velocities 
+around the boundary at each timestep to ensure that the integrated volume flow 
+through the boundary is zero. If \np{nn\_volctl}\forcode{ = 2} then the calculation of 
+the volume change on the timestep includes the change due to the freshwater 
+flux across the surface and the correction velocity corrects for this as well.
+
+If more than one boundary set is used then volume correction is
+applied to all boundaries at once.
+
+\newpage
+%----------------------------------------------
+\subsection{Tidal harmonic forcing}
+\label{subsec:BDY_tides}
+
+%-----------------------------------------nambdy_tide--------------------------------------------
+
+\nlst{nambdy_tide} 
+%-----------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{nambdy\_tide} namelist variables.
+ To be written....
+
+
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LDF.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_LDF.tex	(revision 10321)
@@ -0,0 +1,502 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% Chapter ———  Lateral Ocean Physics (LDF)
+% ================================================================
+\chapter{Lateral Ocean Physics (LDF)}
+\label{chap:LDF}
+\minitoc
+
+
+\newpage
+$\ $\newline    % force a new ligne
+
+
+The lateral physics terms in the momentum and tracer equations have been 
+described in \autoref{eq:PE_zdf} and their discrete formulation in \autoref{sec:TRA_ldf} 
+and \autoref{sec:DYN_ldf}). In this section we further discuss each lateral physics option. 
+Choosing one lateral physics scheme means for the user defining, 
+(1) the type of operator used (laplacian or bilaplacian operators, or no lateral mixing term) ; 
+(2) the direction along which the lateral diffusive fluxes are evaluated (model level, geopotential or isopycnal surfaces) ; and 
+(3) the space and time variations of the eddy coefficients. 
+These three aspects of the lateral diffusion are set through namelist parameters 
+(see the \textit{\ngn{nam\_traldf}} and \textit{\ngn{nam\_dynldf}} below). 
+Note that this chapter describes the standard implementation of iso-neutral
+tracer mixing, and Griffies's implementation, which is used if
+\np{traldf\_grif}\forcode{ = .true.}, is described in Appdx\autoref{apdx:triad}
+
+%-----------------------------------nam_traldf - nam_dynldf--------------------------------------------
+
+\nlst{namtra_ldf} 
+
+\nlst{namdyn_ldf} 
+%--------------------------------------------------------------------------------------------------------------
+
+
+% ================================================================
+% Direction of lateral Mixing
+% ================================================================
+\section{Direction of lateral mixing (\protect\mdl{ldfslp})}
+\label{sec:LDF_slp}
+
+%%%
+\gmcomment{  we should emphasize here that the implementation is a rather old one. 
+Better work can be achieved by using \citet{Griffies_al_JPO98, Griffies_Bk04} iso-neutral scheme. }
+
+A direction for lateral mixing has to be defined when the desired operator does 
+not act along the model levels. This occurs when $(a)$ horizontal mixing is 
+required on tracer or momentum (\np{ln\_traldf\_hor} or \np{ln\_dynldf\_hor}) 
+in $s$- or mixed $s$-$z$- coordinates, and $(b)$ isoneutral mixing is required 
+whatever the vertical coordinate is. This direction of mixing is defined by its 
+slopes in the \textbf{i}- and \textbf{j}-directions at the face of the cell of the 
+quantity to be diffused. For a tracer, this leads to the following four slopes : 
+$r_{1u}$, $r_{1w}$, $r_{2v}$, $r_{2w}$ (see \autoref{eq:tra_ldf_iso}), while 
+for momentum the slopes are  $r_{1t}$, $r_{1uw}$, $r_{2f}$, $r_{2uw}$ for 
+$u$ and  $r_{1f}$, $r_{1vw}$, $r_{2t}$, $r_{2vw}$ for $v$. 
+
+%gm% add here afigure of the slope in i-direction
+
+\subsection{Slopes for tracer geopotential mixing in the $s$-coordinate}
+
+In $s$-coordinates, geopotential mixing ($i.e.$ horizontal mixing) $r_1$ and 
+$r_2$ are the slopes between the geopotential and computational surfaces. 
+Their discrete formulation is found by locally solving \autoref{eq:tra_ldf_iso} 
+when the diffusive fluxes in the three directions are set to zero and $T$ is 
+assumed to be horizontally uniform, $i.e.$ a linear function of $z_T$, the 
+depth of a $T$-point. 
+%gm { Steven : My version is obviously wrong since I'm left with an arbitrary constant which is the local vertical temperature gradient}
+
+\begin{equation} \label{eq:ldfslp_geo}
+\begin{aligned}
+ r_{1u} &= \frac{e_{3u}}{ \left( e_{1u}\;\overline{\overline{e_{3w}}}^{\,i+1/2,\,k} \right)}
+ 			  \;\delta_{i+1/2}[z_t] 
+ 		&\approx \frac{1}{e_{1u}}\; \delta_{i+1/2}[z_t] \ \ \
+\\
+ r_{2v} &= \frac{e_{3v}}{\left( e_{2v}\;\overline{\overline{e_{3w}}}^{\,j+1/2,\,k} \right)} 
+ 			  \;\delta_{j+1/2} [z_t] 
+		&\approx \frac{1}{e_{2v}}\; \delta_{j+1/2}[z_t] \ \ \
+\\
+ r_{1w} &= \frac{1}{e_{1w}}\;\overline{\overline{\delta_{i+1/2}[z_t]}}^{\,i,\,k+1/2}
+ 		&\approx \frac{1}{e_{1w}}\; \delta_{i+1/2}[z_{uw}] 
+ \\
+ r_{2w} &= \frac{1}{e_{2w}}\;\overline{\overline{\delta_{j+1/2}[z_t]}}^{\,j,\,k+1/2}
+		&\approx \frac{1}{e_{2w}}\; \delta_{j+1/2}[z_{vw}] 
+ \\
+\end{aligned}
+\end{equation}
+
+%gm%  caution I'm not sure the simplification was a good idea! 
+
+These slopes are computed once in \rou{ldfslp\_init} when \np{ln\_sco}\forcode{ = .true.}rue, 
+and either \np{ln\_traldf\_hor}\forcode{ = .true.}rue or \np{ln\_dynldf\_hor}\forcode{ = .true.}rue. 
+
+\subsection{Slopes for tracer iso-neutral mixing}
+\label{subsec:LDF_slp_iso}
+In iso-neutral mixing  $r_1$ and $r_2$ are the slopes between the iso-neutral 
+and computational surfaces. Their formulation does not depend on the vertical 
+coordinate used. Their discrete formulation is found using the fact that the 
+diffusive fluxes of locally referenced potential density ($i.e.$ $in situ$ density) 
+vanish. So, substituting $T$ by $\rho$ in \autoref{eq:tra_ldf_iso} and setting the 
+diffusive fluxes in the three directions to zero leads to the following definition for 
+the neutral slopes:
+
+\begin{equation} \label{eq:ldfslp_iso}
+\begin{split}
+ r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac{\delta_{i+1/2}[\rho]}
+ 								{\overline{\overline{\delta_{k+1/2}[\rho]}}^{\,i+1/2,\,k}}
+\\
+ r_{2v} &= \frac{e_{3v}}{e_{2v}}\; \frac{\delta_{j+1/2}\left[\rho \right]}
+ 								{\overline{\overline{\delta_{k+1/2}[\rho]}}^{\,j+1/2,\,k}}
+\\
+ r_{1w} &= \frac{e_{3w}}{e_{1w}}\; 
+ 			\frac{\overline{\overline{\delta_{i+1/2}[\rho]}}^{\,i,\,k+1/2}}
+				 {\delta_{k+1/2}[\rho]}
+\\
+ r_{2w} &= \frac{e_{3w}}{e_{2w}}\; 
+ 			\frac{\overline{\overline{\delta_{j+1/2}[\rho]}}^{\,j,\,k+1/2}}
+				 {\delta_{k+1/2}[\rho]}
+\\
+\end{split}
+\end{equation}
+
+%gm% rewrite this as the explanation is not very clear !!!
+%In practice, \autoref{eq:ldfslp_iso} is of little help in evaluating the neutral surface slopes. Indeed, for an unsimplified equation of state, the density has a strong dependancy on pressure (here approximated as the depth), therefore applying \autoref{eq:ldfslp_iso} using the $in situ$ density, $\rho$, computed at T-points leads to a flattening of slopes as the depth increases. This is due to the strong increase of the $in situ$ density with depth. 
+
+%By definition, neutral surfaces are tangent to the local $in situ$ density \citep{McDougall1987}, therefore in \autoref{eq:ldfslp_iso}, all the derivatives have to be evaluated at the same local pressure (which in decibars is approximated by the depth in meters).
+
+%In the $z$-coordinate, the derivative of the  \autoref{eq:ldfslp_iso} numerator is evaluated at the same depth \nocite{as what?} ($T$-level, which is the same as the $u$- and $v$-levels), so  the $in situ$ density can be used for its evaluation. 
+
+As the mixing is performed along neutral surfaces, the gradient of $\rho$ in 
+\autoref{eq:ldfslp_iso} has to be evaluated at the same local pressure (which, 
+in decibars, is approximated by the depth in meters in the model). Therefore 
+\autoref{eq:ldfslp_iso} cannot be used as such, but further transformation is 
+needed depending on the vertical coordinate used:
+
+\begin{description}
+
+\item[$z$-coordinate with full step : ] in \autoref{eq:ldfslp_iso} the densities 
+appearing in the $i$ and $j$ derivatives  are taken at the same depth, thus 
+the $in situ$ density can be used. This is not the case for the vertical 
+derivatives: $\delta_{k+1/2}[\rho]$ is replaced by $-\rho N^2/g$, where $N^2$ 
+is the local Brunt-Vais\"{a}l\"{a} frequency evaluated following 
+\citet{McDougall1987} (see \autoref{subsec:TRA_bn2}). 
+
+\item[$z$-coordinate with partial step : ] this case is identical to the full step 
+case except that at partial step level, the \emph{horizontal} density gradient 
+is evaluated as described in \autoref{sec:TRA_zpshde}.
+
+\item[$s$- or hybrid $s$-$z$- coordinate : ] in the current release of \NEMO, 
+iso-neutral mixing is only employed for $s$-coordinates if the
+Griffies scheme is used (\np{traldf\_grif}\forcode{ = .true.}; see Appdx \autoref{apdx:triad}). 
+In other words, iso-neutral mixing will only be accurately represented with a 
+linear equation of state (\np{nn\_eos}\forcode{ = 1..2}). In the case of a "true" equation 
+of state, the evaluation of $i$ and $j$ derivatives in \autoref{eq:ldfslp_iso} 
+will include a pressure dependent part, leading to the wrong evaluation of 
+the neutral slopes.
+
+%gm% 
+Note: The solution for $s$-coordinate passes trough the use of different 
+(and better) expression for the constraint on iso-neutral fluxes. Following 
+\citet{Griffies_Bk04}, instead of specifying directly that there is a zero neutral 
+diffusive flux of locally referenced potential density, we stay in the $T$-$S$ 
+plane and consider the balance between the neutral direction diffusive fluxes 
+of potential temperature and salinity:
+\begin{equation}
+\alpha \ \textbf{F}(T) = \beta \ \textbf{F}(S)
+\end{equation}
+%gm{  where vector F is ....}
+
+This constraint leads to the following definition for the slopes:
+
+\begin{equation} \label{eq:ldfslp_iso2}
+\begin{split}
+ r_{1u} &= \frac{e_{3u}}{e_{1u}}\; \frac
+ 		{\alpha_u \;\delta_{i+1/2}[T] - \beta_u \;\delta_{i+1/2}[S]}
+		{\alpha_u \;\overline{\overline{\delta_{k+1/2}[T]}}^{\,i+1/2,\,k}
+		 -\beta_u  \;\overline{\overline{\delta_{k+1/2}[S]}}^{\,i+1/2,\,k} }
+\\
+ r_{2v} &= \frac{e_{3v}}{e_{2v}}\; \frac
+ 		{\alpha_v \;\delta_{j+1/2}[T] - \beta_v \;\delta_{j+1/2}[S]}
+		{\alpha_v \;\overline{\overline{\delta_{k+1/2}[T]}}^{\,j+1/2,\,k}
+		 -\beta_v  \;\overline{\overline{\delta_{k+1/2}[S]}}^{\,j+1/2,\,k} }
+\\
+ r_{1w} &= \frac{e_{3w}}{e_{1w}}\; \frac
+		{\alpha_w \;\overline{\overline{\delta_{i+1/2}[T]}}^{\,i,\,k+1/2}
+		 -\beta_w  \;\overline{\overline{\delta_{i+1/2}[S]}}^{\,i,\,k+1/2} }
+ 		{\alpha_w \;\delta_{k+1/2}[T] - \beta_w \;\delta_{k+1/2}[S]}
+\\
+ r_{2w} &= \frac{e_{3w}}{e_{2w}}\; \frac
+		{\alpha_w \;\overline{\overline{\delta_{j+1/2}[T]}}^{\,j,\,k+1/2}
+		 -\beta_w  \;\overline{\overline{\delta_{j+1/2}[S]}}^{\,j,\,k+1/2} }
+ 		{\alpha_w \;\delta_{k+1/2}[T] - \beta_w \;\delta_{k+1/2}[S]}
+\\
+\end{split}
+\end{equation}
+where $\alpha$ and $\beta$, the thermal expansion and saline contraction 
+coefficients introduced in \autoref{subsec:TRA_bn2}, have to be evaluated at the three 
+velocity points. In order to save computation time, they should be approximated 
+by the mean of their values at $T$-points (for example in the case of $\alpha$:  
+$\alpha_u=\overline{\alpha_T}^{i+1/2}$,  $\alpha_v=\overline{\alpha_T}^{j+1/2}$ 
+and $\alpha_w=\overline{\alpha_T}^{k+1/2}$).
+
+Note that such a formulation could be also used in the $z$-coordinate and 
+$z$-coordinate with partial steps cases.
+
+\end{description}
+
+This implementation is a rather old one. It is similar to the one
+proposed by Cox [1987], except for the background horizontal
+diffusion. Indeed, the Cox implementation of isopycnal diffusion in
+GFDL-type models requires a minimum background horizontal diffusion
+for numerical stability reasons.  To overcome this problem, several
+techniques have been proposed in which the numerical schemes of the
+ocean model are modified \citep{Weaver_Eby_JPO97,
+  Griffies_al_JPO98}. Griffies's scheme is now available in \NEMO if
+\np{traldf\_grif\_iso} is set true; see Appdx \autoref{apdx:triad}. Here,
+another strategy is presented \citep{Lazar_PhD97}: a local
+filtering of the iso-neutral slopes (made on 9 grid-points) prevents
+the development of grid point noise generated by the iso-neutral
+diffusion operator (\autoref{fig:LDF_ZDF1}). This allows an
+iso-neutral diffusion scheme without additional background horizontal
+mixing. This technique can be viewed as a diffusion operator that acts
+along large-scale (2~$\Delta$x) \gmcomment{2deltax doesnt seem very
+  large scale} iso-neutral surfaces. The diapycnal diffusion required
+for numerical stability is thus minimized and its net effect on the
+flow is quite small when compared to the effect of an horizontal
+background mixing.
+
+Nevertheless, this iso-neutral operator does not ensure that variance cannot increase, 
+contrary to the \citet{Griffies_al_JPO98} operator which has that property. 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]      \begin{center}
+\includegraphics[width=0.70\textwidth]{Fig_LDF_ZDF1}
+\caption {    \protect\label{fig:LDF_ZDF1}
+averaging procedure for isopycnal slope computation.}
+\end{center}    \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+%There are three additional questions about the slope calculation. 
+%First the expression for the rotation tensor has been obtain assuming the "small slope" approximation, so a bound has to be imposed on slopes. 
+%Second, numerical stability issues also require a bound on slopes. 
+%Third, the question of boundary condition specified on slopes...
+
+%from griffies: chapter 13.1....
+
+
+
+% In addition and also for numerical stability reasons \citep{Cox1987, Griffies_Bk04}, 
+% the slopes are bounded by $1/100$ everywhere. This limit is decreasing linearly 
+% to zero fom $70$ meters depth and the surface (the fact that the eddies "feel" the 
+% surface motivates this flattening of isopycnals near the surface).
+
+For numerical stability reasons \citep{Cox1987, Griffies_Bk04}, the slopes must also 
+be bounded by $1/100$ everywhere. This constraint is applied in a piecewise linear 
+fashion, increasing from zero at the surface to $1/100$ at $70$ metres and thereafter 
+decreasing to zero at the bottom of the ocean. (the fact that the eddies "feel" the 
+surface motivates this flattening of isopycnals near the surface).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]     \begin{center}
+\includegraphics[width=0.70\textwidth]{Fig_eiv_slp}
+\caption {     \protect\label{fig:eiv_slp}
+Vertical profile of the slope used for lateral mixing in the mixed layer : 
+\textit{(a)} in the real ocean the slope is the iso-neutral slope in the ocean interior, 
+which has to be adjusted at the surface boundary (i.e. it must tend to zero at the 
+surface since there is no mixing across the air-sea interface: wall boundary 
+condition). Nevertheless, the profile between the surface zero value and the interior 
+iso-neutral one is unknown, and especially the value at the base of the mixed layer ; 
+\textit{(b)} profile of slope using a linear tapering of the slope near the surface and 
+imposing a maximum slope of 1/100 ; \textit{(c)} profile of slope actually used in 
+\NEMO: a linear decrease of the slope from zero at the surface to its ocean interior 
+value computed just below the mixed layer. Note the huge change in the slope at the 
+base of the mixed layer between  \textit{(b)}  and \textit{(c)}.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+\colorbox{yellow}{add here a discussion about the flattening of the slopes, vs  tapering the coefficient.}
+
+\subsection{Slopes for momentum iso-neutral mixing}
+
+The iso-neutral diffusion operator on momentum is the same as the one used on 
+tracers but applied to each component of the velocity separately (see 
+\autoref{eq:dyn_ldf_iso} in section~\autoref{subsec:DYN_ldf_iso}). The slopes between the 
+surface along which the diffusion operator acts and the surface of computation 
+($z$- or $s$-surfaces) are defined at $T$-, $f$-, and \textit{uw}- points for the 
+$u$-component, and $T$-, $f$- and \textit{vw}- points for the $v$-component. 
+They are computed from the slopes used for tracer diffusion, $i.e.$ 
+\autoref{eq:ldfslp_geo} and \autoref{eq:ldfslp_iso} :
+
+\begin{equation} \label{eq:ldfslp_dyn}
+\begin{aligned}
+&r_{1t}\ \ = \overline{r_{1u}}^{\,i}       &&&    r_{1f}\ \ &= \overline{r_{1u}}^{\,i+1/2} \\
+&r_{2f} \ \ = \overline{r_{2v}}^{\,j+1/2} &&& 	r_{2t}\ &= \overline{r_{2v}}^{\,j} \\
+&r_{1uw}  = \overline{r_{1w}}^{\,i+1/2} &&\ \ \text{and} \ \ &   r_{1vw}&= \overline{r_{1w}}^{\,j+1/2} \\
+&r_{2uw}= \overline{r_{2w}}^{\,j+1/2} &&&         r_{2vw}&= \overline{r_{2w}}^{\,j+1/2}\\
+\end{aligned}
+\end{equation}
+
+The major issue remaining is in the specification of the boundary conditions. 
+The same boundary conditions are chosen as those used for lateral 
+diffusion along model level surfaces, i.e. using the shear computed along 
+the model levels and with no additional friction at the ocean bottom (see 
+\autoref{sec:LBC_coast}).
+
+
+% ================================================================
+% Lateral Mixing Operator
+% ================================================================
+\section{Lateral mixing operators (\protect\mdl{traldf}, \protect\mdl{traldf}) }
+\label{sec:LDF_op}
+
+
+   
+% ================================================================
+% Lateral Mixing Coefficients
+% ================================================================
+\section{Lateral mixing coefficient (\protect\mdl{ldftra}, \protect\mdl{ldfdyn}) }
+\label{sec:LDF_coef}
+
+Introducing a space variation in the lateral eddy mixing coefficients changes 
+the model core memory requirement, adding up to four extra three-dimensional 
+arrays for the geopotential or isopycnal second order operator applied to 
+momentum. Six CPP keys control the space variation of eddy coefficients: 
+three for momentum and three for tracer. The three choices allow: 
+a space variation in the three space directions (\key{traldf\_c3d},  \key{dynldf\_c3d}), 
+in the horizontal plane (\key{traldf\_c2d},  \key{dynldf\_c2d}), 
+or in the vertical only (\key{traldf\_c1d},  \key{dynldf\_c1d}). 
+The default option is a constant value over the whole ocean on both momentum and tracers. 
+   
+The number of additional arrays that have to be defined and the gridpoint 
+position at which they are defined depend on both the space variation chosen 
+and the type of operator used. The resulting eddy viscosity and diffusivity 
+coefficients can be a function of more than one variable. Changes in the 
+computer code when switching from one option to another have been 
+minimized by introducing the eddy coefficients as statement functions
+(include file \hf{ldftra\_substitute} and \hf{ldfdyn\_substitute}). The functions 
+are replaced by their actual meaning during the preprocessing step (CPP). 
+The specification of the space variation of the coefficient is made in 
+\mdl{ldftra} and \mdl{ldfdyn}, or more precisely in include files 
+\hf{traldf\_cNd} and \hf{dynldf\_cNd}, with N=1, 2 or 3. 
+The user can modify these include files as he/she wishes. The way the 
+mixing coefficient are set in the reference version can be briefly described 
+as follows:
+
+\subsubsection{Constant mixing coefficients (default option)}
+When none of the \key{dynldf\_...} and \key{traldf\_...} keys are 
+defined, a constant value is used over the whole ocean for momentum and 
+tracers, which is specified through the \np{rn\_ahm0} and \np{rn\_aht0} namelist 
+parameters.
+
+\subsubsection{Vertically varying mixing coefficients (\protect\key{traldf\_c1d} and \key{dynldf\_c1d})} 
+The 1D option is only available when using the $z$-coordinate with full step. 
+Indeed in all the other types of vertical coordinate, the depth is a 3D function 
+of (\textbf{i},\textbf{j},\textbf{k}) and therefore, introducing depth-dependent 
+mixing coefficients will require 3D arrays. In the 1D option, a hyperbolic variation 
+of the lateral mixing coefficient is introduced in which the surface value is 
+\np{rn\_aht0} (\np{rn\_ahm0}), the bottom value is 1/4 of the surface value, 
+and the transition takes place around z=300~m with a width of 300~m 
+($i.e.$ both the depth and the width of the inflection point are set to 300~m). 
+This profile is hard coded in file \hf{traldf\_c1d}, but can be easily modified by users.
+
+\subsubsection{Horizontally varying mixing coefficients (\protect\key{traldf\_c2d} and \protect\key{dynldf\_c2d})}
+By default the horizontal variation of the eddy coefficient depends on the local mesh 
+size and the type of operator used:
+\begin{equation} \label{eq:title}
+  A_l = \left\{     
+   \begin{aligned}
+         & \frac{\max(e_1,e_2)}{e_{max}} A_o^l  			& \text{for laplacian operator } \\
+         & \frac{\max(e_1,e_2)^{3}}{e_{max}^{3}} A_o^l          & \text{for bilaplacian operator } 
+   \end{aligned}    \right.
+\end{equation}
+where $e_{max}$ is the maximum of $e_1$ and $e_2$ taken over the whole masked 
+ocean domain, and $A_o^l$ is the \np{rn\_ahm0} (momentum) or \np{rn\_aht0} (tracer) 
+namelist parameter. This variation is intended to reflect the lesser need for subgrid 
+scale eddy mixing where the grid size is smaller in the domain. It was introduced in 
+the context of the DYNAMO modelling project \citep{Willebrand_al_PO01}. 
+Note that such a grid scale dependance of mixing coefficients significantly increase 
+the range of stability of model configurations presenting large changes in grid pacing 
+such as global ocean models. Indeed, in such a case, a constant mixing coefficient 
+can lead to a blow up of the model due to large coefficient compare to the smallest 
+grid size (see \autoref{sec:STP_forward_imp}), especially when using a bilaplacian operator.
+
+Other formulations can be introduced by the user for a given configuration. 
+For example, in the ORCA2 global ocean model (see Configurations), the laplacian 
+viscosity operator uses \np{rn\_ahm0}~= 4.10$^4$ m$^2$/s poleward of 20$^{\circ}$ 
+north and south and decreases linearly to \np{rn\_aht0}~= 2.10$^3$ m$^2$/s 
+at the equator \citep{Madec_al_JPO96, Delecluse_Madec_Bk00}. This modification 
+can be found in routine \rou{ldf\_dyn\_c2d\_orca} defined in \mdl{ldfdyn\_c2d}. 
+Similar modified horizontal variations can be found with the Antarctic or Arctic 
+sub-domain options of ORCA2 and ORCA05 (see \&namcfg namelist).
+
+\subsubsection{Space varying mixing coefficients (\protect\key{traldf\_c3d} and \key{dynldf\_c3d})}
+
+The 3D space variation of the mixing coefficient is simply the combination of the 
+1D and 2D cases, $i.e.$ a hyperbolic tangent variation with depth associated with 
+a grid size dependence of the magnitude of the coefficient. 
+
+\subsubsection{Space and time varying mixing coefficients}
+
+There is no default specification of space and time varying mixing coefficient. 
+The only case available is specific to the ORCA2 and ORCA05 global ocean 
+configurations. It provides only a tracer 
+mixing coefficient for eddy induced velocity (ORCA2) or both iso-neutral and 
+eddy induced velocity (ORCA05) that depends on the local growth rate of 
+baroclinic instability. This specification is actually used when an ORCA key 
+and both \key{traldf\_eiv} and \key{traldf\_c2d} are defined.
+
+$\ $\newline    % force a new ligne
+
+The following points are relevant when the eddy coefficient varies spatially:
+
+(1) the momentum diffusion operator acting along model level surfaces is 
+written in terms of curl and divergent components of the horizontal current 
+(see \autoref{subsec:PE_ldf}). Although the eddy coefficient could be set to different values 
+in these two terms, this option is not currently available. 
+
+(2) with an horizontally varying viscosity, the quadratic integral constraints 
+on enstrophy and on the square of the horizontal divergence for operators 
+acting along model-surfaces are no longer satisfied 
+(\autoref{sec:dynldf_properties}).
+
+(3) for isopycnal diffusion on momentum or tracers, an additional purely 
+horizontal background diffusion with uniform coefficient can be added by 
+setting a non zero value of \np{rn\_ahmb0} or \np{rn\_ahtb0}, a background horizontal 
+eddy viscosity or diffusivity coefficient (namelist parameters whose default 
+values are $0$). However, the technique used to compute the isopycnal 
+slopes is intended to get rid of such a background diffusion, since it introduces 
+spurious diapycnal diffusion (see \autoref{sec:LDF_slp}).
+
+(4) when an eddy induced advection term is used (\key{traldf\_eiv}), $A^{eiv}$, 
+the eddy induced coefficient has to be defined. Its space variations are controlled 
+by the same CPP variable as for the eddy diffusivity coefficient ($i.e.$ 
+\key{traldf\_cNd}). 
+
+(5) the eddy coefficient associated with a biharmonic operator must be set to a \emph{negative} value.
+
+(6) it is possible to use both the laplacian and biharmonic operators concurrently.
+
+(7) it is possible to run without explicit lateral diffusion on momentum (\np{ln\_dynldf\_lap}\forcode{ = 
+}\np{ln\_dynldf\_bilap}\forcode{ = .false.}). This is recommended when using the UBS advection 
+scheme on momentum (\np{ln\_dynadv\_ubs}\forcode{ = .true.}, see \autoref{subsec:DYN_adv_ubs}) 
+and can be useful for testing purposes.
+
+% ================================================================
+% Eddy Induced Mixing
+% ================================================================
+\section{Eddy induced velocity (\protect\mdl{traadv\_eiv}, \protect\mdl{ldfeiv})}
+\label{sec:LDF_eiv}
+
+%%gm  from Triad appendix  : to be incorporated....
+\gmcomment{
+Values of iso-neutral diffusivity and GM coefficient are set as
+described in \autoref{sec:LDF_coef}. If none of the keys \key{traldf\_cNd},
+N=1,2,3 is set (the default), spatially constant iso-neutral $A_l$ and
+GM diffusivity $A_e$ are directly set by \np{rn\_aeih\_0} and
+\np{rn\_aeiv\_0}. If 2D-varying coefficients are set with
+\key{traldf\_c2d} then $A_l$ is reduced in proportion with horizontal
+scale factor according to \autoref{eq:title} \footnote{Except in global ORCA
+  $0.5^{\circ}$ runs with \key{traldf\_eiv}, where
+  $A_l$ is set like $A_e$ but with a minimum vale of
+  $100\;\mathrm{m}^2\;\mathrm{s}^{-1}$}. In idealised setups with
+\key{traldf\_c2d}, $A_e$ is reduced similarly, but if \key{traldf\_eiv}
+is set in the global configurations with \key{traldf\_c2d}, a horizontally varying $A_e$ is
+instead set from the Held-Larichev parameterisation\footnote{In this
+  case, $A_e$ at low latitudes $|\theta|<20^{\circ}$ is further
+  reduced by a factor $|f/f_{20}|$, where $f_{20}$ is the value of $f$
+  at $20^{\circ}$~N} (\mdl{ldfeiv}) and \np{rn\_aeiv\_0} is ignored
+unless it is zero.
+}
+
+When Gent and McWilliams [1990] diffusion is used (\key{traldf\_eiv} defined), 
+an eddy induced tracer advection term is added, the formulation of which 
+depends on the slopes of iso-neutral surfaces. Contrary to the case of iso-neutral 
+mixing, the slopes used here are referenced to the geopotential surfaces, $i.e.$ 
+\autoref{eq:ldfslp_geo} is used in $z$-coordinates, and the sum \autoref{eq:ldfslp_geo}  
++ \autoref{eq:ldfslp_iso} in $s$-coordinates. The eddy induced velocity is given by: 
+\begin{equation} \label{eq:ldfeiv}
+\begin{split}
+ u^* & = \frac{1}{e_{2u}e_{3u}}\; \delta_k \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right]\\
+v^* & = \frac{1}{e_{1u}e_{3v}}\; \delta_k \left[e_{1v} \, A_{vw}^{eiv} \; \overline{r_{2w}}^{\,j+1/2} \right]\\
+w^* & = \frac{1}{e_{1w}e_{2w}}\; \left\{ \delta_i \left[e_{2u} \, A_{uw}^{eiv} \; \overline{r_{1w}}^{\,i+1/2} \right] + \delta_j \left[e_{1v} \, A_{vw}^{eiv} \; \overline{r_{2w}}^{\,j+1/2} \right] \right\} \\
+\end{split}
+\end{equation}
+where $A^{eiv}$ is the eddy induced velocity coefficient whose value is set 
+through \np{rn\_aeiv}, a \textit{nam\_traldf} namelist parameter. 
+The three components of the eddy induced velocity are computed and add 
+to the eulerian velocity in \mdl{traadv\_eiv}. This has been preferred to a 
+separate computation of the advective trends associated with the eiv velocity, 
+since it allows us to take advantage of all the advection schemes offered for 
+the tracers (see \autoref{sec:TRA_adv}) and not just the $2^{nd}$ order advection 
+scheme as in previous releases of OPA \citep{Madec1998}. This is particularly 
+useful for passive tracers where \emph{positivity} of the advection scheme is 
+of paramount importance. 
+
+At the surface, lateral and bottom boundaries, the eddy induced velocity, 
+and thus the advective eddy fluxes of heat and salt, are set to zero. 
+
+
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_OBS.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_OBS.tex	(revision 10321)
@@ -0,0 +1,1407 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter observation operator (OBS)
+% ================================================================
+\chapter{Observation and Model Comparison (OBS)}
+\label{chap:OBS}
+
+Authors: D. Lea, M. Martin, K. Mogensen, A. Vidard, A. Weaver, A. Ryan, ...   % do we keep that ?
+
+\minitoc
+
+
+\newpage
+$\ $\newline    % force a new line
+
+The observation and model comparison code (OBS) reads in observation files (profile
+temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration,
+and velocity) and calculates  an interpolated model equivalent value at the observation
+location and nearest model timestep. The resulting data are saved in a ``feedback'' file (or
+files). The code was originally developed for use with the NEMOVAR data assimilation code, but
+can be used for validation or verification of the model or with any other data assimilation system.
+
+The OBS code is called from \mdl{nemogcm} for model initialisation and to calculate the model
+equivalent values for observations on the 0th timestep. The code is then called again after
+each timestep from \mdl{step}. The code is only activated if the namelist logical \np{ln\_diaobs}
+is set to true.
+
+For all data types a 2D horizontal interpolator or averager is needed to interpolate/average the model fields to
+the observation location. For {\em in situ} profiles, a 1D vertical interpolator is needed in
+addition to provide model fields at the observation depths. This now works in a generalised vertical
+coordinate system. 
+
+Some profile observation types (e.g. tropical moored buoys) are made available as daily averaged quantities.
+The observation operator code can be set-up to calculate the equivalent daily average model temperature fields
+using the \np{nn\_profdavtypes} namelist array. Some SST observations are equivalent to a night-time
+average value and the observation operator code can calculate equivalent night-time average model SST fields by
+setting the namelist value \np{ln\_sstnight} to true. Otherwise the model value from the nearest timestep to the
+observation time is used.
+
+The code is controlled by the namelist \textit{namobs}. See the following sections for more
+details on setting up the namelist.
+
+\autoref{sec:OBS_example} introduces a test example of the observation operator code including
+where to obtain data and how to setup the namelist. \autoref{sec:OBS_details} introduces some
+more technical details of the different observation types used and also shows a more complete
+namelist. \autoref{sec:OBS_theory} introduces some of the theoretical aspects of the observation
+operator including interpolation methods and running on multiple processors.
+\autoref{sec:OBS_ooo} describes the offline observation operator code.
+\autoref{sec:OBS_obsutils} introduces some utilities to help working with the files
+produced by the OBS code.
+
+% ================================================================
+% Example
+% ================================================================
+\section{Running the observation operator code example}
+\label{sec:OBS_example}
+
+This section describes an example of running the observation operator code using
+profile data which can be freely downloaded. It shows how to adapt an
+existing run and build of NEMO to run the observation operator.
+
+\begin{enumerate}
+\item Compile NEMO.
+
+\item Download some EN4 data from 
+\href{http://www.metoffice.gov.uk/hadobs}{www.metoffice.gov.uk/hadobs}. Choose observations which are
+valid for the period of your test run because the observation operator compares
+the model and observations for a matching date and time. 
+
+\item Compile the OBSTOOLS code using: 
+\begin{cmds}
+./maketools -n OBSTOOLS -m [ARCH].
+\end{cmds}
+
+\item Convert the EN4 data into feedback format: 
+\begin{cmds}
+enact2fb.exe profiles_01.nc EN.4.1.1.f.profiles.g10.YYYYMM.nc
+\end{cmds}
+
+\item Include the following in the NEMO namelist to run the observation
+operator on this data:
+\end{enumerate}
+
+%------------------------------------------namobs_example-----------------------------------------------------
+%
+%\nlst{namobs_example}
+%-------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namobs} namelist variables.
+The options \np{ln\_t3d} and \np{ln\_s3d} switch on the temperature and salinity
+profile observation operator code. The filename or array of filenames are
+specified using the \np{cn\_profbfiles} variable. The model grid points for a
+particular  observation latitude and longitude are found using the grid
+searching part of the code. This can be expensive, particularly for large
+numbers of observations, setting \np{ln\_grid\_search\_lookup} allows the use of
+a lookup table which is saved into an ``xypos`` file (or files). This will need
+to be generated the first time if it does not exist in the run directory.
+However, once produced it will significantly speed up future grid searches.
+Setting \np{ln\_grid\_global} means that the code distributes the observations
+evenly between processors. Alternatively each processor will work with
+observations located within the model subdomain (see section~\autoref{subsec:OBS_parallel}).
+
+A number of utilities are now provided to plot the feedback files, convert and
+recombine the files. These are explained in more detail in section~\autoref{sec:OBS_obsutils}.
+Utilites to convert other input data formats into the feedback format are also 
+described in section~\autoref{sec:OBS_obsutils}.
+
+\section{Technical details (feedback type observation file headers)}
+\label{sec:OBS_details}
+
+Here we show a more complete example namelist  \ngn{namobs} and also show the NetCDF headers
+of the observation
+files that may be used with the observation operator
+
+%------------------------------------------namobs--------------------------------------------------------
+
+\nlst{namobs}
+%-------------------------------------------------------------------------------------------------------------
+
+The observation operator code uses the "feedback" observation file format for
+all data types. All the
+observation files must be in NetCDF format. Some example headers (produced using
+\mbox{\textit{ncdump~-h}}) for profile
+data, sea level anomaly and sea surface temperature are in the following
+subsections.
+
+\subsection{Profile feedback}
+
+\begin{clines}
+netcdf profiles_01 {
+dimensions:
+     N_OBS = 603 ;
+     N_LEVELS = 150 ;
+     N_VARS = 2 ;
+     N_QCF = 2 ;
+     N_ENTRIES = 1 ;
+     N_EXTRA = 1 ;
+     STRINGNAM = 8 ;
+     STRINGGRID = 1 ;
+     STRINGWMO = 8 ;
+     STRINGTYP = 4 ;
+     STRINGJULD = 14 ;
+variables:
+     char VARIABLES(N_VARS, STRINGNAM) ;
+          VARIABLES:long_name = "List of variables in feedback files" ;
+     char ENTRIES(N_ENTRIES, STRINGNAM) ;
+          ENTRIES:long_name = "List of additional entries for each variable in feedback files" ;
+     char EXTRA(N_EXTRA, STRINGNAM) ;
+          EXTRA:long_name = "List of extra variables" ;
+     char STATION_IDENTIFIER(N_OBS, STRINGWMO) ;
+          STATION_IDENTIFIER:long_name = "Station identifier" ;
+     char STATION_TYPE(N_OBS, STRINGTYP) ;
+          STATION_TYPE:long_name = "Code instrument type" ;
+     double LONGITUDE(N_OBS) ;
+          LONGITUDE:long_name = "Longitude" ;
+          LONGITUDE:units = "degrees_east" ;
+          LONGITUDE:_Fillvalue = 99999.f ;
+     double LATITUDE(N_OBS) ;
+          LATITUDE:long_name = "Latitude" ;
+          LATITUDE:units = "degrees_north" ;
+          LATITUDE:_Fillvalue = 99999.f ;
+     double DEPTH(N_OBS, N_LEVELS) ;
+          DEPTH:long_name = "Depth" ;
+          DEPTH:units = "metre" ;
+          DEPTH:_Fillvalue = 99999.f ;
+     int DEPTH_QC(N_OBS, N_LEVELS) ;
+          DEPTH_QC:long_name = "Quality on depth" ;
+          DEPTH_QC:Conventions = "q where q =[0,9]" ;
+          DEPTH_QC:_Fillvalue = 0 ;
+     int DEPTH_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          DEPTH_QC_FLAGS:long_name = "Quality flags on depth" ;
+          DEPTH_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+     double JULD(N_OBS) ;
+          JULD:long_name = "Julian day" ;
+          JULD:units = "days since JULD_REFERENCE" ;
+          JULD:Conventions = "relative julian days with decimal part (as parts of day)" ;
+          JULD:_Fillvalue = 99999.f ;
+     char JULD_REFERENCE(STRINGJULD) ;
+          JULD_REFERENCE:long_name = "Date of reference for julian days" ;
+          JULD_REFERENCE:Conventions = "YYYYMMDDHHMMSS" ;
+     int OBSERVATION_QC(N_OBS) ;
+          OBSERVATION_QC:long_name = "Quality on observation" ;
+          OBSERVATION_QC:Conventions = "q where q =[0,9]" ;
+          OBSERVATION_QC:_Fillvalue = 0 ;
+     int OBSERVATION_QC_FLAGS(N_OBS, N_QCF) ;
+          OBSERVATION_QC_FLAGS:long_name = "Quality flags on observation" ;
+          OBSERVATION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          OBSERVATION_QC_FLAGS:_Fillvalue = 0 ;
+     int POSITION_QC(N_OBS) ;
+          POSITION_QC:long_name = "Quality on position (latitude and longitude)" ;
+          POSITION_QC:Conventions = "q where q =[0,9]" ;
+          POSITION_QC:_Fillvalue = 0 ;
+     int POSITION_QC_FLAGS(N_OBS, N_QCF) ;
+          POSITION_QC_FLAGS:long_name = "Quality flags on position" ;
+          POSITION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          POSITION_QC_FLAGS:_Fillvalue = 0 ;
+     int JULD_QC(N_OBS) ;
+          JULD_QC:long_name = "Quality on date and time" ;
+          JULD_QC:Conventions = "q where q =[0,9]" ;
+          JULD_QC:_Fillvalue = 0 ;
+     int JULD_QC_FLAGS(N_OBS, N_QCF) ;
+          JULD_QC_FLAGS:long_name = "Quality flags on date and time" ;
+          JULD_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          JULD_QC_FLAGS:_Fillvalue = 0 ;
+     int ORIGINAL_FILE_INDEX(N_OBS) ;
+          ORIGINAL_FILE_INDEX:long_name = "Index in original data file" ;
+          ORIGINAL_FILE_INDEX:_Fillvalue = -99999 ;
+     float POTM_OBS(N_OBS, N_LEVELS) ;
+          POTM_OBS:long_name = "Potential temperature" ;
+          POTM_OBS:units = "Degrees Celsius" ;
+          POTM_OBS:_Fillvalue = 99999.f ;
+     float POTM_Hx(N_OBS, N_LEVELS) ;
+          POTM_Hx:long_name = "Model interpolated potential temperature" ;
+          POTM_Hx:units = "Degrees Celsius" ;
+          POTM_Hx:_Fillvalue = 99999.f ;
+     int POTM_QC(N_OBS) ;
+          POTM_QC:long_name = "Quality on potential temperature" ;
+          POTM_QC:Conventions = "q where q =[0,9]" ;
+          POTM_QC:_Fillvalue = 0 ;
+     int POTM_QC_FLAGS(N_OBS, N_QCF) ;
+          POTM_QC_FLAGS:long_name = "Quality flags on potential temperature" ;
+          POTM_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          POTM_QC_FLAGS:_Fillvalue = 0 ;
+     int POTM_LEVEL_QC(N_OBS, N_LEVELS) ;
+          POTM_LEVEL_QC:long_name = "Quality for each level on potential temperature" ;
+          POTM_LEVEL_QC:Conventions = "q where q =[0,9]" ;
+          POTM_LEVEL_QC:_Fillvalue = 0 ;
+     int POTM_LEVEL_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          POTM_LEVEL_QC_FLAGS:long_name = "Quality flags for each level on potential temperature" ;
+          POTM_LEVEL_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          POTM_LEVEL_QC_FLAGS:_Fillvalue = 0 ;
+     int POTM_IOBSI(N_OBS) ;
+          POTM_IOBSI:long_name = "ORCA grid search I coordinate" ;
+     int POTM_IOBSJ(N_OBS) ;
+          POTM_IOBSJ:long_name = "ORCA grid search J coordinate" ;
+     int POTM_IOBSK(N_OBS, N_LEVELS) ;
+          POTM_IOBSK:long_name = "ORCA grid search K coordinate" ;
+     char POTM_GRID(STRINGGRID) ;
+          POTM_GRID:long_name = "ORCA grid search grid (T,U,V)" ;
+     float PSAL_OBS(N_OBS, N_LEVELS) ;
+          PSAL_OBS:long_name = "Practical salinity" ;
+          PSAL_OBS:units = "PSU" ;
+          PSAL_OBS:_Fillvalue = 99999.f ;
+     float PSAL_Hx(N_OBS, N_LEVELS) ;
+          PSAL_Hx:long_name = "Model interpolated practical salinity" ;
+          PSAL_Hx:units = "PSU" ;
+          PSAL_Hx:_Fillvalue = 99999.f ;
+     int PSAL_QC(N_OBS) ;
+          PSAL_QC:long_name = "Quality on practical salinity" ;
+          PSAL_QC:Conventions = "q where q =[0,9]" ;
+          PSAL_QC:_Fillvalue = 0 ;
+     int PSAL_QC_FLAGS(N_OBS, N_QCF) ;
+          PSAL_QC_FLAGS:long_name = "Quality flags on practical salinity" ;
+          PSAL_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          PSAL_QC_FLAGS:_Fillvalue = 0 ;
+     int PSAL_LEVEL_QC(N_OBS, N_LEVELS) ;
+          PSAL_LEVEL_QC:long_name = "Quality for each level on practical salinity" ;
+          PSAL_LEVEL_QC:Conventions = "q where q =[0,9]" ;
+          PSAL_LEVEL_QC:_Fillvalue = 0 ;
+     int PSAL_LEVEL_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          PSAL_LEVEL_QC_FLAGS:long_name = "Quality flags for each level on practical salinity" ;
+          PSAL_LEVEL_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          PSAL_LEVEL_QC_FLAGS:_Fillvalue = 0 ;
+     int PSAL_IOBSI(N_OBS) ;
+          PSAL_IOBSI:long_name = "ORCA grid search I coordinate" ;
+     int PSAL_IOBSJ(N_OBS) ;
+          PSAL_IOBSJ:long_name = "ORCA grid search J coordinate" ;
+     int PSAL_IOBSK(N_OBS, N_LEVELS) ;
+          PSAL_IOBSK:long_name = "ORCA grid search K coordinate" ;
+     char PSAL_GRID(STRINGGRID) ;
+          PSAL_GRID:long_name = "ORCA grid search grid (T,U,V)" ;
+     float TEMP(N_OBS, N_LEVELS) ;
+          TEMP:long_name = "Insitu temperature" ;
+          TEMP:units = "Degrees Celsius" ;
+          TEMP:_Fillvalue = 99999.f ;
+
+// global attributes:
+          :title = "NEMO observation operator output" ;
+          :Convention = "NEMO unified observation operator output" ;
+}
+\end{clines}
+
+\subsection{Sea level anomaly feedback}
+
+\begin{clines}
+netcdf sla_01 {
+dimensions:
+     N_OBS = 41301 ;
+     N_LEVELS = 1 ;
+     N_VARS = 1 ;
+     N_QCF = 2 ;
+     N_ENTRIES = 1 ;
+     N_EXTRA = 1 ;
+     STRINGNAM = 8 ;
+     STRINGGRID = 1 ;
+     STRINGWMO = 8 ;
+     STRINGTYP = 4 ;
+     STRINGJULD = 14 ;
+variables:
+     char VARIABLES(N_VARS, STRINGNAM) ;
+          VARIABLES:long_name = "List of variables in feedback files" ;
+     char ENTRIES(N_ENTRIES, STRINGNAM) ;
+          ENTRIES:long_name = "List of additional entries for each variable in feedback files" ;
+     char EXTRA(N_EXTRA, STRINGNAM) ;
+          EXTRA:long_name = "List of extra variables" ;
+     char STATION_IDENTIFIER(N_OBS, STRINGWMO) ;
+          STATION_IDENTIFIER:long_name = "Station identifier" ;
+     char STATION_TYPE(N_OBS, STRINGTYP) ;
+          STATION_TYPE:long_name = "Code instrument type" ;
+     double LONGITUDE(N_OBS) ;
+          LONGITUDE:long_name = "Longitude" ;
+          LONGITUDE:units = "degrees_east" ;
+          LONGITUDE:_Fillvalue = 99999.f ;
+     double LATITUDE(N_OBS) ;
+          LATITUDE:long_name = "Latitude" ;
+          LATITUDE:units = "degrees_north" ;
+          LATITUDE:_Fillvalue = 99999.f ;
+     double DEPTH(N_OBS, N_LEVELS) ;
+          DEPTH:long_name = "Depth" ;
+          DEPTH:units = "metre" ;
+          DEPTH:_Fillvalue = 99999.f ;
+     int DEPTH_QC(N_OBS, N_LEVELS) ;
+          DEPTH_QC:long_name = "Quality on depth" ;
+          DEPTH_QC:Conventions = "q where q =[0,9]" ;
+          DEPTH_QC:_Fillvalue = 0 ;
+     int DEPTH_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          DEPTH_QC_FLAGS:long_name = "Quality flags on depth" ;
+          DEPTH_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+     double JULD(N_OBS) ;
+          JULD:long_name = "Julian day" ;
+          JULD:units = "days since JULD_REFERENCE" ;
+          JULD:Conventions = "relative julian days with decimal part (as parts of day)" ;
+          JULD:_Fillvalue = 99999.f ;
+     char JULD_REFERENCE(STRINGJULD) ;
+          JULD_REFERENCE:long_name = "Date of reference for julian days" ;
+          JULD_REFERENCE:Conventions = "YYYYMMDDHHMMSS" ;
+     int OBSERVATION_QC(N_OBS) ;
+          OBSERVATION_QC:long_name = "Quality on observation" ;
+          OBSERVATION_QC:Conventions = "q where q =[0,9]" ;
+          OBSERVATION_QC:_Fillvalue = 0 ;
+     int OBSERVATION_QC_FLAGS(N_OBS, N_QCF) ;
+          OBSERVATION_QC_FLAGS:long_name = "Quality flags on observation" ;
+          OBSERVATION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          OBSERVATION_QC_FLAGS:_Fillvalue = 0 ;
+     int POSITION_QC(N_OBS) ;
+          POSITION_QC:long_name = "Quality on position (latitude and longitude)" ;
+          POSITION_QC:Conventions = "q where q =[0,9]" ;
+          POSITION_QC:_Fillvalue = 0 ;
+     int POSITION_QC_FLAGS(N_OBS, N_QCF) ;
+          POSITION_QC_FLAGS:long_name = "Quality flags on position" ;
+          POSITION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          POSITION_QC_FLAGS:_Fillvalue = 0 ;
+     int JULD_QC(N_OBS) ;
+          JULD_QC:long_name = "Quality on date and time" ;
+          JULD_QC:Conventions = "q where q =[0,9]" ;
+          JULD_QC:_Fillvalue = 0 ;
+     int JULD_QC_FLAGS(N_OBS, N_QCF) ;
+          JULD_QC_FLAGS:long_name = "Quality flags on date and time" ;
+          JULD_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          JULD_QC_FLAGS:_Fillvalue = 0 ;
+     int ORIGINAL_FILE_INDEX(N_OBS) ;
+          ORIGINAL_FILE_INDEX:long_name = "Index in original data file" ;
+          ORIGINAL_FILE_INDEX:_Fillvalue = -99999 ;
+     float SLA_OBS(N_OBS, N_LEVELS) ;
+          SLA_OBS:long_name = "Sea level anomaly" ;
+          SLA_OBS:units = "metre" ;
+          SLA_OBS:_Fillvalue = 99999.f ;
+     float SLA_Hx(N_OBS, N_LEVELS) ;
+          SLA_Hx:long_name = "Model interpolated sea level anomaly" ;
+          SLA_Hx:units = "metre" ;
+          SLA_Hx:_Fillvalue = 99999.f ;
+     int SLA_QC(N_OBS) ;
+          SLA_QC:long_name = "Quality on sea level anomaly" ;
+          SLA_QC:Conventions = "q where q =[0,9]" ;
+          SLA_QC:_Fillvalue = 0 ;
+     int SLA_QC_FLAGS(N_OBS, N_QCF) ;
+          SLA_QC_FLAGS:long_name = "Quality flags on sea level anomaly" ;
+          SLA_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          SLA_QC_FLAGS:_Fillvalue = 0 ;
+     int SLA_LEVEL_QC(N_OBS, N_LEVELS) ;
+          SLA_LEVEL_QC:long_name = "Quality for each level on sea level anomaly" ;
+          SLA_LEVEL_QC:Conventions = "q where q =[0,9]" ;
+          SLA_LEVEL_QC:_Fillvalue = 0 ;
+     int SLA_LEVEL_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          SLA_LEVEL_QC_FLAGS:long_name = "Quality flags for each level on sea level anomaly" ;
+          SLA_LEVEL_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          SLA_LEVEL_QC_FLAGS:_Fillvalue = 0 ;
+     int SLA_IOBSI(N_OBS) ;
+          SLA_IOBSI:long_name = "ORCA grid search I coordinate" ;
+     int SLA_IOBSJ(N_OBS) ;
+          SLA_IOBSJ:long_name = "ORCA grid search J coordinate" ;
+     int SLA_IOBSK(N_OBS, N_LEVELS) ;
+          SLA_IOBSK:long_name = "ORCA grid search K coordinate" ;
+     char SLA_GRID(STRINGGRID) ;
+          SLA_GRID:long_name = "ORCA grid search grid (T,U,V)" ;
+     float MDT(N_OBS, N_LEVELS) ;
+          MDT:long_name = "Mean Dynamic Topography" ;
+          MDT:units = "metre" ;
+          MDT:_Fillvalue = 99999.f ;
+
+// global attributes:
+          :title = "NEMO observation operator output" ;
+          :Convention = "NEMO unified observation operator output" ;
+}
+\end{clines}
+
+The mean dynamic
+topography (MDT) must be provided in a separate file defined on the model grid
+ called \ifile{slaReferenceLevel}. The MDT is required in
+order to produce the model equivalent sea level anomaly from the model sea
+surface height. Below is an example header for this file (on the ORCA025 grid).
+
+\begin{clines}
+dimensions:
+        x = 1442 ;
+        y = 1021 ;
+variables:
+        float nav_lon(y, x) ;
+                nav_lon:units = "degrees_east" ;
+        float nav_lat(y, x) ;
+                nav_lat:units = "degrees_north" ;
+        float sossheig(y, x) ;
+                sossheig:_FillValue = -1.e+30f ;
+                sossheig:coordinates = "nav_lon nav_lat" ;
+                sossheig:long_name = "Mean Dynamic Topography" ;
+                sossheig:units = "metres" ;
+                sossheig:grid = "orca025T" ;
+\end{clines}
+
+\subsection{Sea surface temperature feedback}
+
+\begin{clines}
+netcdf sst_01 {
+dimensions:
+     N_OBS = 33099 ;
+     N_LEVELS = 1 ;
+     N_VARS = 1 ;
+     N_QCF = 2 ;
+     N_ENTRIES = 1 ;
+     STRINGNAM = 8 ;
+     STRINGGRID = 1 ;
+     STRINGWMO = 8 ;
+     STRINGTYP = 4 ;
+     STRINGJULD = 14 ;
+variables:
+     char VARIABLES(N_VARS, STRINGNAM) ;
+          VARIABLES:long_name = "List of variables in feedback files" ;
+     char ENTRIES(N_ENTRIES, STRINGNAM) ;
+          ENTRIES:long_name = "List of additional entries for each variable in feedback files" ;
+     char STATION_IDENTIFIER(N_OBS, STRINGWMO) ;
+          STATION_IDENTIFIER:long_name = "Station identifier" ;
+     char STATION_TYPE(N_OBS, STRINGTYP) ;
+          STATION_TYPE:long_name = "Code instrument type" ;
+     double LONGITUDE(N_OBS) ;
+          LONGITUDE:long_name = "Longitude" ;
+          LONGITUDE:units = "degrees_east" ;
+          LONGITUDE:_Fillvalue = 99999.f ;
+     double LATITUDE(N_OBS) ;
+          LATITUDE:long_name = "Latitude" ;
+          LATITUDE:units = "degrees_north" ;
+          LATITUDE:_Fillvalue = 99999.f ;
+     double DEPTH(N_OBS, N_LEVELS) ;
+          DEPTH:long_name = "Depth" ;
+          DEPTH:units = "metre" ;
+          DEPTH:_Fillvalue = 99999.f ;
+     int DEPTH_QC(N_OBS, N_LEVELS) ;
+          DEPTH_QC:long_name = "Quality on depth" ;
+          DEPTH_QC:Conventions = "q where q =[0,9]" ;
+          DEPTH_QC:_Fillvalue = 0 ;
+     int DEPTH_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          DEPTH_QC_FLAGS:long_name = "Quality flags on depth" ;
+          DEPTH_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+     double JULD(N_OBS) ;
+          JULD:long_name = "Julian day" ;
+          JULD:units = "days since JULD_REFERENCE" ;
+          JULD:Conventions = "relative julian days with decimal part (as parts of day)" ;
+          JULD:_Fillvalue = 99999.f ;
+     char JULD_REFERENCE(STRINGJULD) ;
+          JULD_REFERENCE:long_name = "Date of reference for julian days" ;
+          JULD_REFERENCE:Conventions = "YYYYMMDDHHMMSS" ;
+     int OBSERVATION_QC(N_OBS) ;
+          OBSERVATION_QC:long_name = "Quality on observation" ;
+          OBSERVATION_QC:Conventions = "q where q =[0,9]" ;
+          OBSERVATION_QC:_Fillvalue = 0 ;
+     int OBSERVATION_QC_FLAGS(N_OBS, N_QCF) ;
+          OBSERVATION_QC_FLAGS:long_name = "Quality flags on observation" ;
+          OBSERVATION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          OBSERVATION_QC_FLAGS:_Fillvalue = 0 ;
+     int POSITION_QC(N_OBS) ;
+          POSITION_QC:long_name = "Quality on position (latitude and longitude)" ;
+          POSITION_QC:Conventions = "q where q =[0,9]" ;
+          POSITION_QC:_Fillvalue = 0 ;
+     int POSITION_QC_FLAGS(N_OBS, N_QCF) ;
+          POSITION_QC_FLAGS:long_name = "Quality flags on position" ;
+          POSITION_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          POSITION_QC_FLAGS:_Fillvalue = 0 ;
+     int JULD_QC(N_OBS) ;
+          JULD_QC:long_name = "Quality on date and time" ;
+          JULD_QC:Conventions = "q where q =[0,9]" ;
+          JULD_QC:_Fillvalue = 0 ;
+     int JULD_QC_FLAGS(N_OBS, N_QCF) ;
+          JULD_QC_FLAGS:long_name = "Quality flags on date and time" ;
+          JULD_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          JULD_QC_FLAGS:_Fillvalue = 0 ;
+     int ORIGINAL_FILE_INDEX(N_OBS) ;
+          ORIGINAL_FILE_INDEX:long_name = "Index in original data file" ;
+          ORIGINAL_FILE_INDEX:_Fillvalue = -99999 ;
+     float SST_OBS(N_OBS, N_LEVELS) ;
+          SST_OBS:long_name = "Sea surface temperature" ;
+          SST_OBS:units = "Degree centigrade" ;
+          SST_OBS:_Fillvalue = 99999.f ;
+     float SST_Hx(N_OBS, N_LEVELS) ;
+          SST_Hx:long_name = "Model interpolated sea surface temperature" ;
+          SST_Hx:units = "Degree centigrade" ;
+          SST_Hx:_Fillvalue = 99999.f ;
+     int SST_QC(N_OBS) ;
+          SST_QC:long_name = "Quality on sea surface temperature" ;
+          SST_QC:Conventions = "q where q =[0,9]" ;
+          SST_QC:_Fillvalue = 0 ;
+     int SST_QC_FLAGS(N_OBS, N_QCF) ;
+          SST_QC_FLAGS:long_name = "Quality flags on sea surface temperature" ;
+          SST_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          SST_QC_FLAGS:_Fillvalue = 0 ;
+     int SST_LEVEL_QC(N_OBS, N_LEVELS) ;
+          SST_LEVEL_QC:long_name = "Quality for each level on sea surface temperature" ;
+          SST_LEVEL_QC:Conventions = "q where q =[0,9]" ;
+          SST_LEVEL_QC:_Fillvalue = 0 ;
+     int SST_LEVEL_QC_FLAGS(N_OBS, N_LEVELS, N_QCF) ;
+          SST_LEVEL_QC_FLAGS:long_name = "Quality flags for each level on sea surface temperature" ;
+          SST_LEVEL_QC_FLAGS:Conventions = "NEMOVAR flag conventions" ;
+          SST_LEVEL_QC_FLAGS:_Fillvalue = 0 ;
+     int SST_IOBSI(N_OBS) ;
+          SST_IOBSI:long_name = "ORCA grid search I coordinate" ;
+     int SST_IOBSJ(N_OBS) ;
+          SST_IOBSJ:long_name = "ORCA grid search J coordinate" ;
+     int SST_IOBSK(N_OBS, N_LEVELS) ;
+          SST_IOBSK:long_name = "ORCA grid search K coordinate" ;
+     char SST_GRID(STRINGGRID) ;
+          SST_GRID:long_name = "ORCA grid search grid (T,U,V)" ;
+
+// global attributes:
+          :title = "NEMO observation operator output" ;
+          :Convention = "NEMO unified observation operator output" ;
+}
+\end{clines}
+
+\section{Theoretical details}
+\label{sec:OBS_theory}
+
+\subsection{Horizontal interpolation and averaging methods}
+
+For most observation types, the horizontal extent of the observation is small compared to the model grid size
+and so the model equivalent of the observation is calculated by interpolating from the four surrounding grid
+points to the observation location. Some satellite observations (e.g. microwave satellite SST data, or satellite SSS data)
+have a footprint which is similar in size or larger than the model grid size (particularly when the grid size is small). 
+In those cases the model counterpart should be calculated by averaging the model grid points over the same size as the footprint.
+NEMO therefore has the capability to specify either an interpolation or an averaging (for surface observation types only). 
+
+The main namelist option associated with the interpolation/averaging is \np{nn\_2dint}. This default option can be set to values from 0 to 6. 
+Values between 0 to 4 are associated with interpolation while values 5 or 6 are associated with averaging.
+\begin{itemize}
+\item \np{nn\_2dint}\forcode{ = 0}: Distance-weighted interpolation
+\item \np{nn\_2dint}\forcode{ = 1}: Distance-weighted interpolation (small angle)
+\item \np{nn\_2dint}\forcode{ = 2}: Bilinear interpolation (geographical grid)
+\item \np{nn\_2dint}\forcode{ = 3}: Bilinear remapping interpolation (general grid)
+\item \np{nn\_2dint}\forcode{ = 4}: Polynomial interpolation
+\item \np{nn\_2dint}\forcode{ = 5}: Radial footprint averaging with diameter specified in the namelist as \np{rn\_???\_avglamscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs})
+\item \np{nn\_2dint}\forcode{ = 6}: Rectangular footprint averaging with E/W and N/S size specified in the namelist as \np{rn\_???\_avglamscl} and \np{rn\_???\_avgphiscl} in degrees or metres (set using \np{ln\_???\_fp\_indegs})
+\end{itemize}
+The ??? in the last two options indicate these options should be specified for each observation type for which the averaging is to be performed (see namelist example above).
+The \np{nn\_2dint} default option can be overridden for surface observation types using namelist values \np{nn\_2dint\_???} where ??? is one of sla,sst,sss,sic.
+
+Below is some more detail on the various options for interpolation and averaging available in NEMO.
+
+\subsubsection{Horizontal interpolation}
+Consider an observation point ${\rm P}$ with 
+with longitude and latitude $({\lambda_{}}_{\rm P}, \phi_{\rm P})$ and the 
+four nearest neighbouring model grid points ${\rm A}$, ${\rm B}$, ${\rm C}$ 
+and ${\rm D}$ with longitude and latitude ($\lambda_{\rm A}$, $\phi_{\rm A}$),
+($\lambda_{\rm B}$, $\phi_{\rm B}$) etc.
+All horizontal interpolation methods implemented in NEMO
+estimate the value of a model variable $x$ at point $P$ as
+a weighted linear combination of the values of the model 
+variables at the grid points ${\rm A}$, ${\rm B}$ etc.:
+\begin{eqnarray}
+{x_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & 
+\frac{1}{w} \left( {w_{}}_{\rm A} {x_{}}_{\rm A} + 
+                   {w_{}}_{\rm B} {x_{}}_{\rm B} + 
+                   {w_{}}_{\rm C} {x_{}}_{\rm C} + 
+                   {w_{}}_{\rm D} {x_{}}_{\rm D} \right)
+\end{eqnarray}
+where ${w_{}}_{\rm A}$, ${w_{}}_{\rm B}$ etc. are the respective weights for the 
+model field at points ${\rm A}$, ${\rm B}$ etc., and 
+$w = {w_{}}_{\rm A} + {w_{}}_{\rm B} + {w_{}}_{\rm C} + {w_{}}_{\rm D}$.
+
+Four different possibilities are available for computing the weights.
+
+\begin{enumerate}
+
+\item[1.] {\bf Great-Circle distance-weighted interpolation.} The weights
+  are computed as a function of the great-circle distance $s(P, \cdot)$ 
+  between $P$ and the model grid points $A$, $B$ etc. For example, 
+  the weight given to the field ${x_{}}_{\rm A}$ is specified as the 
+  product of the distances from ${\rm P}$ to the other points:
+  \begin{eqnarray}
+  {w_{}}_{\rm A} = s({\rm P}, {\rm B}) \, s({\rm P}, {\rm C}) \, s({\rm P}, {\rm D})
+  \nonumber
+  \end{eqnarray}
+  where 
+  \begin{eqnarray}
+   s\left ({\rm P}, {\rm M} \right ) 
+     & \hspace{-2mm} = \hspace{-2mm} & 
+      \cos^{-1} \! \left\{ 
+               \sin {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm M}
+             + \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm M} 
+               \cos ({\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P}) 
+                   \right\}
+   \end{eqnarray}
+   and $M$ corresponds to $B$, $C$ or $D$.
+   A more stable form of the great-circle distance formula for
+   small distances ($x$ near 1) involves the arcsine function
+   ($e.g.$ see p.~101 of \citet{Daley_Barker_Bk01}:
+   \begin{eqnarray}
+   s\left( {\rm P}, {\rm M} \right) 
+     & \hspace{-2mm} = \hspace{-2mm} & 
+      \sin^{-1} \! \left\{ \sqrt{ 1 - x^2 } \right\}
+   \nonumber
+   \end{eqnarray}
+   where
+   \begin{eqnarray}
+    x & \hspace{-2mm} = \hspace{-2mm} & 
+      {a_{}}_{\rm M} {a_{}}_{\rm P} + {b_{}}_{\rm M} {b_{}}_{\rm P} + {c_{}}_{\rm M} {c_{}}_{\rm P}
+   \nonumber
+   \end{eqnarray}
+   and 
+   \begin{eqnarray}
+      {a_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm M}, 
+      \nonumber \\
+      {a_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \sin {\phi_{}}_{\rm P}, 
+      \nonumber \\
+      {b_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \cos {\phi_{}}_{\rm M}, 
+      \nonumber \\
+      {b_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \cos {\phi_{}}_{\rm P}, 
+      \nonumber \\
+      {c_{}}_{\rm M} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm M} \sin {\phi_{}}_{\rm M}, 
+      \nonumber \\
+      {c_{}}_{\rm P} & \hspace{-2mm} = \hspace{-2mm} & \cos {\phi_{}}_{\rm P} \sin {\phi_{}}_{\rm P}.
+      \nonumber
+   \nonumber
+  \end{eqnarray}
+
+\item[2.] {\bf Great-Circle distance-weighted interpolation with small angle
+  approximation.} Similar to the previous interpolation but with the
+  distance $s$ computed as
+  \begin{eqnarray}
+    s\left( {\rm P}, {\rm M} \right) 
+     & \hspace{-2mm} = \hspace{-2mm} & 
+      \sqrt{ \left( {\phi_{}}_{\rm M} - {\phi_{}}_{\rm P} \right)^{2} 
+      + \left( {\lambda_{}}_{\rm M} - {\lambda_{}}_{\rm P} \right)^{2}
+        \cos^{2} {\phi_{}}_{\rm M} }
+  \end{eqnarray}
+  where $M$ corresponds to $A$, $B$, $C$ or $D$.
+
+\item[3.] {\bf Bilinear interpolation for a regular spaced grid.} The
+  interpolation is split into two 1D interpolations in the longitude
+  and latitude directions, respectively.
+
+\item[4.] {\bf Bilinear remapping interpolation for a general grid.} An
+  iterative scheme that involves first mapping a quadrilateral cell
+  into a cell with coordinates (0,0), (1,0), (0,1) and (1,1). This
+  method is based on the SCRIP interpolation package \citep{Jones_1998}.
+  
+\end{enumerate}
+
+\subsubsection{Horizontal averaging}
+
+For each surface observation type:
+\begin{itemize}
+\item The standard grid-searching code is used to find the nearest model grid point to the observation location (see next subsection).
+\item The maximum number of grid points is calculated in the local grid domain for which the averaging is likely need to cover.
+\item The lats/longs of the grid points surrounding the nearest model grid box are extracted using existing mpi routines.
+\item The weights for each grid point associated with each observation are calculated, either for radial or rectangular footprints. For grid points completely within the footprint, the weight is one; for grid points completely outside the footprint, the weight is zero. For grid points which are partly within the footprint the ratio between the area of the footprint within the grid box and the total area of the grid box is used as the weight.
+\item The weighted average of the model grid points associated with each observation is calculated, and this is then given as the model counterpart of the observation.
+\end{itemize}
+
+Examples of the weights calculated for an observation with rectangular and radial footprints are shown in Figs.~\autoref{fig:obsavgrec} and~\autoref{fig:obsavgrad}.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}      \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rec}
+\caption{      \protect\label{fig:obsavgrec}
+Weights associated with each model grid box (blue lines and numbers) for an observation at -170.5E, 56.0N with a rectangular footprint of 1\deg x 1\deg.}
+\end{center}      \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}      \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_OBS_avg_rad}
+\caption{      \protect\label{fig:obsavgrad}
+Weights associated with each model grid box (blue lines and numbers) for an observation at -170.5E, 56.0N with a radial footprint with diameter 1\deg.} 
+\end{center}      \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+\subsection{Grid search}
+
+For many grids used by the NEMO model, such as the ORCA family, 
+the horizontal grid coordinates $i$ and $j$ are not simple functions 
+of latitude and longitude. Therefore, it is not always straightforward 
+to determine the grid points surrounding any given observational position.
+Before the interpolation can be performed, a search 
+algorithm is then required to determine the corner points of 
+the quadrilateral cell in which the observation is located.
+This is the most difficult and time consuming part of the 
+2D interpolation procedure. 
+A robust test for determining if an observation falls
+within a given quadrilateral cell is as follows. Let 
+${\rm P}({\lambda_{}}_{\rm P} ,{\phi_{}}_{\rm P} )$ denote the observation point,
+and let ${\rm A}({\lambda_{}}_{\rm A} ,{\phi_{}}_{\rm A} )$,
+${\rm B}({\lambda_{}}_{\rm B} ,{\phi_{}}_{\rm B} )$,
+${\rm C}({\lambda_{}}_{\rm C} ,{\phi_{}}_{\rm C} )$ 
+and 
+${\rm D}({\lambda_{}}_{\rm D} ,{\phi_{}}_{\rm D} )$ denote
+the bottom left, bottom right, top left and top right
+corner points of the cell, respectively. 
+To determine if P is inside 
+the cell, we verify that the cross-products 
+\begin{eqnarray}
+\begin{array}{lllll}
+{{\bf r}_{}}_{\rm PA} \times {{\bf r}_{}}_{\rm PC}
+& = & [({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )
+    - ({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+{{\bf r}_{}}_{\rm PB} \times {{\bf r}_{}}_{\rm PA}
+& = & [({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm A}   \; -\; {\phi_{}}_{\rm P} )
+    - ({\lambda_{}}_{\rm A}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+{{\bf r}_{}}_{\rm PC} \times {{\bf r}_{}}_{\rm PD}
+& = & [({\lambda_{}}_{\rm C}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm D}   \; -\; {\phi_{}}_{\rm P} )
+    - ({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm C}   \; -\; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+{{\bf r}_{}}_{\rm PD} \times {{\bf r}_{}}_{\rm PB}
+& = & [({\lambda_{}}_{\rm D}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm B}   \; -\; {\phi_{}}_{\rm P} )
+    - ({\lambda_{}}_{\rm B}\; -\; {\lambda_{}}_{\rm P} )
+      ({\phi_{}}_{\rm D}  \;  - \; {\phi_{}}_{\rm P} )] \; \widehat{\bf k} \\
+\end{array}
+\label{eq:cross}
+\end{eqnarray}
+point in the opposite direction to the unit normal 
+$\widehat{\bf k}$ (i.e., that the coefficients of 
+$\widehat{\bf k}$ are negative),
+where ${{\bf r}_{}}_{\rm PA}$, ${{\bf r}_{}}_{\rm PB}$, 
+etc. correspond to the vectors between points P and A, 
+P and B, etc.. The method used is
+similar to the method used in
+the SCRIP interpolation package \citep{Jones_1998}.
+
+In order to speed up the grid search, there is the possibility to construct 
+a lookup table for a user specified resolution. This lookup
+table contains the lower and upper bounds on the $i$ and $j$ indices
+to be searched for on a regular grid. For each observation position,
+the closest point on the regular grid of this position is computed and
+the $i$ and $j$ ranges of this point searched to determine the precise
+four points surrounding the observation. 
+
+\subsection{Parallel aspects of horizontal interpolation}
+\label{subsec:OBS_parallel}
+
+For horizontal interpolation, there is the basic problem that the
+observations are unevenly distributed on the globe. In numerical
+models, it is common to divide the model grid into subgrids (or
+domains) where each subgrid is executed on a single processing element
+with explicit message passing for exchange of information along the
+domain boundaries when running on a massively parallel processor (MPP)
+system. This approach is used by \NEMO.
+
+For observations there is no natural distribution since the
+observations are not equally distributed on the globe. 
+Two options have been made available: 1) geographical distribution;
+and 2) round-robin.
+
+\subsubsection{Geographical distribution of observations among processors}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}      \begin{center}
+\includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_local}
+\caption{      \protect\label{fig:obslocal}
+Example of the distribution of observations with the geographical distribution of observational data.} 
+\end{center}      \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+This is the simplest option in which the observations are distributed according 
+to the domain of the grid-point parallelization. \autoref{fig:obslocal}
+shows an example of the distribution of the {\em in situ} data on processors 
+with a different colour for each observation
+on a given processor for a 4 $\times$ 2 decomposition with ORCA2. 
+The grid-point domain decomposition is clearly visible on the plot.
+
+The advantage of this approach is that all
+information needed for horizontal interpolation is available without
+any MPP communication. Of course, this is under the assumption that 
+we are only using a $2 \times 2$ grid-point stencil for the interpolation 
+(e.g., bilinear interpolation). For higher order interpolation schemes this
+is no longer valid. A disadvantage with the above scheme is that the number of
+observations on each processor can be very different. If the cost of
+the actual interpolation is expensive relative to the communication of
+data needed for interpolation, this could lead to load imbalance.
+
+\subsubsection{Round-robin distribution of observations among processors}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}     \begin{center}
+\includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_ASM_obsdist_global}
+\caption{      \protect\label{fig:obsglobal}
+Example of the distribution of observations with the round-robin distribution of observational data.}
+\end{center}     \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+An alternative approach is to distribute the observations equally
+among processors and use message passing in order to retrieve 
+the stencil for interpolation. The simplest distribution of the observations 
+is to distribute them using a round-robin scheme. \autoref{fig:obsglobal}
+shows the distribution of the {\em in situ} data on processors for the
+round-robin distribution of observations with a different colour for
+each observation on a given processor for a 4 $\times$ 2 decomposition 
+with ORCA2 for the same input data as in \autoref{fig:obslocal}.
+The observations are now clearly randomly distributed on the globe.
+In order to be able to perform horizontal interpolation in this case, 
+a subroutine has been developed that retrieves any grid points in the 
+global space.
+
+\subsection{Vertical interpolation operator}
+
+Vertical interpolation is achieved using either a cubic spline or
+linear interpolation. For the cubic spline, the top and
+bottom boundary conditions for the second derivative of the 
+interpolating polynomial in the spline are set to zero.
+At the bottom boundary, this is done using the land-ocean mask.
+
+\newpage
+
+% ================================================================
+% Offline observation operator documentation
+% ================================================================
+
+%\usepackage{framed}
+
+\section{Offline observation operator}
+\label{sec:OBS_ooo}
+
+\subsection{Concept}
+
+The obs oper maps model variables to observation space. It is possible to apply this mapping
+without running the model. The software which performs this functionality is known as the
+\textbf{offline obs oper}. The obs oper is divided into three stages. An initialisation phase,
+an interpolation phase and an output phase. The implementation of which is outlined in the
+previous sections. During the interpolation phase the offline obs oper populates the model
+arrays by reading saved model fields from disk.
+
+There are two ways of exploiting this offline capacity. The first is to mimic the behaviour of
+the online system by supplying model fields at regular intervals between the start and the end
+of the run. This approach results in a single model counterpart per observation. This kind of
+usage produces feedback files the same file format as the online obs oper. 
+The second is to take advantage of the offline setting in which multiple model counterparts can
+be calculated per observation. In this case it is possible to consider all forecasts verifying
+at the same time. By forecast, I mean any method which produces an estimate of physical reality
+which is not an observed value. In the case of class 4 files this means forecasts, analyses, persisted
+analyses and climatological values verifying at the same time. Although the class 4 file format
+doesn't account for multiple ensemble members or multiple experiments per observation, it is possible
+to include these components in the same or multiple files.
+
+%--------------------------------------------------------------------------------------------------------
+% offline_oper.exe 
+%--------------------------------------------------------------------------------------------------------
+
+\subsection{Using the offline observation operator}
+
+\subsubsection{Building}
+
+In addition to \emph{OPA\_SRC} the offline obs oper requires the inclusion
+of the \emph{OOO\_SRC} directory. \emph{OOO\_SRC} contains a replacement \mdl{nemo} and
+\mdl{nemogcm} which overwrites the resultant \textbf{nemo.exe}. This is the approach taken
+by \emph{SAS\_SRC} and \emph{OFF\_SRC}.
+
+%--------------------------------------------------------------------------------------------------------
+% Running 
+%--------------------------------------------------------------------------------------------------------
+\subsubsection{Running}
+
+The simplest way to use the executable is to edit and append the \textbf{ooo.nml} namelist to
+a full NEMO namelist and then to run the executable as if it were nemo.exe. 
+
+\subsubsection{Quick script}
+
+A useful Python utility to control the namelist options can be found in \textbf{OBSTOOLS/OOO}. The
+functions which locate model fields and observation files can be manually specified. The package
+can be installed by appropriate use of the included setup.py script.
+
+Documentation can be auto-generated by Sphinx by running \emph{make html} in the \textbf{doc} directory.
+
+%--------------------------------------------------------------------------------------------------------
+% Configuration section
+%--------------------------------------------------------------------------------------------------------
+\subsection{Configuring the offline observation operator}
+The observation files and settings understood by \textbf{namobs} have been outlined in the online
+obs oper section. In addition there are two further namelists wich control the operation of the offline
+obs oper. \textbf{namooo} which controls the input model fields and \textbf{namcl4} which controls the
+production of class 4 files. 
+
+\subsubsection{Single field}
+
+In offline mode model arrays are populated at appropriate time steps via input files.
+At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines. 
+These routines will be expanded upon in future versions to allow the specification of any
+model variable. As such, input files must be global versions of the model domain with
+\textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present.
+
+For each field read there must be an entry in the \textbf{namooo} namelist specifying the
+name of the file to read and the index along the \emph{time\_counter}. For example, to
+read the second time counter from a single file the namelist would be.
+
+\begin{forlines}
+!----------------------------------------------------------------------
+!       namooo Offline obs_oper namelist
+!----------------------------------------------------------------------
+!   ooo_files    specifies the files containing the model counterpart
+!   nn_ooo_idx   specifies the time_counter index within the model file
+&namooo
+   ooo_files = "foo.nc"
+   nn_ooo_idx = 2
+/
+\end{forlines}
+
+\subsubsection{Multiple fields per run}
+
+Model field iteration is controlled via \textbf{nn\_ooo\_freq} which specifies
+the number of model steps at which the next field gets read. For example, if
+12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours.
+
+\begin{forlines}
+!----------------------------------------------------------------------
+!       namooo Offline obs_oper namelist
+!----------------------------------------------------------------------
+!   ooo_files    specifies the files containing the model counterpart
+!   nn_ooo_idx   specifies the time_counter index within the model file
+!   nn_ooo_freq  specifies number of time steps between read operations
+&namooo
+   ooo_files = "foo.nc" "foo.nc"
+   nn_ooo_idx = 1 2
+   nn_ooo_freq = 144
+/
+\end{forlines}
+
+The above namelist will result in feedback files whose first 12 hours contain
+the first field of foo.nc and the second 12 hours contain the second field.
+
+%\begin{framed}
+\textbf{Note} Missing files can be denoted as "nofile".
+%\end{framed}
+
+It is easy to see how a collection of fields taken fron a number of files 
+at different indices can be combined at a particular frequency in time to 
+generate a pseudo model evolution. As long as all that is needed is a single
+model counterpart at a regular interval then namooo is all that needs to
+be edited. However, a far more interesting approach can be taken in which
+multiple forecasts, analyses, persisted analyses and climatologies are
+considered against the same set of observations. For this a slightly more
+complicated approach is needed. It is referred to as \emph{Class 4} since
+it is the fourth metric defined by the GODAE intercomparison project.
+
+%--------------------------------------------------------------------------------------------------------
+% Class 4 file section
+%--------------------------------------------------------------------------------------------------------
+\subsubsection{Multiple model counterparts per observation a.k.a Class 4}
+
+A generalisation of feedback files to allow multiple model components per observation. For a single
+observation, as well as previous forecasts verifying at the same time there are also analyses, persisted
+analyses and climatologies. 
+
+
+The above namelist performs two basic functions. It organises the fields
+given in \textbf{namooo} into groups so that observations can be matched
+up multiple times. It also controls the metadata and the output variable
+of the class 4 file when a write routine is called.
+
+%\begin{framed}
+\textbf{Note: ln\_cl4} must be set to \forcode{.true.} in \textbf{namobs} 
+to use class 4 outputs.
+%\end{framed}
+
+\subsubsection{Class 4 naming convention}
+
+The standard class 4 file naming convention is as follows.
+
+\noindent
+\linebreak
+\textbf{\$\{prefix\}\_\$\{yyyymmdd\}\_\$\{sys\}\_\$\{cfg\}\_\$\{vn\}\_\$\{kind\}\_\$\{nproc\}}.nc
+
+\noindent
+\linebreak
+Much of the namelist is devoted to specifying this convention. The
+following namelist settings control the elements of the output
+file names. Each should be specified as a single string of character data.
+
+\begin{description}
+\item[cl4\_prefix]
+Prefix for class 4 files e.g. class4
+\item[cl4\_date]
+YYYYMMDD validity date
+\item[cl4\_sys]
+The name of the class 4 model system e.g. FOAM
+\item[cl4\_cfg]
+The name of the class 4 model configuration e.g. orca025
+\item[cl4\_vn]
+The name of the class 4 model version e.g. 12.0
+\end{description}
+
+\noindent
+The kind is specified by the observation type internally to the obs oper. The processor
+number is specified internally in NEMO. 
+
+\subsubsection{Class 4 file global attributes}
+
+Global attributes necessary to fulfill the class 4 file definition. These
+are also useful pieces of information when collaborating with external
+partners.
+
+\begin{description}
+\item[cl4\_contact]
+Contact email for class 4 files.
+\item[cl4\_inst]
+The name of the producers institution.
+\item[cl4\_cfg]
+The name of the class 4 model configuration e.g. orca025
+\item[cl4\_vn]
+The name of the class 4 model version e.g. 12.0
+\end{description}
+
+\noindent
+The obs\_type,
+creation date and validity time are specified internally to the obs oper.
+
+\subsubsection{Class 4 model counterpart configuration}
+
+As seen previously it is possible to perform a single sweep of the
+obs oper and specify a collection of model fields equally spaced 
+along that sweep. In the class 4 case the single sweep is replaced
+with multiple sweeps and a certain ammount of book keeping is
+needed to ensure each model counterpart makes its way to the 
+correct piece of memory in the output files.
+
+\noindent
+\linebreak
+In terms of book keeping, the offline obs oper needs to know how many
+full sweeps need to be performed. This is specified via the 
+\textbf{cl4\_match\_len} variable and is the total number of model
+counterparts per observation. For example, a 3 forecasts plus 3 persistence
+fields plus an analysis field would be 7 counterparts per observation.
+
+\begin{forlines}
+   cl4_match_len = 7
+\end{forlines}
+
+Then to correctly allocate a class 4 file the forecast axis must be defined. This
+is controlled via \textbf{cl4\_fcst\_len}, which in out above example would be 3.
+
+\begin{forlines}
+   cl4_fcst_len = 3
+\end{forlines}
+
+Then for each model field it is necessary to designate what class 4 variable and
+index along the forecast dimension the model counterpart should be stored in the
+output file. As well as a value for that lead time in hours, this will be useful
+when interpreting the data afterwards. 
+
+\begin{forlines}
+   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
+              "persistence" "best_estimate"
+   cl4_fcst_idx = 1 2 3 1 2 3 1
+   cl4_leadtime = 12 36 60 
+\end{forlines}
+
+In terms of files and indices of fields inside each file the class 4 approach
+makes use of the \textbf{namooo} namelist. If our fields are in separate files
+with a single field per file our example inputs will be specified.
+
+\begin{forlines}
+   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
+   nn_ooo_idx = 1 1 1 1 1 1 1
+\end{forlines}
+
+When we combine all of the naming conventions, global attributes and i/o instructions
+the class 4 namelist becomes.
+
+\begin{forlines}
+!----------------------------------------------------------------------
+!       namooo Offline obs_oper namelist
+!----------------------------------------------------------------------
+!   ooo_files    specifies the files containing the model counterpart
+!   nn_ooo_idx   specifies the time_counter index within the model file
+!   nn_ooo_freq  specifies number of time steps between read operations
+&namooo
+   ooo_files = "F.1.nc" "F.2.nc" "F.3.nc" "P.1.nc" "P.2.nc" "P.3.nc" "A.1.nc"
+   nn_ooo_idx = 1 1 1 1 1 1 1
+/
+!----------------------------------------------------------------------
+!       namcl4 Offline obs_oper class 4 namelist
+!----------------------------------------------------------------------
+!
+!  Naming convention
+!  -----------------
+!  cl4_prefix    specifies the output file prefix
+!  cl4_date      specifies the output file validity date
+!  cl4_sys       specifies the model counterpart system
+!  cl4_cfg       specifies the model counterpart configuration
+!  cl4_vn        specifies the model counterpart version
+!  cl4_inst      specifies the model counterpart institute
+!  cl4_contact   specifies the file producers contact details
+!
+!  I/O specification
+!  -----------------
+!  cl4_vars      specifies the names of the output file netcdf variable
+!  cl4_fcst_idx  specifies output file forecast index
+!  cl4_fcst_len  specifies forecast axis length
+!  cl4_match_len specifies number of unique matches per observation
+!  cl4_leadtime  specifies the forecast axis lead time 
+!
+&namcl4
+   cl4_match_len = 7
+   cl4_fcst_len = 3
+   cl4_fcst_idx = 1 2 3 1 2 3 1
+   cl4_vars = "forecast" "forecast" "forecast" "persistence" "persistence"
+              "persistence" "best_estimate"
+   cl4_leadtime = 12 36 60
+   cl4_prefix = "class4"
+   cl4_date = "20130101"
+   cl4_vn = "12.0"
+   cl4_sys = "FOAM"
+   cl4_cfg = "AMM7"
+   cl4_contact = "example@example.com"
+   cl4_inst = "UK Met Office"
+/
+\end{forlines}
+
+\subsubsection{Climatology interpolation}
+
+The climatological counterpart is generated at the start of the run by restarting 
+the model from climatology through appropriate use of \textbf{namtsd}. To override
+the offline observation operator read routine and to take advantage of the restart
+settings, specify the first entry in \textbf{cl4\_vars} as "climatology". This will then
+pipe the restart from climatology into the output class 4 file. As in every other
+class 4 matchup the input file, input index and output index must be specified.
+These can be replaced with dummy data since they are not used but they must be
+present to cycle through the matchups correctly. 
+
+\subsection{Advanced usage}
+
+In certain cases it may be desirable to include both multiple model fields per
+observation window with multiple match ups per observation. This can be achieved
+by specifying \textbf{nn\_ooo\_freq} as well as the class 4 settings. Care must
+be taken in generating the ooo\_files list such that the files are arranged into
+consecutive blocks of single match ups. For example, 2 forecast fields 
+of 12 hourly data would result in 4 separate read operations but only 2 write
+operations, 1 per forecast.
+
+\begin{forlines}
+   ooo_files = "F1.nc" "F1.nc" "F2.nc" "F2.nc"
+...
+   cl4_fcst_idx = 1 2
+\end{forlines}
+
+The above notation reveals the internal split between match up iterators and file
+iterators. This technique has not been used before so experimentation is needed
+before results can be trusted.
+
+
+
+
+\newpage
+
+\section{Observation utilities}
+\label{sec:OBS_obsutils}
+
+Some tools for viewing and processing of observation and feedback files are provided in the
+NEMO repository for convenience. These include OBSTOOLS which are a collection of Fortran
+programs which are helpful to deal with feedback files. They do such tasks as observation file
+conversion, printing of file contents, some basic statistical analysis of feedback files. The
+other tool is an IDL program called dataplot which uses a graphical interface to visualise
+observations and feedback files. OBSTOOLS and dataplot are described in more detail below.  
+
+\subsection{Obstools}
+
+A series of Fortran utilities is provided with NEMO called OBSTOOLS. This are helpful in
+handling observation files and the feedback file output from the NEMO observation operator.
+The utilities are as follows
+
+\subsubsection{c4comb}
+
+The program c4comb combines multiple class 4 files produced by individual processors in an
+MPI run of NEMO offline obs\_oper into a single class 4 file. The program is called in the following way:
+
+
+\footnotesize
+\begin{cmds}
+c4comb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+
+\subsubsection{corio2fb}
+
+The program corio2fb converts profile observation files from the Coriolis format to the
+standard feedback format. The program is called in the following way:
+
+\footnotesize
+\begin{cmds}
+corio2fb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+
+\subsubsection{enact2fb}
+
+The program enact2fb converts profile observation files from the ENACT format to the standard
+feedback format. The program is called in the following way:
+
+\footnotesize
+\begin{cmds}
+enact2fb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+
+\subsubsection{fbcomb}
+
+The program fbcomb combines multiple feedback files produced by individual processors in an
+MPI run of NEMO into a single feedback file. The program is called in the following way:
+
+\footnotesize
+\begin{cmds}
+fbcomb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+
+\subsubsection{fbmatchup}
+
+The program fbmatchup will match observations from two feedback files. The program is called
+in the following way:
+
+\footnotesize
+\begin{cmds}
+fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ...
+\end{cmds}
+
+\subsubsection{fbprint}
+
+The program fbprint will print the contents of a feedback file or files to standard output.
+Selected information can be output using optional arguments. The program is called in the
+following way:
+
+\footnotesize
+\begin{cmds}
+fbprint.exe [options] inputfile
+
+options:
+     -b            shorter output
+     -q            Select observations based on QC flags
+     -Q            Select observations based on QC flags
+     -B            Select observations based on QC flags
+     -u            unsorted
+     -s ID         select station ID  
+     -t TYPE       select observation type
+     -v NUM1-NUM2  select variable range to print by number 
+                      (default all)
+     -a NUM1-NUM2  select additional variable range to print by number 
+                      (default all)
+     -e NUM1-NUM2  select extra variable range to print by number 
+                      (default all)
+     -d            output date range
+     -D            print depths
+     -z            use zipped files
+\end{cmds}
+
+\subsubsection{fbsel}
+
+The program fbsel will select or subsample observations. The program is called in the
+following way:
+
+\footnotesize
+\begin{cmds}
+fbsel.exe <input filename> <output filename>
+\end{cmds}
+
+\subsubsection{fbstat}
+
+The program fbstat will output summary statistics in different global areas into a number of
+files. The program is called in the following way:
+
+\footnotesize
+\begin{cmds}
+fbstat.exe [-nmlev] <filenames>
+\end{cmds}
+
+\subsubsection{fbthin}
+
+The program fbthin will thin the data to 1 degree resolution. The code could easily be
+modified to thin to a different resolution. The program is called in the following way:
+
+\footnotesize
+\begin{cmds}
+fbthin.exe inputfile outputfile
+\end{cmds}
+
+\subsubsection{sla2fb}
+
+The program sla2fb will convert an AVISO SLA format file to feedback format. The program is
+called in the following way:
+
+\footnotesize
+\begin{cmds}
+sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ...
+
+Option:
+     -s            Select altimeter data_source
+\end{cmds}
+
+\subsubsection{vel2fb}
+
+The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format. The program
+is called in the following way:
+
+\footnotesize
+\begin{cmds}
+vel2fb.exe outputfile inputfile1 inputfile2 ...
+\end{cmds}
+
+\subsection{Building the obstools}
+
+To build the obstools use in the tools directory use ./maketools -n OBSTOOLS -m [ARCH].
+
+\subsection{Dataplot}
+
+An IDL program called dataplot is included which uses a graphical interface to visualise
+observations and feedback files. It is possible to zoom in, plot individual profiles and
+calculate some basic statistics. To plot some data run IDL and then:
+\footnotesize
+\begin{minted}{idl}
+IDL> dataplot, "filename"
+\end{minted}
+
+To read multiple files into dataplot, for example multiple feedback files from different
+processors or from different days, the easiest method is to use the spawn command to generate
+a list of files which can then be passed to dataplot.
+\footnotesize
+\begin{minted}{idl}
+IDL> spawn, 'ls profb*.nc', files
+IDL> dataplot, files
+\end{minted}
+
+\autoref{fig:obsdataplotmain} shows the main window which is launched when dataplot starts.
+This is split into three parts. At the top there is a menu bar which contains a variety of
+drop down menus. Areas - zooms into prespecified regions; plot - plots the data as a
+timeseries or a T-S diagram if appropriate; Find - allows data to be searched; Config - sets
+various configuration options.
+
+The middle part is a plot of the geographical location of the observations. This will plot the
+observation value, the model background value or observation minus background value depending
+on the option selected in the radio button at the bottom of the window. The plotting colour
+range can be changed by clicking on the colour bar. The title of the plot gives some basic
+information about the date range and depth range shown, the extreme values, and the mean and
+rms values. It is possible to zoom in using a drag-box. You may also zoom in or out using the
+mouse wheel.
+
+The bottom part of the window controls what is visible in the plot above. There are two bars
+which select the level range plotted (for profile data). The other bars below select the date
+range shown. The bottom of the figure allows the option to plot the mean, root mean square,
+standard deviation or mean square values. As mentioned above you can choose to plot the
+observation value, the model background value or observation minus background value. The next
+group of radio buttons selects the map projection. This can either be regular latitude
+longitude grid, or north or south polar stereographic. The next group of radio buttons will
+plot bad observations, switch to salinity and plot density for profile observations. The
+rightmost group of buttons will print the plot window as a postscript, save it as png, or exit
+from dataplot.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}     \begin{center}
+%\includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_main}
+\includegraphics[width=9cm,angle=-90.]{Fig_OBS_dataplot_main}
+\caption{      \protect\label{fig:obsdataplotmain}
+Main window of dataplot.}
+\end{center}     \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+If a profile point is clicked with the mouse button a plot of the observation and background
+values as a function of depth (\autoref{fig:obsdataplotprofile}).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}     \begin{center}
+%\includegraphics[width=10cm,height=12cm,angle=-90.]{Fig_OBS_dataplot_prof}
+\includegraphics[width=7cm,angle=-90.]{Fig_OBS_dataplot_prof}
+\caption{      \protect\label{fig:obsdataplotprofile}
+Profile plot from dataplot produced by right clicking on a point in the main window.}
+\end{center}     \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_SBC.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_SBC.tex	(revision 10321)
@@ -0,0 +1,1353 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter —— Surface Boundary Condition (SBC, ISF, ICB) 
+% ================================================================
+\chapter{Surface Boundary Condition (SBC, ISF, ICB) }
+\label{chap:SBC}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+%---------------------------------------namsbc--------------------------------------------------
+
+\nlst{namsbc}
+%--------------------------------------------------------------------------------------------------------------
+$\ $\newline    % force a new ligne
+
+The ocean needs six fields as surface boundary condition:
+\begin{itemize}
+	\item the two components of the surface ocean stress $\left( {\tau _u \;,\;\tau _v} \right)$
+	\item the incoming solar and non solar heat fluxes $\left( {Q_{ns} \;,\;Q_{sr} } \right)$
+	\item the surface freshwater budget $\left( {\textit{emp}} \right)$
+	\item the surface salt flux associated with freezing/melting of seawater $\left( {\textit{sfx}} \right)$
+\end{itemize}
+plus an optional field:
+\begin{itemize}
+	\item the atmospheric pressure at the ocean surface $\left( p_a \right)$
+\end{itemize}
+
+Five different ways to provide the first six fields to the ocean are available which 
+are controlled by namelist \ngn{namsbc} variables: an analytical formulation (\np{ln\_ana}\forcode{ = .true.}), 
+a flux formulation (\np{ln\_flx}\forcode{ = .true.}), a bulk formulae formulation (CORE 
+(\np{ln\_blk\_core}\forcode{ = .true.}), CLIO (\np{ln\_blk\_clio}\forcode{ = .true.}) or MFS
+\footnote { Note that MFS bulk formulae compute fluxes only for the ocean component}
+(\np{ln\_blk\_mfs}\forcode{ = .true.}) bulk formulae) and a coupled or mixed forced/coupled formulation 
+(exchanges with a atmospheric model via the OASIS coupler) (\np{ln\_cpl} or \np{ln\_mixcpl}\forcode{ = .true.}). 
+When used ($i.e.$ \np{ln\_apr\_dyn}\forcode{ = .true.}), the atmospheric pressure forces both ocean and ice dynamics.
+
+The frequency at which the forcing fields have to be updated is given by the \np{nn\_fsbc} namelist parameter. 
+When the fields are supplied from data files (flux and bulk formulations), the input fields 
+need not be supplied on the model grid. Instead a file of coordinates and weights can 
+be supplied which maps the data from the supplied grid to the model points 
+(so called "Interpolation on the Fly", see \autoref{subsec:SBC_iof}).
+If the Interpolation on the Fly option is used, input data belonging to land points (in the native grid),
+can be masked to avoid spurious results in proximity of the coasts  as large sea-land gradients characterize
+most of the atmospheric variables.
+
+In addition, the resulting fields can be further modified using several namelist options. 
+These options control 
+\begin{itemize}
+\item the rotation of vector components supplied relative to an east-north 
+coordinate system onto the local grid directions in the model ; 
+\item the addition of a surface restoring term to observed SST and/or SSS (\np{ln\_ssr}\forcode{ = .true.}) ; 
+\item the modification of fluxes below ice-covered areas (using observed ice-cover or a sea-ice model) (\np{nn\_ice}\forcode{ = 0..3}) ; 
+\item the addition of river runoffs as surface freshwater fluxes or lateral inflow (\np{ln\_rnf}\forcode{ = .true.}) ; 
+\item the addition of isf melting as lateral inflow (parameterisation) or as fluxes applied at the land-ice ocean interface (\np{ln\_isf}) ; 
+\item the addition of a freshwater flux adjustment in order to avoid a mean sea-level drift (\np{nn\_fwb}\forcode{ = 0..2}) ; 
+\item the transformation of the solar radiation (if provided as daily mean) into a diurnal cycle (\np{ln\_dm2dc}\forcode{ = .true.}) ; 
+and a neutral drag coefficient can be read from an external wave model (\np{ln\_cdgw}\forcode{ = .true.}). 
+\end{itemize}
+The latter option is possible only in case core or mfs bulk formulas are selected.
+
+In this chapter, we first discuss where the surface boundary condition appears in the
+model equations. Then we present the five ways of providing the surface boundary condition, 
+followed by the description of the atmospheric pressure and the river runoff. 
+Next the scheme for interpolation on the fly is described.
+Finally, the different options that further modify the fluxes applied to the ocean are discussed.
+One of these is modification by icebergs (see \autoref{sec:ICB_icebergs}), which act as drifting sources of fresh water.
+Another example of modification is that due to the ice shelf melting/freezing (see \autoref{sec:SBC_isf}), 
+which provides additional sources of fresh water.
+
+
+% ================================================================
+% Surface boundary condition for the ocean
+% ================================================================
+\section{Surface boundary condition for the ocean}
+\label{sec:SBC_general}
+
+The surface ocean stress is the stress exerted by the wind and the sea-ice 
+on the ocean. It is applied in \mdl{dynzdf} module as a surface boundary condition of the 
+computation of the momentum vertical mixing trend (see \autoref{eq:dynzdf_sbc} in \autoref{sec:DYN_zdf}).
+As such, it has to be provided as a 2D vector interpolated 
+onto the horizontal velocity ocean mesh, $i.e.$ resolved onto the model 
+(\textbf{i},\textbf{j}) direction at $u$- and $v$-points.
+
+The surface heat flux is decomposed into two parts, a non solar and a solar heat 
+flux, $Q_{ns}$ and $Q_{sr}$, respectively. The former is the non penetrative part 
+of the heat flux ($i.e.$ the sum of sensible, latent and long wave heat fluxes 
+plus the heat content of the mass exchange with the atmosphere and sea-ice). 
+It is applied in \mdl{trasbc} module as a surface boundary condition trend of 
+the first level temperature time evolution equation (see \autoref{eq:tra_sbc} 
+and \autoref{eq:tra_sbc_lin} in \autoref{subsec:TRA_sbc}). 
+The latter is the penetrative part of the heat flux. It is applied as a 3D 
+trends of the temperature equation (\mdl{traqsr} module) when \np{ln\_traqsr}\forcode{ = .true.}.
+The way the light penetrates inside the water column is generally a sum of decreasing 
+exponentials (see \autoref{subsec:TRA_qsr}). 
+
+The surface freshwater budget is provided by the \textit{emp} field.
+It represents the mass flux exchanged with the atmosphere (evaporation minus precipitation) 
+and possibly with the sea-ice and ice shelves (freezing minus melting of ice). 
+It affects both the ocean in two different ways: 
+$(i)$   it changes the volume of the ocean and therefore appears in the sea surface height 
+equation as a volume flux, and 
+$(ii)$  it changes the surface temperature and salinity through the heat and salt contents 
+of the mass exchanged with the atmosphere, the sea-ice and the ice shelves. 
+
+
+%\colorbox{yellow}{Miss: }
+%
+%A extensive description of all namsbc namelist (parameter that have to be 
+%created!)
+%
+%Especially the \np{nn\_fsbc}, the \mdl{sbc\_oce} module (fluxes + mean sst sss ssu 
+%ssv) i.e. information required by flux computation or sea-ice
+%
+%\mdl{sbc\_oce} containt the definition in memory of the 7 fields (6+runoff), add 
+%a word on runoff: included in surface bc or add as lateral obc{\ldots}.
+%
+%Sbcmod manage the ``providing'' (fourniture) to the ocean the 7 fields
+%
+%Fluxes update only each nf{\_}sbc time step (namsbc) explain relation 
+%between nf{\_}sbc and nf{\_}ice, do we define nf{\_}blk??? ? only one 
+%nf{\_}sbc
+%
+%Explain here all the namlist namsbc variable{\ldots}.
+% 
+% explain : use or not of surface currents
+%
+%\colorbox{yellow}{End Miss }
+
+The ocean model provides, at each time step, to the surface module (\mdl{sbcmod}) 
+the surface currents, temperature and salinity.  
+These variables are averaged over \np{nn\_fsbc} time-step (\autoref{tab:ssm}), 
+and it is these averaged fields which are used to computes the surface fluxes 
+at a frequency of \np{nn\_fsbc} time-step.
+
+
+%-------------------------------------------------TABLE---------------------------------------------------
+\begin{table}[tb]   \begin{center}   \begin{tabular}{|l|l|l|l|}
+\hline
+Variable description					& Model variable	& Units	& point \\	\hline
+i-component of the surface current	& ssu\_m	& $m.s^{-1}$	& U \\	\hline
+j-component of the surface current	& ssv\_m	& $m.s^{-1}$	& V \\	\hline
+Sea surface temperature				& sst\_m	& \r{}$K$		& T \\	\hline
+Sea surface salinty					& sss\_m	& $psu$			& T \\	\hline
+\end{tabular}
+\caption{  \protect\label{tab:ssm}   
+Ocean variables provided by the ocean to the surface module (SBC). 
+The variable are averaged over nn{\_}fsbc time step, 
+$i.e.$ the frequency of computation of surface fluxes.}
+\end{center}   \end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+%\colorbox{yellow}{Penser a} mettre dans le restant l'info nn{\_}fsbc ET nn{\_}fsbc*rdt de sorte de reinitialiser la moyenne si on change la frequence ou le pdt
+
+
+% ================================================================
+%       Input Data 
+% ================================================================
+\section{Input data generic interface}
+\label{sec:SBC_input}
+
+A generic interface has been introduced to manage the way input data (2D or 3D fields, 
+like surface forcing or ocean T and S) are specify in \NEMO. This task is archieved by \mdl{fldread}. 
+The module was design with four main objectives in mind: 
+\begin{enumerate}  
+\item optionally provide a time interpolation of the input data at model time-step, 
+whatever their input frequency is, and according to the different calendars available in the model.
+\item optionally provide an on-the-fly space interpolation from the native input data grid to the model grid.
+\item make the run duration independent from the period cover by the input files.
+\item provide a simple user interface and a rather simple developer interface by limiting the 
+ number of prerequisite information. 
+\end{enumerate}  
+
+As a results the user have only to fill in for each variable a structure in the namelist file 
+to defined the input data file and variable names, the frequency of the data (in hours or months), 
+whether its is climatological data or not, the period covered by the input file (one year, month, week or day), 
+and three additional parameters for on-the-fly interpolation. When adding a new input variable, 
+the developer has to add the associated structure in the namelist, read this information 
+by mirroring the namelist read in \rou{sbc\_blk\_init} for example, and simply call \rou{fld\_read} 
+to obtain the desired input field at the model time-step and grid points.
+
+The only constraints are that the input file is a NetCDF file, the file name follows a nomenclature 
+(see \autoref{subsec:SBC_fldread}), the period it cover is one year, month, week or day, and, if on-the-fly 
+interpolation is used, a file of weights must be supplied (see \autoref{subsec:SBC_iof}).
+
+Note that when an input data is archived on a disc which is accessible directly 
+from the workspace where the code is executed, then the use can set the \np{cn\_dir} 
+to the pathway leading to the data. By default, the data are assumed to have been 
+copied so that cn\_dir='./'.
+
+% -------------------------------------------------------------------------------------------------------------
+% Input Data specification (\mdl{fldread})
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Input data specification (\protect\mdl{fldread})}
+\label{subsec:SBC_fldread}
+
+The structure associated with an input variable contains the following information:
+\begin{forlines}
+!  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask ! 
+!             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
+\end{forlines}
+where 
+\begin{description}  
+\item[File name]: the stem name of the NetCDF file to be open. 
+This stem will be completed automatically by the model, with the addition of a '.nc' at its end 
+and by date information and possibly a prefix (when using AGRIF). 
+Tab.\autoref{tab:fldread} provides the resulting file name in all possible cases according to whether 
+it is a climatological file or not, and to the open/close frequency (see below for definition). 
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp] 
+\begin{center}
+\begin{tabular}{|l|c|c|c|}
+\hline
+                         & daily or weekLLL	        & monthly                   &   yearly          \\   \hline
+\np{clim}\forcode{ = .false.}	& fn\_yYYYYmMMdDD.nc  &   fn\_yYYYYmMM.nc   &   fn\_yYYYY.nc  \\   \hline
+\np{clim}\forcode{ = .true.}	 	   & not possible 	              &  fn\_m??.nc             &   fn                \\   \hline
+\end{tabular}
+\end{center}
+\caption{ \protect\label{tab:fldread}   naming nomenclature for climatological or interannual input file, 
+as a function of the Open/close frequency. The stem name is assumed to be 'fn'. 
+For weekly files, the 'LLL' corresponds to the first three letters of the first day of the week ($i.e.$ 'sun','sat','fri','thu','wed','tue','mon'). The 'YYYY', 'MM' and 'DD' should be replaced by the 
+actual year/month/day, always coded with 4 or 2 digits. Note that (1) in mpp, if the file is split 
+over each subdomain, the suffix '.nc' is replaced by '\_PPPP.nc', where 'PPPP' is the 
+process number coded with 4 digits; (2) when using AGRIF, the prefix
+'\_N' is added to files, 
+where 'N'  is the child grid number.}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+  
+
+\item[Record frequency]: the frequency of the records contained in the input file. 
+Its unit is in hours if it is positive (for example 24 for daily forcing) or in months if negative 
+(for example -1 for monthly forcing or -12 for annual forcing). 
+Note that this frequency must really be an integer and not a real. 
+On some computers, seting it to '24.' can be interpreted as 240!
+
+\item[Variable name]: the name of the variable to be read in the input NetCDF file.
+
+\item[Time interpolation]: a logical to activate, or not, the time interpolation. If set to 'false', 
+the forcing will have a steplike shape remaining constant during each forcing period. 
+For example, when using a daily forcing without time interpolation, the forcing remaining 
+constant from 00h00'00'' to 23h59'59". If set to 'true', the forcing will have a broken line shape. 
+Records are assumed to be dated the middle of the forcing period. 
+For example, when using a daily forcing with time interpolation, linear interpolation will 
+be performed between mid-day of two consecutive days. 
+
+\item[Climatological forcing]: a logical to specify if a input file contains climatological forcing 
+which can be cycle in time, or an interannual forcing which will requires additional files 
+if the period covered by the simulation exceed the one of the file. See the above the file 
+naming strategy which impacts the expected name of the file to be opened. 
+
+\item[Open/close frequency]: the frequency at which forcing files must be opened/closed. 
+Four cases are coded: 'daily', 'weekLLL' (with 'LLL' the first 3 letters of the first day of the week), 
+'monthly' and 'yearly' which means the forcing files will contain data for one day, one week, 
+one month or one year. Files are assumed to contain data from the beginning of the open/close period. 
+For example, the first record of a yearly file containing daily data is Jan 1st even if the experiment 
+is not starting at the beginning of the year. 
+
+\item[Others]: 'weights filename', 'pairing rotation' and 'land/sea mask' are associted with on-the-fly interpolation 
+which is described in \autoref{subsec:SBC_iof}.
+
+\end{description}
+
+Additional remarks:\\
+(1) The time interpolation is a simple linear interpolation between two consecutive records of 
+the input data. The only tricky point is therefore to specify the date at which we need to do 
+the interpolation and the date of the records read in the input files. 
+Following \citet{Leclair_Madec_OM09}, the date of a time step is set at the middle of the 
+time step. For example, for an experiment starting at 0h00'00" with a one hour time-step, 
+a time interpolation will be performed at the following time: 0h30'00", 1h30'00", 2h30'00", etc.
+However, for forcing data related to the surface module, values are not needed at every 
+time-step but at every \np{nn\_fsbc} time-step. For example with \np{nn\_fsbc}\forcode{ = 3}, 
+the surface module will be called at time-steps 1, 4, 7, etc. The date used for the time interpolation 
+is thus redefined to be at the middle of \np{nn\_fsbc} time-step period. In the previous example, 
+this leads to: 1h30'00", 4h30'00", 7h30'00", etc. \\ 
+(2) For code readablility and maintenance issues, we don't take into account the NetCDF input file 
+calendar. The calendar associated with the forcing field is build according to the information 
+provided by user in the record frequency, the open/close frequency and the type of temporal interpolation. 
+For example, the first record of a yearly file containing daily data that will be interpolated in time 
+is assumed to be start Jan 1st at 12h00'00" and end Dec 31st at 12h00'00". \\
+(3) If a time interpolation is requested, the code will pick up the needed data in the previous (next) file 
+when interpolating data with the first (last) record of the open/close period. 
+For example, if the input file specifications are ''yearly, containing daily data to be interpolated in time'', 
+the values given by the code between 00h00'00" and 11h59'59" on Jan 1st will be interpolated values 
+between Dec 31st 12h00'00" and Jan 1st 12h00'00". If the forcing is climatological, Dec and Jan will 
+be keep-up from the same year. However, if the forcing is not climatological, at the end of the 
+open/close period the code will automatically close the current file and open the next one. 
+Note that, if the experiment is starting (ending) at the beginning (end) of an open/close period 
+we do accept that the previous (next) file is not existing. In this case, the time interpolation 
+will be performed between two identical values. For example, when starting an experiment on 
+Jan 1st of year Y with yearly files and daily data to be interpolated, we do accept that the file 
+related to year Y-1 is not existing. The value of Jan 1st will be used as the missing one for 
+Dec 31st of year Y-1. If the file of year Y-1 exists, the code will read its last record. 
+Therefore, this file can contain only one record corresponding to Dec 31st, a useful feature for 
+user considering that it is too heavy to manipulate the complete file for year Y-1.
+
+
+% -------------------------------------------------------------------------------------------------------------
+% Interpolation on the Fly
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Interpolation on-the-fly}
+\label{subsec:SBC_iof}
+
+Interpolation on the Fly allows the user to supply input files required
+for the surface forcing on grids other than the model grid.
+To do this he or she must supply, in addition to the source data file,
+a file of weights to be used to interpolate from the data grid to the model grid.
+The original development of this code used the SCRIP package (freely available 
+\href{http://climate.lanl.gov/Software/SCRIP}{here} under a copyright agreement).
+In principle, any package can be used to generate the weights, but the
+variables in the input weights file must have the same names and meanings as
+assumed by the model.
+Two methods are currently available: bilinear and bicubic interpolation.
+Prior to the interpolation, providing a land/sea mask file, the user can decide to
+ remove land points from the input file and substitute the corresponding values 
+with the average of the 8 neighbouring points in the native external grid.
+ Only "sea points" are considered for the averaging. The land/sea mask file must 
+be provided in the structure associated with the input variable.
+ The netcdf land/sea mask variable name must be 'LSM' it must have the same 
+horizontal and vertical dimensions of the associated variable and should 
+be equal to 1 over land and 0 elsewhere.
+The procedure can be recursively applied setting nn\_lsm > 1 in namsbc namelist. 
+Note that nn\_lsm=0 forces the code to not apply the procedure even if a file for land/sea mask is supplied.
+
+\subsubsection{Bilinear interpolation}
+\label{subsec:SBC_iof_bilinear}
+
+The input weights file in this case has two sets of variables: src01, src02,
+src03, src04 and wgt01, wgt02, wgt03, wgt04.
+The "src" variables correspond to the point in the input grid to which the weight
+"wgt" is to be applied. Each src value is an integer corresponding to the index of a 
+point in the input grid when written as a one dimensional array.  For example, for an input grid
+of size 5x10, point (3,2) is referenced as point 8, since (2-1)*5+3=8.
+There are four of each variable because bilinear interpolation uses the four points defining
+the grid box containing the point to be interpolated.
+All of these arrays are on the model grid, so that values src01(i,j) and
+wgt01(i,j) are used to generate a value for point (i,j) in the model.
+
+Symbolically, the algorithm used is:
+
+\begin{equation}
+f_{m}(i,j) = f_{m}(i,j) + \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}
+\end{equation}
+where function idx() transforms a one dimensional index src(k) into a two dimensional index,
+and wgt(1) corresponds to variable "wgt01" for example.
+
+\subsubsection{Bicubic interpolation}
+\label{subsec:SBC_iof_bicubic}
+
+Again there are two sets of variables: "src" and "wgt".
+But in this case there are 16 of each.
+The symbolic algorithm used to calculate values on the model grid is now:
+
+\begin{equation*} \begin{split}
+f_{m}(i,j) =  f_{m}(i,j) +& \sum_{k=1}^{4} {wgt(k)f(idx(src(k)))}     
+              +   \sum_{k=5}^{8} {wgt(k)\left.\frac{\partial f}{\partial i}\right| _{idx(src(k))} }    \\
+              +& \sum_{k=9}^{12} {wgt(k)\left.\frac{\partial f}{\partial j}\right| _{idx(src(k))} }   
+              +   \sum_{k=13}^{16} {wgt(k)\left.\frac{\partial ^2 f}{\partial i \partial j}\right| _{idx(src(k))} }
+\end{split}
+\end{equation*}
+The gradients here are taken with respect to the horizontal indices and not distances since the spatial dependency has been absorbed into the weights.
+
+\subsubsection{Implementation}
+\label{subsec:SBC_iof_imp}
+
+To activate this option, a non-empty string should be supplied in the weights filename column 
+of the relevant namelist; if this is left as an empty string no action is taken.
+In the model, weights files are read in and stored in a structured type (WGT) in the fldread 
+module, as and when they are first required.
+This initialisation procedure determines whether the input data grid should be treated 
+as cyclical or not by inspecting a global attribute stored in the weights input file.
+This attribute must be called "ew\_wrap" and be of integer type.
+If it is negative, the input non-model grid is assumed not to be cyclic.
+If zero or greater, then the value represents the number of columns that overlap.
+$E.g.$ if the input grid has columns at longitudes 0, 1, 2, .... , 359, then ew\_wrap should be set to 0;
+if longitudes are 0.5, 2.5, .... , 358.5, 360.5, 362.5, ew\_wrap should be 2.
+If the model does not find attribute ew\_wrap, then a value of -999 is assumed.
+In this case the \rou{fld\_read} routine defaults ew\_wrap to value 0 and therefore the grid 
+is assumed to be cyclic with no overlapping columns.
+(In fact this only matters when bicubic interpolation is required.)
+Note that no testing is done to check the validity in the model, since there is no way 
+of knowing the name used for the longitude variable,
+so it is up to the user to make sure his or her data is correctly represented.
+
+Next the routine reads in the weights.
+Bicubic interpolation is assumed if it finds a variable with name "src05", otherwise 
+bilinear interpolation is used. The WGT structure includes dynamic arrays both for 
+the storage of the weights (on the model grid), and when required, for reading in 
+the variable to be interpolated (on the input data grid).
+The size of the input data array is determined by examining the values in the "src" 
+arrays to find the minimum and maximum i and j values required.
+Since bicubic interpolation requires the calculation of gradients at each point on the grid, 
+the corresponding arrays are dimensioned with a halo of width one grid point all the way around.
+When the array of points from the data file is adjacent to an edge of the data grid, 
+the halo is either a copy of the row/column next to it (non-cyclical case), or is a copy 
+of one from the first few columns on the opposite side of the grid (cyclical case).
+
+\subsubsection{Limitations}
+\label{subsec:SBC_iof_lim}
+
+\begin{enumerate}  
+\item  The case where input data grids are not logically rectangular has not been tested.
+\item  This code is not guaranteed to produce positive definite answers from positive definite inputs
+          when a bicubic interpolation method is used.
+\item  The cyclic condition is only applied on left and right columns, and not to top and bottom rows.
+\item  The gradients across the ends of a cyclical grid assume that the grid spacing between 
+          the two columns involved are consistent with the weights used.
+\item  Neither interpolation scheme is conservative. (There is a conservative scheme available 
+          in SCRIP, but this has not been implemented.)
+\end{enumerate}
+
+\subsubsection{Utilities}
+\label{subsec:SBC_iof_util}
+
+% to be completed
+A set of utilities to create a weights file for a rectilinear input grid is available 
+(see the directory NEMOGCM/TOOLS/WEIGHTS).
+
+% -------------------------------------------------------------------------------------------------------------
+% Standalone Surface Boundary Condition Scheme
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Standalone surface boundary condition scheme}
+\label{subsec:SAS_iof}
+
+%---------------------------------------namsbc_ana--------------------------------------------------
+
+\nlst{namsbc_sas}
+%--------------------------------------------------------------------------------------------------------------
+
+In some circumstances it may be useful to avoid calculating the 3D temperature, salinity and velocity fields 
+and simply read them in from a previous run or receive them from OASIS.  
+For example:
+
+\begin{itemize}
+\item  Multiple runs of the model are required in code development to see the effect of different algorithms in
+       the bulk formulae.
+\item  The effect of different parameter sets in the ice model is to be examined.
+\item  Development of sea-ice algorithms or parameterizations.
+\item  spinup of the iceberg floats
+\item  ocean/sea-ice simulation with both media running in parallel (\np{ln\_mixcpl}\forcode{ = .true.})
+\end{itemize}
+
+The StandAlone Surface scheme provides this utility.
+Its options are defined through the \ngn{namsbc\_sas} namelist variables.
+A new copy of the model has to be compiled with a configuration based on ORCA2\_SAS\_LIM.
+However no namelist parameters need be changed from the settings of the previous run (except perhaps nn{\_}date0)
+In this configuration, a few routines in the standard model are overriden by new versions.
+Routines replaced are:
+
+\begin{itemize}
+\item \mdl{nemogcm} : This routine initialises the rest of the model and repeatedly calls the stp time stepping routine (\mdl{step})
+       Since the ocean state is not calculated all associated initialisations have been removed.
+\item  \mdl{step} : The main time stepping routine now only needs to call the sbc routine (and a few utility functions).
+\item  \mdl{sbcmod} : This has been cut down and now only calculates surface forcing and the ice model required.  New surface modules
+       that can function when only the surface level of the ocean state is defined can also be added (e.g. icebergs).
+\item  \mdl{daymod} : No ocean restarts are read or written (though the ice model restarts are retained), so calls to restart functions
+       have been removed.  This also means that the calendar cannot be controlled by time in a restart file, so the user
+       must make sure that nn{\_}date0 in the model namelist is correct for his or her purposes.
+\item  \mdl{stpctl} : Since there is no free surface solver, references to it have been removed from \rou{stp\_ctl} module.
+\item  \mdl{diawri} : All 3D data have been removed from the output.  The surface temperature, salinity and velocity components (which
+       have been read in) are written along with relevant forcing and ice data.
+\end{itemize}
+
+One new routine has been added:
+
+\begin{itemize}
+\item  \mdl{sbcsas} : This module initialises the input files needed for reading temperature, salinity and velocity arrays at the surface.
+       These filenames are supplied in namelist namsbc{\_}sas.  Unfortunately because of limitations with the \mdl{iom} module,
+       the full 3D fields from the mean files have to be read in and interpolated in time, before using just the top level.
+       Since fldread is used to read in the data, Interpolation on the Fly may be used to change input data resolution.
+\end{itemize}
+
+
+% Missing the description of the 2 following variables:
+%   ln_3d_uve   = .true.    !  specify whether we are supplying a 3D u,v and e3 field
+%   ln_read_frq = .false.    !  specify whether we must read frq or not
+
+
+
+% ================================================================
+% Analytical formulation (sbcana module) 
+% ================================================================
+\section{Analytical formulation (\protect\mdl{sbcana})}
+\label{sec:SBC_ana}
+
+%---------------------------------------namsbc_ana--------------------------------------------------
+%
+%\nlst{namsbc_ana}
+%--------------------------------------------------------------------------------------------------------------
+
+The analytical formulation of the surface boundary condition is the default scheme.
+In this case, all the six fluxes needed by the ocean are assumed to 
+be uniform in space. They take constant values given in the namelist 
+\ngn{namsbc{\_}ana} by the variables \np{rn\_utau0}, \np{rn\_vtau0}, \np{rn\_qns0}, 
+\np{rn\_qsr0}, and \np{rn\_emp0} ($\textit{emp}=\textit{emp}_S$). The runoff is set to zero. 
+In addition, the wind is allowed to reach its nominal value within a given number 
+of time steps (\np{nn\_tau000}).
+
+If a user wants to apply a different analytical forcing, the \mdl{sbcana} 
+module can be modified to use another scheme. As an example, 
+the \mdl{sbc\_ana\_gyre} routine provides the analytical forcing for the 
+GYRE configuration (see GYRE configuration manual, in preparation).
+
+
+% ================================================================
+% Flux formulation 
+% ================================================================
+\section{Flux formulation (\protect\mdl{sbcflx})}
+\label{sec:SBC_flx}
+%------------------------------------------namsbc_flx----------------------------------------------------
+
+\nlst{namsbc_flx} 
+%-------------------------------------------------------------------------------------------------------------
+
+In the flux formulation (\np{ln\_flx}\forcode{ = .true.}), the surface boundary 
+condition fields are directly read from input files. The user has to define 
+in the namelist \ngn{namsbc{\_}flx} the name of the file, the name of the variable 
+read in the file, the time frequency at which it is given (in hours), and a logical 
+setting whether a time interpolation to the model time step is required 
+for this field. See \autoref{subsec:SBC_fldread} for a more detailed description of the parameters.
+
+Note that in general, a flux formulation is used in associated with a 
+restoring term to observed SST and/or SSS. See \autoref{subsec:SBC_ssr} for its 
+specification.
+
+
+% ================================================================
+% Bulk formulation
+% ================================================================
+\section[Bulk formulation {(\textit{sbcblk\{\_core,\_clio,\_mfs\}.F90})}]
+			{Bulk formulation {(\protect\mdl{sbcblk\_core}, \protect\mdl{sbcblk\_clio}, \protect\mdl{sbcblk\_mfs})}}
+\label{sec:SBC_blk}
+
+In the bulk formulation, the surface boundary condition fields are computed 
+using bulk formulae and atmospheric fields and ocean (and ice) variables. 
+
+The atmospheric fields used depend on the bulk formulae used. Three bulk formulations 
+are available : the CORE, the CLIO and the MFS bulk formulea. The choice is made by setting to true
+one of the following namelist variable : \np{ln\_core} ; \np{ln\_clio} or  \np{ln\_mfs}.
+
+Note : in forced mode, when a sea-ice model is used, a bulk formulation (CLIO or CORE) have to be used. 
+Therefore the two bulk (CLIO and CORE) formulea include the computation of the fluxes over both 
+an ocean and an ice surface. 
+
+% -------------------------------------------------------------------------------------------------------------
+%        CORE Bulk formulea
+% -------------------------------------------------------------------------------------------------------------
+\subsection{CORE formulea (\protect\mdl{sbcblk\_core}, \protect\np{ln\_core}\forcode{ = .true.})}
+\label{subsec:SBC_blk_core}
+%------------------------------------------namsbc_core----------------------------------------------------
+%
+%\nlst{namsbc_core}
+%-------------------------------------------------------------------------------------------------------------
+
+The CORE bulk formulae have been developed by \citet{Large_Yeager_Rep04}. 
+They have been designed to handle the CORE forcing, a mixture of NCEP 
+reanalysis and satellite data. They use an inertial dissipative method to compute 
+the turbulent transfer coefficients (momentum, sensible heat and evaporation) 
+from the 10 metre wind speed, air temperature and specific humidity.
+This \citet{Large_Yeager_Rep04} dataset is available through the 
+\href{http://nomads.gfdl.noaa.gov/nomads/forms/mom4/CORE.html}{GFDL web site}. 
+
+Note that substituting ERA40 to NCEP reanalysis fields 
+does not require changes in the bulk formulea themself. 
+This is the so-called DRAKKAR Forcing Set (DFS) \citep{Brodeau_al_OM09}. 
+
+Options are defined through the  \ngn{namsbc\_core} namelist variables.
+The required 8 input fields are:
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]   \label{tab:CORE}
+\begin{center}
+\begin{tabular}{|l|c|c|c|}
+\hline
+Variable desciption					& Model variable	& Units	 & point \\		\hline
+i-component of the 10m air velocity	& utau		& $m.s^{-1}$			& T  \\ 	\hline
+j-component of the 10m air velocity	& vtau		& $m.s^{-1}$			& T  \\	\hline
+10m air temperature					& tair		& \r{}$K$				& T 	\\	\hline
+Specific humidity					& humi		& \%					& T \\		\hline
+Incoming long wave radiation		& qlw		& $W.m^{-2}$			& T \\		\hline
+Incoming short wave radiation		& qsr		& $W.m^{-2}$			& T \\		\hline
+Total precipitation (liquid + solid)	& precip	& $Kg.m^{-2}.s^{-1}$	& T \\ 	\hline
+Solid precipitation					& snow		& $Kg.m^{-2}.s^{-1}$	& T \\	\hline
+\end{tabular}
+\end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+Note that the air velocity is provided at a tracer ocean point, not at a velocity ocean 
+point ($u$- and $v$-points). It is simpler and faster (less fields to be read), 
+but it is not the recommended method when the ocean grid size is the same 
+or larger than the one of the input atmospheric fields.
+
+The \np{sn\_wndi}, \np{sn\_wndj}, \np{sn\_qsr}, \np{sn\_qlw}, \np{sn\_tair}, \np{sn\_humi},
+\np{sn\_prec}, \np{sn\_snow}, \np{sn\_tdif} parameters describe the fields 
+and the way they have to be used (spatial and temporal interpolations). 
+
+\np{cn\_dir} is the directory of location of bulk files
+\np{ln\_taudif} is the flag to specify if we use Hight Frequency (HF) tau information (.true.) or not (.false.)
+\np{rn\_zqt}: is the height of humidity and temperature measurements (m)
+\np{rn\_zu}: is the height of wind measurements (m)
+
+Three multiplicative factors are availables : 
+\np{rn\_pfac} and \np{rn\_efac} allows to adjust (if necessary) the global freshwater budget 
+by increasing/reducing the precipitations (total and snow) and or evaporation, respectively.
+The third one,\np{rn\_vfac}, control to which extend the ice/ocean velocities are taken into account 
+in the calculation of surface wind stress. Its range should be between zero and one, 
+and it is recommended to set it to 0.
+
+% -------------------------------------------------------------------------------------------------------------
+%        CLIO Bulk formulea
+% -------------------------------------------------------------------------------------------------------------
+\subsection{CLIO formulea (\protect\mdl{sbcblk\_clio}, \protect\np{ln\_clio}\forcode{ = .true.})}
+\label{subsec:SBC_blk_clio}
+%------------------------------------------namsbc_clio----------------------------------------------------
+%
+%\nlst{namsbc_clio}
+%-------------------------------------------------------------------------------------------------------------
+
+The CLIO bulk formulae were developed several years ago for the 
+Louvain-la-neuve coupled ice-ocean model (CLIO, \cite{Goosse_al_JGR99}). 
+They are simpler bulk formulae. They assume the stress to be known and 
+compute the radiative fluxes from a climatological cloud cover. 
+
+Options are defined through the  \ngn{namsbc\_clio} namelist variables.
+The required 7 input fields are:
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]   \label{tab:CLIO}
+\begin{center}
+\begin{tabular}{|l|l|l|l|}
+\hline
+Variable desciption				& Model variable	& Units				& point \\	\hline
+i-component of the ocean stress		& utau			& $N.m^{-2}$			& U \\	\hline
+j-component of the ocean stress		& vtau			& $N.m^{-2}$			& V \\	\hline
+Wind speed module					& vatm			& $m.s^{-1}$			& T \\	\hline
+10m air temperature					& tair			& \r{}$K$				& T \\	\hline
+Specific humidity						& humi			& \%					& T \\	\hline
+Cloud cover							& 				& \%					& T \\	\hline
+Total precipitation (liquid + solid)	& precip		& $Kg.m^{-2}.s^{-1}$	& T \\	\hline
+Solid precipitation 					& snow			& $Kg.m^{-2}.s^{-1}$	& T \\	\hline
+\end{tabular}
+\end{center}
+\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+As for the flux formulation, information about the input data required by the 
+model is provided in the namsbc\_blk\_core or namsbc\_blk\_clio 
+namelist (see \autoref{subsec:SBC_fldread}). 
+
+% -------------------------------------------------------------------------------------------------------------
+%        MFS Bulk formulae
+% -------------------------------------------------------------------------------------------------------------
+\subsection{MFS formulea (\protect\mdl{sbcblk\_mfs}, \protect\np{ln\_mfs}\forcode{ = .true.})}
+\label{subsec:SBC_blk_mfs}
+%------------------------------------------namsbc_mfs----------------------------------------------------
+%
+%\nlst{namsbc_mfs}
+%----------------------------------------------------------------------------------------------------------
+
+The MFS (Mediterranean Forecasting System) bulk formulae have been developed by
+ \citet{Castellari_al_JMS1998}. 
+They have been designed to handle the ECMWF operational data and are currently 
+in use in the MFS operational system \citep{Tonani_al_OS08}, \citep{Oddo_al_OS09}.
+The wind stress computation uses a drag coefficient computed according to \citet{Hellerman_Rosenstein_JPO83}.
+The surface boundary condition for temperature involves the balance between surface solar radiation,
+net long-wave radiation, the latent and sensible heat fluxes.
+Solar radiation is dependent on cloud cover and is computed by means of
+an astronomical formula \citep{Reed_JPO77}. Albedo monthly values are from \citet{Payne_JAS72} 
+as means of the values at $40^{o}N$ and $30^{o}N$ for the Atlantic Ocean (hence the same latitudinal
+band of the Mediterranean Sea). The net long-wave radiation flux
+\citep{Bignami_al_JGR95} is a function of
+air temperature, sea-surface temperature, cloud cover and relative humidity.
+Sensible heat and latent heat fluxes are computed by classical
+bulk formulae parameterised according to \citet{Kondo1975}.
+Details on the bulk formulae used can be found in \citet{Maggiore_al_PCE98} and \citet{Castellari_al_JMS1998}.
+
+Options are defined through the  \ngn{namsbc\_mfs} namelist variables.
+The required 7 input fields must be provided on the model Grid-T and  are:
+\begin{itemize}
+\item          Zonal Component of the 10m wind ($ms^{-1}$)  (\np{sn\_windi})
+\item          Meridional Component of the 10m wind ($ms^{-1}$)  (\np{sn\_windj})
+\item          Total Claud Cover (\%)  (\np{sn\_clc})
+\item          2m Air Temperature ($K$) (\np{sn\_tair})
+\item          2m Dew Point Temperature ($K$)  (\np{sn\_rhm})
+\item          Total Precipitation ${Kg} m^{-2} s^{-1}$ (\np{sn\_prec})
+\item          Mean Sea Level Pressure (${Pa}$) (\np{sn\_msl})
+\end{itemize}
+% -------------------------------------------------------------------------------------------------------------
+% ================================================================
+% Coupled formulation
+% ================================================================
+\section{Coupled formulation (\protect\mdl{sbccpl})}
+\label{sec:SBC_cpl}
+%------------------------------------------namsbc_cpl----------------------------------------------------
+
+\nlst{namsbc_cpl} 
+%-------------------------------------------------------------------------------------------------------------
+
+In the coupled formulation of the surface boundary condition, the fluxes are 
+provided by the OASIS coupler at a frequency which is defined in the OASIS coupler, 
+while sea and ice surface temperature, ocean and ice albedo, and ocean currents 
+are sent to the atmospheric component.
+
+A generalised coupled interface has been developed. 
+It is currently interfaced with OASIS-3-MCT (\key{oasis3}). 
+It has been successfully used to interface \NEMO to most of the European atmospheric 
+GCM (ARPEGE, ECHAM, ECMWF, HadAM, HadGAM, LMDz), 
+as well as to \href{http://wrf-model.org/}{WRF} (Weather Research and Forecasting Model).
+
+Note that in addition to the setting of \np{ln\_cpl} to true, the \key{coupled} have to be defined. 
+The CPP key is mainly used in sea-ice to ensure that the atmospheric fluxes are 
+actually recieved by the ice-ocean system (no calculation of ice sublimation in coupled mode).
+When PISCES biogeochemical model (\key{top} and \key{pisces}) is also used in the coupled system, 
+the whole carbon cycle is computed by defining \key{cpl\_carbon\_cycle}. In this case, 
+CO$_2$ fluxes will be exchanged between the atmosphere and the ice-ocean system (and need to be activated in \ngn{namsbc{\_}cpl} ).
+
+The namelist above allows control of various aspects of the coupling fields (particularly for
+vectors) and now allows for any coupling fields to have multiple sea ice categories (as required by LIM3
+and CICE).  When indicating a multi-category coupling field in namsbc{\_}cpl the number of categories will be
+determined by the number used in the sea ice model.  In some limited cases it may be possible to specify 
+single category coupling fields even when the sea ice model is running with multiple categories - in this
+case the user should examine the code to be sure the assumptions made are satisfactory.  In cases where
+this is definitely not possible the model should abort with an error message.  The new code has been tested using
+ECHAM with LIM2, and HadGAM3 with CICE but although it will compile with \key{lim3} additional minor code changes
+may be required to run using LIM3.
+
+
+% ================================================================
+%        Atmospheric pressure
+% ================================================================
+\section{Atmospheric pressure (\protect\mdl{sbcapr})}
+\label{sec:SBC_apr}
+%------------------------------------------namsbc_apr----------------------------------------------------
+
+\nlst{namsbc_apr} 
+%-------------------------------------------------------------------------------------------------------------
+
+The optional atmospheric pressure can be used to force ocean and ice dynamics 
+(\np{ln\_apr\_dyn}\forcode{ = .true.}, \textit{\ngn{namsbc}} namelist ).
+The input atmospheric forcing defined via \np{sn\_apr} structure (\textit{namsbc\_apr} namelist) 
+can be interpolated in time to the model time step, and even in space when the 
+interpolation on-the-fly is used. When used to force the dynamics, the atmospheric 
+pressure is further transformed into an equivalent inverse barometer sea surface height, 
+$\eta_{ib}$, using:
+\begin{equation} \label{eq:SBC_ssh_ib}
+	\eta_{ib} = -  \frac{1}{g\,\rho_o}  \left( P_{atm} - P_o \right) 
+\end{equation}
+where $P_{atm}$ is the atmospheric pressure and $P_o$ a reference atmospheric pressure.
+A value of $101,000~N/m^2$ is used unless \np{ln\_ref\_apr} is set to true. In this case $P_o$ 
+is set to the value of $P_{atm}$ averaged over the ocean domain, $i.e.$ the mean value of 
+$\eta_{ib}$ is kept to zero at all time step.
+
+The gradient of $\eta_{ib}$ is added to the RHS of the ocean momentum equation 
+(see \mdl{dynspg} for the ocean). For sea-ice, the sea surface height, $\eta_m$, 
+which is provided to the sea ice model is set to $\eta - \eta_{ib}$ (see \mdl{sbcssr} module).
+$\eta_{ib}$ can be set in the output. This can simplify altimetry data and model comparison 
+as inverse barometer sea surface height is usually removed from these date prior to their distribution.
+
+When using time-splitting and BDY package for open boundaries conditions, the equivalent 
+inverse barometer sea surface height $\eta_{ib}$ can be added to BDY ssh data: 
+\np{ln\_apr\_obc}  might be set to true.
+
+% ================================================================
+%        Surface Tides Forcing
+% ================================================================
+\section{Surface tides (\protect\mdl{sbctide})}
+\label{sec:SBC_tide}
+
+%------------------------------------------nam_tide---------------------------------------
+
+\nlst{nam_tide}
+%-----------------------------------------------------------------------------------------
+
+The tidal forcing, generated by the gravity forces of the Earth-Moon and Earth-Sun sytems, is activated if \np{ln\_tide} and \np{ln\_tide\_pot} are both set to \np{.true.} in \ngn{nam\_tide}. This translates as an additional barotropic force in the momentum equations \ref{eq:PE_dyn} such that:
+\begin{equation}     \label{eq:PE_dyn_tides}
+\frac{\partial {\rm {\bf U}}_h }{\partial t}= ...
++g\nabla (\Pi_{eq} + \Pi_{sal}) 
+\end{equation} 
+where $\Pi_{eq}$ stands for the equilibrium tidal forcing and $\Pi_{sal}$ a self-attraction and loading term (SAL). 
+ 
+The equilibrium tidal forcing is expressed as a sum over the chosen constituents $l$ in \ngn{nam\_tide}. The constituents are defined such that \np{clname(1) = 'M2', clname(2)='S2', etc...}. For the three types of tidal frequencies it reads : \\
+Long period tides :
+\begin{equation}
+\Pi_{eq}(l)=A_{l}(1+k-h)(\frac{1}{2}-\frac{3}{2}sin^{2}\phi)cos(\omega_{l}t+V_{l})
+\end{equation}
+diurnal tides :
+\begin{equation}
+\Pi_{eq}(l)=A_{l}(1+k-h)(sin 2\phi)cos(\omega_{l}t+\lambda+V_{l})
+\end{equation}
+Semi-diurnal tides:
+\begin{equation}
+\Pi_{eq}(l)=A_{l}(1+k-h)(cos^{2}\phi)cos(\omega_{l}t+2\lambda+V_{l})
+\end{equation}
+Here $A_{l}$ is the amplitude, $\omega_{l}$ is the frequency, $\phi$ the latitude, $\lambda$ the longitude, $V_{0l}$ a phase shift with respect to Greenwich meridian and $t$ the time. The Love number factor $(1+k-h)$ is here taken as a constant (0.7).
+
+The SAL term should in principle be computed online as it depends on the model tidal prediction itself (see \citet{Arbic2004} for a discussion about the practical implementation of this term). Nevertheless, the complex calculations involved would make this computationally too expensive. Here, practical solutions are whether to read complex estimates $\Pi_{sal}(l)$ from an external model (\np{ln\_read\_load=.true.}) or use a ``scalar approximation'' (\np{ln\_scal\_load=.true.}). In the latter case, it reads:\\
+\begin{equation}
+\Pi_{sal} = \beta \eta
+\end{equation}
+where $\beta$ (\np{rn\_scal\_load}, $\approx0.09$) is a spatially constant scalar, often chosen to minimize tidal prediction errors. Setting both \np{ln\_read\_load} and \np{ln\_scal\_load} to false removes the SAL contribution.
+
+% ================================================================
+%        River runoffs
+% ================================================================
+\section{River runoffs (\protect\mdl{sbcrnf})}
+\label{sec:SBC_rnf}
+%------------------------------------------namsbc_rnf----------------------------------------------------
+
+\nlst{namsbc_rnf} 
+%-------------------------------------------------------------------------------------------------------------
+
+%River runoff generally enters the ocean at a nonzero depth rather than through the surface. 
+%Many models, however, have traditionally inserted river runoff to the top model cell.
+%This was the case in \NEMO prior to the version 3.3. The switch toward a input of runoff 
+%throughout a nonzero depth has been motivated by the numerical and physical problems 
+%that arise when the top grid cells are of the order of one meter. This situation is common in 
+%coastal modelling and becomes more and more often open ocean and climate modelling 
+%\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are
+%required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}.
+
+
+%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the 
+%\mdl{tra\_sbc} module.  We decided to separate them throughout the code, so that the variable 
+%\textit{emp} represented solely evaporation minus precipitation fluxes, and a new 2d variable 
+%rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with 
+%emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use 
+%emp or emps and the changes made are below:
+
+
+%Rachel:
+River runoff generally enters the ocean at a nonzero depth rather than through the surface.
+Many models, however, have traditionally inserted river runoff to the top model cell.
+This was the case in \NEMO prior to the version 3.3, and was combined with an option 
+to increase vertical mixing near the river mouth.
+
+However, with this method numerical and physical problems arise when the top grid cells are 
+of the order of one meter. This situation is common in coastal modelling and is becoming 
+more common in open ocean and climate modelling 
+\footnote{At least a top cells thickness of 1~meter and a 3 hours forcing frequency are
+required to properly represent the diurnal cycle \citep{Bernie_al_JC05}. see also \autoref{fig:SBC_dcy}.}.
+
+As such from V~3.3 onwards it is possible to add river runoff through a non-zero depth, and for the 
+temperature and salinity of the river to effect the surrounding ocean.
+The user is able to specify, in a NetCDF input file, the temperature and salinity of the river, along with the   
+depth (in metres) which the river should be added to.
+
+Namelist variables in \ngn{namsbc\_rnf}, \np{ln\_rnf\_depth}, \np{ln\_rnf\_sal} and \np{ln\_rnf\_temp} control whether 
+the river attributes (depth, salinity and temperature) are read in and used.  If these are set 
+as false the river is added to the surface box only, assumed to be fresh (0~psu), and/or 
+taken as surface temperature respectively.
+
+The runoff value and attributes are read in in sbcrnf.  
+For temperature -999 is taken as missing data and the river temperature is taken to be the 
+surface temperatue at the river point.
+For the depth parameter a value of -1 means the river is added to the surface box only, 
+and a value of -999 means the river is added through the entire water column. 
+After being read in the temperature and salinity variables are multiplied by the amount of runoff (converted into m/s) 
+to give the heat and salt content of the river runoff.
+After the user specified depth is read ini, the number of grid boxes this corresponds to is 
+calculated and stored in the variable \np{nz\_rnf}.
+The variable \textit{h\_dep} is then calculated to be the depth (in metres) of the bottom of the 
+lowest box the river water is being added to (i.e. the total depth that river water is being added to in the model).
+
+The mass/volume addition due to the river runoff is, at each relevant depth level, added to the horizontal divergence 
+(\textit{hdivn}) in the subroutine \rou{sbc\_rnf\_div} (called from \mdl{divcur}).
+This increases the diffusion term in the vicinity of the river, thereby simulating a momentum flux.
+The sea surface height is calculated using the sum of the horizontal divergence terms, and so the 
+river runoff indirectly forces an increase in sea surface height. 
+
+The \textit{hdivn} terms are used in the tracer advection modules to force vertical velocities.
+This causes a mass of water, equal to the amount of runoff, to be moved into the box above. 
+The heat and salt content of the river runoff is not included in this step, and so the tracer 
+concentrations are diluted as water of ocean temperature and salinity is moved upward out of the box 
+and replaced by the same volume of river water with no corresponding heat and salt addition.
+
+For the linear free surface case, at the surface box the tracer advection causes a flux of water 
+(of equal volume to the runoff) through the sea surface out of the domain, which causes a salt and heat flux out of the model.
+As such the volume of water does not change, but the water is diluted.
+
+For the non-linear free surface case (\key{vvl}), no flux is allowed through the surface.
+Instead in the surface box (as well as water moving up from the boxes below) a volume of runoff water 
+is added with no corresponding heat and salt addition and so as happens in the lower boxes there is a dilution effect.
+(The runoff addition to the top box along with the water being moved up through boxes below means the surface box has a large 
+increase in volume, whilst all other boxes remain the same size)
+
+In trasbc the addition of heat and salt due to the river runoff is added.
+This is done in the same way for both vvl and non-vvl.
+The temperature and salinity are increased through the specified depth according to the heat and salt content of the river. 
+
+In the non-linear free surface case (vvl), near the end of the time step the change in sea surface height is redistrubuted 
+through the grid boxes, so that the original ratios of grid box heights are restored.
+In doing this water is moved into boxes below, throughout the water column, so the large volume addition to the surface box is spread between all the grid boxes.
+
+It is also possible for runnoff to be specified as a negative value for modelling flow through straits, i.e. modelling the Baltic flow in and out of the North Sea.
+When the flow is out of the domain there is no change in temperature and salinity, regardless of the namelist options used, as the ocean water leaving the domain removes heat and salt (at the same concentration) with it. 
+
+
+%\colorbox{yellow}{Nevertheless, Pb of vertical resolution and 3D input : increase vertical mixing near river mouths to mimic a 3D river 
+
+%All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.}
+
+%\colorbox{yellow}{river mouths{\ldots}}
+
+%IF( ln_rnf ) THEN                                     ! increase diffusivity at rivers mouths
+%        DO jk = 2, nkrnf   ;   avt(:,:,jk) = avt(:,:,jk) + rn_avt_rnf * rnfmsk(:,:)   ;   END DO
+%ENDIF
+
+%\gmcomment{  word doc of runoffs:
+%
+%In the current \NEMO setup river runoff is added to emp fluxes, these are then applied at just the sea surface as a volume change (in the variable volume case this is a literal volume change, and in the linear free surface case the free surface is moved) and a salt flux due to the concentration/dilution effect.  There is also an option to increase vertical mixing near river mouths; this gives the effect of having a 3d river.  All river runoff and emp fluxes are assumed to be fresh water (zero salinity) and at the same temperature as the sea surface.
+%Our aim was to code the option to specify the temperature and salinity of river runoff, (as well as the amount), along with the depth that the river water will affect.  This would make it possible to model low salinity outflow, such as the Baltic, and would allow the ocean temperature to be affected by river runoff.  
+
+%The depth option makes it possible to have the river water affecting just the surface layer, throughout depth, or some specified point in between.
+
+%To do this we need to treat evaporation/precipitation fluxes and river runoff differently in the tra_sbc module.  We decided to separate them throughout the code, so that the variable emp represented solely evaporation minus precipitation fluxes, and a new 2d variable rnf was added which represents the volume flux of river runoff (in kg/m2s to remain consistent with emp).  This meant many uses of emp and emps needed to be changed, a list of all modules which use emp or emps and the changes made are below:
+
+%}
+% ================================================================
+%        Ice shelf melting
+% ================================================================
+\section{Ice shelf melting (\protect\mdl{sbcisf})}
+\label{sec:SBC_isf}
+%------------------------------------------namsbc_isf----------------------------------------------------
+
+\nlst{namsbc_isf}
+%--------------------------------------------------------------------------------------------------------
+Namelist variable in \ngn{namsbc}, \np{nn\_isf}, controls the ice shelf representation used. 
+\begin{description}
+\item[\np{nn\_isf}\forcode{ = 1}]
+The ice shelf cavity is represented (\np{ln\_isfcav}\forcode{ = .true.} needed). The fwf and heat flux are computed. 
+Two different bulk formula are available:
+	\begin{description}
+	\item[\np{nn\_isfblk}\forcode{ = 1}]
+	The bulk formula used to compute the melt is based the one described in \citet{Hunter2006}.
+        This formulation is based on a balance between the upward ocean heat flux and the latent heat flux at the ice shelf base.
+
+	\item[\np{nn\_isfblk}\forcode{ = 2}] 
+	The bulk formula used to compute the melt is based the one described in \citet{Jenkins1991}.
+        This formulation is based on a 3 equations formulation (a heat flux budget, a salt flux budget
+         and a linearised freezing point temperature equation).
+	\end{description}
+
+For this 2 bulk formulations, there are 3 different ways to compute the exchange coeficient:
+	\begin{description}
+        \item[\np{nn\_gammablk}\forcode{ = 0}]
+	The salt and heat exchange coefficients are constant and defined by \np{rn\_gammas0} and \np{rn\_gammat0}
+
+	\item[\np{nn\_gammablk}\forcode{ = 1}]
+	The salt and heat exchange coefficients are velocity dependent and defined as \np{rn\_gammas0}$ \times u_{*}$ and \np{rn\_gammat0}$ \times u_{*}$
+        where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters).
+        See \citet{Jenkins2010} for all the details on this formulation.
+	
+	\item[\np{nn\_gammablk}\forcode{ = 2}]
+	The salt and heat exchange coefficients are velocity and stability dependent and defined as 
+        $\gamma_{T,S} = \frac{u_{*}}{\Gamma_{Turb} + \Gamma^{T,S}_{Mole}}$
+        where $u_{*}$ is the friction velocity in the top boundary layer (ie first \np{rn\_hisf\_tbl} meters), 
+        $\Gamma_{Turb}$ the contribution of the ocean stability and 
+        $\Gamma^{T,S}_{Mole}$ the contribution of the molecular diffusion.
+        See \citet{Holland1999} for all the details on this formulation.
+        \end{description}
+
+\item[\np{nn\_isf}\forcode{ = 2}]
+A parameterisation of isf is used. The ice shelf cavity is not represented. 
+The fwf is distributed along the ice shelf edge between the depth of the average grounding line (GL)
+(\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}) as in (\np{nn\_isf}\forcode{ = 3}). 
+Furthermore the fwf and heat flux are computed using the \citet{Beckmann2003} parameterisation of isf melting. 
+The effective melting length (\np{sn\_Leff\_isf}) is read from a file.
+
+\item[\np{nn\_isf}\forcode{ = 3}]
+A simple parameterisation of isf is used. The ice shelf cavity is not represented. 
+The fwf (\np{sn\_rnfisf}) is prescribed and distributed along the ice shelf edge between the depth of the average grounding line (GL)
+(\np{sn\_depmax\_isf}) and the base of the ice shelf along the calving front (\np{sn\_depmin\_isf}). 
+The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.
+
+\item[\np{nn\_isf}\forcode{ = 4}]
+The ice shelf cavity is opened (\np{ln\_isfcav}\forcode{ = .true.} needed). However, the fwf is not computed but specified from file \np{sn\_fwfisf}). 
+The heat flux ($Q_h$) is computed as $Q_h = fwf \times L_f$.\\
+\end{description}
+
+
+$\bullet$ \np{nn\_isf}\forcode{ = 1} and \np{nn\_isf}\forcode{ = 2} compute a melt rate based on the water mass properties, ocean velocities and depth.
+ This flux is thus highly dependent of the model resolution (horizontal and vertical), realism of the water masses onto the shelf ...\\
+
+
+$\bullet$ \np{nn\_isf}\forcode{ = 3} and \np{nn\_isf}\forcode{ = 4} read the melt rate from a file. You have total control of the fwf forcing.
+This can be usefull if the water masses on the shelf are not realistic or the resolution (horizontal/vertical) are too 
+coarse to have realistic melting or for studies where you need to control your heat and fw input.\\ 
+
+A namelist parameters control over how many meters the heat and fw fluxes are spread. 
+\np{rn\_hisf\_tbl}] is the top boundary layer thickness as defined in \citet{Losch2008}. 
+This parameter is only used if \np{nn\_isf}\forcode{ = 1} or \np{nn\_isf}\forcode{ = 4}
+
+If \np{rn\_hisf\_tbl}\forcode{ = 0}., the fluxes are put in the top level whatever is its tickness. 
+
+If \np{rn\_hisf\_tbl} $>$ 0., the fluxes are spread over the first \np{rn\_hisf\_tbl} m (ie over one or several cells).\\
+
+The ice shelf melt is implemented as a volume flux with in the same way as for the runoff.
+The fw addition due to the ice shelf melting is, at each relevant depth level, added to the horizontal divergence 
+(\textit{hdivn}) in the subroutine \rou{sbc\_isf\_div}, called from \mdl{divcur}. 
+See the runoff section \autoref{sec:SBC_rnf} for all the details about the divergence correction. 
+
+
+\section{Ice sheet coupling}
+\label{sec:SBC_iscpl}
+%------------------------------------------namsbc_iscpl----------------------------------------------------
+
+\nlst{namsbc_iscpl}
+%--------------------------------------------------------------------------------------------------------
+Ice sheet/ocean coupling is done through file exchange at the restart step. NEMO, at each restart step, 
+read the bathymetry and ice shelf draft variable in a netcdf file. 
+If \np{ln\_iscpl}\forcode{ = .true.}, the isf draft is assume to be different at each restart step 
+with potentially some new wet/dry cells due to the ice sheet dynamics/thermodynamics.
+The wetting and drying scheme applied on the restart is very simple and described below for the 6 different cases:
+\begin{description}
+\item[Thin a cell down:]
+	T/S/ssh are unchanged and U/V in the top cell are corrected to keep the barotropic transport (bt) constant ($bt_b=bt_n$).
+\item[Enlarge  a cell:]
+	See case "Thin a cell down"
+\item[Dry a cell:]
+	mask, T/S, U/V and ssh are set to 0. Furthermore, U/V into the water column are modified to satisfy ($bt_b=bt_n$).
+\item[Wet a cell:] 
+	mask is set to 1, T/S is extrapolated from neighbours, $ssh_n = ssh_b$ and U/V set to 0. If no neighbours along i,j and k, T/S/U/V and mask are set to 0.
+\item[Dry a column:]
+	mask, T/S, U/V are set to 0 everywhere in the column and ssh set to 0.
+\item[Wet a column:]
+	set mask to 1, T/S is extrapolated from neighbours, ssh is extrapolated from neighbours and U/V set to 0. If no neighbour, T/S/U/V and mask set to 0.
+\end{description}
+The extrapolation is call \np{nn\_drown} times. It means that if the grounding line retreat by more than \np{nn\_drown} cells between 2 coupling steps,
+ the code will be unable to fill all the new wet cells properly. The default number is set up for the MISOMIP idealised experiments.\\
+This coupling procedure is able to take into account grounding line and calving front migration. However, it is a non-conservative processe. 
+This could lead to a trend in heat/salt content and volume. In order to remove the trend and keep the conservation level as close to 0 as possible,
+ a simple conservation scheme is available with \np{ln\_hsb}\forcode{ = .true.}. The heat/salt/vol. gain/loss is diagnose, as well as the location. 
+Based on what is done on sbcrnf to prescribed a source of heat/salt/vol., the heat/salt/vol. gain/loss is removed/added,
+ over a period of \np{rn\_fiscpl} time step, into the system. 
+So after \np{rn\_fiscpl} time step, all the heat/salt/vol. gain/loss due to extrapolation process is canceled.\\
+
+As the before and now fields are not compatible (modification of the geometry), the restart time step is prescribed to be an euler time step instead of a leap frog and $fields_b = fields_n$.
+%
+% ================================================================
+%        Handling of icebergs
+% ================================================================
+\section{Handling of icebergs (ICB)}
+\label{sec:ICB_icebergs}
+%------------------------------------------namberg----------------------------------------------------
+
+\nlst{namberg}
+%-------------------------------------------------------------------------------------------------------------
+
+Icebergs are modelled as lagrangian particles in NEMO \citep{Marsh_GMD2015}.
+Their physical behaviour is controlled by equations as described in \citet{Martin_Adcroft_OM10} ).
+(Note that the authors kindly provided a copy of their code to act as a basis for implementation in NEMO).
+Icebergs are initially spawned into one of ten classes which have specific mass and thickness as described 
+in the \ngn{namberg} namelist: 
+\np{rn\_initial\_mass} and \np{rn\_initial\_thickness}.
+Each class has an associated scaling (\np{rn\_mass\_scaling}), which is an integer representing how many icebergs 
+of this class are being described as one lagrangian point (this reduces the numerical problem of tracking every single iceberg).
+They are enabled by setting \np{ln\_icebergs}\forcode{ = .true.}.
+
+Two initialisation schemes are possible.
+\begin{description}
+\item[\np{nn\_test\_icebergs}~$>$~0]
+In this scheme, the value of \np{nn\_test\_icebergs} represents the class of iceberg to generate 
+(so between 1 and 10), and \np{nn\_test\_icebergs} provides a lon/lat box in the domain at each 
+grid point of which an iceberg is generated at the beginning of the run. 
+(Note that this happens each time the timestep equals \np{nn\_nit000}.)
+\np{nn\_test\_icebergs} is defined by four numbers in \np{nn\_test\_box} representing the corners 
+of the geographical box: lonmin,lonmax,latmin,latmax
+\item[\np{nn\_test\_icebergs}\forcode{ = -1}]
+In this scheme the model reads a calving file supplied in the \np{sn\_icb} parameter.
+This should be a file with a field on the configuration grid (typically ORCA) representing ice accumulation rate at each model point. 
+These should be ocean points adjacent to land where icebergs are known to calve.
+Most points in this input grid are going to have value zero.
+When the model runs, ice is accumulated at each grid point which has a non-zero source term.
+At each time step, a test is performed to see if there is enough ice mass to calve an iceberg of each class in order (1 to 10).
+Note that this is the initial mass multiplied by the number each particle represents ($i.e.$ the scaling).
+If there is enough ice, a new iceberg is spawned and the total available ice reduced accordingly.
+\end{description}
+
+Icebergs are influenced by wind, waves and currents, bottom melt and erosion.
+The latter act to disintegrate the iceberg. This is either all melted freshwater, or 
+(if \np{rn\_bits\_erosion\_fraction}~$>$~0) into melt and additionally small ice bits
+which are assumed to propagate with their larger parent and thus delay fluxing into the ocean.
+Melt water (and other variables on the configuration grid) are written into the main NEMO model output files.
+
+Extensive diagnostics can be produced.
+Separate output files are maintained for human-readable iceberg information.
+A separate file is produced for each processor (independent of \np{ln\_ctl}).
+The amount of information is controlled by two integer parameters:
+\begin{description}
+\item[\np{nn\_verbose\_level}]  takes a value between one and four and represents 
+an increasing number of points in the code at which variables are written, and an 
+increasing level of obscurity.
+\item[\np{nn\_verbose\_write}] is the number of timesteps between writes
+\end{description}
+
+Iceberg trajectories can also be written out and this is enabled by setting \np{nn\_sample\_rate}~$>$~0.
+A non-zero value represents how many timesteps between writes of information into the output file.
+These output files are in NETCDF format.
+When \key{mpp\_mpi} is defined, each output file contains only those icebergs in the corresponding processor.
+Trajectory points are written out in the order of their parent iceberg in the model's "linked list" of icebergs.
+So care is needed to recreate data for individual icebergs, since its trajectory data may be spread across
+multiple files.
+
+
+% ================================================================
+% Miscellanea options
+% ================================================================
+\section{Miscellaneous options}
+\label{sec:SBC_misc}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Diurnal cycle
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Diurnal cycle (\protect\mdl{sbcdcy})}
+\label{subsec:SBC_dcy}
+%------------------------------------------namsbc_rnf----------------------------------------------------
+%
+\nlst{namsbc} 
+%-------------------------------------------------------------------------------------------------------------
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]    \begin{center}
+\includegraphics[width=0.8\textwidth]{Fig_SBC_diurnal}
+\caption{ \protect\label{fig:SBC_diurnal}    
+Example of recontruction of the diurnal cycle variation of short wave flux  
+from daily mean values. The reconstructed diurnal cycle (black line) is chosen 
+as the mean value of the analytical cycle (blue line) over a time step, not 
+as the mid time step value of the analytically cycle (red square). From \citet{Bernie_al_CD07}.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+\cite{Bernie_al_JC05} have shown that to capture 90$\%$ of the diurnal variability of 
+SST requires a vertical resolution in upper ocean of 1~m or better and a temporal resolution 
+of the surface fluxes of 3~h or less. Unfortunately high frequency forcing fields are rare, 
+not to say inexistent. Nevertheless, it is possible to obtain a reasonable diurnal cycle 
+of the SST knowning only short wave flux (SWF) at high frequency \citep{Bernie_al_CD07}.
+Furthermore, only the knowledge of daily mean value of SWF is needed, 
+as higher frequency variations can be reconstructed from them, assuming that 
+the diurnal cycle of SWF is a scaling of the top of the atmosphere diurnal cycle 
+of incident SWF. The \cite{Bernie_al_CD07} reconstruction algorithm is available
+in \NEMO by setting \np{ln\_dm2dc}\forcode{ = .true.} (a \textit{\ngn{namsbc}} namelist variable) when using 
+CORE bulk formulea (\np{ln\_blk\_core}\forcode{ = .true.}) or the flux formulation (\np{ln\_flx}\forcode{ = .true.}). 
+The reconstruction is performed in the \mdl{sbcdcy} module. The detail of the algoritm used 
+can be found in the appendix~A of \cite{Bernie_al_CD07}. The algorithm preserve the daily 
+mean incomming SWF as the reconstructed SWF at a given time step is the mean value 
+of the analytical cycle over this time step (\autoref{fig:SBC_diurnal}). 
+The use of diurnal cycle reconstruction requires the input SWF to be daily 
+($i.e.$ a frequency of 24 and a time interpolation set to true in \np{sn\_qsr} namelist parameter).
+Furthermore, it is recommended to have a least 8 surface module time step per day,
+that is  $\rdt \ nn\_fsbc < 10,800~s = 3~h$. An example of recontructed SWF 
+is given in \autoref{fig:SBC_dcy} for a 12 reconstructed diurnal cycle, one every 2~hours 
+(from 1am to 11pm).
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]  \begin{center}
+\includegraphics[width=0.7\textwidth]{Fig_SBC_dcy}
+\caption{ \protect\label{fig:SBC_dcy}   
+Example of recontruction of the diurnal cycle variation of short wave flux  
+from daily mean values on an ORCA2 grid with a time sampling of 2~hours (from 1am to 11pm). 
+The display is on (i,j) plane. }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Note also that the setting a diurnal cycle in SWF is highly recommended  when 
+the top layer thickness approach 1~m or less, otherwise large error in SST can 
+appear due to an inconsistency between the scale of the vertical resolution 
+and the forcing acting on that scale.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Rotation of vector pairs onto the model grid directions
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Rotation of vector pairs onto the model grid directions}
+\label{subsec:SBC_rotation}
+
+When using a flux (\np{ln\_flx}\forcode{ = .true.}) or bulk (\np{ln\_clio}\forcode{ = .true.} or \np{ln\_core}\forcode{ = .true.}) formulation, 
+pairs of vector components can be rotated from east-north directions onto the local grid directions.  
+This is particularly useful when interpolation on the fly is used since here any vectors are likely to be defined 
+relative to a rectilinear grid.
+To activate this option a non-empty string is supplied in the rotation pair column of the relevant namelist.
+The eastward component must start with "U" and the northward component with "V".  
+The remaining characters in the strings are used to identify which pair of components go together.
+So for example, strings "U1" and "V1" next to "utau" and "vtau" would pair the wind stress components together
+and rotate them on to the model grid directions; "U2" and "V2" could be used against a second pair of components, 
+and so on.
+The extra characters used in the strings are arbitrary.
+The rot\_rep routine from the \mdl{geo2ocean} module is used to perform the rotation.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Surface restoring to observed SST and/or SSS
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Surface restoring to observed SST and/or SSS (\protect\mdl{sbcssr})}
+\label{subsec:SBC_ssr}
+%------------------------------------------namsbc_ssr----------------------------------------------------
+
+\nlst{namsbc_ssr} 
+%-------------------------------------------------------------------------------------------------------------
+
+IOptions are defined through the  \ngn{namsbc\_ssr} namelist variables.
+n forced mode using a flux formulation (\np{ln\_flx}\forcode{ = .true.}), a 
+feedback term \emph{must} be added to the surface heat flux $Q_{ns}^o$:
+\begin{equation} \label{eq:sbc_dmp_q}
+Q_{ns} = Q_{ns}^o + \frac{dQ}{dT} \left( \left. T \right|_{k=1} - SST_{Obs} \right)
+\end{equation}
+where SST is a sea surface temperature field (observed or climatological), $T$ is 
+the model surface layer temperature and $\frac{dQ}{dT}$ is a negative feedback 
+coefficient usually taken equal to $-40~W/m^2/K$. For a $50~m$ 
+mixed-layer depth, this value corresponds to a relaxation time scale of two months. 
+This term ensures that if $T$ perfectly matches the supplied SST, then $Q$ is 
+equal to $Q_o$. 
+
+In the fresh water budget, a feedback term can also be added. Converted into an 
+equivalent freshwater flux, it takes the following expression :
+
+\begin{equation} \label{eq:sbc_dmp_emp}
+\textit{emp} = \textit{emp}_o + \gamma_s^{-1} e_{3t}  \frac{  \left(\left.S\right|_{k=1}-SSS_{Obs}\right)}
+												         {\left.S\right|_{k=1}}
+\end{equation}
+
+where $\textit{emp}_{o }$ is a net surface fresh water flux (observed, climatological or an
+atmospheric model product), \textit{SSS}$_{Obs}$ is a sea surface salinity (usually a time 
+interpolation of the monthly mean Polar Hydrographic Climatology \citep{Steele2001}), 
+$\left.S\right|_{k=1}$ is the model surface layer salinity and $\gamma_s$ is a negative 
+feedback coefficient which is provided as a namelist parameter. Unlike heat flux, there is no 
+physical justification for the feedback term in \autoref{eq:sbc_dmp_emp} as the atmosphere 
+does not care about ocean surface salinity \citep{Madec1997}. The SSS restoring 
+term should be viewed as a flux correction on freshwater fluxes to reduce the 
+uncertainties we have on the observed freshwater budget.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Handling of ice-covered area
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Handling of ice-covered area  (\textit{sbcice\_...})}
+\label{subsec:SBC_ice-cover}
+
+The presence at the sea surface of an ice covered area modifies all the fluxes 
+transmitted to the ocean. There are several way to handle sea-ice in the system 
+depending on the value of the \np{nn\_ice} namelist parameter found in \ngn{namsbc} namelist.  
+\begin{description}
+\item[nn{\_}ice = 0]  there will never be sea-ice in the computational domain. 
+This is a typical namelist value used for tropical ocean domain. The surface fluxes 
+are simply specified for an ice-free ocean. No specific things is done for sea-ice.
+\item[nn{\_}ice = 1]  sea-ice can exist in the computational domain, but no sea-ice model 
+is used. An observed ice covered area is read in a file. Below this area, the SST is 
+restored to the freezing point and the heat fluxes are set to $-4~W/m^2$ ($-2~W/m^2$) 
+in the northern (southern) hemisphere. The associated modification of the freshwater 
+fluxes are done in such a way that the change in buoyancy fluxes remains zero. 
+This prevents deep convection to occur when trying to reach the freezing point 
+(and so ice covered area condition) while the SSS is too large. This manner of 
+managing sea-ice area, just by using si IF case, is usually referred as the \textit{ice-if} 
+model. It can be found in the \mdl{sbcice{\_}if} module.
+\item[nn{\_}ice = 2 or more]  A full sea ice model is used. This model computes the 
+ice-ocean fluxes, that are combined with the air-sea fluxes using the ice fraction of 
+each model cell to provide the surface ocean fluxes. Note that the activation of a 
+sea-ice model is is done by defining a CPP key (\key{lim3} or \key{cice}). 
+The activation automatically overwrites the read value of nn{\_}ice to its appropriate 
+value ($i.e.$ $2$ for LIM-3 or $3$ for CICE).
+\end{description}
+
+% {Description of Ice-ocean interface to be added here or in LIM 2 and 3 doc ?}
+
+\subsection{Interface to CICE (\protect\mdl{sbcice\_cice})}
+\label{subsec:SBC_cice}
+
+It is now possible to couple a regional or global NEMO configuration (without AGRIF) to the CICE sea-ice
+model by using \key{cice}.  The CICE code can be obtained from 
+\href{http://oceans11.lanl.gov/trac/CICE/}{LANL} and the additional 'hadgem3' drivers will be required, 
+even with the latest code release.  Input grid files consistent with those used in NEMO will also be needed, 
+and CICE CPP keys \textbf{ORCA\_GRID}, \textbf{CICE\_IN\_NEMO} and \textbf{coupled} should be used (seek advice from UKMO 
+if necessary).  Currently the code is only designed to work when using the CORE forcing option for NEMO (with
+\textit{calc\_strair}\forcode{ = .true.} and \textit{calc\_Tsfc}\forcode{ = .true.} in the CICE name-list), or alternatively when NEMO 
+is coupled to the HadGAM3 atmosphere model (with \textit{calc\_strair}\forcode{ = .false.} and \textit{calc\_Tsfc}\forcode{ = false}).
+The code is intended to be used with \np{nn\_fsbc} set to 1 (although coupling ocean and ice less frequently 
+should work, it is possible the calculation of some of the ocean-ice fluxes needs to be modified slightly - the
+user should check that results are not significantly different to the standard case).
+
+There are two options for the technical coupling between NEMO and CICE.  The standard version allows
+complete flexibility for the domain decompositions in the individual models, but this is at the expense of global
+gather and scatter operations in the coupling which become very expensive on larger numbers of processors. The
+alternative option (using \key{nemocice\_decomp} for both NEMO and CICE) ensures that the domain decomposition is
+identical in both models (provided domain parameters are set appropriately, and 
+\textit{processor\_shape~=~square-ice} and \textit{distribution\_wght~=~block} in the CICE name-list) and allows
+much more efficient direct coupling on individual processors.  This solution scales much better although it is at 
+the expense of having more idle CICE processors in areas where there is no sea ice.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Freshwater budget control 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Freshwater budget control (\protect\mdl{sbcfwb})}
+\label{subsec:SBC_fwb}
+
+For global ocean simulation it can be useful to introduce a control of the mean sea 
+level in order to prevent unrealistic drift of the sea surface height due to inaccuracy 
+in the freshwater fluxes. In \NEMO, two way of controlling the the freshwater budget. 
+\begin{description}
+\item[\np{nn\_fwb}\forcode{ = 0}]  no control at all. The mean sea level is free to drift, and will 
+certainly do so.
+\item[\np{nn\_fwb}\forcode{ = 1}]  global mean \textit{emp} set to zero at each model time step. 
+%Note that with a sea-ice model, this technique only control the mean sea level with linear free surface (\key{vvl} not defined) and no mass flux between ocean and ice (as it is implemented in the current ice-ocean coupling). 
+\item[\np{nn\_fwb}\forcode{ = 2}]  freshwater budget is adjusted from the previous year annual 
+mean budget which is read in the \textit{EMPave\_old.dat} file. As the model uses the 
+Boussinesq approximation, the annual mean fresh water budget is simply evaluated 
+from the change in the mean sea level at January the first and saved in the 
+\textit{EMPav.dat} file. 
+\end{description}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Neutral Drag Coefficient from external wave model
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Neutral drag coeff. from external wave model (\protect\mdl{sbcwave})]
+				{Neutral drag coefficient from external wave model (\protect\mdl{sbcwave})}
+\label{subsec:SBC_wave}
+%------------------------------------------namwave----------------------------------------------------
+
+\nlst{namsbc_wave}
+%-------------------------------------------------------------------------------------------------------------
+
+In order to read a neutral drag coefficient, from an external data source ($i.e.$ a wave model), the 
+logical variable \np{ln\_cdgw} in \ngn{namsbc} namelist must be set to \forcode{.true.}. 
+The \mdl{sbcwave} module containing the routine \np{sbc\_wave} reads the
+namelist \ngn{namsbc\_wave} (for external data names, locations, frequency, interpolation and all 
+the miscellanous options allowed by Input Data generic Interface see \autoref{sec:SBC_input}) 
+and a 2D field of neutral drag coefficient. 
+Then using the routine TURB\_CORE\_1Z or TURB\_CORE\_2Z, and starting from the neutral drag coefficent provided, 
+the drag coefficient is computed according to stable/unstable conditions of the air-sea interface following \citet{Large_Yeager_Rep04}.
+
+
+% Griffies doc:
+% When running ocean-ice simulations, we are not explicitly representing land processes, 
+% such as rivers, catchment areas, snow accumulation, etc. However, to reduce model drift, 
+% it is important to balance the hydrological cycle in ocean-ice models. 
+% We thus need to prescribe some form of global normalization to the precipitation minus evaporation plus river runoff. 
+% The result of the normalization should be a global integrated zero net water input to the ocean-ice system over 
+% a chosen time scale. 
+%How often the normalization is done is a matter of choice. In mom4p1, we choose to do so at each model time step, 
+% so that there is always a zero net input of water to the ocean-ice system. 
+% Others choose to normalize over an annual cycle, in which case the net imbalance over an annual cycle is used 
+% to alter the subsequent year�s water budget in an attempt to damp the annual water imbalance. 
+% Note that the annual budget approach may be inappropriate with interannually varying precipitation forcing. 
+% When running ocean-ice coupled models, it is incorrect to include the water transport between the ocean 
+% and ice models when aiming to balance the hydrological cycle. 
+% The reason is that it is the sum of the water in the ocean plus ice that should be balanced when running ocean-ice models, 
+% not the water in any one sub-component. As an extreme example to illustrate the issue, 
+% consider an ocean-ice model with zero initial sea ice. As the ocean-ice model spins up, 
+% there should be a net accumulation of water in the growing sea ice, and thus a net loss of water from the ocean. 
+% The total water contained in the ocean plus ice system is constant, but there is an exchange of water between 
+% the subcomponents. This exchange should not be part of the normalization used to balance the hydrological cycle 
+% in ocean-ice models. 
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_STO.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 10321)
@@ -0,0 +1,179 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter stochastic parametrization of EOS (STO)
+% ================================================================
+\chapter{Stochastic Parametrization of EOS (STO)}
+\label{chap:STO}
+
+Authors: P.-A. Bouttier
+
+\minitoc
+
+\newpage
+
+
+The stochastic parametrization module aims to explicitly simulate uncertainties in the model. 
+More particularly, \cite{Brankart_OM2013} has shown that, 
+because of the nonlinearity of the seawater equation of state, unresolved scales represent 
+a major source of uncertainties in the computation of the large scale horizontal density gradient 
+(from T/S large scale fields), and that the impact of these uncertainties can be simulated 
+by random processes representing unresolved T/S fluctuations.
+
+The stochastic formulation of the equation of state can be written as:
+\begin{equation}
+ \label{eq:eos_sto}
+  \rho = \frac{1}{2} \sum_{i=1}^m\{ \rho[T+\Delta T_i,S+\Delta S_i,p_o(z)] + \rho[T-\Delta T_i,S-\Delta S_i,p_o(z)] \}
+\end{equation}
+where $p_o(z)$ is the reference pressure depending on the depth and, 
+$\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as the scalar product 
+of the respective local T/S gradients with random walks $\mathbf{\xi}$:
+\begin{equation}
+ \label{eq:sto_pert}
+ \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S
+\end{equation}
+$\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with 
+a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$. 
+$\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical.
+
+
+\section{Stochastic processes}
+\label{sec:STO_the_details}
+
+The starting point of our implementation of stochastic parameterizations
+in NEMO is to observe that many existing parameterizations are based
+on autoregressive processes, which are used as a basic source of randomness
+to transform a deterministic model into a probabilistic model.
+A generic approach is thus to add one single new module in NEMO,
+generating processes with appropriate statistics
+to simulate each kind of uncertainty in the model
+(see \cite{Brankart_al_GMD2015} for more details).
+
+In practice, at every model grid point, independent Gaussian autoregressive
+processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated
+using the same basic equation:
+
+\begin{equation}
+\label{eq:autoreg}
+\xi^{(i)}_{k+1} = a^{(i)} \xi^{(i)}_k + b^{(i)} w^{(i)} + c^{(i)}
+\end{equation}
+
+\noindent
+where $k$ is the index of the model timestep; and
+$a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are parameters defining
+the mean ($\mu^{(i)}$) standard deviation ($\sigma^{(i)}$)
+and correlation timescale ($\tau^{(i)}$) of each process:
+
+\begin{itemize}
+\item for order~1 processes, $w^{(i)}$ is a Gaussian white noise,
+with zero mean and standard deviation equal to~1, and the parameters
+$a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are given by:
+
+\begin{equation}
+\label{eq:ord1}
+\left\{
+\begin{array}{l}
+a^{(i)} = \varphi \\
+b^{(i)} = \sigma^{(i)} \sqrt{ 1 - \varphi^2 } 
+ \qquad\qquad\mbox{with}\qquad\qquad
+\varphi = \exp \left( - 1 / \tau^{(i)} \right) \\
+c^{(i)} = \mu^{(i)} \left( 1 - \varphi \right) \\
+\end{array}
+\right.
+\end{equation}
+
+\item for order~$n>1$ processes, $w^{(i)}$ is an order~$n-1$ autoregressive process,
+with zero mean, standard deviation equal to~$\sigma^{(i)}$; correlation timescale
+equal to~$\tau^{(i)}$; and the parameters $a^{(i)}$, $b^{(i)}$, $c^{(i)}$ are given by:
+
+\begin{equation}
+\label{eq:ord2}
+\left\{
+\begin{array}{l}
+a^{(i)} = \varphi \\
+b^{(i)} = \frac{n-1}{2(4n-3)} \sqrt{ 1 - \varphi^2 } 
+ \qquad\qquad\mbox{with}\qquad\qquad
+\varphi = \exp \left( - 1 / \tau^{(i)} \right) \\
+c^{(i)} = \mu^{(i)} \left( 1 - \varphi \right) \\
+\end{array}
+\right.
+\end{equation}
+
+\end{itemize}
+
+\noindent
+In this way, higher order processes can be easily generated recursively using 
+the same piece of code implementing (\autoref{eq:autoreg}), 
+and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$.
+The parameters in (\autoref{eq:ord2}) are computed so that this recursive application
+of (\autoref{eq:autoreg}) leads to processes with the required standard deviation
+and correlation timescale, with the additional condition that
+the $n-1$ first derivatives of the autocorrelation function
+are equal to zero at~$t=0$, so that the resulting processes
+become smoother and smoother as $n$ is increased.
+
+Overall, this method provides quite a simple and generic way of generating 
+a wide class of stochastic processes. 
+However, this also means that new model parameters are needed to specify each of 
+these stochastic processes. As in any parameterization of lacking physics, 
+a very important issues then to tune these new parameters using either first principles, 
+model simulations, or real-world observations.
+
+\section{Implementation details}
+\label{sec:STO_thech_details}
+
+%---------------------------------------namsbc--------------------------------------------------
+
+\nlst{namsto}
+%--------------------------------------------------------------------------------------------------------------
+
+The computer code implementing stochastic parametrisations can be found in the STO directory.
+It involves three modules : 
+\begin{description}
+\item[\mdl{stopar}] : define the Stochastic parameters and their time evolution.
+\item[\mdl{storng}] : a random number generator based on (and includes) the 64-bit KISS 
+                      (Keep It Simple Stupid) random number generator distributed by George Marsaglia 
+                      (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here})
+\item[\mdl{stopts}] : stochastic parametrisation associated with the non-linearity of the equation of seawater, 
+ implementing \autoref{eq:sto_pert} and specific piece of code in the equation of state implementing \autoref{eq:eos_sto}.
+\end{description}
+
+The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO):
+
+The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}),
+applied at each model grid point (in 2D or 3D), 
+and called at each model time step ($k$) to update
+every autoregressive process ($i=1,\ldots,m$).
+This routine also includes a filtering operator, applied to $w^{(i)}$,
+to introduce a spatial correlation between the stochastic processes.
+
+The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated
+to the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$
+for each autoregressive process, as a function of the statistical properties
+required by the model user (mean, standard deviation, time correlation,
+order of the process,\ldots). 
+
+Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters:
+\begin{description}
+   \item[\np{nn\_sto\_eos}]   : number of independent random walks 
+   \item[\np{rn\_eos\_stdxy}] : random walk horz. standard deviation (in grid points)
+   \item[\np{rn\_eos\_stdz}]  : random walk vert. standard deviation (in grid points)
+   \item[\np{rn\_eos\_tcor}]  : random walk time correlation (in timesteps)
+   \item[\np{nn\_eos\_ord}]   : order of autoregressive processes
+   \item[\np{nn\_eos\_flt}]   : passes of Laplacian filter
+   \item[\np{rn\_eos\_lim}]   : limitation factor (default = 3.0)
+\end{description}
+This routine also includes the initialization (seeding) of the random number generator.
+
+The third routine (\rou{sto\_rst\_write}) writes a restart file (which suffix name is 
+given by \np{cn\_storst\_out} namelist parameter) containing the current value of 
+all autoregressive processes to allow restarting a simulation from where it has been interrupted.
+This file also contains the current state of the random number generator.
+When \np{ln\_rststo} is set to \forcode{.true.}), the restart file (which suffix name is 
+given by \np{cn\_storst\_in} namelist parameter) is read by the initialization routine 
+(\rou{sto\_par\_init}). The simulation will continue exactly as if it was not interrupted
+only  when \np{ln\_rstseed} is set to \forcode{.true.}, $i.e.$ when the state of 
+the random number generator is read in the restart file.
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_TRA.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_TRA.tex	(revision 10321)
@@ -0,0 +1,1466 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter 1 ——— Ocean Tracers (TRA)
+% ================================================================
+\chapter{Ocean Tracers (TRA)}
+\label{chap:TRA}
+\minitoc
+
+% missing/update 
+% traqsr: need to coordinate with SBC module
+
+%STEVEN :  is the use of the word "positive" to describe a scheme enough, or should it be "positive definite"? I added a comment to this effect on some instances of this below
+
+%\newpage
+\vspace{2.cm}
+%$\ $\newline    % force a new ligne
+
+Using the representation described in \autoref{chap:DOM}, several semi-discrete 
+space forms of the tracer equations are available depending on the vertical 
+coordinate used and on the physics used. In all the equations presented 
+here, the masking has been omitted for simplicity. One must be aware that 
+all the quantities are masked fields and that each time a mean or difference 
+operator is used, the resulting field is multiplied by a mask.
+
+The two active tracers are potential temperature and salinity. Their prognostic 
+equations can be summarized as follows:
+\begin{equation*}
+\text{NXT} = \text{ADV}+\text{LDF}+\text{ZDF}+\text{SBC}
+                   \ (+\text{QSR})\ (+\text{BBC})\ (+\text{BBL})\ (+\text{DMP})
+\end{equation*}
+
+NXT stands for next, referring to the time-stepping. From left to right, the terms 
+on the rhs of the tracer equations are the advection (ADV), the lateral diffusion 
+(LDF), the vertical diffusion (ZDF), the contributions from the external forcings 
+(SBC: Surface Boundary Condition, QSR: penetrative Solar Radiation, and BBC: 
+Bottom Boundary Condition), the contribution from the bottom boundary Layer 
+(BBL) parametrisation, and an internal damping (DMP) term. The terms QSR, 
+BBC, BBL and DMP are optional. The external forcings and parameterisations 
+require complex inputs and complex calculations ($e.g.$ bulk formulae, estimation 
+of mixing coefficients) that are carried out in the SBC, LDF and ZDF modules and 
+described in \autoref{chap:SBC}, \autoref{chap:LDF} and \autoref{chap:ZDF}, respectively. 
+Note that \mdl{tranpc}, the non-penetrative convection module, although 
+located in the NEMO/OPA/TRA directory as it directly modifies the tracer fields, 
+is described with the model vertical physics (ZDF) together with other available 
+parameterization of convection.
+
+In the present chapter we also describe the diagnostic equations used to compute 
+the sea-water properties (density, Brunt-V\"{a}is\"{a}l\"{a} frequency, specific heat and 
+freezing point with associated modules \mdl{eosbn2} and \mdl{phycst}).
+
+The different options available to the user are managed by namelist logicals or CPP keys. 
+For each equation term  \textit{TTT}, the namelist logicals are \textit{ln\_traTTT\_xxx}, 
+where \textit{xxx} is a 3 or 4 letter acronym corresponding to each optional scheme. 
+The CPP key (when it exists) is \key{traTTT}. The equivalent code can be 
+found in the \textit{traTTT} or \textit{traTTT\_xxx} module, in the NEMO/OPA/TRA directory.
+
+The user has the option of extracting each tendency term on the RHS of the tracer 
+equation for output (\np{ln\_tra\_trd} or \np{ln\_tra\_mxl}\forcode{ = .true.}), as described in \autoref{chap:DIA}.
+
+$\ $\newline    % force a new ligne
+% ================================================================
+% Tracer Advection
+% ================================================================
+\section{Tracer advection (\protect\mdl{traadv})}
+\label{sec:TRA_adv}
+%------------------------------------------namtra_adv-----------------------------------------------------
+
+\nlst{namtra_adv}
+%-------------------------------------------------------------------------------------------------------------
+
+When considered ($i.e.$ when \np{ln\_traadv\_NONE} is not set to \forcode{.true.}), 
+the advection tendency of a tracer is expressed in flux form, 
+$i.e.$ as the divergence of the advective fluxes. Its discrete expression is given by :
+\begin{equation} \label{eq:tra_adv}
+ADV_\tau =-\frac{1}{b_t} \left( 
+\;\delta _i \left[ e_{2u}\,e_{3u} \;  u\; \tau _u  \right]
++\delta _j \left[ e_{1v}\,e_{3v}  \;  v\; \tau _v  \right] \; \right)
+-\frac{1}{e_{3t}} \;\delta _k \left[ w\; \tau _w \right]
+\end{equation}
+where $\tau$ is either T or S, and $b_t= e_{1t}\,e_{2t}\,e_{3t}$ is the volume of $T$-cells. 
+The flux form in \autoref{eq:tra_adv} 
+implicitly requires the use of the continuity equation. Indeed, it is obtained
+by using the following equality : $\nabla \cdot \left( \vect{U}\,T \right)=\vect{U} \cdot \nabla T$ 
+which results from the use of the continuity equation,  $\partial _t e_3 + e_3\;\nabla \cdot \vect{U}=0$ 
+(which reduces to $\nabla \cdot \vect{U}=0$ in linear free surface, $i.e.$ \np{ln\_linssh}\forcode{ = .true.}). 
+Therefore it is of paramount importance to design the discrete analogue of the 
+advection tendency so that it is consistent with the continuity equation in order to 
+enforce the conservation properties of the continuous equations. In other words, 
+by setting $\tau = 1$ in (\autoref{eq:tra_adv}) we recover the discrete form of 
+the continuity equation which is used to calculate the vertical velocity.
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	 \begin{center}
+\includegraphics[width=0.9\textwidth]{Fig_adv_scheme}
+\caption{	\protect\label{fig:adv_scheme} 
+Schematic representation of some ways used to evaluate the tracer value 
+at $u$-point and the amount of tracer exchanged between two neighbouring grid 
+points. Upsteam biased scheme (ups): the upstream value is used and the black 
+area is exchanged. Piecewise parabolic method (ppm): a parabolic interpolation 
+is used and the black and dark grey areas are exchanged. Monotonic upstream 
+scheme for conservative laws (muscl):  a parabolic interpolation is used and black, 
+dark grey and grey areas are exchanged. Second order scheme (cen2): the mean 
+value is used and black, dark grey, grey and light grey areas are exchanged. Note 
+that this illustration does not include the flux limiter used in ppm and muscl schemes.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The key difference between the advection schemes available in \NEMO is the choice 
+made in space and time interpolation to define the value of the tracer at the 
+velocity points (\autoref{fig:adv_scheme}). 
+
+Along solid lateral and bottom boundaries a zero tracer flux is automatically 
+specified, since the normal velocity is zero there. At the sea surface the 
+boundary condition depends on the type of sea surface chosen: 
+\begin{description}
+\item [linear free surface:] (\np{ln\_linssh}\forcode{ = .true.}) the first level thickness is constant in time: 
+the vertical boundary condition is applied at the fixed surface $z=0$ 
+rather than on the moving surface $z=\eta$. There is a non-zero advective 
+flux which is set for all advection schemes as 
+$\left. {\tau _w } \right|_{k=1/2} =T_{k=1} $, $i.e.$ 
+the product of surface velocity (at $z=0$) by the first level tracer value.
+\item [non-linear free surface:] (\np{ln\_linssh}\forcode{ = .false.}) 
+convergence/divergence in the first ocean level moves the free surface 
+up/down. There is no tracer advection through it so that the advective 
+fluxes through the surface are also zero 
+\end{description}
+In all cases, this boundary condition retains local conservation of tracer. 
+Global conservation is obtained in non-linear free surface case, 
+but \textit{not} in the linear free surface case. Nevertheless, in the latter case, 
+it is achieved to a good approximation since the non-conservative 
+term is the product of the time derivative of the tracer and the free surface 
+height, two quantities that are not correlated \citep{Roullet_Madec_JGR00,Griffies_al_MWR01,Campin2004}.
+
+The velocity field that appears in (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_zco}) 
+is the centred (\textit{now}) \textit{effective} ocean velocity, $i.e.$ the \textit{eulerian} velocity
+(see \autoref{chap:DYN}) plus the eddy induced velocity (\textit{eiv}) 
+and/or the mixed layer eddy induced velocity (\textit{eiv})
+when those parameterisations are used (see \autoref{chap:LDF}).
+
+Several tracer advection scheme are proposed, namely 
+a $2^{nd}$ or $4^{th}$ order centred schemes (CEN), 
+a $2^{nd}$ or $4^{th}$ order Flux Corrected Transport scheme (FCT),
+a Monotone Upstream Scheme for Conservative Laws scheme (MUSCL),
+a $3^{rd}$ Upstream Biased Scheme (UBS, also often called UP3), and
+a Quadratic Upstream Interpolation for Convective Kinematics with 
+Estimated Streaming Terms scheme (QUICKEST).
+The choice is made in the \textit{\ngn{namtra\_adv}} namelist, by 
+setting to \forcode{.true.} one of the logicals \textit{ln\_traadv\_xxx}. 
+The corresponding code can be found in the \mdl{traadv\_xxx} module, 
+where \textit{xxx} is a 3 or 4 letter acronym corresponding to each scheme. 
+By default ($i.e.$ in the reference namelist, \ngn{namelist\_ref}), all the logicals 
+are set to \forcode{.false.}. If the user does not select an advection scheme 
+in the configuration namelist (\ngn{namelist\_cfg}), the tracers will \textit{not} be advected !
+
+Details of the advection schemes are given below. The choosing an advection scheme 
+is a complex matter which depends on the model physics, model resolution, 
+type of tracer, as well as the issue of numerical cost. In particular, we note that
+(1) CEN and FCT schemes require an explicit diffusion operator 
+while the other schemes are diffusive enough so that they do not necessarily need additional diffusion ; 
+(2) CEN and UBS are not \textit{positive} schemes
+\footnote{negative values can appear in an initially strictly positive tracer field 
+which is advected}
+, implying that false extrema are permitted. Their use is not recommended on passive tracers ; 
+(3) It is recommended that the same advection-diffusion scheme is 
+used on both active and passive tracers. Indeed, if a source or sink of a 
+passive tracer depends on an active one, the difference of treatment of 
+active and passive tracers can create very nice-looking frontal structures 
+that are pure numerical artefacts. Nevertheless, most of our users set a different 
+treatment on passive and active tracers, that's the reason why this possibility 
+is offered. We strongly suggest them to perform a sensitivity experiment 
+using a same treatment to assess the robustness of their results.
+
+% -------------------------------------------------------------------------------------------------------------
+%        2nd and 4th order centred schemes
+% -------------------------------------------------------------------------------------------------------------
+\subsection{CEN: Centred scheme (\protect\np{ln\_traadv\_cen}\forcode{ = .true.})}
+\label{subsec:TRA_adv_cen}
+
+%        2nd order centred scheme  
+
+The centred advection scheme (CEN) is used when \np{ln\_traadv\_cen}\forcode{ = .true.}. 
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) 
+and vertical direction by setting \np{nn\_cen\_h} and \np{nn\_cen\_v} to $2$ or $4$. 
+CEN implementation can be found in the \mdl{traadv\_cen} module.
+
+In the $2^{nd}$ order centred formulation (CEN2), the tracer at velocity points 
+is evaluated as the mean of the two neighbouring $T$-point values. 
+For example, in the $i$-direction :
+\begin{equation} \label{eq:tra_adv_cen2}
+\tau _u^{cen2} =\overline T ^{i+1/2}
+\end{equation}
+
+CEN2 is non diffusive ($i.e.$ it conserves the tracer variance, $\tau^2)$ 
+but dispersive ($i.e.$ it may create false extrema). It is therefore notoriously 
+noisy and must be used in conjunction with an explicit diffusion operator to 
+produce a sensible solution. The associated time-stepping is performed using 
+a leapfrog scheme in conjunction with an Asselin time-filter, so $T$ in 
+(\autoref{eq:tra_adv_cen2}) is the \textit{now} tracer value. 
+
+Note that using the CEN2, the overall tracer advection is of second 
+order accuracy since both (\autoref{eq:tra_adv}) and (\autoref{eq:tra_adv_cen2}) 
+have this order of accuracy.
+
+%        4nd order centred scheme  
+
+In the $4^{th}$ order formulation (CEN4), tracer values are evaluated at u- and v-points as 
+a $4^{th}$ order interpolation, and thus depend on the four neighbouring $T$-points. 
+For example, in the $i$-direction:
+\begin{equation} \label{eq:tra_adv_cen4}
+\tau _u^{cen4} 
+=\overline{   T - \frac{1}{6}\,\delta _i \left[ \delta_{i+1/2}[T] \,\right]   }^{\,i+1/2}
+\end{equation}
+In the vertical direction (\np{nn\_cen\_v}\forcode{ = 4}), a $4^{th}$ COMPACT interpolation 
+has been prefered \citep{Demange_PhD2014}.
+In the COMPACT scheme, both the field and its derivative are interpolated, 
+which leads, after a matrix inversion, spectral characteristics 
+similar to schemes of higher order \citep{Lele_JCP1992}.
+ 
+
+Strictly speaking, the CEN4 scheme is not a $4^{th}$ order advection scheme 
+but a $4^{th}$ order evaluation of advective fluxes, since the divergence of 
+advective fluxes \autoref{eq:tra_adv} is kept at $2^{nd}$ order. 
+The expression \textit{$4^{th}$ order scheme} used in oceanographic literature 
+is usually associated with the scheme presented here. 
+Introducing a \forcode{.true.} $4^{th}$ order advection scheme is feasible but, 
+for consistency reasons, it requires changes in the discretisation of the tracer 
+advection together with changes in the continuity equation, 
+and the momentum advection and pressure terms.  
+
+A direct consequence of the pseudo-fourth order nature of the scheme is that 
+it is not non-diffusive, $i.e.$ the global variance of a tracer is not preserved using CEN4. 
+Furthermore, it must be used in conjunction with an explicit diffusion operator 
+to produce a sensible solution. 
+As in CEN2 case, the time-stepping is performed using a leapfrog scheme in conjunction 
+with an Asselin time-filter, so $T$ in (\autoref{eq:tra_adv_cen4}) is the \textit{now} tracer.
+
+At a $T$-grid cell adjacent to a boundary (coastline, bottom and surface), 
+an additional hypothesis must be made to evaluate $\tau _u^{cen4}$. 
+This hypothesis usually reduces the order of the scheme. 
+Here we choose to set the gradient of $T$ across the boundary to zero. 
+Alternative conditions can be specified, such as a reduction to a second order scheme 
+for these near boundary grid points.
+
+% -------------------------------------------------------------------------------------------------------------
+%        FCT scheme  
+% -------------------------------------------------------------------------------------------------------------
+\subsection{FCT: Flux Corrected Transport scheme (\protect\np{ln\_traadv\_fct}\forcode{ = .true.})}
+\label{subsec:TRA_adv_tvd}
+
+The Flux Corrected Transport schemes (FCT) is used when \np{ln\_traadv\_fct}\forcode{ = .true.}. 
+Its order ($2^{nd}$ or $4^{th}$) can be chosen independently on horizontal (iso-level) 
+and vertical direction by setting \np{nn\_fct\_h} and \np{nn\_fct\_v} to $2$ or $4$.
+FCT implementation can be found in the \mdl{traadv\_fct} module.
+
+In FCT formulation, the tracer at velocity points is evaluated using a combination of 
+an upstream and a centred scheme. For example, in the $i$-direction :
+\begin{equation} \label{eq:tra_adv_fct}
+\begin{split}
+\tau _u^{ups}&= \begin{cases}
+ 					T_{i+1} 	& \text{if $\ u_{i+1/2} <     0$} \hfill \\
+ 					T_i   		& \text{if $\ u_{i+1/2} \geq 0$} \hfill \\
+				  \end{cases}     \\
+\\
+\tau _u^{fct}&=\tau _u^{ups} +c_u \;\left( {\tau _u^{cen} -\tau _u^{ups} } \right)
+\end{split}
+\end{equation}
+where $c_u$ is a flux limiter function taking values between 0 and 1. 
+The FCT order is the one of the centred scheme used ($i.e.$ it depends on the setting of
+\np{nn\_fct\_h} and \np{nn\_fct\_v}.
+There exist many ways to define $c_u$, each corresponding to a different 
+FCT scheme. The one chosen in \NEMO is described in \citet{Zalesak_JCP79}. 
+$c_u$ only departs from $1$ when the advective term produces a local extremum in the tracer field. 
+The resulting scheme is quite expensive but \emph{positive}. 
+It can be used on both active and passive tracers. 
+A comparison of FCT-2 with MUSCL and a MPDATA scheme can be found in \citet{Levy_al_GRL01}. 
+
+An additional option has been added controlled by \np{nn\_fct\_zts}. By setting this integer to 
+a value larger than zero, a $2^{nd}$ order FCT scheme is used on both horizontal and vertical direction, 
+but on the latter, a split-explicit time stepping is used, with a number of sub-timestep equals
+to \np{nn\_fct\_zts}. This option can be useful when the size of the timestep is limited 
+by vertical advection \citep{Lemarie_OM2015}. Note that in this case, a similar split-explicit 
+time stepping should be used on vertical advection of momentum to insure a better stability
+(see \autoref{subsec:DYN_zad}).
+
+For stability reasons (see \autoref{chap:STP}), $\tau _u^{cen}$ is evaluated in (\autoref{eq:tra_adv_fct}) 
+using the \textit{now} tracer while $\tau _u^{ups}$ is evaluated using the \textit{before} tracer. In other words, 
+the advective part of the scheme is time stepped with a leap-frog scheme 
+while a forward scheme is used for the diffusive part. 
+
+% -------------------------------------------------------------------------------------------------------------
+%        MUSCL scheme  
+% -------------------------------------------------------------------------------------------------------------
+\subsection{MUSCL: Monotone Upstream Scheme for Conservative Laws (\protect\np{ln\_traadv\_mus}\forcode{ = .true.})}
+\label{subsec:TRA_adv_mus}
+
+The Monotone Upstream Scheme for Conservative Laws (MUSCL) is used when \np{ln\_traadv\_mus}\forcode{ = .true.}. 
+MUSCL implementation can be found in the \mdl{traadv\_mus} module.
+
+MUSCL has been first implemented in \NEMO by \citet{Levy_al_GRL01}. In its formulation, the tracer at velocity points 
+is evaluated assuming a linear tracer variation between two $T$-points 
+(\autoref{fig:adv_scheme}). For example, in the $i$-direction :
+\begin{equation} \label{eq:tra_adv_mus}
+   \tau _u^{mus} = \left\{      \begin{aligned}
+         &\tau _i  &+ \frac{1}{2} \;\left( 1-\frac{u_{i+1/2} \;\rdt}{e_{1u}} \right)
+         &\ \widetilde{\partial _i \tau}  & \quad \text{if }\;u_{i+1/2} \geqslant 0      \\
+         &\tau _{i+1/2} &+\frac{1}{2}\;\left( 1+\frac{u_{i+1/2} \;\rdt}{e_{1u} } \right)
+         &\ \widetilde{\partial_{i+1/2} \tau } & \text{if }\;u_{i+1/2} <0
+   \end{aligned}    \right.
+\end{equation}
+where $\widetilde{\partial _i \tau}$ is the slope of the tracer on which a limitation 
+is imposed to ensure the \textit{positive} character of the scheme.
+
+The time stepping is performed using a forward scheme, that is the \textit{before} 
+tracer field is used to evaluate $\tau _u^{mus}$.
+
+For an ocean grid point adjacent to land and where the ocean velocity is 
+directed toward land, an upstream flux is used. This choice ensure 
+the \textit{positive} character of the scheme. 
+In addition, fluxes round a grid-point where a runoff is applied can optionally be 
+computed using upstream fluxes (\np{ln\_mus\_ups}\forcode{ = .true.}).
+
+% -------------------------------------------------------------------------------------------------------------
+%        UBS scheme  
+% -------------------------------------------------------------------------------------------------------------
+\subsection{UBS a.k.a. UP3: Upstream-Biased Scheme (\protect\np{ln\_traadv\_ubs}\forcode{ = .true.})}
+\label{subsec:TRA_adv_ubs}
+
+The Upstream-Biased Scheme (UBS) is used when \np{ln\_traadv\_ubs}\forcode{ = .true.}. 
+UBS implementation can be found in the \mdl{traadv\_mus} module.
+
+The UBS scheme, often called UP3, is also known as the Cell Averaged QUICK scheme 
+(Quadratic Upstream Interpolation for Convective Kinematics). It is an upstream-biased 
+third order scheme based on an upstream-biased parabolic interpolation.  
+For example, in the $i$-direction :
+\begin{equation} \label{eq:tra_adv_ubs}
+   \tau _u^{ubs} =\overline T ^{i+1/2}-\;\frac{1}{6} \left\{      
+   \begin{aligned}
+         &\tau"_i        	& \quad \text{if }\ u_{i+1/2} \geqslant 0      \\
+         &\tau"_{i+1}	& \quad \text{if }\ u_{i+1/2}       <       0
+   \end{aligned}    \right.
+\end{equation}
+where $\tau "_i =\delta _i \left[ {\delta _{i+1/2} \left[ \tau \right]} \right]$.
+
+This results in a dissipatively dominant (i.e. hyper-diffusive) truncation 
+error \citep{Shchepetkin_McWilliams_OM05}. The overall performance of
+ the advection scheme is similar to that reported in \cite{Farrow1995}. 
+It is a relatively good compromise between accuracy and smoothness. 
+Nevertheless the scheme is not \emph{positive}, meaning that false extrema are permitted, 
+but the amplitude of such are significantly reduced over the centred second 
+or fourth order method. therefore it is not recommended that it should be 
+applied to a passive tracer that requires positivity. 
+
+The intrinsic diffusion of UBS makes its use risky in the vertical direction 
+where the control of artificial diapycnal fluxes is of paramount importance \citep{Shchepetkin_McWilliams_OM05, Demange_PhD2014}. 
+Therefore the vertical flux is evaluated using either a $2^nd$ order FCT scheme 
+or a $4^th$ order COMPACT scheme (\np{nn\_cen\_v}\forcode{ = 2 or 4}).
+
+For stability reasons  (see \autoref{chap:STP}),
+the first term  in \autoref{eq:tra_adv_ubs} (which corresponds to a second order 
+centred scheme) is evaluated using the \textit{now} tracer (centred in time) 
+while the second term (which is the diffusive part of the scheme), is 
+evaluated using the \textit{before} tracer (forward in time). 
+This choice is discussed by \citet{Webb_al_JAOT98} in the context of the 
+QUICK advection scheme. UBS and QUICK schemes only differ 
+by one coefficient. Replacing 1/6 with 1/8 in \autoref{eq:tra_adv_ubs} 
+leads to the QUICK advection scheme \citep{Webb_al_JAOT98}. 
+This option is not available through a namelist parameter, since the 
+1/6 coefficient is hard coded. Nevertheless it is quite easy to make the 
+substitution in the \mdl{traadv\_ubs} module and obtain a QUICK scheme.
+
+Note that it is straightforward to rewrite \autoref{eq:tra_adv_ubs} as follows:
+\begin{equation} \label{eq:traadv_ubs2}
+\tau _u^{ubs} = \tau _u^{cen4} + \frac{1}{12} \left\{	 
+   \begin{aligned}
+	& + \tau"_i			& \quad \text{if }\ u_{i+1/2} \geqslant 0 \\
+	&  - \tau"_{i+1}		& \quad \text{if }\ u_{i+1/2}       <       0
+   \end{aligned}    \right.
+\end{equation}
+or equivalently 
+\begin{equation} \label{eq:traadv_ubs2b}
+u_{i+1/2} \ \tau _u^{ubs} 
+=u_{i+1/2} \ \overline{ T - \frac{1}{6}\,\delta _i\left[ \delta_{i+1/2}[T] \,\right] }^{\,i+1/2}
+- \frac{1}{2} |u|_{i+1/2} \;\frac{1}{6} \;\delta_{i+1/2}[\tau"_i]
+\end{equation}
+
+\autoref{eq:traadv_ubs2} has several advantages. Firstly, it clearly reveals 
+that the UBS scheme is based on the fourth order scheme to which an 
+upstream-biased diffusion term is added. Secondly, this emphasises that the 
+$4^{th}$ order part (as well as the $2^{nd}$ order part as stated above) has 
+to be evaluated at the \emph{now} time step using \autoref{eq:tra_adv_ubs}. 
+Thirdly, the diffusion term is in fact a biharmonic operator with an eddy 
+coefficient which is simply proportional to the velocity:
+ $A_u^{lm}= \frac{1}{12}\,{e_{1u}}^3\,|u|$. Note the current version of NEMO uses 
+the computationally more efficient formulation \autoref{eq:tra_adv_ubs}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        QCK scheme  
+% -------------------------------------------------------------------------------------------------------------
+\subsection{QCK: QuiCKest scheme (\protect\np{ln\_traadv\_qck}\forcode{ = .true.})}
+\label{subsec:TRA_adv_qck}
+
+The Quadratic Upstream Interpolation for Convective Kinematics with 
+Estimated Streaming Terms (QUICKEST) scheme proposed by \citet{Leonard1979} 
+is used when \np{ln\_traadv\_qck}\forcode{ = .true.}. 
+QUICKEST implementation can be found in the \mdl{traadv\_qck} module.
+
+QUICKEST is the third order Godunov scheme which is associated with the ULTIMATE QUICKEST 
+limiter \citep{Leonard1991}. It has been implemented in NEMO by G. Reffray 
+(MERCATOR-ocean) and can be found in the \mdl{traadv\_qck} module.
+The resulting scheme is quite expensive but \emph{positive}. 
+It can be used on both active and passive tracers. 
+However, the intrinsic diffusion of QCK makes its use risky in the vertical 
+direction where the control of artificial diapycnal fluxes is of paramount importance. 
+Therefore the vertical flux is evaluated using the CEN2 scheme. 
+This no longer guarantees the positivity of the scheme. 
+The use of FCT in the vertical direction (as for the UBS case) should be implemented 
+to restore this property.
+
+%%%gmcomment   :  Cross term are missing in the current implementation....
+
+
+% ================================================================
+% Tracer Lateral Diffusion
+% ================================================================
+\section{Tracer lateral diffusion (\protect\mdl{traldf})}
+\label{sec:TRA_ldf}
+%-----------------------------------------nam_traldf------------------------------------------------------
+
+\nlst{namtra_ldf}
+%-------------------------------------------------------------------------------------------------------------
+ 
+Options are defined through the \ngn{namtra\_ldf} namelist variables.
+They are regrouped in four items, allowing to specify 
+$(i)$   the type of operator used (none, laplacian, bilaplacian), 
+$(ii)$  the direction along which the operator acts (iso-level, horizontal, iso-neutral), 
+$(iii)$ some specific options related to the rotated operators ($i.e.$ non-iso-level operator), and 
+$(iv)$  the specification of eddy diffusivity coefficient (either constant or variable in space and time).
+Item $(iv)$ will be described in \autoref{chap:LDF} .
+The direction along which the operators act is defined through the slope between this direction and the iso-level surfaces.
+The slope is computed in the \mdl{ldfslp} module and will also be described in \autoref{chap:LDF}. 
+
+The lateral diffusion of tracers is evaluated using a forward scheme, 
+$i.e.$ the tracers appearing in its expression are the \textit{before} tracers in time, 
+except for the pure vertical component that appears when a rotation tensor is used. 
+This latter component is solved implicitly together with the vertical diffusion term (see \autoref{chap:STP}). 
+When \np{ln\_traldf\_msc}\forcode{ = .true.}, a Method of Stabilizing Correction is used in which 
+the pure vertical component is split into an explicit and an implicit part \citep{Lemarie_OM2012}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Type of operator
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Type of operator (\protect\np{ln\_traldf}\{\_NONE,\_lap,\_blp\}\})]
+			     {Type of operator (\protect\np{ln\_traldf\_NONE}, \protect\np{ln\_traldf\_lap}, or \protect\np{ln\_traldf\_blp}) } 
+\label{subsec:TRA_ldf_op}
+
+Three operator options are proposed and, one and only one of them must be selected:
+\begin{description}
+\item [\np{ln\_traldf\_NONE}\forcode{ = .true.}]: no operator selected, the lateral diffusive tendency will not be 
+applied to the tracer equation. This option can be used when the selected advection scheme 
+is diffusive enough (MUSCL scheme for example).
+\item [\np{ln\_traldf\_lap}\forcode{ = .true.}]: a laplacian operator is selected. This harmonic operator 
+takes the following expression:  $\mathpzc{L}(T)=\nabla \cdot A_{ht}\;\nabla T $, 
+where the gradient operates along the selected direction (see \autoref{subsec:TRA_ldf_dir}),
+and $A_{ht}$ is the eddy diffusivity coefficient expressed in $m^2/s$ (see \autoref{chap:LDF}).
+\item [\np{ln\_traldf\_blp}\forcode{ = .true.}]: a bilaplacian operator is selected. This biharmonic operator 
+takes the following expression:  
+$\mathpzc{B}=- \mathpzc{L}\left(\mathpzc{L}(T) \right) = -\nabla \cdot b\nabla \left( {\nabla \cdot b\nabla T} \right)$ 
+where the gradient operats along the selected direction,
+and $b^2=B_{ht}$ is the eddy diffusivity coefficient expressed in $m^4/s$  (see \autoref{chap:LDF}).
+In the code, the bilaplacian operator is obtained by calling the laplacian twice.
+\end{description}
+
+Both laplacian and bilaplacian operators ensure the total tracer variance decrease. 
+Their primary role is to provide strong dissipation at the smallest scale supported 
+by the grid while minimizing the impact on the larger scale features. 
+The main difference between the two operators is the scale selectiveness. 
+The bilaplacian damping time ($i.e.$ its spin down time) scales like $\lambda^{-4}$ 
+for disturbances of wavelength $\lambda$ (so that short waves damped more rapidelly than long ones), 
+whereas the laplacian damping time scales only like $\lambda^{-2}$.
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Direction of action
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Action direction (\protect\np{ln\_traldf}\{\_lev,\_hor,\_iso,\_triad\})]
+			     {Direction of action (\protect\np{ln\_traldf\_lev}, \protect\np{ln\_traldf\_hor}, \protect\np{ln\_traldf\_iso}, or \protect\np{ln\_traldf\_triad}) } 
+\label{subsec:TRA_ldf_dir}
+
+The choice of a direction of action determines the form of operator used. 
+The operator is a simple (re-entrant) laplacian acting in the (\textbf{i},\textbf{j}) plane 
+when iso-level option is used (\np{ln\_traldf\_lev}\forcode{ = .true.})
+or when a horizontal ($i.e.$ geopotential) operator is demanded in \textit{z}-coordinate 
+(\np{ln\_traldf\_hor} and \np{ln\_zco} equal \forcode{.true.}). 
+The associated code can be found in the \mdl{traldf\_lap\_blp} module.
+The operator is a rotated (re-entrant) laplacian when the direction along which it acts 
+does not coincide with the iso-level surfaces, 
+that is when standard or triad iso-neutral option is used (\np{ln\_traldf\_iso} or 
+ \np{ln\_traldf\_triad} equals \forcode{.true.}, see \mdl{traldf\_iso} or \mdl{traldf\_triad} module, resp.), 
+or when a horizontal ($i.e.$ geopotential) operator is demanded in \textit{s}-coordinate 
+(\np{ln\_traldf\_hor} and \np{ln\_sco} equal \forcode{.true.})
+\footnote{In this case, the standard iso-neutral operator will be automatically selected}. 
+In that case, a rotation is applied to the gradient(s) that appears in the operator 
+so that diffusive fluxes acts on the three spatial direction.
+
+The resulting discret form of the three operators (one iso-level and two rotated one) 
+is given in the next two sub-sections. 
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       iso-level operator
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Iso-level (bi-)laplacian operator ( \protect\np{ln\_traldf\_iso}) }
+\label{subsec:TRA_ldf_lev}
+
+The laplacian diffusion operator acting along the model (\textit{i,j})-surfaces is given by: 
+\begin{equation} \label{eq:tra_ldf_lap}
+D_t^{lT} =\frac{1}{b_t} \left( \;
+   \delta _{i}\left[ A_u^{lT} \; \frac{e_{2u}\,e_{3u}}{e_{1u}} \;\delta _{i+1/2} [T] \right] 
++ \delta _{j}\left[ A_v^{lT} \;  \frac{e_{1v}\,e_{3v}}{e_{2v}} \;\delta _{j+1/2} [T] \right]  \;\right)
+\end{equation}
+where  $b_t$=$e_{1t}\,e_{2t}\,e_{3t}$  is the volume of $T$-cells 
+and where zero diffusive fluxes is assumed across solid boundaries, 
+first (and third in bilaplacian case) horizontal tracer derivative are masked. 
+It is implemented in the \rou{traldf\_lap} subroutine found in the \mdl{traldf\_lap} module. 
+The module also contains \rou{traldf\_blp}, the subroutine calling twice \rou{traldf\_lap} 
+in order to compute the iso-level bilaplacian operator. 
+
+It is a \emph{horizontal} operator ($i.e.$ acting along geopotential surfaces) in the $z$-coordinate 
+with or without partial steps, but is simply an iso-level operator in the $s$-coordinate. 
+It is thus used when, in addition to \np{ln\_traldf\_lap} or \np{ln\_traldf\_blp}\forcode{ = .true.}, 
+we have \np{ln\_traldf\_lev}\forcode{ = .true.} or \np{ln\_traldf\_hor}~=~\np{ln\_zco}\forcode{ = .true.}. 
+In both cases, it significantly contributes to diapycnal mixing. 
+It is therefore never recommended, even when using it in the bilaplacian case.
+
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), tracers in horizontally 
+adjacent cells are located at different depths in the vicinity of the bottom. 
+In this case, horizontal derivatives in (\autoref{eq:tra_ldf_lap}) at the bottom level 
+require a specific treatment. They are calculated in the \mdl{zpshde} module, 
+described in \autoref{sec:TRA_zpshde}.
+
+
+% -------------------------------------------------------------------------------------------------------------
+%         Rotated laplacian operator
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Standard and triad (bi-)laplacian operator}
+\label{subsec:TRA_ldf_iso_triad}
+
+%&&    Standard rotated (bi-)laplacian operator
+%&& ----------------------------------------------
+\subsubsection{Standard rotated (bi-)laplacian operator (\protect\mdl{traldf\_iso})}
+\label{subsec:TRA_ldf_iso}
+The general form of the second order lateral tracer subgrid scale physics 
+(\autoref{eq:PE_zdf}) takes the following semi-discrete space form in $z$- and $s$-coordinates:
+\begin{equation} \label{eq:tra_ldf_iso}
+\begin{split}
+ D_T^{lT} = \frac{1}{b_t}   & \left\{   \,\;\delta_i \left[   A_u^{lT}  \left( 
+	  \frac{e_{2u}\,e_{3u}}{e_{1u}} \,\delta_{i+1/2}[T]
+	- e_{2u}\;r_{1u} \,\overline{\overline{ \delta_{k+1/2}[T] }}^{\,i+1/2,k}
+                                                     \right)   \right]   \right.    \\ 
+&             +\delta_j \left[ A_v^{lT} \left( 
+          \frac{e_{1v}\,e_{3v}}{e_{2v}}  \,\delta_{j+1/2} [T] 
+        - e_{1v}\,r_{2v} \,\overline{\overline{ \delta_{k+1/2} [T] }}^{\,j+1/2,k} 
+                                                    \right)   \right]                 \\ 
+& +\delta_k \left[ A_w^{lT} \left( 
+       -\;e_{2w}\,r_{1w} \,\overline{\overline{ \delta_{i+1/2} [T] }}^{\,i,k+1/2}
+                                                    \right.   \right.                 \\ 
+& \qquad \qquad \quad 
+        - e_{1w}\,r_{2w} \,\overline{\overline{ \delta_{j+1/2} [T] }}^{\,j,k+1/2}     \\
+& \left. {\left. {   \qquad \qquad \ \ \ \left. {
+        +\;\frac{e_{1w}\,e_{2w}}{e_{3w}} \,\left( r_{1w}^2 + r_{2w}^2 \right)
+           \,\delta_{k+1/2} [T] } \right) } \right] \quad } \right\} 
+ \end{split}
+ \end{equation}
+where $b_t$=$e_{1t}\,e_{2t}\,e_{3t}$  is the volume of $T$-cells, 
+$r_1$ and $r_2$ are the slopes between the surface of computation 
+($z$- or $s$-surfaces) and the surface along which the diffusion operator 
+acts ($i.e.$ horizontal or iso-neutral surfaces).  It is thus used when, 
+in addition to \np{ln\_traldf\_lap}\forcode{ = .true.}, we have \np{ln\_traldf\_iso}\forcode{ = .true.}, 
+or both \np{ln\_traldf\_hor}\forcode{ = .true.} and \np{ln\_zco}\forcode{ = .true.}. The way these 
+slopes are evaluated is given in \autoref{sec:LDF_slp}. At the surface, bottom 
+and lateral boundaries, the turbulent fluxes of heat and salt are set to zero 
+using the mask technique (see \autoref{sec:LBC_coast}). 
+
+The operator in \autoref{eq:tra_ldf_iso} involves both lateral and vertical 
+derivatives. For numerical stability, the vertical second derivative must 
+be solved using the same implicit time scheme as that used in the vertical 
+physics (see \autoref{sec:TRA_zdf}). For computer efficiency reasons, this term 
+is not computed in the \mdl{traldf\_iso} module, but in the \mdl{trazdf} module 
+where, if iso-neutral mixing is used, the vertical mixing coefficient is simply 
+increased by $\frac{e_{1w}\,e_{2w} }{e_{3w} }\ \left( {r_{1w} ^2+r_{2w} ^2} \right)$. 
+
+This formulation conserves the tracer but does not ensure the decrease 
+of the tracer variance. Nevertheless the treatment performed on the slopes 
+(see \autoref{chap:LDF}) allows the model to run safely without any additional 
+background horizontal diffusion \citep{Guilyardi_al_CD01}. 
+
+Note that in the partial step $z$-coordinate (\np{ln\_zps}\forcode{ = .true.}), the horizontal derivatives 
+at the bottom level in \autoref{eq:tra_ldf_iso} require a specific treatment. 
+They are calculated in module zpshde, described in \autoref{sec:TRA_zpshde}.
+
+%&&     Triad rotated (bi-)laplacian operator
+%&&  -------------------------------------------
+\subsubsection{Triad rotated (bi-)laplacian operator (\protect\np{ln\_traldf\_triad})}
+\label{subsec:TRA_ldf_triad}
+
+If the Griffies triad scheme is employed (\np{ln\_traldf\_triad}\forcode{ = .true.} ; see \autoref{apdx:triad}) 
+
+An alternative scheme developed by \cite{Griffies_al_JPO98} which ensures tracer variance decreases 
+is also available in \NEMO (\np{ln\_traldf\_grif}\forcode{ = .true.}). A complete description of 
+the algorithm is given in \autoref{apdx:triad}.
+
+The lateral fourth order bilaplacian operator on tracers is obtained by 
+applying (\autoref{eq:tra_ldf_lap}) twice. The operator requires an additional assumption 
+on boundary conditions: both first and third derivative terms normal to the 
+coast are set to zero.
+
+The lateral fourth order operator formulation on tracers is obtained by 
+applying (\autoref{eq:tra_ldf_iso}) twice. It requires an additional assumption 
+on boundary conditions: first and third derivative terms normal to the 
+coast, normal to the bottom and normal to the surface are set to zero. 
+
+%&&    Option for the rotated operators
+%&& ----------------------------------------------
+\subsubsection{Option for the rotated operators}
+\label{subsec:TRA_ldf_options}
+
+\np{ln\_traldf\_msc} = Method of Stabilizing Correction (both operators)
+
+\np{rn\_slpmax} = slope limit (both operators)
+
+\np{ln\_triad\_iso} = pure horizontal mixing in ML (triad only)
+
+\np{rn\_sw\_triad} =1 switching triad ; =0 all 4 triads used (triad only) 
+
+\np{ln\_botmix\_triad} = lateral mixing on bottom (triad only)
+
+% ================================================================
+% Tracer Vertical Diffusion
+% ================================================================
+\section{Tracer vertical diffusion (\protect\mdl{trazdf})}
+\label{sec:TRA_zdf}
+%--------------------------------------------namzdf---------------------------------------------------------
+
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namzdf} namelist variables.
+The formulation of the vertical subgrid scale tracer physics is the same 
+for all the vertical coordinates, and is based on a laplacian operator. 
+The vertical diffusion operator given by (\autoref{eq:PE_zdf}) takes the 
+following semi-discrete space form:
+\begin{equation} \label{eq:tra_zdf}
+\begin{split}
+D^{vT}_T &= \frac{1}{e_{3t}} \; \delta_k \left[ \;\frac{A^{vT}_w}{e_{3w}}  \delta_{k+1/2}[T] \;\right] 
+\\
+D^{vS}_T &= \frac{1}{e_{3t}} \; \delta_k \left[ \;\frac{A^{vS}_w}{e_{3w}}  \delta_{k+1/2}[S] \;\right] 
+\end{split}
+\end{equation}
+where $A_w^{vT}$ and $A_w^{vS}$ are the vertical eddy diffusivity 
+coefficients on temperature and salinity, respectively. Generally, 
+$A_w^{vT}=A_w^{vS}$ except when double diffusive mixing is 
+parameterised ($i.e.$ \key{zdfddm} is defined). The way these coefficients 
+are evaluated is given in \autoref{chap:ZDF} (ZDF). Furthermore, when 
+iso-neutral mixing is used, both mixing coefficients are increased 
+by $\frac{e_{1w}\,e_{2w} }{e_{3w} }\ \left( {r_{1w} ^2+r_{2w} ^2} \right)$ 
+to account for the vertical second derivative of \autoref{eq:tra_ldf_iso}. 
+
+At the surface and bottom boundaries, the turbulent fluxes of 
+heat and salt must be specified. At the surface they are prescribed 
+from the surface forcing and added in a dedicated routine (see \autoref{subsec:TRA_sbc}), 
+whilst at the bottom they are set to zero for heat and salt unless 
+a geothermal flux forcing is prescribed as a bottom boundary 
+condition (see \autoref{subsec:TRA_bbc}). 
+
+The large eddy coefficient found in the mixed layer together with high 
+vertical resolution implies that in the case of explicit time stepping 
+(\np{ln\_zdfexp}\forcode{ = .true.}) there would be too restrictive a constraint on 
+the time step. Therefore, the default implicit time stepping is preferred 
+for the vertical diffusion since it overcomes the stability constraint. 
+A forward time differencing scheme (\np{ln\_zdfexp}\forcode{ = .true.}) using a time 
+splitting technique (\np{nn\_zdfexp} $> 1$) is provided as an alternative. 
+Namelist variables \np{ln\_zdfexp} and \np{nn\_zdfexp} apply to both 
+tracers and dynamics. 
+
+% ================================================================
+% External Forcing
+% ================================================================
+\section{External forcing}
+\label{sec:TRA_sbc_qsr_bbc}
+
+% -------------------------------------------------------------------------------------------------------------
+%        surface boundary condition
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Surface boundary condition (\protect\mdl{trasbc})}
+\label{subsec:TRA_sbc}
+
+The surface boundary condition for tracers is implemented in a separate 
+module (\mdl{trasbc}) instead of entering as a boundary condition on the vertical 
+diffusion operator (as in the case of momentum). This has been found to 
+enhance readability of the code. The two formulations are completely 
+equivalent; the forcing terms in trasbc are the surface fluxes divided by 
+the thickness of the top model layer. 
+
+Due to interactions and mass exchange of water ($F_{mass}$) with other Earth system components 
+($i.e.$ atmosphere, sea-ice, land), the change in the heat and salt content of the surface layer 
+of the ocean is due both to the heat and salt fluxes crossing the sea surface (not linked with $F_{mass}$) 
+and to the heat and salt content of the mass exchange. They are both included directly in $Q_{ns}$, 
+the surface heat flux, and $F_{salt}$, the surface salt flux (see \autoref{chap:SBC} for further details).
+By doing this, the forcing formulation is the same for any tracer (including temperature and salinity).
+
+The surface module (\mdl{sbcmod}, see \autoref{chap:SBC}) provides the following 
+forcing fields (used on tracers):
+
+$\bullet$ $Q_{ns}$, the non-solar part of the net surface heat flux that crosses the sea surface 
+(i.e. the difference between the total surface heat flux and the fraction of the short wave flux that 
+penetrates into the water column, see \autoref{subsec:TRA_qsr}) plus the heat content associated with 
+of the mass exchange with the atmosphere and lands.
+
+$\bullet$ $\textit{sfx}$, the salt flux resulting from ice-ocean mass exchange (freezing, melting, ridging...)
+
+$\bullet$ \textit{emp}, the mass flux exchanged with the atmosphere (evaporation minus precipitation) 
+ and possibly with the sea-ice and ice-shelves.
+
+$\bullet$ \textit{rnf}, the mass flux associated with runoff 
+(see \autoref{sec:SBC_rnf} for further detail of how it acts on temperature and salinity tendencies)
+
+$\bullet$ \textit{fwfisf}, the mass flux associated with ice shelf melt, 
+(see \autoref{sec:SBC_isf} for further details on how the ice shelf melt is computed and applied).
+
+The surface boundary condition on temperature and salinity is applied as follows:
+\begin{equation} \label{eq:tra_sbc}
+\begin{aligned}
+ &F^T = \frac{ 1 }{\rho _o \;C_p \,\left. e_{3t} \right|_{k=1} }  &\overline{ Q_{ns}       }^t  & \\ 
+& F^S =\frac{ 1 }{\rho _o  \,      \left. e_{3t} \right|_{k=1} }  &\overline{ \textit{sfx} }^t   & \\   
+ \end{aligned}
+\end{equation} 
+where $\overline{x }^t$ means that $x$ is averaged over two consecutive time steps 
+($t-\rdt/2$ and $t+\rdt/2$). Such time averaging prevents the 
+divergence of odd and even time step (see \autoref{chap:STP}).
+
+In the linear free surface case (\np{ln\_linssh}\forcode{ = .true.}), 
+an additional term has to be added on both temperature and salinity. 
+On temperature, this term remove the heat content associated with mass exchange
+that has been added to $Q_{ns}$. On salinity, this term mimics the concentration/dilution effect that
+would have resulted from a change in the volume of the first level.
+The resulting surface boundary condition is applied as follows:
+\begin{equation} \label{eq:tra_sbc_lin}
+\begin{aligned}
+ &F^T = \frac{ 1 }{\rho _o \;C_p \,\left. e_{3t} \right|_{k=1} }   
+           &\overline{ \left( Q_{ns} - \textit{emp}\;C_p\,\left. T \right|_{k=1} \right) }^t  & \\ 
+%
+& F^S =\frac{ 1 }{\rho _o \,\left. e_{3t} \right|_{k=1} } 
+           &\overline{ \left( \;\textit{sfx} - \textit{emp} \;\left. S \right|_{k=1}  \right) }^t   & \\   
+ \end{aligned}
+\end{equation} 
+Note that an exact conservation of heat and salt content is only achieved with non-linear free surface. 
+In the linear free surface case, there is a small imbalance. The imbalance is larger 
+than the imbalance associated with the Asselin time filter \citep{Leclair_Madec_OM09}. 
+This is the reason why the modified filter is not applied in the linear free surface case (see \autoref{chap:STP}).
+
+% -------------------------------------------------------------------------------------------------------------
+%        Solar Radiation Penetration 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Solar radiation penetration (\protect\mdl{traqsr})}
+\label{subsec:TRA_qsr}
+%--------------------------------------------namqsr--------------------------------------------------------
+
+\nlst{namtra_qsr}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the \ngn{namtra\_qsr} namelist variables.
+When the penetrative solar radiation option is used (\np{ln\_flxqsr}\forcode{ = .true.}), 
+the solar radiation penetrates the top few tens of meters of the ocean. If it is not used 
+(\np{ln\_flxqsr}\forcode{ = .false.}) all the heat flux is absorbed in the first ocean level. 
+Thus, in the former case a term is added to the time evolution equation of 
+temperature \autoref{eq:PE_tra_T} and the surface boundary condition is 
+modified to take into account only the non-penetrative part of the surface 
+heat flux:
+\begin{equation} \label{eq:PE_qsr}
+\begin{split}
+\frac{\partial T}{\partial t} &= {\ldots} + \frac{1}{\rho_o\, C_p \,e_3} \; \frac{\partial I}{\partial k}	\\
+Q_{ns} &= Q_\text{Total} - Q_{sr}
+\end{split}
+\end{equation}
+where $Q_{sr}$ is the penetrative part of the surface heat flux ($i.e.$ the shortwave radiation) 
+and $I$ is the downward irradiance ($\left. I \right|_{z=\eta}=Q_{sr}$). 
+The additional term in \autoref{eq:PE_qsr} is discretized as follows:
+\begin{equation} \label{eq:tra_qsr}
+\frac{1}{\rho_o\, C_p \,e_3} \; \frac{\partial I}{\partial k} \equiv \frac{1}{\rho_o\, C_p\, e_{3t}} \delta_k \left[ I_w \right]
+\end{equation}
+
+The shortwave radiation, $Q_{sr}$, consists of energy distributed across a wide spectral range. 
+The ocean is strongly absorbing for wavelengths longer than 700~nm and these 
+wavelengths contribute to heating the upper few tens of centimetres. The fraction of $Q_{sr}$ 
+that resides in these almost non-penetrative wavebands, $R$, is $\sim 58\%$ (specified 
+through namelist parameter \np{rn\_abs}). It is assumed to penetrate the ocean 
+with a decreasing exponential profile, with an e-folding depth scale, $\xi_0$, 
+of a few tens of centimetres (typically $\xi_0=0.35~m$ set as \np{rn\_si0} in the \ngn{namtra\_qsr} namelist).
+For shorter wavelengths (400-700~nm), the ocean is more transparent, and solar energy 
+propagates to larger depths where it contributes to 
+local heating. 
+The way this second part of the solar energy penetrates into the ocean depends on 
+which formulation is chosen. In the simple 2-waveband light penetration scheme (\np{ln\_qsr\_2bd}\forcode{ = .true.}) 
+a chlorophyll-independent monochromatic formulation is chosen for the shorter wavelengths, 
+leading to the following expression \citep{Paulson1977}:
+\begin{equation} \label{eq:traqsr_iradiance}
+I(z) = Q_{sr} \left[Re^{-z / \xi_0} + \left( 1-R\right) e^{-z / \xi_1} \right]
+\end{equation}
+where $\xi_1$ is the second extinction length scale associated with the shorter wavelengths.  
+It is usually chosen to be 23~m by setting the \np{rn\_si0} namelist parameter. 
+The set of default values ($\xi_0$, $\xi_1$, $R$) corresponds to a Type I water in 
+Jerlov's (1968) classification (oligotrophic waters).
+
+Such assumptions have been shown to provide a very crude and simplistic 
+representation of observed light penetration profiles (\cite{Morel_JGR88}, see also 
+\autoref{fig:traqsr_irradiance}). Light absorption in the ocean depends on 
+particle concentration and is spectrally selective. \cite{Morel_JGR88} has shown 
+that an accurate representation of light penetration can be provided by a 61 waveband 
+formulation. Unfortunately, such a model is very computationally expensive. 
+Thus, \cite{Lengaigne_al_CD07} have constructed a simplified version of this 
+formulation in which visible light is split into three wavebands: blue (400-500 nm), 
+green (500-600 nm) and red (600-700nm). For each wave-band, the chlorophyll-dependent 
+attenuation coefficient is fitted to the coefficients computed from the full spectral model 
+of \cite{Morel_JGR88} (as modified by \cite{Morel_Maritorena_JGR01}), assuming 
+the same power-law relationship. As shown in \autoref{fig:traqsr_irradiance}, 
+this formulation, called RGB (Red-Green-Blue), reproduces quite closely 
+the light penetration profiles predicted by the full spectal model, but with much greater 
+computational efficiency. The 2-bands formulation does not reproduce the full model very well. 
+
+The RGB formulation is used when \np{ln\_qsr\_rgb}\forcode{ = .true.}. The RGB attenuation coefficients
+($i.e.$ the inverses of the extinction length scales) are tabulated over 61 nonuniform 
+chlorophyll classes ranging from 0.01 to 10 g.Chl/L (see the routine \rou{trc\_oce\_rgb} 
+in \mdl{trc\_oce} module). Four types of chlorophyll can be chosen in the RGB formulation:
+\begin{description} 
+\item[\np{nn\_chdta}\forcode{ = 0}] 
+a constant 0.05 g.Chl/L value everywhere ; 
+\item[\np{nn\_chdta}\forcode{ = 1}]  
+an observed time varying chlorophyll deduced from satellite surface ocean color measurement 
+spread uniformly in the vertical direction ; 
+\item[\np{nn\_chdta}\forcode{ = 2}]  
+same as previous case except that a vertical profile of chlorophyl is used. 
+Following \cite{Morel_Berthon_LO89}, the profile is computed from the local surface chlorophyll value ;
+\item[\np{ln\_qsr\_bio}\forcode{ = .true.}]  
+simulated time varying chlorophyll by TOP biogeochemical model. 
+In this case, the RGB formulation is used to calculate both the phytoplankton 
+light limitation in PISCES or LOBSTER and the oceanic heating rate. 
+\end{description} 
+The trend in \autoref{eq:tra_qsr} associated with the penetration of the solar radiation 
+is added to the temperature trend, and the surface heat flux is modified in routine \mdl{traqsr}. 
+
+When the $z$-coordinate is preferred to the $s$-coordinate, the depth of $w-$levels does 
+not significantly vary with location. The level at which the light has been totally 
+absorbed ($i.e.$ it is less than the computer precision) is computed once, 
+and the trend associated with the penetration of the solar radiation is only added down to that level. 
+Finally, note that when the ocean is shallow ($<$ 200~m), part of the 
+solar radiation can reach the ocean floor. In this case, we have 
+chosen that all remaining radiation is absorbed in the last ocean 
+level ($i.e.$ $I$ is masked). 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	  \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_TRA_Irradiance}
+\caption{ 	 \protect\label{fig:traqsr_irradiance}
+Penetration profile of the downward solar irradiance calculated by four models. 
+Two waveband chlorophyll-independent formulation (blue), a chlorophyll-dependent 
+monochromatic formulation (green), 4 waveband RGB formulation (red), 
+61 waveband Morel (1988) formulation (black) for a chlorophyll concentration of 
+(a) Chl=0.05 mg/m$^3$ and (b) Chl=0.5 mg/m$^3$. From \citet{Lengaigne_al_CD07}.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        Bottom Boundary Condition
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Bottom boundary condition (\protect\mdl{trabbc})}
+\label{subsec:TRA_bbc}
+%--------------------------------------------nambbc--------------------------------------------------------
+
+\nlst{nambbc}
+%--------------------------------------------------------------------------------------------------------------
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	  \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_TRA_geoth}
+\caption{ 	\protect\label{fig:geothermal}
+Geothermal Heat flux (in $mW.m^{-2}$) used by \cite{Emile-Geay_Madec_OS09}.
+It is inferred from the age of the sea floor and the formulae of \citet{Stein_Stein_Nat92}.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Usually it is assumed that there is no exchange of heat or salt through 
+the ocean bottom, $i.e.$ a no flux boundary condition is applied on active 
+tracers at the bottom. This is the default option in \NEMO, and it is 
+implemented using the masking technique. However, there is a 
+non-zero heat flux across the seafloor that is associated with solid 
+earth cooling. This flux is weak compared to surface fluxes (a mean 
+global value of $\sim0.1\;W/m^2$ \citep{Stein_Stein_Nat92}), but it warms 
+systematically the ocean and acts on the densest water masses. 
+Taking this flux into account in a global ocean model increases
+the deepest overturning cell ($i.e.$ the one associated with the Antarctic 
+Bottom Water) by a few Sverdrups  \citep{Emile-Geay_Madec_OS09}. 
+
+Options are defined through the  \ngn{namtra\_bbc} namelist variables.
+The presence of geothermal heating is controlled by setting the namelist 
+parameter  \np{ln\_trabbc} to true. Then, when \np{nn\_geoflx} is set to 1, 
+a constant geothermal heating is introduced whose value is given by the 
+\np{nn\_geoflx\_cst}, which is also a namelist parameter. 
+When  \np{nn\_geoflx} is set to 2, a spatially varying geothermal heat flux is 
+introduced which is provided in the \ifile{geothermal\_heating} NetCDF file 
+(\autoref{fig:geothermal}) \citep{Emile-Geay_Madec_OS09}.
+
+% ================================================================
+% Bottom Boundary Layer
+% ================================================================
+\section{Bottom boundary layer (\protect\mdl{trabbl} - \protect\key{trabbl})}
+\label{sec:TRA_bbl}
+%--------------------------------------------nambbl---------------------------------------------------------
+
+\nlst{nambbl}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{nambbl} namelist variables.
+In a $z$-coordinate configuration, the bottom topography is represented by a 
+series of discrete steps. This is not adequate to represent gravity driven 
+downslope flows. Such flows arise either downstream of sills such as the Strait of 
+Gibraltar or Denmark Strait, where dense water formed in marginal seas flows 
+into a basin filled with less dense water, or along the continental slope when dense 
+water masses are formed on a continental shelf. The amount of entrainment 
+that occurs in these gravity plumes is critical in determining the density 
+and volume flux of the densest waters of the ocean, such as Antarctic Bottom Water, 
+or North Atlantic Deep Water. $z$-coordinate models tend to overestimate the 
+entrainment, because the gravity flow is mixed vertically by convection 
+as it goes ''downstairs'' following the step topography, sometimes over a thickness 
+much larger than the thickness of the observed gravity plume. A similar problem 
+occurs in the $s$-coordinate when the thickness of the bottom level varies rapidly 
+downstream of a sill \citep{Willebrand_al_PO01}, and the thickness 
+of the plume is not resolved. 
+
+The idea of the bottom boundary layer (BBL) parameterisation, first introduced by 
+\citet{Beckmann_Doscher1997}, is to allow a direct communication between 
+two adjacent bottom cells at different levels, whenever the densest water is 
+located above the less dense water. The communication can be by a diffusive flux
+(diffusive BBL), an advective flux (advective BBL), or both. In the current 
+implementation of the BBL, only the tracers are modified, not the velocities. 
+Furthermore, it only connects ocean bottom cells, and therefore does not include 
+all the improvements introduced by \citet{Campin_Goosse_Tel99}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Diffusive BBL
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Diffusive bottom boundary layer (\protect\np{nn\_bbl\_ldf}\forcode{ = 1})}
+\label{subsec:TRA_bbl_diff}
+
+When applying sigma-diffusion (\key{trabbl} defined and \np{nn\_bbl\_ldf} set to 1), 
+the diffusive flux between two adjacent cells at the ocean floor is given by 
+\begin{equation} \label{eq:tra_bbl_diff}
+{\rm {\bf F}}_\sigma=A_l^\sigma \; \nabla_\sigma T
+\end{equation} 
+with $\nabla_\sigma$ the lateral gradient operator taken between bottom cells, 
+and  $A_l^\sigma$ the lateral diffusivity in the BBL. Following \citet{Beckmann_Doscher1997}, 
+the latter is prescribed with a spatial dependence, $i.e.$ in the conditional form
+\begin{equation} \label{eq:tra_bbl_coef}
+A_l^\sigma (i,j,t)=\left\{ {\begin{array}{l}
+ A_{bbl}  \quad \quad   \mbox{if}  \quad   \nabla_\sigma \rho  \cdot  \nabla H<0 \\ 
+ \\
+ 0\quad \quad \;\,\mbox{otherwise} \\ 
+ \end{array}} \right.
+\end{equation} 
+where $A_{bbl}$ is the BBL diffusivity coefficient, given by the namelist 
+parameter \np{rn\_ahtbbl} and usually set to a value much larger 
+than the one used for lateral mixing in the open ocean. The constraint in \autoref{eq:tra_bbl_coef} 
+implies that sigma-like diffusion only occurs when the density above the sea floor, at the top of 
+the slope, is larger than in the deeper ocean (see green arrow in \autoref{fig:bbl}). 
+In practice, this constraint is applied separately in the two horizontal directions, 
+and the density gradient in \autoref{eq:tra_bbl_coef} is evaluated with the log gradient formulation: 
+\begin{equation} \label{eq:tra_bbl_Drho}
+	\nabla_\sigma \rho / \rho = \alpha \,\nabla_\sigma T + \beta   \,\nabla_\sigma S
+\end{equation} 
+where $\rho$, $\alpha$ and $\beta$ are functions of $\overline{T}^\sigma$, 
+$\overline{S}^\sigma$ and $\overline{H}^\sigma$, the along bottom mean temperature, 
+salinity and depth, respectively.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Advective BBL
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Advective bottom boundary layer  (\protect\np{nn\_bbl\_adv}\forcode{ = 1..2})}
+\label{subsec:TRA_bbl_adv}
+
+\sgacomment{"downsloping flow" has been replaced by "downslope flow" in the following
+if this is not what is meant then "downwards sloping flow" is also a possibility"}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	\begin{center}
+\includegraphics[width=0.7\textwidth]{Fig_BBL_adv}
+\caption{ 	\protect\label{fig:bbl}  
+Advective/diffusive Bottom Boundary Layer. The BBL parameterisation is 
+activated when $\rho^i_{kup}$ is larger than $\rho^{i+1}_{kdnw}$. 
+Red arrows indicate the additional overturning circulation due to the advective BBL. 
+The transport of the downslope flow is defined either as the transport of the bottom 
+ocean cell (black arrow), or as a function of the along slope density gradient. 
+The green arrow indicates the diffusive BBL flux directly connecting $kup$ and $kdwn$
+ocean bottom cells.
+connection}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+%!!      nn_bbl_adv = 1   use of the ocean velocity as bbl velocity
+%!!      nn_bbl_adv = 2   follow Campin and Goosse (1999) implentation
+%!!        i.e. transport proportional to the along-slope density gradient
+
+%%%gmcomment   :  this section has to be really written
+
+When applying an advective BBL (\np{nn\_bbl\_adv}\forcode{ = 1..2}), an overturning 
+circulation is added which connects two adjacent bottom grid-points only if dense 
+water overlies less dense water on the slope. The density difference causes dense 
+water to move down the slope. 
+
+\np{nn\_bbl\_adv}\forcode{ = 1} : the downslope velocity is chosen to be the Eulerian
+ocean velocity just above the topographic step (see black arrow in \autoref{fig:bbl}) 
+\citep{Beckmann_Doscher1997}. It is a \textit{conditional advection}, that is, advection
+is allowed only if dense water overlies less dense water on the slope ($i.e.$ 
+$\nabla_\sigma \rho  \cdot  \nabla H<0$) and if the velocity is directed towards 
+greater depth ($i.e.$ $\vect{U}  \cdot  \nabla H>0$).
+
+\np{nn\_bbl\_adv}\forcode{ = 2} : the downslope velocity is chosen to be proportional to $\Delta \rho$,
+the density difference between the higher cell and lower cell densities \citep{Campin_Goosse_Tel99}.
+The advection is allowed only  if dense water overlies less dense water on the slope ($i.e.$ 
+$\nabla_\sigma \rho  \cdot  \nabla H<0$). For example, the resulting transport of the 
+downslope flow, here in the $i$-direction (\autoref{fig:bbl}), is simply given by the 
+following expression:
+\begin{equation} \label{eq:bbl_Utr}
+ u^{tr}_{bbl} = \gamma \, g \frac{\Delta \rho}{\rho_o}  e_{1u} \; min \left( {e_{3u}}_{kup},{e_{3u}}_{kdwn} \right)
+\end{equation}
+where $\gamma$, expressed in seconds, is the coefficient of proportionality 
+provided as \np{rn\_gambbl}, a namelist parameter, and \textit{kup} and \textit{kdwn} 
+are the vertical index of the higher and lower cells, respectively.
+The parameter $\gamma$ should take a different value for each bathymetric 
+step, but for simplicity, and because no direct estimation of this parameter is 
+available, a uniform value has been assumed. The possible values for $\gamma$ 
+range between 1 and $10~s$ \citep{Campin_Goosse_Tel99}.  
+
+Scalar properties are advected by this additional transport $( u^{tr}_{bbl}, v^{tr}_{bbl} )$ 
+using the upwind scheme. Such a diffusive advective scheme has been chosen 
+to mimic the entrainment between the downslope plume and the surrounding 
+water at intermediate depths. The entrainment is replaced by the vertical mixing 
+implicit in the advection scheme. Let us consider as an example the 
+case displayed in \autoref{fig:bbl} where the density at level $(i,kup)$ is 
+larger than the one at level $(i,kdwn)$. The advective BBL scheme
+modifies the tracer time tendency of the ocean cells near the 
+topographic step by the downslope flow \autoref{eq:bbl_dw}, 
+the horizontal \autoref{eq:bbl_hor} and the upward \autoref{eq:bbl_up} 
+return flows as follows: 
+\begin{align} 
+\partial_t T^{do}_{kdw} &\equiv \partial_t T^{do}_{kdw}
+                                     +  \frac{u^{tr}_{bbl}}{{b_t}^{do}_{kdw}}  \left( T^{sh}_{kup} - T^{do}_{kdw} \right)  \label{eq:bbl_dw} \\
+%
+\partial_t T^{sh}_{kup} &\equiv \partial_t T^{sh}_{kup} 
+				   + \frac{u^{tr}_{bbl}}{{b_t}^{sh}_{kup}}   \left( T^{do}_{kup} - T^{sh}_{kup} \right)   \label{eq:bbl_hor} \\
+%
+\intertext{and for $k =kdw-1,\;..., \; kup$ :} 
+%
+\partial_t T^{do}_{k} &\equiv \partial_t S^{do}_{k}
+				   + \frac{u^{tr}_{bbl}}{{b_t}^{do}_{k}}   \left( T^{do}_{k+1} - T^{sh}_{k} \right)   \label{eq:bbl_up}
+\end{align}
+where $b_t$ is the $T$-cell volume. 
+
+Note that the BBL transport, $( u^{tr}_{bbl}, v^{tr}_{bbl} )$, is available in 
+the model outputs. It has to be used to compute the effective velocity 
+as well as the effective overturning circulation.
+
+% ================================================================
+% Tracer damping
+% ================================================================
+\section{Tracer damping (\protect\mdl{tradmp})}
+\label{sec:TRA_dmp}
+%--------------------------------------------namtra_dmp-------------------------------------------------
+
+\nlst{namtra_dmp}
+%--------------------------------------------------------------------------------------------------------------
+
+In some applications it can be useful to add a Newtonian damping term 
+into the temperature and salinity equations:
+\begin{equation} \label{eq:tra_dmp}
+\begin{split}
+ \frac{\partial T}{\partial t}=\;\cdots \;-\gamma \,\left( {T-T_o } \right)  \\
+ \frac{\partial S}{\partial t}=\;\cdots \;-\gamma \,\left( {S-S_o } \right) 
+ \end{split}
+ \end{equation} 
+where $\gamma$ is the inverse of a time scale, and $T_o$ and $S_o$ 
+are given temperature and salinity fields (usually a climatology). 
+Options are defined through the  \ngn{namtra\_dmp} namelist variables.
+The restoring term is added when the namelist parameter \np{ln\_tradmp} is set to true. 
+It also requires that both \np{ln\_tsd\_init} and \np{ln\_tsd\_tradmp} are set to true
+in \textit{namtsd} namelist as well as \np{sn\_tem} and \np{sn\_sal} structures are 
+correctly set  ($i.e.$ that $T_o$ and $S_o$ are provided in input files and read 
+using \mdl{fldread}, see \autoref{subsec:SBC_fldread}). 
+The restoring coefficient $\gamma$ is a three-dimensional array read in during the \rou{tra\_dmp\_init} routine. The file name is specified by the namelist variable \np{cn\_resto}. The DMP\_TOOLS tool is provided to allow users to generate the netcdf file.
+
+The two main cases in which \autoref{eq:tra_dmp} is used are \textit{(a)} 
+the specification of the boundary conditions along artificial walls of a 
+limited domain basin and \textit{(b)} the computation of the velocity 
+field associated with a given $T$-$S$ field (for example to build the 
+initial state of a prognostic simulation, or to use the resulting velocity 
+field for a passive tracer study). The first case applies to regional 
+models that have artificial walls instead of open boundaries. 
+In the vicinity of these walls, $\gamma$ takes large values (equivalent to 
+a time scale of a few days) whereas it is zero in the interior of the 
+model domain. The second case corresponds to the use of the robust 
+diagnostic method \citep{Sarmiento1982}. It allows us to find the velocity 
+field consistent with the model dynamics whilst having a $T$, $S$ field 
+close to a given climatological field ($T_o$, $S_o$). 
+
+The robust diagnostic method is very efficient in preventing temperature 
+drift in intermediate waters but it produces artificial sources of heat and salt 
+within the ocean. It also has undesirable effects on the ocean convection. 
+It tends to prevent deep convection and subsequent deep-water formation, 
+by stabilising the water column too much.
+
+The namelist parameter \np{nn\_zdmp} sets whether the damping should be applied in the whole water column or only below the mixed layer (defined either on a density or $S_o$ criterion). It is common to set the damping to zero in the mixed layer as the adjustment time scale is short here \citep{Madec_al_JPO96}.
+
+\subsection{Generating \ifile{resto} using DMP\_TOOLS}
+
+DMP\_TOOLS can be used to generate a netcdf file containing the restoration coefficient $\gamma$. 
+Note that in order to maintain bit comparison with previous NEMO versions DMP\_TOOLS must be compiled 
+and run on the same machine as the NEMO model. A \ifile{mesh\_mask} file for the model configuration is required as an input. 
+This can be generated by carrying out a short model run with the namelist parameter \np{nn\_msh} set to 1. 
+The namelist parameter \np{ln\_tradmp} will also need to be set to .false. for this to work. 
+The \nl{nam\_dmp\_create} namelist in the DMP\_TOOLS directory is used to specify options for the restoration coefficient.
+
+%--------------------------------------------nam_dmp_create-------------------------------------------------
+%\namtools{namelist_dmp}
+%-------------------------------------------------------------------------------------------------------
+
+\np{cp\_cfg}, \np{cp\_cpz}, \np{jp\_cfg} and \np{jperio} specify the model configuration being used and should be the same as specified in \nl{namcfg}. The variable \nl{lzoom} is used to specify that the damping is being used as in case \textit{a} above to provide boundary conditions to a zoom configuration. In the case of the arctic or antarctic zoom configurations this includes some specific treatment. Otherwise damping is applied to the 6 grid points along the ocean boundaries. The open boundaries are specified by the variables \np{lzoom\_n}, \np{lzoom\_e}, \np{lzoom\_s}, \np{lzoom\_w} in the \nl{nam\_zoom\_dmp} name list.
+
+The remaining switch namelist variables determine the spatial variation of the restoration coefficient in non-zoom configurations. 
+\np{ln\_full\_field} specifies that newtonian damping should be applied to the whole model domain. 
+\np{ln\_med\_red\_seas} specifies grid specific restoration coefficients in the Mediterranean Sea 
+for the ORCA4, ORCA2 and ORCA05 configurations. 
+If \np{ln\_old\_31\_lev\_code} is set then the depth variation of the coeffients will be specified as 
+a function of the model number. This option is included to allow backwards compatability of the ORCA2 reference 
+configurations with previous model versions. 
+\np{ln\_coast} specifies that the restoration coefficient should be reduced near to coastlines. 
+This option only has an effect if \np{ln\_full\_field} is true. 
+\np{ln\_zero\_top\_layer} specifies that the restoration coefficient should be zero in the surface layer. 
+Finally \np{ln\_custom} specifies that the custom module will be called. 
+This module is contained in the file \mdl{custom} and can be edited by users. For example damping could be applied in a specific region.
+
+The restoration coefficient can be set to zero in equatorial regions by specifying a positive value of \np{nn\_hdmp}. 
+Equatorward of this latitude the restoration coefficient will be zero with a smooth transition to 
+the full values of a 10\deg latitud band. 
+This is often used because of the short adjustment time scale in the equatorial region 
+\citep{Reverdin1991, Fujio1991, Marti_PhD92}. The time scale associated with the damping depends on the depth as a 
+hyperbolic tangent, with \np{rn\_surf} as surface value, \np{rn\_bot} as bottom value and a transition depth of \np{rn\_dep}.  
+
+% ================================================================
+% Tracer time evolution
+% ================================================================
+\section{Tracer time evolution (\protect\mdl{tranxt})}
+\label{sec:TRA_nxt}
+%--------------------------------------------namdom-----------------------------------------------------
+
+\nlst{namdom}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namdom} namelist variables.
+The general framework for tracer time stepping is a modified leap-frog scheme 
+\citep{Leclair_Madec_OM09}, $i.e.$ a three level centred time scheme associated 
+with a Asselin time filter (cf. \autoref{sec:STP_mLF}):
+\begin{equation} \label{eq:tra_nxt}
+\begin{aligned}
+(e_{3t}T)^{t+\rdt} &= (e_{3t}T)_f^{t-\rdt} &+ 2 \, \rdt  \,e_{3t}^t\ \text{RHS}^t &	\\
+\\
+(e_{3t}T)_f^t  \;\ \quad &= (e_{3t}T)^t \;\quad 
+                                    &+\gamma \,\left[ {(e_{3t}T)_f^{t-\rdt} -2(e_{3t}T)^t+(e_{3t}T)^{t+\rdt}} \right] &  \\
+                                 & &- \gamma\,\rdt \, \left[ Q^{t+\rdt/2} -  Q^{t-\rdt/2} \right]  &                      
+\end{aligned}
+\end{equation} 
+where RHS is the right hand side of the temperature equation, 
+the subscript $f$ denotes filtered values, $\gamma$ is the Asselin coefficient,
+and $S$ is the total forcing applied on $T$ ($i.e.$ fluxes plus content in mass exchanges). 
+$\gamma$ is initialized as \np{rn\_atfp} (\textbf{namelist} parameter). 
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3}. Note that the forcing correction term in the filter
+is not applied in linear free surface (\jp{lk\_vvl}\forcode{ = .false.}) (see \autoref{subsec:TRA_sbc}.
+Not also that in constant volume case, the time stepping is performed on $T$, 
+not on its content, $e_{3t}T$.
+
+When the vertical mixing is solved implicitly, the update of the \textit{next} tracer 
+fields is done in module \mdl{trazdf}. In this case only the swapping of arrays 
+and the Asselin filtering is done in the \mdl{tranxt} module.
+
+In order to prepare for the computation of the \textit{next} time step, 
+a swap of tracer arrays is performed: $T^{t-\rdt} = T^t$ and $T^t = T_f$. 
+
+% ================================================================
+% Equation of State (eosbn2) 
+% ================================================================
+\section{Equation of state (\protect\mdl{eosbn2}) }
+\label{sec:TRA_eosbn2}
+%--------------------------------------------nameos-----------------------------------------------------
+
+\nlst{nameos}
+%--------------------------------------------------------------------------------------------------------------
+
+% -------------------------------------------------------------------------------------------------------------
+%        Equation of State
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Equation of seawater (\protect\np{nn\_eos}\forcode{ = -1..1})}
+\label{subsec:TRA_eos}
+
+The Equation Of Seawater (EOS) is an empirical nonlinear thermodynamic relationship 
+linking seawater density, $\rho$, to a number of state variables, 
+most typically temperature, salinity and pressure. 
+Because density gradients control the pressure gradient force through the hydrostatic balance, 
+the equation of state provides a fundamental bridge between the distribution of active tracers 
+and the fluid dynamics. Nonlinearities of the EOS are of major importance, in particular 
+influencing the circulation through determination of the static stability below the mixed layer, 
+thus controlling rates of exchange between the atmosphere  and the ocean interior \citep{Roquet_JPO2015}. 
+Therefore an accurate EOS based on either the 1980 equation of state (EOS-80, \cite{UNESCO1983}) 
+or TEOS-10 \citep{TEOS10} standards should be used anytime a simulation of the real 
+ocean circulation is attempted \citep{Roquet_JPO2015}. 
+The use of TEOS-10 is highly recommended because 
+\textit{(i)} it is the new official EOS, 
+\textit{(ii)} it is more accurate, being based on an updated database of laboratory measurements, and 
+\textit{(iii)} it uses Conservative Temperature and Absolute Salinity (instead of potential temperature 
+and practical salinity for EOS-980, both variables being more suitable for use as model variables 
+\citep{TEOS10, Graham_McDougall_JPO13}. 
+EOS-80 is an obsolescent feature of the NEMO system, kept only for backward compatibility.
+For process studies, it is often convenient to use an approximation of the EOS. To that purposed, 
+a simplified EOS (S-EOS) inspired by \citet{Vallis06} is also available.
+
+In the computer code, a density anomaly, $d_a= \rho / \rho_o - 1$, 
+is computed, with $\rho_o$ a reference density. Called \textit{rau0} 
+in the code, $\rho_o$ is set in \mdl{phycst} to a value of $1,026~Kg/m^3$. 
+This is a sensible choice for the reference density used in a Boussinesq ocean 
+climate model, as, with the exception of only a small percentage of the ocean, 
+density in the World Ocean varies by no more than 2$\%$ from that value \citep{Gill1982}.
+
+Options are defined through the  \ngn{nameos} namelist variables, and in particular \np{nn\_eos} 
+which controls the EOS used (\forcode{= -1} for TEOS10 ; \forcode{= 0} for EOS-80 ; \forcode{= 1} for S-EOS).
+\begin{description}
+
+\item[\np{nn\_eos}\forcode{ = -1}] the polyTEOS10-bsq equation of seawater \citep{Roquet_OM2015} is used.  
+The accuracy of this approximation is comparable to the TEOS-10 rational function approximation, 
+but it is optimized for a boussinesq fluid and the polynomial expressions have simpler 
+and more computationally efficient expressions for their derived quantities 
+which make them more adapted for use in ocean models. 
+Note that a slightly higher precision polynomial form is now used replacement of the TEOS-10 
+rational function approximation for hydrographic data analysis  \citep{TEOS10}. 
+A key point is that conservative state variables are used: 
+Absolute Salinity (unit: g/kg, notation: $S_A$) and Conservative Temperature (unit: \degC, notation: $\Theta$).
+The pressure in decibars is approximated by the depth in meters. 
+With TEOS10, the specific heat capacity of sea water, $C_p$, is a constant. It is set to 
+$C_p=3991.86795711963~J\,Kg^{-1}\,^{\circ}K^{-1}$, according to \citet{TEOS10}.
+
+Choosing polyTEOS10-bsq implies that the state variables used by the model are 
+$\Theta$ and $S_A$. In particular, the initial state deined by the user have to be given as 
+\textit{Conservative} Temperature and \textit{Absolute} Salinity. 
+In addition, setting \np{ln\_useCT} to \forcode{.true.} convert the Conservative SST to potential SST 
+prior to either computing the air-sea and ice-sea fluxes (forced mode) 
+or sending the SST field to the atmosphere (coupled mode).
+
+\item[\np{nn\_eos}\forcode{ = 0}] the polyEOS80-bsq equation of seawater is used.
+It takes the same polynomial form as the polyTEOS10, but the coefficients have been optimized 
+to accurately fit EOS80 (Roquet, personal comm.). The state variables used in both the EOS80 
+and the ocean model are: 
+the Practical Salinity ((unit: psu, notation: $S_p$)) and Potential Temperature (unit: $^{\circ}C$, notation: $\theta$).
+The pressure in decibars is approximated by the depth in meters.  
+With thsi EOS, the specific heat capacity of sea water, $C_p$, is a function of temperature, 
+salinity and pressure \citep{UNESCO1983}. Nevertheless, a severe assumption is made in order to 
+have a heat content ($C_p T_p$) which is conserved by the model: $C_p$ is set to a constant 
+value, the TEOS10 value. 
+ 
+\item[\np{nn\_eos}\forcode{ = 1}] a simplified EOS (S-EOS) inspired by \citet{Vallis06} is chosen, 
+the coefficients of which has been optimized to fit the behavior of TEOS10 (Roquet, personal comm.) 
+(see also \citet{Roquet_JPO2015}). It provides a simplistic linear representation of both 
+cabbeling and thermobaricity effects which is enough for a proper treatment of the EOS 
+in theoretical studies \citep{Roquet_JPO2015}.
+With such an equation of state there is no longer a distinction between 
+\textit{conservative} and \textit{potential} temperature, as well as between \textit{absolute} 
+and \textit{practical} salinity.
+S-EOS takes the following expression:
+\begin{equation} \label{eq:tra_S-EOS}
+\begin{split}
+  d_a(T,S,z)  =  ( & - a_0 \; ( 1 + 0.5 \; \lambda_1 \; T_a + \mu_1 \; z ) * T_a  \\
+                                & + b_0 \; ( 1 - 0.5 \; \lambda_2 \; S_a - \mu_2 \; z ) * S_a  \\
+                                & - \nu \; T_a \; S_a \;  ) \; / \; \rho_o                     \\
+  with \ \  T_a = T-10  \; ;  & \;  S_a = S-35  \; ;\;  \rho_o = 1026~Kg/m^3
+\end{split}
+\end{equation} 
+where the computer name of the coefficients as well as their standard value are given in \autoref{tab:SEOS}.
+In fact, when choosing S-EOS, various approximation of EOS can be specified simply by changing 
+the associated coefficients. 
+Setting to zero the two thermobaric coefficients ($\mu_1$, $\mu_2$) remove thermobaric effect from S-EOS.
+setting to zero the three cabbeling coefficients ($\lambda_1$, $\lambda_2$, $\nu$) remove cabbeling effect from S-EOS.
+Keeping non-zero value to $a_0$ and $b_0$ provide a linear EOS function of T and S.
+
+\end{description}
+
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{table}[!tb]
+\begin{center} \begin{tabular}{|p{26pt}|p{72pt}|p{56pt}|p{136pt}|}
+\hline
+coeff.	& computer name   & S-EOS		&  description		                  \\ \hline
+$a_0$       & \np{rn\_a0}     & 1.6550 $10^{-1}$ &  linear thermal expansion coeff. 	\\ \hline
+$b_0$	      & \np{rn\_b0} 	   & 7.6554 $10^{-1}$ &  linear haline  expansion coeff. 	\\ \hline
+$\lambda_1$	& \np{rn\_lambda1}& 5.9520 $10^{-2}$ &  cabbeling coeff. in $T^2$ 	      \\ \hline
+$\lambda_2$	& \np{rn\_lambda2}& 5.4914 $10^{-4}$ &  cabbeling coeff. in $S^2$	 	   \\ \hline
+$\nu$       & \np{rn\_nu}     & 2.4341 $10^{-3}$ &  cabbeling coeff. in $T \, S$ 	   \\ \hline
+$\mu_1$     & \np{rn\_mu1} 	& 1.4970 $10^{-4}$ &  thermobaric coeff. in T    	   \\ \hline
+$\mu_2$     & \np{rn\_mu2} 	& 1.1090 $10^{-5}$ &  thermobaric coeff. in S   	      \\ \hline
+\end{tabular}
+\caption{ \protect\label{tab:SEOS}
+Standard value of S-EOS coefficients. }
+\end{center}
+\end{table}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Brunt-V\"{a}is\"{a}l\"{a} Frequency
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Brunt-V\"{a}is\"{a}l\"{a} frequency (\protect\np{nn\_eos}\forcode{ = 0..2})}
+\label{subsec:TRA_bn2}
+
+An accurate computation of the ocean stability (i.e. of $N$, the brunt-V\"{a}is\"{a}l\"{a}
+ frequency) is of paramount importance as determine the ocean stratification and 
+ is used in several ocean parameterisations (namely TKE, GLS, Richardson number dependent 
+ vertical diffusion, enhanced vertical diffusion, non-penetrative convection, tidal mixing 
+ parameterisation, iso-neutral diffusion). In particular, $N^2$ has to be computed at the local pressure 
+ (pressure in decibar being approximated by the depth in meters). The expression for $N^2$ 
+ is given by: 
+\begin{equation} \label{eq:tra_bn2}
+N^2 =	\frac{g}{e_{3w}} \left(   \beta \;\delta_{k+1/2}[S] - \alpha \;\delta_{k+1/2}[T]   \right)
+\end{equation} 
+where $(T,S) = (\Theta, S_A)$ for TEOS10, $= (\theta, S_p)$ for TEOS-80, or $=(T,S)$ for S-EOS, 
+and, $\alpha$ and $\beta$ are the thermal and haline expansion coefficients. 
+The coefficients are a polynomial function of temperature, salinity and depth which expression 
+depends on the chosen EOS. They are computed through \textit{eos\_rab}, a \textsc{Fortran} 
+function that can be found in \mdl{eosbn2}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Freezing Point of Seawater
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Freezing point of seawater}
+\label{subsec:TRA_fzp}
+
+The freezing point of seawater is a function of salinity and pressure \citep{UNESCO1983}:
+\begin{equation} \label{eq:tra_eos_fzp}
+   \begin{split}
+T_f (S,p) = \left( -0.0575 + 1.710523 \;10^{-3} \, \sqrt{S} 
+						     -  2.154996 \;10^{-4} \,S  \right) \ S    \\
+               - 7.53\,10^{-3} \ \ p 
+   \end{split}
+\end{equation}
+
+\autoref{eq:tra_eos_fzp} is only used to compute the potential freezing point of 
+sea water ($i.e.$ referenced to the surface $p=0$), thus the pressure dependent 
+terms in \autoref{eq:tra_eos_fzp} (last term) have been dropped. The freezing
+point is computed through \textit{eos\_fzp}, a \textsc{Fortran} function that can be found 
+in \mdl{eosbn2}.  
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Potential Energy     
+% -------------------------------------------------------------------------------------------------------------
+%\subsection{Potential Energy anomalies}
+%\label{subsec:TRA_bn2}
+
+%    =====>>>>> TO BE written
+%
+
+
+% ================================================================
+% Horizontal Derivative in zps-coordinate 
+% ================================================================
+\section{Horizontal derivative in \textit{zps}-coordinate (\protect\mdl{zpshde})}
+\label{sec:TRA_zpshde}
+
+\gmcomment{STEVEN: to be consistent with earlier discussion of differencing and averaging operators, 
+                   I've changed "derivative" to "difference" and "mean" to "average"}
+
+With partial cells (\np{ln\_zps}\forcode{ = .true.}) at bottom and top (\np{ln\_isfcav}\forcode{ = .true.}), in general, 
+tracers in horizontally adjacent cells live at different depths. 
+Horizontal gradients of tracers are needed for horizontal diffusion (\mdl{traldf} module) 
+and the hydrostatic pressure gradient calculations (\mdl{dynhpg} module). 
+The partial cell properties at the top (\np{ln\_isfcav}\forcode{ = .true.}) are computed in the same way as for the bottom. 
+So, only the bottom interpolation is explained below.
+
+Before taking horizontal gradients between the tracers next to the bottom, a linear 
+interpolation in the vertical is used to approximate the deeper tracer as if it actually 
+lived at the depth of the shallower tracer point (\autoref{fig:Partial_step_scheme}). 
+For example, for temperature in the $i$-direction the needed interpolated 
+temperature, $\widetilde{T}$, is:
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!p] 	 \begin{center}
+\includegraphics[width=0.9\textwidth]{Partial_step_scheme}
+\caption{ 	\protect\label{fig:Partial_step_scheme} 
+Discretisation of the horizontal difference and average of tracers in the $z$-partial 
+step coordinate (\protect\np{ln\_zps}\forcode{ = .true.}) in the case $( e3w_k^{i+1} - e3w_k^i  )>0$. 
+A linear interpolation is used to estimate $\widetilde{T}_k^{i+1}$, the tracer value 
+at the depth of the shallower tracer point of the two adjacent bottom $T$-points. 
+The horizontal difference is then given by: $\delta _{i+1/2} T_k=  \widetilde{T}_k^{\,i+1} -T_k^{\,i}$ 
+and the average by: $\overline{T}_k^{\,i+1/2}= ( \widetilde{T}_k^{\,i+1/2} - T_k^{\,i} ) / 2$.  }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{equation*}
+\widetilde{T}= \left\{  \begin{aligned}  
+&T^{\,i+1}      -\frac{ \left( e_{3w}^{i+1} -e_{3w}^i \right)}{ e_{3w}^{i+1} }\;\delta _k T^{i+1}	
+ 								&& \quad\text{if  $\ e_{3w}^{i+1} \geq e_{3w}^i$   } 	\\
+										\\
+&T^{\,i} \ \ \ \,+\frac{ \left( e_{3w}^{i+1} -e_{3w}^i \right) }{e_{3w}^i       }\;\delta _k T^{i+1}
+			 					&& \quad\text{if  $\ e_{3w}^{i+1}    <   e_{3w}^i$   } 
+            \end{aligned}   \right.
+\end{equation*}
+and the resulting forms for the horizontal difference and the horizontal average 
+value of $T$ at a $U$-point are: 
+\begin{equation} \label{eq:zps_hde}
+\begin{aligned}
+ \delta _{i+1/2} T= 	\begin{cases}
+\ \ \ \widetilde {T}\quad\ -T^i	 	& \ \ \quad\quad\text{if  $\ e_{3w}^{i+1} \geq e_{3w}^i$ } \\
+										\\
+\ \ \ T^{\,i+1}-\widetilde{T}		& \ \ \quad\quad\text{if  $\ e_{3w}^{i+1}    <   e_{3w}^i$   } 
+            		\end{cases}     \\
+\\
+\overline {T}^{\,i+1/2} \ = 	\begin{cases}
+( \widetilde {T}\ \ \;\,-T^{\,i})	 / 2	& \;\ \ \quad\text{if  $\ e_{3w}^{i+1} \geq e_{3w}^i$ } \\
+										\\
+( T^{\,i+1}-\widetilde{T} ) / 2		& \;\ \ \quad\text{if  $\ e_{3w}^{i+1}    <   e_{3w}^i$   } 
+            \end{cases}
+\end{aligned}
+\end{equation}
+
+The computation of horizontal derivative of tracers as well as of density is 
+performed once for all at each time step in \mdl{zpshde} module and stored 
+in shared arrays to be used when needed. It has to be emphasized that the 
+procedure used to compute the interpolated density, $\widetilde{\rho}$, is not 
+the same as that used for $T$ and $S$. Instead of forming a linear approximation 
+of density, we compute $\widetilde{\rho }$ from the interpolated values of $T$ 
+and $S$, and the pressure at a $u$-point (in the equation of state pressure is 
+approximated by depth, see \autoref{subsec:TRA_eos} ) : 
+\begin{equation} \label{eq:zps_hde_rho}
+\widetilde{\rho } = \rho ( {\widetilde{T},\widetilde {S},z_u }) 
+\quad \text{where }\  z_u = \min \left( {z_T^{i+1} ,z_T^i } \right)
+\end{equation} 
+
+This is a much better approximation as the variation of $\rho$ with depth (and 
+thus pressure) is highly non-linear with a true equation of state and thus is badly 
+approximated with a linear interpolation. This approximation is used to compute 
+both the horizontal pressure gradient (\autoref{sec:DYN_hpg}) and the slopes of neutral 
+surfaces (\autoref{sec:LDF_slp})
+
+Note that in almost all the advection schemes presented in this Chapter, both 
+averaging and differencing operators appear. Yet \autoref{eq:zps_hde} has not 
+been used in these schemes: in contrast to diffusion and pressure gradient 
+computations, no correction for partial steps is applied for advection. The main 
+motivation is to preserve the domain averaged mean variance of the advected 
+field when using the $2^{nd}$ order centred scheme. Sensitivity of the advection 
+schemes to the way horizontal averages are performed in the vicinity of partial 
+cells should be further investigated in the near future.
+%%%
+\gmcomment{gm :   this last remark has to be done}
+%%%
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ZDF.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_ZDF.tex	(revision 10321)
@@ -0,0 +1,1382 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter  Vertical Ocean Physics (ZDF)
+% ================================================================
+\chapter{Vertical Ocean Physics (ZDF)}
+\label{chap:ZDF}
+\minitoc
+
+%gm% Add here a small introduction to ZDF and naming of the different physics (similar to what have been written for TRA and DYN.
+
+
+\newpage
+$\ $\newline    % force a new ligne
+
+
+% ================================================================
+% Vertical Mixing
+% ================================================================
+\section{Vertical mixing}
+\label{sec:ZDF_zdf}
+
+The discrete form of the ocean subgrid scale physics has been presented in 
+\autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}. At the surface and bottom boundaries, 
+the turbulent fluxes of momentum, heat and salt have to be defined. At the 
+surface they are prescribed from the surface forcing (see \autoref{chap:SBC}), 
+while at the bottom they are set to zero for heat and salt, unless a geothermal 
+flux forcing is prescribed as a bottom boundary condition ($i.e.$ \key{trabbl} 
+defined, see \autoref{subsec:TRA_bbc}), and specified through a bottom friction 
+parameterisation for momentum (see \autoref{sec:ZDF_bfr}).
+
+In this section we briefly discuss the various choices offered to compute 
+the vertical eddy viscosity and diffusivity coefficients, $A_u^{vm}$ , 
+$A_v^{vm}$ and $A^{vT}$ ($A^{vS}$), defined at $uw$-, $vw$- and $w$- 
+points, respectively (see \autoref{sec:TRA_zdf} and \autoref{sec:DYN_zdf}). These 
+coefficients can be assumed to be either constant, or a function of the local 
+Richardson number, or computed from a turbulent closure model (either 
+TKE or GLS formulation). The computation of these coefficients is initialized 
+in the \mdl{zdfini} module and performed in the \mdl{zdfric}, \mdl{zdftke} or 
+\mdl{zdfgls} modules. The trends due to the vertical momentum and tracer 
+diffusion, including the surface forcing, are computed and added to the 
+general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively. 
+These trends can be computed using either a forward time stepping scheme 
+(namelist parameter \np{ln\_zdfexp}\forcode{ = .true.}) or a backward time stepping 
+scheme (\np{ln\_zdfexp}\forcode{ = .false.}) depending on the magnitude of the mixing 
+coefficients, and thus of the formulation used (see \autoref{chap:STP}).
+
+% -------------------------------------------------------------------------------------------------------------
+%        Constant 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Constant (\protect\key{zdfcst})}
+\label{subsec:ZDF_cst}
+%--------------------------------------------namzdf---------------------------------------------------------
+
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namzdf} namelist variables.
+When \key{zdfcst} is defined, the momentum and tracer vertical eddy coefficients 
+are set to constant values over the whole ocean. This is the crudest way to define 
+the vertical ocean physics. It is recommended that this option is only used in 
+process studies, not in basin scale simulations. Typical values used in this case are:
+\begin{align*} 
+A_u^{vm} = A_v^{vm} &= 1.2\ 10^{-4}~m^2.s^{-1} 	\\
+A^{vT} = A^{vS} &= 1.2\ 10^{-5}~m^2.s^{-1}
+\end{align*}
+
+These values are set through the \np{rn\_avm0} and \np{rn\_avt0} namelist parameters. 
+In all cases, do not use values smaller that those associated with the molecular 
+viscosity and diffusivity, that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, 
+$\sim10^{-7}~m^2.s^{-1}$ for temperature and $\sim10^{-9}~m^2.s^{-1}$ for salinity.
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Richardson Number Dependent
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Richardson number dependent (\protect\key{zdfric})}
+\label{subsec:ZDF_ric}
+
+%--------------------------------------------namric---------------------------------------------------------
+
+\nlst{namzdf_ric}
+%--------------------------------------------------------------------------------------------------------------
+
+When \key{zdfric} is defined, a local Richardson number dependent formulation 
+for the vertical momentum and tracer eddy coefficients is set through the  \ngn{namzdf\_ric} 
+namelist variables.The vertical mixing 
+coefficients are diagnosed from the large scale variables computed by the model. 
+\textit{In situ} measurements have been used to link vertical turbulent activity to 
+large scale ocean structures. The hypothesis of a mixing mainly maintained by the 
+growth of Kelvin-Helmholtz like instabilities leads to a dependency between the 
+vertical eddy coefficients and the local Richardson number ($i.e.$ the 
+ratio of stratification to vertical shear). Following \citet{Pacanowski_Philander_JPO81}, the following 
+formulation has been implemented:
+\begin{equation} \label{eq:zdfric}
+   \left\{      \begin{aligned}
+         A^{vT} &= \frac {A_{ric}^{vT}}{\left( 1+a \; Ri \right)^n} + A_b^{vT}       \\
+         A^{vm} &= \frac{A^{vT}        }{\left( 1+ a \;Ri  \right)   } + A_b^{vm}
+   \end{aligned}    \right.
+\end{equation}
+where $Ri = N^2 / \left(\partial_z \textbf{U}_h \right)^2$ is the local Richardson 
+number, $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
+$A_b^{vT} $ and $A_b^{vm}$ are the constant background values set as in the 
+constant case (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ 
+is the maximum value that can be reached by the coefficient when $Ri\leq 0$, 
+$a=5$ and $n=2$. The last three values can be modified by setting the 
+\np{rn\_avmri}, \np{rn\_alp} and \np{nn\_ric} namelist parameters, respectively.
+
+A simple mixing-layer model to transfer and dissipate the atmospheric
+ forcings (wind-stress and buoyancy fluxes) can be activated setting 
+the \np{ln\_mldw}\forcode{ = .true.} in the namelist.
+
+In this case, the local depth of turbulent wind-mixing or "Ekman depth"
+ $h_{e}(x,y,t)$ is evaluated and the vertical eddy coefficients prescribed within this layer.
+
+This depth is assumed proportional to the "depth of frictional influence" that is limited by rotation:
+\begin{equation}
+         h_{e} = Ek \frac {u^{*}} {f_{0}}  	\\
+\end{equation}
+where, $Ek$ is an empirical parameter, $u^{*}$ is the friction velocity and $f_{0}$ is the Coriolis 
+parameter.
+
+In this similarity height relationship, the turbulent friction velocity:
+\begin{equation}
+         u^{*} = \sqrt \frac {|\tau|} {\rho_o}  	\\
+\end{equation}
+
+is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$.
+The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}.
+Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to 
+the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{Lermusiaux2001}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        TKE Turbulent Closure Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{TKE turbulent closure scheme (\protect\key{zdftke})}
+\label{subsec:ZDF_tke}
+
+%--------------------------------------------namzdf_tke--------------------------------------------------
+
+\nlst{namzdf_tke}
+%--------------------------------------------------------------------------------------------------------------
+
+The vertical eddy viscosity and diffusivity coefficients are computed from a TKE 
+turbulent closure model based on a prognostic equation for $\bar{e}$, the turbulent 
+kinetic energy, and a closure assumption for the turbulent length scales. This 
+turbulent closure model has been developed by \citet{Bougeault1989} in the 
+atmospheric case, adapted by \citet{Gaspar1990} for the oceanic case, and 
+embedded in OPA, the ancestor of NEMO, by \citet{Blanke1993} for equatorial Atlantic 
+simulations. Since then, significant modifications have been introduced by 
+\citet{Madec1998} in both the implementation and the formulation of the mixing 
+length scale. The time evolution of $\bar{e}$ is the result of the production of 
+$\bar{e}$ through vertical shear, its destruction through stratification, its vertical 
+diffusion, and its dissipation of \citet{Kolmogorov1942} type:
+\begin{equation} \label{eq:zdftke_e}
+\frac{\partial \bar{e}}{\partial t} = 
+\frac{K_m}{{e_3}^2 }\;\left[ {\left( {\frac{\partial u}{\partial k}} \right)^2
+				        +\left( {\frac{\partial v}{\partial k}} \right)^2} \right]
+-K_\rho\,N^2
++\frac{1}{e_3}	\;\frac{\partial }{\partial k}\left[ {\frac{A^{vm}}{e_3 }
+				\;\frac{\partial \bar{e}}{\partial k}} \right]
+- c_\epsilon \;\frac{\bar {e}^{3/2}}{l_\epsilon }
+\end{equation}
+\begin{equation} \label{eq:zdftke_kz}
+   \begin{split}
+         K_m &= C_k\  l_k\  \sqrt {\bar{e}\; }  	\\
+         K_\rho &= A^{vm} / P_{rt}
+   \end{split}
+\end{equation}
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}), 
+$l_{\epsilon }$ and $l_{\kappa }$ are the dissipation and mixing length scales, 
+$P_{rt}$ is the Prandtl number, $K_m$ and $K_\rho$ are the vertical eddy viscosity 
+and diffusivity coefficients. The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$  
+$\approx 0.7$ are designed to deal with vertical mixing at any depth \citep{Gaspar1990}. 
+They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}. 
+$P_{rt}$ can be set to unity or, following \citet{Blanke1993}, be a function 
+of the local Richardson number, $R_i$:
+\begin{align*} \label{eq:prt}
+P_{rt} = \begin{cases}
+                    \ \ \ 1 &      \text{if $\ R_i \leq 0.2$} 	\\
+                    5\,R_i &      \text{if $\ 0.2 \leq R_i \leq 2$} 	\\
+                    \ \ 10 &      \text{if $\ 2 \leq R_i$} 
+            \end{cases}
+\end{align*}
+Options are defined through the  \ngn{namzdfy\_tke} namelist variables.
+The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable.
+
+At the sea surface, the value of $\bar{e}$ is prescribed from the wind 
+stress field as $\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} 
+namelist parameter. The default value of $e_{bb}$ is 3.75. \citep{Gaspar1990}), 
+however a much larger value can be used when taking into account the 
+surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}). 
+The bottom value of TKE is assumed to be equal to the value of the level just above. 
+The time integration of the $\bar{e}$ equation may formally lead to negative values 
+because the numerical scheme does not ensure its positivity. To overcome this 
+problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} 
+namelist parameter). Following \citet{Gaspar1990}, the cut-off value is set 
+to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$. This allows the subsequent formulations 
+to match that of \citet{Gargett1984} for the diffusion in the thermocline and 
+deep ocean :  $K_\rho = 10^{-3} / N$. 
+In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical 
+instabilities associated with too weak vertical diffusion. They must be 
+specified at least larger than the molecular values, and are set through 
+\np{rn\_avm0} and \np{rn\_avt0} (namzdf namelist, see \autoref{subsec:ZDF_cst}).
+
+\subsubsection{Turbulent length scale}
+For computational efficiency, the original formulation of the turbulent length 
+scales proposed by \citet{Gaspar1990} has been simplified. Four formulations 
+are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist 
+parameter. The first two are based on the following first order approximation 
+\citep{Blanke1993}:
+\begin{equation} \label{eq:tke_mxl0_1}
+l_k = l_\epsilon = \sqrt {2 \bar{e}\; } / N
+\end{equation}
+which is valid in a stable stratified region with constant values of the Brunt-
+Vais\"{a}l\"{a} frequency. The resulting length scale is bounded by the distance 
+to the surface or to the bottom (\np{nn\_mxl}\forcode{ = 0}) or by the local vertical scale factor 
+(\np{nn\_mxl}\forcode{ = 1}). \citet{Blanke1993} notice that this simplification has two major 
+drawbacks: it makes no sense for locally unstable stratification and the 
+computation no longer uses all the information contained in the vertical density 
+profile. To overcome these drawbacks, \citet{Madec1998} introduces the 
+\np{nn\_mxl}\forcode{ = 2..3} cases, which add an extra assumption concerning the vertical 
+gradient of the computed length scale. So, the length scales are first evaluated 
+as in \autoref{eq:tke_mxl0_1} and then bounded such that:
+\begin{equation} \label{eq:tke_mxl_constraint}
+\frac{1}{e_3 }\left| {\frac{\partial l}{\partial k}} \right| \leq 1
+\qquad \text{with }\  l =  l_k = l_\epsilon
+\end{equation}
+\autoref{eq:tke_mxl_constraint} means that the vertical variations of the length 
+scale cannot be larger than the variations of depth. It provides a better 
+approximation of the \citet{Gaspar1990} formulation while being much less 
+time consuming. In particular, it allows the length scale to be limited not only 
+by the distance to the surface or to the ocean bottom but also by the distance 
+to a strongly stratified portion of the water column such as the thermocline 
+(\autoref{fig:mixing_length}). In order to impose the \autoref{eq:tke_mxl_constraint} 
+constraint, we introduce two additional length scales: $l_{up}$ and $l_{dwn}$, 
+the upward and downward length scales, and evaluate the dissipation and 
+mixing length scales as (and note that here we use numerical indexing):
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] \begin{center}
+\includegraphics[width=1.00\textwidth]{Fig_mixing_length}
+\caption{ \protect\label{fig:mixing_length} 
+Illustration of the mixing length computation. }
+\end{center}  
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{equation} \label{eq:tke_mxl2}
+\begin{aligned}
+ l_{up\ \ }^{(k)} &= \min \left(  l^{(k)} \ , \ l_{up}^{(k+1)} + e_{3t}^{(k)}\ \ \ \;  \right)
+    \quad &\text{ from $k=1$ to $jpk$ }\ \\
+ l_{dwn}^{(k)} &= \min \left(  l^{(k)} \ , \ l_{dwn}^{(k-1)} + e_{3t}^{(k-1)}  \right)   
+    \quad &\text{ from $k=jpk$ to $1$ }\ \\
+\end{aligned}
+\end{equation}
+where $l^{(k)}$ is computed using \autoref{eq:tke_mxl0_1}, 
+$i.e.$ $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.
+
+In the \np{nn\_mxl}\forcode{ = 2} case, the dissipation and mixing length scales take the same 
+value: $ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the 
+\np{nn\_mxl}\forcode{ = 3} case, the dissipation and mixing turbulent length scales are give 
+as in \citet{Gaspar1990}:
+\begin{equation} \label{eq:tke_mxl_gaspar}
+\begin{aligned}
+& l_k          = \sqrt{\  l_{up} \ \ l_{dwn}\ }  	\\
+& l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right) 
+\end{aligned}
+\end{equation}
+
+At the ocean surface, a non zero length scale is set through the  \np{rn\_mxl0} namelist 
+parameter. Usually the surface scale is given by $l_o = \kappa \,z_o$ 
+where $\kappa = 0.4$ is von Karman's constant and $z_o$ the roughness 
+parameter of the surface. Assuming $z_o=0.1$~m \citep{Craig_Banner_JPO94} 
+leads to a 0.04~m, the default value of \np{rn\_mxl0}. In the ocean interior 
+a minimum length scale is set to recover the molecular viscosity when $\bar{e}$ 
+reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ).
+
+
+\subsubsection{Surface wave breaking parameterization}
+%-----------------------------------------------------------------------%
+Following \citet{Mellor_Blumberg_JPO04}, the TKE turbulence closure model has been modified 
+to include the effect of surface wave breaking energetics. This results in a reduction of summertime 
+surface temperature when the mixed layer is relatively shallow. The \citet{Mellor_Blumberg_JPO04} 
+modifications acts on surface length scale and TKE values and air-sea drag coefficient. 
+The latter concerns the bulk formulea and is not discussed here. 
+
+Following \citet{Craig_Banner_JPO94}, the boundary condition on surface TKE value is :
+\begin{equation}  \label{eq:ZDF_Esbc}
+\bar{e}_o = \frac{1}{2}\,\left(  15.8\,\alpha_{CB} \right)^{2/3} \,\frac{|\tau|}{\rho_o}
+\end{equation}
+where $\alpha_{CB}$ is the \citet{Craig_Banner_JPO94} constant of proportionality 
+which depends on the ''wave age'', ranging from 57 for mature waves to 146 for 
+younger waves \citep{Mellor_Blumberg_JPO04}. 
+The boundary condition on the turbulent length scale follows the Charnock's relation:
+\begin{equation} \label{eq:ZDF_Lsbc}
+l_o = \kappa \beta \,\frac{|\tau|}{g\,\rho_o}
+\end{equation}
+where $\kappa=0.40$ is the von Karman constant, and $\beta$ is the Charnock's constant.
+\citet{Mellor_Blumberg_JPO04} suggest $\beta = 2.10^{5}$ the value chosen by \citet{Stacey_JPO99}
+citing observation evidence, and $\alpha_{CB} = 100$ the Craig and Banner's value.
+As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$, 
+with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds 
+to $\alpha_{CB} = 100$. Further setting  \np{ln\_mxl0} to true applies \autoref{eq:ZDF_Lsbc} 
+as surface boundary condition on length scale, with $\beta$ hard coded to the Stacey's value.
+Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) 
+is applied on surface $\bar{e}$ value.
+
+
+\subsubsection{Langmuir cells}
+%--------------------------------------%
+Langmuir circulations (LC) can be described as ordered large-scale vertical motions 
+in the surface layer of the oceans. Although LC have nothing to do with convection, 
+the circulation pattern is rather similar to so-called convective rolls in the atmospheric 
+boundary layer. The detailed physics behind LC is described in, for example, 
+\citet{Craik_Leibovich_JFM76}. The prevailing explanation is that LC arise from 
+a nonlinear interaction between the Stokes drift and wind drift currents. 
+
+Here we introduced in the TKE turbulent closure the simple parameterization of 
+Langmuir circulations proposed by \citep{Axell_JGR02} for a $k-\epsilon$ turbulent closure. 
+The parameterization, tuned against large-eddy simulation, includes the whole effect
+of LC in an extra source terms of TKE, $P_{LC}$.
+The presence of $P_{LC}$ in \autoref{eq:zdftke_e}, the TKE equation, is controlled 
+by setting \np{ln\_lc} to \forcode{.true.} in the namtke namelist.
+ 
+By making an analogy with the characteristic convective velocity scale 
+($e.g.$, \citet{D'Alessio_al_JPO98}), $P_{LC}$ is assumed to be : 
+\begin{equation}
+P_{LC}(z) = \frac{w_{LC}^3(z)}{H_{LC}}
+\end{equation}
+where $w_{LC}(z)$ is the vertical velocity profile of LC, and $H_{LC}$ is the LC depth.
+With no information about the wave field, $w_{LC}$ is assumed to be proportional to 
+the Stokes drift $u_s = 0.377\,\,|\tau|^{1/2}$, where $|\tau|$ is the surface wind stress module 
+\footnote{Following \citet{Li_Garrett_JMR93}, the surface Stoke drift velocity
+may be expressed as $u_s =  0.016 \,|U_{10m}|$. Assuming an air density of 
+$\rho_a=1.22 \,Kg/m^3$ and a drag coefficient of $1.5~10^{-3}$ give the expression 
+used of $u_s$ as a function of the module of surface stress}. 
+For the vertical variation, $w_{LC}$ is assumed to be zero at the surface as well as 
+at a finite depth $H_{LC}$ (which is often close to the mixed layer depth), and simply 
+varies as a sine function in between (a first-order profile for the Langmuir cell structures). 
+The resulting expression for $w_{LC}$ is :
+\begin{equation}
+w_{LC}  = \begin{cases}
+                   c_{LC} \,u_s \,\sin(- \pi\,z / H_{LC} )    &      \text{if $-z \leq H_{LC}$} 	\\
+                   0                 				 &      \text{otherwise} 
+                 \end{cases}
+\end{equation}
+where $c_{LC} = 0.15$ has been chosen by \citep{Axell_JGR02} as a good compromise 
+to fit LES data. The chosen value yields maximum vertical velocities $w_{LC}$ of the order 
+of a few centimeters per second. The value of $c_{LC}$ is set through the \np{rn\_lc} 
+namelist parameter, having in mind that it should stay between 0.15 and 0.54 \citep{Axell_JGR02}. 
+
+The $H_{LC}$ is estimated in a similar way as the turbulent length scale of TKE equations:
+$H_{LC}$ is depth to which a water parcel with kinetic energy due to Stoke drift
+can reach on its own by converting its kinetic energy to potential energy, according to 
+\begin{equation}
+- \int_{-H_{LC}}^0 { N^2\;z  \;dz} = \frac{1}{2} u_s^2
+\end{equation}
+
+
+\subsubsection{Mixing just below the mixed layer}
+%--------------------------------------------------------------%
+
+Vertical mixing parameterizations commonly used in ocean general circulation models 
+tend to produce mixed-layer depths that are too shallow during summer months and windy conditions.
+This bias is particularly acute over the Southern Ocean. 
+To overcome this systematic bias, an ad hoc parameterization is introduced into the TKE scheme  \cite{Rodgers_2014}. 
+The parameterization is an empirical one, $i.e.$ not derived from theoretical considerations, 
+but rather is meant to account for observed processes that affect the density structure of 
+the ocean’s planetary boundary layer that are not explicitly captured by default in the TKE scheme 
+($i.e.$ near-inertial oscillations and ocean swells and waves).
+
+When using this parameterization ($i.e.$ when \np{nn\_etau}\forcode{ = 1}), the TKE input to the ocean ($S$) 
+imposed by the winds in the form of near-inertial oscillations, swell and waves is parameterized 
+by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition, plus a depth depend one given by:
+\begin{equation}  \label{eq:ZDF_Ehtau}
+S = (1-f_i) \; f_r \; e_s \; e^{-z / h_\tau} 
+\end{equation}
+where 
+$z$ is the depth,  
+$e_s$ is TKE surface boundary condition, 
+$f_r$ is the fraction of the surface TKE that penetrate in the ocean, 
+$h_\tau$ is a vertical mixing length scale that controls exponential shape of the penetration, 
+and $f_i$ is the ice concentration (no penetration if $f_i=1$, that is if the ocean is entirely 
+covered by sea-ice).
+The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter. 
+The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{ = 0}) 
+or a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m 
+at high latitudes (\np{nn\_etau}\forcode{ = 1}). 
+
+Note that two other option existe, \np{nn\_etau}\forcode{ = 2..3}. They correspond to applying 
+\autoref{eq:ZDF_Ehtau} only at the base of the mixed layer, or to using the high frequency part 
+of the stress to evaluate the fraction of TKE that penetrate the ocean. 
+Those two options are obsolescent features introduced for test purposes.
+They will be removed in the next release. 
+
+
+
+% from Burchard et al OM 2008 : 
+% the most critical process not reproduced by statistical turbulence models is the activity of 
+% internal waves and their interaction with turbulence. After the Reynolds decomposition, 
+% internal waves are in principle included in the RANS equations, but later partially 
+% excluded by the hydrostatic assumption and the model resolution. 
+% Thus far, the representation of internal wave mixing in ocean models has been relatively crude 
+% (e.g. Mellor, 1989; Large et al., 1994; Meier, 2001; Axell, 2002; St. Laurent and Garrett, 2002).
+
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        TKE discretization considerations
+% -------------------------------------------------------------------------------------------------------------
+\subsection{TKE discretization considerations (\protect\key{zdftke})}
+\label{subsec:ZDF_tke_ene}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]   \begin{center}
+\includegraphics[width=1.00\textwidth]{Fig_ZDF_TKE_time_scheme}
+\caption{ \protect\label{fig:TKE_time_scheme} 
+Illustration of the TKE time integration and its links to the momentum and tracer time integration. }
+\end{center}  
+\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The production of turbulence by vertical shear (the first term of the right hand side 
+of \autoref{eq:zdftke_e}) should balance the loss of kinetic energy associated with
+the vertical momentum diffusion (first line in \autoref{eq:PE_zdf}). To do so a special care 
+have to be taken for both the time and space discretization of the TKE equation 
+\citep{Burchard_OM02,Marsaleix_al_OM08}.
+
+Let us first address the time stepping issue. \autoref{fig:TKE_time_scheme} shows 
+how the two-level Leap-Frog time stepping of the momentum and tracer equations interplays 
+with the one-level forward time stepping of TKE equation. With this framework, the total loss 
+of kinetic energy (in 1D for the demonstration) due to the vertical momentum diffusion is 
+obtained by multiplying this quantity by $u^t$ and summing the result vertically:   
+\begin{equation} \label{eq:energ1}
+\begin{split}
+\int_{-H}^{\eta}  u^t \,\partial_z &\left( {K_m}^t \,(\partial_z u)^{t+\rdt}  \right) \,dz   \\
+&= \Bigl[  u^t \,{K_m}^t \,(\partial_z u)^{t+\rdt} \Bigr]_{-H}^{\eta}          
+ - \int_{-H}^{\eta}{ {K_m}^t \,\partial_z{u^t} \,\partial_z u^{t+\rdt} \,dz }
+\end{split}
+\end{equation}
+Here, the vertical diffusion of momentum is discretized backward in time 
+with a coefficient, $K_m$, known at time $t$ (\autoref{fig:TKE_time_scheme}), 
+as it is required when using the TKE scheme (see \autoref{sec:STP_forward_imp}). 
+The first term of the right hand side of \autoref{eq:energ1} represents the kinetic energy 
+transfer at the surface (atmospheric forcing) and at the bottom (friction effect). 
+The second term is always negative. It is the dissipation rate of kinetic energy, 
+and thus minus the shear production rate of $\bar{e}$. \autoref{eq:energ1} 
+implies that, to be energetically consistent, the production rate of $\bar{e}$ 
+used to compute $(\bar{e})^t$ (and thus ${K_m}^t$) should be expressed as 
+${K_m}^{t-\rdt}\,(\partial_z u)^{t-\rdt} \,(\partial_z u)^t$ (and not by the more straightforward 
+$K_m \left( \partial_z u \right)^2$ expression taken at time $t$ or $t-\rdt$).
+
+A similar consideration applies on the destruction rate of $\bar{e}$ due to stratification 
+(second term of the right hand side of \autoref{eq:zdftke_e}). This term 
+must balance the input of potential energy resulting from vertical mixing. 
+The rate of change of potential energy (in 1D for the demonstration) due vertical 
+mixing is obtained by multiplying vertical density diffusion 
+tendency by $g\,z$ and and summing the result vertically:
+\begin{equation} \label{eq:energ2}
+\begin{split}
+\int_{-H}^{\eta} g\,z\,\partial_z &\left( {K_\rho}^t \,(\partial_k \rho)^{t+\rdt}   \right) \,dz    \\
+&= \Bigl[  g\,z \,{K_\rho}^t \,(\partial_z \rho)^{t+\rdt} \Bigr]_{-H}^{\eta}  
+   - \int_{-H}^{\eta}{ g \,{K_\rho}^t \,(\partial_k \rho)^{t+\rdt} } \,dz   \\
+&= - \Bigl[  z\,{K_\rho}^t \,(N^2)^{t+\rdt} \Bigr]_{-H}^{\eta}
++ \int_{-H}^{\eta}{  \rho^{t+\rdt} \, {K_\rho}^t \,(N^2)^{t+\rdt} \,dz  }
+\end{split}
+\end{equation}
+where we use $N^2 = -g \,\partial_k \rho / (e_3 \rho)$. 
+The first term of the right hand side of \autoref{eq:energ2}  is always zero 
+because there is no diffusive flux through the ocean surface and bottom). 
+The second term is minus the destruction rate of  $\bar{e}$ due to stratification. 
+Therefore \autoref{eq:energ1} implies that, to be energetically consistent, the product 
+${K_\rho}^{t-\rdt}\,(N^2)^t$ should be used in \autoref{eq:zdftke_e}, the TKE equation.
+
+Let us now address the space discretization issue. 
+The vertical eddy coefficients are defined at $w$-point whereas the horizontal velocity 
+components are in the centre of the side faces of a $t$-box in staggered C-grid 
+(\autoref{fig:cell}). A space averaging is thus required to obtain the shear TKE production term.
+By redoing the \autoref{eq:energ1} in the 3D case, it can be shown that the product of 
+eddy coefficient by the shear at $t$ and $t-\rdt$ must be performed prior to the averaging.
+Furthermore, the possible time variation of $e_3$ (\key{vvl} case) have to be taken into 
+account.
+
+The above energetic considerations leads to 
+the following final discrete form for the TKE equation:
+\begin{equation} \label{eq:zdftke_ene}
+\begin{split}
+\frac { (\bar{e})^t - (\bar{e})^{t-\rdt} } {\rdt}  \equiv  
+\Biggl\{ \Biggr.
+  &\overline{ \left( \left(\overline{K_m}^{\,i+1/2}\right)^{t-\rdt} \,\frac{\delta_{k+1/2}[u^{t+\rdt}]}{{e_3u}^{t+\rdt} } 
+                                                                              \ \frac{\delta_{k+1/2}[u^ t         ]}{{e_3u}^ t          }  \right) }^{\,i} \\
++&\overline{  \left( \left(\overline{K_m}^{\,j+1/2}\right)^{t-\rdt} \,\frac{\delta_{k+1/2}[v^{t+\rdt}]}{{e_3v}^{t+\rdt} } 
+                                                                               \ \frac{\delta_{k+1/2}[v^ t         ]}{{e_3v}^ t          }  \right) }^{\,j} 
+\Biggr. \Biggr\}   \\
+%
+- &{K_\rho}^{t-\rdt}\,{(N^2)^t}    \\
+%
++&\frac{1}{{e_3w}^{t+\rdt}}  \;\delta_{k+1/2} \left[   {K_m}^{t-\rdt} \,\frac{\delta_{k}[(\bar{e})^{t+\rdt}]} {{e_3w}^{t+\rdt}}   \right]   \\
+%
+- &c_\epsilon \; \left( \frac{\sqrt{\bar {e}}}{l_\epsilon}\right)^{t-\rdt}\,(\bar {e})^{t+\rdt}
+\end{split}
+\end{equation}
+where the last two terms in \autoref{eq:zdftke_ene} (vertical diffusion and Kolmogorov dissipation) 
+are time stepped using a backward scheme (see\autoref{sec:STP_forward_imp}). 
+Note that the Kolmogorov term has been linearized in time in order to render 
+the implicit computation possible. The restart of the TKE scheme 
+requires the storage of $\bar {e}$, $K_m$, $K_\rho$ and $l_\epsilon$ as they all appear in 
+the right hand side of \autoref{eq:zdftke_ene}. For the latter, it is in fact 
+the ratio $\sqrt{\bar{e}}/l_\epsilon$ which is stored. 
+
+% -------------------------------------------------------------------------------------------------------------
+%        GLS Generic Length Scale Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{GLS: Generic Length Scale (\protect\key{zdfgls})}
+\label{subsec:ZDF_gls}
+
+%--------------------------------------------namzdf_gls---------------------------------------------------------
+
+\nlst{namzdf_gls}
+%--------------------------------------------------------------------------------------------------------------
+
+The Generic Length Scale (GLS) scheme is a turbulent closure scheme based on 
+two prognostic equations: one for the turbulent kinetic energy $\bar {e}$, and another 
+for the generic length scale, $\psi$ \citep{Umlauf_Burchard_JMS03, Umlauf_Burchard_CSR05}. 
+This later variable is defined as : $\psi = {C_{0\mu}}^{p} \ {\bar{e}}^{m} \ l^{n}$, 
+where the triplet $(p, m, n)$ value given in Tab.\autoref{tab:GLS} allows to recover 
+a number of well-known turbulent closures ($k$-$kl$ \citep{Mellor_Yamada_1982}, 
+$k$-$\epsilon$ \citep{Rodi_1987}, $k$-$\omega$ \citep{Wilcox_1988} 
+among others \citep{Umlauf_Burchard_JMS03,Kantha_Carniel_CSR05}). 
+The GLS scheme is given by the following set of equations:
+\begin{equation} \label{eq:zdfgls_e}
+\frac{\partial \bar{e}}{\partial t} = 
+\frac{K_m}{\sigma_e e_3 }\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+                                                   +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+-K_\rho \,N^2
++\frac{1}{e_3}\,\frac{\partial}{\partial k} \left[ \frac{K_m}{e_3}\,\frac{\partial \bar{e}}{\partial k} \right]
+- \epsilon
+\end{equation}
+
+\begin{equation} \label{eq:zdfgls_psi}
+   \begin{split}
+\frac{\partial \psi}{\partial t} =& \frac{\psi}{\bar{e}} \left\{
+\frac{C_1\,K_m}{\sigma_{\psi} {e_3}}\;\left[ {\left( \frac{\partial u}{\partial k} \right)^2
+                                                                   +\left( \frac{\partial v}{\partial k} \right)^2} \right]
+- C_3 \,K_\rho\,N^2   - C_2 \,\epsilon \,Fw   \right\}             \\
+&+\frac{1}{e_3}  \;\frac{\partial }{\partial k}\left[ {\frac{K_m}{e_3 }
+                                  \;\frac{\partial \psi}{\partial k}} \right]\;
+   \end{split}
+\end{equation}
+
+\begin{equation} \label{eq:zdfgls_kz}
+   \begin{split}
+         K_m    &= C_{\mu} \ \sqrt {\bar{e}} \ l         \\
+         K_\rho &= C_{\mu'}\ \sqrt {\bar{e}} \ l
+   \end{split}
+\end{equation}
+
+\begin{equation} \label{eq:zdfgls_eps}
+{\epsilon} = C_{0\mu} \,\frac{\bar {e}^{3/2}}{l} \;
+\end{equation}
+where $N$ is the local Brunt-Vais\"{a}l\"{a} frequency (see \autoref{subsec:TRA_bn2}) 
+and $\epsilon$ the dissipation rate. 
+The constants $C_1$, $C_2$, $C_3$, ${\sigma_e}$, ${\sigma_{\psi}}$ and the wall function ($Fw$) 
+depends of the choice of the turbulence model. Four different turbulent models are pre-defined 
+(Tab.\autoref{tab:GLS}). They are made available through the \np{nn\_clo} namelist parameter. 
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[htbp]	\begin{center}
+%\begin{tabular}{cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}cp{70pt}c}
+\begin{tabular}{ccccc}
+          	             &   $k-kl$   & $k-\epsilon$ & $k-\omega$ &   generic   \\  
+%                        & \citep{Mellor_Yamada_1982} &  \citep{Rodi_1987}       & \citep{Wilcox_1988} &                 \\  
+\hline  \hline 
+\np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\  
+\hline 
+$( p , n , m )$	       &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\
+$\sigma_k$      &    2.44         &     1.              &      2.                &      0.8          \\
+$\sigma_\psi$  &    2.44         &     1.3            &      2.                 &       1.07       \\
+$C_1$              &      0.9         &     1.44          &      0.555          &       1.           \\
+$C_2$              &      0.5         &     1.92          &      0.833          &       1.22       \\
+$C_3$              &      1.           &     1.              &      1.                &       1.           \\
+$F_{wall}$        &      Yes        &       --             &     --                  &      --          \\
+\hline
+\hline
+\end{tabular}
+\caption{   \protect\label{tab:GLS} 
+Set of predefined GLS parameters, or equivalently predefined turbulence models available 
+with \protect\key{zdfgls} and controlled by the \protect\np{nn\_clos} namelist variable in \protect\ngn{namzdf\_gls} .}
+\end{center}	\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+In the Mellor-Yamada model, the negativity of $n$ allows to use a wall function to force
+the convergence of the mixing length towards $K z_b$ ($K$: Kappa and $z_b$: rugosity length) 
+value near physical boundaries (logarithmic boundary layer law). $C_{\mu}$ and $C_{\mu'}$ 
+are calculated from stability function proposed by \citet{Galperin_al_JAS88}, or by \citet{Kantha_Clayson_1994} 
+or one of the two functions suggested by \citet{Canuto_2001}  (\np{nn\_stab\_func}\forcode{ = 0..3}, resp.). 
+The value of $C_{0\mu}$ depends of the choice of the stability function.
+
+The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated 
+thanks to Dirichlet or Neumann condition through \np{nn\_tkebc\_surf} and \np{nn\_tkebc\_bot}, resp. 
+As for TKE closure , the wave effect on the mixing is considered when \np{ln\_crban}\forcode{ = .true.}
+\citep{Craig_Banner_JPO94, Mellor_Blumberg_JPO04}. The \np{rn\_crban} namelist parameter 
+is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and \np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}. 
+
+The $\psi$ equation is known to fail in stably stratified flows, and for this reason 
+almost all authors apply a clipping of the length scale as an \textit{ad hoc} remedy. 
+With this clipping, the maximum permissible length scale is determined by 
+$l_{max} = c_{lim} \sqrt{2\bar{e}}/ N$. A value of $c_{lim} = 0.53$ is often used 
+\citep{Galperin_al_JAS88}. \cite{Umlauf_Burchard_CSR05} show that the value of 
+the clipping factor is of crucial importance for the entrainment depth predicted in 
+stably stratified situations, and that its value has to be chosen in accordance 
+with the algebraic model for the turbulent fluxes. The clipping is only activated 
+if \np{ln\_length\_lim}\forcode{ = .true.}, and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
+
+The time and space discretization of the GLS equations follows the same energetic 
+consideration as for the TKE case described in \autoref{subsec:ZDF_tke_ene}  \citep{Burchard_OM02}. 
+Examples of performance of the 4 turbulent closure scheme can be found in \citet{Warner_al_OM05}.
+
+% -------------------------------------------------------------------------------------------------------------
+%        OSM OSMOSIS BL Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{OSM: OSMOSIS boundary layer scheme (\protect\key{zdfosm})}
+\label{subsec:ZDF_osm}
+
+%--------------------------------------------namzdf_osm---------------------------------------------------------
+
+\nlst{namzdf_osm}
+%--------------------------------------------------------------------------------------------------------------
+
+The OSMOSIS turbulent closure scheme is based on......   TBC
+
+% ================================================================
+% Convection
+% ================================================================
+\section{Convection}
+\label{sec:ZDF_conv}
+
+%--------------------------------------------namzdf--------------------------------------------------------
+
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+
+Static instabilities (i.e. light potential densities under heavy ones) may 
+occur at particular ocean grid points. In nature, convective processes 
+quickly re-establish the static stability of the water column. These 
+processes have been removed from the model via the hydrostatic 
+assumption so they must be parameterized. Three parameterisations 
+are available to deal with convective processes: a non-penetrative 
+convective adjustment or an enhanced vertical diffusion, or/and the 
+use of a turbulent closure scheme.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Non-Penetrative Convective Adjustment 
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Non-penetrative convective adjmt (\protect\np{ln\_tranpc}\forcode{ = .true.})]
+				{Non-penetrative convective adjustment (\protect\np{ln\_tranpc}\forcode{ = .true.})}
+\label{subsec:ZDF_npc}
+
+%--------------------------------------------namzdf--------------------------------------------------------
+
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!htb]  	\begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_npc}
+\caption{  \protect\label{fig:npc} 
+Example of an unstable density profile treated by the non penetrative 
+convective adjustment algorithm. $1^{st}$ step: the initial profile is checked from 
+the surface to the bottom. It is found to be unstable between levels 3 and 4. 
+They are mixed. The resulting $\rho$ is still larger than $\rho$(5): levels 3 to 5 
+are mixed. The resulting $\rho$ is still larger than $\rho$(6): levels 3 to 6 are 
+mixed. The $1^{st}$ step ends since the density profile is then stable below 
+the level 3. $2^{nd}$ step: the new $\rho$ profile is checked following the same 
+procedure as in $1^{st}$ step: levels 2 to 5 are mixed. The new density profile 
+is checked. It is found stable: end of algorithm.}
+\end{center}  	\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Options are defined through the  \ngn{namzdf} namelist variables.
+The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{ = .true.}. 
+It is applied at each \np{nn\_npc} time step and mixes downwards instantaneously 
+the statically unstable portion of the water column, but only until the density 
+structure becomes neutrally stable ($i.e.$ until the mixed portion of the water 
+column has \textit{exactly} the density of the water just below) \citep{Madec_al_JPO91}. 
+The associated algorithm is an iterative process used in the following way 
+(\autoref{fig:npc}): starting from the top of the ocean, the first instability is 
+found. Assume in the following that the instability is located between levels 
+$k$ and $k+1$. The temperature and salinity in the two levels are 
+vertically mixed, conserving the heat and salt contents of the water column. 
+The new density is then computed by a linear approximation. If the new 
+density profile is still unstable between levels $k+1$ and $k+2$, levels $k$, 
+$k+1$ and $k+2$ are then mixed. This process is repeated until stability is 
+established below the level $k$ (the mixing process can go down to the 
+ocean bottom). The algorithm is repeated to check if the density profile 
+between level $k-1$ and $k$ is unstable and/or if there is no deeper instability.
+
+This algorithm is significantly different from mixing statically unstable levels 
+two by two. The latter procedure cannot converge with a finite number 
+of iterations for some vertical profiles while the algorithm used in \NEMO 
+converges for any profile in a number of iterations which is less than the 
+number of vertical levels. This property is of paramount importance as 
+pointed out by \citet{Killworth1989}: it avoids the existence of permanent 
+and unrealistic static instabilities at the sea surface. This non-penetrative 
+convective algorithm has been proved successful in studies of the deep 
+water formation in the north-western Mediterranean Sea 
+\citep{Madec_al_JPO91, Madec_al_DAO91, Madec_Crepon_Bk91}.
+
+The current implementation has been modified in order to deal with any non linear 
+equation of seawater (L. Brodeau, personnal communication). 
+Two main differences have been introduced compared to the original algorithm: 
+$(i)$ the stability is now checked using the Brunt-V\"{a}is\"{a}l\"{a} frequency 
+(not the the difference in potential density) ; 
+$(ii)$ when two levels are found unstable, their thermal and haline expansion coefficients 
+are vertically mixed in the same way their temperature and salinity has been mixed.
+These two modifications allow the algorithm to perform properly and accurately 
+with TEOS10 or EOS-80 without having to recompute the expansion coefficients at each 
+mixing iteration.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Enhanced Vertical Diffusion 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Enhanced vertical diffusion (\protect\np{ln\_zdfevd}\forcode{ = .true.})}
+\label{subsec:ZDF_evd}
+
+%--------------------------------------------namzdf--------------------------------------------------------
+
+\nlst{namzdf}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namzdf} namelist variables.
+The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{ = .true.}. 
+In this case, the vertical eddy mixing coefficients are assigned very large values 
+(a typical value is $10\;m^2s^{-1})$ in regions where the stratification is unstable 
+($i.e.$ when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) 
+\citep{Lazar_PhD97, Lazar_al_JPO99}. This is done either on tracers only 
+(\np{nn\_evdm}\forcode{ = 0}) or on both momentum and tracers (\np{nn\_evdm}\forcode{ = 1}).
+
+In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and 
+if \np{nn\_evdm}\forcode{ = 1}, the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ 
+values also, are set equal to the namelist parameter \np{rn\_avevd}. A typical value 
+for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$. This parameterisation of 
+convective processes is less time consuming than the convective adjustment 
+algorithm presented above when mixing both tracers and momentum in the 
+case of static instabilities. It requires the use of an implicit time stepping on 
+vertical diffusion terms (i.e. \np{ln\_zdfexp}\forcode{ = .false.}). 
+
+Note that the stability test is performed on both \textit{before} and \textit{now} 
+values of $N^2$. This removes a potential source of divergence of odd and
+even time step in a leapfrog environment \citep{Leclair_PhD2010} (see \autoref{sec:STP_mLF}).
+
+% -------------------------------------------------------------------------------------------------------------
+%       Turbulent Closure Scheme 
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Turbulent closure scheme (\protect\key{zdf}\{tke,gls,osm\})]{Turbulent Closure Scheme (\protect\key{zdftke}, \protect\key{zdfgls} or \protect\key{zdfosm})}
+\label{subsec:ZDF_tcs}
+
+The turbulent closure scheme presented in \autoref{subsec:ZDF_tke} and \autoref{subsec:ZDF_gls} 
+(\key{zdftke} or \key{zdftke} is defined) in theory solves the problem of statically 
+unstable density profiles. In such a case, the term corresponding to the 
+destruction of turbulent kinetic energy through stratification in \autoref{eq:zdftke_e} 
+or \autoref{eq:zdfgls_e} becomes a source term, since $N^2$ is negative. 
+It results in large values of $A_T^{vT}$ and  $A_T^{vT}$, and also the four neighbouring 
+$A_u^{vm} {and}\;A_v^{vm}$ (up to $1\;m^2s^{-1})$. These large values 
+restore the static stability of the water column in a way similar to that of the 
+enhanced vertical diffusion parameterisation (\autoref{subsec:ZDF_evd}). However, 
+in the vicinity of the sea surface (first ocean layer), the eddy coefficients 
+computed by the turbulent closure scheme do not usually exceed $10^{-2}m.s^{-1}$, 
+because the mixing length scale is bounded by the distance to the sea surface. 
+It can thus be useful to combine the enhanced vertical 
+diffusion with the turbulent closure scheme, $i.e.$ setting the \np{ln\_zdfnpc} 
+namelist parameter to true and defining the turbulent closure CPP key all together.
+
+The KPP turbulent closure scheme already includes enhanced vertical diffusion 
+in the case of convection, as governed by the variables $bvsqcon$ and $difcon$ 
+found in \mdl{zdfkpp}, therefore \np{ln\_zdfevd}\forcode{ = .false.} should be used with the KPP 
+scheme. %gm%  + one word on non local flux with KPP scheme trakpp.F90 module...
+
+% ================================================================
+% Double Diffusion Mixing
+% ================================================================
+\section{Double diffusion mixing (\protect\key{zdfddm})}
+\label{sec:ZDF_ddm}
+
+%-------------------------------------------namzdf_ddm-------------------------------------------------
+%
+%\nlst{namzdf_ddm}
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namzdf\_ddm} namelist variables.
+Double diffusion occurs when relatively warm, salty water overlies cooler, fresher 
+water, or vice versa. The former condition leads to salt fingering and the latter 
+to diffusive convection. Double-diffusive phenomena contribute to diapycnal 
+mixing in extensive regions of the ocean.  \citet{Merryfield1999} include a 
+parameterisation of such phenomena in a global ocean model and show that 
+it leads to relatively minor changes in circulation but exerts significant regional 
+influences on temperature and salinity. This parameterisation has been 
+introduced in \mdl{zdfddm} module and is controlled by the \key{zdfddm} CPP key.
+
+Diapycnal mixing of S and T are described by diapycnal diffusion coefficients 
+\begin{align*} % \label{eq:zdfddm_Kz}
+    &A^{vT} = A_o^{vT}+A_f^{vT}+A_d^{vT}	\\
+    &A^{vS} = A_o^{vS}+A_f^{vS}+A_d^{vS}
+\end{align*}
+where subscript $f$ represents mixing by salt fingering, $d$ by diffusive convection, 
+and $o$ by processes other than double diffusion. The rates of double-diffusive 
+mixing depend on the buoyancy ratio $R_\rho = \alpha \partial_z T / \beta \partial_z S$, 
+where $\alpha$ and $\beta$ are coefficients of thermal expansion and saline 
+contraction (see \autoref{subsec:TRA_eos}). To represent mixing of $S$ and $T$ by salt 
+fingering, we adopt the diapycnal diffusivities suggested by Schmitt (1981):
+\begin{align} \label{eq:zdfddm_f}
+A_f^{vS} &= 	\begin{cases}
+	\frac{A^{\ast v}}{1+(R_\rho / R_c)^n   } &\text{if  $R_\rho > 1$ and $N^2>0$ } \\
+	0 				  					    &\text{otherwise} 
+				\end{cases}   
+\\ 		    \label{eq:zdfddm_f_T}
+A_f^{vT} &= 0.7 \ A_f^{vS} / R_\rho 
+\end{align}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t]   \begin{center}
+\includegraphics[width=0.99\textwidth]{Fig_zdfddm}
+\caption{  \protect\label{fig:zdfddm}
+From \citet{Merryfield1999} : (a) Diapycnal diffusivities $A_f^{vT}$ 
+and $A_f^{vS}$ for temperature and salt in regions of salt fingering. Heavy 
+curves denote $A^{\ast v} = 10^{-3}~m^2.s^{-1}$ and thin curves 
+$A^{\ast v} = 10^{-4}~m^2.s^{-1}$ ; (b) diapycnal diffusivities $A_d^{vT}$ and 
+$A_d^{vS}$ for temperature and salt in regions of diffusive convection. Heavy 
+curves denote the Federov parameterisation and thin curves the Kelley 
+parameterisation. The latter is not implemented in \NEMO. }
+\end{center}    \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+The factor 0.7 in \autoref{eq:zdfddm_f_T} reflects the measured ratio 
+$\alpha F_T /\beta F_S \approx  0.7$ of buoyancy flux of heat to buoyancy 
+flux of salt ($e.g.$, \citet{McDougall_Taylor_JMR84}). Following  \citet{Merryfield1999}, 
+we adopt $R_c = 1.6$, $n = 6$, and $A^{\ast v} = 10^{-4}~m^2.s^{-1}$.
+
+To represent mixing of S and T by diffusive layering,  the diapycnal diffusivities suggested by Federov (1988) is used: 
+\begin{align} 	\label{eq:zdfddm_d}
+A_d^{vT} &= 	\begin{cases}
+	1.3635 \, \exp{\left( 4.6\, \exp{ \left[  -0.54\,( R_{\rho}^{-1} - 1 )  \right] }    \right)}
+									&\text{if  $0<R_\rho < 1$ and $N^2>0$ } \\
+	0 								&\text{otherwise} 
+				\end{cases}   
+\\   			\label{eq:zdfddm_d_S}
+A_d^{vS} &= 	\begin{cases}
+	A_d^{vT}\ \left( 1.85\,R_{\rho} - 0.85 \right)
+									&\text{if  $0.5 \leq R_\rho<1$ and $N^2>0$ } \\
+	A_d^{vT} \ 0.15 \ R_\rho
+									&\text{if  $\ \ 0 < R_\rho<0.5$ and $N^2>0$ } \\
+	0 								&\text{otherwise} 
+				\end{cases}   
+\end{align}
+
+The dependencies of \autoref{eq:zdfddm_f} to \autoref{eq:zdfddm_d_S} on $R_\rho$ 
+are illustrated in \autoref{fig:zdfddm}. Implementing this requires computing 
+$R_\rho$ at each grid point on every time step. This is done in \mdl{eosbn2} at the 
+same time as $N^2$ is computed. This avoids duplication in the computation of 
+$\alpha$ and $\beta$ (which is usually quite expensive).
+
+% ================================================================
+% Bottom Friction
+% ================================================================
+\section{Bottom and top friction (\protect\mdl{zdfbfr})}
+\label{sec:ZDF_bfr}
+
+%--------------------------------------------nambfr--------------------------------------------------------
+%
+%\nlst{nambfr}
+%--------------------------------------------------------------------------------------------------------------
+
+Options to define the top and bottom friction are defined through the  \ngn{nambfr} namelist variables.
+The bottom friction represents the friction generated by the bathymetry. 
+The top friction represents the friction generated by the ice shelf/ocean interface. 
+As the friction processes at the top and bottom are treated in similar way, 
+only the bottom friction is described in detail below.
+
+
+Both the surface momentum flux (wind stress) and the bottom momentum 
+flux (bottom friction) enter the equations as a condition on the vertical 
+diffusive flux. For the bottom boundary layer, one has:
+\begin{equation} \label{eq:zdfbfr_flux}
+A^{vm} \left( \partial {\textbf U}_h / \partial z \right) = {{\cal F}}_h^{\textbf U}
+\end{equation}
+where ${\cal F}_h^{\textbf U}$ is represents the downward flux of horizontal momentum 
+outside the logarithmic turbulent boundary layer (thickness of the order of 
+1~m in the ocean). How ${\cal F}_h^{\textbf U}$ influences the interior depends on the 
+vertical resolution of the model near the bottom relative to the Ekman layer 
+depth. For example, in order to obtain an Ekman layer depth 
+$d = \sqrt{2\;A^{vm}} / f = 50$~m, one needs a vertical diffusion coefficient 
+$A^{vm} = 0.125$~m$^2$s$^{-1}$ (for a Coriolis frequency 
+$f = 10^{-4}$~m$^2$s$^{-1}$). With a background diffusion coefficient 
+$A^{vm} = 10^{-4}$~m$^2$s$^{-1}$, the Ekman layer depth is only 1.4~m. 
+When the vertical mixing coefficient is this small, using a flux condition is 
+equivalent to entering the viscous forces (either wind stress or bottom friction) 
+as a body force over the depth of the top or bottom model layer. To illustrate 
+this, consider the equation for $u$ at $k$, the last ocean level:
+\begin{equation} \label{eq:zdfbfr_flux2}
+\frac{\partial u_k}{\partial t} = \frac{1}{e_{3u}} \left[ \frac{A_{uw}^{vm}}{e_{3uw}} \delta_{k+1/2}\;[u] - {\cal F}^u_h \right] \approx - \frac{{\cal F}^u_{h}}{e_{3u}}
+\end{equation}
+If the bottom layer thickness is 200~m, the Ekman transport will 
+be distributed over that depth. On the other hand, if the vertical resolution 
+is high (1~m or less) and a turbulent closure model is used, the turbulent 
+Ekman layer will be represented explicitly by the model. However, the 
+logarithmic layer is never represented in current primitive equation model 
+applications: it is \emph{necessary} to parameterize the flux ${\cal F}^u_h $. 
+Two choices are available in \NEMO: a linear and a quadratic bottom friction. 
+Note that in both cases, the rotation between the interior velocity and the 
+bottom friction is neglected in the present release of \NEMO.
+
+In the code, the bottom friction is imposed by adding the trend due to the bottom 
+friction to the general momentum trend in \mdl{dynbfr}. For the time-split surface 
+pressure gradient algorithm, the momentum trend due to the barotropic component 
+needs to be handled separately. For this purpose it is convenient to compute and 
+store coefficients which can be simply combined with bottom velocities and geometric 
+values to provide the momentum trend due to bottom friction. 
+These coefficients are computed in \mdl{zdfbfr} and generally take the form 
+$c_b^{\textbf U}$ where:
+\begin{equation} \label{eq:zdfbfr_bdef}
+\frac{\partial {\textbf U_h}}{\partial t} = 
+  - \frac{{\cal F}^{\textbf U}_{h}}{e_{3u}} = \frac{c_b^{\textbf U}}{e_{3u}} \;{\textbf U}_h^b
+\end{equation}
+where $\textbf{U}_h^b = (u_b\;,\;v_b)$ is the near-bottom, horizontal, ocean velocity.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Linear Bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 0..1})}
+\label{subsec:ZDF_bfr_linear}
+
+The linear bottom friction parameterisation (including the special case 
+of a free-slip condition) assumes that the bottom friction 
+is proportional to the interior velocity (i.e. the velocity of the last 
+model level):
+\begin{equation} \label{eq:zdfbfr_linear}
+{\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3} \; \frac{\partial \textbf{U}_h}{\partial k} = r \; \textbf{U}_h^b
+\end{equation}
+where $r$ is a friction coefficient expressed in ms$^{-1}$. 
+This coefficient is generally estimated by setting a typical decay time 
+$\tau$ in the deep ocean, 
+and setting $r = H / \tau$, where $H$ is the ocean depth. Commonly accepted 
+values of $\tau$ are of the order of 100 to 200 days \citep{Weatherly_JMR84}. 
+A value $\tau^{-1} = 10^{-7}$~s$^{-1}$ equivalent to 115 days, is usually used 
+in quasi-geostrophic models. One may consider the linear friction as an 
+approximation of quadratic friction, $r \approx 2\;C_D\;U_{av}$ (\citet{Gill1982}, 
+Eq. 9.6.6). For example, with a drag coefficient $C_D = 0.002$, a typical speed 
+of tidal currents of $U_{av} =0.1$~m\;s$^{-1}$, and assuming an ocean depth 
+$H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$. 
+This is the default value used in \NEMO. It corresponds to a decay time scale 
+of 115~days. It can be changed by specifying \np{rn\_bfri1} (namelist parameter).
+
+For the linear friction case the coefficients defined in the general 
+expression \autoref{eq:zdfbfr_bdef} are: 
+\begin{equation} \label{eq:zdfbfr_linbfr_b}
+\begin{split}
+ c_b^u &= - r\\
+ c_b^v &= - r\\
+\end{split}
+\end{equation}
+When \np{nn\_botfr}\forcode{ = 1}, the value of $r$ used is \np{rn\_bfri1}. 
+Setting \np{nn\_botfr}\forcode{ = 0} is equivalent to setting $r=0$ and leads to a free-slip 
+bottom boundary condition. These values are assigned in \mdl{zdfbfr}. 
+From v3.2 onwards there is support for local enhancement of these values 
+via an externally defined 2D mask array (\np{ln\_bfr2d}\forcode{ = .true.}) given
+in the \ifile{bfr\_coef} input NetCDF file. The mask values should vary from 0 to 1. 
+Locations with a non-zero mask value will have the friction coefficient increased 
+by $mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri1}.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Non-Linear Bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Non-linear bottom friction (\protect\np{nn\_botfr}\forcode{ = 2})}
+\label{subsec:ZDF_bfr_nonlinear}
+
+The non-linear bottom friction parameterisation assumes that the bottom 
+friction is quadratic: 
+\begin{equation} \label{eq:zdfbfr_nonlinear}
+{\cal F}_h^\textbf{U} = \frac{A^{vm}}{e_3 }\frac{\partial \textbf {U}_h 
+}{\partial k}=C_D \;\sqrt {u_b ^2+v_b ^2+e_b } \;\; \textbf {U}_h^b 
+\end{equation}
+where $C_D$ is a drag coefficient, and $e_b $ a bottom turbulent kinetic energy 
+due to tides, internal waves breaking and other short time scale currents. 
+A typical value of the drag coefficient is $C_D = 10^{-3} $. As an example, 
+the CME experiment \citep{Treguier_JGR92} uses $C_D = 10^{-3}$ and 
+$e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{Killworth1992} 
+uses $C_D = 1.4\;10^{-3}$ and $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$. 
+The CME choices have been set as default values (\np{rn\_bfri2} and \np{rn\_bfeb2} 
+namelist parameters).
+
+As for the linear case, the bottom friction is imposed in the code by 
+adding the trend due to the bottom friction to the general momentum trend 
+in \mdl{dynbfr}.
+For the non-linear friction case the terms
+computed in \mdl{zdfbfr}  are: 
+\begin{equation} \label{eq:zdfbfr_nonlinbfr}
+\begin{split}
+ c_b^u &= - \; C_D\;\left[ u^2 + \left(\bar{\bar{v}}^{i+1,j}\right)^2 + e_b \right]^{1/2}\\
+ c_b^v &= - \; C_D\;\left[  \left(\bar{\bar{u}}^{i,j+1}\right)^2 + v^2 + e_b \right]^{1/2}\\
+\end{split}
+\end{equation}
+
+The coefficients that control the strength of the non-linear bottom friction are
+initialised as namelist parameters: $C_D$= \np{rn\_bfri2}, and $e_b$ =\np{rn\_bfeb2}.
+Note for applications which treat tides explicitly a low or even zero value of
+\np{rn\_bfeb2} is recommended. From v3.2 onwards a local enhancement of $C_D$ is possible
+via an externally defined 2D mask array (\np{ln\_bfr2d}\forcode{ = .true.}).  This works in the same way
+as for the linear bottom friction case with non-zero masked locations increased by
+$mask\_value$*\np{rn\_bfrien}*\np{rn\_bfri2}.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction Log-layer
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Log-layer btm frict enhncmnt (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})]
+				{Log-layer bottom friction enhancement (\protect\np{nn\_botfr}\forcode{ = 2}, \protect\np{ln\_loglayer}\forcode{ = .true.})}
+\label{subsec:ZDF_bfr_loglayer}
+
+In the non-linear bottom friction case, the drag coefficient, $C_D$, can be optionally
+enhanced using a "law of the wall" scaling. If  \np{ln\_loglayer} = .true., $C_D$ is no
+longer constant but is related to the thickness of the last wet layer in each column by:
+
+\begin{equation}
+C_D = \left ( {\kappa \over {\rm log}\left ( 0.5e_{3t}/rn\_bfrz0 \right ) } \right )^2
+\end{equation}
+
+\noindent where $\kappa$ is the von-Karman constant and \np{rn\_bfrz0} is a roughness
+length provided via the namelist.
+
+For stability, the drag coefficient is bounded such that it is kept greater or equal to
+the base \np{rn\_bfri2} value and it is not allowed to exceed the value of an additional
+namelist parameter: \np{rn\_bfri2\_max}, i.e.:
+
+\begin{equation}
+rn\_bfri2 \leq C_D \leq rn\_bfri2\_max
+\end{equation}
+
+\noindent Note also that a log-layer enhancement can also be applied to the top boundary
+friction if under ice-shelf cavities are in use (\np{ln\_isfcav}\forcode{ = .true.}).  In this case, the
+relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2}
+and \np{rn\_tfri2\_max}.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction stability
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Bottom friction stability considerations}
+\label{subsec:ZDF_bfr_stability}
+
+Some care needs to exercised over the choice of parameters to ensure that the
+implementation of bottom friction does not induce numerical instability. For 
+the purposes of stability analysis, an approximation to \autoref{eq:zdfbfr_flux2}
+is:
+\begin{equation} \label{eq:Eqn_bfrstab}
+\begin{split}
+ \Delta u &= -\frac{{{\cal F}_h}^u}{e_{3u}}\;2 \rdt    \\
+               &= -\frac{ru}{e_{3u}}\;2\rdt\\
+\end{split}
+\end{equation}
+\noindent where linear bottom friction and a leapfrog timestep have been assumed. 
+To ensure that the bottom friction cannot reverse the direction of flow it is necessary to have:
+\begin{equation}
+ |\Delta u| < \;|u| 
+\end{equation}
+\noindent which, using \autoref{eq:Eqn_bfrstab}, gives:
+\begin{equation}
+r\frac{2\rdt}{e_{3u}} < 1 \qquad  \Rightarrow \qquad r < \frac{e_{3u}}{2\rdt}\\
+\end{equation}
+This same inequality can also be derived in the non-linear bottom friction case 
+if a velocity of 1 m.s$^{-1}$ is assumed. Alternatively, this criterion can be 
+rearranged to suggest a minimum bottom box thickness to ensure stability:
+\begin{equation}
+e_{3u} > 2\;r\;\rdt
+\end{equation}
+\noindent which it may be necessary to impose if partial steps are being used. 
+For example, if $|u| = 1$ m.s$^{-1}$, $rdt = 1800$ s, $r = 10^{-3}$ then
+$e_{3u}$ should be greater than 3.6 m. For most applications, with physically
+sensible parameters these restrictions should not be of concern. But 
+caution may be necessary if attempts are made to locally enhance the bottom
+friction parameters. 
+To ensure stability limits are imposed on the bottom friction coefficients both during 
+initialisation and at each time step. Checks at initialisation are made in \mdl{zdfbfr} 
+(assuming a 1 m.s$^{-1}$ velocity in the non-linear case).
+The number of breaches of the stability criterion are reported as well as the minimum 
+and maximum values that have been set. The criterion is also checked at each time step, 
+using the actual velocity, in \mdl{dynbfr}. Values of the bottom friction coefficient are 
+reduced as necessary to ensure stability; these changes are not reported.
+
+Limits on the bottom friction coefficient are not imposed if the user has elected to
+handle the bottom friction implicitly (see \autoref{subsec:ZDF_bfr_imp}). The number of potential
+breaches of the explicit stability criterion are still reported for information purposes.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Implicit Bottom Friction
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Implicit bottom friction (\protect\np{ln\_bfrimp}\forcode{ = .true.})}
+\label{subsec:ZDF_bfr_imp}
+
+An optional implicit form of bottom friction has been implemented to improve
+model stability. We recommend this option for shelf sea and coastal ocean applications, especially 
+for split-explicit time splitting. This option can be invoked by setting \np{ln\_bfrimp} 
+to \forcode{.true.} in the \textit{nambfr} namelist. This option requires \np{ln\_zdfexp} to be \forcode{.false.} 
+in the \textit{namzdf} namelist. 
+
+This implementation is realised in \mdl{dynzdf\_imp} and \mdl{dynspg\_ts}. In \mdl{dynzdf\_imp}, the 
+bottom boundary condition is implemented implicitly.
+
+\begin{equation} \label{eq:dynzdf_bfr}
+\left.{\left( {\frac{A^{vm} }{e_3 }\ \frac{\partial \textbf{U}_h}{\partial k}} \right)} \right|_{mbk}
+	 = \binom{c_{b}^{u}u^{n+1}_{mbk}}{c_{b}^{v}v^{n+1}_{mbk}}
+\end{equation}
+
+where $mbk$ is the layer number of the bottom wet layer. superscript $n+1$ means the velocity used in the
+friction formula is to be calculated, so, it is implicit.
+
+If split-explicit time splitting is used, care must be taken to avoid the double counting of
+the bottom friction in the 2-D barotropic momentum equations. As NEMO only updates the barotropic 
+pressure gradient and Coriolis' forcing terms in the 2-D barotropic calculation, we need to remove
+the bottom friction induced by these two terms which has been included in the 3-D momentum trend 
+and update it with the latest value. On the other hand, the bottom friction contributed by the
+other terms (e.g. the advection term, viscosity term) has been included in the 3-D momentum equations
+and should not be added in the 2-D barotropic mode.
+
+The implementation of the implicit bottom friction in \mdl{dynspg\_ts} is done in two steps as the
+following:
+
+\begin{equation} \label{eq:dynspg_ts_bfr1}
+\frac{\textbf{U}_{med}-\textbf{U}^{m-1}}{2\Delta t}=-g\nabla\eta-f\textbf{k}\times\textbf{U}^{m}+c_{b}
+\left(\textbf{U}_{med}-\textbf{U}^{m-1}\right)
+\end{equation}
+\begin{equation} \label{eq:dynspg_ts_bfr2}
+\frac{\textbf{U}^{m+1}-\textbf{U}_{med}}{2\Delta t}=\textbf{T}+
+\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{U}^{'}\right)-
+2\Delta t_{bc}c_{b}\left(g\nabla\eta^{'}+f\textbf{k}\times\textbf{u}_{b}\right)
+\end{equation}
+
+where $\textbf{T}$ is the vertical integrated 3-D momentum trend. We assume the leap-frog time-stepping
+is used here. $\Delta t$ is the barotropic mode time step and $\Delta t_{bc}$ is the baroclinic mode time step.
+ $c_{b}$ is the friction coefficient. $\eta$ is the sea surface level calculated in the barotropic loops
+while $\eta^{'}$ is the sea surface level used in the 3-D baroclinic mode. $\textbf{u}_{b}$ is the bottom
+layer horizontal velocity.
+
+
+
+
+% -------------------------------------------------------------------------------------------------------------
+%       Bottom Friction with split-explicit time splitting
+% -------------------------------------------------------------------------------------------------------------
+\subsection[Bottom friction w/ split-explicit time splitting (\protect\np{ln\_bfrimp})]
+				{Bottom friction with split-explicit time splitting (\protect\np{ln\_bfrimp})}
+\label{subsec:ZDF_bfr_ts}
+
+When calculating the momentum trend due to bottom friction in \mdl{dynbfr}, the
+bottom velocity at the before time step is used. This velocity includes both the
+baroclinic and barotropic components which is appropriate when using either the
+explicit or filtered surface pressure gradient algorithms (\key{dynspg\_exp} or 
+\key{dynspg\_flt}). Extra attention is required, however, when using 
+split-explicit time stepping (\key{dynspg\_ts}). In this case the free surface 
+equation is solved with a small time step \np{rn\_rdt}/\np{nn\_baro}, while the three 
+dimensional prognostic variables are solved with the longer time step 
+of \np{rn\_rdt} seconds. The trend in the barotropic momentum due to bottom 
+friction appropriate to this method is that given by the selected parameterisation 
+($i.e.$ linear or non-linear bottom friction) computed with the evolving velocities 
+at each barotropic timestep. 
+
+In the case of non-linear bottom friction, we have elected to partially linearise 
+the problem by keeping the coefficients fixed throughout the barotropic 
+time-stepping to those computed in \mdl{zdfbfr} using the now timestep. 
+This decision allows an efficient use of the $c_b^{\vect{U}}$ coefficients to:
+
+\begin{enumerate}
+\item On entry to \rou{dyn\_spg\_ts}, remove the contribution of the before
+barotropic velocity to the bottom friction component of the vertically
+integrated momentum trend. Note the same stability check that is carried out 
+on the bottom friction coefficient in \mdl{dynbfr} has to be applied here to
+ensure that the trend removed matches that which was added in \mdl{dynbfr}.
+\item At each barotropic step, compute the contribution of the current barotropic
+velocity to the trend due to bottom friction. Add this contribution to the
+vertically integrated momentum trend. This contribution is handled implicitly which
+eliminates the need to impose a stability criteria on the values of the bottom friction
+coefficient within the barotropic loop. 
+\end{enumerate}
+
+Note that the use of an implicit formulation within the barotropic loop
+for the bottom friction trend means that any limiting of the bottom friction coefficient 
+in \mdl{dynbfr} does not adversely affect the solution when using split-explicit time 
+splitting. This is because the major contribution to bottom friction is likely to come from 
+the barotropic component which uses the unrestricted value of the coefficient. However, if the
+limiting is thought to be having a major effect (a more likely prospect in coastal and shelf seas
+applications) then the fully implicit form of the bottom friction should be used (see \autoref{subsec:ZDF_bfr_imp} ) 
+which can be selected by setting \np{ln\_bfrimp} $=$ \forcode{.true.}.
+
+Otherwise, the implicit formulation takes the form:
+\begin{equation} \label{eq:zdfbfr_implicitts}
+ \bar{U}^{t+ \rdt} = \; \left [ \bar{U}^{t-\rdt}\; + 2 \rdt\;RHS \right ] / \left [ 1 - 2 \rdt \;c_b^{u} / H_e \right ]  
+\end{equation}
+where $\bar U$ is the barotropic velocity, $H_e$ is the full depth (including sea surface height), 
+$c_b^u$ is the bottom friction coefficient as calculated in \rou{zdf\_bfr} and $RHS$ represents 
+all the components to the vertically integrated momentum trend except for that due to bottom friction.
+
+
+
+
+% ================================================================
+% Tidal Mixing
+% ================================================================
+\section{Tidal mixing (\protect\key{zdftmx})}
+\label{sec:ZDF_tmx}
+
+%--------------------------------------------namzdf_tmx--------------------------------------------------
+%
+%\nlst{namzdf_tmx}
+%--------------------------------------------------------------------------------------------------------------
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Bottom intensified tidal mixing 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Bottom intensified tidal mixing}
+\label{subsec:ZDF_tmx_bottom}
+
+Options are defined through the  \ngn{namzdf\_tmx} namelist variables.
+The parameterization of tidal mixing follows the general formulation for 
+the vertical eddy diffusivity proposed by \citet{St_Laurent_al_GRL02} and 
+first introduced in an OGCM by \citep{Simmons_al_OM04}. 
+In this formulation an additional vertical diffusivity resulting from internal tide breaking, 
+$A^{vT}_{tides}$ is expressed as a function of $E(x,y)$, the energy transfer from barotropic 
+tides to baroclinic tides : 
+\begin{equation} \label{eq:Ktides}
+A^{vT}_{tides} =  q \,\Gamma \,\frac{ E(x,y) \, F(z) }{ \rho \, N^2 }
+\end{equation}
+where $\Gamma$ is the mixing efficiency, $N$ the Brunt-Vais\"{a}l\"{a} frequency 
+(see \autoref{subsec:TRA_bn2}), $\rho$ the density, $q$ the tidal dissipation efficiency, 
+and $F(z)$ the vertical structure function. 
+
+The mixing efficiency of turbulence is set by $\Gamma$ (\np{rn\_me} namelist parameter)
+and is usually taken to be the canonical value of $\Gamma = 0.2$ (Osborn 1980). 
+The tidal dissipation efficiency is given by the parameter $q$ (\np{rn\_tfe} namelist parameter) 
+represents the part of the internal wave energy flux $E(x, y)$ that is dissipated locally, 
+with the remaining $1-q$ radiating away as low mode internal waves and 
+contributing to the background internal wave field. A value of $q=1/3$ is typically used  
+\citet{St_Laurent_al_GRL02}.
+The vertical structure function $F(z)$ models the distribution of the turbulent mixing in the vertical. 
+It is implemented as a simple exponential decaying upward away from the bottom, 
+with a vertical scale of $h_o$ (\np{rn\_htmx} namelist parameter, with a typical value of $500\,m$) \citep{St_Laurent_Nash_DSR04}, 
+\begin{equation} \label{eq:Fz}
+F(i,j,k) = \frac{ e^{ -\frac{H+z}{h_o} } }{ h_o \left( 1- e^{ -\frac{H}{h_o} } \right) }
+\end{equation}
+and is normalized so that vertical integral over the water column is unity. 
+
+The associated vertical viscosity is calculated from the vertical 
+diffusivity assuming a Prandtl number of 1, $i.e.$ $A^{vm}_{tides}=A^{vT}_{tides}$. 
+In the limit of $N \rightarrow 0$ (or becoming negative), the vertical diffusivity 
+is capped at $300\,cm^2/s$ and impose a lower limit on $N^2$ of \np{rn\_n2min} 
+usually set to $10^{-8} s^{-2}$. These bounds are usually rarely encountered.
+
+The internal wave energy map, $E(x, y)$ in \autoref{eq:Ktides}, is derived 
+from a barotropic model of the tides utilizing a parameterization of the 
+conversion of barotropic tidal energy into internal waves. 
+The essential goal of the parameterization is to represent the momentum 
+exchange between the barotropic tides and the unrepresented internal waves 
+induced by the tidal flow over rough topography in a stratified ocean. 
+In the current version of \NEMO, the map is built from the output of 
+the barotropic global ocean tide model MOG2D-G \citep{Carrere_Lyard_GRL03}.
+This model provides the dissipation associated with internal wave energy for the M2 and K1 
+tides component (\autoref{fig:ZDF_M2_K1_tmx}). The S2 dissipation is simply approximated
+as being $1/4$ of the M2 one. The internal wave energy is thus : $E(x, y) = 1.25 E_{M2} + E_{K1}$. 
+Its global mean value is $1.1$ TW, in agreement with independent estimates 
+\citep{Egbert_Ray_Nat00, Egbert_Ray_JGR01}. 
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	\begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_ZDF_M2_K1_tmx}
+\caption{  \protect\label{fig:ZDF_M2_K1_tmx} 
+(a) M2 and (b) K1 internal wave drag energy from \citet{Carrere_Lyard_GRL03} ($W/m^2$). }
+\end{center}  	\end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>> 
+ 
+% -------------------------------------------------------------------------------------------------------------
+%        Indonesian area specific treatment 
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Indonesian area specific treatment (\protect\np{ln\_zdftmx\_itf})}
+\label{subsec:ZDF_tmx_itf}
+
+When the Indonesian Through Flow (ITF) area is included in the model domain,
+a specific treatment of tidal induced mixing in this area can be used. 
+It is activated through the namelist logical \np{ln\_tmx\_itf}, and the user must provide
+an input NetCDF file, \ifile{mask\_itf}, which contains a mask array defining the ITF area
+where the specific treatment is applied.
+
+When \np{ln\_tmx\_itf}\forcode{ = .true.}, the two key parameters $q$ and $F(z)$ are adjusted following 
+the parameterisation developed by \citet{Koch-Larrouy_al_GRL07}:
+
+First, the Indonesian archipelago is a complex geographic region 
+with a series of large, deep, semi-enclosed basins connected via 
+numerous narrow straits. Once generated, internal tides remain 
+confined within this semi-enclosed area and hardly radiate away. 
+Therefore all the internal tides energy is consumed within this area. 
+So it is assumed that $q = 1$, $i.e.$ all the energy generated is available for mixing.
+Note that for test purposed, the ITF tidal dissipation efficiency is a 
+namelist parameter (\np{rn\_tfe\_itf}). A value of $1$ or close to is
+this recommended for this parameter.
+
+Second, the vertical structure function, $F(z)$, is no more associated
+with a bottom intensification of the mixing, but with a maximum of 
+energy available within the thermocline. \citet{Koch-Larrouy_al_GRL07} 
+have suggested that the vertical distribution of the energy dissipation 
+proportional to $N^2$ below the core of the thermocline and to $N$ above. 
+The resulting $F(z)$ is:
+\begin{equation} \label{eq:Fz_itf}
+F(i,j,k) \sim     \left\{ \begin{aligned}
+\frac{q\,\Gamma E(i,j) } {\rho N \, \int N     dz}    \qquad \text{when $\partial_z N < 0$} \\
+\frac{q\,\Gamma E(i,j) } {\rho     \, \int N^2 dz}    \qquad \text{when $\partial_z N > 0$}
+                      \end{aligned} \right.
+\end{equation}
+
+Averaged over the ITF area, the resulting tidal mixing coefficient is $1.5\,cm^2/s$, 
+which agrees with the independent estimates inferred from observations. 
+Introduced in a regional OGCM, the parameterization improves the water mass 
+characteristics in the different Indonesian seas, suggesting that the horizontal 
+and vertical distributions of the mixing are adequately prescribed 
+\citep{Koch-Larrouy_al_GRL07, Koch-Larrouy_al_OD08a, Koch-Larrouy_al_OD08b}.
+Note also that such a parameterisation has a significant impact on the behaviour 
+of global coupled GCMs \citep{Koch-Larrouy_al_CD10}.
+
+
+% ================================================================
+% Internal wave-driven mixing
+% ================================================================
+\section{Internal wave-driven mixing (\protect\key{zdftmx\_new})}
+\label{sec:ZDF_tmx_new}
+
+%--------------------------------------------namzdf_tmx_new------------------------------------------
+%
+%\nlst{namzdf_tmx_new}
+%--------------------------------------------------------------------------------------------------------------
+
+The parameterization of mixing induced by breaking internal waves is a generalization 
+of the approach originally proposed by \citet{St_Laurent_al_GRL02}. 
+A three-dimensional field of internal wave energy dissipation $\epsilon(x,y,z)$ is first constructed, 
+and the resulting diffusivity is obtained as 
+\begin{equation} \label{eq:Kwave}
+A^{vT}_{wave} =  R_f \,\frac{ \epsilon }{ \rho \, N^2 }
+\end{equation}
+where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution 
+of the energy available for mixing. If the \np{ln\_mevar} namelist parameter is set to false, 
+the mixing efficiency is taken as constant and equal to 1/6 \citep{Osborn_JPO80}. 
+In the opposite (recommended) case, $R_f$ is instead a function of the turbulence intensity parameter 
+$Re_b = \frac{ \epsilon}{\nu \, N^2}$, with $\nu$ the molecular viscosity of seawater, 
+following the model of \cite{Bouffard_Boegman_DAO2013} 
+and the implementation of \cite{de_lavergne_JPO2016_efficiency}.
+Note that $A^{vT}_{wave}$ is bounded by $10^{-2}\,m^2/s$, a limit that is often reached when the mixing efficiency is constant.
+
+In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary 
+as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to true, a recommended choice). 
+This parameterization of differential mixing, due to \cite{Jackson_Rehmann_JPO2014}, 
+is implemented as in \cite{de_lavergne_JPO2016_efficiency}.
+
+The three-dimensional distribution of the energy available for mixing, $\epsilon(i,j,k)$, is constructed 
+from three static maps of column-integrated internal wave energy dissipation, $E_{cri}(i,j)$, 
+$E_{pyc}(i,j)$, and $E_{bot}(i,j)$, combined to three corresponding vertical structures 
+(de Lavergne et al., in prep):
+\begin{align*}
+F_{cri}(i,j,k) &\propto e^{-h_{ab} / h_{cri} }\\
+F_{pyc}(i,j,k) &\propto N^{n\_p}\\
+F_{bot}(i,j,k) &\propto N^2 \, e^{- h_{wkb} / h_{bot} }
+\end{align*} 
+In the above formula, $h_{ab}$ denotes the height above bottom, 
+$h_{wkb}$ denotes the WKB-stretched height above bottom, defined by
+\begin{equation*}
+h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; ,
+\end{equation*}
+The $n_p$ parameter (given by \np{nn\_zpyc} in \ngn{namzdf\_tmx\_new} namelist)  controls the stratification-dependence of the pycnocline-intensified dissipation. 
+It can take values of 1 (recommended) or 2.
+Finally, the vertical structures $F_{cri}$ and $F_{bot}$ require the specification of 
+the decay scales $h_{cri}(i,j)$ and $h_{bot}(i,j)$, which are defined by two additional input maps. 
+$h_{cri}$ is related to the large-scale topography of the ocean (etopo2) 
+and $h_{bot}$ is a function of the energy flux $E_{bot}$, the characteristic horizontal scale of 
+the abyssal hill topography \citep{Goff_JGR2010} and the latitude.
+
+% ================================================================
+
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_conservation.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_conservation.tex	(revision 10321)
@@ -0,0 +1,337 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% Invariant of the Equations
+% ================================================================
+\chapter{Invariants of the Primitive Equations}
+\label{chap:Invariant}
+\minitoc
+
+The continuous equations of motion have many analytic properties. Many 
+quantities (total mass, energy, enstrophy, etc.) are strictly conserved in 
+the inviscid and unforced limit, while ocean physics conserve the total 
+quantities on which they act (momentum, temperature, salinity) but dissipate 
+their total variance (energy, enstrophy, etc.). Unfortunately, the finite 
+difference form of these equations is not guaranteed to retain all these 
+important properties. In constructing the finite differencing schemes, we 
+wish to ensure that certain integral constraints will be maintained. In 
+particular, it is desirable to construct the finite difference equations so 
+that horizontal kinetic energy and/or potential enstrophy of horizontally 
+non-divergent flow, and variance of temperature and salinity will be 
+conserved in the absence of dissipative effects and forcing. \citet{Arakawa1966} 
+has first pointed out the advantage of this approach. He showed that if 
+integral constraints on energy are maintained, the computation will be free 
+of the troublesome "non linear" instability originally pointed out by 
+\citet{Phillips1959}. A consistent formulation of the energetic properties is 
+also extremely important in carrying out long-term numerical simulations for 
+an oceanographic model. Such a formulation avoids systematic errors that 
+accumulate with time \citep{Bryan1997}.
+
+The general philosophy of OPA which has led to the discrete formulation 
+presented in {\S}II.2 and II.3 is to choose second order non-diffusive 
+scheme for advective terms for both dynamical and tracer equations. At this 
+level of complexity, the resulting schemes are dispersive schemes. 
+Therefore, they require the addition of a diffusive operator to be stable. 
+The alternative is to use diffusive schemes such as upstream or flux 
+corrected schemes. This last option was rejected because we prefer a 
+complete handling of the model diffusion, i.e. of the model physics rather 
+than letting the advective scheme produces its own implicit diffusion 
+without controlling the space and time structure of this implicit diffusion. 
+Note that in some very specific cases as passive tracer studies, the 
+positivity of the advective scheme is required. In that case, and in that 
+case only, the advective scheme used for passive tracer is a flux correction 
+scheme \citep{Marti1992, Levy1996, Levy1998}.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Ocean Dynamics
+% -------------------------------------------------------------------------------------------------------------
+\section{Conservation properties on ocean dynamics}
+\label{sec:Invariant_dyn}
+
+The non linear term of the momentum equations has been split into a 
+vorticity term, a gradient of horizontal kinetic energy and a vertical 
+advection term. Three schemes are available for the former (see {\S}~II.2) 
+according to the CPP variable defined (default option\textbf{ 
+}or \textbf{key{\_}vorenergy } or \textbf{key{\_}vorcombined 
+} defined). They differ in their conservative 
+properties (energy or enstrophy conserving scheme). The two latter terms 
+preserve the total kinetic energy: the large scale kinetic energy is also 
+preserved in practice. The remaining non-diffusive terms of the momentum 
+equation (namely the hydrostatic and surface pressure gradient terms) also 
+preserve the total kinetic energy and have no effect on the vorticity of the 
+flow.
+
+\textbf{* relative, planetary and total vorticity term:}
+
+Let us define as either the relative, planetary and total potential 
+vorticity, i.e. , , and , respectively. The continuous formulation of the 
+vorticity term satisfies following integral constraints:
+\begin{equation} \label{eq:vor_vorticity}
+\int_D {{\textbf {k}}\cdot \frac{1}{e_3 }\nabla \times \left( {\varsigma 
+\;{\rm {\bf k}}\times {\textbf {U}}_h } \right)\;dv} =0
+\end{equation}
+
+\begin{equation} \label{eq:vor_enstrophy}
+if\quad \chi =0\quad \quad \int\limits_D {\varsigma \;{\textbf{k}}\cdot 
+\frac{1}{e_3 }\nabla \times \left( {\varsigma {\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =-\int\limits_D {\frac{1}{2}\varsigma ^2\,\chi \;dv} 
+=0
+\end{equation}
+
+\begin{equation} \label{eq:vor_energy}
+\int_D {{\textbf{U}}_h \times \left( {\varsigma \;{\textbf{k}}\times {\textbf{U}}_h } \right)\;dv} =0
+\end{equation}
+where $dv = e_1\, e_2\, e_3\, di\, dj\, dk$ is the volume element. 
+(II.4.1a) means that $\varsigma $ is conserved. (II.4.1b) is obtained by an 
+integration by part. It means that $\varsigma^2$ is conserved for a horizontally 
+non-divergent flow. 
+(II.4.1c) is even satisfied locally since the vorticity term is orthogonal 
+to the horizontal velocity. It means that the vorticity term has no 
+contribution to the evolution of the total kinetic energy. (II.4.1a) is 
+obviously always satisfied, but (II.4.1b) and (II.4.1c) cannot be satisfied 
+simultaneously with a second order scheme. Using the symmetry or 
+anti-symmetry properties of the operators (Eqs II.1.10 and 11), it can be 
+shown that the scheme (II.2.11) satisfies (II.4.1b) but not (II.4.1c), while 
+scheme (II.2.12) satisfies (II.4.1c) but not (II.4.1b) (see appendix C). 
+Note that the enstrophy conserving scheme on total vorticity has been chosen 
+as the standard discrete form of the vorticity term.
+
+\textbf{* Gradient of kinetic energy / vertical advection}
+
+In continuous formulation, the gradient of horizontal kinetic energy has no 
+contribution to the evolution of the vorticity as the curl of a gradient is 
+zero. This property is satisfied locally with the discrete form of both the 
+gradient and the curl operator we have made (property (II.1.9)~). Another 
+continuous property is that the change of horizontal kinetic energy due to 
+vertical advection is exactly balanced by the change of horizontal kinetic 
+energy due to the horizontal gradient of horizontal kinetic energy:
+
+\begin{equation} \label{eq:keg_zad}
+\int_D {{\textbf{U}}_h \cdot \nabla _h \left( {1/2\;{\textbf{U}}_h ^2} \right)\;dv} =-\int_D {{\textbf{U}}_h \cdot \frac{w}{e_3 }\;\frac{\partial 
+{\textbf{U}}_h }{\partial k}\;dv}
+\end{equation}
+
+Using the discrete form given in {\S}II.2-a and the symmetry or 
+anti-symmetry properties of the mean and difference operators, \autoref{eq:keg_zad} is 
+demonstrated in the Appendix C. The main point here is that satisfying 
+\autoref{eq:keg_zad} links the choice of the discrete forms of the vertical advection 
+and of the horizontal gradient of horizontal kinetic energy. Choosing one 
+imposes the other. The discrete form of the vertical advection given in 
+{\S}II.2-a is a direct consequence of formulating the horizontal kinetic 
+energy as $1/2 \left( \overline{u^2}^i + \overline{v^2}^j \right) $ in the gradient term.
+
+\textbf{* hydrostatic pressure gradient term}
+
+In continuous formulation, a pressure gradient has no contribution to the 
+evolution of the vorticity as the curl of a gradient is zero. This 
+properties is satisfied locally with the choice of discretization we have 
+made (property (II.1.9)~). In addition, when the equation of state is linear 
+(i.e. when an advective-diffusive equation for density can be derived from 
+those of temperature and salinity) the change of horizontal kinetic energy 
+due to the work of pressure forces is balanced by the change of potential 
+energy due to buoyancy forces:
+
+\begin{equation} \label{eq:hpg_pe}
+\int_D {-\frac{1}{\rho _o }\left. {\nabla p^h} \right|_z \cdot {\textbf {U}}_h \;dv} \;=\;\int_D {\nabla .\left( {\rho \,{\textbf{U}}} \right)\;g\;z\;\;dv}
+\end{equation}
+
+Using the discrete form given in {\S}~II.2-a and the symmetry or 
+anti-symmetry properties of the mean and difference operators, (II.4.3) is 
+demonstrated in the Appendix C. The main point here is that satisfying 
+(II.4.3) strongly constraints the discrete expression of the depth of 
+$T$-points and of the term added to the pressure gradient in $s-$coordinates: the 
+depth of a $T$-point, $z_T$, is defined as the sum the vertical scale 
+factors at $w$-points starting from the surface.
+
+\textbf{* surface pressure gradient term}
+
+In continuous formulation, the surface pressure gradient has no contribution 
+to the evolution of vorticity. This properties is trivially satisfied 
+locally as (II.2.3) (the equation verified by $\psi$ has been 
+derived from the discrete formulation of the momentum equations, vertical 
+sum and curl. Nevertheless, the $\psi$-equation is solved numerically by an 
+iterative solver (see {\S}~III.5), thus the property is only satisfied with 
+the accuracy required on the solver. In addition, with the rigid-lid 
+approximation, the change of horizontal kinetic energy due to the work of 
+surface pressure forces is exactly zero:
+\begin{equation} \label{eq:spg}
+\int_D {-\frac{1}{\rho _o }\nabla _h } \left( {p_s } \right)\cdot {\textbf{U}}_h \;dv=0
+\end{equation}
+
+(II.4.4) is satisfied in discrete form only if the discrete barotropic 
+streamfunction time evolution equation is given by (II.2.3) (see appendix 
+C). This shows that (II.2.3) is the only way to compute the streamfunction, 
+otherwise there is no guarantee that the surface pressure force work 
+vanishes.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Ocean Thermodynamics
+% -------------------------------------------------------------------------------------------------------------
+\section{Conservation properties on ocean thermodynamics}
+\label{sec:Invariant_tra}
+
+In continuous formulation, the advective terms of the tracer equations 
+conserve the tracer content and the quadratic form of the tracer, i.e.
+\begin{equation} \label{eq:tra_tra2}
+\int_D {\nabla .\left( {T\;{\textbf{U}}} \right)\;dv} =0
+\;\text{and}
+\int_D {T\;\nabla .\left( {T\;{\textbf{U}}} \right)\;dv} =0
+\end{equation}
+
+The numerical scheme used ({\S}II.2-b) (equations in flux form, second order 
+centred finite differences) satisfies (II.4.5) (see appendix C). Note that 
+in both continuous and discrete formulations, there is generally no strict 
+conservation of mass, since the equation of state is non linear with respect 
+to $T$ and $S$. In practice, the mass is conserved with a very good accuracy. 
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Momentum Physics
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Conservation properties on momentum physics}
+\label{subsec:Invariant_dyn_physics}
+
+\textbf{* lateral momentum diffusion term}
+
+The continuous formulation of the horizontal diffusion of momentum satisfies 
+the following integral constraints~:
+\begin{equation} \label{eq:dynldf_dyn}
+\int\limits_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left[ {\nabla 
+_h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( {A^{lm}\;\zeta 
+\;{\rm {\bf k}}} \right)} \right]\;dv} =0
+\end{equation}
+
+\begin{equation} \label{eq:dynldf_div}
+\int\limits_D {\nabla _h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
+\right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
+\right]\;dv} =0
+\end{equation}
+
+\begin{equation} \label{eq:dynldf_curl}
+\int_D {{\rm {\bf U}}_h \cdot \left[ {\nabla _h \left( {A^{lm}\;\chi } 
+\right)-\nabla _h \times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} 
+\right]\;dv} \leqslant 0
+\end{equation}
+
+\begin{equation} \label{eq:dynldf_curl2}
+\mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\zeta \;{\rm {\bf k}}\cdot 
+\nabla \times \left[ {\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h 
+\times \left( {A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} 
+\leqslant 0
+\end{equation}
+
+\begin{equation} \label{eq:dynldf_div2}
+\mbox{if}\quad A^{lm}=cste\quad \quad \int_D {\chi \;\nabla _h \cdot \left[ 
+{\nabla _h \left( {A^{lm}\;\chi } \right)-\nabla _h \times \left( 
+{A^{lm}\;\zeta \;{\rm {\bf k}}} \right)} \right]\;dv} \leqslant 0
+\end{equation}
+
+
+(II.4.6a) and (II.4.6b) means that the horizontal diffusion of momentum 
+conserve both the potential vorticity and the divergence of the flow, while 
+Eqs (II.4.6c) to (II.4.6e) mean that it dissipates the energy, the enstrophy 
+and the square of the divergence. The two latter properties are only 
+satisfied when the eddy coefficients are horizontally uniform.
+
+Using (II.1.8) and (II.1.9), and the symmetry or anti-symmetry properties of 
+the mean and difference operators, it is shown that the discrete form of the 
+lateral momentum diffusion given in {\S}II.2-c satisfies all the integral 
+constraints (II.4.6) (see appendix C). In particular, when the eddy 
+coefficients are horizontally uniform, a complete separation of vorticity 
+and horizontal divergence fields is ensured, so that diffusion (dissipation) 
+of vorticity (enstrophy) does not generate horizontal divergence (variance 
+of the horizontal divergence) and \textit{vice versa}. When the vertical curl of the horizontal 
+diffusion of momentum (discrete sense) is taken, the term associated to the 
+horizontal gradient of the divergence is zero locally. When the horizontal 
+divergence of the horizontal diffusion of momentum (discrete sense) is 
+taken, the term associated to the vertical curl of the vorticity is zero 
+locally. The resulting term conserves $\chi$ and dissipates 
+$\chi^2$ when the 
+eddy coefficient is horizontally uniform.
+
+\textbf{* vertical momentum diffusion term}
+
+As for the lateral momentum physics, the continuous form of the vertical 
+diffusion of momentum satisfies following integral constraints~:
+
+conservation of momentum, dissipation of horizontal kinetic energy
+
+\begin{equation} \label{eq:dynzdf_dyn}
+\begin{aligned}
+& \int_D {\frac{1}{e_3 }}  \frac{\partial }{\partial k}\left( \frac{A^{vm}}{e_3 }\frac{\partial {\textbf{U}}_h }{\partial k} \right) \;dv = \overrightarrow{\textbf{0}} \\ 
+& \int_D \textbf{U}_h \cdot \frac{1}{e_3} \frac{\partial}{\partial k} \left( {\frac{A^{vm}}{e_3 }}{\frac{\partial \textbf{U}_h }{\partial k}} \right) \;dv \leq 0 \\ 
+ \end{aligned} 
+ \end{equation}
+conservation of vorticity, dissipation of enstrophy
+\begin{equation} \label{eq:dynzdf_vor}
+\begin{aligned}
+& \int_D {\frac{1}{e_3 }{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
+}\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
+{\bf U}}_h }{\partial k}} \right)} \right)\;dv} =0 \\ 
+& \int_D {\zeta \,{\rm {\bf k}}\cdot \nabla \times \left( {\frac{1}{e_3 
+}\frac{\partial }{\partial k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm 
+{\bf U}}_h }{\partial k}} \right)} \right)\;dv} \leq 0 \\ 
+\end{aligned}
+\end{equation}
+conservation of horizontal divergence, dissipation of square of the 
+horizontal divergence
+\begin{equation} \label{eq:dynzdf_div}
+\begin{aligned}
+ &\int_D {\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
+k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
+\right)} \right)\;dv} =0 \\ 
+& \int_D {\chi \;\nabla \cdot \left( {\frac{1}{e_3 }\frac{\partial }{\partial 
+k}\left( {\frac{A^{vm}}{e_3 }\frac{\partial {\rm {\bf U}}_h }{\partial k}} 
+\right)} \right)\;dv} \leq 0 \\ 
+\end{aligned}
+\end{equation}
+
+In discrete form, all these properties are satisfied in $z$-coordinate (see 
+Appendix C). In $s$-coordinates, only first order properties can be 
+demonstrated, i.e. the vertical momentum physics conserve momentum, 
+potential vorticity, and horizontal divergence.
+
+% -------------------------------------------------------------------------------------------------------------
+%       Conservation Properties on Tracer Physics
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Conservation properties on tracer physics}
+\label{subsec:Invariant_tra_physics}
+
+The numerical schemes used for tracer subgridscale physics are written in 
+such a way that the heat and salt contents are conserved (equations in flux 
+form, second order centred finite differences). As a form flux is used to 
+compute the temperature and salinity, the quadratic form of these quantities 
+(i.e. their variance) globally tends to diminish. As for the advective term, 
+there is generally no strict conservation of mass even if, in practice, the 
+mass is conserved with a very good accuracy. 
+
+\textbf{* lateral physics: }conservation of tracer, dissipation of tracer 
+variance, i.e.
+
+\begin{equation} \label{eq:traldf_t_t2}
+\begin{aligned}
+&\int_D \nabla\, \cdot\, \left( A^{lT} \,\Re \,\nabla \,T \right)\;dv = 0 \\ 
+&\int_D \,T\, \nabla\, \cdot\, \left( A^{lT} \,\Re \,\nabla \,T \right)\;dv \leq 0 \\ 
+\end{aligned}
+\end{equation}
+
+\textbf{* vertical physics: }conservation of tracer, dissipation of tracer 
+variance, i.e.
+
+\begin{equation} \label{eq:trazdf_t_t2}
+\begin{aligned}
+& \int_D \frac{1}{e_3 } \frac{\partial }{\partial k}\left( \frac{A^{vT}}{e_3 }  \frac{\partial T}{\partial k}  \right)\;dv = 0 \\ 
+& \int_D \,T \frac{1}{e_3 } \frac{\partial }{\partial k}\left( \frac{A^{vT}}{e_3 }  \frac{\partial T}{\partial k}  \right)\;dv \leq 0 \\ 
+\end{aligned}
+\end{equation}
+
+Using the symmetry or anti-symmetry properties of the mean and difference 
+operators, it is shown that the discrete form of tracer physics given in 
+{\S}~II.2-c satisfies all the integral constraints (II.4.8) and (II.4.9) 
+except the dissipation of the square of the tracer when non-geopotential 
+diffusion is used (see appendix C). A discrete form of the lateral tracer 
+physics can be derived which satisfies these last properties. Nevertheless, 
+it requires a horizontal averaging of the vertical component of the lateral 
+physics that prevents the use of implicit resolution in the vertical. It has 
+not been implemented.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_misc.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_misc.tex	(revision 10321)
@@ -0,0 +1,284 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter --- Miscellaneous Topics
+% ================================================================
+\chapter{Miscellaneous Topics}
+\label{chap:MISC}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Representation of Unresolved Straits
+% ================================================================
+\section{Representation of unresolved straits}
+\label{sec:MISC_strait}
+
+In climate modeling, it often occurs that a crucial connections between water masses
+is broken as the grid mesh is too coarse to resolve narrow straits. For example, coarse 
+grid spacing typically closes off the Mediterranean from the Atlantic at the Strait of 
+Gibraltar. In this case, it is important for climate models to include the effects of salty 
+water entering the Atlantic from the Mediterranean. Likewise, it is important for the 
+Mediterranean to replenish its supply of water from the Atlantic to balance the net 
+evaporation occurring over the Mediterranean region. This problem occurs even in 
+eddy permitting simulations. For example, in ORCA 1/4\deg several straits of the Indonesian 
+archipelago (Ombai, Lombok...) are much narrow than even a single ocean grid-point.
+
+We describe briefly here the three methods that can be used in \NEMO to handle 
+such improperly resolved straits. The first two consist of opening the strait by hand 
+while ensuring that the mass exchanges through the strait are not too large by 
+either artificially reducing the surface of the strait grid-cells or, locally increasing 
+the lateral friction. In the third one, the strait is closed but exchanges of mass, 
+heat and salt across the land are allowed.
+Note that such modifications are so specific to a given configuration that no attempt 
+has been made to set them in a generic way. However, examples of how 
+they can be set up is given in the ORCA 2\deg and 0.5\deg configurations. For example, 
+for details of implementation in ORCA2, search: 
+\texttt{ IF( cp\_cfg == "orca" .AND. jp\_cfg == 2 ) }
+
+% -------------------------------------------------------------------------------------------------------------
+%       Hand made geometry changes
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Hand made geometry changes}
+\label{subsec:MISC_strait_hand}
+
+$\bullet$ reduced scale factor in the cross-strait direction to a value in better agreement 
+with the true mean width of the strait. (\autoref{fig:MISC_strait_hand}).
+This technique is sometime called "partially open face" or "partially closed cells".
+The key issue here is only to reduce the faces of $T$-cell ($i.e.$ change the value 
+of the horizontal scale factors at $u$- or $v$-point) but not the volume of the $T$-cell.
+Indeed, reducing the volume of strait $T$-cell can easily produce a numerical 
+instability at that grid point that would require a reduction of the model time step.
+The changes associated with strait management are done in \mdl{domhgr}, 
+just after the definition or reading of the horizontal scale factors. 
+
+$\bullet$ increase of the viscous boundary layer thickness by local increase of the 
+fmask value at the coast (\autoref{fig:MISC_strait_hand}). This is done in 
+\mdl{dommsk} together with the setting of the coastal value of fmask 
+(see  \autoref{sec:LBC_coast})
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tbp] 	 \begin{center}
+\includegraphics[width=0.80\textwidth]{Fig_Gibraltar}
+\includegraphics[width=0.80\textwidth]{Fig_Gibraltar2}
+\caption{	\protect\label{fig:MISC_strait_hand} 
+Example of the Gibraltar strait defined in a $1^{\circ} \times 1^{\circ}$ mesh. 
+\textit{Top}: using partially open cells. The meridional scale factor at $v$-point 
+is reduced on both sides of the strait to account for the real width of the strait 
+(about 20 km). Note that the scale factors of the strait $T$-point remains unchanged. 
+\textit{Bottom}: using viscous boundary layers. The four fmask parameters 
+along the strait coastlines are set to a value larger than 4, $i.e.$ "strong" no-slip 
+case (see \autoref{fig:LBC_shlat}) creating a large viscous boundary layer 
+that allows a reduced transport through the strait.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+% ================================================================
+% Closed seas
+% ================================================================
+\section{Closed seas (\protect\mdl{closea})}
+\label{sec:MISC_closea}
+
+\colorbox{yellow}{Add here a short description of the way closed seas are managed}
+
+
+% ================================================================
+% Sub-Domain Functionality 
+% ================================================================
+\section{Sub-domain functionality}
+\label{sec:MISC_zoom}
+
+\subsection{Simple subsetting of input files via NetCDF attributes}
+
+The extended grids for use with the under-shelf ice cavities will result in redundant rows
+around Antarctica if the ice cavities are not active. A simple mechanism for subsetting
+input files associated with the extended domains has been implemented to avoid the need to
+maintain different sets of input fields for use with or without active ice cavities. The
+existing 'zoom' options are overly complex for this task and marked for deletion anyway.
+This alternative subsetting operates for the j-direction only and works by optionally
+looking for and using a global file attribute (named: \np{open\_ocean\_jstart}) to
+determine the starting j-row for input. The use of this option is best explained with an
+example: Consider an ORCA1 configuration using the extended grid bathymetry and coordinate
+files:
+\vspace{-10pt}
+\ifile{eORCA1\_bathymetry\_v2}
+\ifile{eORCA1\_coordinates}
+\noindent These files define a horizontal domain of 362x332. Assuming the first row with
+open ocean wet points in the non-isf bathymetry for this set is row 42 (Fortran indexing)
+then the formally correct setting for \np{open\_ocean\_jstart} is 41. Using this value as the
+first row to be read will result in a 362x292 domain which is the same size as the original
+ORCA1 domain. Thus the extended coordinates and bathymetry files can be used with all the
+original input files for ORCA1 if the ice cavities are not active (\np{ln\_isfcav =
+.false.}). Full instructions for achieving this are:
+
+\noindent Add the new attribute to any input files requiring a j-row offset, i.e:
+\vspace{-10pt}
+\begin{cmds}
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_coordinates.nc 
+ncatted  -a open_ocean_jstart,global,a,d,41 eORCA1_bathymetry_v2.nc
+\end{cmds}
+ 
+\noindent Add the logical switch to \ngn{namcfg} in the configuration namelist and set true:
+%--------------------------------------------namcfg--------------------------------------------------------
+
+\nlst{namcfg}
+%--------------------------------------------------------------------------------------------------------------
+
+\noindent Note the j-size of the global domain is the (extended j-size minus
+\np{open\_ocean\_jstart} + 1 ) and this must match the size of all datasets other than
+bathymetry and coordinates currently. However the option can be extended to any global, 2D
+and 3D, netcdf, input field by adding the:
+\vspace{-10pt}
+\begin{forlines}
+lrowattr=ln_use_jattr
+\end{forlines}
+optional argument to the appropriate \np{iom\_get} call and the \np{open\_ocean\_jstart} attribute to the corresponding input files. It remains the users responsibility to set \np{jpjdta} and \np{jpjglo} values in the \np{namelist\_cfg} file according to their needs.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht] 	  \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_LBC_zoom}
+\caption{	\protect\label{fig:LBC_zoom}
+Position of a model domain compared to the data input domain when the zoom functionality is used.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+% ================================================================
+% Accuracy and Reproducibility
+% ================================================================
+\section{Accuracy and reproducibility (\protect\mdl{lib\_fortran})}
+\label{sec:MISC_fortran}
+
+\subsection{Issues with intrinsinc SIGN function (\protect\key{nosignedzero})}
+\label{subsec:MISC_sign}
+
+The SIGN(A, B) is the \textsc {Fortran} intrinsic function delivers the magnitude 
+of A with the sign of B. For example, SIGN(-3.0,2.0) has the value 3.0.
+The problematic case is when the second argument is zero, because, on platforms 
+that support IEEE arithmetic, zero is actually a signed number. 
+There is a positive zero and a negative zero.
+
+In \textsc{Fortran}~90, the processor was required always to deliver a positive result for SIGN(A, B) 
+if B was zero. Nevertheless, in \textsc{Fortran}~95, the processor is allowed to do the correct thing 
+and deliver ABS(A) when B is a positive zero and -ABS(A) when B is a negative zero. 
+This change in the specification becomes apparent only when B is of type real, and is zero, 
+and the processor is capable of distinguishing between positive and negative zero, 
+and B is negative real zero. Then SIGN delivers a negative result where, under \textsc{Fortran}~90 
+rules,  it used to return a positive result. 
+This change may be especially sensitive for the ice model, so we overwrite the intrinsinc 
+function with our own function simply performing :   \\
+\verb?   IF( B >= 0.e0 ) THEN   ;   SIGN(A,B) = ABS(A)  ?    \\
+\verb?   ELSE                   ;   SIGN(A,B) =-ABS(A)     ?  \\
+\verb?   ENDIF    ? \\
+This feature can be found in \mdl{lib\_fortran} module and is effective when \key{nosignedzero}
+is defined. We use a CPP key as the overwritting of a intrinsic function can present 
+performance issues with some computers/compilers.
+
+
+\subsection{MPP reproducibility}
+\label{subsec:MISC_glosum}
+
+The numerical reproducibility of simulations on distributed memory parallel computers 
+is a critical issue. In particular, within NEMO global summation of distributed arrays 
+is most susceptible to rounding errors, and their propagation and accumulation cause 
+uncertainty in final simulation reproducibility on different numbers of processors.
+To avoid so, based on \citet{He_Ding_JSC01} review of different technics, 
+we use a so called self-compensated summation method. The idea is to estimate 
+the roundoff error, store it in a buffer, and then add it back in the next addition. 
+
+Suppose we need to calculate $b = a_1 + a_2 + a_3$. The following algorithm 
+will allow to split the sum in two ($sum_1 = a_{1} + a_{2}$ and $b = sum_2 = sum_1 + a_3$) 
+with exactly the same rounding errors as the sum performed all at once.
+\begin{align*}
+	sum_1 \ \  &= a_1 + a_2 \\
+	error_1     &= a_2 + ( a_1 - sum_1 ) \\
+	sum_2 \ \  &= sum_1 + a_3 + error_1 \\
+	error_2     &= a_3 + error_1 + ( sum_1 - sum_2 ) \\
+	b \qquad \ &= sum_2 \\
+\end{align*}
+An example of this feature can be found in \mdl{lib\_fortran} module.
+It is systematicallt used in glob\_sum function (summation over the entire basin excluding 
+duplicated rows and columns due to cyclic or north fold boundary condition as well as 
+overlap MPP areas). The self-compensated summation method should be used in all summation
+in i- and/or j-direction. See \mdl{closea} module for an example.
+Note also that this implementation may be sensitive to the optimization level. 
+
+\subsection{MPP scalability}
+\label{subsec:MISC_mppsca}
+
+The default method of communicating values across the north-fold in distributed memory applications
+(\key{mpp\_mpi}) uses a \textsc{MPI\_ALLGATHER} function to exchange values from each processing
+region in the northern row with every other processing region in the northern row. This enables a
+global width array containing the top 4 rows to be collated on every northern row processor and then
+folded with a simple algorithm. Although conceptually simple, this "All to All" communication will
+hamper performance scalability for large numbers of northern row processors. From version 3.4
+onwards an alternative method is available which only performs direct "Peer to Peer" communications
+between each processor and its immediate "neighbours" across the fold line. This is achieved by
+using the default \textsc{MPI\_ALLGATHER} method during initialisation to help identify the "active"
+neighbours. Stored lists of these neighbours are then used in all subsequent north-fold exchanges to
+restrict exchanges to those between associated regions. The collated global width array for each
+region is thus only partially filled but is guaranteed to be set at all the locations actually
+required by each individual for the fold operation. This alternative method should give identical
+results to the default \textsc{ALLGATHER} method and is recommended for large values of \np{jpni}.
+The new method is activated by setting \np{ln\_nnogather} to be true ({\bf nammpp}). The
+reproducibility of results using the two methods should be confirmed for each new, non-reference
+configuration.
+
+% ================================================================
+% Model optimisation, Control Print and Benchmark
+% ================================================================
+\section{Model optimisation, control print and benchmark}
+\label{sec:MISC_opt}
+%--------------------------------------------namctl-------------------------------------------------------
+
+\nlst{namctl} 
+%--------------------------------------------------------------------------------------------------------------
+
+ \gmcomment{why not make these bullets into subsections?}
+Options are defined through the  \ngn{namctl} namelist variables.
+
+$\bullet$ Vector optimisation:
+
+\key{vectopt\_loop} enables the internal loops to collapse. This is very 
+a very efficient way to increase the length of vector calculations and thus 
+to speed up the model on vector computers.
+ 
+% Add here also one word on NPROMA technique that has been found useless, since compiler have made significant progress during the last decade.
+ 
+% Add also one word on NEC specific optimisation (Novercheck option for example)
+ 
+$\bullet$ Control print %: describe here 4 things:
+
+1- \np{ln\_ctl} : compute and print the trends averaged over the interior domain 
+in all TRA, DYN, LDF and ZDF modules. This option is very helpful when 
+diagnosing the origin of an undesired change in model results. 
+
+2- also \np{ln\_ctl} but using the nictl and njctl namelist parameters to check 
+the source of differences between mono and multi processor runs.
+
+%%gm   to be removed both here and in the code
+3- last digit comparison (\np{nn\_bit\_cmp}). In an MPP simulation, the computation of 
+a sum over the whole domain is performed as the summation over all processors of 
+each of their sums over their interior domains. This double sum never gives exactly 
+the same result as a single sum over the whole domain, due to truncation differences. 
+The "bit comparison" option has been introduced in order to be able to check that 
+mono-processor and multi-processor runs give exactly the same results. 
+%THIS is to be updated with the mpp_sum_glo  introduced in v3.3
+% nn_bit_cmp  today only check that the nn_cla = 0 (no cross land advection)
+%%gm end
+
+$\bullet$  Benchmark (\np{nn\_bench}). This option defines a benchmark run based on 
+a GYRE configuration (see \autoref{sec:CFG_gyre}) in which the resolution remains the same 
+whatever the domain size. This allows a very large model domain to be used, just by 
+changing the domain size (\jp{jpiglo}, \jp{jpjglo}) and without adjusting either the time-step 
+or the physical parameterisations. 
+
+% ================================================================
+\end{document}
+
+
+
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics.tex	(revision 10321)
@@ -0,0 +1,1252 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter 1 Ñ Model Basics
+% ================================================================
+
+\chapter{Model Basics}
+\label{chap:PE}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new ligne
+
+% ================================================================
+% Primitive Equations
+% ================================================================
+\section{Primitive equations}
+\label{sec:PE_PE}
+
+% -------------------------------------------------------------------------------------------------------------
+%        Vector Invariant Formulation 
+% -------------------------------------------------------------------------------------------------------------
+
+\subsection{Vector invariant formulation}
+\label{subsec:PE_Vector}
+
+
+The ocean is a fluid that can be described to a good approximation by the primitive 
+equations, $i.e.$ the Navier-Stokes equations along with a nonlinear equation of 
+state which couples the two active tracers (temperature and salinity) to the fluid 
+velocity, plus the following additional assumptions made from scale considerations:
+
+\textit{(1) spherical earth approximation: }the geopotential surfaces are assumed to 
+be spheres so that gravity (local vertical) is parallel to the earth's radius
+
+\textit{(2) thin-shell approximation: }the ocean depth is neglected compared to the earth's radius
+
+\textit{(3) turbulent closure hypothesis: }the turbulent fluxes (which represent the effect 
+of small scale processes on the large-scale) are expressed in terms of large-scale features
+
+\textit{(4) Boussinesq hypothesis:} density variations are neglected except in their 
+contribution to the buoyancy force
+
+\textit{(5) Hydrostatic hypothesis: }the vertical momentum equation is reduced to a 
+balance between the vertical pressure gradient and the buoyancy force (this removes 
+convective processes from the initial Navier-Stokes equations and so convective processes 
+must be parameterized instead)
+
+\textit{(6) Incompressibility hypothesis: }the three dimensional divergence of the velocity 
+vector is assumed to be zero.
+
+Because the gravitational force is so dominant in the equations of large-scale motions, 
+it is useful to choose an orthogonal set of unit vectors (\textbf{i},\textbf{j},\textbf{k}) linked 
+to the earth such that \textbf{k} is the local upward vector and (\textbf{i},\textbf{j}) are two 
+vectors orthogonal to \textbf{k}, $i.e.$ tangent to the geopotential surfaces. Let us define 
+the following variables: \textbf{U} the vector velocity, $\textbf{U}=\textbf{U}_h + w\, \textbf{k}$ 
+(the subscript $h$ denotes the local horizontal vector, $i.e.$ over the (\textbf{i},\textbf{j}) plane), 
+$T$ the potential temperature, $S$ the salinity, \textit{$\rho $} the \textit{in situ} density. 
+The vector invariant form of the primitive equations in the (\textbf{i},\textbf{j},\textbf{k}) 
+vector system provides the following six equations (namely the momentum balance, the 
+hydrostatic equilibrium, the incompressibility equation, the heat and salt conservation 
+equations and an equation of state):
+\begin{subequations} \label{eq:PE}
+  \begin{equation}     \label{eq:PE_dyn}
+\frac{\partial {\rm {\bf U}}_h }{\partial t}=
+-\left[    {\left( {\nabla \times {\rm {\bf U}}} \right)\times {\rm {\bf U}}
+            +\frac{1}{2}\nabla \left( {{\rm {\bf U}}^2} \right)}    \right]_h
+ -f\;{\rm {\bf k}}\times {\rm {\bf U}}_h 
+-\frac{1}{\rho _o }\nabla _h p + {\rm {\bf D}}^{\rm {\bf U}} + {\rm {\bf F}}^{\rm {\bf U}}
+  \end{equation}
+  \begin{equation}     \label{eq:PE_hydrostatic}
+\frac{\partial p }{\partial z} = - \rho \ g
+  \end{equation}
+  \begin{equation}     \label{eq:PE_continuity}
+\nabla \cdot {\bf U}=  0
+  \end{equation}
+\begin{equation} \label{eq:PE_tra_T}
+\frac{\partial T}{\partial t} = - \nabla \cdot  \left( T \ \rm{\bf U} \right) + D^T + F^T
+  \end{equation}
+  \begin{equation}     \label{eq:PE_tra_S}
+\frac{\partial S}{\partial t} = - \nabla \cdot  \left( S \ \rm{\bf U} \right) + D^S + F^S
+  \end{equation}
+  \begin{equation}     \label{eq:PE_eos}
+\rho = \rho \left( T,S,p \right)
+  \end{equation}
+\end{subequations}
+where $\nabla$ is the generalised derivative vector operator in $(\bf i,\bf j, \bf k)$ directions, 
+$t$ is the time, $z$ is the vertical coordinate, $\rho $ is the \textit{in situ} density given by 
+the equation of state (\autoref{eq:PE_eos}), $\rho_o$ is a reference density, $p$ the pressure, 
+$f=2 \bf \Omega \cdot \bf k$ is the Coriolis acceleration (where $\bf \Omega$ is the Earth's 
+angular velocity vector), and $g$ is the gravitational acceleration. 
+${\rm {\bf D}}^{\rm {\bf U}}$, $D^T$ and $D^S$ are the parameterisations of small-scale 
+physics for momentum, temperature and salinity, and ${\rm {\bf F}}^{\rm {\bf U}}$, $F^T$ 
+and $F^S$ surface forcing terms. Their nature and formulation are discussed in 
+\autoref{sec:PE_zdf_ldf} and \autoref{subsec:PE_boundary_condition}.
+
+.
+
+% -------------------------------------------------------------------------------------------------------------
+% Boundary condition
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Boundary conditions}
+\label{subsec:PE_boundary_condition}
+
+An ocean is bounded by complex coastlines, bottom topography at its base and an air-sea 
+or ice-sea interface at its top. These boundaries can be defined by two surfaces, $z=-H(i,j)$ 
+and $z=\eta(i,j,k,t)$, where $H$ is the depth of the ocean bottom and $\eta$ is the height 
+of the sea surface. Both $H$ and $\eta$ are usually referenced to a given surface, $z=0$, 
+chosen as a mean sea surface (\autoref{fig:ocean_bc}). Through these two boundaries, 
+the ocean can exchange fluxes of heat, fresh water, salt, and momentum with the solid earth, 
+the continental margins, the sea ice and the atmosphere. However, some of these fluxes are 
+so weak that even on climatic time scales of thousands of years they can be neglected. 
+In the following, we briefly review the fluxes exchanged at the interfaces between the ocean 
+and the other components of the earth system.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!ht]	 \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_I_ocean_bc}
+\caption{	 \protect\label{fig:ocean_bc} 
+The ocean is bounded by two surfaces, $z=-H(i,j)$ and $z=\eta(i,j,t)$, where $H$ 
+is the depth of the sea floor and $\eta$ the height of the sea surface. 
+Both $H$ and $\eta$ are referenced to $z=0$.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+\begin{description}
+\item[Land - ocean interface:] the major flux between continental margins and the ocean is 
+a mass exchange of fresh water through river runoff. Such an exchange modifies the sea 
+surface salinity especially in the vicinity of major river mouths. It can be neglected for short 
+range integrations but has to be taken into account for long term integrations as it influences 
+the characteristics of water masses formed (especially at high latitudes). It is required in order 
+to close the water cycle of the climate system. It is usually specified as a fresh water flux at 
+the air-sea interface in the vicinity of river mouths.
+\item[Solid earth - ocean interface:] heat and salt fluxes through the sea floor are small, 
+except in special areas of little extent. They are usually neglected in the model 
+\footnote{In fact, it has been shown that the heat flux associated with the solid Earth cooling 
+($i.e.$the geothermal heating) is not negligible for the thermohaline circulation of the world 
+ocean (see \autoref{subsec:TRA_bbc}).}. 
+The boundary condition is thus set to no flux of heat and salt across solid boundaries. 
+For momentum, the situation is different. There is no flow across solid boundaries, 
+$i.e.$ the velocity normal to the ocean bottom and coastlines is zero (in other words, 
+the bottom velocity is parallel to solid boundaries). This kinematic boundary condition 
+can be expressed as:
+\begin{equation} \label{eq:PE_w_bbc}
+w = -{\rm {\bf U}}_h \cdot  \nabla _h \left( H \right)
+\end{equation}
+In addition, the ocean exchanges momentum with the earth through frictional processes. 
+Such momentum transfer occurs at small scales in a boundary layer. It must be parameterized 
+in terms of turbulent fluxes using bottom and/or lateral boundary conditions. Its specification 
+depends on the nature of the physical parameterisation used for ${\rm {\bf D}}^{\rm {\bf U}}$ 
+in \autoref{eq:PE_dyn}. It is discussed in \autoref{eq:PE_zdf}.% and Chap. III.6 to 9.
+\item[Atmosphere - ocean interface:] the kinematic surface condition plus the mass flux 
+of fresh water PE  (the precipitation minus evaporation budget) leads to: 
+\begin{equation} \label{eq:PE_w_sbc}
+w = \frac{\partial \eta }{\partial t} 
+    + \left. {{\rm {\bf U}}_h } \right|_{z=\eta } \cdot  \nabla _h \left( \eta \right) 
+    + P-E
+\end{equation}
+The dynamic boundary condition, neglecting the surface tension (which removes capillary 
+waves from the system) leads to the continuity of pressure across the interface $z=\eta$. 
+The atmosphere and ocean also exchange horizontal momentum (wind stress), and heat.
+\item[Sea ice - ocean interface:] the ocean and sea ice exchange heat, salt, fresh water 
+and momentum. The sea surface temperature is constrained to be at the freezing point 
+at the interface. Sea ice salinity is very low ($\sim4-6 \,psu$) compared to those of the 
+ocean ($\sim34 \,psu$). The cycle of freezing/melting is associated with fresh water and 
+salt fluxes that cannot be neglected.
+\end{description}
+
+
+%\newpage
+%$\ $\newline    % force a new ligne
+
+% ================================================================
+% The Horizontal Pressure Gradient
+% ================================================================
+\section{Horizontal pressure gradient }
+\label{sec:PE_hor_pg}
+
+% -------------------------------------------------------------------------------------------------------------
+% Pressure Formulation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Pressure formulation}
+\label{subsec:PE_p_formulation}
+
+The total pressure at a given depth $z$ is composed of a surface pressure $p_s$ at a 
+reference geopotential surface ($z=0$) and a hydrostatic pressure $p_h$ such that: 
+$p(i,j,k,t)=p_s(i,j,t)+p_h(i,j,k,t)$. The latter is computed by integrating (\autoref{eq:PE_hydrostatic}), 
+assuming that pressure in decibars can be approximated by depth in meters in (\autoref{eq:PE_eos}). 
+The hydrostatic pressure is then given by:
+\begin{equation} \label{eq:PE_pressure}
+p_h \left( {i,j,z,t} \right)
+ = \int_{\varsigma =z}^{\varsigma =0} {g\;\rho \left( {T,S,\varsigma} \right)\;d\varsigma } 
+\end{equation}
+ Two strategies can be considered for the surface pressure term: $(a)$ introduce of a 
+ new variable $\eta$, the free-surface elevation, for which a prognostic equation can be 
+ established and solved; $(b)$ assume that the ocean surface is a rigid lid, on which the 
+ pressure (or its horizontal gradient) can be diagnosed. When the former strategy is used, 
+ one solution of the free-surface elevation consists of the excitation of external gravity waves. 
+ The flow is barotropic and the surface moves up and down with gravity as the restoring force. 
+ The phase speed of such waves is high (some hundreds of metres per second) so that 
+ the time step would have to be very short if they were present in the model. The latter 
+ strategy filters out these waves since the rigid lid approximation implies $\eta=0$, $i.e.$ 
+ the sea surface is the surface $z=0$. This well known approximation increases the surface 
+ wave speed to infinity and modifies certain other longwave dynamics ($e.g.$ barotropic 
+ Rossby or planetary waves). The rigid-lid hypothesis is an obsolescent feature in modern 
+ OGCMs. It has been available until the release 3.1 of  \NEMO, and it has been removed
+ in release 3.2 and followings. Only the free surface formulation is now described in the
+ this document (see the next sub-section).
+
+% -------------------------------------------------------------------------------------------------------------
+% Free Surface Formulation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Free surface formulation}
+\label{subsec:PE_free_surface}
+
+In the free surface formulation, a variable $\eta$, the sea-surface height, is introduced 
+which describes the shape of the air-sea interface. This variable is solution of a 
+prognostic equation which is established by forming the vertical average of the kinematic 
+surface condition (\autoref{eq:PE_w_bbc}):
+\begin{equation} \label{eq:PE_ssh}
+\frac{\partial \eta }{\partial t}=-D+P-E
+ 	\quad \text{where} \ 
+D=\nabla \cdot \left[ {\left( {H+\eta } \right) \; {\rm{\bf \overline{U}}}_h \,} \right]
+\end{equation}
+and using (\autoref{eq:PE_hydrostatic}) the surface pressure is given by: $p_s = \rho \, g \, \eta$.
+
+Allowing the air-sea interface to move introduces the external gravity waves (EGWs) 
+as a class of solution of the primitive equations. These waves are barotropic because 
+of hydrostatic assumption, and their phase speed is quite high. Their time scale is 
+short with respect to the other processes described by the primitive equations.
+
+Two choices can be made regarding the implementation of the free surface in the model, 
+depending on the physical processes of interest. 
+
+$\bullet$ If one is interested in EGWs, in particular the tides and their interaction 
+with the baroclinic structure of the ocean (internal waves) possibly in shallow seas, 
+then a non linear free surface is the most appropriate. This means that no 
+approximation is made in (\autoref{eq:PE_ssh}) and that the variation of the ocean 
+volume is fully taken into account. Note that in order to study the fast time scales 
+associated with EGWs it is necessary to minimize time filtering effects (use an 
+explicit time scheme with very small time step, or a split-explicit scheme with 
+reasonably small time step, see \autoref{subsec:DYN_spg_exp} or \autoref{subsec:DYN_spg_ts}.
+
+$\bullet$ If one is not interested in EGW but rather sees them as high frequency 
+noise, it is possible to apply an explicit filter to slow down the fastest waves while 
+not altering the slow barotropic Rossby waves. If further, an approximative conservation 
+of heat and salt contents is sufficient for the problem solved, then it is 
+sufficient to solve a linearized version of (\autoref{eq:PE_ssh}), which still allows 
+to take into account freshwater fluxes applied at the ocean surface \citep{Roullet_Madec_JGR00}.
+Nevertheless, with the linearization, an exact conservation of heat and salt contents is lost.
+
+The filtering of EGWs in models with a free surface is usually a matter of discretisation 
+of the temporal derivatives, using a split-explicit method \citep{Killworth_al_JPO91, Zhang_Endoh_JGR92} 
+or the implicit scheme \citep{Dukowicz1994} or the addition of a filtering force in the momentum equation 
+\citep{Roullet_Madec_JGR00}. With the present release, \NEMO offers the choice between 
+an explicit free surface (see \autoref{subsec:DYN_spg_exp}) or a split-explicit scheme strongly 
+inspired the one proposed by \citet{Shchepetkin_McWilliams_OM05} (see \autoref{subsec:DYN_spg_ts}).
+
+%\newpage
+%$\ $\newline    % force a new line
+
+% ================================================================
+% Curvilinear z-coordinate System
+% ================================================================
+\section{Curvilinear \textit{z-}coordinate system}
+\label{sec:PE_zco}
+
+
+% -------------------------------------------------------------------------------------------------------------
+% Tensorial Formalism
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Tensorial formalism}
+\label{subsec:PE_tensorial}
+
+In many ocean circulation problems, the flow field has regions of enhanced dynamics 
+($i.e.$ surface layers, western boundary currents, equatorial currents, or ocean fronts). 
+The representation of such dynamical processes can be improved by specifically increasing 
+the model resolution in these regions. As well, it may be convenient to use a lateral 
+boundary-following coordinate system to better represent coastal dynamics. Moreover, 
+the common geographical coordinate system has a singular point at the North Pole that 
+cannot be easily treated in a global model without filtering. A solution consists of introducing 
+an appropriate coordinate transformation that shifts the singular point onto land 
+\citep{Madec_Imbard_CD96, Murray_JCP96}. As a consequence, it is important to solve the primitive 
+equations in various curvilinear coordinate systems. An efficient way of introducing an 
+appropriate coordinate transform can be found when using a tensorial formalism. 
+This formalism is suited to any multidimensional curvilinear coordinate system. Ocean 
+modellers mainly use three-dimensional orthogonal grids on the sphere (spherical earth 
+approximation), with preservation of the local vertical. Here we give the simplified equations 
+for this particular case. The general case is detailed by \citet{Eiseman1980} in their survey 
+of the conservation laws of fluid dynamics.
+
+Let (\textit{i},\textit{j},\textit{k}) be a set of orthogonal curvilinear coordinates on the sphere 
+associated with the positively oriented orthogonal set of unit vectors (\textbf{i},\textbf{j},\textbf{k}) 
+linked to the earth such that \textbf{k} is the local upward vector and (\textbf{i},\textbf{j}) are 
+two vectors orthogonal to \textbf{k}, $i.e.$ along geopotential surfaces (\autoref{fig:referential}). 
+Let $(\lambda,\varphi,z)$ be the geographical coordinate system in which a position is defined 
+by the latitude $\varphi(i,j)$, the longitude $\lambda(i,j)$ and the distance from the centre of 
+the earth $a+z(k)$ where $a$ is the earth's radius and $z$ the altitude above a reference sea 
+level (\autoref{fig:referential}). The local deformation of the curvilinear coordinate system is 
+given by $e_1$, $e_2$ and $e_3$, the three scale factors:
+\begin{equation} \label{eq:scale_factors}
+\begin{aligned}
+ e_1 &=\left( {a+z} \right)\;\left[ {\left( {\frac{\partial \lambda 
+}{\partial i}\cos \varphi } \right)^2+\left( {\frac{\partial \varphi 
+}{\partial i}} \right)^2} \right]^{1/2} \\ 
+ e_2 &=\left( {a+z} \right)\;\left[ {\left( {\frac{\partial \lambda 
+}{\partial j}\cos \varphi } \right)^2+\left( {\frac{\partial \varphi 
+}{\partial j}} \right)^2} \right]^{1/2} \\ 
+ e_3 &=\left( {\frac{\partial z}{\partial k}} \right) \\ 
+ \end{aligned}
+ \end{equation}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!tb] 	 \begin{center}
+\includegraphics[width=0.60\textwidth]{Fig_I_earth_referential}
+\caption{	\protect\label{fig:referential} 
+the geographical coordinate system $(\lambda,\varphi,z)$ and the curvilinear 
+coordinate system (\textbf{i},\textbf{j},\textbf{k}). }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+Since the ocean depth is far smaller than the earth's radius, $a+z$, can be replaced by 
+$a$ in (\autoref{eq:scale_factors}) (thin-shell approximation). The resulting horizontal scale 
+factors $e_1$, $e_2$  are independent of $k$ while the vertical scale factor is a single 
+function of $k$ as \textbf{k} is parallel to \textbf{z}. The scalar and vector operators that 
+appear in the primitive equations (\autoref{eq:PE_dyn} to \autoref{eq:PE_eos}) can 
+be written in the tensorial form, invariant in any orthogonal horizontal curvilinear coordinate 
+system transformation:
+\begin{subequations} \label{eq:PE_discrete_operators}
+\begin{equation} \label{eq:PE_grad}
+\nabla q=\frac{1}{e_1 }\frac{\partial q}{\partial i}\;{\rm {\bf 
+i}}+\frac{1}{e_2 }\frac{\partial q}{\partial j}\;{\rm {\bf j}}+\frac{1}{e_3 
+}\frac{\partial q}{\partial k}\;{\rm {\bf k}}    \\
+\end{equation}
+\begin{equation} \label{eq:PE_div}
+\nabla \cdot {\rm {\bf A}} 
+= \frac{1}{e_1 \; e_2} \left[ 
+  \frac{\partial \left(e_2 \; a_1\right)}{\partial i }
++\frac{\partial \left(e_1 \; a_2\right)}{\partial j }    	\right]
++ \frac{1}{e_3} \left[ \frac{\partial a_3}{\partial k }   \right]
+\end{equation}
+\begin{equation} \label{eq:PE_curl}
+   \begin{split}
+\nabla \times \vect{A} = 
+    \left[ {\frac{1}{e_2 }\frac{\partial a_3}{\partial j}
+            -\frac{1}{e_3 }\frac{\partial a_2 }{\partial k}} \right] \; \vect{i}
+&+\left[ {\frac{1}{e_3 }\frac{\partial a_1 }{\partial k}
+           -\frac{1}{e_1 }\frac{\partial a_3 }{\partial i}} \right] \; \vect{j} 		\\
+&+\frac{1}{e_1 e_2 } \left[ {\frac{\partial \left( {e_2 a_2 } \right)}{\partial i}
+                                       -\frac{\partial \left( {e_1 a_1 } \right)}{\partial j}} \right] \; \vect{k} 
+   \end{split}
+\end{equation}
+\begin{equation} \label{eq:PE_lap}
+\Delta q = \nabla \cdot \left(  \nabla q \right)
+\end{equation}
+\begin{equation} \label{eq:PE_lap_vector}
+\Delta {\rm {\bf A}} =
+  \nabla \left( \nabla \cdot {\rm {\bf A}} \right)
+- \nabla \times \left(  \nabla \times {\rm {\bf A}} \right)
+\end{equation}
+\end{subequations}
+where $q$ is a scalar quantity and ${\rm {\bf A}}=(a_1,a_2,a_3)$ a vector in the $(i,j,k)$ coordinate system.
+
+% -------------------------------------------------------------------------------------------------------------
+% Continuous Model Equations
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Continuous model equations}
+\label{subsec:PE_zco_Eq}
+
+In order to express the Primitive Equations in tensorial formalism, it is necessary to compute 
+the horizontal component of the non-linear and viscous terms of the equation using 
+\autoref{eq:PE_grad}) to \autoref{eq:PE_lap_vector}. 
+Let us set $\vect U=(u,v,w)={\vect{U}}_h +w\;\vect{k}$, the velocity in the $(i,j,k)$ coordinate 
+system and define the relative vorticity $\zeta$ and the divergence of the horizontal velocity 
+field $\chi$, by:
+\begin{equation} \label{eq:PE_curl_Uh}
+\zeta =\frac{1}{e_1 e_2 }\left[ {\frac{\partial \left( {e_2 \,v} 
+\right)}{\partial i}-\frac{\partial \left( {e_1 \,u} \right)}{\partial j}} 
+\right]
+\end{equation}
+\begin{equation} \label{eq:PE_div_Uh}
+\chi =\frac{1}{e_1 e_2 }\left[ {\frac{\partial \left( {e_2 \,u} 
+\right)}{\partial i}+\frac{\partial \left( {e_1 \,v} \right)}{\partial j}} 
+\right]
+\end{equation}
+
+Using the fact that the horizontal scale factors $e_1$ and $e_2$ are independent of $k$ 
+and that $e_3$  is a function of the single variable $k$, the nonlinear term of 
+\autoref{eq:PE_dyn} can be transformed as follows:
+\begin{flalign*}
+&\left[ {\left( {	\nabla \times {\rm {\bf U}}    } \right) \times {\rm {\bf U}}
++\frac{1}{2}	\nabla \left( {{\rm {\bf U}}^2} \right)}	 \right]_h 			&
+\end{flalign*}
+\begin{flalign*}
+&\qquad=\left( {{\begin{array}{*{20}c}
+ {\left[ 	{	 \frac{1}{e_3}	\frac{\partial u	}{\partial k}
+			-\frac{1}{e_1}	\frac{\partial w	}{\partial i} } \right] w - \zeta \; v } 	 	\\
+ 		{\zeta \; u - \left[ {	 \frac{1}{e_2} \frac{\partial w}{\partial j}
+							-\frac{1}{e_3} \frac{\partial v}{\partial k} } \right] \ w}	 \\
+		 \end{array} }} \right)			
++\frac{1}{2}	\left( {{\begin{array}{*{20}c}
+		 {	\frac{1}{e_1}	\frac{\partial \left( u^2+v^2+w^2 \right)}{\partial i}} 	\hfill	 \\
+		 {	\frac{1}{e_2}	\frac{\partial \left( u^2+v^2+w^2 \right)}{\partial j}} 	\hfill	 \\
+		 \end{array} }} \right)			&
+\end{flalign*}
+\begin{flalign*}
+& \qquad =\left( {{	\begin{array}{*{20}c}
+ {-\zeta \; v} \hfill \\
+ { \zeta \; u} \hfill \\
+			\end{array} }} \right)
++\frac{1}{2}\left( {{	\begin{array}{*{20}c}
+ {\frac{1}{e_1 }\frac{\partial \left( {u^2+v^2} \right)}{\partial i}} \hfill 	\\
+ {\frac{1}{e_2 }\frac{\partial \left( {u^2+v^2} \right)}{\partial j}} \hfill 	\\
+						\end{array} }} \right)			
++\frac{1}{e_3 }\left( {{		\begin{array}{*{20}c}
+ { w \; \frac{\partial u}{\partial k}} 	\\
+ { w \; \frac{\partial v}{\partial k}} 	\\
+							\end{array} }} \right)	
+-\left( {{	\begin{array}{*{20}c}
+ {\frac{w}{e_1}\frac{\partial w}{\partial i}
+ -\frac{1}{2e_1}\frac{\partial w^2}{\partial i}} \hfill \\
+ {\frac{w}{e_2}\frac{\partial w}{\partial j}
+  -\frac{1}{2e_2}\frac{\partial w^2}{\partial j}} \hfill \\
+			\end{array} }} \right) 			&
+\end{flalign*}
+
+The last term of the right hand side is obviously zero, and thus the nonlinear term of 
+\autoref{eq:PE_dyn} is written in the $(i,j,k)$ coordinate system:
+\begin{equation} \label{eq:PE_vector_form}
+\left[ {\left( {	\nabla \times {\rm {\bf U}}    } \right) \times {\rm {\bf U}}
++\frac{1}{2}	\nabla \left( {{\rm {\bf U}}^2} \right)}	 \right]_h 
+=\zeta 
+\;{\rm {\bf k}}\times {\rm {\bf U}}_h +\frac{1}{2}\nabla _h \left( {{\rm 
+{\bf U}}_h^2 } \right)+\frac{1}{e_3 }w\frac{\partial {\rm {\bf U}}_h 
+}{\partial k}   	
+\end{equation}
+
+This is the so-called \textit{vector invariant form} of the momentum advection term. 
+For some purposes, it can be advantageous to write this term in the so-called flux form, 
+$i.e.$ to write it as the divergence of fluxes. For example, the first component of 
+\autoref{eq:PE_vector_form} (the $i$-component) is transformed as follows:
+\begin{flalign*}
+&{	\begin{array}{*{20}l}
+\left[ {\left( {\nabla \times \vect{U}} \right)\times \vect{U}
+          +\frac{1}{2}\nabla \left( {\vect{U}}^2 \right)} \right]_i   % \\
+%\\
+     = - \zeta \;v 
+     + \frac{1}{2\;e_1 } \frac{\partial \left( {u^2+v^2} \right)}{\partial i}
+     + \frac{1}{e_3}w \ \frac{\partial u}{\partial k} 			\\
+\\
+\qquad =\frac{1}{e_1 \; e_2} \left( 	-v\frac{\partial \left( {e_2 \,v} \right)}{\partial i}
+							+v\frac{\partial \left( {e_1 \,u} \right)}{\partial j}	 \right)
++\frac{1}{e_1 e_2 }\left( 	+e_2 \; u\frac{\partial u}{\partial i}
+ 							+e_2 \; v\frac{\partial v}{\partial i}	  				 \right) 
++\frac{1}{e_3}       \left( 	w\;\frac{\partial u}{\partial k} 		\right)   \\
+\end{array} } 			&
+\end{flalign*}
+\begin{flalign*}
+&{	\begin{array}{*{20}l}
+\qquad =\frac{1}{e_1 \; e_2} 	\left\{ 
+ -\left(   	    v^2 	\frac{\partial e_2                                }{\partial i} 
+ 		+e_2 \,v		\frac{\partial v                                   }{\partial i}  	\right)
++\left( 				\frac{\partial \left( {e_1 \,u\,v} 	\right)}{\partial j}
+		-e_1 \,u		\frac{\partial v                                   }{\partial j} 	\right) 	\right. 
+\\  \left.	\qquad \qquad \quad
++\left( 				\frac{\partial \left( {e_2 u\,u}     \right)}{\partial i}
+		-u			\frac{\partial \left( {e_2 u}         \right)}{\partial i} 	\right)
++e_2 v		 		\frac{\partial v                                    }{\partial i}
+ 						\right\} 
++\frac{1}{e_3} \left(
+ 					\frac{\partial \left( {w\,u} \right)         }{\partial k}
+		 -u			\frac{\partial w 						   }{\partial k} 	\right) \\
+\end{array} } 		&
+\end{flalign*}
+\begin{flalign*}
+&{	\begin{array}{*{20}l}
+\qquad =\frac{1}{e_1 \; e_2} 	\left( 
+					\frac{\partial \left( {e_2 \,u\,u} \right)}{\partial i}
+		+			\frac{\partial \left( {e_1 \,u\,v} \right)}{\partial j}	\right)
++\frac{1}{e_3 }		\frac{\partial \left( {w\,u		 } \right)}{\partial k}
+\\  \qquad \qquad \quad
++\frac{1}{e_1 e_2 }		\left( 
+ 		-u	\left( 	\frac{\partial \left( {e_1 v	 } \right)}{\partial j}
+	 				-v\,\frac{\partial e_1 }{\partial j}				 \right)
+		-u			\frac{\partial \left( {e_2 u	 } \right)}{\partial i}
+						\right)
+ -\frac{1}{e_3 }	 	\frac{\partial w}{\partial k}	u
+ +\frac{1}{e_1 e_2 }\left( 	-v^2\frac{\partial e_2	 }{\partial i}		 \right)	
+\end{array} } 		&
+\end{flalign*}
+\begin{flalign*}
+&{	\begin{array}{*{20}l}
+\qquad = \nabla \cdot \left( {{\rm {\bf U}}\,u}	\right)
+-   \left( \nabla \cdot {\rm {\bf U}} \right) \ u
++\frac{1}{e_1 e_2 }\left( 
+		-v^2		\frac{\partial e_2 }{\partial i}
+		+uv	\,		\frac{\partial e_1 }{\partial j} 	\right) \\
+\end{array} } 		&
+\end{flalign*}
+as $\nabla \cdot {\rm {\bf U}}\;=0$ (incompressibility) it comes:
+\begin{flalign*}
+&{	\begin{array}{*{20}l}
+\qquad = \nabla \cdot \left( 	{{\rm {\bf U}}\,u}		\right)
++	\frac{1}{e_1 e_2 }   \left( v \; \frac{\partial e_2}{\partial i}
+						       -u \; \frac{\partial e_1}{\partial j} 	\right)  \left( -v \right)	
+\end{array} } 		&
+\end{flalign*}
+
+The flux form of the momentum advection term is therefore given by:
+\begin{multline} \label{eq:PE_flux_form}
+		\left[ 
+  \left( 	{\nabla \times {\rm {\bf U}}} 	\right) \times {\rm {\bf U}}
++\frac{1}{2}	\nabla \left( 	{{\rm {\bf U}}^2} 	\right)
+		\right]_h 
+\\
+= \nabla \cdot 	\left( {{\begin{array}{*{20}c}	{\rm {\bf U}} \, u 	\hfill \\
+												{\rm {\bf U}} \, v	\hfill \\
+						\end{array} }} 	
+				\right)
++\frac{1}{e_1 e_2 }		\left( 
+		 v\frac{\partial e_2}{\partial i}
+		-u\frac{\partial e_1}{\partial j} 
+						\right) {\rm {\bf k}} \times {\rm {\bf U}}_h
+\end{multline}
+
+The flux form has two terms, the first one is expressed as the divergence of momentum 
+fluxes (hence the flux form name given to this formulation) and the second one is due to 
+the curvilinear nature of the coordinate system used. The latter is called the \emph{metric} 
+term and can be viewed as a modification of the Coriolis parameter: 
+\begin{equation} \label{eq:PE_cor+metric}
+f \to f + \frac{1}{e_1\;e_2}  \left(  v \frac{\partial e_2}{\partial i}
+					         -u \frac{\partial e_1}{\partial j}  \right)
+\end{equation}
+
+Note that in the case of geographical coordinate, $i.e.$ when $(i,j) \to (\lambda ,\varphi )$ 
+and $(e_1 ,e_2) \to (a \,\cos \varphi ,a)$, we recover the commonly used modification of 
+the Coriolis parameter $f \to f+(u/a) \tan \varphi$.
+
+
+$\ $\newline    % force a new ligne
+
+To sum up, the curvilinear $z$-coordinate equations solved by the ocean model can be 
+written in the following tensorial formalism:
+
+\vspace{+10pt}
+$\bullet$ \textbf{Vector invariant form of the momentum equations} :
+
+\begin{subequations} \label{eq:PE_dyn_vect}
+\begin{equation} \label{eq:PE_dyn_vect_u} \begin{split}
+\frac{\partial u}{\partial t} 
+= +   \left( {\zeta +f} \right)\,v                                    
+   -   \frac{1}{2\,e_1}           \frac{\partial}{\partial i} \left(  u^2+v^2   \right) 
+   -   \frac{1}{e_3    }  w     \frac{\partial u}{\partial k}      &      \\
+   -   \frac{1}{e_1    }            \frac{\partial}{\partial i} \left( \frac{p_s+p_h }{\rho _o}    \right)    
+   &+   D_u^{\vect{U}}  +   F_u^{\vect{U}}      \\
+\\
+\frac{\partial v}{\partial t} =
+       -   \left( {\zeta +f} \right)\,u   
+       -   \frac{1}{2\,e_2 }        \frac{\partial }{\partial j}\left(  u^2+v^2  \right)   
+       -   \frac{1}{e_3     }   w  \frac{\partial v}{\partial k}     &      \\
+       -   \frac{1}{e_2     }        \frac{\partial }{\partial j}\left( \frac{p_s+p_h }{\rho _o}  \right)    
+    &+  D_v^{\vect{U}}  +   F_v^{\vect{U}}
+\end{split} \end{equation}
+\end{subequations}
+
+
+\vspace{+10pt}
+$\bullet$ \textbf{flux form of the momentum equations} :
+\begin{subequations} \label{eq:PE_dyn_flux}
+\begin{multline} \label{eq:PE_dyn_flux_u}
+\frac{\partial u}{\partial t}=
++   \left( { f + \frac{1}{e_1 \; e_2}
+					\left( 	 v \frac{\partial e_2}{\partial i}
+						-u \frac{\partial e_1}{\partial j} 	\right)} 	\right) \, v    \\
+- \frac{1}{e_1 \; e_2} 	\left( 
+					\frac{\partial \left( {e_2 \,u\,u} \right)}{\partial i}
+		+			\frac{\partial \left( {e_1 \,v\,u} \right)}{\partial j}	\right)
+                 - \frac{1}{e_3 }\frac{\partial \left( {         w\,u} \right)}{\partial k}    \\
+-   \frac{1}{e_1 }\frac{\partial}{\partial i}\left( \frac{p_s+p_h }{\rho _o}   \right)
++   D_u^{\vect{U}} +   F_u^{\vect{U}}
+\end{multline}
+\begin{multline} \label{eq:PE_dyn_flux_v}
+\frac{\partial v}{\partial t}=
+-   \left( { f + \frac{1}{e_1 \; e_2}
+					\left( 	 v \frac{\partial e_2}{\partial i}
+						-u \frac{\partial e_1}{\partial j} 	\right)} 	\right) \, u   \\
+ \frac{1}{e_1 \; e_2} 	\left( 
+					\frac{\partial \left( {e_2 \,u\,v} \right)}{\partial i}
+		+			\frac{\partial \left( {e_1 \,v\,v} \right)}{\partial j}	\right)
+                 - \frac{1}{e_3 } \frac{\partial \left( {        w\,v} \right)}{\partial k}    \\
+-   \frac{1}{e_2 }\frac{\partial }{\partial j}\left( \frac{p_s+p_h }{\rho _o}    \right)
++  D_v^{\vect{U}} +  F_v^{\vect{U}} 
+\end{multline}
+\end{subequations}
+where $\zeta$, the relative vorticity, is given by \autoref{eq:PE_curl_Uh} and $p_s $, 
+the surface pressure, is given by:
+\begin{equation} \label{eq:PE_spg}
+p_s =  \rho \,g \,\eta 
+\end{equation}
+with $\eta$ is solution of \autoref{eq:PE_ssh}
+
+The vertical velocity and the hydrostatic pressure are diagnosed from the following equations:
+\begin{equation} \label{eq:w_diag}
+\frac{\partial w}{\partial k}=-\chi \;e_3 
+\end{equation}
+\begin{equation} \label{eq:hp_diag}
+\frac{\partial p_h }{\partial k}=-\rho \;g\;e_3 
+\end{equation}
+where the divergence of the horizontal velocity, $\chi$ is given by \autoref{eq:PE_div_Uh}.
+
+\vspace{+10pt}
+$\bullet$ \textit{tracer equations} :
+\begin{equation} \label{eq:S}
+\frac{\partial T}{\partial t} = 
+-\frac{1}{e_1 e_2 }\left[ {	   \frac{\partial \left( {e_2 T\,u} \right)}{\partial i}
+						+\frac{\partial \left( {e_1 T\,v} \right)}{\partial j}} \right]
+-\frac{1}{e_3 }\frac{\partial \left( {T\,w} \right)}{\partial k} + D^T + F^T
+\end{equation}
+\begin{equation} \label{eq:T}
+\frac{\partial S}{\partial t} = 
+-\frac{1}{e_1 e_2 }\left[ 	  {\frac{\partial \left( {e_2 S\,u} \right)}{\partial i}
+						+\frac{\partial \left( {e_1 S\,v} \right)}{\partial j}} \right]
+-\frac{1}{e_3 }\frac{\partial \left( {S\,w} \right)}{\partial k} + D^S + F^S
+\end{equation}
+\begin{equation} \label{eq:rho}
+\rho =\rho \left( {T,S,z(k)} \right)
+\end{equation}
+
+The expression of \textbf{D}$^{U}$, $D^{S}$ and $D^{T}$ depends on the subgrid scale 
+parameterisation used. It will be defined in \autoref{eq:PE_zdf}. The nature and formulation of 
+${\rm {\bf F}}^{\rm {\bf U}}$, $F^T$ and $F^S$, the surface forcing terms, are discussed 
+in \autoref{chap:SBC}.
+
+
+\newpage 
+$\ $\newline    % force a new ligne
+% ================================================================
+% Curvilinear generalised vertical coordinate System
+% ================================================================
+\section{Curvilinear generalised vertical coordinate system}
+\label{sec:PE_gco}
+
+The ocean domain presents a huge diversity of situation in the vertical. First the ocean surface is a time dependent surface (moving surface). Second the ocean floor depends on the geographical position, varying from more than 6,000 meters in abyssal trenches to zero at the coast. Last but not least, the ocean stratification exerts a strong barrier to vertical motions and mixing. 
+Therefore, in order to represent the ocean with respect to the first point a space and time dependent vertical coordinate that follows the variation of the sea surface height $e.g.$ an $z$*-coordinate; for the second point, a space variation to fit the change of bottom topography $e.g.$ a terrain-following or $\sigma$-coordinate; and for the third point, one will be tempted to use a space and time dependent coordinate that follows the isopycnal surfaces, $e.g.$ an isopycnic coordinate.
+
+In order to satisfy two or more constrains one can even be tempted to mixed these coordinate systems, as in HYCOM (mixture of $z$-coordinate at the surface, isopycnic coordinate in the ocean interior and $\sigma$ at the ocean bottom) \citep{Chassignet_al_JPO03}  or OPA (mixture of $z$-coordinate in vicinity the surface and steep topography areas and $\sigma$-coordinate elsewhere) \citep{Madec_al_JPO96} among others.
+
+In fact one is totally free to choose any space and time vertical coordinate by introducing an arbitrary vertical coordinate :
+\begin{equation} \label{eq:PE_s}
+s=s(i,j,k,t)
+\end{equation}
+with the restriction that the above equation gives a single-valued monotonic relationship between $s$ and $k$, when $i$, $j$ and $t$ are held fixed. \autoref{eq:PE_s} is a transformation from the $(i,j,k,t)$ coordinate system with independent variables into the $(i,j,s,t)$ generalised coordinate system with $s$ depending on the other three variables through \autoref{eq:PE_s}.
+This so-called \textit{generalised vertical coordinate} \citep{Kasahara_MWR74} is in fact an Arbitrary Lagrangian--Eulerian (ALE) coordinate. Indeed, choosing an expression for $s$ is an arbitrary choice that determines which part of the vertical velocity (defined from a fixed referential) will cross the levels (Eulerian part) and which part will be used to move them (Lagrangian part).
+The coordinate is also sometime referenced as an adaptive coordinate \citep{Hofmeister_al_OM09}, since the coordinate system is adapted in the course of the simulation. Its most often used implementation is via an ALE algorithm, in which a pure lagrangian step is followed by regridding and remapping steps, the later step implicitly embedding the vertical advection \citep{Hirt_al_JCP74, Chassignet_al_JPO03, White_al_JCP09}. Here we follow the \citep{Kasahara_MWR74} strategy : a regridding step (an update of the vertical coordinate) followed by an eulerian step with an explicit computation of vertical advection relative to the moving s-surfaces.
+
+%\gmcomment{
+
+%A key point here is that the $s$-coordinate depends on $(i,j)$ ==> horizontal pressure gradient...
+
+the generalized vertical coordinates used in ocean modelling are not orthogonal, 
+which contrasts with many other applications in mathematical physics. 
+Hence, it is useful to keep in mind the following properties that may seem 
+odd on initial encounter.
+
+The horizontal velocity in ocean models measures motions in the horizontal plane, 
+perpendicular to the local gravitational field. That is, horizontal velocity is mathematically 
+the same regardless the vertical coordinate, be it geopotential, isopycnal, pressure, 
+or terrain following. The key motivation for maintaining the same horizontal velocity 
+component is that the hydrostatic and geostrophic balances are dominant in the large-scale ocean. 
+Use of an alternative quasi-horizontal velocity, for example one oriented parallel 
+to the generalized surface, would lead to unacceptable numerical errors. 
+Correspondingly, the vertical direction is anti-parallel to the gravitational force in all 
+of the coordinate systems. We do not choose the alternative of a quasi-vertical 
+direction oriented normal to the surface of a constant generalized vertical coordinate. 
+
+It is the method used to measure transport across the generalized vertical coordinate 
+surfaces which differs between the vertical coordinate choices. That is, computation 
+of the dia-surface velocity component represents the fundamental distinction between 
+the various coordinates. In some models, such as geopotential, pressure, and 
+terrain following, this transport is typically diagnosed from volume or mass conservation. 
+In other models, such as isopycnal layered models, this transport is prescribed based 
+on assumptions about the physical processes producing a flux across the layer interfaces. 
+
+
+In this section we first establish the PE in the generalised vertical $s$-coordinate, 
+then we discuss the particular cases available in \NEMO, namely $z$, $z$*, $s$, and $\tilde z$.  
+%}
+
+% -------------------------------------------------------------------------------------------------------------
+% The s-coordinate Formulation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{\textit{S-}coordinate formulation}
+
+Starting from the set of equations established in \autoref{sec:PE_zco} for the special case $k=z$ 
+and thus $e_3=1$, we introduce an arbitrary vertical coordinate $s=s(i,j,k,t)$, which includes 
+$z$-, \textit{z*}- and $\sigma-$coordinates as special cases ($s=z$, $s=\textit{z*}$, and 
+$s=\sigma=z/H$ or $=z/\left(H+\eta \right)$, resp.). A formal derivation of the transformed 
+equations is given in \autoref{apdx:A}. Let us define the vertical scale factor by 
+$e_3=\partial_s z$  ($e_3$ is now a function of $(i,j,k,t)$ ), and the slopes in the 
+(\textbf{i},\textbf{j}) directions between $s-$ and $z-$surfaces by :
+\begin{equation} \label{eq:PE_sco_slope}
+\sigma _1 =\frac{1}{e_1 }\;\left. {\frac{\partial z}{\partial i}} \right|_s 
+\quad \text{, and } \quad 
+\sigma _2 =\frac{1}{e_2 }\;\left. {\frac{\partial z}{\partial j}} \right|_s
+\end{equation}
+We also introduce  $\omega $, a dia-surface velocity component, defined as the velocity 
+relative to the moving $s$-surfaces and normal to them:
+\begin{equation} \label{eq:PE_sco_w}
+\omega  = w - e_3 \, \frac{\partial s}{\partial t} - \sigma _1 \,u - \sigma _2 \,v    \\
+\end{equation}
+
+The equations solved by the ocean model \autoref{eq:PE} in $s-$coordinate can be written as follows (see \autoref{sec:A_momentum}):
+
+ \vspace{0.5cm}
+$\bullet$ Vector invariant form of the momentum equation :
+\begin{multline} \label{eq:PE_sco_u_vector}
+\frac{\partial  u   }{\partial t}=
+	+   \left( {\zeta +f} \right)\,v                                    
+	-   \frac{1}{2\,e_1} \frac{\partial}{\partial i} \left(  u^2+v^2   \right) 
+	-   \frac{1}{e_3} \omega \frac{\partial u}{\partial k}       \\
+	-   \frac{1}{e_1} \frac{\partial}{\partial i} \left( \frac{p_s + p_h}{\rho _o}    \right)    
+	+  g\frac{\rho }{\rho _o}\sigma _1 
+	+   D_u^{\vect{U}}  +   F_u^{\vect{U}} \quad
+\end{multline}
+\begin{multline} \label{eq:PE_sco_v_vector}
+\frac{\partial v }{\partial t}=
+	-   \left( {\zeta +f} \right)\,u   
+	-   \frac{1}{2\,e_2 }\frac{\partial }{\partial j}\left(  u^2+v^2  \right)     	
+	-   \frac{1}{e_3 } \omega \frac{\partial v}{\partial k}         \\
+	-   \frac{1}{e_2 }\frac{\partial }{\partial j}\left( \frac{p_s+p_h }{\rho _o}  \right) 
+	 +  g\frac{\rho }{\rho _o }\sigma _2   
+	+  D_v^{\vect{U}}  +   F_v^{\vect{U}} \quad
+\end{multline}
+
+ \vspace{0.5cm}
+$\bullet$ Flux form of the momentum equation :
+\begin{multline} \label{eq:PE_sco_u_flux}
+\frac{1}{e_3} \frac{\partial \left(  e_3\,u  \right) }{\partial t}=
+   +   \left( { f + \frac{1}{e_1 \; e_2 }
+					\left( 	 v \frac{\partial e_2}{\partial i}
+						-u \frac{\partial e_1}{\partial j} 	\right)} 	\right) \, v    \\
+   - \frac{1}{e_1 \; e_2 \; e_3 } 	\left( 
+					\frac{\partial \left( {e_2 \, e_3 \, u\,u} \right)}{\partial i}
+		+			\frac{\partial \left( {e_1 \, e_3 \, v\,u} \right)}{\partial j}	\right)
+   - \frac{1}{e_3 }\frac{\partial \left( { \omega\,u} \right)}{\partial k}    \\
+	- \frac{1}{e_1} \frac{\partial}{\partial i} \left( \frac{p_s + p_h}{\rho _o}    \right)    
+	+  g\frac{\rho }{\rho _o}\sigma _1 
+	+   D_u^{\vect{U}}  +   F_u^{\vect{U}} \quad
+\end{multline}
+\begin{multline} \label{eq:PE_sco_v_flux}
+\frac{1}{e_3} \frac{\partial \left(  e_3\,v  \right) }{\partial t}=
+   -   \left( { f + \frac{1}{e_1 \; e_2}
+					\left( 	 v \frac{\partial e_2}{\partial i}
+						-u \frac{\partial e_1}{\partial j} 	\right)} 	\right) \, u   \\
+   - \frac{1}{e_1 \; e_2 \; e_3 } 	\left( 
+					\frac{\partial \left( {e_2 \; e_3  \,u\,v} \right)}{\partial i}
+		+			\frac{\partial \left( {e_1 \; e_3  \,v\,v} \right)}{\partial j}	\right)
+                 - \frac{1}{e_3 } \frac{\partial \left( { \omega\,v} \right)}{\partial k}    \\
+	-   \frac{1}{e_2 }\frac{\partial }{\partial j}\left( \frac{p_s+p_h }{\rho _o}  \right) 
+	 +  g\frac{\rho }{\rho _o }\sigma _2   
+	+  D_v^{\vect{U}}  +   F_v^{\vect{U}} \quad
+\end{multline}
+
+where the relative vorticity, \textit{$\zeta $}, the surface pressure gradient, and the hydrostatic 
+pressure have the same expressions as in $z$-coordinates although they do not represent 
+exactly the same quantities. $\omega$ is provided by the continuity equation 
+(see \autoref{apdx:A}):
+\begin{equation} \label{eq:PE_sco_continuity}
+\frac{\partial e_3}{\partial t} + e_3 \; \chi + \frac{\partial \omega }{\partial s} = 0   
+\qquad \text{with }\;\;  
+\chi =\frac{1}{e_1 e_2 e_3 }\left[ {\frac{\partial \left( {e_2 e_3 \,u} 
+\right)}{\partial i}+\frac{\partial \left( {e_1 e_3 \,v} \right)}{\partial 
+j}} \right]
+\end{equation}
+
+ \vspace{0.5cm}
+$\bullet$ tracer equations:
+\begin{multline} \label{eq:PE_sco_t}
+\frac{1}{e_3} \frac{\partial \left(  e_3\,T  \right) }{\partial t}=
+-\frac{1}{e_1 e_2 e_3 }\left[ {\frac{\partial \left( {e_2 e_3\,u\,T} \right)}{\partial i}
+                                           +\frac{\partial \left( {e_1 e_3\,v\,T} \right)}{\partial j}} \right]   \\
+-\frac{1}{e_3 }\frac{\partial \left( {T\,\omega } \right)}{\partial k}   + D^T + F^S   \qquad
+\end{multline}
+
+\begin{multline} \label{eq:PE_sco_s}
+\frac{1}{e_3} \frac{\partial \left(  e_3\,S  \right) }{\partial t}=
+-\frac{1}{e_1 e_2 e_3 }\left[ {\frac{\partial \left( {e_2 e_3\,u\,S} \right)}{\partial i}
+                                           +\frac{\partial \left( {e_1 e_3\,v\,S} \right)}{\partial j}} \right]    \\
+-\frac{1}{e_3 }\frac{\partial \left( {S\,\omega } \right)}{\partial k}     + D^S + F^S   \qquad
+\end{multline}
+
+The equation of state has the same expression as in $z$-coordinate, and similar expressions 
+are used for mixing and forcing terms.
+
+\gmcomment{
+\colorbox{yellow}{ to be updated $= = >$}
+Add a few works on z and zps and s and underlies the differences between all of them
+\colorbox{yellow}{ $< = =$ end update}  }
+
+
+
+% -------------------------------------------------------------------------------------------------------------
+% Curvilinear z*-coordinate System
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Curvilinear \textit{z*}--coordinate system}
+\label{subsec:PE_zco_star}
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!b] 	 \begin{center}
+\includegraphics[width=1.0\textwidth]{Fig_z_zstar}
+\caption{	\protect\label{fig:z_zstar} 
+(a) $z$-coordinate in linear free-surface case ; 
+(b) $z-$coordinate in non-linear free surface case ; 
+(c) re-scaled height coordinate (become popular as the \textit{z*-}coordinate 
+\citep{Adcroft_Campin_OM04} ).}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+
+In that case, the free surface equation is nonlinear, and the variations of volume are fully 
+taken into account. These coordinates systems is presented in a report \citep{Levier2007} 
+available on the \NEMO web site. 
+
+%\gmcomment{
+The \textit{z*} coordinate approach is an unapproximated, non-linear free surface implementation 
+which allows one to deal with large amplitude free-surface
+variations relative to the vertical resolution \citep{Adcroft_Campin_OM04}. In
+the  \textit{z*} formulation, the variation of the column thickness due to sea-surface
+undulations is not concentrated in the surface level, as in the $z$-coordinate formulation,
+but is equally distributed over the full water column. Thus vertical
+levels naturally follow sea-surface variations, with a linear attenuation with
+depth, as illustrated by figure fig.1c . Note that with a flat bottom, such as in
+fig.1c, the bottom-following  $z$ coordinate and  \textit{z*} are equivalent.
+The definition and modified oceanic equations for the rescaled vertical coordinate
+ \textit{z*}, including the treatment of fresh-water flux at the surface, are
+detailed in Adcroft and Campin (2004). The major points are summarized
+here. The position ( \textit{z*}) and vertical discretization (\textit{z*}) are expressed as:
+\begin{equation} \label{eq:z-star}
+H +  \textit{z*} = (H + z) / r \quad \text{and} \ \delta \textit{z*} = \delta z / r \quad \text{with} \ r = \frac{H+\eta} {H}
+\end{equation} 
+Since the vertical displacement of the free surface is incorporated in the vertical
+coordinate  \textit{z*}, the upper and lower boundaries are at fixed  \textit{z*} position,  
+$\textit{z*} = 0$ and  $\textit{z*} = -H$ respectively. Also the divergence of the flow field 
+is no longer zero as shown by the continuity equation:
+\begin{equation*} 
+\frac{\partial r}{\partial t} = \nabla_{\textit{z*}} \cdot \left( r \; \rm{\bf U}_h \right)
+		\left( r \; w\textit{*} \right) = 0 
+\end{equation*} 
+%}
+
+
+% from MOM4p1 documentation
+
+To overcome problems with vanishing surface and/or bottom cells, we consider the 
+zstar coordinate 
+\begin{equation} \label{eq:PE_}
+	z^\star = H \left( \frac{z-\eta}{H+\eta} \right)
+\end{equation}
+
+This coordinate is closely related to the "eta" coordinate used in many atmospheric 
+models (see Black (1994) for a review of eta coordinate atmospheric models). It 
+was originally used in ocean models by Stacey et al. (1995) for studies of tides 
+next to shelves, and it has been recently promoted by Adcroft and Campin (2004) 
+for global climate modelling.
+
+The surfaces of constant $z^\star$ are quasi-horizontal. Indeed, the $z^\star$ coordinate reduces to $z$ when $\eta$ is zero. In general, when noting the large differences between 
+undulations of the bottom topography versus undulations in the surface height, it 
+is clear that surfaces constant $z^\star$ are very similar to the depth surfaces. These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to terrain following sigma models discussed in \autoref{subsec:PE_sco}. 
+Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in an 
+unforced ocean starting from rest, regardless the bottom topography. This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in 
+the presence of nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state, depending on the sophistication of the pressure 
+gradient solver. The quasi-horizontal nature of the coordinate surfaces also facilitates the implementation of neutral physics parameterizations in $z^\star$ models using 
+the same techniques as in $z$-models (see Chapters 13-16 of \cite{Griffies_Bk04}) for a 
+discussion of neutral physics in $z$-models, as well as \autoref{sec:LDF_slp} 
+in this document for treatment in \NEMO). 
+
+The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$. Hence, all 
+cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. This 
+is a minor constraint relative to that encountered on the surface height when using 
+$s = z$ or $s = z - \eta$. 
+
+Because $z^\star$ has a time independent range, all grid cells have static increments 
+ds, and the sum of the ver tical increments yields the time independent ocean 
+depth %·k ds = H. 
+The $z^\star$ coordinate is therefore invisible to undulations of the 
+free surface, since it moves along with the free surface. This proper ty means that 
+no spurious ver tical transpor t is induced across surfaces of constant $z^\star$ by the 
+motion of external gravity waves. Such spurious transpor t can be a problem in 
+z-models, especially those with tidal forcing. Quite generally, the time independent 
+range for the $z^\star$ coordinate is a very convenient proper ty that allows for a nearly 
+arbitrary ver tical resolution even in the presence of large amplitude fluctuations of 
+the surface height, again so long as $\eta > -H$. 
+
+%end MOM doc %%%
+
+
+
+\newpage 
+% -------------------------------------------------------------------------------------------------------------
+% Terrain following  coordinate System
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Curvilinear terrain-following \textit{s}--coordinate}
+\label{subsec:PE_sco}
+
+% -------------------------------------------------------------------------------------------------------------
+% Introduction
+% -------------------------------------------------------------------------------------------------------------
+\subsubsection{Introduction}
+
+Several important aspects of the ocean circulation are influenced by bottom topography. 
+Of course, the most important is that bottom topography determines deep ocean sub-basins, 
+barriers, sills and channels that strongly constrain the path of water masses, but more subtle 
+effects exist. For example, the topographic $\beta$-effect is usually larger than the planetary 
+one along continental slopes. Topographic Rossby waves can be excited and can interact 
+with the mean current. In the $z-$coordinate system presented in the previous section 
+(\autoref{sec:PE_zco}), $z-$surfaces are geopotential surfaces. The bottom topography is 
+discretised by steps. This often leads to a misrepresentation of a gradually sloping bottom 
+and to large localized depth gradients associated with large localized vertical velocities. 
+The response to such a velocity field often leads to numerical dispersion effects. 
+One solution to strongly reduce this error is to use a partial step representation of bottom 
+topography instead of a full step one \cite{Pacanowski_Gnanadesikan_MWR98}. 
+Another solution is to introduce a terrain-following coordinate system (hereafter $s-$coordinate) 
+
+The $s$-coordinate avoids the discretisation error in the depth field since the layers of 
+computation are gradually adjusted with depth to the ocean bottom. Relatively small 
+topographic features as well as  gentle, large-scale slopes of the sea floor in the deep 
+ocean, which would be ignored in typical $z$-model applications with the largest grid 
+spacing at greatest depths, can easily be represented (with relatively low vertical resolution). 
+A terrain-following model (hereafter $s-$model) also facilitates the modelling of the 
+boundary layer flows over a large depth range, which in the framework of the $z$-model 
+would require high vertical resolution over the whole depth range. Moreover, with a 
+$s$-coordinate it is possible, at least in principle, to have the bottom and the sea surface 
+as the only boundaries of the domain (nomore lateral boundary condition to specify). 
+Nevertheless, a $s$-coordinate also has its drawbacks. Perfectly adapted to a 
+homogeneous ocean, it has strong limitations as soon as stratification is introduced. 
+The main two problems come from the truncation error in the horizontal pressure 
+gradient and a possibly increased diapycnal diffusion. The horizontal pressure force 
+in $s$-coordinate consists of two terms (see \autoref{apdx:A}),
+
+\begin{equation} \label{eq:PE_p_sco}
+\left. {\nabla p} \right|_z =\left. {\nabla p} \right|_s -\frac{\partial 
+p}{\partial s}\left. {\nabla z} \right|_s 
+\end{equation}
+
+The second term in \autoref{eq:PE_p_sco} depends on the tilt of the coordinate surface 
+and introduces a truncation error that is not present in a $z$-model. In the special case 
+of a $\sigma-$coordinate (i.e. a depth-normalised coordinate system $\sigma = z/H$), 
+\citet{Haney1991} and \citet{Beckmann1993} have given estimates of the magnitude 
+of this truncation error. It depends on topographic slope, stratification, horizontal and 
+vertical resolution, the equation of state, and the finite difference scheme. This error 
+limits the possible topographic slopes that a model can handle at a given horizontal 
+and vertical resolution. This is a severe restriction for large-scale applications using 
+realistic bottom topography. The large-scale slopes require high horizontal resolution, 
+and the computational cost becomes prohibitive. This problem can be at least partially 
+overcome by mixing $s$-coordinate and step-like representation of bottom topography \citep{Gerdes1993a,Gerdes1993b,Madec_al_JPO96}. However, the definition of the model 
+domain vertical coordinate becomes then a non-trivial thing for a realistic bottom 
+topography: a envelope topography is defined in $s$-coordinate on which a full or 
+partial step bottom topography is then applied in order to adjust the model depth to 
+the observed one (see \autoref{sec:DOM_zgr}.
+
+For numerical reasons a minimum of diffusion is required along the coordinate surfaces 
+of any finite difference model. It causes spurious diapycnal mixing when coordinate 
+surfaces do not coincide with isoneutral surfaces. This is the case for a $z$-model as 
+well as for a $s$-model. However, density varies more strongly on $s-$surfaces than 
+on horizontal surfaces in regions of large topographic slopes, implying larger diapycnal 
+diffusion in a $s$-model than in a $z$-model. Whereas such a diapycnal diffusion in a 
+$z$-model tends to weaken horizontal density (pressure) gradients and thus the horizontal 
+circulation, it usually reinforces these gradients in a $s$-model, creating spurious circulation. 
+For example, imagine an isolated bump of topography in an ocean at rest with a horizontally 
+uniform stratification. Spurious diffusion along $s$-surfaces will induce a bump of isoneutral 
+surfaces over the topography, and thus will generate there a baroclinic eddy. In contrast, 
+the ocean will stay at rest in a $z$-model. As for the truncation error, the problem can be reduced by introducing the terrain-following coordinate below the strongly stratified portion of the water column 
+($i.e.$ the main thermocline) \citep{Madec_al_JPO96}. An alternate solution consists of rotating 
+the lateral diffusive tensor to geopotential or to isoneutral surfaces (see \autoref{subsec:PE_ldf}. 
+Unfortunately, the slope of isoneutral surfaces relative to the $s$-surfaces can very large, 
+strongly exceeding the stability limit of such a operator when it is discretized (see \autoref{chap:LDF}). 
+
+The $s-$coordinates introduced here \citep{Lott_al_OM90,Madec_al_JPO96} differ mainly in two 
+aspects from similar models:  it allows  a representation of bottom topography with mixed 
+full or partial step-like/terrain following topography ; It also offers a completely general 
+transformation, $s=s(i,j,z)$ for the vertical coordinate.
+
+
+\newpage 
+% -------------------------------------------------------------------------------------------------------------
+% Curvilinear z-tilde coordinate System
+% -------------------------------------------------------------------------------------------------------------
+\subsection{\texorpdfstring{Curvilinear $\tilde{z}$--coordinate}{}}
+\label{subsec:PE_zco_tilde}
+
+The $\tilde{z}$-coordinate has been developed by \citet{Leclair_Madec_OM11}.
+It is available in \NEMO since the version 3.4. Nevertheless, it is currently not robust enough 
+to be used in all possible configurations. Its use is therefore not recommended.
+
+
+\newpage 
+% ================================================================
+% Subgrid Scale Physics
+% ================================================================
+\section{Subgrid scale physics}
+\label{sec:PE_zdf_ldf}
+
+The primitive equations describe the behaviour of a geophysical fluid at 
+space and time scales larger than a few kilometres in the horizontal, a few 
+meters in the vertical and a few minutes. They are usually solved at larger 
+scales: the specified grid spacing and time step of the numerical model. The 
+effects of smaller scale motions (coming from the advective terms in the 
+Navier-Stokes equations) must be represented entirely in terms of 
+large-scale patterns to close the equations. These effects appear in the 
+equations as the divergence of turbulent fluxes ($i.e.$ fluxes associated with 
+the mean correlation of small scale perturbations). Assuming a turbulent 
+closure hypothesis is equivalent to choose a formulation for these fluxes. 
+It is usually called the subgrid scale physics. It must be emphasized that 
+this is the weakest part of the primitive equations, but also one of the 
+most important for long-term simulations as small scale processes \textit{in fine} 
+balance the surface input of kinetic energy and heat.
+
+The control exerted by gravity on the flow induces a strong anisotropy 
+between the lateral and vertical motions. Therefore subgrid-scale physics  
+\textbf{D}$^{\vect{U}}$, $D^{S}$ and $D^{T}$  in \autoref{eq:PE_dyn}, 
+\autoref{eq:PE_tra_T} and \autoref{eq:PE_tra_S} are divided into a lateral part  
+\textbf{D}$^{l \vect{U}}$, $D^{lS}$ and $D^{lT}$ and a vertical part  
+\textbf{D}$^{vU}$, $D^{vS}$ and $D^{vT}$. The formulation of these terms 
+and their underlying physics are briefly discussed in the next two subsections.
+
+% -------------------------------------------------------------------------------------------------------------
+% Vertical Subgrid Scale Physics
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Vertical subgrid scale physics}
+\label{subsec:PE_zdf}
+
+The model resolution is always larger than the scale at which the major 
+sources of vertical turbulence occur (shear instability, internal wave 
+breaking...). Turbulent motions are thus never explicitly solved, even 
+partially, but always parameterized. The vertical turbulent fluxes are 
+assumed to depend linearly on the gradients of large-scale quantities (for 
+example, the turbulent heat flux is given by $\overline{T'w'}=-A^{vT} \partial_z \overline T$, 
+where $A^{vT}$ is an eddy coefficient). This formulation is 
+analogous to that of molecular diffusion and dissipation. This is quite 
+clearly a necessary compromise: considering only the molecular viscosity 
+acting on large scale severely underestimates the role of turbulent 
+diffusion and dissipation, while an accurate consideration of the details of 
+turbulent motions is simply impractical. The resulting vertical momentum and 
+tracer diffusive operators are of second order:
+\begin{equation} \label{eq:PE_zdf}
+   \begin{split}
+{\vect{D}}^{v \vect{U}} &=\frac{\partial }{\partial z}\left( {A^{vm}\frac{\partial {\vect{U}}_h }{\partial z}} \right) \ , \\         
+D^{vT}                         &= \frac{\partial }{\partial z}\left( {A^{vT}\frac{\partial T}{\partial z}} \right) \ ,
+\quad
+D^{vS}=\frac{\partial }{\partial z}\left( {A^{vT}\frac{\partial S}{\partial z}} \right)
+   \end{split}
+\end{equation}
+where $A^{vm}$ and $A^{vT}$ are the vertical eddy viscosity and diffusivity coefficients, 
+respectively. At the sea surface and at the bottom, turbulent fluxes of momentum, heat 
+and salt must be specified (see \autoref{chap:SBC} and \autoref{chap:ZDF} and \autoref{sec:TRA_bbl}). 
+All the vertical physics is embedded in the specification of the eddy coefficients. 
+They can be assumed to be either constant, or function of the local fluid properties 
+($e.g.$ Richardson number, Brunt-Vais\"{a}l\"{a} frequency...), or computed from a 
+turbulent closure model. The choices available in \NEMO are discussed in \autoref{chap:ZDF}).
+
+% -------------------------------------------------------------------------------------------------------------
+% Lateral Diffusive and Viscous Operators Formulation
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Formulation of the lateral diffusive and viscous operators}
+\label{subsec:PE_ldf}
+
+Lateral turbulence can be roughly divided into a mesoscale turbulence 
+associated with eddies (which can be solved explicitly if the resolution is 
+sufficient since their underlying physics are included in the primitive 
+equations), and a sub mesoscale turbulence which is never explicitly solved 
+even partially, but always parameterized. The formulation of lateral eddy 
+fluxes depends on whether the mesoscale is below or above the grid-spacing 
+($i.e.$ the model is eddy-resolving or not).
+
+In non-eddy-resolving configurations, the closure is similar to that used 
+for the vertical physics. The lateral turbulent fluxes are assumed to depend 
+linearly on the lateral gradients of large-scale quantities. The resulting 
+lateral diffusive and dissipative operators are of second order. 
+Observations show that lateral mixing induced by mesoscale turbulence tends 
+to be along isopycnal surfaces (or more precisely neutral surfaces \cite{McDougall1987}) 
+rather than across them. 
+As the slope of neutral surfaces is small in the ocean, a common 
+approximation is to assume that the `lateral' direction is the horizontal, 
+$i.e.$ the lateral mixing is performed along geopotential surfaces. This leads 
+to a geopotential second order operator for lateral subgrid scale physics. 
+This assumption can be relaxed: the eddy-induced turbulent fluxes can be 
+better approached by assuming that they depend linearly on the gradients of 
+large-scale quantities computed along neutral surfaces. In such a case, 
+the diffusive operator is an isoneutral second order operator and it has 
+components in the three space directions. However, both horizontal and 
+isoneutral operators have no effect on mean ($i.e.$ large scale) potential 
+energy whereas potential energy is a main source of turbulence (through 
+baroclinic instabilities). \citet{Gent1990} have proposed a 
+parameterisation of mesoscale eddy-induced turbulence which associates an 
+eddy-induced velocity to the isoneutral diffusion. Its mean effect is to 
+reduce the mean potential energy of the ocean. This leads to a formulation 
+of lateral subgrid-scale physics made up of an isoneutral second order 
+operator and an eddy induced advective part. In all these lateral diffusive 
+formulations, the specification of the lateral eddy coefficients remains the 
+problematic point as there is no really satisfactory formulation of these 
+coefficients as a function of large-scale features.
+
+In eddy-resolving configurations, a second order operator can be used, but 
+usually the more scale selective biharmonic operator is preferred as the 
+grid-spacing is usually not small enough compared to the scale of the 
+eddies. The role devoted to the subgrid-scale physics is to dissipate the 
+energy that cascades toward the grid scale and thus to ensure the stability of 
+the model while not interfering with the resolved mesoscale activity. Another approach 
+is becoming more and more popular: instead of specifying explicitly a sub-grid scale 
+term in the momentum and tracer time evolution equations, one uses a advective 
+scheme which is diffusive enough to maintain the model stability. It must be emphasised
+that then, all the sub-grid scale physics is included in the formulation of the
+advection scheme. 
+
+All these parameterisations of subgrid scale physics have advantages and 
+drawbacks. There are not all available in \NEMO. For active tracers (temperature and 
+salinity) the main ones are: Laplacian and bilaplacian operators acting along 
+geopotential or iso-neutral surfaces, \citet{Gent1990} parameterisation, 
+and various slightly diffusive advection schemes. 
+For momentum, the main ones are: Laplacian and bilaplacian operators acting along 
+geopotential surfaces, and UBS advection schemes when flux form is chosen for the momentum advection.
+
+\subsubsection{Lateral laplacian tracer diffusive operator}
+
+The lateral Laplacian tracer diffusive operator is defined by (see \autoref{apdx:B}):
+\begin{equation} \label{eq:PE_iso_tensor}
+D^{lT}=\nabla {\rm {\bf .}}\left( {A^{lT}\;\Re \;\nabla T} \right) \qquad 
+\mbox{with}\quad \;\;\Re =\left( {{\begin{array}{*{20}c}
+ 1 \hfill & 0 \hfill & {-r_1 } \hfill \\
+ 0 \hfill & 1 \hfill & {-r_2 } \hfill \\
+ {-r_1 } \hfill & {-r_2 } \hfill & {r_1 ^2+r_2 ^2} \hfill \\
+\end{array} }} \right)
+\end{equation}
+where $r_1 \;\mbox{and}\;r_2 $ are the slopes between the surface along 
+which the diffusive operator acts and the model level ($e. g.$ $z$- or 
+$s$-surfaces). Note that the formulation \autoref{eq:PE_iso_tensor} is exact for the 
+rotation between geopotential and $s$-surfaces, while it is only an approximation 
+for the rotation between isoneutral and $z$- or $s$-surfaces. Indeed, in the latter 
+case, two assumptions are made to simplify \autoref{eq:PE_iso_tensor} \citep{Cox1987}. 
+First, the horizontal contribution of the dianeutral mixing is neglected since the ratio 
+between iso and dia-neutral diffusive coefficients is known to be several orders of 
+magnitude smaller than unity. Second, the two isoneutral directions of diffusion are 
+assumed to be independent since the slopes are generally less than $10^{-2}$ in the 
+ocean (see \autoref{apdx:B}).
+
+For \textit{iso-level} diffusion, $r_1$ and $r_2 $ are zero. $\Re $ reduces to the identity 
+in the horizontal direction, no rotation is applied. 
+
+For \textit{geopotential} diffusion, $r_1$ and $r_2 $ are the slopes between the 
+geopotential and computational surfaces: they are equal to $\sigma _1$ and $\sigma _2$, 
+respectively (see \autoref{eq:PE_sco_slope}).
+
+For \textit{isoneutral} diffusion $r_1$ and $r_2$ are the slopes between the isoneutral 
+and computational surfaces. Therefore, they are different quantities,
+but have similar expressions in $z$- and $s$-coordinates. In $z$-coordinates:
+\begin{equation} \label{eq:PE_iso_slopes}
+r_1 =\frac{e_3 }{e_1 }	\left( \pd[\rho]{i} \right) \left( \pd[\rho]{k} \right)^{-1} \, \quad
+r_2 =\frac{e_3 }{e_2 }	\left( \pd[\rho]{j} \right) \left( \pd[\rho]{k} \right)^{-1} \,
+\end{equation}
+while in $s$-coordinates $\pd[]{k}$ is replaced by $\pd[]{s}$.
+
+\subsubsection{Eddy induced velocity}
+ When the \textit{eddy induced velocity} parametrisation (eiv) \citep{Gent1990} is used, 
+an additional tracer advection is introduced in combination with the isoneutral diffusion of tracers:
+\begin{equation} \label{eq:PE_iso+eiv}
+D^{lT}=\nabla \cdot \left( {A^{lT}\;\Re \;\nabla T} \right)
+           +\nabla \cdot \left( {{\vect{U}}^\ast \,T} \right)
+\end{equation}
+where ${\vect{U}}^\ast =\left( {u^\ast ,v^\ast ,w^\ast } \right)$ is a non-divergent, 
+eddy-induced transport velocity. This velocity field is defined by:
+\begin{equation} \label{eq:PE_eiv}
+   \begin{split}
+ u^\ast  &= +\frac{1}{e_3       }\frac{\partial }{\partial k}\left[ {A^{eiv}\;\tilde{r}_1 } \right] \\ 
+ v^\ast  &= +\frac{1}{e_3       }\frac{\partial }{\partial k}\left[ {A^{eiv}\;\tilde{r}_2 } \right] \\ 
+ w^\ast &=  -\frac{1}{e_1 e_2 }\left[ 
+                      \frac{\partial }{\partial i}\left( {A^{eiv}\;e_2\,\tilde{r}_1 } \right)
+                     +\frac{\partial }{\partial j}\left( {A^{eiv}\;e_1\,\tilde{r}_2 } \right)      \right]
+   \end{split}
+\end{equation}
+where $A^{eiv}$ is the eddy induced velocity coefficient (or equivalently the isoneutral 
+thickness diffusivity coefficient), and $\tilde{r}_1$ and $\tilde{r}_2$ are the slopes 
+between isoneutral and \emph{geopotential} surfaces. Their values are
+thus independent of the vertical coordinate, but their expression depends on the coordinate: 
+\begin{align} \label{eq:PE_slopes_eiv}
+\tilde{r}_n = \begin{cases}
+   r_n            &      \text{in $z$-coordinate}    \\
+   r_n + \sigma_n &      \text{in \textit{z*} and $s$-coordinates}  
+              \end{cases}
+\quad \text{where } n=1,2
+\end{align}
+
+The normal component of the eddy induced velocity is zero at all the boundaries. 
+This can be achieved in a model by tapering either the eddy coefficient or the slopes 
+to zero in the vicinity of the boundaries. The latter strategy is used in \NEMO (cf. \autoref{chap:LDF}).
+
+\subsubsection{Lateral bilaplacian tracer diffusive operator}
+
+The lateral bilaplacian tracer diffusive operator is defined by:
+\begin{equation} \label{eq:PE_bilapT}
+D^{lT}= - \Delta \left( \;\Delta T \right) 
+\qquad \text{where} \;\; \Delta \bullet = \nabla \left( {\sqrt{B^{lT}\,}\;\Re \;\nabla \bullet} \right)
+ \end{equation}
+It is the Laplacian operator given by \autoref{eq:PE_iso_tensor} applied twice with 
+the harmonic eddy diffusion coefficient set to the square root of the biharmonic one. 
+
+
+\subsubsection{Lateral Laplacian momentum diffusive operator}
+
+The Laplacian momentum diffusive operator along $z$- or $s$-surfaces is found by 
+applying \autoref{eq:PE_lap_vector} to the horizontal velocity vector (see \autoref{apdx:B}):
+\begin{equation} \label{eq:PE_lapU}
+\begin{split}
+{\rm {\bf D}}^{l{\rm {\bf U}}} 
+&= \quad \  \nabla _h \left( {A^{lm}\chi } \right)
+   \ - \ \nabla _h \times \left( {A^{lm}\,\zeta \;{\rm {\bf k}}} \right)     \\
+&=   \left(      \begin{aligned}
+             \frac{1}{e_1      } \frac{\partial \left( A^{lm} \chi          \right)}{\partial i} 
+         &-\frac{1}{e_2 e_3}\frac{\partial \left( {A^{lm} \;e_3 \zeta} \right)}{\partial j}  \\
+             \frac{1}{e_2      }\frac{\partial \left( {A^{lm} \chi         } \right)}{\partial j}   
+         &+\frac{1}{e_1 e_3}\frac{\partial \left( {A^{lm} \;e_3 \zeta} \right)}{\partial i}
+        \end{aligned}    \right)
+\end{split}
+\end{equation}
+
+Such a formulation ensures a complete separation between the vorticity and 
+horizontal divergence fields (see \autoref{apdx:C}). 
+Unfortunately, it is only available in \textit{iso-level} direction. 
+When a rotation is required ($i.e.$ geopotential diffusion in $s-$coordinates 
+or isoneutral diffusion in both $z$- and $s$-coordinates), the $u$ and $v-$fields 
+are considered as independent scalar fields, so that the diffusive operator is given by:
+\begin{equation} \label{eq:PE_lapU_iso}
+\begin{split}
+ D_u^{l{\rm {\bf U}}} &= \nabla .\left( {A^{lm} \;\Re \;\nabla u} \right) \\ 
+ D_v^{l{\rm {\bf U}}} &= \nabla .\left( {A^{lm} \;\Re \;\nabla v} \right)
+ \end{split}
+ \end{equation}
+where $\Re$ is given by \autoref{eq:PE_iso_tensor}. It is the same expression as 
+those used for diffusive operator on tracers. It must be emphasised that such a 
+formulation is only exact in a Cartesian coordinate system, $i.e.$ on a $f-$ or 
+$\beta-$plane, not on the sphere. It is also a very good approximation in vicinity 
+of the Equator in a geographical coordinate system \citep{Lengaigne_al_JGR03}.
+
+\subsubsection{lateral bilaplacian momentum diffusive operator}
+
+As for tracers, the bilaplacian order momentum diffusive operator is a 
+re-entering Laplacian operator with the harmonic eddy diffusion coefficient 
+set to the square root of the biharmonic one. Nevertheless it is currently 
+not available in the iso-neutral case.
+
+\end{document}
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_model_basics_zstar.tex	(revision 10321)
@@ -0,0 +1,262 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+% ================================================================
+% Chapter 1 ——— Model Basics
+% ================================================================
+% ================================================================
+% Curvilinear z*- s*-coordinate System
+% ================================================================
+\chapter{ essai z* s*}
+\section{Curvilinear \textit{z*}- or \textit{s*} coordinate system}
+
+% -------------------------------------------------------------------------------------------------------------
+% ????
+% -------------------------------------------------------------------------------------------------------------
+
+\colorbox{yellow}{ to be updated }
+
+In that case, the free surface equation is nonlinear, and the variations of 
+volume are fully taken into account. These coordinates systems is presented in 
+a report \citep{Levier2007} available on the \NEMO web site. 
+
+\colorbox{yellow}{  end of to be updated}
+\newline
+
+% from MOM4p1 documentation
+
+To overcome problems with vanishing surface and/or bottom cells, we consider the 
+zstar coordinate 
+\begin{equation} \label{eq:PE_}
+	z^\star = H \left( \frac{z-\eta}{H+\eta} \right)
+\end{equation}
+
+This coordinate is closely related to the "eta" coordinate used in many atmospheric 
+models (see Black (1994) for a review of eta coordinate atmospheric models). It 
+was originally used in ocean models by Stacey et al. (1995) for studies of tides 
+next to shelves, and it has been recently promoted by Adcroft and Campin (2004) 
+for global climate modelling.
+
+The surfaces of constant $z^\star$ are quasi-horizontal. Indeed, the $z^\star$ coordinate reduces to $z$ when $\eta$ is zero. In general, when noting the large differences between 
+undulations of the bottom topography versus undulations in the surface height, it 
+is clear that surfaces constant $z^\star$ are very similar to the depth surfaces. These properties greatly reduce difficulties of computing the horizontal pressure gradient relative to terrain following sigma models discussed in \autoref{subsec:PE_sco}. 
+Additionally, since $z^\star$ when $\eta = 0$, no flow is spontaneously generated in an 
+unforced ocean starting from rest, regardless the bottom topography. This behaviour is in contrast to the case with "s"-models, where pressure gradient errors in 
+the presence of nontrivial topographic variations can generate nontrivial spontaneous flow from a resting state, depending on the sophistication of the pressure 
+gradient solver. The quasi-horizontal nature of the coordinate surfaces also facilitates the implementation of neutral physics parameterizations in $z^\star$ models using 
+the same techniques as in $z$-models (see Chapters 13-16 of Griffies (2004) for a 
+discussion of neutral physics in $z$-models, as well as  \autoref{sec:LDF_slp} 
+in this document for treatment in \NEMO). 
+
+The range over which $z^\star$ varies is time independent $-H \leq z^\star \leq 0$. Hence, all 
+cells remain nonvanishing, so long as the surface height maintains $\eta > ?H$. This 
+is a minor constraint relative to that encountered on the surface height when using 
+$s = z$ or $s = z - \eta$. 
+
+Because $z^\star$ has a time independent range, all grid cells have static increments 
+ds, and the sum of the ver tical increments yields the time independent ocean 
+depth %�k ds = H. 
+The $z^\star$ coordinate is therefore invisible to undulations of the 
+free surface, since it moves along with the free surface. This proper ty means that 
+no spurious ver tical transpor t is induced across surfaces of constant $z^\star$ by the 
+motion of external gravity waves. Such spurious transpor t can be a problem in 
+z-models, especially those with tidal forcing. Quite generally, the time independent 
+range for the $z^\star$ coordinate is a very convenient proper ty that allows for a nearly 
+arbitrary ver tical resolution even in the presence of large amplitude fluctuations of 
+the surface height, again so long as $\eta > -H$. 
+
+
+
+%%%
+%  essai update time splitting...
+%%%
+
+
+% ================================================================
+% Surface Pressure Gradient and Sea Surface Height
+% ================================================================
+\section{Surface pressure gradient and sea surface heigth (\protect\mdl{dynspg})}
+\label{sec:DYN_hpg_spg}
+%-----------------------------------------nam_dynspg----------------------------------------------------
+
+\nlst{nam_dynspg} 
+%------------------------------------------------------------------------------------------------------------
+Options are defined through the  \ngn{nam\_dynspg} namelist variables.
+The surface pressure gradient term is related to the representation of the free surface (\autoref{sec:PE_hor_pg}). The main distinction is between the fixed volume case (linear free surface or rigid lid) and the variable volume case (nonlinear free surface, \key{vvl} is active). In the linear free surface case (\autoref{subsec:PE_free_surface}) and rigid lid (\autoref{PE_rigid_lid}), the vertical scale factors $e_{3}$ are fixed in time, while in the nonlinear case (\autoref{subsec:PE_free_surface}) they are time-dependent. With both linear and nonlinear free surface, external gravity waves are allowed in the equations, which imposes a very small time step when an explicit time stepping is used. Two methods are proposed to allow a longer time step for the three-dimensional equations: the filtered free surface, which is a modification of the continuous equations (see \autoref{eq:PE_flt}), and the split-explicit free surface described below. The extra term introduced in the filtered method is calculated implicitly, so that the update of the next velocities is done in module \mdl{dynspg\_flt} and not in \mdl{dynnxt}.
+
+%-------------------------------------------------------------
+% Explicit
+%-------------------------------------------------------------
+\subsubsection{Explicit (\protect\key{dynspg\_exp})}
+\label{subsec:DYN_spg_exp}
+
+In the explicit free surface formulation, the model time step is chosen small enough to describe the external gravity waves (typically a few ten seconds). The sea surface height is given by :
+\begin{equation} \label{eq:dynspg_ssh}
+\frac{\partial \eta }{\partial t}\equiv \frac{\text{EMP}}{\rho _w }+\frac{1}{e_{1T} 
+e_{2T} }\sum\limits_k {\left( {\delta _i \left[ {e_{2u} e_{3u} u} 
+\right]+\delta _j \left[ {e_{1v} e_{3v} v} \right]} \right)} 
+\end{equation}
+
+where EMP is the surface freshwater budget (evaporation minus precipitation, and minus river runoffs (if the later are introduced as a surface freshwater flux, see \autoref{chap:SBC}) expressed in $Kg.m^{-2}.s^{-1}$, and $\rho _w =1,000\,Kg.m^{-3}$ is the volumic mass of pure water. The sea-surface height is evaluated using a leapfrog scheme in combination with an Asselin time filter, i.e. the velocity appearing in (\autoref{eq:dynspg_ssh}) is centred in time (\textit{now} velocity). 
+
+The surface pressure gradient, also evaluated using a leap-frog scheme, is then simply given by :
+\begin{equation} \label{eq:dynspg_exp}
+\left\{ \begin{aligned}
+ - \frac{1}    						{e_{1u}} \;	\delta _{i+1/2} \left[  \,\eta\,  \right] 	\\
+ \\
+ - \frac{1}    						{e_{2v}} \;	\delta _{j+1/2} \left[  \,\eta\,  \right]  
+\end{aligned} \right.
+\end{equation} 
+
+Consistent with the linearization, a $\left. \rho \right|_{k=1} / \rho _o$ factor is omitted in (\autoref{eq:dynspg_exp}). 
+
+%-------------------------------------------------------------
+% Split-explicit time-stepping
+%-------------------------------------------------------------
+\subsubsection{Split-explicit time-stepping (\protect\key{dynspg\_ts})}
+\label{subsec:DYN_spg_ts}
+%--------------------------------------------namdom----------------------------------------------------
+
+\nlst{namdom} 
+%--------------------------------------------------------------------------------------------------------------
+The split-explicit free surface formulation used in OPA follows the one proposed by \citet{Griffies2004}. The general idea is to solve the free surface equation with a small time step, while the three dimensional prognostic variables are solved with a longer time step that is a multiple of \np{rdtbt}
+in the  \ngn{namdom} namelist. 
+(Figure III.3). 
+
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+\begin{figure}[!t] 	\begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_DYN_dynspg_ts}
+\caption{	 \protect\label{fig:DYN_dynspg_ts}
+Schematic of the split-explicit time stepping scheme for the barotropic and baroclinic modes, 
+after \citet{Griffies2004}. Time increases to the right. Baroclinic time steps are denoted by 
+$t-\Delta t$, $t, t+\Delta t$, and $t+2\Delta t$. The curved line represents a leap-frog time step, 
+and the smaller barotropic time steps $N \Delta t=2\Delta t$ are denoted by the zig-zag line. 
+The vertically integrated forcing \textbf{M}(t) computed at baroclinic time step t represents 
+the interaction between the barotropic and baroclinic motions. While keeping the total depth, 
+tracer, and freshwater forcing fields fixed, a leap-frog integration carries the surface height 
+and vertically integrated velocity from t to $t+2 \Delta t$ using N barotropic time steps of length 
+$\Delta t$. Time averaging the barotropic fields over the N+1 time steps (endpoints included) 
+centers the vertically integrated velocity at the baroclinic timestep $t+\Delta t$. 
+A baroclinic leap-frog time step carries the surface height to $t+\Delta t$ using the convergence 
+of the time averaged vertically integrated velocity taken from baroclinic time step t. }
+\end{center}
+\end{figure}
+%>   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >   >
+
+The split-explicit formulation has a damping effect on external gravity waves, which is weaker than the filtered free surface but still significant as shown by \citet{Levier2007} in the case of an analytical barotropic Kelvin wave. 
+
+%from griffies book: .....   copy past !
+
+\textbf{title: Time stepping the barotropic system }
+
+Assume knowledge of the full velocity and tracer fields at baroclinic time $\tau$. Hence, 
+we can update the surface height and vertically integrated velocity with a leap-frog 
+scheme using the small barotropic time step $\Delta t$. We have 
+
+\begin{equation} \label{eq:DYN_spg_ts_eta}
+\eta^{(b)}(\tau,t_{n+1}) - \eta^{(b)}(\tau,t_{n+1}) (\tau,t_{n-1})
+	= 2 \Delta t \left[-\nabla \cdot \textbf{U}^{(b)}(\tau,t_n) + \text{EMP}_w(\tau) \right] 
+\end{equation}
+\begin{multline} \label{eq:DYN_spg_ts_u}
+\textbf{U}^{(b)}(\tau,t_{n+1}) - \textbf{U}^{(b)}(\tau,t_{n-1})  \\
+	= 2\Delta t \left[ - f \textbf{k} \times \textbf{U}^{(b)}(\tau,t_{n}) 
+	- H(\tau) \nabla p_s^{(b)}(\tau,t_{n}) +\textbf{M}(\tau) \right]
+\end{multline}
+\
+
+In these equations, araised (b) denotes values of surface height and vertically integrated velocity updated with the barotropic time steps. The $\tau$ time label on $\eta^{(b)}$ 
+and $U^{(b)}$ denotes the baroclinic time at which the vertically integrated forcing $\textbf{M}(\tau)$ (note that this forcing includes the surface freshwater forcing), the tracer fields, the freshwater flux $\text{EMP}_w(\tau)$, and total depth of the ocean $H(\tau)$ are held for the duration of the barotropic time stepping over a single cycle. This is also the time 
+that sets the barotropic time steps via 
+\begin{equation} \label{eq:DYN_spg_ts_t}
+t_n=\tau+n\Delta t   
+\end{equation}
+with $n$ an integer. The density scaled surface pressure is evaluated via 
+\begin{equation} \label{eq:DYN_spg_ts_ps}
+p_s^{(b)}(\tau,t_{n}) = \begin{cases}
+	g \;\eta_s^{(b)}(\tau,t_{n}) \;\rho(\tau)_{k=1}) / \rho_o  &      \text{non-linear case} \\
+	g \;\eta_s^{(b)}(\tau,t_{n})  &      \text{linear case} 
+	\end{cases}
+\end{equation}
+To get started, we assume the following initial conditions 
+\begin{equation} \label{eq:DYN_spg_ts_eta}
+\begin{split}
+\eta^{(b)}(\tau,t_{n=0}) &= \overline{\eta^{(b)}(\tau)}
+\\
+\eta^{(b)}(\tau,t_{n=1}) &= \eta^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0} 
+\end{split}
+\end{equation}
+with 
+\begin{equation} \label{eq:DYN_spg_ts_etaF}
+ \overline{\eta^{(b)}(\tau)} = \frac{1}{N+1} \sum\limits_{n=0}^N \eta^{(b)}(\tau-\Delta t,t_{n})
+\end{equation}
+the time averaged surface height taken from the previous barotropic cycle. Likewise, 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+\textbf{U}^{(b)}(\tau,t_{n=0}) = \overline{\textbf{U}^{(b)}(\tau)}	\\
+\\
+\textbf{U}(\tau,t_{n=1}) = \textbf{U}^{(b)}(\tau,t_{n=0}) + \Delta t \ \text{RHS}_{n=0}  	
+\end{equation}
+with 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+ \overline{\textbf{U}^{(b)}(\tau)} 
+ 	= \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau-\Delta t,t_{n})
+\end{equation}
+the time averaged vertically integrated transport. Notably, there is no Robert-Asselin time filter used in the barotropic portion of the integration. 
+
+Upon reaching $t_{n=N} = \tau + 2\Delta \tau$ , the vertically integrated velocity is time averaged to produce the updated vertically integrated velocity at baroclinic time $\tau + \Delta \tau$ 
+\begin{equation} \label{eq:DYN_spg_ts_u}
+\textbf{U}(\tau+\Delta t) = \overline{\textbf{U}^{(b)}(\tau+\Delta t)} 
+ 	= \frac{1}{N+1} \sum\limits_{n=0}^N\textbf{U}^{(b)}(\tau,t_{n})
+\end{equation}
+The surface height on the new baroclinic time step is then determined via a baroclinic leap-frog using the following form 
+
+\begin{equation} \label{eq:DYN_spg_ts_ssh}
+\eta(\tau+\Delta) - \eta^{F}(\tau-\Delta) = 2\Delta t \ \left[ - \nabla \cdot \textbf{U}(\tau) + \text{EMP}_w \right]  
+\end{equation}
+
+ The use of this "big-leap-frog" scheme for the surface height ensures compatibility between the mass/volume budgets and the tracer budgets. More discussion of this point is provided in Chapter 10 (see in particular Section 10.2). 
+ 
+In general, some form of time filter is needed to maintain integrity of the surface 
+height field due to the leap-frog splitting mode in equation \autoref{eq:DYN_spg_ts_ssh}. We 
+have tried various forms of such filtering, with the following method discussed in 
+Griffies et al. (2001) chosen due to its stability and reasonably good maintenance of 
+tracer conservation properties (see ??) 
+
+\begin{equation} \label{eq:DYN_spg_ts_sshf}
+\eta^{F}(\tau-\Delta) =  \overline{\eta^{(b)}(\tau)} 
+\end{equation}
+Another approach tried was 
+
+\begin{equation} \label{eq:DYN_spg_ts_sshf2}
+\eta^{F}(\tau-\Delta) = \eta(\tau) 
+	+ (\alpha/2) \left[\overline{\eta^{(b)}}(\tau+\Delta t)
+				    + \overline{\eta^{(b)}}(\tau-\Delta t) -2 \;\eta(\tau) \right]
+\end{equation}
+
+which is useful since it isolates all the time filtering aspects into the term multiplied 
+by $\alpha$. This isolation allows for an easy check that tracer conservation is exact when 
+eliminating tracer and surface height time filtering (see ?? for more complete discussion). However, in the general case with a non-zero $\alpha$, the filter \autoref{eq:DYN_spg_ts_sshf} was found to be more conservative, and so is recommended. 
+
+
+
+
+
+%-------------------------------------------------------------
+% Filtered formulation 
+%-------------------------------------------------------------
+\subsubsection{Filtered formulation (\protect\key{dynspg\_flt})}
+\label{subsec:DYN_spg_flt}
+
+The filtered formulation follows the \citet{Roullet2000} implementation. The extra term introduced in the equations (see {\S}I.2.2) is solved implicitly. The elliptic solvers available in the code are 
+documented in \autoref{chap:MISC}. The amplitude of the extra term is given by the namelist variable \np{rnu}. The default value is 1, as recommended by \citet{Roullet2000}
+
+\colorbox{red}{\np{rnu}\forcode{ = 1} to be suppressed from namelist !}
+
+%-------------------------------------------------------------
+% Non-linear free surface formulation 
+%-------------------------------------------------------------
+\subsection{Non-linear free surface formulation (\protect\key{vvl})}
+\label{subsec:DYN_spg_vvl}
+
+In the non-linear free surface formulation, the variations of volume are fully taken into account. This option is presented in a report \citep{Levier2007} available on the NEMO web site. The three time-stepping methods (explicit, split-explicit and filtered) are the same as in \autoref{DYN_spg_linear} except that the ocean depth is now time-dependent. In particular, this means that in filtered case, the matrix to be inverted has to be recomputed at each time-step.
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_time_domain.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/chap_time_domain.tex	(revision 10321)
@@ -0,0 +1,408 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% Chapter 2 ——— Time Domain (step.F90)
+% ================================================================
+\chapter{Time Domain (STP) }
+\label{chap:STP}
+\minitoc
+
+% Missing things:
+%	- daymod: definition of the time domain (nit000, nitend andd the calendar)
+
+
+\gmcomment{STEVEN :maybe a picture of the directory structure in the introduction 
+which could be referred to here, would help  ==> to be added}
+%%%%
+
+
+\newpage
+$\ $\newline    % force a new ligne
+
+
+Having defined the continuous equations in \autoref{chap:PE}, we need now to choose 
+a time discretization, a key feature of an ocean model as it exerts a strong influence  
+on the structure of the computer code ($i.e.$ on its flowchart). 
+In the present chapter, we provide a general description of the \NEMO 
+time stepping strategy and the consequences for the order in which the equations are
+solved.
+
+$\ $\newline    % force a new ligne
+% ================================================================
+% Time Discretisation
+% ================================================================
+\section{Time stepping environment}
+\label{sec:STP_environment}
+
+The time stepping used in \NEMO is a three level scheme that can be 
+represented as follows:
+\begin{equation} \label{eq:STP}
+   x^{t+\rdt} = x^{t-\rdt} + 2 \, \rdt \  \text{RHS}_x^{t-\rdt,\,t,\,t+\rdt}
+\end{equation} 
+where $x$ stands for $u$, $v$, $T$ or $S$; RHS is the Right-Hand-Side of the 
+corresponding time evolution equation; $\rdt$ is the time step; and the 
+superscripts indicate the time at which a quantity is evaluated. Each term of the 
+RHS is evaluated at a specific time step depending on the physics with which 
+it is associated. 
+
+The choice of the time step used for this evaluation is discussed below as 
+well as the implications for starting or restarting a model 
+simulation. Note that the time stepping calculation is generally performed in a single 
+operation. With such a complex and nonlinear system of equations it would be 
+dangerous to let a prognostic variable evolve in time for each term separately.
+
+The three level scheme requires three arrays for each prognostic variable. 
+For each variable $x$ there is $x_b$ (before), $x_n$ (now) and $x_a$. The third array, 
+although referred to as $x_a$ (after) in the code, is usually not the variable at 
+the after time step; but rather it is used to store the time derivative (RHS in 
+\autoref{eq:STP}) prior to time-stepping the equation. Generally, the time 
+stepping is performed once at each time step in the \mdl{tranxt} and \mdl{dynnxt} 
+modules, except when using implicit vertical diffusion or calculating sea surface height 
+in which case time-splitting options are used.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Non-Diffusive Part---Leapfrog Scheme
+% -------------------------------------------------------------------------------------------------------------
+\section{Non-diffusive part --- Leapfrog scheme}
+\label{sec:STP_leap_frog}
+
+The time stepping used for processes other than diffusion is the well-known leapfrog
+scheme \citep{Mesinger_Arakawa_Bk76}.  This scheme is widely used for advection 
+processes in low-viscosity fluids. It is a time centred scheme, $i.e.$ 
+the RHS in \autoref{eq:STP} is evaluated at time step $t$, the now time step. 
+It may be used for momentum and tracer advection, 
+pressure gradient, and Coriolis terms, but not for diffusion terms.
+It is an efficient method that achieves 
+second-order accuracy with just one right hand side evaluation per time step. 
+Moreover, it does not artificially damp linear oscillatory motion nor does it produce 
+instability by amplifying the oscillations. These advantages are somewhat diminished 
+by the large phase-speed error of the leapfrog scheme, and the unsuitability 
+of leapfrog differencing for the representation of diffusion and Rayleigh 
+damping processes. However, the scheme allows the coexistence of a numerical 
+and a physical mode due to its leading third order dispersive error. In other words a 
+divergence of odd and even time steps may occur. To prevent it, the leapfrog scheme 
+is often used in association with a Robert-Asselin time filter (hereafter the LF-RA scheme). 
+This filter, first designed by \citet{Robert_JMSJ66} and more comprehensively studied 
+by \citet{Asselin_MWR72}, is a kind of laplacian diffusion in time that mixes odd and 
+even time steps:
+\begin{equation} \label{eq:STP_asselin}
+x_F^t  = x^t + \gamma \, \left[ x_F^{t-\rdt} - 2 x^t + x^{t+\rdt} \right]
+\end{equation} 
+where the subscript $F$ denotes filtered values and $\gamma$ is the Asselin 
+coefficient. $\gamma$ is initialized as \np{rn\_atfp} (namelist parameter). 
+Its default value is \np{rn\_atfp}\forcode{ = 10.e-3} (see \autoref{sec:STP_mLF}), 
+causing only a weak dissipation of high frequency motions (\citep{Farge1987}). 
+The addition of a time filter degrades the accuracy of the 
+calculation from second to first order. However, the second order truncation 
+error is proportional to $\gamma$, which is small compared to 1. Therefore, 
+the LF-RA is a quasi second order accurate scheme. The LF-RA scheme 
+is preferred to other time differencing schemes such as 
+predictor corrector or trapezoidal schemes, because the user has an explicit 
+and simple control of the magnitude of the time diffusion of the scheme. 
+When used with the 2nd order space centred discretisation of the 
+advection terms in the momentum and tracer equations, LF-RA avoids implicit 
+numerical diffusion: diffusion is set explicitly by the user through the Robert-Asselin 
+filter parameter and the viscosity and diffusion coefficients.
+
+% -------------------------------------------------------------------------------------------------------------
+%        Diffusive Part---Forward or Backward Scheme
+% -------------------------------------------------------------------------------------------------------------
+\section{Diffusive part --- Forward or backward scheme}
+\label{sec:STP_forward_imp}
+
+The leapfrog differencing scheme is unsuitable for the representation of 
+diffusion and damping processes. For a tendancy $D_x$, representing a 
+diffusion term or a restoring term to a tracer climatology 
+(when present, see \autoref{sec:TRA_dmp}), a forward time differencing scheme
+ is used :
+\begin{equation} \label{eq:STP_euler}
+   x^{t+\rdt} = x^{t-\rdt} + 2 \, \rdt \ {D_x}^{t-\rdt}
+\end{equation} 
+
+This is diffusive in time and conditionally stable. The 
+conditions for stability of second and fourth order horizontal diffusion schemes are \citep{Griffies_Bk04}:
+\begin{equation} \label{eq:STP_euler_stability}
+A^h < \left\{
+\begin{aligned}
+                    &\frac{e^2}{  8 \; \rdt } 	&&\quad \text{laplacian diffusion} 	\\
+                    &\frac{e^4}{64 \; \rdt } 	&&\quad \text{bilaplacian diffusion} 
+            \end{aligned}
+\right.
+\end{equation}
+where $e$ is the smallest grid size in the two horizontal directions and $A^h$ is 
+the mixing coefficient. The linear constraint \autoref{eq:STP_euler_stability} 
+is a necessary condition, but not sufficient. If it is not satisfied, even mildly, 
+then the model soon becomes wildly unstable. The instability can be removed 
+by either reducing the length of the time steps or reducing the mixing coefficient.
+
+For the vertical diffusion terms, a forward time differencing scheme can be 
+used, but usually the numerical stability condition imposes a strong 
+constraint on the time step. Two solutions are available in \NEMO to overcome 
+the stability constraint: $(a)$ a forward time differencing scheme using a 
+time splitting technique (\np{ln\_zdfexp}\forcode{ = .true.}) or $(b)$ a backward (or implicit) 
+time differencing scheme (\np{ln\_zdfexp}\forcode{ = .false.}). In $(a)$, the master 
+time step $\Delta $t is cut into $N$ fractional time steps so that the 
+stability criterion is reduced by a factor of $N$. The computation is performed as 
+follows:
+\begin{equation} \label{eq:STP_ts}
+\begin{split}
+& x_\ast ^{t-\rdt} = x^{t-\rdt}   \\
+& x_\ast ^{t-\rdt+L\frac{2\rdt}{N}}=x_\ast ^{t-\rdt+\left( {L-1} 
+\right)\frac{2\rdt}{N}}+\frac{2\rdt}{N}\;\text{DF}^{t-\rdt+\left( {L-1} \right)\frac{2\rdt}{N}}
+        \quad \text{for $L=1$ to $N$}      \\
+& x^{t+\rdt} = x_\ast^{t+\rdt}
+\end{split}
+\end{equation}
+with DF a vertical diffusion term. The number of fractional time steps, $N$, is given 
+by setting \np{nn\_zdfexp}, (namelist parameter). The scheme $(b)$ is unconditionally 
+stable but diffusive. It can be written as follows:
+\begin{equation} \label{eq:STP_imp}
+   x^{t+\rdt} = x^{t-\rdt} + 2 \, \rdt \  \text{RHS}_x^{t+\rdt}
+\end{equation} 
+
+%%gm
+%%gm   UPDATE the next paragraphs with time varying thickness ...
+%%gm
+
+This scheme is rather time consuming since it requires a matrix inversion, 
+but it becomes attractive since a value of 3 or more is needed for N in
+the forward time differencing scheme. For example, the finite difference 
+approximation of the temperature equation is:
+\begin{equation} \label{eq:STP_imp_zdf}
+\frac{T(k)^{t+1}-T(k)^{t-1}}{2\;\rdt}\equiv \text{RHS}+\frac{1}{e_{3t} }\delta 
+_k \left[ {\frac{A_w^{vT} }{e_{3w} }\delta _{k+1/2} \left[ {T^{t+1}} \right]} 
+\right]
+\end{equation}
+where RHS is the right hand side of the equation except for the vertical diffusion term. 
+We rewrite \autoref{eq:STP_imp} as:
+\begin{equation} \label{eq:STP_imp_mat}
+-c(k+1)\;T^{t+1}(k+1) + d(k)\;T^{t+1}(k) - \;c(k)\;T^{t+1}(k-1) \equiv b(k)
+\end{equation}
+where 
+\begin{align*} 
+ c(k) &= A_w^{vT} (k) \, / \, e_{3w} (k)     \\
+ d(k) &= e_{3t} (k)       \, / \, (2\rdt) + c_k + c_{k+1}    \\
+ b(k) &= e_{3t} (k) \; \left( T^{t-1}(k) \, / \, (2\rdt) + \text{RHS} \right)    
+\end{align*}
+
+\autoref{eq:STP_imp_mat} is a linear system of equations with an associated 
+matrix which is tridiagonal. Moreover, $c(k)$ and $d(k)$ are positive and the diagonal 
+term is greater than the sum of the two extra-diagonal terms, therefore a special 
+adaptation of the Gauss elimination procedure is used to find the solution 
+(see for example \citet{Richtmyer1967}).
+
+
+
+% -------------------------------------------------------------------------------------------------------------
+%        Surface Pressure gradient
+% -------------------------------------------------------------------------------------------------------------
+\section{Surface pressure gradient}
+\label{sec:STP_spg_ts}
+
+===>>>>  TO BE written....  :-)
+
+%\gmcomment{ 
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	  \begin{center}
+\includegraphics[width=0.7\textwidth]{Fig_TimeStepping_flowchart}
+\caption{ 	\protect\label{fig:TimeStep_flowchart}
+Sketch of the leapfrog time stepping sequence in \NEMO from \citet{Leclair_Madec_OM09}. 
+The use of a semi-implicit computation of the hydrostatic pressure gradient requires
+the tracer equation to be stepped forward prior to the momentum equation. 
+The need for knowledge of the vertical scale factor (here denoted as $h$)
+requires the sea surface height and the continuity equation to be stepped forward
+prior to the computation of the tracer equation.
+Note that the method for the evaluation of the surface pressure gradient $\nabla p_s$ is not presented here 
+(see \autoref{sec:DYN_spg}). }
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+%}
+
+% -------------------------------------------------------------------------------------------------------------
+%        The Modified Leapfrog -- Asselin Filter scheme
+% -------------------------------------------------------------------------------------------------------------
+\section{Modified Leapfrog -- Asselin filter scheme}
+\label{sec:STP_mLF}
+
+Significant changes have been introduced by \cite{Leclair_Madec_OM09} in the 
+LF-RA scheme in order to ensure tracer conservation and to allow the use of 
+a much smaller value of the Asselin filter parameter. The modifications affect 
+both the forcing and filtering treatments in the LF-RA scheme.
+
+In a classical LF-RA environment, the forcing term is centred in time, $i.e.$ 
+it is time-stepped over a $2\rdt$ period:  $x^t  = x^t + 2\rdt Q^t $ where $Q$ 
+is the forcing applied to $x$, and the time filter is given by \autoref{eq:STP_asselin} 
+so that $Q$ is redistributed over several time step. 
+In the modified LF-RA environment, these two formulations have been replaced by:
+\begin{align} 
+x^{t+\rdt}  &= x^{t-\rdt} + \rdt \left( Q^{t-\rdt/2} + Q^{t+\rdt/2} \right)                   \label{eq:STP_forcing} \\
+%
+x_F^t  &= x^t + \gamma \, \left[ x_F^{t-\rdt} - 2 x^t + x^{t+\rdt} \right] 
+           - \gamma\,\rdt \, \left[ Q^{t+\rdt/2} -  Q^{t-\rdt/2} \right]                          \label{eq:STP_RA}
+\end{align}
+The change in the forcing formulation given by \autoref{eq:STP_forcing} 
+(see \autoref{fig:MLF_forcing}) has a significant effect: the forcing term no 
+longer excites the divergence of odd and even time steps \citep{Leclair_Madec_OM09}. 
+% forcing seen by the model....
+This property improves the LF-RA scheme in two respects. 
+First, the LF-RA can now ensure the local and global conservation of tracers.
+Indeed, time filtering is no longer required on the forcing part. The influence of 
+the Asselin filter on the forcing is be removed by adding a new term in the filter
+(last term in \autoref{eq:STP_RA} compared to \autoref{eq:STP_asselin}). Since 
+the filtering of the forcing was the source of non-conservation in the classical 
+LF-RA scheme, the modified formulation becomes conservative  \citep{Leclair_Madec_OM09}.
+Second, the LF-RA becomes a truly quasi-second order scheme. Indeed, 
+\autoref{eq:STP_forcing} used in combination with a careful treatment of static 
+instability (\autoref{subsec:ZDF_evd}) and of the TKE physics (\autoref{subsec:ZDF_tke_ene}),
+the two other main sources of time step divergence, allows a reduction by 
+two orders of magnitude of the Asselin filter parameter. 
+
+Note that the forcing is now provided at the middle of a time step: $Q^{t+\rdt/2}$ 
+is the forcing applied over the $[t,t+\rdt]$ time interval. This and the change 
+in the time filter, \autoref{eq:STP_RA}, allows an exact evaluation of the 
+contribution due to the forcing term between any two time steps, 
+even if separated by only $\rdt$ since the time filter is no longer applied to the
+forcing term.
+
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+\begin{figure}[!t] 	  \begin{center}
+\includegraphics[width=0.90\textwidth]{Fig_MLF_forcing}
+\caption{ 	\protect\label{fig:MLF_forcing}
+Illustration of forcing integration methods. 
+(top) ''Traditional'' formulation : the forcing is defined at the same time as the variable 
+to which it is applied (integer value of the time step index) and it is applied over a $2\rdt$ period. 
+(bottom)  modified formulation : the forcing is defined in the middle of the time (integer and a half 
+value of the time step index) and the mean of two successive forcing values ($n-1/2$, $n+1/2$).
+is applied over a $2\rdt$ period.}
+\end{center}   \end{figure}
+%>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+% -------------------------------------------------------------------------------------------------------------
+%        Start/Restart strategy
+% -------------------------------------------------------------------------------------------------------------
+\section{Start/Restart strategy}
+\label{sec:STP_rst}
+
+%--------------------------------------------namrun-------------------------------------------
+\nlst{namrun}
+%--------------------------------------------------------------------------------------------------------------
+
+The first time step of this three level scheme when starting from initial conditions 
+is a forward step (Euler time integration): 
+\begin{equation} \label{eq:DOM_euler}
+	x^1 = x^0 + \rdt \ \text{RHS}^0
+\end{equation}
+This is done simply by keeping the leapfrog environment ($i.e.$ the \autoref{eq:STP} 
+three level time stepping) but setting all $x^0$ (\textit{before}) and $x^{1}$ (\textit{now}) fields 
+equal at the first time step and using half the value of $\rdt$.
+
+It is also possible to restart from a previous computation, by using a 
+restart file. The restart strategy is designed to ensure perfect 
+restartability of the code: the user should obtain the same results to 
+machine precision either by running the model for $2N$ time steps in one go, 
+or by performing two consecutive experiments of $N$ steps with a restart. 
+This requires saving two time levels and many auxiliary data in the restart 
+files in machine precision. 
+
+Note that when a semi-implicit scheme is used to evaluate the hydrostatic pressure 
+gradient (see \autoref{subsec:DYN_hpg_imp}), an extra three-dimensional field has to be 
+added to the restart file to ensure an exact restartability. This is done optionally 
+via the  \np{nn\_dynhpg\_rst} namelist parameter, so that the size of the
+restart file can be reduced when restartability is not a key issue (operational 
+oceanography or in ensemble simulations for seasonal forecasting).
+
+Note the size of the time step used, $\rdt$, is also saved in the restart file. 
+When restarting, if the the time step has been changed, a restart using an Euler time 
+stepping scheme is imposed. 
+Options are defined through the  \ngn{namrun} namelist variables.
+%%%
+\gmcomment{
+add here how to force the restart to contain only one time step for operational purposes
+
+add also the idea of writing several restart for seasonal forecast : how is it done ?
+
+verify that all namelist pararmeters are truly described 
+
+a word on the check of restart  .....
+}
+%%%
+
+\gmcomment{       % add a subsection here  
+
+%-------------------------------------------------------------------------------------------------------------
+%        Time Domain
+% -------------------------------------------------------------------------------------------------------------
+\subsection{Time domain}
+\label{subsec:STP_time}
+%--------------------------------------------namrun-------------------------------------------
+
+\nlst{namdom}         
+%--------------------------------------------------------------------------------------------------------------
+
+Options are defined through the  \ngn{namdom} namelist variables.
+ \colorbox{yellow}{add here a few word on nit000 and nitend}
+
+ \colorbox{yellow}{Write documentation on the calendar and the key variable adatrj}
+
+add a description of daymod, and the model calandar (leap-year and co)
+
+}     	%% end add
+
+
+
+%%
+\gmcomment{       % add implicit in vvl case  and Crant-Nicholson scheme   
+
+Implicit time stepping in case of variable volume thickness.
+
+Tracer case (NB for momentum in vector invariant form take care!)
+
+\begin{flalign*}
+&\frac{\left( e_{3t}\,T \right)_k^{t+1}-\left( e_{3t}\,T \right)_k^{t-1}}{2\rdt}
+\equiv \text{RHS}+ \delta _k \left[ {\frac{A_w^{vt} }{e_{3w}^{t+1} }\delta _{k+1/2} \left[ {T^{t+1}} \right]} 
+\right]      \\
+&\left( e_{3t}\,T \right)_k^{t+1}-\left( e_{3t}\,T \right)_k^{t-1}
+\equiv {2\rdt} \ \text{RHS}+ {2\rdt} \ \delta _k \left[ {\frac{A_w^{vt} }{e_{3w}^{t+1} }\delta _{k+1/2} \left[ {T^{t+1}} \right]} 
+\right]      \\
+&\left( e_{3t}\,T \right)_k^{t+1}-\left( e_{3t}\,T \right)_k^{t-1}
+\equiv 2\rdt \ \text{RHS}
++ 2\rdt \ \left\{ \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k+1/2} [ T_{k+1}^{t+1} - T_k      ^{t+1} ]
+                          - \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k-1/2} [ T_k       ^{t+1} - T_{k-1}^{t+1} ]  \right\}     \\
+&\\
+&\left( e_{3t}\,T \right)_k^{t+1}
+-  {2\rdt} \           \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k+1/2}                  T_{k+1}^{t+1} 
++ {2\rdt} \ \left\{  \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k+1/2} 
+                            +  \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k-1/2}     \right\}   T_{k    }^{t+1}
+-  {2\rdt} \           \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k-1/2}                  T_{k-1}^{t+1}      \\
+&\equiv \left( e_{3t}\,T \right)_k^{t-1} + {2\rdt} \ \text{RHS}    \\
+%
+\end{flalign*}
+
+\begin{flalign*}
+\allowdisplaybreaks
+\intertext{ Tracer case }
+%
+&  \qquad \qquad  \quad   -  {2\rdt}                  \ \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k+1/2}   
+                                                                                                      \qquad \qquad \qquad  \qquad  T_{k+1}^{t+1}   \\
+&+ {2\rdt} \ \biggl\{  (e_{3t})_{k   }^{t+1}  \bigg. +    \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k+1/2}  
+                                                                               +   \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k-1/2} \bigg. \biggr\}  \ \ \ T_{k   }^{t+1}  &&\\
+& \qquad \qquad  \qquad \qquad \qquad \quad \ \ -  {2\rdt} \                          \left[ \frac{A_w^{vt}}{e_{3w}^{t+1}} \right]_{k-1/2}                          \quad \ \ T_{k-1}^{t+1}     
+\ \equiv \ \left( e_{3t}\,T \right)_k^{t-1} + {2\rdt} \ \text{RHS}  \\
+%
+\end{flalign*}
+\begin{flalign*}
+\allowdisplaybreaks
+\intertext{ Tracer content case }
+%
+& -  {2\rdt} \              & \frac{(A_w^{vt})_{k+1/2}} {(e_{3w})_{k+1/2}^{t+1}\;(e_{3t})_{k+1}^{t+1}}  && \  \left( e_{3t}\,T \right)_{k+1}^{t+1}   &\\
+& + {2\rdt} \ \left[ 1  \right.+ & \frac{(A_w^{vt})_{k+1/2}} {(e_{3w})_{k+1/2}^{t+1}\;(e_{3t})_k^{t+1}} 
+                                    + & \frac{(A_w^{vt})_{k -1/2}} {(e_{3w})_{k -1/2}^{t+1}\;(e_{3t})_k^{t+1}}  \left.  \right]  & \left( e_{3t}\,T \right)_{k   }^{t+1}  &\\
+& -  {2\rdt} \               & \frac{(A_w^{vt})_{k -1/2}} {(e_{3w})_{k -1/2}^{t+1}\;(e_{3t})_{k-1}^{t+1}}     &\  \left( e_{3t}\,T \right)_{k-1}^{t+1}   
+\equiv \left( e_{3t}\,T \right)_k^{t-1} + {2\rdt} \ \text{RHS}  &
+\end{flalign*}
+
+%%
+}
+%%
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/introduction.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/introduction.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/NEMO/subfiles/introduction.tex	(revision 10321)
@@ -0,0 +1,266 @@
+\documentclass[../tex_main/NEMO_manual]{subfiles}
+\begin{document}
+
+% ================================================================
+% INTRODUCTION
+% ================================================================
+
+\chapter{Introduction}
+
+The Nucleus for European Modelling of the Ocean (\NEMO) is a framework of ocean 
+related engines, namely OPA\footnote{OPA = Oc\'{e}an PArall\'{e}lis\'{e}} for the 
+ocean dynamics and thermodynamics, LIM\footnote{LIM = Louvain la-neuve Ice 
+Model} for the sea-ice dynamics and thermodynamics, TOP\footnote{TOP = Tracer 
+in the Ocean Paradigm} for the biogeochemistry (both transport (TRP) and sources 
+minus sinks (LOBSTER\footnote{LOBSTER = Lodyc Ocean Biogeochemical SysTem for 
+Ecosystem and Resources}, PISCES\footnote{PISCES = Pelagic Interactions Scheme for 
+Carbon and Ecosystem Studies}). It is intended to be a flexible tool for studying 
+the ocean and its interactions with the other components of the earth climate system 
+(atmosphere, sea-ice, biogeochemical tracers, ...) over a wide range of space and time scales. 
+This documentation provides information about the physics represented by the ocean 
+component of \NEMO and the rationale for the choice of numerical schemes and 
+the model design. More specific information about running the model on different 
+computers, or how to set up a configuration, are found on the \NEMO web site 
+(www.nemo-ocean.eu). 
+
+The ocean component of \NEMO has been developed from the OPA model, 
+release 8.2, described in \citet{Madec1998}. This model has been used for a wide 
+range of applications, both regional or global, as a forced ocean model and as a 
+model coupled with the sea-ice and/or the atmosphere.  
+
+This manual is organised in as follows. \autoref{chap:PE} presents the model basics, 
+$i.e.$ the equations and their assumptions, the vertical coordinates used, and the 
+subgrid scale physics. This part deals with the continuous equations of the model 
+(primitive equations, with temperature, salinity and an equation of seawater). 
+The equations are written in a curvilinear coordinate system, with a choice of vertical 
+coordinates ($z$, $s$, \textit{z*}, \textit{s*}, $\tilde{z}$, $\tilde{s}$, and a mixture of them). 
+Momentum equations are formulated in vector invariant or flux form. 
+Dimensional units in the meter, kilogram, second (MKS) international system 
+are used throughout.
+
+The following chapters deal with the discrete equations. \autoref{chap:STP} presents the 
+time domain. The model time stepping environment is a three level scheme in which 
+the tendency terms of the equations are evaluated either centered  in time, or forward, 
+or backward depending of the nature of the term.
+\autoref{chap:DOM} presents the space domain. The model is discretised on a staggered 
+grid (Arakawa C grid) with masking of land areas. Vertical discretisation used depends 
+on both how the bottom topography is represented and whether the free surface is linear or not. 
+Full step or partial step $z$-coordinate or $s$- (terrain-following) coordinate is used 
+with linear free surface (level position are then fixed in time). In non-linear free surface, 
+the corresponding rescaled height coordinate formulation (\textit{z*} or \textit{s*}) is used 
+(the level position then vary in time as a function of the sea surface heigh). 
+The following two chapters (\autoref{chap:TRA} and \autoref{chap:DYN}) describe the discretisation of the 
+prognostic equations for the active tracers and the momentum. Explicit, split-explicit 
+and filtered free surface formulations are implemented. 
+A number of numerical schemes are available for momentum advection, for the computation 
+of the pressure gradients, as well as for the advection of tracers (second or higher 
+order advection schemes, including positive ones).
+
+Surface boundary conditions (\autoref{chap:SBC}) can be implemented as prescribed
+fluxes, or bulk formulations for the surface fluxes (wind stress, heat, freshwater). The 
+model allows penetration of solar radiation  There is an optional geothermal heating at 
+the ocean bottom. Within the \NEMO system the ocean model is interactively coupled 
+with a sea ice model (LIM) and with biogeochemistry models (PISCES, LOBSTER). 
+Interactive coupling to Atmospheric models is possible via the OASIS coupler 
+\citep{OASIS2006}. Two-way nesting is also available through an interface to the
+AGRIF package (Adaptative Grid Refinement in \textsc{Fortran}) \citep{Debreu_al_CG2008}.
+The interface code for coupling to an alternative sea ice model (CICE, \citet{Hunke2008})
+has now been upgraded so that it works for both global and regional domains, although AGRIF 
+is still not available.
+
+Other model characteristics are the lateral boundary conditions (\autoref{chap:LBC}).  
+Global configurations of the model make use of the ORCA tripolar grid, with special north 
+fold boundary condition. Free-slip or no-slip boundary conditions are allowed at land 
+boundaries. Closed basin geometries as well as periodic domains and open boundary 
+conditions are possible. 
+
+Physical parameterisations are described in \autoref{chap:LDF} and \autoref{chap:ZDF}. The 
+model includes an implicit treatment of vertical viscosity and diffusivity. The lateral 
+Laplacian and biharmonic viscosity and diffusion can be rotated following a geopotential 
+or neutral direction. There is an optional eddy induced velocity \citep{Gent1990} with a 
+space and time variable coefficient \citet{Treguier1997}. The model has vertical harmonic 
+viscosity and diffusion with a space and time variable coefficient, with options to compute 
+the coefficients with \citet{Blanke1993}, \citet{Pacanowski_Philander_JPO81}, 
+or \citet{Umlauf_Burchard_JMS03} mixing schemes.
+ \vspace{1cm}
+ 
+%%gm    To be put somewhere else ....
+
+\noindent CPP keys and namelists are used for inputs to the code.  \newline
+
+\noindent \index{CPP keys} CPP keys \newline
+Some CPP keys are implemented in the FORTRAN code to allow code selection at compiling step. This selection of code at compilation time reduces the reliability of the whole platform since it changes the code from one set of CPP keys to the other. It is used only when the addition/suppression of the part of code highly changes the amount of memory at run time.
+Usual coding looks like : 
+\begin{forlines}
+#if defined key_option1
+	! This part of the FORTRAN code will be active
+	! only if key_option1 is activated at compiling step
+#endif
+\end{forlines}
+
+\noindent \index{Namelist} Namelists
+
+The namelist allows to input variables (character, logical, real and integer) into the code. There is one namelist file for each component of NEMO (dynamics, sea-ice, biogeochemistry...) containing all the FOTRAN namelists needed. The implementation in NEMO uses a two step process. For each FORTRAN namelist, two files are read:
+\begin{enumerate}
+\item A reference namelist (in \path{CONFIG/SHARED/namelist_ref}) is read first. This file contains all the namelist variables which are initialised to default values  
+\item A configuration namelist (in \path{CONFIG/CFG_NAME/EXP00/namelist_cfg}) is read aferwards. This file contains only the namelist variables which are changed from default values, and overwrites those.
+\end{enumerate}
+A template can be found in \path{NEMO/OPA_SRC/module.example}.
+The effective namelist, taken in account during the run, is stored at execution time in an output\_namelist\_dyn (or \_ice or \_top) file.
+ \vspace{1cm}
+
+%%gm  end
+
+Model outputs management and specific online diagnostics are described in \autoref{chap:DIA}.
+The diagnostics includes the output of all the tendencies of the momentum and tracers equations, 
+the output of tracers tendencies averaged over the time evolving mixed layer, the output of 
+the tendencies of the barotropic vorticity equation, the computation of on-line floats trajectories... 
+\autoref{chap:OBS} describes a tool which reads in observation files (profile temperature 
+and salinity, sea surface temperature, sea level anomaly and sea ice concentration) 
+and calculates an interpolated model equivalent value at the observation location 
+and nearest model timestep. Originally developed of data assimilation, it is a fantastic 
+tool for model and data comparison. \autoref{chap:ASM} describes how increments 
+produced by data assimilation may be applied to the model equations.
+Finally, \autoref{chap:CFG} provides a brief introduction to the pre-defined model 
+configurations (water column model, ORCA and GYRE families of configurations).
+
+The model is implemented in \textsc{Fortran 90}, with preprocessing (C-pre-processor). 
+It runs under UNIX. It is optimized for vector computers and parallelised by domain  
+decomposition with MPI. All input and output is done in NetCDF (Network Common Data 
+Format) with a optional direct access format for output. To ensure the clarity and 
+readability of the code it is necessary to follow coding rules. The coding rules for OPA 
+include conventions for naming variables, with different starting letters for different types 
+of variables (real, integer, parameter\ldots). Those rules are briefly presented in 
+\autoref{apdx:D} and a more complete document is available on the \NEMO web site.
+
+The model is organized with a high internal modularity based on physics. For example, 
+each trend ($i.e.$, a term in the RHS of the prognostic equation) for momentum and 
+tracers is computed in a dedicated module.  To make it easier for the user to find his way 
+around the code, the module names follow a three-letter rule. For example, \mdl{traldf} 
+is a module related to the TRAcers equation, computing the Lateral DiFfussion. 
+%The complete list of module names is presented in \autoref{apdx:D}.      %====>>>> to be done !
+Furthermore, modules are organized in a few directories that correspond to their category, 
+as indicated by the first three letters of their name (\autoref{tab:chap}).
+
+The manual mirrors the organization of the model. 
+After the presentation of the continuous equations (\autoref{chap:PE}), the following chapters 
+refer to specific terms of the equations each associated with a group of modules (\autoref{tab:chap}).
+
+
+%--------------------------------------------------TABLE--------------------------------------------------
+\begin{table}[!t]	
+%\begin{center} \begin{tabular}{|p{143pt}|l|l|}	\hline
+\caption{ \protect\label{tab:chap}   Organization of Chapters mimicking the one of the model directories. }
+\begin{center} 	\begin{tabular}{|l|l|l|}	\hline
+\autoref{chap:STP}	& -   		        & model time STePping environment \\		\hline
+\autoref{chap:DOM}	& DOM		& model DOMain \\		\hline
+\autoref{chap:TRA}	& TRA		& TRAcer equations (potential temperature and salinity) \\   \hline
+\autoref{chap:DYN}	& DYN		& DYNamic equations (momentum) \\		\hline
+\autoref{chap:SBC} 	& SBC		& Surface Boundary Conditions \\			\hline
+\autoref{chap:LBC}	& LBC		& Lateral Boundary Conditions (also OBC and BDY)  \\ 		\hline
+\autoref{chap:LDF}	& LDF		& Lateral DiFfusion (parameterisations) \\	\hline
+\autoref{chap:ZDF}	& ZDF		& vertical (Z) DiFfusion (parameterisations)  \\		\hline
+\autoref{chap:DIA}	& DIA		& I/O and DIAgnostics (also IOM, FLO and TRD) \\		\hline
+\autoref{chap:OBS}	& OBS		& OBServation and model comparison  \\		\hline
+\autoref{chap:ASM}	& ASM		& ASsiMilation increment  \\		\hline
+\autoref{chap:MISC}	& SOL		& Miscellaneous  topics (including solvers)  \\       \hline
+\autoref{chap:CFG}	&  - 			& predefined configurations (including C1D) \\		\hline
+\end{tabular} 	
+\end{center}	\end{table}
+%--------------------------------------------------------------------------------------------------------------
+
+
+\subsubsection{Changes between releases}
+NEMO/OPA, like all research tools, is in perpetual evolution. The present document describes 
+the OPA version include in the release 3.4 of NEMO.  This release differs significantly
+from version 8, documented in \citet{Madec1998}.\\
+
+$\bullet$ The main modifications from OPA v8 and NEMO/OPA v3.2 are :\\
+\begin{enumerate}
+\item transition to full native \textsc{Fortran} 90, deep code restructuring and drastic 
+reduction of CPP keys; 
+\item introduction of partial step representation of bottom topography \citep{Barnier_al_OD06, Le_Sommer_al_OM09, Penduff_al_OS07}; 
+\item partial reactivation of a terrain-following vertical coordinate ($s$- and hybrid $s$-$z$) 
+with the addition of several options for pressure gradient computation \footnote{Partial 
+support of $s$-coordinate: there is presently no support for neutral physics in $s$-
+coordinate and for the new options for horizontal pressure gradient computation with 
+a non-linear equation of state.}; 
+\item more choices for the treatment of the free surface: full explicit, split-explicit or filtered 
+schemes, and suppression of the rigid-lid option;
+\item non linear free surface associated with the rescaled height coordinate  
+\textit{z*} or  \textit{s}; 
+\item additional schemes for vector and flux forms of the momentum  advection; 
+\item additional advection schemes for tracers; 
+\item implementation of the AGRIF package (Adaptative Grid Refinement in \textsc{Fortran}) \citep{Debreu_al_CG2008}; 
+\item online diagnostics : tracers trend in the mixed layer and vorticity balance;
+\item rewriting of the I/O management with the use of an I/O server; 
+\item generalized ocean-ice-atmosphere-CO2 coupling interface, interfaced with OASIS 3 coupler ;
+\item surface module (SBC) that simplify the way the ocean is forced and include two
+bulk formulea (CLIO and CORE) and which includes an on-the-fly interpolation of input forcing fields ;
+\item RGB light penetration and optional use of ocean color 
+\item major changes in the TKE schemes: it now includes a Langmuir cell parameterization  \citep{Axell_JGR02}, 
+the \citet{Mellor_Blumberg_JPO04} surface wave breaking parameterization, and has a time discretization 
+which is energetically consistent with the ocean model equations \citep{Burchard_OM02, Marsaleix_al_OM08}; 
+\item tidal mixing parametrisation (bottom intensification) + Indonesian specific tidal mixing \citep{Koch-Larrouy_al_GRL07}; 
+\item introduction of LIM-3, the new Louvain-la-Neuve sea-ice model (C-grid rheology and
+new thermodynamics including bulk ice salinity) \citep{Vancoppenolle_al_OM09a, Vancoppenolle_al_OM09b}
+\end{enumerate}
+
+ \vspace{1cm}
+$\bullet$ The main modifications from NEMO/OPA v3.2 and  v3.3 are :\\
+\begin{enumerate}
+\item introduction of a modified leapfrog-Asselin filter time stepping scheme \citep{Leclair_Madec_OM09}; 
+\item additional scheme for iso-neutral mixing \citep{Griffies_al_JPO98}, although it is still a "work in progress"; 
+\item a rewriting of the bottom boundary layer scheme, following \citet{Campin_Goosse_Tel99}; 
+\item addition of a Generic Length Scale vertical mixing scheme, following \citet{Umlauf_Burchard_JMS03}; 
+\item addition of the atmospheric pressure as an external forcing on both ocean and sea-ice dynamics; 
+\item addition of a diurnal cycle on solar radiation \citep{Bernie_al_CD07}; 
+\item river runoffs added through a non-zero depth, and having its own temperature and salinity; 
+\item CORE II normal year forcing set as the default forcing of ORCA2-LIM configuration ; 
+\item generalisation of the use of \mdl{fldread} for all input fields (ocean climatology, sea-ice damping...) ; 
+\item addition of an on-line observation and model comparison (thanks to NEMOVAR project); 
+\item optional application of an assimilation increment (thanks to NEMOVAR project); 
+\item coupling interface adjusted for WRF atmospheric model; 
+\item C-grid ice rheology now available fro both LIM-2 and LIM-3 \citep{Bouillon_al_OM09}; 
+\item LIM-3 ice-ocean momentum coupling applied to LIM-2 ; 
+\item a deep re-writting and simplification of the off-line tracer component (OFF\_SRC) ; 
+\item the merge of passive and active advection and diffusion modules ;
+\item  Use of the Flexible Configuration Manager (FCM) to build configurations, generate the Makefile and produce the executable ;
+\item Linear-tangent and Adjoint component (TAM) added, phased with v3.0
+\end{enumerate}
+ \vspace{1cm}
+In addition, several minor modifications in the coding have been introduced with the constant 
+concern of improving the model performance. 
+
+ \vspace{1cm}
+$\bullet$ The main modifications from NEMO/OPA v3.3 and  v3.4 are :\\
+\begin{enumerate}
+\item finalisation of above iso-neutral mixing \citep{Griffies_al_JPO98}"; 
+\item "Neptune effect" parametrisation;
+\item horizontal pressure gradient suitable for s-coordinate; 
+\item semi-implicit bottom friction;
+\item finalisation of the merge of passive and active tracers advection-diffusion modules; 
+\item a new bulk formulae (so-called MFS);
+\item use fldread for the off-line tracer component (OFF\_SRC) ; 
+\item use MPI point to point communications  for north fold;
+\item diagnostic of transport ; 
+\end{enumerate}
+
+
+ \vspace{1cm}
+$\bullet$ The main modifications from NEMO/OPA v3.4 and  v3.6 are :\\
+\begin{enumerate}
+ \item ... ; 
+\end{enumerate}
+
+
+ \vspace{1cm}
+$\bullet$ The main modifications from NEMO/OPA v3.6 and  v4.0 are :\\
+\begin{enumerate}
+\item new definition of configurations ;
+\item bulk formulation ;
+\item ... ; 
+\end{enumerate}
+
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/Thermal_properties.pro
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/Thermal_properties.pro	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/Thermal_properties.pro	(revision 10321)
@@ -0,0 +1,269 @@
+;
+;------------------------------------------------------------------------------
+;
+; Plot LIM thermal properties
+; 
+;------------------------------------------------------------------------------
+
+; Model parameters
+; Sample experiments
+N_spl = 3 & Ts_spl = FLTARR(N_spl)
+Ts_spl[*] = [ -15., -10., -5. ] & Tw_spl = 2.
+colors = [ 50., 100., 150. ]
+
+;
+;==============================================================================
+; 1) User parameters
+;==============================================================================
+;
+
+out_dir=''
+file_out   = 'Thermal_properties'
+
+numplot_x = 2       ; number of horizontal plots
+numplot_y = 2       ; number of vertical plots
+ct = 13             ; colortable
+cs = 1.0            ; size of fonts on plots (1=normal)
+th = 2.             ; thickness of curves
+device = 'PS'       ; 'PS' or 'X'
+
+;
+;==============================================================================
+; 2) Initialize graphics
+;==============================================================================
+;
+
+dx = 6 
+dy = 6.
+figuresize_x = numplot_x * dx; figure size on x direction
+figuresize_y = numplot_y * dy; figure size on y direction
+SET_PLOT, DEVICE
+;!P.FONT=1
+TVLCT, [0,255,0,0], [0,0,255,0], [0,0,0,255]
+IF ( device EQ 'PS' ) THEN BEGIN
+;   DEVICE, /COLOR, /LANDSCAPE, filename=out_dir+file_out+'.ps', $
+;           XSIZE=figuresize_x,YSIZE=figuresize_y,FONT_SIZE=12.0, SET_FONT='Helvetica', BITS = 16
+   DEVICE, /COLOR, /LANDSCAPE, filename=out_dir+file_out+'.ps', $
+           XSIZE=figuresize_x,YSIZE=figuresize_y,FONT_SIZE=9.0
+ENDIF
+
+IF ( device EQ 'X' ) THEN BEGIN
+   xsize = 1200
+   ysize = 800
+   colorkey = 'rd'
+   init_graphics_x, xsize, ysize, colorkey
+ENDIF
+
+!P.MULTI=[0,numplot_x,numplot_y]
+!X.MARGIN   = [6,3]
+!Y.MARGIN   = [4,3]
+
+;==============================================================================
+; 3) Computations and plots
+;==============================================================================
+
+; arrays
+N_T = 200
+N_S = 3
+miss_val = 9.99e32
+
+;--- Physical constants
+c0 = 2067.d0
+cw = 3991.d0
+L  = 334000.d0
+mu = 0.054d0
+rhoi = 917.d0
+rhow = 1026.d0
+rhos = 330.d0
+
+Sw = 34.d0
+
+beta1 = 0.09; pringle coefficients
+beta2 = 0.011;
+
+;--- Ice salinity
+;S = ( rhoi - rhos ) / rhoi * Sw
+S = FLTARR(N_S)
+Smin = 5.   
+Smax = 15.
+dS = ( Smax - Smin ) / FLOAT(N_S-1)
+S[0:N_S-1] = Smin + FINDGEN(N_S) * dS
+
+Tf = -mu * S
+
+;--- Temperatures
+T = FLTARR(N_T)
+Tmin = -20.
+Tf   = -mu * Smax
+Tmax = 0. 
+dT = ( Tmax - Tmin ) / FLOAT(N_T-1)
+T[0:N_T-1] = Tmin + FINDGEN(N_T) * dT
+
+;--- Grids
+S_grid = FLTARR(N_S,N_T)
+T_grid = FLTARR(N_S,N_T)
+
+FOR j = 0, N_T - 1 DO BEGIN
+   S_grid(0:N_S-1,j) = S(0:N_S-1)
+ENDFOR
+
+FOR i = 0, N_S - 1 DO BEGIN
+   T_grid(i,0:N_T-1) = T(0:N_T-1)
+ENDFOR
+
+;--- Brine fraction
+phi = -mu * S_grid / T_grid
+
+;--- specific enthalpy
+q_i = c0 * ( T_grid + mu * S_grid ) - L * ( 1 + mu * S_grid / T_grid ) - cw*mu*S_grid
+
+;--- thermal conductivity (pringle)
+kpri = 2.11 + beta1 * S_grid / T_grid - beta2 * T_grid; 
+
+;--- specific heat
+cp = c0 + L*mu*S_grid/(T_grid*T_grid)
+
+;--- PLOTS
+!P.MULTI=[0, numplot_x, numplot_y]
+LOADCT, 13
+
+PLOT, [Tmin, Tmax], [0., 50.], /NODATA, XTITLE='T (C)', YTITLE='phi (%)', CHARSIZE = cs
+FOR i = 0, N_S - 1 DO BEGIN
+   zaddr = where(phi LT 100) 
+   OPLOT, T_grid(i,zaddr), phi(i,zaddr)*100., thick = th, color = i* 50
+ENDFOR
+
+PLOT, [Tmin, Tmax], [-4., 0.], /NODATA, XTITLE='T (C)', YTITLE='q_m (10^5 J/kg)', CHARSIZE = cs
+FOR i = 0, N_S - 1 DO BEGIN
+   zaddr = where(phi LT 100) 
+   OPLOT, T_grid(i,zaddr), q_i(i,zaddr)/1.0e5, thick = th, color = i* 50
+ENDFOR
+
+PLOT, [Tmin, Tmax], [0., 3.], /NODATA, XTITLE='T (C)', YTITLE='k_i (W/m/K)', CHARSIZE = cs
+FOR i = 0, N_S - 1 DO BEGIN
+   zaddr = where(phi LT 100) 
+   OPLOT, T_grid(i,zaddr), kpri(i,zaddr), thick = th, color = i* 50
+ENDFOR
+
+PLOT, [Tmin, Tmax], [0., 20.], /NODATA, XTITLE='T (C)', YTITLE='c_i (10^3 J/kg/K)', CHARSIZE = cs
+FOR i = 0, N_S - 1 DO BEGIN
+   zaddr = where(phi LT 100) 
+   OPLOT, T_grid(i,zaddr), cp(i,zaddr)/1000., thick = th, color = i* 50
+ENDFOR
+
+
+;T[0:N_T-1] = FINDGEN(N_T) * dT + Tmin
+;dT = ( Tmax - Tf) / FLOAT(N/2-1)
+;T[N/2:N-1] = FINDGEN(N/2) * dT + Tf
+
+;;PLOT, T, TITLE = "T", CHARSIZE = cs
+;
+;; Specific heat
+;ci = FLTARR(N) & ci(*) = miss_val
+;cis = FLTARR(N) & cis(*) = miss_val
+;ci(0:N/2) = c0 + L*mu*S/T(0:N/2)/T(0:N/2)
+;cis(0:N/2) = mu*(c0 - L/T(0:N/2))
+;;PLOT, T(0:N/2), ci(0:N/2)/L, CHARSIZE = cs
+;;OPLOT, T(0:N/2), cis(0:N/2)/L, LINESTYLE = 1
+;
+;;--- Brine volume
+;e_i = FLTARR(N) & e_i(*) = 1.
+;i_addr = FINDGEN(N/2+1)
+;e_i(i_addr) = -mu * S / T(i_addr)
+;PLOT, T, e_i, CHARSIZE = cs, TITLE = "e"
+;OPLOT, T, REPLICATE(0.5, N), linestyle = 1
+;T_50 = -mu * S / 0.50 ; temperature at which brine volume is 50%
+;
+;; Notz (2005), Phd thesis, page 44
+;i_addr = WHERE(T LT Tf)
+;Sbr = - 21.4 * T(i_addr) - 0.886 * T(i_addr) * T(i_addr) - 0.0170 * T(i_addr) * T(i_addr) * T(i_addr)
+;zrS = S / Sbr(i_addr)
+;beta_ocs = 0.81
+;
+;zrhoi      = 916.8 - 0.1403 * T(i_addr)              ; pure ice density Pounder(1965)
+;zrhol      = rhow + beta_ocs * ( Sbr(i_addr) - Sw )
+;zrR        = zrhoi / zrhol
+;znum       = 1 - zrS
+;zden       = 1 + zrS * ( zrR - 1 )
+;e_i2 = FLTARR(N) & e_i2(*) = 1.
+;e_i2(i_addr) =  1. - znum / zden
+;;OPLOT, T, e_i2, linestyle = 3
+;
+;;OPLOT, [ T_50, T_50], [ 0., 1.], linestyle = 1
+;
+;;--- Enthalpies
+;Ei = FLTARR(N) & Ei(*) = miss_val
+;Ei2= FLTARR(N) & Ei2(*) = miss_val
+;Es = FLTARR(N) & Es(*) = miss_val
+;Es_wgt = FLTARR(N) & Es(*) = miss_val
+;Ew = FLTARR(N) & Ew(*) = miss_val
+;
+;i_addr = WHERE( T LE 0. )
+;Es(i_addr) = c0 * T(i_addr) - L
+;Es_wgt(i_addr) = Es(i_addr) * rhos / rhoi
+;i_addr = WHERE( T GT 0. )
+;Es(i_addr) = cw * T(i_addr)
+;Es_wgt(i_addr) = Es(i_addr) * ( rhoi - rhos ) / rhoi
+;
+;i_addr = WHERE( T GE Tf )
+;Ew(i_addr) = cw * T(i_addr)
+;i_addr = FINDGEN(N/2+1)
+;
+;Ei(i_addr) = c0 * ( T(i_addr) + mu * S ) - L * ( 1 + mu * S / T(i_addr) ) - cw*mu*S
+;Ei2(i_addr) = - ( 1 - e_i(i_addr) ) * L
+;
+;Emax = MAX(Ew(WHERE(Ew NE miss_val)))
+;
+;PLOT, [Tmin, Tmax], [ MIN(Ei)/1000., Emax/1000. ], /NODATA, TITLE = "Enthalpy", CHARSIZE = cs, XTITLE = "degC", YTITLE = "kJ/kg", YMINOR = 2
+;OPLOT, T, Ei/1000., MAX=0., THICK = 3.;, solid black
+;OPLOT, T, Ei2/1000., MAX=0., COLOR = 150, THICK = 3.; solid grey
+;;OPLOT, T, Es/1000., LINESTYLE = 1, THICK = 3.
+;OPLOT, T, Es_wgt/1000., COLOR = 100, THICK = 3
+;i_addr = WHERE( T GE 0. )
+;OPLOT, T(i_addr), Es_wgt(i_addr)/1000., COLOR = 200, THICK = 3
+;;OPLOT, T, Ew/1000., MAX=Emax/1000., LINESTYLE = 0, THICK = 3.
+;OPLOT, [ T_50, T_50], [ -400., 100.], COLOR = 100
+;OPLOT, [ Tmin, Tmax], [0., 0.], COLOR = 100
+;
+;;--- Sample experiment
+;Es_spl = c0 * Ts_spl - L
+;Ew_spl = cw * Tw_spl
+;
+;LOADCT, ct
+;FOR i = 0, N_spl - 1 DO BEGIN
+;   OPLOT, [ Ts_spl(i) ], [ rhos / rhoi * Es_spl(i) ]/1000., PSYM = 1, SYMSIZE = 2, THICK = 3, COLOR = COLORS(i)
+;ENDFOR
+;LOADCT, 0
+;OPLOT, [ Tw_spl ], [ (rhoi - rhos) / rhoi * Ew_spl ]/1000., PSYM = 1, SYMSIZE = 2, THICK = 3
+;
+;Ei_spl = Es_spl * rhos / rhoi + Ew_spl * ( rhoi - rhos ) / rhoi
+;
+;; Retrieve T
+;zA = ( L *( rhos/rhoi ) - (rhos/rhoi) * c0 * Ts_spl + (rhos-rhoi)/rhoi * cw * Tw_spl ) * rhoi
+;
+;aaa = c0
+;bbb = mu * S * ( c0 - cw ) - L + zA / rhoi
+;ccc = - L * mu * S
+;
+;discr = SQRT ( bbb * bbb - 4 * aaa * ccc )
+;
+;Ti_spl = ( - bbb - discr ) / 2.0 / aaa
+;
+;Ei_test = c0 * ( Ti_spl + mu * S ) - L * ( 1 + mu * S / Ti_spl ) - cw*mu*S
+;PRINT, "Ei_test : ", Ei_test
+;PRINT, "Ei_spl  : ", Ei_spl
+;
+;; Retrieve brine volume
+;e_i_spl = -mu*S/Ti_spl
+;PRINT, "e_i_spl = ", e_i_spl
+;
+;LOADCT, ct
+;FOR i = 0, N_spl - 1 DO BEGIN
+;   OPLOT, [ Ti_spl(i) ], [ Ei_spl(i) ]/1000., PSYM = 1, SYMSIZE = 2, COLOR = COLORS(i), THICK = 3
+;ENDFOR
+;LOADCT, 0
+
+;--------------------------------------------------------------------------------------------------
+DEVICE, /CLOSE
+SET_PLOT, 'X'
+END
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_cloud_correction.m
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_cloud_correction.m	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_cloud_correction.m	(revision 10321)
@@ -0,0 +1,51 @@
+clear all; close all;
+
+% Script to plot the cloud fraction dependency of albedo correction
+
+%------------------
+% Sea Ice
+%------------------
+
+% overcast albedo
+alpha_os = 0:0.001:1.;
+
+% SI3 correction
+f = ( -0.1010 * alpha_os.^2 + 0.1933 * alpha_os - 0.0148 );
+
+% clear sky sea ice albedo
+alpha_cs = alpha_os - f;
+
+% Grenfell and Perovich, Table 3 data
+alpha_GP04 = [ 0.114 0.151 0.141 0.266 0.367 0.309 0.332 0.492 0.678 0.928 ];
+f_GP04     = [ -0.010 -0.022 0.012 0.027 0.020 0.036 0.037 0.056 0.071 0.077 ];
+
+%--------------
+% Ocean
+%--------------
+alpha_oce_cs = 0.05 / ( 1.1 * 0.40^1.4 + 0.15 ) % --- Briegleb and Ramanathan 1972
+alpha_oce_os = 0.06 %--- Payne 1972
+f_oce = alpha_oce_os - alpha_oce_cs
+
+%--------------
+% Plot
+%--------------
+plot(alpha_os,f,'k'); hold on
+zaddr = find( ( alpha_os >= alpha_GP04(3)  )   & ...
+              ( alpha_os <= alpha_GP04(10) ) );
+plot(alpha_os(zaddr),f(zaddr),'k', 'LineWidth', 3)
+plot(alpha_GP04(3:10),f_GP04(3:10),'ksq','MarkerFaceColor', 'k')
+plot(alpha_GP04(5),f_GP04(5),'rsq','MarkerFaceColor','r')
+text(alpha_GP04(5)+0.02,f_GP04(5),'dirty ice')
+plot(alpha_GP04(1:2),f_GP04(1:2),'rsq','MarkerFaceColor','r')
+text(alpha_GP04(1)+0.02,f_GP04(1),'wet tundra')
+text(alpha_GP04(2)+0.02,f_GP04(2),'dry tundra')
+plot(alpha_oce_os,f_oce,'bo','MarkerFaceColor', 'b')
+text(alpha_oce_os+0.02,f_oce,'ocean')
+plot( [ alpha_GP04(3) alpha_GP04(3) ], [ -0.06 0.08 ], 'k--' )
+plot( [ alpha_GP04(10) alpha_GP04(10) ], [ -0.06 0.08 ], 'k--' )
+
+xlabel('\alpha^{os}')
+ylabel('\alpha^{os}-\alpha^{cs}')
+
+set(gca,'fontsize', 16)
+set(gca, 'FontName', 'Helvetica LT Std')
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_hi.m
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_hi.m	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/albedo_hi.m	(revision 10321)
@@ -0,0 +1,71 @@
+clear all, close all
+
+% plots SI3 albedo dependence versus ice thickness
+
+z1_href_pnd = 1. / 0.05
+z1_c1 = 1. / ( log(1.5) - log(0.05) );
+z1_c2 = 1. / 0.05;
+z1_c3 = 1. / 0.02
+z1_c4 = 1. / 0.03
+
+rn_alb_idry = 0.60;
+rn_alb_imlt = 0.50;
+rn_alb_sdry = 0.85
+rn_alb_smlt = 0.75
+rn_alb_oce  = 0.06;
+rn_alb_dpnd = 0.27;
+
+h_i = 0:0.001:3;
+
+%--- Bare ice albedo (for hi > 150cm)
+zalb_ice    = h_i;
+zalb_ice(:) = rn_alb_idry;
+
+%--- Bare ice albedo (for hi < 150cm)
+zaddr = find( ( 0.05 < h_i ) & ( h_i <= 1.5 ) ); % 5cm < hi < 150cm
+zalb_ice(zaddr) = zalb_ice(zaddr) + ( 0.18 - zalb_ice(zaddr) ) * z1_c1 .* ( log(1.5) - log(h_i(zaddr)) );
+zaddr = find( h_i <= 0.05 );
+zalb_ice(zaddr) = rn_alb_oce  + ( 0.18 - rn_alb_oce ) * z1_c2 * h_i(zaddr);
+
+figure; 
+
+
+subplot(1,3,1)
+
+plot(h_i,zalb_ice,'k','LineWidth', 3)
+xlabel('h_i(m)')
+ylabel('\alpha')
+ylim([0.1 0.9])
+set(gca,'fontsize', 16)
+set(gca, 'FontName', 'Helvetica LT Std')
+
+
+
+%--- Snow covered albedo
+
+h_s = 0:0.001:0.6;
+zalb_ice    = 0.6
+zalb_snw    = rn_alb_sdry - ( rn_alb_sdry - zalb_ice ) * exp( -h_s * z1_c3 )
+
+subplot(1,3,2)
+plot(h_s,zalb_snw,'k','LineWidth', 3)
+xlabel('h_s(m)')
+ylabel('\alpha')
+ylim([0.1 0.9])
+set(gca,'fontsize', 16)
+set(gca, 'FontName', 'Helvetica LT Std')
+
+%--- Ponded ice albedo
+zalb_ice    = 0.5
+h_pnd = 0:0.001:0.6;
+zalb_pnd = rn_alb_dpnd - ( rn_alb_dpnd - zalb_ice ) * exp( -h_pnd * z1_href_pnd )
+
+subplot(1,3,3)
+plot(h_pnd,zalb_pnd,'k','LineWidth', 3)
+xlabel('h_{pnd}(m)')
+ylabel('\alpha')
+ylim([0.1 0.9])
+set(gca,'fontsize', 16)
+set(gca, 'FontName', 'Helvetica LT Std')
+
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/ice_cats.pro
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/ice_cats.pro	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/Figures/scripts/ice_cats.pro	(revision 10321)
@@ -0,0 +1,157 @@
+
+;
+;==============================================================================
+; 1) User parameters
+;==============================================================================
+;
+
+out_dir=''
+file_out   = 'ThicknessSpace'
+
+numplot_x = 1       ; number of horizontal plots
+numplot_y = 1       ; number of vertical plots
+ct = 13             ; colortable
+cs = 2.0            ; size of fonts on plots (1=normal)
+th = 2.             ; thickness of curves
+device = 'PS'       ; 'PS' or 'X'
+
+;
+;==============================================================================
+; 2) Initialize graphics
+;==============================================================================
+;
+
+dx = 12.
+dy = 8.
+figuresize_x = numplot_x * dx; figure size on x direction
+figuresize_y = numplot_y * dy; figure size on y direction
+SET_PLOT, DEVICE
+;!P.FONT=1
+TVLCT, [0,255,0,0], [0,0,255,0], [0,0,0,255]
+IF ( device EQ 'PS' ) THEN BEGIN
+;   DEVICE, /COLOR, /LANDSCAPE, filename=out_dir+file_out+'.ps', $
+;           XSIZE=figuresize_x,YSIZE=figuresize_y,FONT_SIZE=12.0, SET_FONT='Helvetica', BITS = 16
+   DEVICE, /COLOR, /LANDSCAPE, filename=out_dir+file_out+'.ps', $
+           XSIZE=figuresize_x,YSIZE=figuresize_y,FONT_SIZE=9.0
+ENDIF
+
+IF ( device EQ 'X' ) THEN BEGIN
+   xsize = 1200
+   ysize = 800
+   colorkey = 'rd'
+   init_graphics_x, xsize, ysize, colorkey
+ENDIF
+
+!P.MULTI=[0,numplot_x,numplot_y]
+!X.MARGIN   = [7,3]
+!Y.MARGIN   = [4,3]
+
+;
+;==============================================================================
+; 2) Initialize graphics
+;==============================================================================
+;
+
+jpl = 5
+jpl1 = 10
+
+;-----------------------
+; original CICE version
+;-----------------------
+
+hi_max_cice_5 = FLTARR(jpl+1)
+hi_max_cice_5(0) = 0
+zc1 =  3. / FLOAT(jpl)
+zc2 = 10. * zc1 
+zc3 =  3.
+
+FOR jl = 1, jpl  DO BEGIN
+   zx1 = FLOAT( jl-1 ) / FLOAT( jpl )
+   hi_max_cice_5(jl) = hi_max_cice_5(jl-1) + zc1 + zc2 * (1. + TANH( zc3 * (zx1 - 1. ) ) ) 
+ENDFOR
+
+hi_max_cice_10 = FLTARR(jpl1+1)
+hi_max_cice_10(0) = 0
+zc1 =  3. / FLOAT(jpl1)
+zc2 = 10. * zc1 
+zc3 =  3.
+
+FOR jl = 1, jpl1  DO BEGIN
+   zx1 = FLOAT( jl-1 ) / FLOAT( jpl1 )
+   hi_max_cice_10(jl) = hi_max_cice_10(jl-1) + zc1 + zc2 * (1. + TANH( zc3 * (zx1 - 1. ) ) ) 
+ENDFOR
+
+;-------------------
+; LIM3 distribution
+;-------------------
+alpha = 1./20.
+
+; 5 categories, Arctic ice
+hmean = 2.5
+hL = 3.*hmean
+
+hi_max_1 = FLTARR(jpl + 1)
+hi_max_1(0) = 0.
+
+FOR jl = 1, jpl DO BEGIN
+   znum = jpl * ( hL+1 )^alpha
+   zden = ( jpl - jl ) * ( hL+1 )^alpha + jl
+   hi_max_1(jl) = ( znum / zden )^(1./alpha) - 1
+ENDFOR
+
+; 10 categories, Arctic ice
+hi_max_2 = FLTARR(jpl1 + 1)
+hi_max_2(0) = 0.
+FOR jl = 1, jpl1 DO BEGIN
+   znum = jpl1 * ( hL+1 )^alpha
+   zden = ( jpl1 - jl ) * ( hL+1 )^alpha + jl
+   hi_max_2(jl) = ( znum / zden )^(1./alpha) - 1
+ENDFOR
+
+; 5 categories, Spitzberg
+hmean = 1.0
+hL = 3.*hmean
+
+hi_max_3 = FLTARR(jpl + 1)
+hi_max_3(0) = 0.
+
+FOR jl = 1, jpl DO BEGIN
+   znum = jpl * ( hL+1 )^alpha
+   zden = ( jpl - jl ) * ( hL+1 )^alpha + jl
+   hi_max_3(jl) = ( znum / zden )^(1./alpha) - 1
+ENDFOR
+
+; 10 categories, Spitzberg
+hmean = 1.0
+hi_max_4 = FLTARR(jpl1 + 1)
+hi_max_4(0) = 0.
+
+FOR jl = 1, jpl1 DO BEGIN
+   znum = jpl1 * ( hL+1 )^alpha
+   zden = ( jpl1 - jl ) * ( hL+1 )^alpha + jl
+   hi_max_4(jl) = ( znum / zden )^(1./alpha) - 1
+ENDFOR
+
+!P.MULTI = [ 0, numplot_x, numplot_y ]
+
+PLOT, [0.1, 10.], [0., 7.], /NODATA, charsize = cs, XSTYLE = 1, YSTYLE = 1
+OPLOT, hi_max_cice_5, FINDGEN(jpl+1)*0.+1, psym = 4, symsize = 1, thick = 2
+OPLOT, hi_max_cice_10, FINDGEN(jpl1+1)*0.+2, psym = 4, symsize = 1, thick = 2, color =150
+OPLOT, hi_max_1, FINDGEN(jpl+1)*0.+3   , psym = 1, symsize = 1, thick = 2, color = 0
+OPLOT, hi_max_2, FINDGEN(jpl1+1)*0.+4  , psym = 1, symsize = 1, thick = 2, color = 150
+OPLOT, hi_max_3, FINDGEN(jpl+1)*0.+5   , psym = 2, symsize = 1, thick = 2, color = 0
+OPLOT, hi_max_4, FINDGEN(jpl1+1)*0.+6   , psym = 2, symsize = 1, thick = 2, color = 150
+
+PLOT, FINDGEN(jpl+1)/jpl, hi_max_cice_5, psym = 4, symsize = 1, thick = 2, charsize = cs
+OPLOT, FINDGEN(jpl1+1)/jpl1, hi_max_cice_10, psym = 4, symsize = 1, thick = 2, color = 150
+OPLOT, FINDGEN(jpl+1)/jpl, hi_max_1,   psym = 1, symsize = 1, thick = 2
+OPLOT, FINDGEN(jpl1+1)/jpl1, hi_max_2, psym = 1, symsize = 1, thick = 2, color = 150
+OPLOT, FINDGEN(jpl+1)/jpl, hi_max_3,   psym = 2, symsize = 1, thick = 2 
+OPLOT, FINDGEN(jpl1+1)/jpl1, hi_max_4, psym = 2, symsize = 1, thick = 2, color = 150
+
+
+DEVICE, /CLOSE
+SET_PLOT, 'X'
+!P.MULTI=[0,1,1]
+END
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namalb
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namalb	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namalb	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namalb         !   albedo parameters
+!------------------------------------------------------------------------------
+   !                                  !                          !  obs range (cloud-sky)
+   rn_alb_sdry      =   0.85          !  dry snow albedo         :  0.85 -- 0.87
+   rn_alb_smlt      =   0.75          !  melting snow albedo     :  0.72 -- 0.82
+   rn_alb_idry      =   0.60          !  dry ice albedo          :  0.54 -- 0.65
+   rn_alb_imlt      =   0.50          !  bare puddled ice albedo :  0.49 -- 0.58
+   rn_alb_dpnd      =   0.27          !  ponded ice albedo       :  0.10 -- 0.30 
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdia
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdia	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdia	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namdia         !   Diagnostics
+!------------------------------------------------------------------------------
+   ln_icediachk     = .false.         !  check online the heat, mass & salt budgets (T) or not (F)
+   ln_icediahsb     = .false.         !  output the heat, mass & salt budgets (T) or not (F)
+   ln_icectl        = .false.         !  ice points output for debug (T or F)
+   iiceprt          =  10             !  i-index for debug
+   jiceprt          =  10             !  j-index for debug
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn	(revision 10321)
@@ -0,0 +1,17 @@
+!------------------------------------------------------------------------------
+&namdyn         !   Ice dynamics
+!------------------------------------------------------------------------------
+   ln_dynFULL       = .true.          !  dyn.: full ice dynamics               (rheology + advection + ridging/rafting + correction)
+   ln_dynRHGADV     = .false.         !  dyn.: no ridge/raft & no corrections  (rheology + advection)
+   ln_dynADV        = .false.         !  dyn.: only advection w prescribed vel.(rn_uvice + advection)
+      rn_uice       =   0.00001       !        prescribed ice u-velocity
+      rn_vice       =   0.            !        prescribed ice v-velocity
+   rn_ishlat        =   2.            !  free slip (0) ; partial slip (0-2) ; no slip (2) ; strong slip (>2)
+   ln_landfast      = .false.         !  landfast ice parameterization (T or F)                           
+      rn_gamma      =   0.15          !     fraction of ocean depth that ice must reach to initiate landfast
+                                      !        recommended range: [0.1 ; 0.25]
+      rn_icebfr     =  10.            !     maximum bottom stress per unit area of contact [N/m2]                 
+                                      !        a very large value ensures ice velocity=0 even with a small contact area
+                                      !        recommended range: ?? (should be greater than atm-ice stress => >0.1 N/m2)
+      rn_lfrelax    =   1.e-5         !     relaxation time scale to reach static friction [s-1]
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_adv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_adv	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_adv	(revision 10321)
@@ -0,0 +1,7 @@
+!------------------------------------------------------------------------------
+&namdyn_adv     !   Ice advection
+!------------------------------------------------------------------------------
+   ln_adv_Pra       = .false.         !  Advection scheme (Prather)
+   ln_adv_UMx       = .true.          !  Advection scheme (Ultimate-Macho)
+      nn_UMx        =   5             !     order of the scheme for UMx (1-5 ; 20=centered 2nd order)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rdgrft
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rdgrft	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rdgrft	(revision 10321)
@@ -0,0 +1,25 @@
+!------------------------------------------------------------------------------
+&namdyn_rdgrft  !   Ice ridging/rafting
+!------------------------------------------------------------------------------
+          ! -- ice_rdgrft_strength -- !
+   ln_str_H79       = .true.          !  ice strength param.: Hibler_79   => P = pstar*<h>*exp(-c_rhg*A)                      
+      rn_pstar      =   2.0e+04       !     ice strength thickness parameter [N/m2]
+      rn_crhg       =   20.0          !     ice strength conc. parameter (-)
+                   ! -- ice_rdgrft -- !
+   rn_csrdg         =   0.5           !  fraction of shearing energy contributing to ridging
+              ! -- ice_rdgrft_prep -- !
+   ln_partf_lin     = .false.         !  Linear ridging participation function (Thorndike et al, 1975)
+      rn_gstar      =   0.15          !     fractional area of thin ice being ridged 
+   ln_partf_exp     = .true.          !  Exponential ridging participation function (Lipscomb, 2007)
+      rn_astar      =   0.03          !     exponential measure of ridging ice fraction [set to 0.05 if hstar=100]
+   ln_ridging       = .true.          !  ridging activated (T) or not (F)
+      rn_hstar      =  25.0           !     determines the maximum thickness of ridged ice [m] (Hibler, 1980)
+      rn_porordg    =   0.3           !     porosity of newly ridged ice (Lepparanta et al., 1995)
+      rn_fsnwrdg    =   0.5           !     snow volume fraction that survives in ridging
+      rn_fpndrdg    =   1.0           !     pond fraction that survives in ridging (small a priori)
+   ln_rafting       = .true.          !  rafting activated (T) or not (F)
+      rn_hraft      =   0.75          !     threshold thickness for rafting [m]
+      rn_craft      =   5.0           !     squeezing coefficient used in the rafting function
+      rn_fsnwrft    =   0.5           !     snow volume fraction that survives in rafting
+      rn_fpndrft    =   1.0           !     pond fraction that survives in rafting (0.5 a priori)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rhg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rhg	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namdyn_rhg	(revision 10321)
@@ -0,0 +1,11 @@
+!------------------------------------------------------------------------------
+&namdyn_rhg     !   Ice rheology
+!------------------------------------------------------------------------------
+   ln_rhg_EVP       = .true.          !  EVP rheology
+      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
+      rn_creepl     =   2.0e-9        !     creep limit [1/s]
+      rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve          
+      nn_nevp       = 120             !     number of EVP subcycles                             
+      rn_relast     =   0.333         !     ratio of elastic timescale to ice time step: Telast = dt_ice * rn_relast 
+                                      !        advised value: 1/3 (rn_nevp=120) or 1/9 (rn_nevp=300)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namforcing
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namforcing	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namforcing	(revision 10321)
@@ -0,0 +1,13 @@
+!------------------------------------------------------------------------------
+&namforcing     !   Ice surface forcing
+!------------------------------------------------------------------------------
+   rn_cio           =   5.0e-03       !  ice-ocean drag coefficient (-)
+   rn_blow_s        =   0.66          !  mesure of snow blowing into the leads
+                                      !     = 1 => no snow blowing, < 1 => some snow blowing
+   nn_flxdist       =  -1             !  Redistribute heat flux over ice categories
+                                      !     =-1  Do nothing (needs N(cat) fluxes)
+                                      !     = 0  Average N(cat) fluxes then apply the average over the N(cat) ice
+                                      !     = 1  Average N(cat) fluxes then redistribute over the N(cat) ice using T-ice and albedo sensitivity
+                                      !     = 2  Redistribute a single flux over categories
+   nice_jules       = 0               !  Jules coupling (0=OFF, 1=EMULATED, 2=ACTIVE)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namini
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namini	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namini	(revision 10321)
@@ -0,0 +1,25 @@
+!------------------------------------------------------------------------------
+&namini         !   Ice initialization
+!------------------------------------------------------------------------------
+   ln_iceini        = .true.          !  activate ice initialization (T) or not (F)
+   ln_iceini_file   = .false.         !  netcdf file provided for initialization (T) or not (F)
+   rn_thres_sst     =   2.0           !  max delta temp. above Tfreeze with initial ice = (sst - tfreeze)
+   rn_hts_ini_n     =   0.3           !  initial real snow thickness (m), North
+   rn_hts_ini_s     =   0.3           !        "            "             South
+   rn_hti_ini_n     =   3.0           !  initial real ice thickness  (m), North
+   rn_hti_ini_s     =   1.0           !        "            "             South
+   rn_ati_ini_n     =   0.9           !  initial ice concentration   (-), North
+   rn_ati_ini_s     =   0.9           !        "            "             South
+   rn_smi_ini_n     =   6.3           !  initial ice salinity     (g/kg), North
+   rn_smi_ini_s     =   6.3           !        "            "             South
+   rn_tmi_ini_n     = 270.            !  initial ice/snw temperature (K), North
+   rn_tmi_ini_s     = 270.            !        "            "             South
+
+   sn_hti = 'Ice_initialization'    , -12 ,'hti'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_hts = 'Ice_initialization'    , -12 ,'hts'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_ati = 'Ice_initialization'    , -12 ,'ati'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_tsu = 'Ice_initialization'    , -12 ,'tsu'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_tmi = 'Ice_initialization'    , -12 ,'tmi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_smi = 'Ice_initialization'    , -12 ,'smi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   cn_dir='./'
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namitd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namitd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namitd	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namitd         !   Ice discretization
+!------------------------------------------------------------------------------
+   ln_cat_hfn       = .true.          !  ice categories are defined by a function following rn_himean**(-0.05)
+      rn_himean     =   2.0           !  expected domain-average ice thickness (m)
+   ln_cat_usr       = .false.         !  ice categories are defined by rn_catbnd below (m)
+      rn_catbnd     =   0.,0.45,1.1,2.1,3.7,6.0  
+   rn_himin         =   0.1           !  minimum ice thickness (m) used in remapping
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/nampar
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/nampar	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/nampar	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&nampar         !   Generic parameters
+!------------------------------------------------------------------------------
+   jpl              =   5             !  number of ice  categories
+   nlay_i           =   2             !  number of ice  layers
+   nlay_s           =   1             !  number of snow layers (only 1 is working)
+   nn_virtual_itd   =   0             !  virtual ITD mono-category parameterizations (1-3 => jpl = 1 only) or not (0)
+                                      !     2: activate enhanced thermal conductivity only --- temporary option
+                                      !     3: activate virtual thin ice melting only      ---  temporary option
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd	(revision 10321)
@@ -0,0 +1,8 @@
+!------------------------------------------------------------------------------
+&namthd         !   Ice thermodynamics
+!------------------------------------------------------------------------------
+   ln_icedH         = .true.          !  activate ice thickness change from growing/melting (T) or not (F)
+   ln_icedA         = .true.          !  activate lateral melting param. (T) or not (F)
+   ln_icedO         = .true.          !  activate ice growth in open-water (T) or not (F)
+   ln_icedS         = .true.          !  activate brine drainage (T) or not (F)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_da
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_da	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_da	(revision 10321)
@@ -0,0 +1,11 @@
+!------------------------------------------------------------------------------
+&namthd_da      !   Ice lateral melting
+!------------------------------------------------------------------------------
+   rn_beta          =   1.0           !  coef. beta for lateral melting param. Recommended range=[0.8-1.2]
+                                      !   => decrease = more melt and melt peaks toward higher concentration (A~0.5 for beta=1 ; A~0.8 for beta=0.2)
+                                      !      0.3 = best fit for western Fram Strait and Antarctica
+                                      !      1.4 = best fit for eastern Fram Strait      
+   rn_dmin          =   8.            !  minimum floe diameter for lateral melting param. Recommended range=[6-10]
+                                      !   => 6  vs 8m = +40% melting at the peak (A~0.5)
+                                      !      10 vs 8m = -20% melting
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_do
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_do	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_do	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namthd_do      !   Ice growth in open water
+!------------------------------------------------------------------------------
+   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_hnewice
+   ln_frazil        = .false.         !  Frazil ice parameterization (ice collection as a function of wind)
+      rn_maxfraz    =   1.0           !     maximum fraction of frazil ice collecting at the ice base
+      rn_vfraz      =   0.417         !     thresold drift speed for frazil ice collecting at the ice bottom (m/s)
+      rn_Cfraz      =   5.0           !     squeezing coefficient for frazil ice collecting at the ice bottom
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_pnd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_pnd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_pnd	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namthd_pnd     !   Melt ponds
+!------------------------------------------------------------------------------
+   ln_pnd_H12       = .false.         !  activate evolutive melt ponds (from Holland et al 2012)
+      ln_pnd_fwb    = .false.         !     melt ponds store freshwater or not
+   ln_pnd_CST       = .false.         !  activate constant melt ponds
+      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0
+      rn_hpnd       =   0.05          !     prescribed pond depth, at Tsu=0
+   ln_pnd_alb       = .false.         !  melt ponds affect albedo or not
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_sal
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_sal	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_sal	(revision 10321)
@@ -0,0 +1,15 @@
+!------------------------------------------------------------------------------
+&namthd_sal     !   Ice salinity
+!------------------------------------------------------------------------------
+   nn_icesal        =   2             !  ice salinity option
+                                      !     1: constant ice salinity (S=rn_icesal)
+                                      !     2: varying salinity parameterization S(z,t)
+                                      !     3: prescribed salinity profile S(z), Schwarzacher, 1959
+   rn_icesal        =   4.            !    (nn_icesal=1) ice salinity (g/kg)
+   rn_sal_gd        =   5.            !  restoring ice salinity, gravity drainage (g/kg)
+   rn_time_gd       =   1.73e+6       !  restoring time scale, gravity drainage  (s)
+   rn_sal_fl        =   2.            !  restoring ice salinity, flushing (g/kg)
+   rn_time_fl       =   8.64e+5       !  restoring time scale, flushing (s)
+   rn_simax         =  20.            !  maximum tolerated ice salinity (g/kg)
+   rn_simin         =   0.1           !  minimum tolerated ice salinity (g/kg)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_zdf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_zdf	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/namelists/namthd_zdf	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namthd_zdf     !   Ice heat diffusion
+!------------------------------------------------------------------------------
+   ln_zdf_BL99      = .true.          !  Heat diffusion follows Bitz and Lipscomb 1999
+   ln_cndi_U64      = .false.         !  sea ice thermal conductivity: k = k0 + beta.S/T            (Untersteiner, 1964)
+   ln_cndi_P07      = .true.          !  sea ice thermal conductivity: k = k0 + beta1.S/T - beta2.T (Pringle et al., 2007)
+   rn_cnd_s         =   0.31          !  thermal conductivity of the snow (0.31 W/m/K, Maykut and Untersteiner, 1971)
+                                      !     Obs: 0.1-0.5 (Lecomte et al, JAMES 2013)
+   rn_kappa_i       =   1.0           !  radiation attenuation coefficient in sea ice [1/m]
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.bbl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.bbl	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.bbl	(revision 10321)
@@ -0,0 +1,252 @@
+\begin{thebibliography}{47}
+\providecommand{\natexlab}[1]{#1}
+\providecommand{\url}[1]{\texttt{#1}}
+\providecommand{\urlprefix}{URL }
+\expandafter\ifx\csname urlstyle\endcsname\relax
+  \providecommand{\doi}[1]{doi:\discretionary{}{}{}#1}\else
+  \providecommand{\doi}{doi:\discretionary{}{}{}\begingroup
+  \urlstyle{rm}\Url}\fi
+\providecommand{\eprint}[2][]{\url{#2}}
+
+\bibitem[{Assur(1958)}]{Assur58}
+Assur, A., 1958: Composition of sea ice and its tensile strength. \textit{A.
+  Nat. Acad. Sci./Nat. Res. Council, Arctic Sea Ice}, \textbf{598}, 106--138.
+
+\bibitem[{Babko et~al.(2002)Babko, Rothrock, and Maykut}]{Babkoetal02}
+Babko, O., D.~A. Rothrock, and G.~A. Maykut, 2002: Role of rafting in the
+  mechanical redistribution of sea ice thickness. \textit{Journal of
+  Geophysical Research}, \textbf{107}, 3113, doi:10.1029/1999JC000\,190,
+  \doi{doi:10.1029/1999JC000190}.
+
+\bibitem[{Bitz et~al.(2001)Bitz, Holland, Weaver, and Eby}]{Bitzetal01}
+Bitz, C.~M., M.~M. Holland, A.~J. Weaver, and M.~Eby, 2001: Simulating the
+  ice-thickness distribution in a coupled climate model. \textit{Journal of
+  Geophysical Research}, \textbf{106}, 2441--2463.
+
+\bibitem[{Bitz and Lipscomb(1999)}]{BitzLipscomb99}
+Bitz, C.~M. and W.~H. Lipscomb, 1999: An energy-conserving thermodynamic model
+  of sea ice. \textit{Journal of Geophysical Research}, \textbf{104},
+  15,669--15,677.
+
+\bibitem[{Bouillon et~al.(2013)Bouillon, Fichefet, Legat, and
+  Madec}]{Bouillonetal13}
+Bouillon, S., T.~Fichefet, V.~Legat, and G.~Madec, 2013: The
+  elastic-viscous-plastic method revisited. \textit{Ocean Modelling},
+  \textbf{71}, 2--12.
+
+\bibitem[{Brandt et~al.(2005)Brandt, Warren, Worby, and
+  Grenfell}]{Brandtetal05}
+Brandt, R.~E., S.~G. Warren, A.~P. Worby, and T.~C. Grenfell, 2005: {Surface
+  albedo of the Antarctic sea ice zone}. \textit{Journal of Climate},
+  \textbf{18}, 3606--3622.
+
+\bibitem[{Coon et~al.(1974)Coon, Maykut, Pritchard, Rothrock, and
+  Thorndike}]{Coonetal74}
+Coon, M.~D., G.~A. Maykut, R.~S. Pritchard, D.~A. Rothrock, and A.~S.
+  Thorndike, 1974: Modeling the pack ice as an elastic-plastic material.
+  \textit{AIDJEX Bulletin}, \textbf{24}, 1--105.
+
+\bibitem[{Ebert and Curry(1993)}]{EbertCurry93}
+Ebert, E.~E. and J.~A. Curry, 1993: An intermediate one-dimensional
+  thermodynamic sea ice model for investigating ice-atmosphere interactions.
+  \textit{Journal of Geophysical Research}, \textbf{98}, 10,085--10,109.
+
+\bibitem[{Fichefet and Morales~Maqueda(1997)}]{FichefetMaqueda97}
+Fichefet, T. and M.~A. Morales~Maqueda, 1997: Sensitivity of a global sea ice
+  model to the treatment of ice thermodynamics and dynamics. \textit{Journal of
+  Geophysical Research}, \textbf{102}, 12,609--12,646.
+
+\bibitem[{Flato and Hibler(1995)}]{FlatoHibler95}
+Flato, G.~M. and W.~D. Hibler, 1995: Ridging and strength in modeling the
+  thickness distribution of arctic sea ice. \textit{Journal of Geophysical
+  Research}, \textbf{100}, 18\,611--18\,626.
+
+\bibitem[{Girard et~al.(2009)Girard, Weiss, Molines, Barnier, and
+  Bouillon}]{Girardetal09}
+Girard, L., J.~Weiss, J.~Molines, B.~Barnier, and S.~Bouillon, 2009: Evaluation
+  of high-resolution sea ice models on the basis of statistical and scaling
+  properties of arctic sea ice drift and deformation. \textit{Journal of
+  Geophysical Research}, \textbf{114}, \doi{10.1029/2008JC005182}.
+
+\bibitem[{Grenfell and Maykut(1977)}]{GrenfellMaykut77}
+Grenfell, T.~C. and G.~A. Maykut, 1977: The optical properties of ice and snow
+  in the arctic basin. \textit{Journal of Glaciology}, \textbf{18}, 445--463.
+
+\bibitem[{Grenfell and Perovich(2004)}]{GrenfellPerovich04}
+Grenfell, T.~C. and D.~K. Perovich, 2004: Seasonal and spatial evolution of
+  albedo in a snow-ice-land-ocean environment. \textit{J. Geophys. Res.},
+  \textbf{109~(C01001)}, \doi{10.1029/2003JC001866}.
+
+\bibitem[{Haapala(2000)}]{Haapala00}
+Haapala, J., 2000: On the modelling of ice-thickness redistribution.
+  \textit{Journal of Glaciology}, \textbf{46~(154)}, 427--437.
+
+\bibitem[{Hibler(1979)}]{Hibler79}
+Hibler, W.~D., 1979: A dynamic thermodynamic sea ice model. \textit{Journal of
+  Physical Oceanography}, \textbf{9}, 815--846.
+
+\bibitem[{Hibler(1980)}]{Hibler80}
+---{}---{}---, 1980: Modeling a variable thickness sea ice cover.
+  \textit{Monthly Weather Review}, \textbf{108}, 1943--1973.
+
+\bibitem[{H{{\o{}}}yland(2002)}]{Hoyland02}
+H{{\o{}}}yland, 2002: Consolidation of first-year sea ice ridges.
+  \textit{Journal of Geophysical Research}, \textbf{107}, 3062,
+  \doi{doi:10.1029/2000JC000526.}
+
+\bibitem[{{IOC, SCOR and IAPSO}(2010)}]{TEOS-10}
+{IOC, SCOR and IAPSO}, 2010: The international thermodynamic equation of
+  seawater - 2010: Calculation and use of thermodynamic properties.
+  Intergovernmental Oceanographic Commission, Manuals and Guides~56, UNESCO.
+
+\bibitem[{Kovacs(1996)}]{Kovacs96}
+Kovacs, A., 1996: Sea ice, part i. bulk salinity versus ice floe thickness.
+  Tech. Rep. 96-7, Cold Regions Research and Engineering Laboratory, Hanover,
+  New Hampshire.
+
+\bibitem[{Kreyscher et~al.(1999)Kreyscher, Harder, Lemke, and
+  Flato}]{Kreyscheretal00}
+Kreyscher, M., M.~Harder, P.~Lemke, and G.~M. Flato, 1999: Results of the sea
+  ice model intercomparison project: Evaluation of sea ice rheology scheme for
+  use in climate simulations. \textit{Jounal of Geophysical Research},
+  \textbf{105}, 11,299--11,320.
+
+\bibitem[{Lecomte et~al.(2015)Lecomte, Fichefet, Flocco, Schroeder, and
+  Vancoppenolle}]{Lecomteetal15}
+Lecomte, O., T.~Fichefet, D.~Flocco, D.~Schroeder, and M.~Vancoppenolle, 2015:
+  Interactions between wind-blown snow redistribution and melt ponds in a
+  coupled ocean-sea ice model. \textit{Ocean Modelling}, \textbf{87}, 67--80.
+
+\bibitem[{Lecomte et~al.(2011)Lecomte, Fichefet, Vancoppenolle, and
+  Nicolaus}]{Lecomteetal11}
+Lecomte, O., T.~Fichefet, M.~Vancoppenolle, and M.~Nicolaus, 2011: A new snow
+  thermodynamic scheme for large-scale sea-ice models. \textit{Annals of
+  Glaciology}, \textbf{52}, 337--346.
+
+\bibitem[{Lepp\"aranta(2005)}]{Lepparanta05}
+Lepp\"aranta, M., 2005: \textit{The Drift of Sea ice}. Springer, 266 pp. pp.
+
+\bibitem[{Lepp\"aranta et~al.(1995)Lepp\"aranta, Lensu, and
+  Witch}]{Lepparantaetal95}
+Lepp\"aranta, M., M.~Lensu, and P.~K.~B. Witch, 1995: The life story of a
+  first-year sea ice ridge. \textit{Cold Regions Science and Technology},
+  \textbf{23(3)}, 279--290.
+
+\bibitem[{Lipscomb(2001)}]{Lipscomb01}
+Lipscomb, W.~H., 2001: Remapping the thickness distribution in sea ice models.
+  \textit{Journal of Geophysical Research}, \textbf{106}, 13\,989--14\,000.
+
+\bibitem[{Lipscomb et~al.(2007)Lipscomb, Hunke, Maslowski, and
+  Jackaci}]{Lipscombetal07}
+Lipscomb, W.~H., E.~Hunke, W.~Maslowski, and J.~Jackaci, 2007: Ridging,
+  strength, and stability in high-resolution sea ice models. \textit{Journal of
+  Geophysical Research}, \textbf{112}, C03S9, \doi{doi:10.1029/2005JC003355}.
+
+\bibitem[{Massonnet et~al.(2018)Massonnet, Barth\'el\'emy, Worou, Fichefet,
+  Vancoppenolle, and Rousset}]{Massonnetetal18b}
+Massonnet, F., A.~Barth\'el\'emy, K.~Worou, T.~Fichefet, M.~Vancoppenolle, and
+  C.~Rousset, 2018: Insights on the discretization of the ice thickness
+  distribution in large-scale sea ice models. \textit{submitted}.
+
+\bibitem[{Maykut(1986)}]{Maykut86}
+Maykut, G.~A., 1986: \textit{The Geophysics of Sea Ice}, NATO ASI Series.
+  Series B, Physics., Vol. 146, chap. The surface heat and mass balance,
+  395--463. Plenum Press, New York.
+
+\bibitem[{Maykut and McPhee(1995)}]{MaykutMcPhee95}
+Maykut, G.~A. and M.~G. McPhee, 1995: Solar heating of the arctic mixed layer.
+  \textit{Journal of Geophysical Research}, \textbf{100}, 24,691--24,703.
+
+\bibitem[{Maykut and Thorndike(1973)}]{MaykutThorndike73}
+Maykut, G.~A. and A.~S. Thorndike, 1973: An approach to coupling the dynamics
+  and thermodynamics of arctic sea ice. \textit{AIDJEX Bulletin}, \textbf{21},
+  23--29.
+
+\bibitem[{Maykut and Untersteiner(1971)}]{MaykutUntersteiner71}
+Maykut, G.~A. and N.~Untersteiner, 1971: Some results from a time-dependent
+  thermodynamic model of sea ice. \textit{Journal of Geophysical Research},
+  \textbf{76}, 1550--1575.
+
+\bibitem[{McPhee(1992)}]{McPhee92}
+McPhee, M., 1992: Turbulent heat flux in the upper ocean under sea ice.
+  \textit{Journal of Geophysical Research}, \textbf{97(C4)}, 5365--5379.
+
+\bibitem[{Mellor and Kantha(1989)}]{MellorKantha89}
+Mellor, G.~L. and L.~Kantha, 1989: An ice-ocean coupled model. \textit{Journal
+  of Geophysical Research}, \textbf{94}, 10,937--10,954.
+
+\bibitem[{Notz et~al.(2016)Notz, Jahn, Holland, Hunke, Massonnet, Stroeve,
+  Tremblay, and Vancoppenolle}]{Notzetal16}
+Notz, D., A.~Jahn, M.~Holland, E.~Hunke, F.~Massonnet, J.~Stroeve, B.~Tremblay,
+  and M.~Vancoppenolle, 2016: {The CMIP6 Sea-Ice Model Intercomparison Project
+  (SIMIP): understanding sea ice through climate-model simulations}.
+  \textit{Geoscientific Model Development}, \textbf{9 (9)}, 3427--3446.
+
+\bibitem[{Parmerter(1975)}]{Parmerter75}
+Parmerter, R.~R., 1975: A model of simple rafting in sea ice. \textit{Journal
+  of Geophysical Research}, \textbf{80}, 1948--1952.
+
+\bibitem[{Perovich et~al.(2002)Perovich, Grenfell, Light, and
+  Hobbs}]{Perovichetal02alb}
+Perovich, D.~K., T.~C. Grenfell, B.~Light, and P.~V. Hobbs, 2002: Seasonal
+  evolution of the albedo of multiyear arctic sea ice. \textit{Journal of
+  Geophysical Research}, \textbf{107}, 8044, doi:10.1029/2000JC000\,438,
+  \doi{doi:10.1029/2000JC000438}.
+
+\bibitem[{Prather(1986)}]{Prather86}
+Prather, M.~J., 1986: Numerical advection by conservation of second-order
+  moments. \textit{Journal of Geophysical Research}, \textbf{91}, 6671--6681.
+
+\bibitem[{Pringle et~al.(2007)Pringle, Eicken, Trodahl, and
+  Backstrom}]{Pringleetal07}
+Pringle, D.~J., H.~Eicken, H.~J. Trodahl, and L.~Backstrom, 2007: Thermal
+  conductivity of landfast antarctic and arctic sea ice. \textit{Journal of
+  Geophysical Research}, \textbf{112}, C04017, \doi{10.1029/2006JC003641}.
+
+\bibitem[{Schmidt et~al.(2004)Schmidt, Bitz, Mikolajewicz, and
+  Tremblay}]{Schmidtetal04}
+Schmidt, G., C.~M. Bitz, U.~Mikolajewicz, and L.-B. Tremblay, 2004: Ice-ocean
+  boundary conditions for coupled models. \textit{Ocean Modelling}, \textbf{7},
+  59--74, \doi{doi:10.1016/S1463-5003(03)00030-1}.
+
+\bibitem[{Shine and Henderson-Sellers(1985)}]{ShineHenderson85}
+Shine, K.~P. and A.~Henderson-Sellers, 1985: The sensitivity of a thermodynamic
+  sea ice model to changes in surface albedo parameterization. \textit{Journal
+  of Geophysical Research}, \textbf{90}, 2243--2250.
+
+\bibitem[{Thorndike et~al.(1975)Thorndike, Rothrock, Maykut, and
+  Colony}]{Thorndikeetal75}
+Thorndike, A.~S., D.~A. Rothrock, G.~A. Maykut, and R.~Colony, 1975: The
+  thickness distribution of sea ice. \textit{Journal of Geophysical Research},
+  \textbf{80}, 4501--4513.
+
+\bibitem[{Tuhkuri and Lensu(2002)}]{TuhkuriLensu02}
+Tuhkuri, J. and M.~Lensu, 2002: Laboratory tests on ridging and rafting of ice
+  sheets. \textit{Journal of Geophysical Research}, \textbf{107}, 3125,
+  doi:10.1029/2001JC000\,848, \doi{doi:10.1029/2001JC000848}.
+
+\bibitem[{Vancoppenolle et~al.(2009)Vancoppenolle, Fichefet, and
+  Goosse}]{Vancoppenolleetal09b}
+Vancoppenolle, M., T.~Fichefet, and H.~Goosse, 2009: {Simulating the mass
+  balance and salinity of Arctic and Antarctic sea ice. 2. Sensitivity to
+  salinity processes}. \textit{Ocean Modelling}, \textbf{27 (1--2)}, 54--69,
+  \doi{10.1016/j.ocemod.2008.11.003}.
+
+\bibitem[{Weiss(2013)}]{Weiss13}
+Weiss, J., 2013: \textit{Drift, Deformation and Fracture of Sea Ice: A
+  Perspective across Scales}. Springer.
+
+\bibitem[{Worster(1992)}]{Worster92}
+Worster, M.~G., 1992: \textit{Interactive Dynamics of Convection and
+  Solidification}, chap. The dynamics of mushy layers, 113--138. Kluwer.
+
+\bibitem[{Zhang and Rothrock(2001)}]{ZhangRothrock01}
+Zhang, J. and D.~Rothrock, 2001: A thickness and enthalpy distribution sea ice
+  model. \textit{Journal of Physical Oceanography}, \textbf{31}, 2986--3001.
+
+\bibitem[{Zuo and Oerlemans(1996)}]{ZuoOerlemans96}
+Zuo, Z. and J.~Oerlemans, 1996: Modelling albedo and specific balance of the
+  greenland ice sheet: calculations for the sondre stromfjord transect.
+  \textit{Journal of Glaciology}, \textbf{42}, 305--317.
+
+\end{thebibliography}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_main/SI3_manual.tex	(revision 10321)
@@ -0,0 +1,129 @@
+%% ==============================================================================
+%% NEMO_book.tex: build the NEMO Reference Manual
+%% ==============================================================================
+
+
+%% Run ../build_NEMO_manual.sh to generate the PDF version (with pdflatex)
+
+%% Document layout
+%% ==============================================================================
+
+\documentclass[a4paper, 11pt]{book}
+
+
+%% Preamble
+%% ==============================================================================
+
+\usepackage{../../tex_main/NEMO_manual}
+\usepackage{../../tex_sub/NEMO_minted}
+
+\usepackage{bm}
+
+\makeindex
+
+
+%% 
+%% ==============================================================================
+
+\begin{document}
+
+
+%% Frontmatter
+%% ==============================================================================
+
+%% Frontpage
+
+\title{
+\vspace{1.5cm}
+\rule{400pt}{1.5pt} \\
+\vspace{0.45cm}
+ {\Huge SI$^3$ \\}
+ {\Large -- Sea Ice modelling Integrated Initiative --}\\
+ {\Large The NEMO Sea Ice engine}\\ 
+\date{\today}
+\author{The NEMO Sea Ice Working Group \\
+\\
+\small \textit{Note du P\^ole de mod\'elisation de l'Institut Pierre-Simon Laplace No 31} \\
+\small \textcolor{red}{First draft documentation. Needs completion and rewriting}. \\
+\\
+ISSN No 1288-1619\\
+}
+\rule{400pt}{1.5pt}
+}
+
+\maketitle						% generate the title
+
+\frontmatter
+
+%% ToC i.e. Table of Contents
+
+\dominitoc
+\tableofcontents
+
+
+%% Mainmatter
+%% ==============================================================================
+
+\mainmatter
+
+\subfile{../tex_sub/todolist}
+
+%% Abstract - Foreword
+
+\subfile{../tex_sub/abstract_foreword}
+
+% Introduction
+
+\subfile{../tex_sub/introduction}
+
+% Chapters
+
+\subfile{../tex_sub/chap_model_basics}
+
+\subfile{../tex_sub/chap_domain}
+
+\subfile{../tex_sub/chap_dynamics}
+
+\subfile{../tex_sub/chap_transport}
+
+\subfile{../tex_sub/chap_ridging_rafting}
+
+\subfile{../tex_sub/chap_radiative_transfer}
+
+\subfile{../tex_sub/chap_thermo}
+
+\subfile{../tex_sub/chap_interfaces}
+
+\subfile{../tex_sub/chap_output_diagnostics}
+
+\subfile{../tex_sub/chap_single_category_use}
+
+\subfile{../tex_sub/chap_bdy_agrif}
+
+\subfile{../tex_sub/chap_miscellaneous}
+
+%% Appendix
+
+%\appendix
+%% Backmatter
+%% ==============================================================================
+
+\backmatter
+
+%% Bibliography
+
+\cleardoublepage
+\phantomsection
+\addcontentsline{toc}{chapter}{Bibliography}
+
+\bibliography{../tex_main/SI3_manual.bbl}
+%\bibliography{/Users/ioulianikolskaia/Boulot/LIBRARY/BIBTEX/Martin_biblio.bib} 
+
+%% Index
+
+\cleardoublepage
+\phantomsection
+\addcontentsline{toc}{chapter}{Index}
+\printindex
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/abstract_foreword.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/abstract_foreword.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/abstract_foreword.tex	(revision 10321)
@@ -0,0 +1,44 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Abstract
+% ================================================================
+
+\chapter*{Abstract}
+
+SI$^3$ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO (Nucleus for European Modelling of the Ocean). It is adapted to regional and global sea ice and climate problems. It is intended to be a flexible tool for studying sea ice and its interactions with the other components of the Earth System over a wide range of space and time scales. SI$^3$ is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework \citep{Coonetal74}, combining the ice thickness distribution framework, the conservation of horizontal momentum, an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics. Prognostic variables are the two-dimensional horizontal velocity field, ice volume, area, enthalpy, salt content, snow volume and enthalpy. In the horizontal direction, the model uses a curvilinear orthogonal grid. In the vertical direction, the model uses equally-spaced layers. In thickness space, the model uses thickness categories with prescribed boundaries. Various physical and numerical choices are available to describe sea ice physics. SI$^3$ is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with several atmospheric general circulation models. It also supports two-way grid embedding via the AGRIF software.
+
+%\vspace{-40pt}
+
+{\small
+} 
+
+% ================================================================
+% Disclaimer
+% ================================================================
+\chapter*{Disclaimer}
+
+Like all components of NEMO, the sea ice component is developed under the \href{http://www.cecill.info/}{CECILL license}, 
+which is a French adaptation of the GNU GPL (General Public License). Anyone may use it 
+freely for research purposes, and is encouraged to communicate back to the NEMO team 
+its own developments and improvements. The model and the present document have been 
+made available as a service to the community. We cannot certify that the code and its manual 
+are free of errors. Bugs are inevitable and some have undoubtedly survived the testing phase. 
+Users are encouraged to bring them to our attention. The authors assume no responsibility 
+for problems, errors, or incorrect usage of NEMO.
+
+\vspace{1cm}
+SI3 reference in papers and other publications is as follows:
+\vspace{0.5cm}
+
+The NEMO Sea Ice Working Group, 2018: SI$^3$ -- Sea Ice modelling Integrated Initiative -- The NEMO Sea Ice Engine, \textit{Note du P\^ole de mod\'{e}lisation}, Institut Pierre-Simon Laplace (IPSL), France, 
+No XX, ISSN No 1288-1619.\\
+
+\vspace{0.5cm}
+Additional information can be found on \href{http://www.nemo-ocean.eu/}{www.nemo-ocean.eu}.
+\vspace{0.5cm}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/ametsoc.bst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/ametsoc.bst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/ametsoc.bst	(revision 10321)
@@ -0,0 +1,1662 @@
+%%
+%% This is file `ametsoc7.bst',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% merlin.mbs  (with options: `ay,nat,nm-rev1,ed-rev,jnrlst,nmdash,nmd-3,dt-beg,yr-com,yrp-col,thtit-a,vol-2bf,vnum-sp,volp-com,pgsep-s,num-xser,numser,ser-vol,bkpg-x,pg-bk,pre-edn,agu-doi,doi,edparc,bkedcap,edby,edbyy,blk-tit,in-x,pp,ed,abr,ednx,ord,jabr,eprint,url,url-nt,em-it,nfss,')
+%% ----------------------------------------
+%% *** Bibliography style file for ALL AMS Journals...version 1.0  ***
+%% *** Brian Papa - American Meteorological Society ***
+%% 
+%% Copyright 1994-2004 Patrick W Daly
+ % ===============================================================
+ % IMPORTANT NOTICE:
+ % This bibliographic style (bst) file has been generated from one or
+ % more master bibliographic style (mbs) files, listed above.
+ %
+ % This generated file can be redistributed and/or modified under the terms
+ % of the LaTeX Project Public License Distributed from CTAN
+ % archives in directory macros/latex/base/lppl.txt; either
+ % version 1 of the License, or any later version.
+ % ===============================================================
+ % Name and version information of the main mbs file:
+ % \ProvidesFile{merlin.mbs}[2004/02/09 4.13 (PWD, AO, DPC)]
+ %   For use with BibTeX version 0.99a or later
+ %-------------------------------------------------------------------
+ % This bibliography style file is intended for texts in ENGLISH
+ % This is an author-year citation style bibliography. As such, it is
+ % non-standard LaTeX, and requires a special package file to function properly.
+ % Such a package is    natbib.sty   by Patrick W. Daly
+ % The form of the \bibitem entries is
+ %   \bibitem[Jones et al.(1990)]{key}...
+ %   \bibitem[Jones et al.(1990)Jones, Baker, and Smith]{key}...
+ % The essential feature is that the label (the part in brackets) consists
+ % of the author names, as they should appear in the citation, with the year
+ % in parentheses following. There must be no space before the opening
+ % parenthesis!
+ % With natbib v5.3, a full list of authors may also follow the year.
+ % In natbib.sty, it is possible to define the type of enclosures that is
+ % really wanted (brackets or parentheses), but in either case, there must
+ % be parentheses in the label.
+ % The \cite command functions as follows:
+ %   \citet{key} ==>>                Jones et al. (1990)
+ %   \citet*{key} ==>>               Jones, Baker, and Smith (1990)
+ %   \citep{key} ==>>                (Jones et al., 1990)
+ %   \citep*{key} ==>>               (Jones, Baker, and Smith, 1990)
+ %   \citep[chap. 2]{key} ==>>       (Jones et al., 1990, chap. 2)
+ %   \citep[e.g.][]{key} ==>>        (e.g. Jones et al., 1990)
+ %   \citep[e.g.][p. 32]{key} ==>>   (e.g. Jones et al., p. 32)
+ %   \citeauthor{key} ==>>           Jones et al.
+ %   \citeauthor*{key} ==>>          Jones, Baker, and Smith
+ %   \citeyear{key} ==>>             1990
+ %---------------------------------------------------------------------
+
+ENTRY
+  { address
+    archive
+    author
+    booktitle
+    chapter
+    doi
+    edition
+    editor
+    eid
+    eprint
+    howpublished
+    department
+    institution
+    journal
+    key
+    month
+    note
+    number
+    organization
+    pages
+    publisher
+    school
+    series
+    title
+    type
+    url
+    volume
+    year
+  }
+  {}
+  { label extra.label sort.label short.list }
+INTEGERS { output.state before.all mid.sentence after.sentence after.block }
+FUNCTION {init.state.consts}
+{ #0 'before.all :=
+  #1 'mid.sentence :=
+  #2 'after.sentence :=
+  #3 'after.block :=
+}
+STRINGS { s t}
+FUNCTION {output.nonnull}
+{ 's :=
+  output.state mid.sentence =
+    { ", " * write$ }
+    { output.state after.block =
+        { add.period$ write$
+          newline$
+          "\newblock " write$
+        }
+        { output.state before.all =
+            'write$
+            { add.period$ " " * write$ }
+          if$
+        }
+      if$
+      mid.sentence 'output.state :=
+    }
+  if$
+  s
+}
+FUNCTION {output}
+{ duplicate$ empty$
+    'pop$
+    'output.nonnull
+  if$
+}
+FUNCTION {output.check}
+{ 't :=
+  duplicate$ empty$
+    { pop$ "empty " t * " in " * cite$ * warning$ }
+    'output.nonnull
+  if$
+}
+FUNCTION {fin.entry}
+{ add.period$
+  write$
+  newline$
+}
+
+FUNCTION {new.block}
+{ output.state before.all =
+    'skip$
+    { after.block 'output.state := }
+  if$
+}
+FUNCTION {new.sentence}
+{ output.state after.block =
+    'skip$
+    { output.state before.all =
+        'skip$
+        { after.sentence 'output.state := }
+      if$
+    }
+  if$
+}
+FUNCTION {add.blank}
+{  " " * before.all 'output.state :=
+}
+
+FUNCTION {date.block}
+{
+  ":" *
+  add.blank
+}
+
+FUNCTION {not}
+{   { #0 }
+    { #1 }
+  if$
+}
+FUNCTION {and}
+{   'skip$
+    { pop$ #0 }
+  if$
+}
+FUNCTION {or}
+{   { pop$ #1 }
+    'skip$
+  if$
+}
+FUNCTION {new.block.checkb}
+{ empty$
+  swap$ empty$
+  and
+    'skip$
+    'new.block
+  if$
+}
+FUNCTION {field.or.null}
+{ duplicate$ empty$
+    { pop$ "" }
+    'skip$
+  if$
+}
+FUNCTION {emphasize}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textit{" swap$ * "}" * }
+  if$
+}
+FUNCTION {bolden}
+{ duplicate$ empty$
+    { pop$ "" }
+    { "\textbf{" swap$ * "}" * }
+  if$
+}
+FUNCTION {tie.or.space.prefix}
+{ duplicate$ text.length$ #3 <
+    { "~" }
+    { " " }
+  if$
+  swap$
+}
+
+FUNCTION {capitalize}
+{ "u" change.case$ "t" change.case$ }
+
+FUNCTION {space.word}
+{ " " swap$ * " " * }
+ % Here are the language-specific definitions for explicit words.
+ % Each function has a name bbl.xxx where xxx is the English word.
+ % The language selected here is ENGLISH
+FUNCTION {bbl.and}
+{ "and"}
+
+FUNCTION {bbl.etal}
+{ "et~al." }
+
+FUNCTION {bbl.editors}
+{ "Eds." }
+
+FUNCTION {bbl.editor}
+{ "Ed." }
+
+FUNCTION {bbl.edby}
+{ "edited by" }
+
+FUNCTION {bbl.edition}
+{ "ed." }
+
+FUNCTION {bbl.volume}
+{ "Vol." }
+
+FUNCTION {bbl.of}
+{ "of" }
+
+FUNCTION {bbl.number}
+{ "No." }
+
+FUNCTION {bbl.nr}
+{ "No." }
+
+FUNCTION {bbl.in}
+{ "in" }
+
+FUNCTION {bbl.pages}
+{ "pp." }
+
+FUNCTION {bbl.page}
+{ "p." }
+
+FUNCTION {bbl.chapter}
+{ "chap." }
+
+FUNCTION {bbl.techrep}
+{ "Tech. Rep." }
+
+FUNCTION {bbl.mthesis}
+{ "Master's thesis" }
+
+FUNCTION {bbl.phdthesis}
+{ "Ph.D. thesis" }
+
+FUNCTION {bbl.first}
+{ "1st" }
+
+FUNCTION {bbl.second}
+{ "2d" }
+
+FUNCTION {bbl.third}
+{ "3d" }
+
+FUNCTION {bbl.fourth}
+{ "4th" }
+
+FUNCTION {bbl.fifth}
+{ "5th" }
+
+FUNCTION {bbl.st}
+{ "st" }
+
+FUNCTION {bbl.nd}
+{ "d" }
+
+FUNCTION {bbl.rd}
+{ "d" }
+
+FUNCTION {bbl.th}
+{ "th" }
+
+MACRO {jan} {"Jan."}
+
+MACRO {feb} {"Feb."}
+
+MACRO {mar} {"Mar."}
+
+MACRO {apr} {"Apr."}
+
+MACRO {may} {"May"}
+
+MACRO {jun} {"Jun."}
+
+MACRO {jul} {"Jul."}
+
+MACRO {aug} {"Aug."}
+
+MACRO {sep} {"Sep."}
+
+MACRO {oct} {"Oct."}
+
+MACRO {nov} {"Nov."}
+
+MACRO {dec} {"Dec."}
+
+FUNCTION {eng.ord}
+{ duplicate$ "1" swap$ *
+  #-2 #1 substring$ "1" =
+     { bbl.th * }
+     { duplicate$ #-1 #1 substring$
+       duplicate$ "1" =
+         { pop$ bbl.st * }
+         { duplicate$ "2" =
+             { pop$ bbl.nd * }
+             { "3" =
+                 { bbl.rd * }
+                 { bbl.th * }
+               if$
+             }
+           if$
+          }
+       if$
+     }
+   if$
+}
+
+MACRO {acmcs} {"ACM Comput. Surv."}
+
+MACRO {acta} {"Acta Inf."}
+
+MACRO {cacm} {"Commun. ACM"}
+
+MACRO {ibmjrd} {"IBM J. Res. Dev."}
+
+MACRO {ibmsj} {"IBM Syst.~J."}
+
+MACRO {ieeese} {"IEEE Trans. Software Eng."}
+
+MACRO {ieeetc} {"IEEE Trans. Comput."}
+
+MACRO {ieeetcad}
+ {"IEEE Trans. Comput. Aid. Des."}
+
+MACRO {ipl} {"Inf. Process. Lett."}
+
+MACRO {jacm} {"J.~ACM"}
+
+MACRO {jcss} {"J.~Comput. Syst. Sci."}
+
+MACRO {scp} {"Sci. Comput. Program."}
+
+MACRO {sicomp} {"SIAM J. Comput."}
+
+MACRO {tocs} {"ACM Trans. Comput. Syst."}
+
+MACRO {tods} {"ACM Trans. Database Syst."}
+
+MACRO {tog} {"ACM Trans. Graphic."}
+
+MACRO {toms} {"ACM Trans. Math. Software"}
+
+MACRO {toois} {"ACM Trans. Office Inf. Syst."}
+
+MACRO {toplas} {"ACM Trans. Progr. Lang. Syst."}
+
+MACRO {tcs} {"Theor. Comput. Sci."}
+
+FUNCTION {bibinfo.check}
+{ swap$
+  duplicate$ missing$
+    {
+      pop$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ pop$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {bibinfo.warn}
+{ swap$
+  duplicate$ missing$
+    {
+      swap$ "missing " swap$ * " in " * cite$ * warning$ pop$
+      ""
+    }
+    { duplicate$ empty$
+        {
+          swap$ "empty " swap$ * " in " * cite$ * warning$
+        }
+        { swap$
+          pop$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.eprint}
+{ eprint duplicate$ empty$
+    'skip$
+    { "\eprint"
+      archive empty$
+        'skip$
+        { "[" * archive * "]" * }
+      if$
+      "{" * swap$ * "}" *
+    }
+  if$
+}
+STRINGS  { bibinfo}
+INTEGERS { nameptr namesleft numnames }
+
+FUNCTION {format.names}
+{ 'bibinfo :=
+  duplicate$ empty$ 'skip$ {
+  's :=
+  "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      duplicate$ #1 >
+        { "{f.~}{vv~}{ll}{, jj}" }
+        { "{vv~}{ll}{, f.}{, jj}" }
+      if$
+      format.name$
+      bibinfo bibinfo.check
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              numnames #2 >
+                { "," * }
+                'skip$
+              if$
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+  } if$
+}
+FUNCTION {format.names.ed}
+{
+  format.names
+}
+FUNCTION {format.key}
+{ empty$
+    { key field.or.null }
+    { "" }
+  if$
+}
+
+FUNCTION {format.authors}
+{ author "author" format.names
+}
+FUNCTION {get.bbl.editor}
+{ editor num.names$ #1 > 'bbl.editors 'bbl.editor if$ }
+
+FUNCTION {format.editors}
+{ editor "editor" format.names duplicate$ empty$ 'skip$
+    {
+      "," *
+      " " *
+      get.bbl.editor
+      capitalize
+   "(" swap$ * ")" *
+      *
+    }
+  if$
+}
+FUNCTION {format.book.pages}
+{ pages "pages" bibinfo.check
+  duplicate$ empty$ 'skip$
+    { " " * bbl.pages * }
+  if$
+}
+FUNCTION {format.doi}
+{ doi "doi" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      "\doi{" swap$ * "}" *
+    }
+  if$
+}
+FUNCTION {format.note}
+{
+  url empty$
+    'skip$
+    { "\urlprefix\url{" url * "}" * output }
+  if$
+ note empty$
+    { "" }
+    { note #1 #1 substring$
+      duplicate$ "{" =
+        'skip$
+        { output.state mid.sentence =
+          { "l" }
+          { "u" }
+        if$
+        change.case$
+        }
+      if$
+      note #2 global.max$ substring$ * "note" bibinfo.check
+    }
+  if$
+}
+
+FUNCTION {format.title}
+{ title
+  duplicate$ empty$ 'skip$
+    { "t" change.case$ }
+  if$
+  "title" bibinfo.check
+}
+FUNCTION {format.full.names}
+{'s :=
+ "" 't :=
+  #1 'nameptr :=
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv~}{ll}" format.name$
+      't :=
+      nameptr #1 >
+        {
+          namesleft #1 >
+            { ", " * t * }
+            {
+              s nameptr "{ll}" format.name$ duplicate$ "others" =
+                { 't := }
+                { pop$ }
+              if$
+              t "others" =
+                {
+                  " " * bbl.etal *
+                }
+                {
+                  numnames #2 >
+                    { "," * }
+                    'skip$
+                  if$
+                  bbl.and
+                  space.word * t *
+                }
+              if$
+            }
+          if$
+        }
+        't
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {author.editor.key.full}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.full.names }
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {author.key.full}
+{ author empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { author format.full.names }
+  if$
+}
+
+FUNCTION {editor.key.full}
+{ editor empty$
+    { key empty$
+         { cite$ #1 #3 substring$ }
+          'key
+      if$
+    }
+    { editor format.full.names }
+  if$
+}
+
+FUNCTION {make.full.names}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.full
+    { type$ "proceedings" =
+        'editor.key.full
+        'author.key.full
+      if$
+    }
+  if$
+}
+
+FUNCTION {output.bibitem}
+{ newline$
+  "\bibitem[{" write$
+  label write$
+  ")" make.full.names duplicate$ short.list =
+     { pop$ }
+     { * }
+   if$
+  "}]{" * write$
+  cite$ write$
+  "}" write$
+  newline$
+  ""
+  before.all 'output.state :=
+}
+
+FUNCTION {if.digit}
+{ duplicate$ "0" =
+  swap$ duplicate$ "1" =
+  swap$ duplicate$ "2" =
+  swap$ duplicate$ "3" =
+  swap$ duplicate$ "4" =
+  swap$ duplicate$ "5" =
+  swap$ duplicate$ "6" =
+  swap$ duplicate$ "7" =
+  swap$ duplicate$ "8" =
+  swap$ "9" = or or or or or or or or or
+}
+FUNCTION {n.separate}
+{ 't :=
+  ""
+  #0 'numnames :=
+  { t empty$ not }
+  { t #-1 #1 substring$ if.digit
+      { numnames #1 + 'numnames := }
+      { #0 'numnames := }
+    if$
+    t #-1 #1 substring$ swap$ *
+    t #-2 global.max$ substring$ 't :=
+    numnames #5 =
+      { duplicate$ #1 #2 substring$ swap$
+        #3 global.max$ substring$
+        "\," swap$ * *
+      }
+      'skip$
+    if$
+  }
+  while$
+}
+FUNCTION {n.dashify}
+{
+  n.separate
+  't :=
+  ""
+    { t empty$ not }
+    { t #1 #1 substring$ "-" =
+        { t #1 #2 substring$ "--" = not
+            { "--" *
+              t #2 global.max$ substring$ 't :=
+            }
+            {   { t #1 #1 substring$ "-" = }
+                { "-" *
+                  t #2 global.max$ substring$ 't :=
+                }
+              while$
+            }
+          if$
+        }
+        { t #1 #1 substring$ *
+          t #2 global.max$ substring$ 't :=
+        }
+      if$
+    }
+  while$
+}
+
+FUNCTION {word.in}
+{ "" }
+
+FUNCTION {format.date}
+{ year "year" bibinfo.check duplicate$ empty$
+    {
+      "empty year in " cite$ * "; set to ????" * warning$
+       pop$ "????"
+    }
+    'skip$
+  if$
+  extra.label *
+  before.all 'output.state :=
+  ", " swap$ *
+}
+FUNCTION {format.btitle}
+{ title "title" bibinfo.check
+  duplicate$ empty$ 'skip$
+    {
+      emphasize
+    }
+  if$
+}
+FUNCTION {either.or.check}
+{ empty$
+    'pop$
+    { "can't use both " swap$ * " fields in " * cite$ * warning$ }
+  if$
+}
+FUNCTION {format.bvolume}
+{ volume empty$
+    { "" }
+    { bbl.volume volume tie.or.space.prefix
+      "volume" bibinfo.check * *
+      series "series" bibinfo.check
+      duplicate$ empty$ 'pop$
+%%% NO ITALIC SERIES        { emphasize ", " * swap$ * }
+      {", " * swap$ * }
+      if$
+      "volume and number" number either.or.check
+    }
+  if$
+}
+FUNCTION {format.number.series}
+{ volume empty$
+    { number empty$
+        { series field.or.null }
+        { series empty$
+            { number "number" bibinfo.check }
+            { output.state mid.sentence =
+                { bbl.number }
+                { bbl.number capitalize }
+              if$
+              number tie.or.space.prefix "number" bibinfo.check * *
+              bbl.in space.word *
+              series "series" bibinfo.check *
+            }
+          if$
+        }
+      if$
+    }
+    { "" }
+  if$
+}
+FUNCTION {is.num}
+{ chr.to.int$
+  duplicate$ "0" chr.to.int$ < not
+  swap$ "9" chr.to.int$ > not and
+}
+
+FUNCTION {extract.num}
+{ duplicate$ 't :=
+  "" 's :=
+  { t empty$ not }
+  { t #1 #1 substring$
+    t #2 global.max$ substring$ 't :=
+    duplicate$ is.num
+      { s swap$ * 's := }
+      { pop$ "" 't := }
+    if$
+  }
+  while$
+  s empty$
+    'skip$
+    { pop$ s }
+  if$
+}
+
+FUNCTION {convert.edition}
+{ extract.num "l" change.case$ 's :=
+  s "first" = s "1" = or
+    { bbl.first 't := }
+    { s "second" = s "2" = or
+        { bbl.second 't := }
+        { s "third" = s "3" = or
+            { bbl.third 't := }
+            { s "fourth" = s "4" = or
+                { bbl.fourth 't := }
+                { s "fifth" = s "5" = or
+                    { bbl.fifth 't := }
+                    { s #1 #1 substring$ is.num
+                        { s eng.ord 't := }
+                        { edition 't := }
+                      if$
+                    }
+                  if$
+                }
+              if$
+            }
+          if$
+        }
+      if$
+    }
+  if$
+  t
+}
+
+FUNCTION {format.edition}
+{ edition duplicate$ empty$ 'skip$
+    {
+      convert.edition
+      output.state mid.sentence =
+        { "l" }
+        { "t" }
+      if$ change.case$
+      "edition" bibinfo.check
+      " " * bbl.edition *
+    }
+  if$
+}
+INTEGERS { multiresult }
+FUNCTION {multi.page.check}
+{ 't :=
+  #0 'multiresult :=
+    { multiresult not
+      t empty$ not
+      and
+    }
+    { t #1 #1 substring$
+      duplicate$ "-" =
+      swap$ duplicate$ "," =
+      swap$ "+" =
+      or or
+        { #1 'multiresult := }
+        { t #2 global.max$ substring$ 't := }
+      if$
+    }
+  while$
+  multiresult
+}
+FUNCTION {format.pages}
+{ pages duplicate$ empty$ 'skip$
+    { duplicate$ multi.page.check
+        {
+          n.dashify
+        }
+        {
+        }
+      if$
+      "pages" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.journal.pages}
+{ pages duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$
+        { pop$ pop$ format.pages }
+        {
+          ", " *
+          swap$
+          n.dashify
+          "pages" bibinfo.check
+          *
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.journal.eid}
+{ eid "eid" bibinfo.check
+  duplicate$ empty$ 'pop$
+    { swap$ duplicate$ empty$ 'skip$
+      {
+          ", " *
+      }
+      if$
+      swap$ *
+    }
+  if$
+}
+FUNCTION {format.vol.num.pages}
+{ volume field.or.null
+  duplicate$ empty$ 'skip$
+    {
+      "volume" bibinfo.check
+    }
+  if$
+  number "number" bibinfo.check duplicate$ empty$ 'skip$
+    {
+      swap$ duplicate$ empty$
+        { "there's a number but no volume in " cite$ * warning$ }
+        'skip$
+      if$
+      swap$
+      "~(" swap$ * ")" *
+    }
+  if$ *
+  bolden
+  eid empty$
+    { format.journal.pages }
+    { format.journal.eid }
+  if$
+}
+
+FUNCTION {format.chapter.pages}
+{ chapter empty$
+    'format.pages
+    { type empty$
+        { bbl.chapter }
+        { type "l" change.case$
+          "type" bibinfo.check
+        }
+      if$
+      chapter tie.or.space.prefix
+      "chapter" bibinfo.check
+      * *
+      pages empty$
+        'skip$
+        { ", " * format.pages * }
+      if$
+    }
+  if$
+}
+
+FUNCTION {format.booktitle}
+{
+  booktitle "booktitle" bibinfo.check
+  emphasize
+}
+FUNCTION {format.in.ed.booktitle}
+{ format.booktitle duplicate$ empty$ 'skip$
+    {
+      editor "editor" format.names.ed duplicate$ empty$ 'pop$
+        {
+          get.bbl.editor
+          swap$ "," *
+          " " * swap$ *
+          swap$
+          "," *
+          " " * swap$
+          * }
+      if$
+      word.in swap$ *
+    }
+  if$
+}
+FUNCTION {format.thesis.type}
+{ type duplicate$ empty$
+    'pop$
+    { swap$ pop$
+      "t" change.case$ "type" bibinfo.check
+    }
+  if$
+}
+FUNCTION {format.tr.number}
+{ number "number" bibinfo.check
+  type duplicate$ empty$
+    { pop$ bbl.techrep }
+    'skip$
+  if$
+  "type" bibinfo.check
+  swap$ duplicate$ empty$
+    { pop$ "t" change.case$ }
+    { tie.or.space.prefix * * }
+  if$
+}
+FUNCTION {format.article.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.book.crossref}
+{ volume duplicate$ empty$
+    { "empty volume in " cite$ * "'s crossref of " * crossref * warning$
+      pop$ word.in
+    }
+    { bbl.volume
+      capitalize
+      swap$ tie.or.space.prefix "volume" bibinfo.check * * bbl.of space.word *
+    }
+  if$
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.incoll.inproc.crossref}
+{
+  word.in
+  " \cite{" * crossref * "}" *
+}
+FUNCTION {format.org.or.pub}
+{ 't :=
+  ""
+  address empty$ t empty$ and
+    'skip$
+    {
+      t empty$
+        { address "address" bibinfo.check *
+        }
+        { t *
+          address empty$
+            'skip$
+            { ", " * address "address" bibinfo.check * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+FUNCTION {format.publisher.address}
+{ publisher "publisher" bibinfo.warn format.org.or.pub
+}
+
+FUNCTION {format.organization.address}
+{ organization "organization" bibinfo.check format.org.or.pub
+}
+
+STRINGS {oldname}
+
+FUNCTION {name.or.dash}
+{ 's :=
+   oldname empty$
+     { s 'oldname := s }
+     { s oldname =
+         { "---{}---{}---" }
+         { s 'oldname := s }
+       if$
+     }
+   if$
+}
+
+FUNCTION {article}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    {
+      journal
+      "journal" bibinfo.check
+      emphasize
+      "journal" output.check
+      format.vol.num.pages output
+  format.doi output
+    }
+    { format.article.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {book}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      add.blank
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    { format.bvolume output
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {booklet}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  address "address" bibinfo.check output
+  format.book.pages output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {inbook}
+{ output.bibitem
+  author empty$
+    { format.editors "author and editor" output.check
+      editor format.key output
+      name.or.dash
+    }
+    { format.authors output.nonnull
+      name.or.dash
+      crossref missing$
+        { "author and editor" editor either.or.check }
+        'skip$
+      if$
+    }
+  if$
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  crossref missing$
+    {
+      format.bvolume output
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.edition output
+      format.number.series output
+      format.publisher.address output
+    }
+    {
+      format.chapter.pages "chapter and pages" output.check
+  new.sentence
+      format.book.crossref output.nonnull
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {incollection}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      format.publisher.address output      
+      format.bvolume output
+      format.number.series output
+      format.edition output
+      format.chapter.pages output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.chapter.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {inproceedings}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  new.sentence
+  crossref missing$
+    { format.in.ed.booktitle "booktitle" output.check
+      publisher empty$
+        { format.organization.address output }
+        { organization "organization" bibinfo.check output
+          format.publisher.address output
+        }
+      if$
+      format.bvolume output
+      format.pages output
+      format.number.series output
+      howpublished "howpublished" bibinfo.check output
+    }
+    { format.incoll.inproc.crossref output.nonnull
+      format.pages output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {conference} { inproceedings }
+FUNCTION {manual}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  new.sentence
+  organization "organization" bibinfo.check output
+  address "address" bibinfo.check output
+  format.edition output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {mastersthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.mthesis format.thesis.type output.nonnull
+  department "department" bibinfo.warn output
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {misc}
+{ output.bibitem
+  format.authors output
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title output
+  new.sentence
+  howpublished "howpublished" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+FUNCTION {phdthesis}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  bbl.phdthesis format.thesis.type output.nonnull
+  school "school" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {proceedings}
+{ output.bibitem
+  format.editors output
+  editor format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.btitle "title" output.check
+  format.bvolume output
+  format.number.series output
+  publisher empty$
+    { format.organization.address output }
+    { organization "organization" bibinfo.check output
+      format.publisher.address output
+    }
+  if$
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {techreport}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title
+  "title" output.check
+  new.sentence
+  format.tr.number output.nonnull
+  institution "institution" bibinfo.warn output
+  address "address" bibinfo.check output
+  format.doi output
+  format.note output
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {unpublished}
+{ output.bibitem
+  format.authors "author" output.check
+  author format.key output
+  name.or.dash
+  format.date "year" output.check
+  date.block
+  format.title "title" output.check
+  format.doi output
+  format.note "note" output.check
+  format.eprint output
+  fin.entry
+}
+
+FUNCTION {default.type} { misc }
+READ
+FUNCTION {sortify}
+{ purify$
+  "l" change.case$
+}
+INTEGERS { len }
+FUNCTION {chop.word}
+{ 's :=
+  'len :=
+  s #1 len substring$ =
+    { s len #1 + global.max$ substring$ }
+    's
+  if$
+}
+FUNCTION {format.lab.names}
+{ 's :=
+  "" 't :=
+  s #1 "{vv~}{ll}" format.name$
+  s num.names$ duplicate$
+  #2 >
+    { pop$
+      " " * bbl.etal *
+    }
+    { #2 <
+        'skip$
+        { s #2 "{ff }{vv }{ll}{ jj}" format.name$ "others" =
+            {
+              " " * bbl.etal *
+            }
+            { bbl.and space.word * s #2 "{vv~}{ll}" format.name$
+              * }
+          if$
+        }
+      if$
+    }
+  if$
+}
+
+FUNCTION {author.key.label}
+{ author empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {author.editor.key.label}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { cite$ #1 #3 substring$ }
+            'key
+          if$
+        }
+        { editor format.lab.names }
+      if$
+    }
+    { author format.lab.names }
+  if$
+}
+
+FUNCTION {editor.key.label}
+{ editor empty$
+    { key empty$
+        { cite$ #1 #3 substring$ }
+        'key
+      if$
+    }
+    { editor format.lab.names }
+  if$
+}
+
+FUNCTION {calc.short.authors}
+{ type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.key.label
+    { type$ "proceedings" =
+        'editor.key.label
+        'author.key.label
+      if$
+    }
+  if$
+  'short.list :=
+}
+
+FUNCTION {calc.label}
+{ calc.short.authors
+  short.list
+  "("
+  *
+  year duplicate$ empty$
+     { pop$ "????" }
+     { purify$ #-1 #4 substring$ }
+  if$
+  *
+  'label :=
+}
+
+FUNCTION {sort.format.names}
+{ 's :=
+  #1 'nameptr :=
+  ""
+  s num.names$ 'numnames :=
+  numnames 'namesleft :=
+    { namesleft #0 > }
+    { s nameptr
+      "{vv{ } }{ll{ }}{  f{ }}{  jj{ }}"
+      format.name$ 't :=
+      nameptr #1 >
+        {
+          "   "  *
+          namesleft #1 = t "others" = and
+            { "zzzzz" * }
+            { t sortify * }
+          if$
+        }
+        { t sortify * }
+      if$
+      nameptr #1 + 'nameptr :=
+      namesleft #1 - 'namesleft :=
+    }
+  while$
+}
+
+FUNCTION {sort.format.title}
+{ 't :=
+  "A " #2
+    "An " #3
+      "The " #4 t chop.word
+    chop.word
+  chop.word
+  sortify
+  #1 global.max$ substring$
+}
+FUNCTION {author.sort}
+{ author empty$
+    { key empty$
+        { "to sort, need author or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {author.editor.sort}
+{ author empty$
+    { editor empty$
+        { key empty$
+            { "to sort, need author, editor, or key in " cite$ * warning$
+              ""
+            }
+            { key sortify }
+          if$
+        }
+        { editor sort.format.names }
+      if$
+    }
+    { author sort.format.names }
+  if$
+}
+FUNCTION {editor.sort}
+{ editor empty$
+    { key empty$
+        { "to sort, need editor or key in " cite$ * warning$
+          ""
+        }
+        { key sortify }
+      if$
+    }
+    { editor sort.format.names }
+  if$
+}
+FUNCTION {presort}
+{ calc.label
+  label sortify
+  "    "
+  *
+  type$ "book" =
+  type$ "inbook" =
+  or
+    'author.editor.sort
+    { type$ "proceedings" =
+        'editor.sort
+        'author.sort
+      if$
+    }
+  if$
+  #1 entry.max$ substring$
+  'sort.label :=
+  sort.label
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+
+ITERATE {presort}
+SORT
+STRINGS { last.label next.extra }
+INTEGERS { last.extra.num number.label }
+FUNCTION {initialize.extra.label.stuff}
+{ #0 int.to.chr$ 'last.label :=
+  "" 'next.extra :=
+  #0 'last.extra.num :=
+  #0 'number.label :=
+}
+FUNCTION {forward.pass}
+{ last.label label =
+    { last.extra.num #1 + 'last.extra.num :=
+      last.extra.num int.to.chr$ 'extra.label :=
+    }
+    { "a" chr.to.int$ 'last.extra.num :=
+      "" 'extra.label :=
+      label 'last.label :=
+    }
+  if$
+  number.label #1 + 'number.label :=
+}
+FUNCTION {reverse.pass}
+{ next.extra "b" =
+    { "a" 'extra.label := }
+    'skip$
+  if$
+  extra.label 'next.extra :=
+  extra.label
+  duplicate$ empty$
+    'skip$
+    { "{\natexlab{" swap$ * "}}" * }
+  if$
+  'extra.label :=
+  label extra.label * 'label :=
+}
+EXECUTE {initialize.extra.label.stuff}
+ITERATE {forward.pass}
+REVERSE {reverse.pass}
+FUNCTION {bib.sort.order}
+{ sort.label
+  "    "
+  *
+  year field.or.null sortify
+  *
+  "    "
+  *
+  title field.or.null
+  sort.format.title
+  *
+  #1 entry.max$ substring$
+  'sort.key$ :=
+}
+ITERATE {bib.sort.order}
+SORT
+FUNCTION {begin.bib}
+{ preamble$ empty$
+    'skip$
+    { preamble$ write$ newline$ }
+  if$
+  "\begin{thebibliography}{" number.label int.to.str$ * "}" *
+  write$ newline$
+  "\providecommand{\natexlab}[1]{#1}"
+  write$ newline$
+  "\providecommand{\url}[1]{\texttt{#1}}"
+  write$ newline$
+  "\providecommand{\urlprefix}{URL }"
+  write$ newline$
+  "\expandafter\ifx\csname urlstyle\endcsname\relax"
+  write$ newline$
+  "  \providecommand{\doi}[1]{doi:\discretionary{}{}{}#1}\else"
+  write$ newline$
+  "  \providecommand{\doi}{doi:\discretionary{}{}{}\begingroup \urlstyle{rm}\Url}\fi"
+  write$ newline$
+  "\providecommand{\eprint}[2][]{\url{#2}}"
+  write$ newline$
+}
+EXECUTE {begin.bib}
+EXECUTE {init.state.consts}
+ITERATE {call.type$}
+FUNCTION {end.bib}
+{ newline$
+  "\end{thebibliography}" write$ newline$
+}
+EXECUTE {end.bib}
+%% End of customized bst file
+%%
+%% End of file `ametsoc7.bst'.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_bdy_agrif.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_bdy_agrif.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_bdy_agrif.tex	(revision 10321)
@@ -0,0 +1,16 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 11 - BDY and AGRIF with SI$^3$
+% ================================================================
+
+\chapter{BDY and AGRIF with SI$^3$}
+\label{chap:REG}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_domain.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_domain.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_domain.tex	(revision 10321)
@@ -0,0 +1,106 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 2 Ñ Domain
+% ================================================================
+
+\chapter{Time, space and thickness space domain}
+\label{chap:DOM}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+Having defined the model equations in previous Chapter, we need now to choose the numerical discretization.  In the present chapter, we provide a general description of the SI$^3$ discretization strategy, in terms of time, space and thickness, which is considered as an extra independent variable. 
+
+Sea ice state variables are typically expressed as:
+\begin{equation}
+X(ji,jj,\textcolor{gray}{jk},jl).
+\end{equation}
+$ji$ and $jj$ are x-y spatial indices, as in the ocean. $jk=1, ..., nlay\_i$ corresponds to the vertical coordinate system in sea ice (ice layers), and only applies to vertically-resolved quantities (ice enthalpy and salinity). $jl=1, ..., jpl$ corresponds to the ice categories, discretizing thickness space.
+
+\section{Time domain}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Time Stepping
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{../Figures/time_stepping.png}
+\caption{Schematic representation of time stepping in SI$^3$, assuming $nn\_fsbc=5$.}
+\label{ice_scheme}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The sea ice time stepping is synchronized with that of the ocean. Because of the potentially large numerical cost of sea ice physics, in particular rheology, SI$^3$ can be called every nn\_fsbc time steps (namsbc in \textit{namelist\_ref}). The sea ice time step is therefore $rdt\_ice = rdt * nn\_fsbc$. In terms of quality, the best value for \textit{nn\_fsbc} is 1, providing full consistency between sea ice and oceanic fields. Larger values (typically 2 to 5) can be used but numerical instabilities can appear because of the progressive decoupling between the state of sea ice and that of the ocean, hence changing $nn\_fsbc$ must be done carefully.
+
+Ice dynamics (rheology, advection, ridging/rafting) and thermodynamics are called successively. To avoid pathological situations, thermodynamics were chosen to be applied on fields that have been updated by dynamics, in a somehow semi-implicit procedure.
+
+There are a few iterative / subcycling procedures throughout the code, notably for rheology, advection, ridging/ rafting and the diffusion of heat. In some cases, the arrays at the beginning of the sea ice time step are required. Those are referred to as $X\_b$.
+
+\section{Spatial domain}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIGx : Vertical grid
+%
+%
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{../Figures/thermogrid.eps}
+\caption{\footnotesize{Vertical grid of the model, used to resolve vertical temperature and salinity profiles}}\label{fig_dom_icelayers}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The horizontal indices $ji$ and $jj$ are handled as for the ocean in NEMO, assuming C-grid discretization and in most cases a finite difference expression for scale factors.
+
+The vertical index $jk=1, ..., nlay\_i$ is used for enthalpy (temperature) and salinity. In each ice category, the temperature and salinity profiles are vertically resolved over $nlay\_i$ equally-spaced layers. The number of snow layers can currently only be set to $nlay\_s=1$ (Fig. \ref{fig_dom_icelayers}).
+
+To increase numerical efficiency of the code, the two horizontal dimensions of an array $X(ji,jj,jk,jl)$ are collapsed into one (array $X\_1d(ji,jk,jl)$) for thermodynamic computations, and re-expanded afterwards.
+
+\forfile{../namelists/nampar}
+
+\section{Thickness space domain}
+
+\forfile{../namelists/namitd}
+
+Thickness space is discretized using $jl=1, ..., jpl$ thickness categories, with prescribed boundaries $hi\_max(jl-1),hi\_max(jl)$. Following \cite{Lipscomb01}, ice thickness can freely evolve between these boundaries. The number of ice categories $jpl$ can be adjusted from the namelist ($nampar$).
+
+There are two means to specify the position of the thickness boundaries of ice categories. The first option (ln\_cat\_hfn) is to use a fitting function that places the category boundaries between 0 and 3$\overline h$, with $\overline h$ the expected mean ice thickness over the domain (namelist parameter rn\_himean), and with a greater resolution for thin ice (Fig. \ref{fig_dom_icecats}). More specifically, the upper limits for ice in category $jl=1, ..., jpl-1$ are:
+\begin{eqnarray} 
+hi\_max(jl) = \biggr ( \frac{jl \cdot (3\overline h + 1 )^{\alpha}}{ (jpl-jl)(3 \overline h + 1)^{\alpha} + jl }\biggr )^{\alpha^{-1}} - 1,
+\end{eqnarray}
+with $hi\_max(0)$=0 m and $\alpha = 0.05$. The last category has no upper boundary, so that it can contain arbitrarily thick ice.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIGx : Ice categories
+%
+%
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{../Figures/ice_cats.eps}
+\caption{\footnotesize{Boundaries of the model ice thickness categories (m) for varying number of categories and prescribed mean thickness ($\overline h$). The formerly used $tanh$ formulation is also depicted.}}\label{fig_dom_icecats}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The other option (ln\_cat\_usr) is to specify category boundaries by hand using rn\_catbnd. The first category must always be thickner than rn\_himin (0.1 m by default).
+
+The choice of ice categories is important, because it constraints the ability of the model to resolve the ice thickness distribution. The latest study \citep{Massonnetetal18b} recommends to use at least 5 categories, which should include one thick ice with lower bounds at $\sim$4 m and $\sim$2 m for the Arctic and Antarctic, respectively, for allowing the storage of deformed ice.
+
+With a fixed number of cores, the cost of the model linearly increases with the number of ice categories. Using $jpl=1$ single ice category is also much cheaper than with 5 categories, but seriously deteriorates the ability of the model to grow and melt ice. Indeed, thin ice thicknes faster than thick ice, and shrinks more rapidly as well. When nn\_virtual\_itd=1 ($jpl$ = 1 only), two parameterizations are activated to compensate for these shortcomings. Heat conduction and areal decay of melting ice are adjusted to closely approach the 5 categories case.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_dynamics.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_dynamics.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_dynamics.tex	(revision 10321)
@@ -0,0 +1,35 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 3 Ñ Ice dynamics
+% ================================================================
+
+\chapter{Ice dynamics}
+\label{chap:DYN}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+In this chapter, we describe how the momentum equation is solved.
+
+I guess we could be brief. Gurvan and Clem should take the lead to write this.
+
+1) aEVP approach, revisited by Bouillon et al (2013).
+
+2) Short description of the numerical method. NEMO scale factors.
+
+3) Landfast ice option
+
+4) Boundary conditions (free-slip, no-slip, ...)
+
+4) Practical use of namelist parameters (nevp, telast, ...).
+
+\end{document}
+
+
+
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_interfaces.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_interfaces.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_interfaces.tex	(revision 10321)
@@ -0,0 +1,30 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 8 Ñ Interfaces
+% ================================================================
+
+\chapter{Ice-atmosphere and ice-ocean interfaces}
+\label{chap:INT}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+In this chapter, we give information on the representation of interfaces.
+
+\section{Ice-ocean interface}
+
+\section{Ice-atmosphere interface}
+
+Drags?
+
+Blowing snow parameter
+
+Flux redistributor
+
+Jules coupling
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_miscellaneous.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_miscellaneous.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_miscellaneous.tex	(revision 10321)
@@ -0,0 +1,18 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 12 -Miscellaneous
+% ================================================================
+
+\chapter{Miscellaneous topics}
+\label{chap:MIS}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+getting started, namelists, configs, ...
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_model_basics.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_model_basics.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_model_basics.tex	(revision 10321)
@@ -0,0 +1,457 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+% ================================================================
+% Chapter 1 Ñ Model Basics
+% ================================================================
+
+\chapter{Model Basics}
+\label{chap:MB}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+%-------------------------------------------------------------------------------------------------------------------------
+%
+% 2.1 Assumptions
+\section{Rationale and assumptions}
+%
+%-------------------------------------------------------------------------------------------------------------------------
+\begin{itemize}
+\item Separation of horizontal dynamics and vertical thermodynamics;
+\item Dynamics: sea ice is a viscous-plastic continuum;
+\item Thermodynamics: sea ice is a mushy layer covered by snow
+\item Subgrid-scale physics
+\end{itemize}
+
+\subsection{Scales, thermodynamics and dynamics}
+Because sea ice is much wider -- $\mathcal{O}$(100-1000 km) -- than thick -- $\mathcal{O}$(1 m) -- ice drift can be considered as purely horizontal: vertical motions around the hydrostatic equilibrium position are negligible. The same scaling argument justifies the assumption that heat exchanges are purely vertical\footnote{The latter assumption is probably less valid, because the horizontal scales of temperature variations are $\mathcal{O}$(10-100 m)}. It is on this basis that thermodynamics and dynamics are separated and rely upon different frameworks and sets of hypotheses: thermodynamics use the ice thickness distribution \citep{Thorndikeetal75} and the mushy-layer \citep{Worster92} frameworks, whereas dynamics assume continuum mechanics \citep[e.g.,][]{Lepparanta05}. Thermodynamics and dynamics interact by two means: first, advection impacts state variables; second, the horizontal momentum equation depends, among other things, on the ice state.
+
+\subsection{Subgrid scale variations}
+
+Sea ice properties -- in particular ice thickness -- feature important changes at horizontal scales $\mathcal{O}$(1m) \citep{Thorndikeetal75}. An explicit representation of these variations is not and will not be -- at least in the next twenty years or so -- accessible to large-scale sea ice models. Yet important features, such as energy exchanges through the ice, quite non-linearly depend on ice thickness \citep{Maykut86}; whereas ice motion depends on the presence of open water, thin and thick ice at the very least, suggesting that subgrid-scale variations in ice properties must be accounted for, at least in a statistical fashion \citep{MaykutThorndike73}. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice scheme
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{../Figures/ice_scheme.png}
+\caption{Representation of the ice pack, using multiple categories with specific ice concentration ($a_l, l=1, 2, ..., L$), thickness ($h^i_l$), snow depth ($h^s_l$), vertical temperature and salinity profiles ($T^i_{kl}$, $S^{*}_{kl}$) and a single ice velocity vector ($\bm{u}$).}
+\label{ice_scheme}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The \textit{multi-category} framework \citep{MaykutThorndike73} addresses this issue by treating the ice thickness as an independent variable next to spatial coordinates and time, and introducing a thickness distribution\footnote{$g(h)$, termed the \textit{ice thickness distribution} is the density of probability of ice thickness \citep{Thorndikeetal75}.} $g(h)$ as the main prognostic model field. In the discrete world, the thickness distribution is converted into $L$ thickness categories. Ice thickness categories occupy a fraction of each grid cell, termed ice concentration ($a_l, l=1, 2, ..., L$), with specific thickness and properties. 
+
+The \textit{single-category} framework \citep{Hibler79} tackles the subgrid-scale issue by drastically simplifying the ice thickness distribution. The grid cell is divided into open water and sea ice characterized by a single ice concentration $A$ and mean thickness $H$. Single-category models (in particular LIM2) typically add parameterizations to represent the effects of unresolved ice thickness distribution on ice growth and melt \citep[see, e.g.][]{MellorKantha89,FichefetMaqueda97}.
+
+SI$^3$ provides the choice between either a multi- or a single-category framework. The default mode is multi-category. The single-category mode can be activated by setting the number of categories ($jpl=1$) and by activating the virtual thickness distribution parameterizations (nn\_monocat=1).
+
+\subsection{Thermodynamic formulation}
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Physical constants
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Thermodynamic constants of the model.}
+\begin{center}
+\begin{tabular}{@{}llccl}\hline
+ & Description & Value & Units & Ref \\ \hline
+$c_i$ (cpic) & Pure ice specific heat & 2067 & J/kg/K & ? \\
+$c_w$ (rcp) & Seawater specific heat & 3991 & J/kg/K & \cite{TEOS-10} \\
+$L$ (lfus) & Latent heat of fusion (0$^\circ$C) & 334000 & J/kg/K & \cite{BitzLipscomb99} \\
+$\rho_i$ (rhoic) & Sea ice density & 917 & kg/m$^3$ & \cite{BitzLipscomb99} \\
+$\rho_s$ (rhosn) & Snow density & 330 & kg/m$^3$ & \cite{MaykutUntersteiner71} \\
+$\mu$ (tmut) & Linear liquidus coefficient & 0.054 & $^\circ$C/(g/kg) & \cite{Assur58} \\
+\hline
+\end{tabular}
+\end{center}
+\label{PhysicalConstants_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+
+Ice thermodynamics are formulated assuming that sea ice is covered by snow. Within each thickness category, both snow and sea ice are horizontally uniform, hence each thickness category has a specific ice thickness ($h_i^l$) and snow depth ($h_s^l$). Snow is assumed to be fresh, with constant density and thermal conductivity. Sea ice is assumed to be a \textit{mushy layer}\footnote{Mushy layers are two-phase, two-component porous media.} \citep{Worster92} of constant density, made of pure ice and brine in thermal equilibrium, related by a linear liquidus relationship \citep{BitzLipscomb99}. A vertically-averaged bulk salinity $S_l$ uniquely characterizes brine fraction for each thickness category, and changes through  time from a simple parametrization of brine drainage. The linear vertical salinity profile ($S^*_{kl}$) is reconstructed from the vertical mean \citep{Vancoppenolleetal09b}. The diffusion of heat affects the vertical temperature profile, discretized on a unique layer of snow and multiple ice layers (typically 2-5) for each category, whereas thermal properties depend on local brine fraction. Growth and melt rates are computed, also for each ice category. The choice of the main thermodynamic constants  is described in Tab. \ref{PhysicalConstants_table}.
+
+
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Global variables
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{LIM global variables.}
+\begin{center}
+\begin{tabular}{@{}llcc}\hline
+Symbol   & Description & Units & Code name \\ \hline
+$\mathbf{u}$ & Sea ice velocity & [$m.s^{-1}$] & \textit{u\_ice, v\_ice (ji,jj)} \\
+$\mathbf{\sigma}$ & Stress tensor & [$Pa.m$] & \textit{stress1\_i, stress2\_i} \\
+ & & & \textit{stress12\_i (ji,jj)} \\
+$a_l$ & Concentration of sea ice in category $l$ & [-] & \textit{a\_i(ji,jj,jl)} \\
+$v^i_l$ & Volume of sea ice per unit area in category $l$ & [$m$] & \textit{v\_i(ji,jj,jl)} \\
+$v^s_l$ & Volume of snow per unit area in category $l$ & [$m$] & \textit{v\_s(ji,jj,jl)} \\
+$e^i_{kl}$ & Sea ice enthalpy per unit area in layer $k$ and category $l$ & [$J.m^{-2}$] & \textit{e\_i(ji,jj,jk,jl)} \\
+$e^s_{l}$ & Snow enthalpy per unit area in category $l$ & [$J.m^{-2}$] & \textit{e\_s(ji,jj,jl)} \\
+$M^s_l$ & Sea ice salt content in category $l$ & [$g/kg.m$] & \textit{smv\_i(ji,jj,jl)}\\
+%$O_l$ & Sea ice age content in category $l$ & $[days.m]$ \\
+\hline
+\end{tabular}
+\end{center}
+\label{GVariables_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+ Temperature, salinity, ice thickness, and snow depth are not extensive variables and therefore not conservative. Hence, conservative, extensive variables, must be introduced to ensure mass, salt and energy conservation. There are several back-and-forth conversions from extensive (conservative) state variables (see Table \ref{GVariables_table}) to intensive state variables of practical use (Table \ref{IVariables_table}).
+ 
+ %--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Equivalent variables
+%
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Intensive variables of practical use.}
+\begin{center}
+\begin{tabular}{@{}llcc}\hline
+Symbol   & Description & Units \\ \hline
+$h^i_l=v^i_l/g^i_l$ & Ice thickness & [$m$] \\
+$h^s_l=v^s_l/g^i_l$ & Snow depth & [$m$] \\
+$q^i_{m,kl}=e^i_{l,k}/(h^i_l/N)$ & Ice specific enthalpy & [$J.kg^{-1}$]\\
+$q^s_{m,l}=e^s_{l}/h^s_l$ & Snow specific enthalpy & [$J.kg^{-1}$] \\
+$T^i_{kl}=T(q^i_{kl})$ & Ice temperature & [$K$] \\
+$T^s_{l} =T(q^s_{l}) $ & Snow temperature & [$K$] \\
+$\overline S^i_{l}=M^s_l / v^i_l$ & Vertically-averaged bulk ice salinity & [g/kg] \\
+$S^*_{kl}$ & Depth-dependent ice salinity & [g/kg] \\
+$\phi_{kl}$ & Brine fraction & [-] \\
+%$o^i_{l}=O_l / g^i_l $ & Ice age & [$days$] \\
+\hline
+\end{tabular}
+\end{center}
+\label{IVariables_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+\subsection{Dynamic formulation}
+
+The formulation of ice dynamics is based on the continuum approach. The latter holds provided the drift ice particles are much larger than single ice floes, and much smaller than typical gradient scales. This compromise is rarely achieved in practice \citep{Lepparanta05}. Yet the continuum approach generates a convenient momentum equation for the horizontal ice velocity vector $\mathbf{u}=(u,v)$, which can be solved with classical numerical methods (here, finite differences on the NEMO C-grid). The most important term in the momentum equation is internal stress. We follow the viscous-plastic (VP) rheological framework \citep{Hibler79}, assuming that sea ice has no tensile strength but responds to compressive and shear deformations in a plastic way. In practice, the elastic-viscous-plastic (EVP) technique of  \citep{Bouillonetal13} is used, more convient numerically than VP.  It is well accepted that the VP rheology and its relatives are the minimum complexity to get reasonable ice drift patterns \citep{Kreyscheretal00}, but fail at generating the observed deformation patterns \citep{Girardetal09}. This is a long-lasting problem: what is the ideal rheological model for sea ice and how it should be applied are still being debated \citep[see, e.g.][]{Weiss13}. 
+
+%-------------------------------------------------------------------------------------------------------------------------
+%
+\section{Thickness distribution framework}
+%
+%-------------------------------------------------------------------------------------------------------------------------
+
+We first present the essentials of the thickness distribution framework \citep{Thorndikeetal75}. Consider a given region of area $R$ centered at spatial coordinates $(\bm{x})$ at a given time $t$. $R$ could be e.g. a model grid cell. The ice thickness distribution $g(\mathbf{x},t, h)$ is introduced as follows:
+\begin{linenomath}
+\begin{align}
+g(h) &= \lim_{dh \to 0} \frac{dA(h,h+dh)}{dh},
+\end{align}
+\end{linenomath}
+where $dA(h,h+dh)$ is the surface fraction of all parts of $R$ with ice thickness between $h$ and $h+dh$. Using this definition, the spatial structure of ice thickness is lost (see Fig. \ref{fig_g_h}), and $h$ becomes an extra independent variable, next to spatial coordinates and time, that can be thought as random. $g$ is by definition normalized to 1. The conservation of area, expressed in terms of $g(h)$, is given by \citep{Thorndikeetal75}: 
+\begin{linenomath}
+\begin{align}
+\frac{\partial g}{\partial t} = - \nabla .(g \mathbf{u}) - \frac{\partial}{\partial h} (f g) + \psi,
+\label{eq:gt}
+\end{align}
+\end{linenomath}
+where the terms on the right hand side refer to horizontal transport, thermodynamic transport in thickness space ($f$, m/s is the growth/melt rate), and mechanical redistribution rate, e.g. by ridging and rafting, where $\psi$ must conserve ice area and volume by construction.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice thickness distribution
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{../Figures/g_h.png}
+\caption{Representation of the relation between real thickness profiles and the ice thickness distribution function $g(h)$}
+\label{fig_g_h}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+In numerical implementations, the thickness distribution is discretized into several thickness categories, with specific ice concentration $a_l$ and ice volume per area $v_l^i$:
+\begin{linenomath}
+\begin{align}
+a_l &= \int _{H^*_{l-1}}^{H^*_l} dh \cdot g(h) , \\
+v_l^i &= \int _{H^*_{l-1}}^{H^*_l} dh \cdot h \cdot g(h).
+\end{align}
+\end{linenomath}
+Ice volume per area is the extensive counterpart for ice thickness, connected with volume through $h_l^i = v_l^i / a_l$. Evolution equations for extensive variables can be readily derived from equation \ref{eq:gt} by integration between thickness boundaries of the $l^{th}$ category \citep{Bitzetal01}. This applies to all model extensive variables (see Table \ref{GVariables_table}). For ice area, this reads:
+\begin{linenomath}
+\begin{align}
+\frac{\partial a_l}{\partial t} = - \bm{\nabla} \cdot (a_l \mathbf{u}) + \Theta^a_l + \int_{H^*_{l-1}}^{H^*_l} dh \psi.
+\label{eq:gt}
+\end{align}
+\end{linenomath}
+wher $\Theta^a_l$ refers to the effect of thermodynamics. Enthalpy is a particular case because it also has a vertical depth dependence $z$, which corresponds to $K$ vertical layers of equal thickness. The solution adopted here, following from \cite{ZhangRothrock01}, is that enthalpy from the individual layers are conserved separately. This is a practical solution, for lack of better.
+
+One of the major actions of LIM is to resolve conservation equations for all extensive variables that characterize the ice state.  Let us now connect this detailed information with classical sea ice fields. The ice concentration $A$ and the ice volume per area\footnote{Ice volume per area is equivalent to the grid-cell averaged ice thickness.} $V_i$ (m) directly derive from $g$: 
+\begin{linenomath}
+\begin{align}
+ A(\bm{x},t) &=\int_{0^+}^{\infty} dh \cdot g(h,\bm{x},t) \sim A_{ij} = \sum_{l=1}^L a_{ijl}, & \\
+ V_i(\bm{x},t)&=\int_{0}^{\infty} dh \cdot g(h,\bm{x},t) \cdot h \sim V^i_{ij} = \sum_{l=1}^L v^i_{ijl}. & \\
+\end{align}
+\end{linenomath}
+where the $0^+$ boundary implies that the means exclude open water. The mean ice thicknesses $H_i$ (m) is:
+\begin{linenomath}
+\begin{align}
+H_i = V_i/A,
+\end{align}
+\end{linenomath}
+whereas the open water fraction is simply $1-A$.
+
+\section{Governing equations}
+
+Let us now readily present the set of the LIM "governing" equations in the framework of the assumptions developed above. The conservation of horizontal momentum reads:
+\begin{linenomath}
+\begin{align}
+m \frac{\partial \bm{u}} {\partial t} & = \bm{\nabla}\cdot\bm{\sigma} +A \left(\bm{\tau}_{a}+\bm{\tau}_{w}\right) - m f \bm{k} \times \bm{u} - m g \bm{\nabla}{\eta},
+\label{a}
+\end{align}
+\end{linenomath}
+where $m=\rho_i V_i + \rho_s V_s $ is the ice and snow mass per unit area, $\bm{u}$ is the ice velocity, $\bm{\sigma}$ is the internal stress tensor, $\bm{\tau}_a$ and $\bm{\tau}_w$ are the air and ocean stresses, respectively, $f$ is the Coriolis parameter, $\bm{k}$ is a unit vector pointing upwards, $g$ is the gravity acceleration and $\eta$ is the ocean surface elevation. The EVP approach used in LIM \citep{Bouillonetal13} gives the stress tensor as a function of the strain rate tensor $\dot{\bm{\epsilon}}$ and some of the sea ice state variables:
+\begin{linenomath}
+\begin{align}
+\bm{\sigma} & = \bm{\sigma} (\dot{ \bm{\epsilon}}, \text{ice state}).
+\end{align}
+\end{linenomath}
+To the exception of velocity and internal stress, all extensive variables in Table \ref{GVariables_table} follow a conservation equation of the form:
+\begin{linenomath}
+\begin{align}
+\frac{\partial X}{\partial t} & = - \nabla .(\mathbf{u}X) + \Theta^X + \Psi^X,
+\label{eq:Xt}
+\end{align}
+\end{linenomath}
+including the effets of transport, thermodynamics ($\Theta^X$) and mechanical redistribution ($\Psi^X$). Solving these $jpl.(4+2.jpk)$ equations gives the temporal evolution of $\bm{u}$, $\bm{\sigma}$ and the rest of the global (extensive) variables listed in Table \ref{GVariables_table}.
+
+\section{Ice Dynamics}
+
+Dynamical processes include the conservation of momentum, rheology, transport and mechanical redistribution.
+To resolve the momentum equation, atmospheric stress is taken either as forcing or from an atmospheric model, oceanic stress and sea surface elevation from the ocean model, the Coriolis term is trivial. The last term, the divergence of the internal stress tensor $\sigma$, is the most critical term in the momentum equation and requires a rheological formulation. The EVP approach used in LIM gives the stress tensor components as \citep{Bouillonetal13}:
+\begin{linenomath}
+\begin{align}
+\sigma_{ij} & = \frac{P}{2(\Delta + \Delta_{min}) }
+\biggr [ ( \dot{\epsilon}_{kk} - \Delta) \delta_{ij} + \frac{1}{e^2} ( 2 \dot{\epsilon}_{ij} - \dot{\epsilon}_{kk} \delta_{ij} ) \biggr ],
+\end{align}
+\end{linenomath}
+where $\Delta$ is a particular measure of the deformation rate, $\Delta_{min}$ a parameter determining a smooth transition from pure viscous vlow ($\Delta<<\Delta_{min}$) to pure plastic flow ($\Delta >> \Delta_{min}$), and $e$ is a parameter giving the ratio between the maximum compressive stress and twice the maximum shear stress. In the pure plastic regime, the stress principal components should lie on the edge of an elliptical yield curve (Fig. \ref{fig_yield}). In the viscous regime, they are within the ellipse. The ice strength $P$ determines the plastic failure criterion and connects the momentum equation with the state of the sea ice. $P$ is not well constrained and must be parameterized. The heuristic option of \cite{Hibler79} was here adopted as a reference formulation:
+\begin{linenomath}
+\begin{align}
+P & = P^* V_i e^{-C(1-A)},
+\end{align}
+\end{linenomath}
+where $P^*$ and $C$ are empirical constants (see Table \ref{Modelparameters_table} for the values of the main model parameters).
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Ice thickness distribution
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{../Figures/yield_curve.png}
+\caption{Elliptical yield curve used in the VP rheologies, drawn in the space of the principal components of the stress tensor ($\sigma_1$ and $\sigma_2$).}
+\label{fig_yield}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+% TABLE x Model parameters %
+%
+\begin{table}[ht]
+\begin{footnotesize}
+\caption{Main model parameters.}
+\begin{center}
+\begin{tabular}{@{}llccl}\hline
+ & Description & Value & Units & Ref \\ \hline
+ 
+% Parameters
+$P*$ (rn\_pstar) & ice strength thickness param. & 20000 & N/m2 & - \\
+$C$ (rn\_crhg) & ice strength concentration param. & 20 & - & \citep{Hibler79} \\
+$H^*$ (rn\_hstar) & maximum ridged ice thickness param. & 25 & m & \citep{Lipscombetal07} \\
+$p$ (rn\_por\_rdg) & porosity of new ridges & 0.3 & - & \citep{Lepparantaetal95} \\
+$amax$ (rn\_amax) & maximum ice concentration & 0.999 & - & -\\
+$h_0$ (rn\_hnewice) & thickness of newly formed ice & 0.1 & m & - \\
+ 
+\hline
+\end{tabular}
+\end{center}
+\label{Modelparameters_table}
+\end{footnotesize}
+\end{table}
+%
+%--------------------------------------------------------------------------------------------------------------------
+%
+
+
+Transport connects the horizontal velocity fields and the rest of the ice properties. LIM assumes that the ice properties in the different thickness categories are transported at the same velocity. The scheme of \cite{Prather86}, based on the conservation of 0, 1$^{st}$ and 2$^{nd}$ order moments in $x-$ and $y-$directions,  is used, with some numerical diffusion if desired. Whereas this scheme is accurate, nearly conservative, it is also quite expensive since, for each advected field, five moments need to be advected, which proves CPU consuming, in particular when multiple categories are used. Other solutions are currently explored.
+
+The dissipation of energy associated with plastic failure under convergence and shear is accomplished by rafting (overriding of two ice plates) and ridging (breaking of an ice plate and subsequent piling of the broken ice blocks into pressure ridges). Thin ice preferentially rafts whereas thick ice preferentially ridges \citep{TuhkuriLensu02}. Because observations of these processes are limited, their representation in LIM is rather heuristic. The amount of ice that rafts/ridges depends on the strain rate tensor invariants (shear and divergence) as in \citep{FlatoHibler95}, while the ice categories involved are determined by a participation function favouring thin ice \citep{Lipscombetal07}. The thickness of ice being deformed ($h'$) determines whether ice rafts ($h'<$ 0.75 m) or ridges ($h'>$ 0.75 m), following \cite{Haapala00}. The deformed ice thickness is $2h'$ after rafting, and is distributed between $2h'$ and $2 \sqrt{H^*h'}$ after ridging, where $H^* = 25$ m \citep{Lipscombetal07}. Newly ridged ice is highly porous, effectively trapping seawater. To represent this, a prescribed volume fraction (30\%) of newly ridged ice \citep{Lepparantaetal95} incorporates mass, salt and heat are extracted from the ocean. Hence, in contrast with other models, the net thermodynamic ice production during convergence is not zero in LIM, since mass is added to sea ice during ridging. Consequently, simulated new ridges have high temperature and salinity as observed \citep{Hoyland02}. A fraction of snow (50 \%) falls into the ocean during deformation.
+
+\section{Ice thermodynamics}
+In this section, we develop the underlying principles of the thermodynamic formulation, summarized in the term $\Theta^X$, where $X$ refers to all extensive state variables. $\Theta^X$ includes the contributions of transport in thickness space and thermodynamic source and sink terms.
+
+\subsection{Transport in thickness space}
+Transport in thickness space describes how vertical growth and melt moves ice state variables among the different thicknesses at a velocity $f(h)$, the net ice growth/melt rate, which needs to be first computed.  In discretized form, this term moves ice properties between neighbouring categories. The linear remapping scheme of \cite{Lipscomb01} is used. This scheme is semi-lagrangian, second-order, is less diffusive and converges faster than other options.
+
+\subsection{Thermodynamic source and sink terms}
+
+Since heat, salt and mass are strongly inter-dependent for sea ice, the thermodynamic source and sink terms are treated together. They include the changes in extensive sea ice state associated with thermodynamic processes. The latter are separated in two main parts: (i) open water fraction processes, where atmosphere and ocean are in direct interaction; and (ii) vertical ice thermodynamic processes, driven by surface snow/ice-atmosphere and basal ice-ocean exchanges, for each thickness category. For each part, first, the energy available or lost is specified. Then the impact on mass exchanges is evaluated. The latter part requires to specify how sea ice and snow responds to energy supply or loss, which is achieved through the enthalpy formulation.
+
+%\subsubsection{Atmosphere-ice-ocean heat and mass exchanges}
+%
+%The atmosphere-ice heat exchanges are either specified in external files (forcing) or computed from an atmospheric model. The following heat and mass fluxes should be specified:
+%\begin{itemize}
+%\item Net solar flux, for open water ($Q^{sol}$) and ice categories ($Q^{sol,ice}_{l}$);
+%\item Net non-solar flux, for open water ($Q^{nsol}$) and ice categories ($Q^{nsol,ice}_{l}$);
+%\item Solid and liquid precipitation (kg/m$^2$/s).
+%\end{itemize}
+%
+%In terms of mass (freshwater), the ocean gets:
+%\begin{itemize}
+%\item All liquid precipitation;
+%\item The part of solid precipitation that is not intercepted by the ice, accounting for the part that is blown off the sea ice by winds;
+%\item The net melting minus freezing mass flux, as diagnosed from thermodynamic sea ice calculations.
+%\end{itemize}
+%
+%In terms of energy, the ocean gets:
+%\begin{itemize}
+%\item The net atmospheric solar flux, minus what is intercepted by the ice; plus what is transmitted below the ice; 
+%\item The net atmospheric non-solar heat flux, minus what is used by the sea ice; 
+%\item The sensible heat exchange associated with ice-ocean and atmosphere-ocean mass fluxes. 
+%\end{itemize}
+%
+%In terms of salt, the ocean gets the net salt release minus uptake associated with sea ice growth, melt and brine drainage. There is no atmosphere-ocean salt flux.
+
+\subsubsection{Enthalpy formulation}
+
+% Add snow and water
+
+A first overarching aspect of the thermodynamic calculations is the specification of the response of sea ice to energy supply. This is achieved by defining the internal energy (or enthalpy\footnote{Wording it internal energy or enthalpy is equivalent since pressure effects are not considered.}). This ultimately relies on the response of the phase composition to salinity and temperature changes. The enthalpy formulation used in LIM is based on the following assumptions:
+\begin{itemize}
+\item Sea ice is gas-free, composed solely of pure ice and saline brine, characterized by brine fraction $\phi$;
+\item brine and pure ice are in thermodynamic equilibrium;
+\item the salinity-dependence of the freezing point is linear (linear liquidus);
+\item the density of the sea ice (ice+brine) medium is constant ($\rho_i$).
+\end{itemize}
+%In this context, the bulk salinity of a small control sea ice volume is related to the salinity of brine ($S_{br}$):
+%\begin{linenomath}
+%\begin{align}
+%S = \phi S_{br}
+%\label{eq_S_Sbr}
+%\end{align}
+%\end{linenomath}
+%Because of thermal equilibrium and linear liquidus, brine salinity directly depends on local temperature: $T=-\mu S_{br}$. Hence, brine fraction is given by
+%\begin{linenomath}
+%\begin{align}
+%\phi = -\frac{\mu S}{T}.
+%\end{align}
+%\end{linenomath}
+%This equation relates brine fraction to bulk salinity and temperature, which therefore can be seen as the two main state variables in this linear mushy layer formulation for sea ice thermodynamics. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Thermal properties
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=8cm,angle=-00]{../Figures/Thermal_properties.png}
+\caption{Thermal properties of sea ice vs temperature for different bulk salinities: brine fraction, specific enthalpy, thermal conductivity, and effective specific heat.}
+\label{fig_thermal_properties}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Based on these, brine fraction reduces to $\phi = -\mu S/T$ (see Fig. \ref{fig_thermal_properties}), where $\mu$ relates the freezing point of brine to salinity, and one can derive the specific enthalpy $q_m(S,T)$, defined as the energy required to warm and melt a unit control volume of sea ice at temperature $T$ (in Celsius) and salinity $S$ until 0$^\circ$ C, taken as a reference zero-energy level \citep{BitzLipscomb99,Schmidtetal04}:
+\begin{linenomath}
+\begin{align}
+q_m(S,T) = \biggr [ c_i ( T + \mu S) - L \biggr ( 1 + \frac{\mu S}{T} \biggr ) - c_w \mu S \biggr ]
+\end{align}
+\end{linenomath}
+where $c_i$ is pure ice specific heat, $L$ is latent heat of fusion at 0$^\circ$C, and $c_w$ is water specific heat. The first term expresses the warming of solid ice. The second term expresses internal change in brine fraction, which is often the largest because the Stefan number  ($c_i T/L$) is generally small. The last term gives the warming of the remaining water from $T_{fr} = -\mu S$ until 0$^\circ$C. Similar, but simpler and linear expressions for snow and water can be derived.
+
+The second overarching aspect is that all growth and melt processes must be calculated consistently with the enthalpy formulation. Energetics of phase transitions are handled using the formalism of \cite{Schmidtetal04}. For each phase transition, initial and final states (temperature and salinity) are defined, and the ice-to-ocean mass flux to the ice $F_m$ (kg/s) relates to the energy gain or loss $\Delta Q$ through:
+\begin{linenomath}
+\begin{align}
+\Delta Q / \Delta q_m = F_m,
+\label{eq_phasechange}
+\end{align}
+\end{linenomath}
+where $\Delta q_m$ is the change in specific enthalpy involved in the considered phase transition, from initial to final state.
+
+
+\subsubsection{Open water processes}
+
+As part of the sea ice thermodynamic calculations, a heat budget estimate for the uppermost ocean level ($B^{opw}$) must be included, to compute the rate of new ice formation or the contribution of sensible heat to bottom melting. $B^{opw}$ includes:
+\begin{itemize}
+\item the absorption of a fraction $f_1^{qsr}$ of solar radiation (given by radiative transfer component of the ocean model);
+\item the non-solar heat flux absorbed at the surface;
+\item the sensible heat content of precipitation
+\item the sensible heat flux from the ocean to the sea ice ($A.F_w$)
+\end{itemize}
+Other contributions are not assumed not to contribute. The ocean-to-ice sensible heat flux is formulated the bulk formula of \citep{McPhee92}.
+
+% Ice growth
+If $B^{opw}$ is such that the SST would decrease below the freezing point, the remainder of the heat is used to form new ice. The heat loss is converted into a volume of new ice $v_0$. The thickness $h_0$ of the new ice grown during a sea ice time step depends on unresolved small-scale currents and waves and is prescribed. The fraction $a_0=v_0/h_0$ is computed accordingly. The salinity of this new ice $S_0$ is given by the salinity-thickness empirical relationship of \cite{Kovacs96}. The temperature assumed for this new ice is the local freezing point. If by contrast $B^{opw}$ is positive and there still is ice in the grid cell, then $B^{opw}$ is directly redirected to bottom melting. This argument follows from \cite{MaykutMcPhee95}, who found that most of solar heat absorbed in the surface waters is converted into melting. In practise, this prevents the SST to be above freezing as long ice is present.
+
+$B^{opw}$ can be seen as a predictor of the heat budget of the first ocean level. As such, it only helps to compute new ice formation and the extra bottom melt in summer, but is not part of the conservation of heat in the model. To ensure heat conservation, the heat effectively contributing to changing sea ice is removed from the non-solar flux sent to the ocean. This includes: (i) the heat loss used for ice formation, (ii) the heat gain used to melt ice, and (iii) the sensible heat given by the ocean to the ice. Finally, because ice dynamics are not able to maintain the small amount of open water that is observed, a maximum ice fraction ($amax, <1$) is prescribed.
+
+\subsubsection{Vertical ice thermodynamic processes}
+
+The second part of the computations regard the computation of purerly vertical processes in the ice-covered part of the grid cell, similarly for each ice category. 
+
+\textbf{Surface melt, basal growth and melt and diffusion of heat}. The surface melt rate, as well as the basal growth / melt rate depend on the energy budget at the upper and lower interfaces, respectively, between the external fluxes either from the atmosphere or the ocean, and the internal conduction fluxes. The internal conduction fluxes depend on the internal temperature profile, which is determined by solving the enthalpy equation:
+\begin{linenomath}
+\begin{align}
+\rho \frac{\partial q_m}{\partial t} = - \frac{\partial}{\partial z} (F_c + F_r ).
+\end{align}
+\end{linenomath}
+which state that the local change in enthalpy is given by the divergence of the vertical conduction ($F_c=-k(S,T) \partial T / \partial z$) and radiation ($F_r$) fluxes. $\rho$ is the density of ice or snow. Re-expressed as a function of temperature, this becomes the heat diffusion equation.  This equation is non-linear in $T$, because of $q$ and $k$, and its main specificity is that internal melting requires large amounts of energy near the freezing point. The thermal conductivity is formulated following \cite{Pringleetal07}, empirically accounting for the reduction of thermal conductivity at large brine fractions. 
+
+At the ice base, we assume that the temperature is at the local freezing point.  Ice grows or melt if the heat balance between the oceanic sensible heat flux ($F_w$) and internal conduction is negative or positive.
+
+At the ice surface, the boundary condition on the heat diffusion equation is:
+\begin{linenomath}
+\begin{align}
+Q^{sr}  + Q^{ns}(T_{su})= F_c + Q^{sum}.
+\end{align}
+\end{linenomath}
+where $Q^{sr}$ and $Q^{ns}$ are the net downwelling atmospheric solar and non-solar flux components. If the solution of this equation without melting gives a surface temperature ($T_{su}$) below 0$^\circ$ C, then there is no melting and the heat available for surface melting $Q_{sum}=0$.  Otherwise $T_{su}$ is capped at 0$^\circ$ C and $Q_{sum}$ is calculated as a residual.
+
+\textbf{Radiation}. Radiation contributes to the surface and internal heat budget. The radiative transfer scheme is currently basic, composed of surface albedo, transmission through the ice interior and attenuation with vertical depth. The albedo is computed empirically as a function of ice thickness, snow depth and surface temperature, using a reformulation of the parameterization of \cite{ShineHenderson85}. When snow is present, all the absorbed radiation is transformed into sensible heat available for conduction or melting. Over snow-free ice, a fraction of solar radiation is transmitted below the surface and attenuates exponentially with depth, until it reaches the base of the ice.
+
+\textbf{Growth and melt processes}.  Snow grows from precipitation and loses mass from melting and snow-ice conversion once the snow base is below sea level. Sea ice grows and melts by various means. Ice forms by congelation or melt at the base, can melt at the surface and form from snow-to-ice conversion at the snow-ice interface if the latter is below sea level. Some new ice is also added to the system when seawater is trapped into newly formed pressure ridges.
+
+\textbf{Salt dynamics}. Bulk salinity is empirically parameterized, as a function of salt uptake during growth, gravity drainage and flushing. The shape of the vertical profile depends on the bulk salinity \citep{Vancoppenolleetal09b}.
+
+\textbf{Single-category parameterizations}. If the single-category representation is adopted, then two parameterizations can be activated, following \citep{FichefetMaqueda97}. First, the thermal conductivity of both ice and snow is multiplied by a factor $>1$ accounting for the unresolved thin ice, effectively increasing the ice growth rate. Second, to account for the loss of thin ice in summer, the ice concentration is reduced in proportion to the loss of ice thickness. Both parameterizations have been tuned to match the results in multi-category mode.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_output_diagnostics.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_output_diagnostics.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_output_diagnostics.tex	(revision 10321)
@@ -0,0 +1,65 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 9 - Outputs and diagnostics
+% ================================================================
+
+\chapter{Output and diagnostics}
+\label{chap:DIA}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\section{SIMIP diagnostics}
+
+The SIMIP protocol \citep{Notzetal16} was designed for CMIP6, to standardize sea ice model outputs in climate simulations. We tried to follow the data request as closely as possible. Outputs are in most cases directly managed with XIOS2 in \textbf{limwri.F90}, but not always. In the code, output fields keep their native LIM reference name. 
+
+A corresponding entry exists in \textbf{field\_def\_nemo-lim.xml}, where fields are given their SIMIP specifications (standard name, long name, units). At the end of the file the fields are gathered in the field groups \textbf{SIday\_fields}, \textbf{SImon\_fields} and \textbf{SImon\_scalar} for separation of the daily (SIday) and monthly (SImon) requests. 
+
+In \textbf{file\_def\_nemo-lim.xml}, the daily, monthly and scalar output files are created.
+
+In the reference xml files, the largest possible SIMIP-based diagnostics with LIM are distributed among the field groups. If some fields are to be discarded, the best way to do so is to remove them from the field groups in  field\_def\_nemo-lim.xml.
+
+\subsection{Missing SIMIP fields}
+
+About 90\% of the SIMIP fields can be output. Below is the list of the missing fields and why they are missing. \\
+
+\textbf{1. Fields that are not part of the sea ice representation in LIM3.6}
+\begin{itemize}
+\item sisnconc (snow area fraction), siitdsnconc (snow area fractions in thickness categories);
+\item simpconc (meltpond area fraction), simpmass (melt pond mass per area), simprefrozen (thickness of refrozen ice on ponds);
+\item sirdgconc (ridged ice area fraction), sirdgmass (ridged ice thickness);
+\item sidmasslat (lateral sea ice melt rate);
+\item sndmasswindrif (snow mass change through wind drift of snow);
+\end{itemize}
+
+\textbf{2. Fields which value is trivial}
+\begin{itemize}
+\item sipr (rainfall over sea ice): all rain falls in open water;
+\item sidragtop (atmospheric drag over sea ice): namelist parameter;
+\item sidragbot (oceanic drag over sea ice): namelist parameter
+\end{itemize}
+
+\textbf{3. Fields that belong to the atmospheric component}
+\begin{itemize}
+\item siflswdtop, siflswutop, siflswdbot, sifllwdtop, sifllwutop, siflsenstop, sifllatstop (surface energy budget components)
+\end{itemize}
+
+Ice thickness and snow depth were masked below 5\% ice concentration, because below this value, they become meaninglessly large in LIM. This is notably because of the Prather advection scheme. We hope to fix these issues for our next release. For similar reasons, the ice age is masked below 15\% concentration.
+
+Fluxes through straits and passages were not directly implemented. Instead, ice mass, snow mass, and ice area transports were implemented as 2D arrays, for x- and y- directions. A python script is available to derive the fluxes through straits and passages from full 2D arrays for ORCA2 and eORCA1 grids.
+
+\subsection{Links}
+
+\begin{itemize}
+\item \textcolor{blue}{\href{http://www.geosci-model-dev.net/9/3427/2016/}{Paper of Notz et al}};
+\item \textcolor{blue}{\href{http://clipc-services.ceda.ac.uk/dreq/u/SIMIP.html}{SIMIP CMIP6 data request page}};
+\item \textcolor{blue}{\href{http://www.climate-cryosphere.org/activities/targeted/simip}{SIMIP description on CliC website}}.
+\end{itemize}
+
+\section{Conservation checks}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_radiative_transfer.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_radiative_transfer.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_radiative_transfer.tex	(revision 10321)
@@ -0,0 +1,210 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+
+
+
+% ================================================================
+% Chapter 6 Ñ Radiative transfer
+% ================================================================
+
+\chapter{Radiative transfer}
+\label{chap:RAD}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+Radiative transfer in SI$^3$ currently reduces to the parameterization of solar radiation partitionning through the snow/ice/open water system, treated using a single wavelength band. This will likely be improved in future versions of the code. In this chapter, we first explain how solar radiation is partionned in the snow-ice system, then describe how, solar radiation-wise, the snow-ice system is framed in the context of the atmosphere-ice-ocean boundary.
+
+\section{Solar radiation partitionning in the snow-ice system}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Radiation balance %
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=6cm,angle=-00]{../Figures/radiative_transfer.png}
+\caption{Partitionning of solar radiation in the snow-ice system, as represented in SI$^3$.}
+\label{fig_radiative_transfer}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Solar radiation in the snow-ice system is represented following the principles of \cite{MaykutUntersteiner71}, see Fig.\ref{fig_radiative_transfer}, using a unique band of solar radiation. Incident solar radiation (W/m$^2$, counted per unit ice area - not per grid cell area) is specified in the SBC routines and is a priori category dependent, because multiple atmosphere-surface reflexions are frequent in polar regions imply that incident radiation depends on the surface albedo and therefore surface state. 
+
+Net solar radiation qsr\_ice(i,j,l) is obtained by substracting the reflected part of the incident radiation using the surface albedo $\alpha(i,j,l)$, parameterized as a function of environmental conditions. 
+
+The subsequent attenuation of solar radiation through the snow-ice system is represented assuming the presence of a highly diffusive surface scattering layer, absorbing a fraction $i_o$ of net solar radiation, which is transformed into sensible heat, contributing to the surface energy balance. 
+
+The remainder of solar radiation, qtr\_ice\_top(i,j,l), is transmitted below the surface and attenuates following Beer-Lambert law. The part of solar radiation that is absorbed on its path to the base of the ice is given as sensible heat to the snow/ice system, via a source term in the heat diffusion equation. The rest of solar radiation that reaches the ice base, qtr\_ice\_bot(i,j,l), is transmitted to the ocean. 
+
+In the rest of this section, we describe how the albedo, the surface transmission parameter $i_o$ and the attenuation of solar radiation are parameterized.
+
+\subsection{Surface albedo}
+
+The surface albedo determines the amount of solar radiation that is reflected by the ice surface, hence also net solar radiation. The philosophy of the parameterization of surface albedo is the following: each ice category has its own albedo value $\alpha(i,j,l)$, determined as a function of cloud fraction, ice thickness, snow depth, melt pond fraction and depth, using observation-based empirical fits. 
+
+The original \cite{ShineHenderson85} parameterization had a few inconsistencies and flaws that the revisited parameterization described hereafter fixes. In particular, the dependencies of albedos on ice thickness, snow depth and cloud fraction have been revised in the light of recent observational constraints \citep{Brandtetal05,GrenfellPerovich04}. In addition, the asymptotic properties of albedo are better specified and now fully consistent with oceanic values. Finally, the effect of melt ponds has been included \citep{Lecomteetal15}.
+
+The user has control on 5 reference namelist values, which describe the asymptotic values of albedo of snow and ice for dry and wet conditions, as well as the deep ponded-ice albedo. Observational surveys, in particular during SHEBA in the Arctic \citep{Perovichetal02alb} and further additional experiments \citep{GrenfellPerovich04}, as well as by \cite{Brandtetal05} in the Antarctic, have provided relatively strong constraints on the surface albedo. In this context, the albedo can hardly be used as the main model tuning parameter, at least outside of these observation-based bounds (see namalb for reference values).
+
+\forfile{../namelists/namalb}
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : cloud correction
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{../Figures/albedo_cloud_correction.png}
+\caption{Albedo correction $\Delta \alpha$ as a function of overcast sky (diffuse light) albedo $\alpha_os$, from field observations \cite[][their Table 3]{GrenfellPerovich04} (squares) and 2nd-order fit (Eq. \ref{eq_albedo_cloud_correction}). Red squares represent the irrelevant data points excluded from the fit. For indication, the amplitude of the correction used in the ocean component is also depicted (blue circle).}
+% ocean uses 0.06 for overcast sky (Payne 74) and Briegleb and Ramanathan parameterization
+\label{fig_albedo_cloud_correction}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+Because the albedo is not an intrinsic optical property, it depends on the type of light (diffuse of direct), which is practically handled by weighting the clear (cs) and overcast (os) skies values by cloud fraction $c(i,j)$ \citep{FichefetMaqueda97}:
+\begin{equation}
+\alpha(i,j,l) = [ 1 - c(i,j) ] \cdot \alpha_{cs} (i,j,l) + c (i,j) \cdot \alpha_{os}(i,j,l).
+\end{equation}
+For concision, we drop the spatial and category indices hereafter. \cite{GrenfellPerovich04} observations at Point Barrow, on the Alaskan Coast, suggest that clear and overcast sky albedos are directly related through
+\begin{equation}
+\alpha_{cs} = \alpha_{os} - \Delta \alpha(\alpha_{os}).
+\end{equation}
+The relation between $\Delta \alpha$ and $ \alpha_{os}$ can well be handled using a 2$^{nd}$-order polynomial fit (Fig. \ref{fig_albedo_cloud_correction}):
+\begin{equation}
+\Delta \alpha =  ( -0.1010 \cdot \alpha_{os}^2 + 0.1933 \cdot \alpha_{os} - 0.0148 ).
+\label{eq_albedo_cloud_correction}
+\end{equation}
+Overcast sky surface albedo is used as a reference, from which the clear-sky value is derived.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : thickness, snow depth, pond depth dependencies
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=4cm,angle=-00]{../Figures/albedo_dependencies.png}
+\caption{Example albedo dependencies on ice thickness, snow depth and pond depth, as parameterized in SI$^3$.}
+\label{fig_albedo_dependencies}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+The second important parameter that controls surface albedo is surface type. In each category, we assume that three types of surfaces can coexist (bare, snow-covered and ponded ice), with respective fractions $f_{ice}$, $f_{snw}$ and $f_{pnd}$ summing to 1. Then the overcast albedo is expressed as
+\begin{equation}
+\alpha_{os}(i,j,l) = f_{ice} \cdot \alpha_{ice} + f_{snw} \cdot \alpha_{snw} + f_{pnd}\cdot \alpha_{pnd}
+\end{equation}
+with a specific albedo value for each surface type. 
+
+The surface fractions $f_{ice}$, $f_{snw}$ and $f_{pnd}$ are currently crudely parameterized: if snow is present ($h_s>0$), then $f_{snw}=1$ and $f_{ice}=f_{pnd}=0$. In the absence of snow, $f_{pnd}$ is either specified or calculated (depending on melt pond options in nampnd), and $f_{ice}=1.-f_{pnd}$. Admittedly, more refined parameterizations of $f_{snw}$ could improve the realism of the model. Note finally that the dependence of surface albedo on the presence of melt ponds can be included or not (namelist parameter ln\_pnd\_alb). If the latter is set to false, $f_{pnd}$ is always assumed zero in the albedo computations.
+
+Works by \cite{Brandtetal05} and references therein, indicate that the dependence of the albedo of bare ice on ice thickness depends is linear/logarithmic/constant from thin to thick ice. Hence, the following expressions capture  the essence of their works:
+\begin{eqnarray}
+\alpha_{ice} = 
+\begin{cases}
+\alpha_{ice}^{\infty} & \text{ if } h_i > 1.5, \\
+\alpha_{ice}^{\infty} + ( 0.18 - \alpha_{ice}^{\infty} ) \cdot \frac{ln(1.5) - ln(h_i)}{ln(1.5) - ln(0.05)} & \text{ if } 0.05 < h_i ,<= 1.5 \\
+\alpha_{oce}  + ( 0.18 - \alpha_{oce} ) h_i /0.05 & \text{ if } h_i < 0.05.
+\end{cases}
+\end{eqnarray}
+The thick-ice constant albedo value depends on whether the surface is dry or melting:
+\begin{eqnarray}
+\alpha_{ice}^{\infty} =
+\begin{cases}
+\alpha_{i,dry} & \text{ if } T_{su} < T_{fr} \\
+\alpha_{i,mlt} & \text{ if } T_{su} = T_{fr},
+\end{cases}
+\end{eqnarray}
+values that are to be specified from the namelist.
+
+\cite{GrenfellPerovich04} suggest that the dependence of surface albedo on snow depth is exponential,
+\begin{eqnarray}
+\alpha_{snw} = \alpha_{snw}^{\infty} - ( \alpha_{snw}^{\infty} - \alpha_{ice} ) * exp( -h_s / h_s^{ref} ),
+\end{eqnarray}
+where $h_s^{ref} = 0.02$ $(0.03)$ m for dry (wet) snow. As for bare ice, the deep-snow asymptotic albedo also depends on whether the surface is dry or melting:
+\begin{eqnarray}
+\alpha_{snw}^{\infty} =
+\begin{cases}
+\alpha_{s,dry} & \text{ if } T_{su} < T_{fr} \\
+\alpha_{s,mlt} & \text{ if } T_{su} = T_{fr},
+\end{cases}
+\end{eqnarray}
+values that are to be specified from the namelist.
+
+Based on ideas developed from melt ponds on continental ice \citep{ZuoOerlemans96}, the albedo of ponded ice was proposed to follow \citep{Lecomteetal11}:
+\begin{eqnarray}
+\alpha_{pnd} = \alpha_{dpnd} - ( \alpha_{dpnd} -\alpha_{ice} ) \cdot exp( -h_{pnd} / 0.05 )
+\end{eqnarray}
+$\alpha_{dpnd}$ is a namelist parameter. \cite{EbertCurry93} also use such dependency for their multi-spectral albedo.
+
+The dependencies of surface albedo on ice thickness, snow depth and pond depth are illustrated in Fig. \ref{fig_albedo_dependencies}.
+
+\subsection{Transmission below the snow/ice surface}
+
+The transmitted solar radiation below the surface is represented following \cite{FichefetMaqueda97} and \cite{MaykutUntersteiner71}:
+\begin{eqnarray}
+qtr\_ice\_top(i,j,l) = i_o(i,j) qsr\_ice(i,j,l),
+\end{eqnarray}
+where $i_o=0$ in presence of snow, and depends on cloud fraction otherwise, based on works of \cite{GrenfellMaykut77}. This parameterization needs to be re-evaluated and likely updated.
+
+\subsection{Attenuation and transmission below the ice/ocean interface}
+
+Attenuation of solar radiation through the ice follows Beer-Lambert law. In practise, we assume that irradiance below layer $k$ is given by
+
+\begin{eqnarray}
+radtr\_i(i,j,k,l) = qtr\_ice\_top(i,j,l) \cdot exp(-\kappa_i z),
+\end{eqnarray}
+where $\kappa_i = 1$ m$^{-1}$ is the exponential attenuation coefficient (namelist parameter rn\_kappa\_i). Hence, at the ice base, remains below the $l^{th}$ category a transmitted flux: 
+\begin{eqnarray}
+qtr\_ice\_bot(i,j,l) = qtr\_ice\_top(i,j,l) \cdot exp(-\kappa_i h_i).
+\end{eqnarray}
+
+\section{Solar radiation: framing sea ice at the ocean-atmosphere boundary}
+
+How solar radiation transfer through sea ice is framed into the atmosphere-ice-ocean is nearly identical but not exactly the same in forced and coupled mode (see Fig. \ref{fig_radiative_transfer}.
+
+The basic principle of the computation is that the irradiant flux given to the ocean model (qsr) is computed as the average flux per grid cell area (qsr\_tot) minus what is given to the sea ice ($\sum a(l) qsr\_ice(l)$), plus what is transmitted below sea ice $\sum$ qtr\_ice\_bot(jl) (see at the base of Fig. \ref{fig_radiative_transfer}). Such formulation ensures heat conservation by construction.
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Radiation balance %
+\begin{figure}[!ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=8cm,angle=-00]{../Figures/radiation_atm_ice_oce.png}
+\caption{Framing solar radiation transfer through sea ice into the atmosphere-ice-ocean context.}
+% ocean uses 0.06 for overcast sky (Payne 74) and Briegleb and Ramanathan parameterization
+\label{fig_radiative_transfer}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+\subsection{Forced mode}
+
+In forced-atmosphere mode, it is the incoming solar irradiance fluxes above the ocean and sea ice (categories) that are specified (from files) or computed (from bulk formulae), and constitute the basis of solar radiation transfer computations. Then the net solar fluxes above open water (qsr\_oce) and ice categories (qsr\_ice) are obtained by multiplication by $1-\alpha$. qsr\_tot is then diagnosed as a weighted sum of qsr\_oce and the qsr\_ice(jl)'s.
+
+\subsection{Coupled mode}
+
+In coupled-atmosphere mode, qsr\_tot and qsr\_ice have to be provided by the atmospheric model, whereas qsr\_oce is diagnosed from qsr\_ice and qsr\_tot.
+
+Some atmospheric models enable \textit{tiling} and can provide solar fluxes over individual ice categories. For such atmospheric models, net solar radiation fluxes are directly useable by SI$^3$ (nn\_flxdist =  -1). Other models cannot do tiling, being only able to provide a net solar flux above all ice categories, seen as a single surface type. For such models a first option is to give the net solar flux above sea ice identically to all sea ice categories (nn\_flxdist = 0). Yet a better option is to redistribute the mean solar flux above sea ice $< qsr_ice >$ above categories (nn\_flxdist = 2) using the following scaling, conserving heat by construction:
+
+\begin{eqnarray}
+qsr\_ice(jl) = < qsr\_ice > \frac{1 - \alpha(jl)}{1 - < \alpha >}
+\end{eqnarray}
+
+where $ < \alpha >$ is the albedo averaged over the ice categories. Note that for testing, the flux redistributor can be emulated in forced mode (nn\_flxdist = 1).
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_ridging_rafting.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_ridging_rafting.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_ridging_rafting.tex	(revision 10321)
@@ -0,0 +1,156 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 5 Ñ Ridging and rafting
+% ================================================================
+
+\chapter{Ridging and rafting}
+\label{chap:RDG}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+This chapter focuses on how LIM solves the red part of the general equation:
+\begin{equation}
+\frac{\partial X}{\partial t} = - \nabla .(\mathbf{u} X)  \color{black} \Theta^X  + \color{red} \Psi^X,
+\label{eq:Xt}
+\end{equation}
+where $X$ refers to any global sea ice state variable.
+
+Divergence and shear open the ice pack and create ice of zero thickness. Convergence and shear consumes thin ice and create thicker ice by mechanical deformation. The redistribution functions $\Psi^X$ describe how opening and mechanical deformation redistribute the global ice state variables into the various ice thickness categories. 
+
+The fundamental redistribution function is $\Psi^g$, which accounts for area redistribution. The other redistribution functions $\Psi^X$ associated with other state variables will derive naturally. The redistribution function $\Psi^g$ should first ensure area conservation. By integrating the evolution equation for $g(h)$ over all thicknesses, recalling that $\int_0^\infty g(h) = 1$, and that the total areal change due to thermodynamics must be zero, e.g. $\int_0^\infty \partial (fg) / \partial h=0$, then the area conservation reads: 
+\begin{equation}
+\int_0^\infty h \Psi^g dh = \nabla \cdot \mathbf{u}.
+\end{equation}
+
+Second, we must say something about volume conservation, and this will be done more specifically later. Following \cite{Thorndikeetal75}, we separate the $\Psi^X$'s into \textbf{(i)} \textit{dynamical inputs}, \textbf{(ii)} \textit{participation functions}, i.e., how much area of ice with a given thickness participates to mechanical deformation \textbf{(iii)} \textit{transfer functions}, i.e., where in thickness space the ice is transferred after deformation.
+
+\section{Dynamical inputs}
+
+A general expression of $\Psi^g$, the mechanical redistribution function associated to the ice concentration, was proposed by \cite{Thorndikeetal75}:
+\begin{equation}
+\Psi^g = \vert \dot{\epsilon} \vert [ \alpha_o(\theta) \delta(h) + \alpha_d(\theta) w_d(h,g) ],
+\label{eq:psi}
+\end{equation}
+which is convenient to separate the dependence in $\mathbf{u}$ from those in $g$ and $h$. The first and second terms on the right-hand side correspond to opening and deformation, respectively. $\vert \dot{\epsilon} \vert = (\dot{\epsilon}_{I}^2+ \dot{\epsilon}_{II}^2)^{1/2}$, where $\dot{\epsilon}_{I}=\nabla \cdot \mathbf{u}$ and $\dot{ \epsilon}_{II}$ are the strain rate tensor invariants; $\theta=\textrm{atan}(\dot{\epsilon_{II}} / \dot{\epsilon_{I}} )$. $w_d(h,g)$, the deformation mode will be discussed in the next section. $\vert \dot{\epsilon} \vert \alpha_o$ and $\vert \dot{\epsilon} \vert \alpha_d$ are called the lead opening and closing rates, respectively.
+
+The \textbf{dynamical} inputs of the mechanical redistribution in LIM are:
+\begin{itemize}
+\item $\vert \dot{\epsilon} \vert \alpha_o$, the opening rate,
+\item $\vert \dot{\epsilon} \vert \alpha_d$, the net closing rate.
+\end{itemize}
+Following \cite{Thorndikeetal75}, we choose $\int_0^\infty w_d(h,g) = - 1$. In order to satisfy area conservation, the relation $\vert \dot{\epsilon} \vert \alpha_o - \vert \dot{\epsilon} \vert \alpha_d = \nabla \cdot \mathbf{u}$ must be verified. In the model, there are two ways to compute the divergence of the velocity field. A first way is to use the velocity components ($\dot{\epsilon}_I = \nabla \cdot \mathbf{u}\vert^{rhg}$) as computed after the rheology (superscript $rhg$). Another way is to derive it from the horizontal transport of ice concentration and open water fraction. In principle, the equality $A^o + \sum_{l=1}^L g^i_L = 1$ should always be verified. However, after ice transport (superscript $trp$), this is not the case, and one can diagnose a velocity divergence using the departure from this equality: $\nabla \cdot \mathbf{u}\vert^{trp} = ( 1 - A^o - \sum_{l=1}^L g^i_L )/ \Delta t$. In general, we will use $\dot{\epsilon}_I$ unless otherwise stated.
+
+The \textbf{net closing rate} is written as a sum of two terms representing the energy dissipation by shear and convergence \citep{FlatoHibler95}:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_d (\theta) = C_s \frac{1}{2} ( \Delta - \vert \dot{\epsilon}_I \vert) - \textrm{min} (\dot{\epsilon}_I,0),
+\end{equation}
+where $\Delta$ is a measure of deformation (defined in the rheology section). The factor $C_s=0.5$ (\textit{Cs} in \textit{namelist\_ice}) is added to allow for energy sinks other than ridge building (e.g., sliding friction) during shear. In case of convergence, the closing rate must be large enough to satisfy area conservation after ridging, so we take:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_d (\theta) = \text{max}(\vert \dot{\epsilon} \vert \alpha_d (\theta), - \nabla \cdot \mathbf{u} \vert^{trp}) \quad \text{if } \nabla \cdot \mathbf{u} < 0.
+\end{equation}
+
+The \textbf{opening rate} is obtained by taking the difference:
+\begin{equation}
+\vert \dot{\epsilon} \vert \alpha_o = \vert \dot{\epsilon} \vert \alpha_d = \nabla \cdot \mathbf{u}\vert^{trp}
+\end{equation}
+
+\section{The two deformation modes: ridging and rafting}
+
+The deformation mode is separated into ridging $w^{ri}$ and rafting $w^{ra}$ modes:
+\begin{equation}
+w^d(h,g) = w^{ri}(g,h) + w^{ra}(g,h).
+\end{equation}
+
+\textbf{Rafting} is the piling of two ice sheets on top of each other. Rafting doubles the participating ice thickness and is a volume-conserving process. \cite{Babkoetal02} concluded that rafting plays a significant role during initial ice growth in fall, therefore we included it into the model. 
+
+\textbf{Ridging} is the piling of a series of broken ice blocks into pressure ridges. Ridging redistributes participating ice on a various range of thicknesses. Ridging does not conserve ice volume, as pressure ridges are porous. Therefore, the volume of ridged ice is larger than the volume of new ice being ridged. In the model, newly ridged is has a prescribed porosity $p=30\%$ (\textit{ridge\_por} in \textit{namelist\_ice}), following observations \citep{Lepparantaetal95,Hoyland02}. The importance of ridging is now since the early works of \citep{Thorndikeetal75}.
+
+The deformation modes are formulated using \textbf{participation} and \textbf{transfer} functions with specific contributions from ridging and rafting:
+\begin{equation}
+w_d(h,g) = - [ b^{ra}(h) + b^{ri}(h) ] g(h) + n^{ra}(h)+n^{ri}(h).
+\label{eq:wd}
+\end{equation}
+$b^{ra}(h)$ and $b^{ri}(h)$ are the rafting and ridging participation functions. They determine which regions of the ice thickness space participate in the redistribution. $n^{ra}(h)$ and $n^{ri}(h)$, called transfer functions, specify how thin, deformation ice is redistributed onto thick, deformed ice. Participation and transfer functions are normalized in order to conserve area.
+
+\section{Participation functions}
+
+We assume that the participation of ice in redistribution does not depend upon whether the deformation process is rafting or ridging. Therefore, the participation functions can be written as follows:
+\begin{equation}
+b^{ra}(h)= \beta(h) b(h),
+\label{eq:bra}
+\end{equation}
+\begin{equation}
+b^{ri}(h) = [1-\beta(h)] b(h),
+\label{eq:bri}
+\end{equation}
+where $b(h)$ is an exponential weighting function with an e-folding scale $a*$ \citep{Lipscombetal07} (\textit{astar} in \textit{namelist\_ice}) which preferentially apportions the thinnest available ice to ice deformation:
+\begin{equation}
+b(h) = \frac{\text{exp} [ - G(h) / a^\star ]}{a^\star[1-\text{exp}(-1/a^\star)]} ,
+\end{equation}
+It is numerically more stable than the original version of \cite{Thorndikeetal75}. This scheme is still present in the code and can be activated using \textit{partfun\_swi} from \textit{namelist\_ice}, with the associated parameter \textit{Gstar}.
+
+$\beta(h)$ partitions deformation ice between rafted and ridged ice. $\beta(h)$ is formulated following \cite{Haapala00}, using the \cite{Parmerter75} law, which states that, under a critical participating ice thickness $h_P$, ice rafts, otherwise it ridges:
+\begin{equation}
+\beta(h)= \frac{ \textrm{tanh} [ -C_{ra} (h-h_P) ] + 1 } {2},
+\end{equation}
+where $C_{ra}=5$ m$^{-1}$ (\textit{Craft} in \textit{namelist\_ice})  and $h_P=0.75$ m (\textit{hparmeter} in \textit{namelist\_ice}) \citep{Haapala00,Babkoetal02}. The $tanh$ function is used to smooth the transition between ridging and rafting.  If namelist parameter \textit{raftswi} is set to 0, ice only ridges and does not raft. 
+
+\section{Transfer functions}
+
+The rafting transfer function assumes a doubling of ice thickness :
+\begin{equation}
+n^{ra}(h)=\frac{1}{2}\int_0^\infty \delta(h-2h') b(h') g(h') dh,
+\end{equation}
+where $\delta$ is the Dirac delta function. 
+
+The ridging transfer function is :
+\begin{equation}
+n^{ri}(h)=\int_0^\infty \gamma(h',h) (1+p) b(h') g(h') dh.
+\label{eq:nri}
+\end{equation}
+The redistributor $\gamma(h',h)$ specifies how area of thickness $h'$ is redistributed on area of thickness $h$. We follow \citep{Hibler80} who constructed a rule, based on observations, that forces all ice participating in ridging with thickness $h'$ to be linearly distributed between ice that is between $2h'$ and $2\sqrt{H^*h'}$ thick, where $H^\star=100$ m (\textit{Hstar} in \textit{namelist\_ice}). This in turn determines how to construct the ice volume redistribution function $\Psi^v$. Volumes equal to participating area times thickness are removed from thin ice. They are redistributed following Hibler's rule. The factor $(1+p)$ accounts for initial ridge porosity $p$ (\textit{ridge\_por} in \textit{namelist\_ice}, defined as the fractional volume of seawater initially included into ridges. In many previous models, the initial ridge porosity has been assumed to be 0, which is not the case in reality since newly formed ridges are porous, as indicated by in-situ observations \citep{Lepparantaetal95,Hoyland02}. In other words, LIM3 creates a higher volume of ridged ice with the same participating ice.
+
+For the numerical computation of the integrals, we have to compute several temporary values:
+\begin{itemize}
+\item The thickness of rafted ice $h^{ra}_l = 2 h^i_l$
+\item The mean thickness of ridged ice $h^{ri,mean}_l=\text{max} ( \sqrt{H^\star h^i_l} , h^i_l \cdot 1.1 )$
+\item The minimum thickness of ridged ice $h^{ri,min}_l = \text{min} [ 2*h^i_l, 0.5\cdot(h^{ri,mean}_l+h^i_l) ]$
+\item The maximum thickness of ridged ice $h^{ri,min}_l = 2 h^{ri,mean}_l - h^{ri,min}_l$
+\item The mean rate of thickening of ridged ice $k^{ri}_l = h^{ri,mean}_l / h^{i}_l$
+\end{itemize}
+
+\section{Ridging shift}
+
+%\textit{Subroutine}: \textbf{lim\_itd\_ridgeshift}
+
+The numerical computation of the impact of mechanical redistribution on ice concentration involves:
+\begin{itemize}
+\item A normalization factor that ensures volume conservation (\textit{aksum})
+\item The removal of ice participating in deformation (including the closing of open water)
+\item The addition of deformed ice
+\end{itemize}
+
+For ice concentrations, the numerical procedure reads:
+\begin{equation}
+\Delta g^i_l = C^{net} \Delta t \biggr [ - ( b^{ri}_l + b^{ra}_l) + \sum_{l_2=1}^L \biggr ( f^{ra}_{l,l_2}  \frac{b^{ra}_{l_2}}{k^{ra}} + f^{ri}_{l,l_2} \frac{ b^{ri}_{l_2} }{k^{ri}_{l_2}} \biggr ) \biggr ]
+\end{equation}
+\begin{itemize}
+\item $C^{net}$ is the normalized closing rate ($\vert \dot{\epsilon} \vert \alpha^d/\textit{aksum}$)
+\item $b^{ri}_l$ and $b^{ra}_l$ are the area participating into redistribution for category $l$
+\item $f^{ra}_{l,l_2}$ and $f^{ri}_{l,l_2}$ are the fractions of are of category $l$ being redistributed into category $l_2$
+\item $k^{ra}$ is the rate of thickening of rafted ice (=2)
+\end{itemize}
+
+Because of the nonlinearities involved in the integrals, the ridging procedure has to be iterated until $A^\star = A^{ow} + \sum_{l=1}^L g^i_l = 1$.
+
+\section{Mechanical redistribution for other global ice variables}
+
+The other global ice state variables redistribution functions $\Psi^X$ are computed based on $\Psi^g$ for the ice age content and on $\Psi^{v^i}$ for the remainder (ice enthalpy and salt content, snow volume and enthalpy). The general principles behind this derivation are described in Appendix A of \cite{Bitzetal01}. A fraction $f_s=0.5$ (\textit{fsnowrdg} and \textit{fsnowrft} in \textit{namelist\_ice}) of the snow volume and enthalpy is assumed to be lost during ridging and rafting and transferred to the ocean. The contribution of the seawater trapped into the porous ridges is included in the computation of the redistribution of ice enthalpy and salt content (i.e., $\Psi^{e^i}$ and $\Psi^{M^s}$). During this computation, seawater is supposed to be in thermal equilibrium with the surrounding ice blocks. Ridged ice desalination induces an implicit decrease in internal brine volume, and heat supply to the ocean, which accounts for ridge consolidation as described by \cite{Hoyland02}. The inclusion of seawater in ridges does not imply any net change in ocean salinity. The energy used to cool down the seawater trapped in porous ridges until the seawater freezing point is rejected into the ocean.
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_single_category_use.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_single_category_use.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_single_category_use.tex	(revision 10321)
@@ -0,0 +1,22 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 10 Ñ Single-category use
+% ================================================================
+
+\chapter{Using SI$^3$ with a single category}
+
+\label{chap:INT}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+\section{Enhanced conduction}
+\section{Virtual thin ice melting (fake lateral melting)}
+\section{Ridging and rafting with a single ice category}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_thermo.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_thermo.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_thermo.tex	(revision 10321)
@@ -0,0 +1,88 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 7 Ñ Ice thermodynamics
+% ================================================================
+
+\chapter{Ice thermodynamics}
+\label{chap:THD}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+
+% ================================================================
+% Thermodynamics % ================================================================
+
+Mass, energy and salt are intertwined for sea ice. Referred to as thermodynamics, or more exactly halo-thermodynamics. Mushy-layer theory.
+
+\section{Open water and new ice formation}
+
+% There is everything in here, but there are too much details.
+% Move things around into chapters and summarize.
+
+As part of the sea ice computations, a heat budget of the uppermost oceanic level is estimated. This heat budget is used if negative to compute the production of new ice or, if positive, for bottom melting. 
+
+%--------------------------------------------------------------------------------------------------------------------
+%
+% FIG x : Open water energy budget
+%
+\begin{figure}[ht]
+\begin{center}
+\vspace{0cm}
+\includegraphics[height=10cm,angle=-00]{../Figures/Openwater_eb.png}
+\caption{Scheme of the estimate of the heat budget of the first ocean level.}
+\label{fig_yield}
+\end{center}
+\end{figure}
+%
+%--------------------------------------------------------------------------------------------------------------------
+
+We estimate the heat budget of the first ocean level ($B^{opw}$) assuming four contributions, namely:
+\begin{itemize}
+\item The absorption of a fraction $f_1^{qsr}$ of solar radiation (given by radiative transfer component of the ocean model);
+\item The non-solar heat flux absorbed at the surface;
+\item The sensible heat content of precipitation
+\item The sensible heat loss to the sea ice
+\end{itemize}
+The estimated heat budget thus reads:
+\begin{linenomath}
+\begin{align}
+B^{opw} = Q^{sr} ( 1 - A ) f_1^{qsr} + Q^{ns} ( 1 - A ) + Q^{emp} - A F_w,
+\end{align}
+\end{linenomath}
+Hence there is no consideration of the entrainment of heat at the base of the first ocean level, or of solar radiation transmitted below the ice. The ocean-to-ice turbulent sensible heat flux is formulated following \citep{McPhee92}
+\begin{linenomath}
+\begin{align}
+F_w = \rho_0 c_w C_h u^* ( SST - T_b )
+\end{align}
+\end{linenomath}
+where $\rho_0$ is the reference ocean density, $c_w$ is the seawater specific heat, $C_h = 7.5 \times 10^{-3}$ is a heat transfer coefficient, and $u^*=\sqrt{\tau_{iw}/\rho_0}$. There are two additional conditions, the oceanic heat flux cannot be negative. Second, $F_w$ cannot exceed the heat content of the first ocean level.
+
+% Ice growth
+If the $B^{opw}$ is such that the SST would decrease below the freezing point, the remainder of the heat is used to form new ice. The heat loss is converted into mass through [\ref{eq_phasechange}], giving by multiplication by density a volume of new ice $v_0$. The thickness $h_0$ of the new ice grown during a sea ice time step depends on unresolved small currents and waves and is prescribed. The fraction $a_0=v_0/h_0$ is computed accordingly. The salinity of this new ice $S_0$ is given by the S-h empirical relationship of \cite{Kovacs96}. The temperature assumed for this new ice is the local freezing point.
+
+% Ice melt
+If there is ice in the grid cell and that the $B^{opw}$ is positive, it is directly given attributed to the heat available for bottom melting. This argument follows from \cite{MaykutMcPhee95}, who found that most of solar heat absorbed in the surface waters is converted into melting. In practise, this means that the SST cannot go above freezing as long ice is present.
+
+The heat loss used for ice formation, heat gain used to melt ice and the sensible heat given by the ocean to the ice, are all removed from the non-solar heat flux transmitted to the ocean.
+
+Because ice dynamics are not able to maintain the small amount of open water that is observed, a maximum ice fraction ($amax, <1$) is prescribed.
+
+\section{Diffusion of heat}
+
+\section{Vertical growth and melt}
+
+\section{Desalination}
+
+\section{Remapping}
+
+\section{Transport in thickness space}
+
+\section{True lateral melting}
+
+\end{document}
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_transport.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_transport.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/chap_transport.tex	(revision 10321)
@@ -0,0 +1,27 @@
+
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Chapter 4 Ñ Ice transport
+% ================================================================
+
+\chapter{Ice transport}
+\label{chap:TRP}
+\minitoc
+
+\newpage
+$\ $\newline    % force a new line
+
+As soon as ice dynamics are activated (\textit{ln\_dyn\_xxx}), all extensive state variables are to be advected following the horizontal velocity field.
+
+\section{Second order moments conserving (Prather 1986) scheme (\textit{ln\_adv\_Pra})}
+
+The scheme of  \cite{Prather86} explicitly computes the conservation of second-order moments of the spatial distribution of global sea ice state variables. This scheme preserves positivity of the transported variables and is practically non-diffusive. It is also computationally expensive, however it allows to localize the ice edge quite accurately. As the scheme is conditionally stable, the time step is split into two parts if the ice drift is too fast, based on the CFL criterion. 
+
+State variables per unit grid cell area are first multiplied by grid cell area. Then, for each state variable, the 0$^{th}$ (mean), 1$^{st}$ (x, y) and 2$^{nd}$ (xx, xy, yy) order moments of the spatial distribution are transported. At 1st time step, all moments are zero (if prescribed initial state); or read from a restart file, and then evolve through the course of the run. Therefore, for each global variable, 5 additional tracers have to be kept into memory and written in the restart file, which significantly increases the required memory. Advection following x and y are computed independently. The succession order of x- and y- advection is reversed every day.
+
+\section{5$^{th}$ order flux-corrected transport scheme (UM5)}
+
+\end{document}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/introduction.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/introduction.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/introduction.tex	(revision 10321)
@@ -0,0 +1,59 @@
+
+% ================================================================
+% INTRODUCTION
+% ================================================================
+
+\chapter*{Introduction}
+
+\textcolor{red}{[ \textit{July 2018} ]} \\
+
+%Near the poles of the Earth, the seas and oceans freeze when seawater at the freezing point loses heat. The resulting forms of saline ice are collectively called \textit{sea ice} \citep{WMO70}, reaching up to a few meters in thickness, where as sea ice coverage is about 5\% of the global ocean, about 30 million square kilometers. All sea ice characteristics vary over a wide range of spatio-temporal scales, reflecting changes in heat, mass and momentum exchanges with the atmosphere and the ocean; the clearest temporal signal being an ample seasonal cycle. Sea ice formation and melting affects water mass formation in the ocean \citep{GoosseFichefet99}. It not only impacts, but also reflects the state of the climate system \citep{Budyko69,NotzStroeve16}.  Sea ice also affects marine life, water chemistry and human activities in polar regions. Local populations use sea ice for travelling and hunting, whereas navigation and resource exploitation are dependent on sea ice conditions. For such reasons, ocean modelling systems, including NEMO, must include a sea ice component.
+
+The sea Ice Modelling Integrated Initiative (SI$^3$) is the sea ice engine of the Nucleus for European Modelling of the Ocean (NEMO). It is intended to be a flexible tool for studying sea ice and its interactions with the other components of the Earth System over a wide range of space and time scales. SI$^3$ is a curvilinear grid, finite-difference implementation of the classical AIDJEX\footnote{AIDJEX=\textbf{A}rctic \textbf{I}ce \textbf{D}ynamics \textbf{J}oint \textbf{EX}periment} model \citep{Coonetal74}, combining the conservation of momentum for viscous-plastic continuum, energy and salt-conserving halo-thermodynamics, an explicit representation of subgrid-scale ice thickness variations, snow and melt ponds. An option to switch back to the \textit{single-category} (or \textit{2-level}) framework of \cite{Hibler79} provides a cheap sea ice modelling solution.
+
+SI$^3$ is the result of the recommendation of the Sea Ice Working Group (SIWG) to reduce duplication and better use development resources. SI$^3$ merges the capabilities of the 3 formerly used NEMO sea ice models (CICE, GELATO and LIM). The \textbf{3} in SI$^3$ refers to the three formerly used sea ice models. It also refers to linkages between 3 different media (ocean, ice, snow). The model can be spelt 'SI3' in situations where the superscript could be problematic (i.e., within code and svn repository etc.) The model name would be pronounced as 'si-cube' for short (or 'sea ice cubed' for slightly longer). 
+
+% Limitations & scope
+%There are limitations to the applicability of models such as SI$^3$. The continuum approach is not invalid for grid cell size above at least 1 km, below which sea ice particles may include just a few floes, which is not sufficient \citep{Lepparanta05}. Second, one must remember that our current knowledge of sea ice is not as complete as for the ocean: there are no fundamental equations such as Navier Stokes equations for sea ice. Besides, important features and processes span widely different scales, such as brine inclusions (1 $\mu$m-1 mm) \citep{PerovichGow96}, horizontal thickness variations (1 m-100 km) \citep{Percivaletal08}, deformation and fracturing (10 m-1000 km) \citep{Marsanetal04}. These impose complicated and often subjective subgrid-scale treatments. All in all, there is more empirism in sea ice models than in ocean models. 
+
+In order to handle all the subsequent required subjective choices, we applied the following guidelines or principles:
+\begin{itemize}
+\item Sea ice is frozen seawater that is in tight interaction with the underlying ocean. This close connexion suggests that the sea ice and ocean model components must be as consistent as possible. In practice, this is materialized by the close match between LIM and NEMO, in terms of numerical choices, regarding the grid (Arakawa C-type) and the numerical discretization (finite differences with NEMO scale factors).
+\item It is useful to be able to either prescribe the atmospheric state or to use an atmospheric model. For consistency and simplicity of the code, we choose to use formulations as close as possible in both cases.
+\item Different resolutions and time steps can be used. There are parameters that depend on such choices. We thrieved to achieve a resolution and time-step independent code, by imposing a priori scaling on the resolution / time step dependence of such parameters.
+\item Energy, mass and salt must be conserved as much as possible.
+\end{itemize}
+
+This manual is organised as follows. \\
+
+List of chapters... \\
+
+There are no more CPP keys in the code. \\
+
+Namelists and output management follow NEMO guidelines. \\
+
+Changes between releases. \\
+
+The list of people that should be acknowledged is too long, but a great number of people or more exactly a number of great people contributed to the code and should be gratefully acknowledged. As for today,
+the SIWG members are \textit{(July 2018)}.
+
+\begin{itemize}
+\begin{footnotesize}
+\item Yevgeny Aksenov (NOCS, Southampton, UK)
+\item Ed Blockley (Met Office, Exeter, UK, co-chair)
+\item Matthieu Chevallier (CNRM-GAME, M\'et\'eo France, Toulouse)
+\item Danny Feltham (CPOM, Reading, UK)
+\item Thierry Fichefet (UCL, Louvain-la-Neuve, Belgium)
+\item Gilles Garric (Mercator-Oc\'ean, Toulouse, France)
+\item Paul Holland (BAS, Cambridge, UK)
+\item Dorotea Iovino (CMCC, Bologna, Italy)
+\item Gurvan Madec (LOCEAN, CNRS, Paris, France)
+\item Fran\c cois Massonnet (UCL, Louain-la-Neuve, Belgium)
+\item Jeff Ridley (Met Office, Exeter, UK)
+\item Cl\'ement Rousset (LOCEAN, CNRS, Paris, France)
+\item David Salas (CNRM-GAME, M\'et\'eo France, Toulouse)
+\item David Schroeder (CPOM, Reading, UK)
+\item Steffen Tietsche (ECMWF, Reading, UK)
+\item Martin Vancoppenolle (LOCEAN, CNRS, Paris, France, co-chair) 
+\end{footnotesize}
+\end{itemize}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/todolist.tex
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/todolist.tex	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/latex/SI3/tex_sub/todolist.tex	(revision 10321)
@@ -0,0 +1,56 @@
+\documentclass[../../tex_main/NEMO_manual]{subfiles}
+
+\begin{document}
+
+% ================================================================
+% Dummy Chapter - To do list
+% ================================================================
+
+\chapter*{To-do-list for documentation}
+\label{chap:TDL}
+
+\begin{itemize}
+
+\item \textcolor{gray}{Documentation infrastructure ready by Jul 19, 2018.}
+
+\item \textcolor{gray}{Abstract: v1 written.}
+
+\item \textcolor{gray}{Disclaimer: v1 written.}
+
+\item Introduction: list of chapters and change between realeases to be written (1h)
+
+\item \textcolor{gray}{1. Model basics: v1 written.}
+
+\item \textcolor{gray}{Add namelist infrastructure as in NEMO doc (done)}
+
+\item \textcolor{gray}{2. Time, space and thickness space domain}
+
+\item 3. Ice dynamics: to be written (Clem \& Martin, 3h)
+
+\item 4. Ice transport: UM5 description to be written (Clem, 3h)
+
+\item 5. Ridging and rafting: V1 from previous doc. Should be refreshed. A bit too long. All namelist parameters are not explained (namdyn\_rdgrft).
+
+\item \textcolor{gray}{6. Radiative transfer: Full rewriting required (Martin \& Clem, 3-6h). Available elements from previous documentation, but mostly obsolete.}
+
+\item 7. Thermodynamics: Lots of rewriting required. Available elements from previous documentation, but mostly obsolete (Martin, 6h)
+
+\item 8. Interfaces: Full writing required 
+
+\item 9. Output and diagnostics: Full writing required
+
+\item 10. Single category (Martin, 3h). Full writing required.
+
+\item 11. BDY-AGRIF (Clem, 3h). Full writing required.
+
+\item 12. Miscellaneous. Full writing required.
+
+\item Melt ponds are not currently considered in the plan.
+
+\item Make sure all namelist parameters are properly described.
+
+\item Peer-review by SIWG members.
+
+\end{itemize}
+
+\end{document}
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/namelist_split.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelist_split.sh	(revision 10320)
+++ 	(revision )
@@ -1,247 +1,0 @@
-#! /bin/sh
-#
-#       usage for NEMO doc to create an update of the Namelists directory :
-# 1- delete the existing directory (You can also choose to save it somewhere) 
-#    rm -rf Namelists
-# 2- create the updated Namelists directory from the SHARED/namelist_ref :
-#    ./namelist_split.sh -i ../NEMOGCM/CONFIG/SHARED/namelist_ref -o Namelists
-#
-# .. _namelist_split.sh:
-#
-# =================
-# namelist_split.sh
-# =================
-#
-# ----------------
-# split a namelist
-# ----------------
-#
-# SYNOPSIS
-# ========
-#
-# .. code-block:: bash
-#
-#    namelist_split.sh -i namelist -o dirout [-n]
-#
-# DESCRIPTION
-# ===========
-#
-# Split a namelist file (NEMO convention syntax) given in parameter
-# into files in a given output directory.
-#
-# .. option:: -i <input file (namelist)>
-# .. option:: -o <output directory>
-# .. option:: -n <numbered output files>
-#
-# Each file of the output directory is named after the *block* it contains.
-#
-# We assume here that the input file is written with this pattern of block:
-#
-# .. parsed-literal::
-#
-#    !---------------
-#    &nameblock
-#    !---------------
-#    var1 = val1
-#    ...
-#    varn = valn
-#    /
-#
-# If ``-n`` option is used, files in the directory output are named after
-# the number of the block it contains and the name of this block. This might
-# be useful to recombine blocks in the same order.
-#
-# EXAMPLES
-# ========
-#
-# To split the namelist NEMO ORCA2_LIM experiment 00 if you are in NEMO
-# working space :
-#
-# .. code-block:: bash
-#
-#    namelist_split.sh -i CONFIG/ORCA2_LIM/EXP00/namelist -o /tmp/EXP00_namelist_split/
-#
-# To split the namelist under data directory with numbered files:
-#
-# .. code-block:: bash
-#
-#    namelist_split.sh -i ./data/namelist -o /tmp/EXP00_namelist_split/ -n
-#
-# Check can be made by concatenation of files in output directory if ``-n``
-# option have been used and comparison with original file :
-#
-# .. code-block:: bash
-#
-#    cat /tmp/EXP00_namelist_split/b???_* > /tmp/EXP00_namelist_rebuild
-#    sdiff -w80 ./data/namelist /tmp/EXP00_namelist_rebuild
-#
-# Output contains lines which are before the first block, after the last
-# block and lines between blocks.
-#
-# EVOLUTIONS
-# ==========
-#
-# $Id$
-#
-# - fplod 2008-08-11T08:56:44Z aedon.locean-ipsl.upmc.fr (Darwin)
-#
-#   * commentaires dans ce fichier en reStructuredText
-#     cf. reStructuredText_ and Docutils_
-#
-# .. _reStructuredText: http://docutils.sourceforge.net/rst.html
-# .. _Docutils: http://docutils.sourceforge.net/
-#
-# - fplod 2008-07-22T12:41:04Z aedon.locean-ipsl.upmc.fr (Darwin)
-#
-#   * creation with test on
-#     http://forge.ipsl.jussieu.fr/nemo/browser/trunk/CONFIG/ORCA2_LIM/EXP00/namelist revision 1151
-#-
-#
-system=$(uname)
-case "${system}" in
-    AIX|IRIX64)
-        echo " www : no specific posix checking"
-    ;;
-    *)
-        set -o posix
-    ;;
-esac
-unset system
-#
-command=$(basename ${0})
-log_date=$(date -u +"%Y%m%dT%H%M%SZ")
-#
-usage=" Usage : ${command} -i namelist -o dirout [-n]"
-#
-# default
-blocknum=0
-#
-minargcount=4
-if [ ${#} -lt ${minargcount} ]
-then
-    echo "eee : not enough arguments"
-    echo "${usage}"
-    exit 1
-fi
-#
-while [ ${#} -gt 0 ]
-do
-    case ${1} in
-        -i)
-            filein=${2}
-            shift
-        ;;
-        -o)
-            dirout=${2}
-            shift
-        ;;
-        -h)
-            echo "${usage}"
-            exit 0
-        ;;
-        -n)
-            blocknum=1
-        ;;
-        *)
-            # anything else
-            echo "eee : unknown option ${1}"
-            echo "eee : ${usage}"
-            exit 1
-        ;;
-    esac
-    # next flag
-    shift
-done
-unset usage
-#
-set -u
-#
-# check for filein
-if [ ! -r ${filein} ]
-then
-    echo "eee : ${filein} not accessible"
-    exit 1
-fi
-#
-# check for dirout
-# the idea is to prevent unwanted overwrite
-if [ -d ${dirout} ]
-then
-    echo "eee : ${dirout} already exist"
-    exit 1
-else
-    mkdir -p ${dirout}
-    if [ ${?} -ne 0 ]
-    then
-        echo "eee : cannot create ${dirout}"
-        exit 1
-    fi
-fi
-#
-# loop on each line of ${filein} ie the namelist to be split
-fileout=/dev/null
-begin=0
-if [ ${blocknum} -eq 1 ]
-then
-    iblock=0
-fi
-nbline=$(wc -l ${filein} | awk '{print $1}')
-il=1
-while [ ${il} -le ${nbline} ]
-do
-    line=$(sed -ne "${il},${il}p" ${filein})
-    # if current line start with "&", we can establish the name of output file
-    echo ${line} | grep -q "^&"
-    if [ ${?} -eq 0 ]
-    then
-        begin=1
-        # the form of this line is "&block   !"
-        block=${line#&}
-        block=${block%% *}
-        echo "iii : detection of the beginning of ${block}"
-        if [ ${blocknum} -eq 1 ]
-        then
-            iblock=$(( ${iblock} + 1))
-            fileout=${dirout}/b$(echo ${iblock} | awk '{printf "%3.3d", $1}')_${block}
-        else
-            fileout="${dirout}/${block}"
-        fi
-        # check for ${fileout}
-        if [ -f ${fileout} ]
-        then
-            echo "eee : ${fileout} already exists"
-            exit 1
-        fi
-        # write the previous line and the current line
-        echo "${memoline}" > ${fileout}
-        echo "${line}" >> ${fileout}
-    fi
-    # if current line contains "/" there will be no more lines to put in fileout
-    echo ${line} | grep -q "^/$"
-    if [ ${?} -eq 0 ]
-    then
-        echo "iii : detection of the end of ${block}"
-        echo "${line}" >> ${fileout}
-        fileout="/dev/null"
-    fi
-    # if current line is between "&" and "/", it should be written in fileout
-    # if current line is before the first &, it won't be written
-    if [ "${fileout}" != "/dev/null" ]
-    then
-        if [ ${begin} -eq 0 ]
-        then
-            echo "${line}" >> ${fileout}
-        fi
-    fi
-    # keep memory of this current line to use it if the next one is the
-    # beginning of a block
-    memoline=${line}
-    begin=0
-    # next line
-    il=$(( ${il} + 1 ))
-done
-#
-echo "iii : ${filein} is split in ${dirout}"
-#
-# end
-exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_dia25h
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_dia25h	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_dia25h	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nam_dia25h    !  25h Mean Output                                        (default F)
+&nam_dia25h    !  25h Mean Output                                       (default: OFF)
 !-----------------------------------------------------------------------
    ln_dia25h   = .false.   ! Choose 25h mean output or not
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diaharm
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diaharm	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diaharm	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nam_diaharm   !   Harmonic analysis of tidal constituents               ("key_diaharm")
+&nam_diaharm   !   Harmonic analysis of tidal constituents              ("key_diaharm")
 !-----------------------------------------------------------------------
     nit000_han = 1         ! First time step used for harmonic analysis
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diatmb
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diatmb	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_diatmb	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nam_diatmb    !  Top Middle Bottom Output                               (default F)
+&nam_diatmb    !  Top Middle Bottom Output                              (default: OFF)
 !-----------------------------------------------------------------------
    ln_diatmb   = .false.   !  Choose Top Middle and Bottom output or not
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_tide
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_tide	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_tide	(revision 10321)
@@ -1,6 +1,6 @@
 !-----------------------------------------------------------------------
-&nam_tide      !   tide parameters
+&nam_tide      !   tide parameters                                      (default: OFF)
 !-----------------------------------------------------------------------
-   ln_tide       = .false.                ! Activate tides
+   ln_tide     = .false.      ! Activate tides
       ln_tide_pot   = .true.                !  use tidal potential forcing
          ln_scal_load  = .false.               ! Use scalar approximation for
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_vvl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_vvl	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nam_vvl	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nam_vvl       !   vertical coordinate options                             (default: z-star)
+&nam_vvl       !   vertical coordinate options                          (default: z-star)
 !-----------------------------------------------------------------------
    ln_vvl_zstar  = .true.           !  z-star vertical coordinate
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namage
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namage	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namage	(revision 10321)
@@ -0,0 +1,6 @@
+!-----------------------------------------------------------------------
+&namage          !   AGE 
+!-----------------------------------------------------------------------
+   rn_age_depth      = 10            ! depth over which age tracer reset to zero
+   rn_age_kill_rate  = -0.000138888  !  = -1/7200 recip of relaxation timescale (s) for  age tracer shallower than age_depth
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namagrif
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namagrif	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namagrif	(revision 10321)
@@ -5,4 +5,4 @@
    rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s]
    rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s]
-   ln_chk_bathy  = .FALSE. !
+   ln_chk_bathy  = .false. !  =T  check the parent bathymetry
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namalb
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namalb	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namalb	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namalb         !   albedo parameters
+!------------------------------------------------------------------------------
+   !                                  !                          !  obs range (cloud-sky)
+   rn_alb_sdry      =   0.85          !  dry snow albedo         :  0.85 -- 0.87
+   rn_alb_smlt      =   0.75          !  melting snow albedo     :  0.72 -- 0.82
+   rn_alb_idry      =   0.60          !  dry ice albedo          :  0.54 -- 0.65
+   rn_alb_imlt      =   0.50          !  bare puddled ice albedo :  0.49 -- 0.58
+   rn_alb_dpnd      =   0.27          !  ponded ice albedo       :  0.10 -- 0.30 
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbc
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbc	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbc	(revision 10321)
@@ -1,14 +1,14 @@
 !-----------------------------------------------------------------------
-&nambbc        !   bottom temperature boundary condition                (default: NO)
+&nambbc        !   bottom temperature boundary condition                (default: OFF)
 !-----------------------------------------------------------------------
-!              !  file name      ! frequency (hours) ! variable  ! time interp.!  clim   ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !                 !  (if <0  months)  !   name    !  (logical)  !  (T/F ) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_qgh      ='geothermal_heating.nc',  -12.       , 'heatflow',   .false.   , .true.  , 'yearly'  ,   ''     ,   ''     ,   ''
-   !
    ln_trabbc   = .false.   !  Apply a geothermal heating at the ocean bottom
-   nn_geoflx   =    2      !  geothermal heat flux: = 0 no flux
-                           !     = 1 constant flux
-                           !     = 2 variable flux (read in geothermal_heating.nc in mW/m2)
-   rn_geoflx_cst = 86.4e-3 !  Constant value of geothermal heat flux [W/m2]
-   cn_dir      = './'      !  root directory for the location of the runoff files 
+      nn_geoflx     = 2       !  geothermal heat flux: = 1 constant flux
+      !                       !                        = 2 read variable flux [mW/m2]
+      rn_geoflx_cst = 86.4e-3 !  Constant value of geothermal heat flux       [mW/m2]
+
+   cn_dir      = './'      !  root directory for the geothermal data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_qgh      ='geothermal_heating.nc'  ,       -12.        , 'heatflow',   .false.   , .true. , 'yearly'  ,   ''             ,   ''     ,   ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbl	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambbl	(revision 10321)
@@ -1,9 +1,9 @@
 !-----------------------------------------------------------------------
-&nambbl        !   bottom boundary layer scheme                         (default: NO)
+&nambbl        !   bottom boundary layer scheme                         (default: OFF)
 !-----------------------------------------------------------------------
    ln_trabbl   = .false.   !  Bottom Boundary Layer parameterisation flag
-   nn_bbl_ldf  =  1        !  diffusive bbl (=1)   or not (=0)
-   nn_bbl_adv  =  0        !  advective bbl (=1/2) or not (=0)
-   rn_ahtbbl   =  1000.    !  lateral mixing coefficient in the bbl  [m2/s]
-   rn_gambbl   =  10.      !  advective bbl coefficient                 [s]
+      nn_bbl_ldf  =  1        !  diffusive bbl (=1)   or not (=0)
+      nn_bbl_adv  =  0        !  advective bbl (=1/2) or not (=0)
+      rn_ahtbbl   =  1000.    !  lateral mixing coefficient in the bbl  [m2/s]
+      rn_gambbl   =  10.      !  advective bbl coefficient                 [s]
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy	(revision 10321)
@@ -1,36 +1,36 @@
 !-----------------------------------------------------------------------
-&nambdy        !  unstructured open boundaries                          
+&nambdy        !  unstructured open boundaries                          (default: OFF)
 !-----------------------------------------------------------------------
-    ln_bdy         = .false.              !  Use unstructured open boundaries
-    nb_bdy         = 0                    !  number of open boundary sets
-    ln_coords_file = .true.               !  =T : read bdy coordinates from file
-    cn_coords_file = 'coordinates.bdy.nc' !  bdy coordinates files
-    ln_mask_file   = .false.              !  =T : read mask from file
-    cn_mask_file   = ''                   !  name of mask file (if ln_mask_file=.TRUE.)
-    cn_dyn2d       = 'none'               !
-    nn_dyn2d_dta   =  0                   !  = 0, bdy data are equal to the initial state
-                                          !  = 1, bdy data are read in 'bdydata   .nc' files
-                                          !  = 2, use tidal harmonic forcing data from files
-                                          !  = 3, use external data AND tidal harmonic forcing
-    cn_dyn3d      =  'none'               !
-    nn_dyn3d_dta  =  0                    !  = 0, bdy data are equal to the initial state
-                                          !  = 1, bdy data are read in 'bdydata   .nc' files
-    cn_tra        =  'none'               !
-    nn_tra_dta    =  0                    !  = 0, bdy data are equal to the initial state
-                                          !  = 1, bdy data are read in 'bdydata   .nc' files
-    cn_ice_lim      =  'none'             !
-    nn_ice_lim_dta  =  0                  !  = 0, bdy data are equal to the initial state
-                                          !  = 1, bdy data are read in 'bdydata   .nc' files
-    rn_ice_tem      = 270.                !  lim3 only: arbitrary temperature of incoming sea ice
-    rn_ice_sal      = 10.                 !  lim3 only:      --   salinity           --
-    rn_ice_age      = 30.                 !  lim3 only:      --   age                --
-
-    ln_tra_dmp    =.false.                !  open boudaries conditions for tracers
-    ln_dyn3d_dmp  =.false.                !  open boundary condition for baroclinic velocities
-    rn_time_dmp   =  1.                   ! Damping time scale in days
-    rn_time_dmp_out =  1.                 ! Outflow damping time scale
-    nn_rimwidth   = 10                    !  width of the relaxation zone
-    ln_vol        = .false.               !  total volume correction (see nn_volctl parameter)
-    nn_volctl     = 1                     !  = 0, the total water flux across open boundaries is zero
-    nb_jpk_bdy    = -1                    ! number of levels in the bdy data (set < 0 if consistent with planned run)
+   ln_bdy         = .false.   !  Use unstructured open boundaries
+   nb_bdy         = 0         !  number of open boundary sets
+   ln_coords_file = .true.    !  =T : read bdy coordinates from file
+      cn_coords_file = 'coordinates.bdy.nc'  !  bdy coordinates files
+   ln_mask_file   = .false.   !  =T : read mask from file
+      cn_mask_file= ''        !  name of mask file (if ln_mask_file=.TRUE.)
+   cn_dyn2d    = 'none'       !
+   nn_dyn2d_dta   =  0        !  = 0, bdy data are equal to the initial state
+      !                       !  = 1, bdy data are read in 'bdydata   .nc' files
+      !                       !  = 2, use tidal harmonic forcing data from files
+      !                       !  = 3, use external data AND tidal harmonic forcing
+   cn_dyn3d      =  'none'    !
+   nn_dyn3d_dta  =  0         !  = 0, bdy data are equal to the initial state
+   !                          !  = 1, bdy data are read in 'bdydata   .nc' files
+   cn_tra        =  'none'    !
+   nn_tra_dta    =  0         !  = 0, bdy data are equal to the initial state
+   !                          !  = 1, bdy data are read in 'bdydata   .nc' files
+   cn_ice        =  'none'    !
+   nn_ice_dta    =  0         !  = 0, bdy data are equal to the initial state
+   !                          !  = 1, bdy data are read in 'bdydata   .nc' files
+   rn_ice_tem    = 270.       !  si3 only: arbitrary temperature of incoming sea ice
+   rn_ice_sal    = 10.        !  si3 only:      --   salinity           --
+   rn_ice_age    = 30.        !  si3 only:      --   age                --
+   !
+   ln_tra_dmp    =.false.     !  open boudaries conditions for tracers
+   ln_dyn3d_dmp  =.false.     !  open boundary condition for baroclinic velocities
+   rn_time_dmp   =  1.        !  Damping time scale in days
+   rn_time_dmp_out= 1.        !  Outflow damping time scale
+   nn_rimwidth   = 10         !  width of the relaxation zone
+   ln_vol        = .false.    !  total volume correction (see nn_volctl parameter)
+   nn_volctl     =  1         !  = 0, the total water flux across open boundaries is zero
+   nb_jpk_bdy    = -1         ! number of levels in the bdy data (set < 0 if consistent with planned run)
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_dta
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_dta	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_dta	(revision 10321)
@@ -1,20 +1,21 @@
 !-----------------------------------------------------------------------
-&nambdy_dta    !  open boundaries - external data                       
+&nambdy_dta    !  open boundaries - external data                       (see nam_bdy)
 !-----------------------------------------------------------------------
-!              !  file name      ! frequency (hours) ! variable  ! time interp.!  clim   ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !                 !  (if <0  months)  !   name    !  (logical)  !  (T/F ) ! 'monthly' ! filename ! pairing  ! filename      !
-   bn_ssh      = 'amm12_bdyT_u2d',         24        , 'sossheig',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_u2d      = 'amm12_bdyU_u2d',         24        , 'vobtcrtx',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_v2d      = 'amm12_bdyV_u2d',         24        , 'vobtcrty',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_u3d      = 'amm12_bdyU_u3d',         24        , 'vozocrtx',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_v3d      = 'amm12_bdyV_u3d',         24        , 'vomecrty',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_tem      = 'amm12_bdyT_tra',         24        , 'votemper',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-   bn_sal      = 'amm12_bdyT_tra',         24        , 'vosaline',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-! for lim3
-!   bn_a_i     = 'amm12_bdyT_ice',         24        , 'ileadfra',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-!   bn_h_i     = 'amm12_bdyT_ice',         24        , 'iicethic',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
-!   bn_h_s     = 'amm12_bdyT_ice',         24        , 'isnowthi',    .true.   , .false. ,  'daily'  ,    ''    ,   ''     ,     ''
+   ln_full_vel = .false.      !  ???
 
-   cn_dir      = 'bdydta/' !  root directory for the location of the bulk files
-   ln_full_vel = .false.   !  
+   cn_dir      = 'bdydta/'    !  root directory for the BDY data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   bn_ssh      = 'amm12_bdyT_u2d'        ,         24        , 'sossheig',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_u2d      = 'amm12_bdyU_u2d'        ,         24        , 'vobtcrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_v2d      = 'amm12_bdyV_u2d'        ,         24        , 'vobtcrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_u3d      = 'amm12_bdyU_u3d'        ,         24        , 'vozocrtx',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_v3d      = 'amm12_bdyV_u3d'        ,         24        , 'vomecrty',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_tem      = 'amm12_bdyT_tra'        ,         24        , 'votemper',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+   bn_sal      = 'amm12_bdyT_tra'        ,         24        , 'vosaline',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+!* for si3
+!   bn_a_i     = 'amm12_bdyT_ice'        ,         24        , 'ileadfra',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+!   bn_h_i     = 'amm12_bdyT_ice'        ,         24        , 'iicethic',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
+!   bn_h_s     = 'amm12_bdyT_ice'        ,         24        , 'isnowthi',    .true.   , .false.,  'daily'  ,    ''            ,   ''     ,     ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_tide
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_tide	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nambdy_tide	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nambdy_tide   !  tidal forcing at open boundaries
+&nambdy_tide   !  tidal forcing at open boundaries                      (default: OFF)
 !-----------------------------------------------------------------------
    filtide          = 'bdydta/amm12_bdytide_'   !  file name root of tidal forcing files
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namberg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namberg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namberg	(revision 10321)
@@ -1,34 +1,40 @@
 !-----------------------------------------------------------------------
-&namberg       !   iceberg parameters                                   (default: No iceberg)
+&namberg       !   iceberg parameters                                   (default: OFF)
 !-----------------------------------------------------------------------
-   ln_icebergs              = .false.              ! iceberg floats or not
-   ln_bergdia               = .true.               ! Calculate budgets
-   nn_verbose_level         = 1                    ! Turn on more verbose output if level > 0
-   nn_verbose_write         = 15                   ! Timesteps between verbose messages
-   nn_sample_rate           = 1                    ! Timesteps between sampling for trajectory storage
-                                                   ! Initial mass required for an iceberg of each class
-   rn_initial_mass          = 8.8e7, 4.1e8, 3.3e9, 1.8e10, 3.8e10, 7.5e10, 1.2e11, 2.2e11, 3.9e11, 7.4e11
-                                                   ! Proportion of calving mass to apportion to each class
-   rn_distribution          = 0.24, 0.12, 0.15, 0.18, 0.12, 0.07, 0.03, 0.03, 0.03, 0.02
-                                                   ! Ratio between effective and real iceberg mass (non-dim)
-                                                   ! i.e. number of icebergs represented at a point
-   rn_mass_scaling          = 2000, 200, 50, 20, 10, 5, 2, 1, 1, 1
-                                                   ! thickness of newly calved bergs (m)
+   ln_icebergs = .false.      ! activate iceberg floats (force =F with "key_agrif")
+   !
+   !                          ! diagnostics:
+   ln_bergdia        = .true.       ! Calculate budgets
+   nn_verbose_level  = 1            ! Turn on more verbose output if level > 0
+   nn_verbose_write  = 15           ! Timesteps between verbose messages
+   nn_sample_rate    = 1            ! Timesteps between sampling for trajectory storage
+   !
+   !                          ! iceberg setting:
+   !                                ! Initial mass required for an iceberg of each class
+   rn_initial_mass   = 8.8e7, 4.1e8, 3.3e9, 1.8e10, 3.8e10, 7.5e10, 1.2e11, 2.2e11, 3.9e11, 7.4e11
+   !                                ! Proportion of calving mass to apportion to each class
+   rn_distribution   = 0.24, 0.12, 0.15, 0.18, 0.12, 0.07, 0.03, 0.03, 0.03, 0.02
+   !                                ! Ratio between effective and real iceberg mass (non-dim)
+   !                                ! i.e. number of icebergs represented at a point
+   rn_mass_scaling   = 2000, 200, 50, 20, 10, 5, 2, 1, 1, 1
+                                    ! thickness of newly calved bergs (m)
    rn_initial_thickness     = 40., 67., 133., 175., 250., 250., 250., 250., 250., 250.
-   rn_rho_bergs             = 850.                 ! Density of icebergs
-   rn_LoW_ratio             = 1.5                  ! Initial ratio L/W for newly calved icebergs
-   ln_operator_splitting    = .true.               ! Use first order operator splitting for thermodynamics
-   rn_bits_erosion_fraction = 0.                   ! Fraction of erosion melt flux to divert to bergy bits
-   rn_sicn_shift            = 0.                   ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1)
-   ln_passive_mode          = .false.              ! iceberg - ocean decoupling
-   nn_test_icebergs         =  10                  ! Create test icebergs of this class (-1 = no)
-                                                   ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2)
-   rn_test_box              = 108.0,  116.0, -66.0, -58.0
-   rn_speed_limit           = 0.                   ! CFL speed limit for a berg
+   !
+   rn_rho_bergs            = 850.   ! Density of icebergs
+   rn_LoW_ratio            = 1.5    ! Initial ratio L/W for newly calved icebergs
+   ln_operator_splitting   = .true. ! Use first order operator splitting for thermodynamics
+   rn_bits_erosion_fraction = 0.    ! Fraction of erosion melt flux to divert to bergy bits
+   rn_sicn_shift           = 0.     ! Shift of sea-ice concn in erosion flux (0<sicn_shift<1)
+   ln_passive_mode         = .false.! iceberg - ocean decoupling
+   nn_test_icebergs        =  10    ! Create test icebergs of this class (-1 = no)
+   !                                ! Put a test iceberg at each gridpoint in box (lon1,lon2,lat1,lat2)
+   rn_test_box             = 108.0,  116.0, -66.0, -58.0
+   ln_use_calving          = .false.! Use calving data even when nn_test_icebergs > 0
+   rn_speed_limit          = 0.     ! CFL speed limit for a berg
 
-!         ! file name ! frequency (hours) !   variable   ! time interp. !  clim   ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!         !           !  (if <0  months)  !     name     !   (logical)  !  (T/F ) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_icb =  'calving',       -1          , 'calvingmask',  .true.      , .true.  , 'yearly'  , ''       , ''       , ''
-
-   cn_dir = './'
+   cn_dir      = './'      !  root directory for the calving data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_icb     =  'calving'              ,         -1         ,'calvingmask',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d	(revision 10321)
@@ -1,7 +1,7 @@
 !-----------------------------------------------------------------------
-&namc1d        !   1D configuration options                             ("key_c1d")
+&namc1d        !   1D configuration options                             ("key_c1d" default: PAPA station)
 !-----------------------------------------------------------------------
-   rn_lat1d    =      50   !  Column latitude (default at PAPA station)
-   rn_lon1d    =    -145   !  Column longitude (default at PAPA station)
+   rn_lat1d    =      50   !  Column latitude
+   rn_lon1d    =    -145   !  Column longitude
    ln_c1d_locpt=  .true.   ! Localization of 1D config in a grid (T) or independant point (F)
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_dyndmp
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_dyndmp	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_dyndmp	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namc1d_dyndmp !   U & V newtonian damping                              ("key_c1d")
+&namc1d_dyndmp !   U & V newtonian damping                              ("key_c1d" default: OFF)
 !-----------------------------------------------------------------------
    ln_dyndmp   =  .false.  !  add a damping term (T) or not (F)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_uvd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_uvd	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namc1d_uvd	(revision 10321)
@@ -1,12 +1,14 @@
 !-----------------------------------------------------------------------
-&namc1d_uvd    !   data: U & V currents                                 ("key_c1d")
+&namc1d_uvd    !   data: U & V currents                                 ("key_c1d" default: OFF)
 !-----------------------------------------------------------------------
-!              !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_ucur     = 'ucurrent'  ,         -1        ,'u_current',   .false.    , .true. , 'monthly' ,  ''      ,  'Ume'   , ''
-   sn_vcur     = 'vcurrent'  ,         -1        ,'v_current',   .false.    , .true. , 'monthly' ,  ''      ,  'Vme'   , ''
-!
-   cn_dir        = './'    !  root directory for the location of the files
-   ln_uvd_init   = .false. !  Initialisation of ocean U & V with U & V input data (T) or not (F)
-   ln_uvd_dyndmp = .false. !  damping of ocean U & V toward U & V input data (T) or not (F)
+   !                       !  =T read U-V fields for:
+   ln_uvd_init   = .false.       !  ocean initialisation
+   ln_uvd_dyndmp = .false.       !  U-V restoring
+
+   cn_dir      = './'      !  root directory for the U-V data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_ucur     = 'ucurrent'              ,         -1        ,'u_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Ume'   , ''
+   sn_vcur     = 'vcurrent'              ,         -1        ,'v_current',   .false.   , .true. , 'monthly' ,  ''              ,  'Vme'   , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcfg	(revision 10321)
@@ -1,10 +1,16 @@
 !-----------------------------------------------------------------------
-&namcfg        !   parameters of the configuration                     !   (default: user defined GYRE)
+&namcfg        !   parameters of the configuration                      (default: use namusr_def in namelist_cfg)
 !-----------------------------------------------------------------------
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
-      !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-      cn_domcfg = "domain_cfg"         ! domain configuration filename
+      !                    !  (=F) user defined configuration           (F => create/check namusr_def)
+      cn_domcfg = "domain_cfg"  ! domain configuration filename
       !
-   ln_write_cfg= .true.   !  (=T) create the domain configuration file
+      ln_closea    = .false.    !  T => keep closed seas (defined by closea_mask field) in the  
+      !                         !       domain and apply special treatment of freshwater fluxes.
+      !                         !  F => suppress closed seas (defined by closea_mask field) 
+      !                         !       from the bathymetry at runtime.
+      !                         !  If closea_mask field doesn't exist in the domain_cfg file
+      !                         !       then this logical does nothing.
+   ln_write_cfg= .false.   !  (=T) create the domain configuration file
       cn_domcfg_out = "domain_cfg_out" ! newly created domain configuration filename
       !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcrs
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcrs	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namcrs	(revision 10321)
@@ -5,11 +5,11 @@
    nn_facty    = 3         !  Reduction factor of y-direction
    nn_binref   = 0         !  Bin centering preference: NORTH or EQUAT
-                           !  0, coarse grid is binned with preferential treatment of the north fold
-                           !  1, coarse grid is binned with centering at the equator
-                           !    Symmetry with nn_facty being odd-numbered. Asymmetry with even-numbered nn_facty.
-   nn_msh_crs  = 1         !  create (=1) a mesh file or not (=0)
+      !                    !  0, coarse grid is binned with preferential treatment of the north fold
+      !                    !  1, coarse grid is binned with centering at the equator
+      !                    !    Symmetry with nn_facty being odd-numbered. Asymmetry with even-numbered nn_facty.
+   ln_msh_crs  = .false.   ! =T create a mesh & mask file
    nn_crs_kz   = 0         ! 0, MEAN of volume boxes
-                           ! 1, MAX of boxes
-                           ! 2, MIN of boxes
+      !                    ! 1, MAX of boxes
+      !                    ! 2, MIN of boxes
    ln_crs_wn   = .true.    ! wn coarsened (T) or computed using horizontal divergence ( F )
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namctl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namctl	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namctl	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namctl        !   Control prints 
+&namctl        !   Control prints                                       (default: OFF)
 !-----------------------------------------------------------------------
    ln_ctl      = .false.   !  trends control print (expensive!)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdct
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdct	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdct	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namdct        ! transports through some sections                        ("key_diadct")
+&namdct        ! transports through some sections                       ("key_diadct")
 !-----------------------------------------------------------------------
     nn_dct     = 15        !  time step frequency for transports computing
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdia
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdia	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdia	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namdia         !   Diagnostics
+!------------------------------------------------------------------------------
+   ln_icediachk     = .false.         !  check online the heat, mass & salt budgets (T) or not (F)
+   ln_icediahsb     = .false.         !  output the heat, mass & salt budgets (T) or not (F)
+   ln_icectl        = .false.         !  ice points output for debug (T or F)
+   iiceprt          =  10             !  i-index for debug
+   jiceprt          =  10             !  j-index for debug
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdiu
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdiu	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdiu	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namdiu        !   Cool skin and warm layer models                       (default F)
+&namdiu        !   Cool skin and warm layer models                      (default: OFF)
 !-----------------------------------------------------------------------
    ln_diurnal      = .false.   !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdom
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdom	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdom	(revision 10321)
@@ -3,8 +3,5 @@
 !-----------------------------------------------------------------------
    ln_linssh   = .false.   !  =T  linear free surface  ==>>  model level are fixed in time
-   nn_closea   =    0      !  remove (=0) or keep (=1) closed seas and lakes (ORCA)
-   !
-   nn_msh      =    0      !  create (>0) a mesh file or not (=0)
-   rn_isfhmin  =    1.00   !  treshold (m) to discriminate grounding ice to floating ice
+   rn_isfhmin  =    1.00   !  treshold [m] to discriminate grounding ice from floating ice
    !
    rn_rdt      = 5760.     !  time step for the dynamics and tracer
@@ -12,3 +9,5 @@
    !
    ln_crs      = .false.   !  Logical switch for coarsening module      (T => fill namcrs)
+   !
+   ln_meshmask = .false.   !  =T create a mesh file
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg	(revision 10321)
@@ -1,10 +1,10 @@
 !-----------------------------------------------------------------------
-&namdrg            !   top/bottom drag coefficient                      (default: NO selection)
+&namdrg        !   top/bottom drag coefficient                          (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_NONE    = .false.    !  free-slip       : Cd = 0                  (F => fill namdrg_bot
-   ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
-   ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_OFF      = .false.   !  free-slip       : Cd = 0                  (F => fill namdrg_bot
+   ln_lin      = .false.   !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
+   ln_non_lin  = .false.   !  non-linear  drag: Cd = Cd0 |U|
+   ln_loglayer = .false.   !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
-   ln_drgimp  = .true.     !  implicit top/bottom friction flag
+   ln_drgimp   = .true.    !  implicit top/bottom friction flag
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_bot
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_bot	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_bot	(revision 10321)
@@ -1,11 +1,11 @@
 !-----------------------------------------------------------------------
-&namdrg_bot        !   BOTTOM friction                                  
+&namdrg_bot    !   BOTTOM friction                                      (ln_OFF =F)
 !-----------------------------------------------------------------------
-   rn_Cd0     =  1.e-3    !  drag coefficient [-]
-   rn_Uc0     =  0.4      !  ref. velocity [m/s] (linear drag=Cd0*Uc0) 
-   rn_Cdmax   =  0.1      !  drag value maximum [-] (logarithmic drag)
-   rn_ke0     =  2.5e-3   !  background kinetic energy  [m2/s2] (non-linear cases)
-   rn_z0      =  3.e-3    !  roughness [m] (ln_loglayer=T)
-   ln_boost   = .false.   !  =T regional boost of Cd0 ; =F constant
-      rn_boost=  50.         !  local boost factor  [-]
+   rn_Cd0      =  1.e-3    !  drag coefficient [-]
+   rn_Uc0      =  0.4      !  ref. velocity [m/s] (linear drag=Cd0*Uc0) 
+   rn_Cdmax    =  0.1      !  drag value maximum [-] (logarithmic drag)
+   rn_ke0      =  2.5e-3   !  background kinetic energy  [m2/s2] (non-linear cases)
+   rn_z0       =  3.e-3    !  roughness [m] (ln_loglayer=T)
+   ln_boost    = .false.   !  =T regional boost of Cd0 ; =F constant
+      rn_boost =  50.         !  local boost factor  [-]
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_top
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_top	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdrg_top	(revision 10321)
@@ -1,11 +1,11 @@
 !-----------------------------------------------------------------------
-&namdrg_top        !   TOP friction                                     (ln_isfcav=T)
+&namdrg_top    !   TOP friction                                         (ln_OFF =F & ln_isfcav=T)
 !-----------------------------------------------------------------------
-   rn_Cd0     =  1.e-3     !  drag coefficient [-]
-   rn_Uc0     =  0.4       !  ref. velocity [m/s] (linear drag=Cd0*Uc0) 
-   rn_Cdmax   =  0.1       !  drag value maximum [-] (logarithmic drag)
-   rn_ke0     =  2.5e-3    !  background kinetic energy  [m2/s2] (non-linear cases)
-   rn_z0      =  3.0e-3    !  roughness [m] (ln_loglayer=T)
-   ln_boost   = .false.    !  =T regional boost of Cd0 ; =F constant
-      rn_boost=  50.          !  local boost factor  [-]
+   rn_Cd0      =  1.e-3    !  drag coefficient [-]
+   rn_Uc0      =  0.4      !  ref. velocity [m/s] (linear drag=Cd0*Uc0) 
+   rn_Cdmax    =  0.1      !  drag value maximum [-] (logarithmic drag)
+   rn_ke0      =  2.5e-3   !  background kinetic energy  [m2/s2] (non-linear cases)
+   rn_z0       =  3.0e-3   !  roughness [m] (ln_loglayer=T)
+   ln_boost    = .false.   !  =T regional boost of Cd0 ; =F constant
+      rn_boost =  50.         !  local boost factor  [-]
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdta_dyn
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdta_dyn	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdta_dyn	(revision 10321)
@@ -0,0 +1,26 @@
+!-----------------------------------------------------------------------
+&namdta_dyn    !   offline ocean input files                            (OFF_SRC only)
+!-----------------------------------------------------------------------
+   ln_dynrnf       =  .false.    !  runoffs option enabled (T) or not (F)
+   ln_dynrnf_depth =  .false.    !  runoffs is spread in vertical (T) or not (F)
+!   fwbcorr        = 3.786e-06   !  annual global mean of empmr for ssh correction
+
+   cn_dir      = './'      !  root directory for the ocean data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_tem      = 'dyna_grid_T'           ,       120         , 'votemper'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_sal      = 'dyna_grid_T'           ,       120         , 'vosaline'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_mld      = 'dyna_grid_T'           ,       120         , 'somixhgt'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_emp      = 'dyna_grid_T'           ,       120         , 'sowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_fmf      = 'dyna_grid_T'           ,       120         , 'iowaflup'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_ice      = 'dyna_grid_T'           ,       120         , 'soicecov'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_qsr      = 'dyna_grid_T'           ,       120         , 'soshfldo'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_wnd      = 'dyna_grid_T'           ,       120         , 'sowindsp'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_uwd      = 'dyna_grid_U'           ,       120         , 'uocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_vwd      = 'dyna_grid_V'           ,       120         , 'vocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_wwd      = 'dyna_grid_W'           ,       120         , 'wocetr_eff',  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_avt      = 'dyna_grid_W'           ,       120         , 'voddmavs'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_ubl      = 'dyna_grid_U'           ,       120         , 'sobblcox'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_vbl      = 'dyna_grid_V'           ,       120         , 'sobblcoy'  ,  .true.   , .true. , 'yearly'  , ''               , ''       , ''
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn	(revision 10321)
@@ -0,0 +1,17 @@
+!------------------------------------------------------------------------------
+&namdyn         !   Ice dynamics
+!------------------------------------------------------------------------------
+   ln_dynFULL       = .true.          !  dyn.: full ice dynamics               (rheology + advection + ridging/rafting + correction)
+   ln_dynRHGADV     = .false.         !  dyn.: no ridge/raft & no corrections  (rheology + advection)
+   ln_dynADV        = .false.         !  dyn.: only advection w prescribed vel.(rn_uvice + advection)
+      rn_uice       =   0.00001       !        prescribed ice u-velocity
+      rn_vice       =   0.            !        prescribed ice v-velocity
+   rn_ishlat        =   2.            !  free slip (0) ; partial slip (0-2) ; no slip (2) ; strong slip (>2)
+   ln_landfast      = .false.         !  landfast ice parameterization (T or F)                           
+      rn_gamma      =   0.15          !     fraction of ocean depth that ice must reach to initiate landfast
+                                      !        recommended range: [0.1 ; 0.25]
+      rn_icebfr     =  10.            !     maximum bottom stress per unit area of contact [N/m2]                 
+                                      !        a very large value ensures ice velocity=0 even with a small contact area
+                                      !        recommended range: ?? (should be greater than atm-ice stress => >0.1 N/m2)
+      rn_lfrelax    =   1.e-5         !     relaxation time scale to reach static friction [s-1]
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_adv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_adv	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_adv	(revision 10321)
@@ -2,5 +2,5 @@
 &namdyn_adv    !   formulation of the momentum advection                (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_dynadv_NONE= .false. !  linear dynamics (no momentum advection)
+   ln_dynadv_OFF = .false. !  linear dynamics (no momentum advection)
    ln_dynadv_vec = .false. !  vector form - 2nd centered scheme
      nn_dynkeg     = 0        ! grad(KE) scheme: =0   C2  ;  =1   Hollingsworth correction
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_ldf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_ldf	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_ldf	(revision 10321)
@@ -3,28 +3,30 @@
 !-----------------------------------------------------------------------
    !                       !  Type of the operator :
-   ln_dynldf_NONE=  .false.    !  No operator (i.e. no explicit diffusion)
-   ln_dynldf_lap =  .false.    !    laplacian operator
-   ln_dynldf_blp =  .false.    !  bilaplacian operator
+   ln_dynldf_OFF = .false.     !  No operator (i.e. no explicit diffusion)
+   ln_dynldf_lap = .false.     !    laplacian operator
+   ln_dynldf_blp = .false.     !  bilaplacian operator
    !                       !  Direction of action  :
-   ln_dynldf_lev =  .false.    !  iso-level
-   ln_dynldf_hor =  .false.    !  horizontal (geopotential)
-   ln_dynldf_iso =  .false.    !  iso-neutral
+   ln_dynldf_lev = .false.     !  iso-level
+   ln_dynldf_hor = .false.     !  horizontal  (geopotential)
+   ln_dynldf_iso = .false.     !  iso-neutral (lap only)
    !                       !  Coefficient
-   nn_ahm_ijk_t  = 0           !  space/time variation of eddy coef
-   !                                !  =-30  read in eddy_viscosity_3D.nc file
-   !                                !  =-20  read in eddy_viscosity_2D.nc file
-   !                                !  =  0  constant 
-   !                                !  = 10  F(k)=c1d
-   !                                !  = 20  F(i,j)=F(grid spacing)=c2d
-   !                                !  = 30  F(i,j,k)=c2d*c1d
-   !                                !  = 31  F(i,j,k)=F(grid spacing and local velocity)
-   !                                !  = 32  F(i,j,k)=F(local gridscale and deformation rate)
-   ! Caution in 20 and 30 cases the coefficient have to be given for a 1 degree grid (~111km)
-   rn_ahm_0      =  40000.     !  horizontal laplacian eddy viscosity   [m2/s]
-   rn_ahm_b      =      0.     !  background eddy viscosity for ldf_iso [m2/s]
-   rn_bhm_0      = 1.e+12      !  horizontal bilaplacian eddy viscosity [m4/s]
-   !                       !  Smagorinsky settings (nn_ahm_ijk_t  = 32) :
-   rn_csmc       = 3.5         !  Smagorinsky constant of proportionality
-   rn_minfac     = 1.0         !  multiplier of theorectical lower limit
-   rn_maxfac     = 1.0         !  multiplier of theorectical upper limit
+   nn_ahm_ijk_t  = 0           !  space/time variation of eddy coefficient :
+      !                             !  =-30  read in eddy_viscosity_3D.nc file
+      !                             !  =-20  read in eddy_viscosity_2D.nc file
+      !                             !  =  0  constant 
+      !                             !  = 10  F(k)=c1d
+      !                             !  = 20  F(i,j)=F(grid spacing)=c2d
+      !                             !  = 30  F(i,j,k)=c2d*c1d
+      !                             !  = 31  F(i,j,k)=F(grid spacing and local velocity)
+      !                             !  = 32  F(i,j,k)=F(local gridscale and deformation rate)
+      !                        !  time invariant coefficients :  ahm = 1/2  Uv*Lv   (lap case) 
+      !                             !                            or  = 1/12 Uv*Lv^3 (blp case)
+      rn_Uv      = 0.1              !  lateral viscous velocity [m/s] (nn_ahm_ijk_t= 0, 10, 20, 30)
+      rn_Lv      = 10.e+3           !  lateral viscous length   [m]   (nn_ahm_ijk_t= 0, 10)
+      !                       !  Smagorinsky settings  (nn_ahm_ijk_t= 32) :
+      rn_csmc       = 3.5         !  Smagorinsky constant of proportionality
+      rn_minfac     = 1.0         !  multiplier of theorectical lower limit
+      rn_maxfac     = 1.0         !  multiplier of theorectical upper limit
+      !                       !  iso-neutral laplacian operator (ln_dynldf_iso=T) :
+      rn_ahm_b      = 0.0         !  background eddy viscosity  [m2/s]
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rdgrft
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rdgrft	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rdgrft	(revision 10321)
@@ -0,0 +1,25 @@
+!------------------------------------------------------------------------------
+&namdyn_rdgrft  !   Ice ridging/rafting
+!------------------------------------------------------------------------------
+          ! -- ice_rdgrft_strength -- !
+   ln_str_H79       = .true.          !  ice strength param.: Hibler_79   => P = pstar*<h>*exp(-c_rhg*A)                      
+      rn_pstar      =   2.0e+04       !     ice strength thickness parameter [N/m2]
+      rn_crhg       =   20.0          !     ice strength conc. parameter (-)
+                   ! -- ice_rdgrft -- !
+   rn_csrdg         =   0.5           !  fraction of shearing energy contributing to ridging
+              ! -- ice_rdgrft_prep -- !
+   ln_partf_lin     = .false.         !  Linear ridging participation function (Thorndike et al, 1975)
+      rn_gstar      =   0.15          !     fractional area of thin ice being ridged 
+   ln_partf_exp     = .true.          !  Exponential ridging participation function (Lipscomb, 2007)
+      rn_astar      =   0.03          !     exponential measure of ridging ice fraction [set to 0.05 if hstar=100]
+   ln_ridging       = .true.          !  ridging activated (T) or not (F)
+      rn_hstar      =  25.0           !     determines the maximum thickness of ridged ice [m] (Hibler, 1980)
+      rn_porordg    =   0.3           !     porosity of newly ridged ice (Lepparanta et al., 1995)
+      rn_fsnwrdg    =   0.5           !     snow volume fraction that survives in ridging
+      rn_fpndrdg    =   1.0           !     pond fraction that survives in ridging (small a priori)
+   ln_rafting       = .true.          !  rafting activated (T) or not (F)
+      rn_hraft      =   0.75          !     threshold thickness for rafting [m]
+      rn_craft      =   5.0           !     squeezing coefficient used in the rafting function
+      rn_fsnwrft    =   0.5           !     snow volume fraction that survives in rafting
+      rn_fpndrft    =   1.0           !     pond fraction that survives in rafting (0.5 a priori)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rhg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rhg	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_rhg	(revision 10321)
@@ -0,0 +1,11 @@
+!------------------------------------------------------------------------------
+&namdyn_rhg     !   Ice rheology
+!------------------------------------------------------------------------------
+   ln_rhg_EVP       = .true.          !  EVP rheology
+      ln_aEVP       = .true.          !     adaptive rheology (Kimmritz et al. 2016 & 2017)
+      rn_creepl     =   2.0e-9        !     creep limit [1/s]
+      rn_ecc        =   2.0           !     eccentricity of the elliptical yield curve          
+      nn_nevp       = 120             !     number of EVP subcycles                             
+      rn_relast     =   0.333         !     ratio of elastic timescale to ice time step: Telast = dt_ice * rn_relast 
+                                      !        advised value: 1/3 (rn_nevp=120) or 1/9 (rn_nevp=300)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_spg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_spg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_spg	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namdyn_spg    !   surface pressure gradient                            (default: NO)
+&namdyn_spg    !   surface pressure gradient                            (default: NO selection)
 !-----------------------------------------------------------------------
    ln_dynspg_exp  = .false.   ! explicit free surface
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_vor
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_vor	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namdyn_vor	(revision 10321)
@@ -1,10 +1,14 @@
 !-----------------------------------------------------------------------
-&namdyn_vor    !   Vorticity / Coriolis scheme                          (default: NO)
+&namdyn_vor    !   Vorticity / Coriolis scheme                          (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_dynvor_ene = .false. !  enstrophy conserving scheme
-   ln_dynvor_ens = .false. !  energy conserving scheme
+   ln_dynvor_ene = .false. !  energy    conserving scheme
+   ln_dynvor_ens = .false. !  enstrophy conserving scheme
    ln_dynvor_mix = .false. !  mixed scheme
+   ln_dynvor_enT = .false. !  energy conserving scheme (T-point)
+   ln_dynvor_eeT = .false. !  energy conserving scheme (een using e3t)
    ln_dynvor_een = .false. !  energy & enstrophy scheme
-      nn_een_e3f = 1          ! e3f = masked averaging of e3t divided by 4 (=0) or by the sum of mask (=1)
-   ln_dynvor_msk = .false. !  vorticity multiplied by fmask (=T) or not (=F) (all vorticity schemes)  ! PLEASE DO NOT ACTIVATE
+      nn_een_e3f = 1          ! =0  e3f = mi(mj(e3t))/4 
+      !                       ! =1  e3f = mi(mj(e3t))/mi(mj( tmask))
+   ln_dynvor_msk = .false. !  vorticity multiplied by fmask (=T)        ==>>> PLEASE DO NOT ACTIVATE
+      !                    !  (f-point vorticity schemes only)
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nameos
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nameos	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nameos	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&nameos        !   ocean Equation Of Seawater                           (default: NO)
+&nameos        !   ocean Equation Of Seawater                           (default: NO selection)
 !-----------------------------------------------------------------------
    ln_teos10   = .false.         !  = Use TEOS-10
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namflo
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namflo	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namflo	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namflo        !   float parameters                                      ("key_float")
+&namflo        !   float parameters                                     ("key_float")
 !-----------------------------------------------------------------------
    jpnfl       = 1         !  total number of floats during the run
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namforcing
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namforcing	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namforcing	(revision 10321)
@@ -0,0 +1,13 @@
+!------------------------------------------------------------------------------
+&namforcing     !   Ice surface forcing
+!------------------------------------------------------------------------------
+   rn_cio           =   5.0e-03       !  ice-ocean drag coefficient (-)
+   rn_blow_s        =   0.66          !  mesure of snow blowing into the leads
+                                      !     = 1 => no snow blowing, < 1 => some snow blowing
+   nn_flxdist       =  -1             !  Redistribute heat flux over ice categories
+                                      !     =-1  Do nothing (needs N(cat) fluxes)
+                                      !     = 0  Average N(cat) fluxes then apply the average over the N(cat) ice
+                                      !     = 1  Average N(cat) fluxes then redistribute over the N(cat) ice using T-ice and albedo sensitivity
+                                      !     = 2  Redistribute a single flux over categories
+   nice_jules       = 0               !  Jules coupling (0=OFF, 1=EMULATED, 2=ACTIVE)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namhsb
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namhsb	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namhsb	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namhsb        !  Heat and salt budgets                                  (default F)
+&namhsb        !  Heat and salt budgets                                 (default: OFF)
 !-----------------------------------------------------------------------
    ln_diahsb   = .false.   !  check the heat and salt budgets (T) or not (F)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namini
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namini	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namini	(revision 10321)
@@ -0,0 +1,25 @@
+!------------------------------------------------------------------------------
+&namini         !   Ice initialization
+!------------------------------------------------------------------------------
+   ln_iceini        = .true.          !  activate ice initialization (T) or not (F)
+   ln_iceini_file   = .false.         !  netcdf file provided for initialization (T) or not (F)
+   rn_thres_sst     =   2.0           !  max delta temp. above Tfreeze with initial ice = (sst - tfreeze)
+   rn_hts_ini_n     =   0.3           !  initial real snow thickness (m), North
+   rn_hts_ini_s     =   0.3           !        "            "             South
+   rn_hti_ini_n     =   3.0           !  initial real ice thickness  (m), North
+   rn_hti_ini_s     =   1.0           !        "            "             South
+   rn_ati_ini_n     =   0.9           !  initial ice concentration   (-), North
+   rn_ati_ini_s     =   0.9           !        "            "             South
+   rn_smi_ini_n     =   6.3           !  initial ice salinity     (g/kg), North
+   rn_smi_ini_s     =   6.3           !        "            "             South
+   rn_tmi_ini_n     = 270.            !  initial ice/snw temperature (K), North
+   rn_tmi_ini_s     = 270.            !        "            "             South
+
+   sn_hti = 'Ice_initialization'    , -12 ,'hti'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_hts = 'Ice_initialization'    , -12 ,'hts'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_ati = 'Ice_initialization'    , -12 ,'ati'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_tsu = 'Ice_initialization'    , -12 ,'tsu'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_tmi = 'Ice_initialization'    , -12 ,'tmi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   sn_smi = 'Ice_initialization'    , -12 ,'smi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
+   cn_dir ='./'
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namitd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namitd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namitd	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namitd         !   Ice discretization
+!------------------------------------------------------------------------------
+   ln_cat_hfn       = .true.          !  ice categories are defined by a function following rn_himean**(-0.05)
+      rn_himean     =   2.0           !  expected domain-average ice thickness (m)
+   ln_cat_usr       = .false.         !  ice categories are defined by rn_catbnd below (m)
+      rn_catbnd     =   0.,0.45,1.1,2.1,3.7,6.0  
+   rn_himin         =   0.1           !  minimum ice thickness (m) used in remapping
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namlbc
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namlbc	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namlbc	(revision 10321)
@@ -1,7 +1,7 @@
 !-----------------------------------------------------------------------
-&namlbc        !   lateral momentum boundary condition
+&namlbc        !   lateral momentum boundary condition                  (default: NO selection)
 !-----------------------------------------------------------------------
    !                       !  free slip  !   partial slip  !   no slip   ! strong slip
-   rn_shlat    =    2.     !  shlat = 0  !  0 < shlat < 2  !  shlat = 2  !  2 < shlat
+   rn_shlat    =  -9999.   !  shlat = 0  !  0 < shlat < 2  !  shlat = 2  !  2 < shlat
    ln_vorlat   = .false.   !  consistency of vorticity boundary condition with analytical Eqs.
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namnc4
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namnc4	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namnc4	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namnc4        !   netcdf4 chunking and compression settings             ("key_netcdf4")
+&namnc4        !   netcdf4 chunking and compression settings            ("key_netcdf4")
 !-----------------------------------------------------------------------
    nn_nchunks_i=   4       !  number of chunks in i-dimension
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namobs
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namobs	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namobs	(revision 10321)
@@ -1,6 +1,7 @@
 !-----------------------------------------------------------------------
-&namobs        !  observation usage switch
+&namobs        !  observation usage switch                              (default: OFF)
 !-----------------------------------------------------------------------
    ln_diaobs   = .false.             ! Logical switch for the observation operator
+   !
    ln_t3d      = .false.             ! Logical switch for T profile observations
    ln_s3d      = .false.             ! Logical switch for S profile observations
@@ -51,5 +52,5 @@
    nn_2dint_sss = 0                  ! Horizontal interpolation method for SSS
    nn_2dint_sic = 0                  ! Horizontal interpolation method for SIC
-   nn_msshc    = 0                   ! MSSH correction scheme
+   nn_msshc     = 0                  ! MSSH correction scheme
    nn_profdavtypes = -1              ! Profile daily average types - array
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nampar
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nampar	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/nampar	(revision 10321)
@@ -0,0 +1,18 @@
+!------------------------------------------------------------------------------
+&nampar         !   Generic parameters
+!------------------------------------------------------------------------------
+   jpl              =   5             !  number of ice  categories
+   nlay_i           =   2             !  number of ice  layers
+   nlay_s           =   1             !  number of snow layers (only 1 is working)
+   nn_virtual_itd   =   0             !  virtual ITD mono-category parameterizations (1-3 => jpl = 1 only) or not (0)
+                                      !     2: activate enhanced thermal conductivity only --- temporary option
+                                      !     3: activate virtual thin ice melting only      ---  temporary option
+   ln_icedyn        = .true.          !  ice dynamics (T) or not (F)
+   ln_icethd        = .true.          !  ice thermo   (T) or not (F)
+   rn_amax_n        =   0.997         !  maximum tolerated ice concentration NH
+   rn_amax_s        =   0.997         !  maximum tolerated ice concentration SH
+   cn_icerst_in     = "restart_ice"   !  suffix of ice restart name (input)
+   cn_icerst_out    = "restart_ice"   !  suffix of ice restart name (output)
+   cn_icerst_indir  = "."             !  directory to read   input ice restarts
+   cn_icerst_outdir = "."             !  directory to write output ice restarts
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namptr
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namptr	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namptr	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namptr        !   Poleward Transport Diagnostic                         (default F)
+&namptr        !   Poleward Transport Diagnostic                        (default: OFF)
 !-----------------------------------------------------------------------
    ln_diaptr   = .false.   !  Poleward heat and salt transport (T) or not (F)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namrun
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namrun	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namrun	(revision 10321)
@@ -2,5 +2,5 @@
 &namrun        !   parameters of the run
 !-----------------------------------------------------------------------
-   nn_no       =       0   !  job number (no more used...)
+   nn_no       =       0   !  Assimilation cycle index
    cn_exp      =  "ORCA2"  !  experience name
    nn_it000    =       1   !  first time step
@@ -10,9 +10,9 @@
    nn_leapy    =       0   !  Leap year calendar (1) or not (0)
    ln_rstart   = .false.   !  start from rest (F) or from a restart file (T)
-      nn_euler    =    1            !  = 0 : start with forward time step if ln_rstart=T
-      nn_rstctl   =    0            !  restart control ==> activated only if ln_rstart=T
-      !                             !    = 0 nn_date0 read in namelist ; nn_it000 : read in namelist
-      !                             !    = 1 nn_date0 read in namelist ; nn_it000 : check consistancy between namelist and restart
-      !                             !    = 2 nn_date0 read in restart  ; nn_it000 : check consistancy between namelist and restart
+      nn_euler    =    1      !  = 0 : start with forward time step if ln_rstart=T
+      nn_rstctl   =    0      !  restart control ==> activated only if ln_rstart=T
+      !                          !    = 0 nn_date0 read in namelist ; nn_it000 : read in namelist
+      !                          !    = 1 nn_date0 read in namelist ; nn_it000 : check consistancy between namelist and restart
+      !                          !    = 2 nn_date0 read in restart  ; nn_it000 : check consistancy between namelist and restart
       cn_ocerst_in    = "restart"   !  suffix of ocean restart name (input)
       cn_ocerst_indir = "."         !  directory from which to read input ocean restarts
@@ -29,3 +29,5 @@
    ln_clobber  = .true.    !  clobber (overwrite) an existing file
    nn_chunksz  =       0   !  chunksize (bytes) for NetCDF file (works only with iom_nf90 routines)
+   ln_xios_read = .FALSE.  !  use XIOS to read restart file (only for a single file restart)
+   nn_wxios = 0      !  use XIOS to write restart file 0 - no, 1 - single file output, 2 - multiple file output
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc	(revision 10321)
@@ -1,42 +1,42 @@
 !-----------------------------------------------------------------------
-&namsbc        !   Surface Boundary Condition (surface module)
+&namsbc        !   Surface Boundary Condition manager                   (default: NO selection)
 !-----------------------------------------------------------------------
-   nn_fsbc     = 5         !  frequency of surface boundary condition computation
-                           !     (also = the frequency of sea-ice & iceberg model call)
+   nn_fsbc     = 5         !  frequency of SBC module call
+      !                    !  (control sea-ice & iceberg model call)
                      ! Type of air-sea fluxes 
    ln_usr      = .false.   !  user defined formulation                  (T => check usrdef_sbc)
    ln_flx      = .false.   !  flux formulation                          (T => fill namsbc_flx )
-   ln_blk      = .false.    !  Bulk formulation                          (T => fill namsbc_blk )
-                     ! Type of coupling (Ocean/Ice/Atmosphere) :
+   ln_blk      = .false.   !  Bulk formulation                          (T => fill namsbc_blk )
+      !              ! Type of coupling (Ocean/Ice/Atmosphere) :
    ln_cpl      = .false.   !  atmosphere coupled   formulation          ( requires key_oasis3 )
    ln_mixcpl   = .false.   !  forced-coupled mixed formulation          ( requires key_oasis3 )
    nn_components = 0       !  configuration of the opa-sas OASIS coupling
-                           !  =0 no opa-sas OASIS coupling: default single executable config.
-                           !  =1 opa-sas OASIS coupling: multi executable config., OPA component
-                           !  =2 opa-sas OASIS coupling: multi executable config., SAS component 
+      !                    !  =0 no opa-sas OASIS coupling: default single executable config.
+      !                    !  =1 opa-sas OASIS coupling: multi executable config., OPA component
+      !                    !  =2 opa-sas OASIS coupling: multi executable config., SAS component 
                      ! Sea-ice :
-   nn_ice      = 2         !  =0 no ice boundary condition   ,
-                           !  =1 use observed ice-cover      ,
-                           !  =2 or 3 automatically for LIM3 or CICE    ("key_lim3" or "key_cice")
-                           !          except in AGRIF zoom where it has to be specified
+   nn_ice      = 0         !  =0 no ice boundary condition    
+      !                    !  =1 use observed ice-cover                 (  => fill namsbc_iif )
+      !                    !  =2 or 3 automatically for SI3 or CICE    ("key_si3" or "key_cice")
+      !                    !          except in AGRIF zoom where it has to be specified
    ln_ice_embd = .false.   !  =T embedded sea-ice (pressure + mass and salt exchanges)
-                           !  =F levitating ice (no pressure, mass and salt exchanges)
+      !                    !  =F levitating ice (no pressure, mass and salt exchanges)
                      ! Misc. options of sbc : 
-   ln_traqsr   = .true.    !  Light penetration in the ocean            (T => fill namtra_qsr)
+   ln_traqsr   = .false.   !  Light penetration in the ocean            (T => fill namtra_qsr)
    ln_dm2dc    = .false.   !  daily mean to diurnal cycle on short wave
-   ln_rnf      = .true.    !  runoffs                                   (T => fill namsbc_rnf)
-   ln_ssr      = .true.    !  Sea Surface Restoring on T and/or S       (T => fill namsbc_ssr)
-   nn_fwb      = 2         !  FreshWater Budget: =0 unchecked
-                           !     =1 global mean of e-p-r set to zero at each time step
-                           !     =2 annual global mean of e-p-r set to zero
+   ln_ssr      = .false.   !  Sea Surface Restoring on T and/or S       (T => fill namsbc_ssr)
+   nn_fwb      = 0         !  FreshWater Budget: =0 unchecked
+      !                    !     =1 global mean of e-p-r set to zero at each time step
+      !                    !     =2 annual global mean of e-p-r set to zero
+   ln_rnf      = .false.   !  runoffs                                   (T => fill namsbc_rnf)
    ln_apr_dyn  = .false.   !  Patm gradient added in ocean & ice Eqs.   (T => fill namsbc_apr )
-   ln_isf      = .false.   !  ice shelf                                 (T   => fill namsbc_isf)
+   ln_isf      = .false.   !  ice shelf                                 (T   => fill namsbc_isf & namsbc_iscpl)
    ln_wave     = .false.   !  Activate coupling with wave  (T => fill namsbc_wave)
    ln_cdgw     = .false.   !  Neutral drag coefficient read from wave model (T => ln_wave=.true. & fill namsbc_wave)
    ln_sdw      = .false.   !  Read 2D Surf Stokes Drift & Computation of 3D stokes drift (T => ln_wave=.true. & fill namsbc_wave) 
    nn_sdrift   =  0        !  Parameterization for the calculation of 3D-Stokes drift from the surface Stokes drift
-                           !   = 0 Breivik 2015 parameterization: v_z=v_0*[exp(2*k*z)/(1-8*k*z)]
-                           !   = 1 Phillips:                      v_z=v_o*[exp(2*k*z)-beta*sqrt(-2*k*pi*z)*erfc(sqrt(-2*k*z))]
-                           !   = 2 Phillips as (1) but using the wave frequency from a wave model
+      !                    !   = 0 Breivik 2015 parameterization: v_z=v_0*[exp(2*k*z)/(1-8*k*z)]
+      !                    !   = 1 Phillips:                      v_z=v_o*[exp(2*k*z)-beta*sqrt(-2*k*pi*z)*erfc(sqrt(-2*k*z))]
+      !                    !   = 2 Phillips as (1) but using the wave frequency from a wave model
    ln_tauwoc   = .false.   !  Activate ocean stress modified by external wave induced stress (T => ln_wave=.true. & fill namsbc_wave)
    ln_tauw     = .false.   !  Activate ocean stress components from wave model
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_apr
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_apr	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_apr	(revision 10321)
@@ -2,11 +2,12 @@
 &namsbc_apr    !   Atmospheric pressure used as ocean forcing           (ln_apr_dyn =T)
 !-----------------------------------------------------------------------
-!              ! file name ! frequency (hours) ! variable ! time interp.!  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !           !  (if <0  months)  !   name   !  (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_apr      = 'patm'    ,         -1        ,'somslpre',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,      ''
-
-   cn_dir      = './'      !  root directory for the location of the bulk files
    rn_pref     = 101000.   !  reference atmospheric pressure   [N/m2]/
    ln_ref_apr  = .false.   !  ref. pressure: global mean Patm (T) or a constant (F)
    ln_apr_obc  = .false.   !  inverse barometer added to OBC ssh data
+
+   cn_dir = './'        !  root directory for the Patm data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_apr      = 'patm'                  ,         -1        ,'somslpre' ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,      ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_blk
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_blk	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_blk	(revision 10321)
@@ -1,17 +1,5 @@
 !-----------------------------------------------------------------------
-&namsbc_blk   !   namsbc_blk  generic Bulk formula                      (ln_blk =T)
+&namsbc_blk    !   namsbc_blk  generic Bulk formula                     (ln_blk =T)
 !-----------------------------------------------------------------------
-!              !  file name                   ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights                              ! rotation ! land/sea mask !
-!              !                              !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename                             ! pairing  ! filename      !
-   sn_wndi     = 'u_10.15JUNE2009_fill'       ,         6         , 'U_10_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'   , 'Uwnd'   , ''
-   sn_wndj     = 'v_10.15JUNE2009_fill'       ,         6         , 'V_10_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'   , 'Vwnd'   , ''
-   sn_qsr      = 'ncar_rad.15JUNE2009_fill'   ,        24         , 'SWDN_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_qlw      = 'ncar_rad.15JUNE2009_fill'   ,        24         , 'LWDN_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_tair     = 't_10.15JUNE2009_fill'       ,         6         , 'T_10_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_humi     = 'q_10.15JUNE2009_fill'       ,         6         , 'Q_10_MOD',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_prec     = 'ncar_precip.15JUNE2009_fill',        -1         , 'PRC_MOD1',   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_snow     = 'ncar_precip.15JUNE2009_fill',        -1         , 'SNOW'    ,   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_slp      = 'slp.15JUNE2009_fill'        ,         6         , 'SLP'     ,   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
-   sn_tdif     = 'taudif_core'                ,        24         , 'taudif'  ,   .false.    , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc'  , ''       , ''
    !                    !  bulk algorithm :
    ln_NCAR     = .false.   ! "NCAR"      algorithm   (Large and Yeager 2008)
@@ -19,14 +7,28 @@
    ln_COARE_3p5= .false.   ! "COARE 3.5" algorithm   (Edson et al. 2013)
    ln_ECMWF    = .false.   ! "ECMWF"     algorithm   (IFS cycle 31)
-   !
-   cn_dir      = './'      !  root directory for the location of the bulk files
-   ln_taudif   = .false.   !  HF tau contribution: use "mean of stress module - module of the mean stress" data
-   rn_zqt      = 10.       !  Air temperature and humidity reference height (m)
-   rn_zu       = 10.       !  Wind vector reference height (m)
-   rn_pfac     = 1.        !  multiplicative factor for precipitation (total & snow)
-   rn_efac     = 1.        !  multiplicative factor for evaporation (0. or 1.)
-   rn_vfac     = 0.        !  multiplicative factor for ocean & ice velocity used to
-   !                       !  calculate the wind stress (0.=absolute or 1.=relative winds)
-   ln_Cd_L12   = .false.   !  air-ice drags = F(ice concentration) (Lupkes et al. 2012)
-   ln_Cd_L15   = .false.   !  air-ice drags = F(ice concentration) (Lupkes et al. 2015)
+      !
+      rn_zqt      = 10.       !  Air temperature & humidity reference height (m)
+      rn_zu       = 10.       !  Wind vector reference height (m)
+      ln_Cd_L12   = .false.   !  air-ice drags = F(ice concentration) (Lupkes et al. 2012)
+      ln_Cd_L15   = .false.   !  air-ice drags = F(ice concentration) (Lupkes et al. 2015)
+      ln_taudif   = .false.   !  HF tau contribution: use "mean of stress module - module of the mean stress" data
+      rn_pfac     = 1.        !  multiplicative factor for precipitation (total & snow)
+      rn_efac     = 1.        !  multiplicative factor for evaporation (0. or 1.)
+      rn_vfac     = 0.        !  multiplicative factor for ocean & ice velocity used to
+      !                       !  calculate the wind stress (0.=absolute or 1.=relative winds)
+
+   cn_dir      = './'      !  root directory for the bulk data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!______________________________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ !       weights filename               ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                                      ! pairing  !    filename   !
+   sn_wndi     = 'u_10.15JUNE2009_fill'       ,    6         , 'U_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Uwnd'   , ''
+   sn_wndj     = 'v_10.15JUNE2009_fill'       ,    6         , 'V_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bicubic_noc.nc'  , 'Vwnd'   , ''
+   sn_qsr      = 'ncar_rad.15JUNE2009_fill'   ,   24         , 'SWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_qlw      = 'ncar_rad.15JUNE2009_fill'   ,   24         , 'LWDN_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_tair     = 't_10.15JUNE2009_fill'       ,    6         , 'T_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_humi     = 'q_10.15JUNE2009_fill'       ,    6         , 'Q_10_MOD',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_prec     = 'ncar_precip.15JUNE2009_fill',   -1         , 'PRC_MOD1',   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_snow     = 'ncar_precip.15JUNE2009_fill',   -1         , 'SNOW'    ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_slp      = 'slp.15JUNE2009_fill'        ,    6         , 'SLP'     ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
+   sn_tdif     = 'taudif_core'                ,   24         , 'taudif'  ,   .false.   , .true. , 'yearly'  , 'weights_core_orca2_bilinear_noc.nc' , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_cpl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_cpl	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_cpl	(revision 10321)
@@ -2,7 +2,13 @@
 &namsbc_cpl    !   coupled ocean/atmosphere model                       ("key_oasis3")
 !-----------------------------------------------------------------------
-!                    !     description      !  multiple  !    vector   !      vector          ! vector !
-!                    !                      ! categories !  reference  !    orientation       ! grids  !
-! send
+   nn_cplmodel   =     1   !  Maximum number of models to/from which NEMO is potentially sending/receiving data
+   ln_usecplmask = .false. !  use a coupling mask file to merge data received from several models
+   !                       !   -> file cplmask.nc with the float variable called cplmask (jpi,jpj,nn_cplmodel)
+   nn_cats_cpl   =     5   !  Number of sea ice categories over which coupling is to be carried out (if not 1)
+
+   !_____________!__________________________!____________!_____________!______________________!________!
+   !             !        description       !  multiple  !    vector   !       vector         ! vector !
+   !             !                          ! categories !  reference  !     orientation      ! grids  !
+!***   send    ***
    sn_snd_temp   =   'weighted oce and ice' ,    'no'    ,     ''      ,         ''           ,   ''
    sn_snd_alb    =   'weighted ice'         ,    'no'    ,     ''      ,         ''           ,   ''
@@ -18,5 +24,5 @@
    sn_snd_sstfrz =   'coupled'              ,    'no'    ,     ''      ,         ''           ,   ''
    sn_snd_ttilyr =   'weighted ice'         ,    'no'    ,     ''      ,         ''           ,   ''
-! receive
+!***  receive  ***
    sn_rcv_w10m   =   'none'                 ,    'no'    ,     ''      ,         ''           ,   ''
    sn_rcv_taumod =   'coupled'              ,    'no'    ,     ''      ,         ''           ,   ''
@@ -45,8 +51,3 @@
    sn_rcv_tauw   =   'none'                 ,    'no'    ,     ''      ,         ''          ,   ''
    sn_rcv_wdrag  =   'none'                 ,    'no'    ,     ''      ,         ''          ,   ''
-!
-   nn_cplmodel   =     1   !  Maximum number of models to/from which NEMO is potentialy sending/receiving data
-   ln_usecplmask = .false. !  use a coupling mask file to merge data received from several models
-   !                       !   -> file cplmask.nc with the float variable called cplmask (jpi,jpj,nn_cplmodel)
-   nn_cats_cpl   =     5   !  Number of sea ice categories over which coupling is to be carried out (if not 1)
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_flx
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_flx	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_flx	(revision 10321)
@@ -1,13 +1,13 @@
 !-----------------------------------------------------------------------
-&namsbc_flx    !   surface boundary condition : flux formulation
+&namsbc_flx    !   surface boundary condition : flux formulation        (ln_flx =T)
 !-----------------------------------------------------------------------
-!              !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_utau     = 'utau'      ,        24         , 'utau'    , .false.      , .false., 'yearly'  , ''       , ''       , ''
-   sn_vtau     = 'vtau'      ,        24         , 'vtau'    , .false.      , .false., 'yearly'  , ''       , ''       , ''
-   sn_qtot     = 'qtot'      ,        24         , 'qtot'    , .false.      , .false., 'yearly'  , ''       , ''       , ''
-   sn_qsr      = 'qsr'       ,        24         , 'qsr'     , .false.      , .false., 'yearly'  , ''       , ''       , ''
-   sn_emp      = 'emp'       ,        24         , 'emp'     , .false.      , .false., 'yearly'  , ''       , ''       , ''
-   !
-   cn_dir      = './'      !  root directory for the location of the flux files
+   cn_dir      = './'      !  root directory for the fluxes data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_utau     = 'utau'                  ,        24         , 'utau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_vtau     = 'vtau'                  ,        24         , 'vtau'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_qtot     = 'qtot'                  ,        24         , 'qtot'    , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_qsr      = 'qsr'                   ,        24         , 'qsr'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
+   sn_emp      = 'emp'                   ,        24         , 'emp'     , .false.     , .false., 'yearly'  , ''               , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iif
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iif	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iif	(revision 10321)
@@ -0,0 +1,9 @@
+!-----------------------------------------------------------------------
+&namsbc_iif    !   Ice-IF : use observed ice cover                      (nn_ice = 1)
+!-----------------------------------------------------------------------
+   cn_dir      = './'      !  root directory for the ice cover data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_ice      ='ice_cover_clim.nc'      ,        -12.       ,'ice_cover',   .true.    , .true.  , 'yearly'  ,   ''            ,   ''     ,   ''
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iscpl
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iscpl	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_iscpl	(revision 10321)
@@ -1,5 +1,5 @@
 !-----------------------------------------------------------------------
-&namsbc_iscpl  !   land ice / ocean coupling option                     
-!-----------------------------------------------------------------------
+&namsbc_iscpl  !   land ice / ocean coupling option                     (ln_isfcav =T : read (ln_read_cfg=T) 
+!-----------------------------------------------------------------------             or set or usr_def_zgr )
    nn_drown    = 10        ! number of iteration of the extrapolation loop (fill the new wet cells)
    ln_hsb      = .false.   ! activate conservation module (conservation exact after a time of rn_fiscpl)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_isf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_isf	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_isf	(revision 10321)
@@ -1,33 +1,34 @@
 !-----------------------------------------------------------------------
-&namsbc_isf    !  Top boundary layer (ISF)                              (nn_isf >0)
-!-----------------------------------------------------------------------
-!              ! file name ! frequency (hours) ! variable ! time interp.!  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !           !  (if <0  months)  !   name   !  (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-! nn_isf == 4
-   sn_fwfisf   = 'rnfisf'  ,         -12       ,'sowflisf',   .false.   , .true. , 'yearly'  ,    ''    ,   ''     ,    ''
-! nn_isf == 3
-   sn_rnfisf   = 'rnfisf'  ,         -12       ,'sofwfisf',   .false.   , .true. , 'yearly'  ,    ''    ,   ''     ,    ''
-! nn_isf == 2 and 3
-   sn_depmax_isf='rnfisf'  ,         -12       ,'sozisfmax',  .false.   , .true. , 'yearly'  ,    ''    ,   ''     ,    ''
-   sn_depmin_isf='rnfisf'  ,         -12       ,'sozisfmin',  .false.   , .true. , 'yearly'  ,    ''    ,   ''     ,    ''
-! nn_isf == 2
-   sn_Leff_isf = 'rnfisf'  ,         -12       ,'Leff'    ,   .false.   , .true. , 'yearly'  ,    ''    ,   ''     ,    ''
-!
-! for all case
+&namsbc_isf    !  Top boundary layer (ISF)                              (ln_isfcav =T : read (ln_read_cfg=T) 
+!-----------------------------------------------------------------------             or set or usr_def_zgr )
+   !                 ! type of top boundary layer 
    nn_isf      = 1         !  ice shelf melting/freezing
-                           !  1 = presence of ISF    2 = bg03 parametrisation 
-                           !  3 = rnf file for isf   4 = ISF fwf specified
-                           !  option 1 and 4 need ln_isfcav = .true. (domzgr)
-! only for nn_isf = 1 or 2
-   rn_gammat0  = 1.e-4     ! gammat coefficient used in blk formula
-   rn_gammas0  = 1.e-4     ! gammas coefficient used in blk formula
-! only for nn_isf = 1 or 4
-   rn_hisf_tbl =  30.      ! thickness of the top boundary layer    (Losh et al. 2008)
-   !                       ! 0 => thickness of the tbl = thickness of the first wet cell
-! only for nn_isf = 1
-   nn_isfblk   = 1         ! 1 ISOMIP  like: 2 equations formulation (Hunter et al., 2006)
-   !                       ! 2 ISOMIP+ like: 3 equations formulation (Asay-Davis et al., 2015)
-   nn_gammablk = 1         ! 0 = cst Gammat (= gammat/s)
-   !                       ! 1 = velocity dependend Gamma (u* * gammat/s)  (Jenkins et al. 2010)
-   !                       ! 2 = velocity and stability dependent Gamma    (Holland et al. 1999)
+                           !  1 = presence of ISF   ;  2 = bg03 parametrisation 
+                           !  3 = rnf file for ISF  ;  4 = ISF specified freshwater flux
+                           !  options 1 and 4 need ln_isfcav = .true. (domzgr)
+      !              !  nn_isf = 1 or 2 cases:
+      rn_gammat0  = 1.e-4     ! gammat coefficient used in blk formula
+      rn_gammas0  = 1.e-4     ! gammas coefficient used in blk formula
+      !              !  nn_isf = 1 or 4 cases:
+      rn_hisf_tbl =  30.      ! thickness of the top boundary layer    (Losh et al. 2008)
+      !                       ! 0 => thickness of the tbl = thickness of the first wet cell
+      !              ! nn_isf = 1 case
+      nn_isfblk   = 1         ! 1 ISOMIP  like: 2 equations formulation (Hunter et al., 2006)
+      !                       ! 2 ISOMIP+ like: 3 equations formulation (Asay-Davis et al., 2015)
+      nn_gammablk = 1         ! 0 = cst Gammat (= gammat/s)
+      !                       ! 1 = velocity dependend Gamma (u* * gammat/s)  (Jenkins et al. 2010)
+      !                       ! 2 = velocity and stability dependent Gamma    (Holland et al. 1999)
+
+   !___________!_____________!___________________!___________!_____________!_________!___________!__________!__________!_______________!
+   !           !  file name  ! frequency (hours) ! variable  ! time interp.!  clim   ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+   !           !             !  (if <0  months)  !   name    !  (logical)  !  (T/F)  ! 'monthly' ! filename ! pairing  ! filename      !
+!* nn_isf = 4 case
+   sn_fwfisf   = 'rnfisf'    ,         -12       ,'sowflisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+!* nn_isf = 3 case
+   sn_rnfisf   = 'rnfisf'    ,         -12       ,'sofwfisf' ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+!* nn_isf = 2 and 3 cases 
+   sn_depmax_isf='rnfisf'    ,         -12       ,'sozisfmax',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+   sn_depmin_isf='rnfisf'    ,         -12       ,'sozisfmin',  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
+!* nn_isf = 2 case
+   sn_Leff_isf = 'rnfisf'    ,         -12       ,'Leff'     ,  .false.    , .true.  , 'yearly'  ,    ''    ,   ''     ,    ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_rnf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_rnf	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_rnf	(revision 10321)
@@ -1,15 +1,6 @@
 !-----------------------------------------------------------------------
-&namsbc_rnf    !   runoffs namelist surface boundary condition          (ln_rnf =T)
+&namsbc_rnf    !   runoffs                                              (ln_rnf =T)
 !-----------------------------------------------------------------------
-!              !  file name           ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !                      !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_rnf      = 'runoff_core_monthly',        -1         , 'sorunoff',   .true.     , .true. , 'yearly'  , ''       , ''       , ''
-   sn_cnf      = 'runoff_core_monthly',         0         , 'socoefr0',   .false.    , .true. , 'yearly'  , ''       , ''       , ''
-   sn_s_rnf    = 'runoffs'            ,        24         , 'rosaline',   .true.     , .true. , 'yearly'  , ''       , ''       , ''
-   sn_t_rnf    = 'runoffs'            ,        24         , 'rotemper',   .true.     , .true. , 'yearly'  , ''       , ''       , ''
-   sn_dep_rnf  = 'runoffs'            ,         0         , 'rodepth' ,   .false.    , .true. , 'yearly'  , ''       , ''       , ''
-
-   cn_dir      = './'      !  root directory for the location of the runoff files
-   ln_rnf_mouth= .true.    !  specific treatment at rivers mouths
+   ln_rnf_mouth= .false.   !  specific treatment at rivers mouths
       rn_hrnf     =  15.e0    !  depth over which enhanced vertical mixing is used    (ln_rnf_mouth=T)
       rn_avt_rnf  =   1.e-3   !  value of the additional vertical mixing coef. [m2/s] (ln_rnf_mouth=T)
@@ -22,3 +13,13 @@
       rn_dep_max  = 150.      !  depth over which runoffs is spread ( ln_rnf_depth_ini = .true )
       nn_rnf_depth_file = 0   !  create (=1) a runoff depth file or not (=0)
+
+   cn_dir      = './'      !  root directory for the runoff data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_rnf      = 'runoff_core_monthly'   ,        -1         , 'sorunoff',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_cnf      = 'runoff_core_monthly'   ,         0         , 'socoefr0',   .false.   , .true. , 'yearly'  , ''               , ''       , ''
+   sn_s_rnf    = 'runoffs'               ,        24         , 'rosaline',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_t_rnf    = 'runoffs'               ,        24         , 'rotemper',   .true.    , .true. , 'yearly'  , ''               , ''       , ''
+   sn_dep_rnf  = 'runoffs'               ,         0         , 'rodepth' ,   .false.   , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_sas
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_sas	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_sas	(revision 10321)
@@ -1,18 +1,19 @@
 !-----------------------------------------------------------------------
-&namsbc_sas    !   Stand-Alone Surface boundary condition
+&namsbc_sas    !   Stand-Alone Surface module: ocean data               (SAS_SRC  only)
 !-----------------------------------------------------------------------
-!              !  file name  ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !             !  (if <0  months)  !   name    !  (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_usp      = 'sas_grid_U',     120           , 'uos'     ,   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_vsp      = 'sas_grid_V',     120           , 'vos'     ,   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_tem      = 'sas_grid_T',     120           , 'sosstsst',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_sal      = 'sas_grid_T',     120           , 'sosaline',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_ssh      = 'sas_grid_T',     120           , 'sossheig',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_e3t      = 'sas_grid_T',     120           , 'e3t_m'   ,   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_frq      = 'sas_grid_T',     120           , 'frq_m'   ,   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
+   l_sasread   = .true.    !  =T Read in file ;  =F set all to 0. (see sbcssm)
+      ln_3d_uve   = .false.   !  specify whether we are supplying a 3D u,v and e3 field
+      ln_read_frq = .false.   !  specify whether we must read frq or not
 
-   l_sasread   = .true.    !  =T Read the above fields in a file, =F initialize to 0. in sbcssm.F90
-   ln_3d_uve   = .false.   !  specify whether we are supplying a 3D u,v and e3 field
-   ln_read_frq = .false.   !  specify whether we must read frq or not
-   cn_dir      = './'      !  root directory for the location of the bulk files are
+   cn_dir      = './'      !  root directory for the ocean data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_usp      = 'sas_grid_U'            ,       120         , 'uos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_vsp      = 'sas_grid_V'            ,       120         , 'vos'     ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_tem      = 'sas_grid_T'            ,       120         , 'sosstsst',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_sal      = 'sas_grid_T'            ,       120         , 'sosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_ssh      = 'sas_grid_T'            ,       120         , 'sossheig',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_e3t      = 'sas_grid_T'            ,       120         , 'e3t_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_frq      = 'sas_grid_T'            ,       120         , 'frq_m'   ,   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_ssr
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_ssr	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_ssr	(revision 10321)
@@ -2,16 +2,17 @@
 &namsbc_ssr    !   surface boundary condition : sea surface restoring   (ln_ssr =T)
 !-----------------------------------------------------------------------
-!              ! file name ! frequency (hours) ! variable ! time interp.!  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !           !  (if <0  months)  !   name   !   (logical) !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_sst      = 'sst_data',        24         ,  'sst'   ,    .false.  , .false., 'yearly'  ,    ''    ,    ''    ,     ''
-   sn_sss      = 'sss_data',        -1         ,  'sss'   ,    .true.   , .true. , 'yearly'  ,    ''    ,    ''    ,     ''
+   nn_sstr     =     0     !  add a retroaction term to the surface heat flux (=1) or not (=0)
+      rn_dqdt     = -40.      !  magnitude of the retroaction on temperature   [W/m2/K]
+   nn_sssr     =     0     !  add a damping term to the surface freshwater flux (=2)
+      !                    !  or to SSS only (=1) or no damping term (=0)
+      rn_deds     =  -166.67  !  magnitude of the damping on salinity   [mm/day]
+      ln_sssr_bnd =  .true.   !  flag to bound erp term (associated with nn_sssr=2)
+      rn_sssr_bnd =   4.e0    !  ABS(Max/Min) value of the damping erp term [mm/day]
 
-   cn_dir      = './'      !  root directory for the location of the runoff files
-   nn_sstr     =     0     !  add a retroaction term in the surface heat       flux (=1) or not (=0)
-   nn_sssr     =     2     !  add a damping     term in the surface freshwater flux (=2)
-   !                       !  or to SSS only (=1) or no damping term (=0)
-   rn_dqdt     =   -40.    !  magnitude of the retroaction on temperature   [W/m2/K]
-   rn_deds     =  -166.67  !  magnitude of the damping on salinity   [mm/day]
-   ln_sssr_bnd =  .true.   !  flag to bound erp term (associated with nn_sssr=2)
-   rn_sssr_bnd =   4.e0    !  ABS(Max/Min) value of the damping erp term [mm/day]
+   cn_dir      = './'      !  root directory for the SST/SSS data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_sst      = 'sst_data'              ,        24         ,  'sst'    ,    .false.  , .false., 'yearly'  ,    ''            ,    ''    ,     ''
+   sn_sss      = 'sss_data'              ,        -1         ,  'sss'    ,    .true.   , .true. , 'yearly'  ,    ''            ,    ''    ,     ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_wave
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_wave	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsbc_wave	(revision 10321)
@@ -2,17 +2,17 @@
 &namsbc_wave   ! External fields from wave model                        (ln_wave=T)
 !-----------------------------------------------------------------------
-!              !  file name  ! frequency (hours) ! variable     ! time interp. !  clim   ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !             !  (if <0  months)  !   name       !   (logical)  !  (T/F)  ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_cdg      =  'sdw_wave' ,        1          , 'drag_coeff' ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_usd      =  'sdw_wave' ,        1          , 'u_sd2d'     ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_vsd      =  'sdw_wave' ,        1          , 'v_sd2d'     ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_hsw      =  'sdw_wave' ,        1          , 'hs'         ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_wmp      =  'sdw_wave' ,        1          , 'wmp'        ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_wfr      =  'sdw_wave' ,        1          , 'wfr'        ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_wnum     =  'sdw_wave' ,        1          , 'wave_num'   ,     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_tauwoc   =  'sdw_wave' ,        1          , 'wave_stress',     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_tauwx    =  'sdw_wave' ,        1          , 'wave_stress',     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-   sn_tauwy    =  'sdw_wave' ,        1          , 'wave_stress',     .true.   , .false. , 'daily'   ,  ''      , ''       , ''
-!
-   cn_dir  = './'  !  root directory for the location of drag coefficient files
+   cn_dir      = './'      !  root directory for the waves data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_cdg      =  'sdw_wave'             ,        1          , 'drag_coeff' ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_usd      =  'sdw_wave'             ,        1          , 'u_sd2d'     ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_vsd      =  'sdw_wave'             ,        1          , 'v_sd2d'     ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_hsw      =  'sdw_wave'             ,        1          , 'hs'         ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_wmp      =  'sdw_wave'             ,        1          , 'wmp'        ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_wfr      =  'sdw_wave'             ,        1          , 'wfr'        ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_wnum     =  'sdw_wave'             ,        1          , 'wave_num'   ,  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_tauwoc   =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_tauwx    =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
+   sn_tauwy    =  'sdw_wave'             ,        1          , 'wave_stress',  .true.  , .false., 'daily'   ,  ''             , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsto
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsto	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namsto	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namsto        ! Stochastic parametrization of EOS                      (default: NO)
+&namsto        ! Stochastic parametrization of EOS                      (default: OFF)
 !-----------------------------------------------------------------------
    ln_sto_eos  = .false.   ! stochastic equation of state
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd	(revision 10321)
@@ -0,0 +1,8 @@
+!------------------------------------------------------------------------------
+&namthd         !   Ice thermodynamics
+!------------------------------------------------------------------------------
+   ln_icedH         = .true.          !  activate ice thickness change from growing/melting (T) or not (F)
+   ln_icedA         = .true.          !  activate lateral melting param. (T) or not (F)
+   ln_icedO         = .true.          !  activate ice growth in open-water (T) or not (F)
+   ln_icedS         = .true.          !  activate brine drainage (T) or not (F)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_da
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_da	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_da	(revision 10321)
@@ -0,0 +1,11 @@
+!------------------------------------------------------------------------------
+&namthd_da      !   Ice lateral melting
+!------------------------------------------------------------------------------
+   rn_beta          =   1.0           !  coef. beta for lateral melting param. Recommended range=[0.8-1.2]
+                                      !   => decrease = more melt and melt peaks toward higher concentration (A~0.5 for beta=1 ; A~0.8 for beta=0.2)
+                                      !      0.3 = best fit for western Fram Strait and Antarctica
+                                      !      1.4 = best fit for eastern Fram Strait      
+   rn_dmin          =   8.            !  minimum floe diameter for lateral melting param. Recommended range=[6-10]
+                                      !   => 6  vs 8m = +40% melting at the peak (A~0.5)
+                                      !      10 vs 8m = -20% melting
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_do
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_do	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_do	(revision 10321)
@@ -0,0 +1,9 @@
+!------------------------------------------------------------------------------
+&namthd_do      !   Ice growth in open water
+!------------------------------------------------------------------------------
+   rn_hinew         =   0.1           !  thickness for new ice formation in open water (m), must be larger than rn_hnewice
+   ln_frazil        = .false.         !  Frazil ice parameterization (ice collection as a function of wind)
+      rn_maxfraz    =   1.0           !     maximum fraction of frazil ice collecting at the ice base
+      rn_vfraz      =   0.417         !     thresold drift speed for frazil ice collecting at the ice bottom (m/s)
+      rn_Cfraz      =   5.0           !     squeezing coefficient for frazil ice collecting at the ice bottom
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_pnd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_pnd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_pnd	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namthd_pnd     !   Melt ponds
+!------------------------------------------------------------------------------
+   ln_pnd_H12       = .false.         !  activate evolutive melt ponds (from Holland et al 2012)
+      ln_pnd_fwb    = .false.         !     melt ponds store freshwater or not
+   ln_pnd_CST       = .false.         !  activate constant melt ponds
+      rn_apnd       =   0.2           !     prescribed pond fraction, at Tsu=0
+      rn_hpnd       =   0.05          !     prescribed pond depth, at Tsu=0
+   ln_pnd_alb       = .false.         !  melt ponds affect albedo or not
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_sal
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_sal	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_sal	(revision 10321)
@@ -0,0 +1,15 @@
+!------------------------------------------------------------------------------
+&namthd_sal     !   Ice salinity
+!------------------------------------------------------------------------------
+   nn_icesal        =   2             !  ice salinity option
+                                      !     1: constant ice salinity (S=rn_icesal)
+                                      !     2: varying salinity parameterization S(z,t)
+                                      !     3: prescribed salinity profile S(z), Schwarzacher, 1959
+   rn_icesal        =   4.            !    (nn_icesal=1) ice salinity (g/kg)
+   rn_sal_gd        =   5.            !  restoring ice salinity, gravity drainage (g/kg)
+   rn_time_gd       =   1.73e+6       !  restoring time scale, gravity drainage  (s)
+   rn_sal_fl        =   2.            !  restoring ice salinity, flushing (g/kg)
+   rn_time_fl       =   8.64e+5       !  restoring time scale, flushing (s)
+   rn_simax         =  20.            !  maximum tolerated ice salinity (g/kg)
+   rn_simin         =   0.1           !  minimum tolerated ice salinity (g/kg)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_zdf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_zdf	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namthd_zdf	(revision 10321)
@@ -0,0 +1,10 @@
+!------------------------------------------------------------------------------
+&namthd_zdf     !   Ice heat diffusion
+!------------------------------------------------------------------------------
+   ln_zdf_BL99      = .true.          !  Heat diffusion follows Bitz and Lipscomb 1999
+   ln_cndi_U64      = .false.         !  sea ice thermal conductivity: k = k0 + beta.S/T            (Untersteiner, 1964)
+   ln_cndi_P07      = .true.          !  sea ice thermal conductivity: k = k0 + beta1.S/T - beta2.T (Pringle et al., 2007)
+   rn_cnd_s         =   0.31          !  thermal conductivity of the snow (0.31 W/m/K, Maykut and Untersteiner, 1971)
+                                      !     Obs: 0.1-0.5 (Lecomte et al, JAMES 2013)
+   rn_kappa_i       =   1.0           !  radiation attenuation coefficient in sea ice [1/m]
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_adv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_adv	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_adv	(revision 10321)
@@ -2,5 +2,5 @@
 &namtra_adv    !   advection scheme for tracer                          (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_traadv_NONE= .false. !  No tracer advection
+   ln_traadv_OFF = .false. !  No tracer advection
    ln_traadv_cen = .false. !  2nd order centered scheme
       nn_cen_h   =  4            !  =2/4, horizontal 2nd order CEN / 4th order CEN
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_adv_mle
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_adv_mle	(revision 10320)
+++ 	(revision )
@@ -1,13 +1,0 @@
-!-----------------------------------------------------------------------
-&namtra_adv_mle !   mixed layer eddy parametrisation (Fox-Kemper param) (default: NO)
-!-----------------------------------------------------------------------
-   ln_mle      = .false.   ! (T) use the Mixed Layer Eddy (MLE) parameterisation
-   rn_ce       = 0.06      ! magnitude of the MLE (typical value: 0.06 to 0.08)
-   nn_mle      = 1         ! MLE type: =0 standard Fox-Kemper ; =1 new formulation
-   rn_lf       = 5.e+3     ! typical scale of mixed layer front (meters)                      (case rn_mle=0)
-   rn_time     = 172800.   ! time scale for mixing momentum across the mixed layer (seconds)  (case rn_mle=0)
-   rn_lat      = 20.       ! reference latitude (degrees) of MLE coef.                        (case rn_mle=1)
-   nn_mld_uv   = 0         ! space interpolation of MLD at u- & v-pts (0=min,1=averaged,2=max)
-   nn_conv     = 0         ! =1 no MLE in case of convection ; =0 always MLE
-   rn_rho_c_mle= 0.01      ! delta rho criterion used to calculate MLD for FK
-/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_dmp
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_dmp	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_dmp	(revision 10321)
@@ -1,9 +1,9 @@
 !-----------------------------------------------------------------------
-&namtra_dmp    !   tracer: T & S newtonian damping                      (default: NO)
+&namtra_dmp    !   tracer: T & S newtonian damping                      (default: OFF)
 !-----------------------------------------------------------------------
-   ln_tradmp   =  .true.   !  add a damping term
-      nn_zdmp     =    0      !  vertical shape =0    damping throughout the water column
+   ln_tradmp   =  .false.  !  add a damping term (using resto.nc coef.)
+      nn_zdmp  =    0         !  vertical shape =0    damping throughout the water column
       !                       !                 =1 no damping in the mixing layer (kz  criteria)
       !                       !                 =2 no damping in the mixed  layer (rho crieria)
-      cn_resto    ='resto.nc' !  Name of file containing restoration coeff. field (use dmp_tools to create this)
+      cn_resto = 'resto.nc'   !  Name of file containing restoration coeff. field (use dmp_tools to create this)
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_eiv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_eiv	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_eiv	(revision 10321)
@@ -0,0 +1,19 @@
+!-----------------------------------------------------------------------
+&namtra_eiv    !   eddy induced velocity param.                         (default: OFF)
+!-----------------------------------------------------------------------
+   ln_ldfeiv   = .false.   ! use eddy induced velocity parameterization
+      !
+      !                        !  Coefficients:
+      nn_aei_ijk_t    = 0           !  space/time variation of eddy coefficient:
+      !                             !   =-20 (=-30)    read in eddy_induced_velocity_2D.nc (..._3D.nc) file
+      !                             !   =  0           constant 
+      !                             !   = 10 F(k)      =ldf_c1d 
+      !                             !   = 20 F(i,j)    =ldf_c2d 
+      !                             !   = 21 F(i,j,t)  =Treguier et al. JPO 1997 formulation
+      !                             !   = 30 F(i,j,k)  =ldf_c2d * ldf_c1d
+      !                        !  time invariant coefficients:  aei0 = 1/2  Ue*Le 
+      rn_Ue        = 0.02           !  lateral diffusive velocity [m/s] (nn_aht_ijk_t= 0, 10, 20, 30)
+      rn_Le        = 200.e+3        !  lateral diffusive length   [m]   (nn_aht_ijk_t= 0, 10)
+      !
+      ln_ldfeiv_dia =.false.   ! diagnose eiv stream function and velocities
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_ldf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_ldf	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_ldf	(revision 10321)
@@ -3,31 +3,33 @@
 !-----------------------------------------------------------------------
    !                       !  Operator type:
-   ln_traldf_NONE  =  .false.  !  No explicit diffusion
-   ln_traldf_lap   =  .false.  !    laplacian operator
-   ln_traldf_blp   =  .false.  !  bilaplacian operator
+   ln_traldf_OFF   = .false.   !  No explicit diffusion
+   ln_traldf_lap   = .false.   !    laplacian operator
+   ln_traldf_blp   = .false.   !  bilaplacian operator
    !
    !                       !  Direction of action:
-   ln_traldf_lev   =  .false.  !  iso-level
-   ln_traldf_hor   =  .false.  !  horizontal (geopotential)
-   ln_traldf_iso   =  .false.  !  iso-neutral (standard operator)
-   ln_traldf_triad =  .false.  !  iso-neutral (triad    operator)
+   ln_traldf_lev   = .false.   !  iso-level
+   ln_traldf_hor   = .false.   !  horizontal  (geopotential)
+   ln_traldf_iso   = .false.   !  iso-neutral (standard operator)
+   ln_traldf_triad = .false.   !  iso-neutral (triad    operator)
    !
    !		       	         !  iso-neutral options:        
-   ln_traldf_msc   =  .false.  !  Method of Stabilizing Correction (both operators)
-   rn_slpmax       =   0.01    !  slope limit                      (both operators)
-   ln_triad_iso    =  .false.  !  pure horizontal mixing in ML              (triad only)
-   rn_sw_triad     =  1        !  =1 switching triad ; =0 all 4 triads used (triad only)
-   ln_botmix_triad =  .false.  !  lateral mixing on bottom                  (triad only)
+   ln_traldf_msc   = .false.   !  Method of Stabilizing Correction      (both operators)
+   rn_slpmax       =  0.01     !  slope limit                           (both operators)
+   ln_triad_iso    = .false.   !  pure horizontal mixing in ML              (triad only)
+   rn_sw_triad     = 1         !  =1 switching triad ; =0 all 4 triads used (triad only)
+   ln_botmix_triad = .false.   !  lateral mixing on bottom                  (triad only)
    !
    !                       !  Coefficients:
-   nn_aht_ijk_t    = 0         !  space/time variation of eddy coef
-   !                                !   =-20 (=-30)    read in eddy_diffusivity_2D.nc (..._3D.nc) file
-   !                                !   =  0           constant 
-   !                                !   = 10 F(k)      =ldf_c1d 
-   !                                !   = 20 F(i,j)    =ldf_c2d 
-   !                                !   = 21 F(i,j,t)  =Treguier et al. JPO 1997 formulation
-   !                                !   = 30 F(i,j,k)  =ldf_c2d * ldf_c1d
-   !                                !   = 31 F(i,j,k,t)=F(local velocity and grid-spacing)
-   rn_aht_0        = 2000.     !  lateral eddy diffusivity   (lap. operator) [m2/s]
-   rn_bht_0        = 1.e+12    !  lateral eddy diffusivity (bilap. operator) [m4/s]
+   nn_aht_ijk_t    = 0         !  space/time variation of eddy coefficient:
+      !                             !   =-20 (=-30)    read in eddy_diffusivity_2D.nc (..._3D.nc) file
+      !                             !   =  0           constant 
+      !                             !   = 10 F(k)      =ldf_c1d 
+      !                             !   = 20 F(i,j)    =ldf_c2d 
+      !                             !   = 21 F(i,j,t)  =Treguier et al. JPO 1997 formulation
+      !                             !   = 30 F(i,j,k)  =ldf_c2d * ldf_c1d
+      !                             !   = 31 F(i,j,k,t)=F(local velocity and grid-spacing)
+      !                        !  time invariant coefficients:  aht0 = 1/2  Ud*Ld   (lap case) 
+      !                             !                           or   = 1/12 Ud*Ld^3 (blp case)
+      rn_Ud        = 0.01           !  lateral diffusive velocity [m/s] (nn_aht_ijk_t= 0, 10, 20, 30)
+      rn_Ld        = 200.e+3        !  lateral diffusive length   [m]   (nn_aht_ijk_t= 0, 10)
 /
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_ldfeiv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_ldfeiv	(revision 10320)
+++ 	(revision )
@@ -1,14 +1,0 @@
-!-----------------------------------------------------------------------
-&namtra_ldfeiv !   eddy induced velocity param.                         (default: NO)
-!-----------------------------------------------------------------------
-   ln_ldfeiv     = .false. ! use eddy induced velocity parameterization
-      rn_aeiv_0     = 2000.   ! eddy induced velocity coefficient   [m2/s]
-      nn_aei_ijk_t  = 21      ! space/time variation of the eiv coeficient
-      !                             !   =-20 (=-30)    read in eddy_induced_velocity_2D.nc (..._3D.nc) file
-      !                             !   =  0           constant 
-      !                             !   = 10 F(k)      =ldf_c1d 
-      !                             !   = 20 F(i,j)    =ldf_c2d 
-      !                             !   = 21 F(i,j,t)  =Treguier et al. JPO 1997 formulation
-      !                             !   = 30 F(i,j,k)  =ldf_c2d + ldf_c1d
-      ln_ldfeiv_dia =.false.  ! diagnose eiv stream function and velocities
-/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_mle
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_mle	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_mle	(revision 10321)
@@ -0,0 +1,13 @@
+!-----------------------------------------------------------------------
+&namtra_mle    !   mixed layer eddy parametrisation (Fox-Kemper)       (default: OFF)
+!-----------------------------------------------------------------------
+   ln_mle      = .false.   ! (T) use the Mixed Layer Eddy (MLE) parameterisation
+   rn_ce       = 0.06      ! magnitude of the MLE (typical value: 0.06 to 0.08)
+   nn_mle      = 1         ! MLE type: =0 standard Fox-Kemper ; =1 new formulation
+   rn_lf       = 5.e+3     ! typical scale of mixed layer front (meters)                      (case rn_mle=0)
+   rn_time     = 172800.   ! time scale for mixing momentum across the mixed layer (seconds)  (case rn_mle=0)
+   rn_lat      = 20.       ! reference latitude (degrees) of MLE coef.                        (case rn_mle=1)
+   nn_mld_uv   = 0         ! space interpolation of MLD at u- & v-pts (0=min,1=averaged,2=max)
+   nn_conv     = 0         ! =1 no MLE in case of convection ; =0 always MLE
+   rn_rho_c_mle= 0.01      ! delta rho criterion used to calculate MLD for FK
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_qsr
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_qsr	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtra_qsr	(revision 10321)
@@ -2,15 +2,18 @@
 &namtra_qsr    !   penetrative solar radiation                          (ln_traqsr =T)
 !-----------------------------------------------------------------------
-!              !  file name  ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !             !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_chl      ='chlorophyll',        -1         , 'CHLA'    ,   .true.     , .true. , 'yearly'  , ''       , ''       , ''
-
-   cn_dir      = './'      !  root directory for the location of the runoff files
-   ln_qsr_rgb  = .true.    !  RGB (Red-Green-Blue) light penetration
-   ln_qsr_2bd  = .false.   !  2 bands              light penetration
-   ln_qsr_bio  = .false.   !  bio-model light penetration
-   nn_chldta   =      1    !  RGB : Chl data (=1) or cst value (=0)
-   rn_abs      =   0.58    !  RGB & 2 bands: fraction of light (rn_si1)
-   rn_si0      =   0.35    !  RGB & 2 bands: shortess depth of extinction
-   rn_si1      =   23.0    !  2 bands: longest depth of extinction
+   !                       !  type of penetration                        (default: NO selection)
+   ln_qsr_rgb  = .false.      !  RGB light penetration (Red-Green-Blue)
+   ln_qsr_2bd  = .false.      !  2BD light penetration (two bands)
+   ln_qsr_bio  = .false.      !  bio-model light penetration
+   !                       !  RGB & 2BD choices:
+   rn_abs      =   0.58       !  RGB & 2BD: fraction absorbed in the very near surface
+   rn_si0      =   0.35       !  RGB & 2BD: shortess depth of extinction
+   nn_chldta   =      0       !  RGB : Chl data (=1) or cst value (=0)
+   rn_si1      =   23.0       !  2BD : longest depth of extinction
+   
+   cn_dir      = './'      !  root directory for the chlorophyl data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_chl      ='chlorophyll'            ,        -1         , 'CHLA'    ,   .true.    , .true. , 'yearly'  , ''               , ''       , ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc	(revision 10321)
@@ -0,0 +1,23 @@
+!-----------------------------------------------------------------------
+&namtrc          !   tracers definition
+!-----------------------------------------------------------------------
+   jp_bgc        =  0           !  Number of passive tracers of the BGC model
+   !
+   ln_pisces     =  .false.     !  Run PISCES BGC model 
+   ln_my_trc     =  .false.     !  Run MY_TRC BGC model
+   ln_age        =  .false.     !  Run the sea water age tracer
+   ln_cfc11      =  .false.     !  Run the CFC11 passive tracer
+   ln_cfc12      =  .false.     !  Run the CFC12 passive tracer
+   ln_sf6        =  .false.     !  Run the SF6 passive tracer
+   ln_c14        =  .false.     !  Run the Radiocarbon passive tracer
+   !
+   ln_trcdta     =  .false.  !  Initialisation from data input file (T) or not (F)
+   ln_trcdmp     =  .false.  !  add a damping termn (T) or not (F)
+   ln_trcdmp_clo =  .false.  !  damping term (T) or not (F) on closed seas
+   !
+   jp_dia3d      = 0         ! Number of 3D diagnostic variables
+   jp_dia2d      = 0         ! Number of 2D diagnostic variables
+   !_____________!___________!_________________________________________!____________!________________!
+   !             !    name   !           title of the field            !   units    ! init from file ! 
+!  sn_tracer(1)  = 'tracer  ', 'Tracer  Concentration                 ',   ' - '    ,   .false.
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_adv
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_adv	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_adv	(revision 10321)
@@ -0,0 +1,16 @@
+!-----------------------------------------------------------------------
+&namtrc_adv      !   advection scheme for passive tracer                (default: NO selection)
+!-----------------------------------------------------------------------
+   ln_trcadv_OFF =  .false.  !  No passive tracer advection
+   ln_trcadv_cen =  .false.  !  2nd order centered scheme
+      nn_cen_h   =  4               !  =2/4, horizontal 2nd order CEN / 4th order CEN
+      nn_cen_v   =  4               !  =2/4, vertical   2nd order CEN / 4th order COMPACT
+   ln_trcadv_fct =  .false.  !  FCT scheme
+      nn_fct_h   =  2               !  =2/4, horizontal 2nd / 4th order 
+      nn_fct_v   =  2               !  =2/4, vertical   2nd / COMPACT 4th order 
+   ln_trcadv_mus =  .false.  !  MUSCL scheme
+      ln_mus_ups =  .false.         !  use upstream scheme near river mouths
+   ln_trcadv_ubs =  .false.  !  UBS scheme
+      nn_ubs_v   =  2               !  =2  , vertical 2nd order FCT
+   ln_trcadv_qck =  .false.  !  QUICKEST scheme
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bc
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bc	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bc	(revision 10321)
@@ -0,0 +1,9 @@
+!----------------------------------------------------------------------
+&namtrc_bc       !   data for boundary conditions
+!-----------------------------------------------------------------------
+   cn_dir_sbc    =  './'     !  root directory for the location of SURFACE data files
+   cn_dir_cbc    =  './'     !  root directory for the location of COASTAL data files
+   cn_dir_obc    =  './'     !  root directory for the location of OPEN data files
+   ln_rnf_ctl    = .false.   !  Remove runoff dilution on tracers with absent river load
+   rn_bc_time    =  86400.   !  Time scaling factor for SBC and CBC data (seconds in a day)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bdy
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bdy	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_bdy	(revision 10321)
@@ -0,0 +1,11 @@
+!----------------------------------------------------------------------
+&namtrc_bdy      !   Setup of tracer boundary conditions
+!-----------------------------------------------------------------------
+   cn_trc_dflt   = 'neumann' !  OBC applied by default to all tracers
+   cn_trc        = 'none'    !  Boundary conditions used for tracers with data files (selected in namtrc)
+
+   nn_trcdmp_bdy = 0         !  Use damping timescales defined in nambdy of namelist
+                             !  = 0 NO damping of tracers at open boudaries
+                             !  = 1 Only for tracers forced with external data
+                             !  = 2 Damping applied to all tracers
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dmp
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dmp	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dmp	(revision 10321)
@@ -0,0 +1,8 @@
+!-----------------------------------------------------------------------
+&namtrc_dmp      !   passive tracer newtonian damping                   (ln_trcdmp=T)
+!-----------------------------------------------------------------------
+   nn_zdmp_tr    =    1      !  vertical   shape =0    damping throughout the water column
+                             !                   =1 no damping in the mixing layer (kz  criteria)
+                             !                   =2 no damping in the mixed  layer (rho crieria)
+   cn_resto_tr   = 'resto_tr.nc'    !  create a damping.coeff NetCDF file (=1) or not (=0)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dta
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dta	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_dta	(revision 10321)
@@ -0,0 +1,9 @@
+!-----------------------------------------------------------------------
+&namtrc_dta      !    Initialisation from data input file
+!-----------------------------------------------------------------------
+!                !  file name        ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+!                !                   !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
+   sn_trcdta(1)  = 'data_TRC_nomask' ,        -12        ,  'TRC'    ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
+   !
+   cn_dir        =  './'     !  root directory for the location of the data files
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ice
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ice	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ice	(revision 10321)
@@ -0,0 +1,8 @@
+!-----------------------------------------------------------------------
+&namtrc_ice      !    Representation of sea ice growth & melt effects
+!-----------------------------------------------------------------------
+   nn_ice_tr     =  -1       !  tracer concentration in sea ice 
+                             !    =-1 (no vvl: identical cc in ice and ocean / vvl: cc_ice = 0)
+                             !    = 0 (no vvl: cc_ice = zero / vvl: cc_ice = )
+                             !    = 1 prescribed to a namelist value (implemented in pisces only)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ldf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ldf	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_ldf	(revision 10321)
@@ -0,0 +1,10 @@
+!-----------------------------------------------------------------------
+&namtrc_ldf      !   lateral diffusion scheme for passive tracer        (default: NO selection)
+!-----------------------------------------------------------------------
+!                            !  Type of the operator:
+   ln_trcldf_OFF   =  .false.    !  No explicit diffusion
+   ln_trcldf_tra   =  .false.    !  use active tracer setting
+   !                         !  Coefficient (defined with namtra_ldf coefficient)
+   rn_ldf_multi    = 1.          !  multiplier of aht for TRC mixing coefficient
+   rn_fact_lap     = 1.          !  Equatorial enhanced zonal eddy diffusivity (lap only)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_rad
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_rad	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_rad	(revision 10321)
@@ -0,0 +1,5 @@
+!-----------------------------------------------------------------------
+&namtrc_rad      !  treatment of negative concentrations 
+!-----------------------------------------------------------------------
+   ln_trcrad     =  .true.   !  artificially correct negative concentrations (T) or not (F)
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_run
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_run	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_run	(revision 10321)
@@ -0,0 +1,14 @@
+!-----------------------------------------------------------------------
+&namtrc_run      !   run information
+!-----------------------------------------------------------------------
+   nn_dttrc      =  1        !  time step frequency for passive sn_tracers
+   ln_top_euler  = .false.   !  use Euler time-stepping for TOP
+   ln_rsttr      = .false.   !  start from a restart file (T) or not (F)
+   nn_rsttr      =   0       !  restart control = 0 initial time step is not compared to the restart file value
+                             !                  = 1 do not use the value in the restart file
+                             !                  = 2 calendar parameters read in the restart file
+   cn_trcrst_in  = "restart_trc"   !  suffix of pass. sn_tracer restart name (input)
+   cn_trcrst_indir = "."           !  directory from which to read input passive tracer restarts
+   cn_trcrst_out = "restart_trc"   !  suffix of pass. sn_tracer restart name (output)
+   cn_trcrst_outdir = "."          !  directory to which to write output passive tracer restarts
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_trd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_trd	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrc_trd	(revision 10321)
@@ -0,0 +1,13 @@
+!-----------------------------------------------------------------------
+&namtrc_trd      !   diagnostics on tracer trends                       ('key_trdtrc')
+!                          or mixed-layer trends                        ('key_trdmld_trc')
+!----------------------------------------------------------------------
+   nn_trd_trc    =  5475     !  time step frequency and tracers trends
+   nn_ctls_trc   =   0       !  control surface type in mixed-layer trends (0,1 or n<jpk)
+   rn_ucf_trc    =   1       !  unit conversion factor (=1 -> /seconds ; =86400. -> /day)
+   ln_trdmld_trc_restart = .false. !  restart for ML diagnostics
+   ln_trdmld_trc_instant = .true.  !  flag to diagnose trends of instantantaneous or mean ML T/S
+   ln_trdtrc( 1) = .true.
+   ln_trdtrc( 2) = .true.
+   ln_trdtrc(23) = .true.
+/
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrd	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtrd	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namtrd        !   trend diagnostics                                    (default F)
+&namtrd        !   trend diagnostics                                    (default: OFF)
 !-----------------------------------------------------------------------
    ln_glo_trd  = .false.   ! (T) global domain averaged diag for T, T^2, KE, and PE
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtsd
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtsd	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namtsd	(revision 10321)
@@ -1,12 +1,14 @@
 !-----------------------------------------------------------------------
-&namtsd        !   data : Temperature  & Salinity
+&namtsd        !    Temperature & Salinity Data  (init/dmp)             (default: OFF)
 !-----------------------------------------------------------------------
-!              !  file name                 ! frequency (hours) ! variable ! time interp.!  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
-!              !                            !  (if <0  months)  !   name   !  (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
-   sn_tem = 'data_1m_potential_temperature_nomask',     -1      ,'votemper',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   sn_sal = 'data_1m_salinity_nomask'             ,     -1      ,'vosaline',   .true.    , .true. , 'yearly'  ,    ''    ,    ''    ,    ''
-   !
-   cn_dir      = './'      !  root directory for the location of the runoff files
-   ln_tsd_init = .true.    !  Initialisation of ocean T & S with T & S input data (T) or not (F)
-   ln_tsd_tradmp = .true.  !  damping of ocean T & S toward T & S input data (T) or not (F)
+   !                       ! =T  read T-S fields for:
+   ln_tsd_init = .false.         !  ocean initialisation
+   ln_tsd_dmp  = .false.         !  T-S restoring   (see namtra_dmp)
+   
+   cn_dir      = './'      !  root directory for the T-S data location
+   !___________!_________________________!___________________!___________!_____________!________!___________!__________________!__________!_______________!
+   !           !  file name              ! frequency (hours) ! variable  ! time interp.!  clim  ! 'yearly'/ ! weights filename ! rotation ! land/sea mask !
+   !           !                         !  (if <0  months)  !   name    !   (logical) !  (T/F) ! 'monthly' !                  ! pairing  !    filename   !
+   sn_tem = 'data_1m_potential_temperature_nomask',  -1      , 'votemper',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
+   sn_sal = 'data_1m_salinity_nomask'             ,  -1      , 'vosaline',   .true.    , .true. , 'yearly'  ,    ''            ,    ''    ,    ''
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namwad
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namwad	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namwad	(revision 10321)
@@ -1,13 +1,13 @@
 !-----------------------------------------------------------------------
-&namwad  !   Wetting and drying  default it no WAD
+&namwad        !   Wetting and Drying (WaD)                             (default: OFF)
 !-----------------------------------------------------------------------
-   ln_wd_il          = .false   ! T/F activation of iterative limiter for  wetting and drying scheme
-   ln_wd_dl          = .false.   ! T/F activation of directional llimiter for wetting drying scheme
-   ln_wd_dl_bc       = .false.   ! T/F Directional limiteer Baroclinic option
-   ln_wd_dl_rmp      = .false.   ! T/F Turn on directional limiter ramp
-   rn_wdmin0         =  0.30    ! dpoth at which wetting/drying starts
-   rn_wdmin1         =  0.2     ! Minimum wet depth on dried cells
-   rn_wdmin2         =  0.0001  ! Tolerance of min wet depth on dried cells
-   rn_wdld           =  2.5     ! Land elevation below which wetting/drying is allowed
-   nn_wdit           =   20     ! Max iterations for W/D limiter
+   ln_wd_il    = .false    !  T/F activation of iterative   limiter
+   ln_wd_dl    = .false.   !  T/F activation of directional limiter
+   ln_wd_dl_bc = .false.   !  T/F Directional limiteer Baroclinic option
+   ln_wd_dl_rmp= .false.   !  T/F Turn on directional limiter ramp
+   rn_wdmin0   =  0.30     !  depth at which WaD starts
+   rn_wdmin1   =  0.2      !  Minimum wet depth on dried cells
+   rn_wdmin2   =  0.0001   !  Tolerance of min wet depth on dried cells
+   rn_wdld     =  2.5      !  Land elevation below which WaD is allowed
+   nn_wdit     =   20      !  Max iterations for WaD limiter
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namzdf        !   vertical physics                                     (default: NO selection)
+&namzdf        !   vertical physics manager                             (default: NO selection)
 !-----------------------------------------------------------------------
    !                       ! type of vertical closure (required)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_osm
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_osm	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_osm	(revision 10321)
@@ -1,4 +1,4 @@
 !-----------------------------------------------------------------------
-&namzdf_osm                !   OSM vertical diffusion                   (ln_zdfosm =T)
+&namzdf_osm    !   OSM vertical diffusion                               (ln_zdfosm =T)
 !-----------------------------------------------------------------------
    ln_use_osm_la = .false.      !  Use namelist  rn_osm_la
@@ -14,6 +14,6 @@
    rn_difconv = 1.             ! diffusivity when unstable below BL  (m2/s)
    nn_osm_wave = 0             ! Method used to calculate Stokes drift
-                               !  = 2: Use ECMWF wave fields
-                               !  = 1: Pierson Moskowitz wave spectrum
-                               !  = 0: Constant La# = 0.3
+      !                        !  = 2: Use ECMWF wave fields
+      !                        !  = 1: Pierson Moskowitz wave spectrum
+      !                        !  = 0: Constant La# = 0.3
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_tke
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_tke	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/namelists/namzdf_tke	(revision 10321)
@@ -12,5 +12,5 @@
    !                       !                 = 1 bounded by the local vertical scale factor
    !                       !                 = 2 first vertical derivative of mixing length bounded by 1
-   !                       !                 = 3 as =2 with distinct disspipative an mixing length scale
+   !                       !                 = 3 as =2 with distinct dissipative an mixing length scale
    ln_mxl0     = .true.    !  surface mixing length scale = F(wind stress) (T) or not (F)
    rn_mxl0     =   0.04    !  surface  buoyancy lenght scale minimum value
@@ -26,3 +26,4 @@
                               !        = 0  constant 10 m length scale
                               !        = 1  0.5m at the equator to 30m poleward of 40 degrees
+      rn_eice     =   4       !  below sea ice: =0 ON ; =4 OFF when ice fraction > 1/4   
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/Makefile
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/Makefile	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/Makefile	(revision 10321)
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = NEMO
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/NEMO_guide.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/NEMO_guide.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/NEMO_guide.rst	(revision 10321)
@@ -0,0 +1,74 @@
+#################
+Quick Start Guide
+#################
+
+..
+	For headings markup, this convention is recommended from Python’s Style Guide
+	# with overline, for parts
+	* with overline, for chapters
+	=, for sections
+	-, for subsections
+	^, for subsubsections
+	", for paragraphs
+
+	'global.rst' contains a list of common directives (roles, substitutions and URL links)
+	It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py'
+
+.. toctree::
+	:hidden:
+
+	release_notes.rst
+
+.. toctree::
+	:hidden:
+	:caption: Getting started
+
+	install
+	configurations
+	test_cases
+
+.. toctree::
+	:hidden:
+	:caption: Setup your configuration
+
+	setup
+	diagnostics
+	tools
+
+.. toctree::
+	:hidden:
+	:caption: Advanced use
+
+	zooms
+	coarsening
+	coupling
+	assimilation
+	tracers
+
+.. toctree::
+	:hidden:
+	:caption: Glossary
+
+	definitions
+
+.. include:: readme.rst
+
+.. Next headings markup acording to readme.rst
+
+How to cite NEMO
+================
+
+..	bibliography:: references.bib
+	:all:
+	:style: unsrt
+	:labelprefix: R
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under CeCILL license
+(GNU GPL compatible - see ``./LICENSE``).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_crs_def.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_crs_def.xml	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_crs_def.xml	(revision 10321)
@@ -0,0 +1,80 @@
+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files                                         =
+=                                         put the variables you want...                                    =
+============================================================================================================
+    -->
+ <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4">
+
+    <file_group id="1d" output_freq="1d"  split_freq="1d" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+       <file id="file1" name_suffix="_gcrsT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"       />
+          <field field_ref="toce"         name="votemper"  operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+          <field field_ref="soce"         name="vosaline"  operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+          <field field_ref="mldkz5"       name="somixhgt"  />
+       </file>
+
+       <file id="file2" name_suffix="_gcrsU" description="ocean T grid variables" >
+          <field field_ref="e3u"       name="e3u"           />
+          <field field_ref="uoce"      name="uo"       operation="instant" freq_op="1d" > @uoce_e3u / @e3u </field>
+       </file>
+
+       <file id="file3" name_suffix="_gcrsV" description="ocean T grid variables" >
+          <field field_ref="e3v"       name="e3v"           />
+          <field field_ref="voce"      name="vo"       operation="instant" freq_op="1d" > @voce_e3v / @e3v </field>
+       </file>
+
+       <file id="file4" name_suffix="_gcrsW" description="ocean T grid variables" >
+          <field field_ref="woce"        name="woce"        />
+          <field field_ref="avt"         name="difvho"   />
+       </file>
+
+       <file id="file5" name_suffix="_gcrsC" description="ocean T grid variables" >
+          <field field_ref="Alkalini" operation="instant" freq_op="1d" > @Alkalini_E3T / @e3t </field>
+          <field field_ref="O2"       operation="instant" freq_op="1d" > @O2_E3T / @e3t </field>
+          <field field_ref="Si"       operation="instant" freq_op="1d" > @Si_E3T / @e3t </field>
+          <field field_ref="PHY"      operation="instant" freq_op="1d" > @PHY_E3T / @e3t </field>
+          <field field_ref="ZOO"      operation="instant" freq_op="1d" > @ZOO_E3T / @e3t </field>
+          <field field_ref="DOC"      operation="instant" freq_op="1d" > @DOC_E3T / @e3t </field>
+          <field field_ref="NCHL"     operation="instant" freq_op="1d" > @NCHL_E3T / @e3t </field>
+          <field field_ref="DCHL"     operation="instant" freq_op="1d" > @DCHL_E3T / @e3t </field>
+          <field field_ref="NO3"      operation="instant" freq_op="1d" > @NO3_E3T / @e3t </field>
+       </file>
+
+    </file_group>
+
+    <file_group id="1mo" output_freq="1mo"  split_freq="1mo" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+       <file id="file6" name_suffix="_gcrsC" description="ocean T grid variables" >
+          <field field_ref="DIC"      operation="instant" freq_op="1mo" > @DIC_E3T / @e3t </field>
+          <field field_ref="Alkalini" operation="instant" freq_op="1mo" > @Alkalini_E3T / @e3t </field>
+          <field field_ref="O2"       operation="instant" freq_op="1mo" > @O2_E3T / @e3t </field>
+          <field field_ref="CaCO3"    operation="instant" freq_op="1mo" > @CaCO3_E3T / @e3t </field>
+          <field field_ref="PO4"      operation="instant" freq_op="1mo" > @PO4_E3T / @e3t </field>
+          <field field_ref="POC"      operation="instant" freq_op="1mo" > @POC_E3T / @e3t </field>
+          <field field_ref="Si"       operation="instant" freq_op="1mo" > @Si_E3T / @e3t </field>
+          <field field_ref="PHY"      operation="instant" freq_op="1mo" > @PHY_E3T / @e3t </field>
+          <field field_ref="ZOO"      operation="instant" freq_op="1mo" > @ZOO_E3T / @e3t </field>
+          <field field_ref="DOC"      operation="instant" freq_op="1mo" > @DOC_E3T / @e3t </field>
+          <field field_ref="PHY2"     operation="instant" freq_op="1mo" > @PHY2_E3T / @e3t </field>
+          <field field_ref="ZOO2"     operation="instant" freq_op="1mo" > @ZOO2_E3T / @e3t </field>
+          <field field_ref="DSi"      operation="instant" freq_op="1mo" > @DSi_E3T / @e3t </field>
+          <field field_ref="Fer"      operation="instant" freq_op="1mo" > @Fer_E3T / @e3t </field>
+          <field field_ref="BFe"      operation="instant" freq_op="1mo" > @BFe_E3T / @e3t </field>
+          <field field_ref="GOC"      operation="instant" freq_op="1mo" > @GOC_E3T / @e3t </field>
+          <field field_ref="SFe"      operation="instant" freq_op="1mo" > @SFe_E3T / @e3t </field>
+          <field field_ref="DFe"      operation="instant" freq_op="1mo" > @DFe_E3T / @e3t </field>
+          <field field_ref="GSi"      operation="instant" freq_op="1mo" > @GSi_E3T / @e3t </field>
+          <field field_ref="NFe"      operation="instant" freq_op="1mo" > @NFe_E3T / @e3t </field>
+          <field field_ref="NCHL"     operation="instant" freq_op="1mo" > @NCHL_E3T / @e3t </field>
+          <field field_ref="DCHL"     operation="instant" freq_op="1mo" > @DCHL_E3T / @e3t </field>
+          <field field_ref="NO3"      operation="instant" freq_op="1mo" > @NO3_E3T / @e3t </field>
+          <field field_ref="NH4"      operation="instant" freq_op="1mo" > @NH4_E3T / @e3t </field>
+       </file>
+
+    </file_group>
+
+
+ </file_definition>
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_def.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_def.xml	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/file_def.xml	(revision 10321)
@@ -0,0 +1,111 @@
+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files        default value="9.96921e+36"                                  =
+=                                         put the variables you want...                                    =
+============================================================================================================
+    -->
+    
+    <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4" >
+    
+     
+      <file_group id="1d" output_freq="1d" split_freq="1d" output_level="10" enabled=".TRUE." >  <!-- 5d files -->  
+ 
+	<file id="file1" name_suffix="_gridT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"        />
+          <field field_ref="toce"         name="votemper"   operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+        </file>
+
+	<file id="file2" name_suffix="_gridS" description="ocean T grid variables" >
+          <field field_ref="soce"         name="vosaline"   operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+        </file>
+
+	<file id="file3" name_suffix="_grid2D" description="ocean T grid variables" >
+	  <field field_ref="mldkz5"       name="somixhgt"   /> 
+	  <field field_ref="empmr"        name="sowaflup"   />
+          <field field_ref="empbmr"       name="sowaflupb"  />
+	  <field field_ref="fmmflx"       name="iowaflup"   />
+	  <field field_ref="ice_cover"    name="soicecov"   />
+	  <field field_ref="qsr"          name="soceshwf"   />
+	  <field field_ref="taum"         name="sowindsp"   />
+          <field field_ref="runoffs"      name="runoffs"   />
+        </file>
+	
+	<file id="file4" name_suffix="_gridU" description="ocean U grid variables" >
+          <field field_ref="e3u"          name="e3u"        />
+          <field field_ref="uocetr_eff"   name="uocetr_eff" /> 
+          <field field_ref="utau"         name="tauuo"      />
+        </file>
+	
+	<file id="file5" name_suffix="_gridV" description="ocean V grid variables" >
+          <field field_ref="e3v"          name="e3v"        />
+          <field field_ref="vocetr_eff"   name="vocetr_eff" /> 
+          <field field_ref="vtau"         name="tauvo"      />
+        </file>
+
+        <file id="file6" name_suffix="_gridW" description="ocean W grid variables" >
+          <field field_ref="e3w"          name="e3w"        />
+          <field field_ref="wocetr_eff"   name="wocetr_eff" /> 
+        </file>
+
+        <file id="file7" name_suffix="_gridKZ" description="ocean W grid variables" >
+          <field field_ref="avt"          name="voddmavs"   />
+        </file>
+
+        <file id="file8" name_suffix="_gridH" description="ocean W grid variables" >
+          <field field_ref="hdiv"      name="hdivtr"  long_name="horizontal divergence transport"   operation="average"  freq_op="1d" > @hdiv * @e3t </field> 
+        </file>
+
+      </file_group>
+
+      <file_group id="1mo" output_freq="1mo" split_freq="1mo" output_level="10" enabled=".TRUE." >  <!-- 5d files -->
+
+        <file id="file10" name_suffix="_gridT" description="ocean T grid variables" >
+          <field field_ref="e3t"          name="e3t"        />
+          <field field_ref="toce"         name="votemper"   operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+        </file>
+
+        <file id="file11" name_suffix="_gridS" description="ocean T grid variables" >
+          <field field_ref="soce"         name="vosaline"   operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+        </file>
+
+        <file id="file12" name_suffix="_grid2D" description="ocean T grid variables" >
+          <field field_ref="mldkz5"       name="somixhgt"   />
+          <field field_ref="empmr"        name="sowaflup"   />
+          <field field_ref="empbmr"       name="sowaflupb"  />
+          <field field_ref="fmmflx"       name="iowaflup"   />
+          <field field_ref="ice_cover"    name="soicecov"   />
+          <field field_ref="qsr"          name="soceshwf"   />
+          <field field_ref="taum"         name="sowindsp"   />
+          <field field_ref="runoffs"      name="runoffs"   />
+        </file>
+
+        <file id="file13" name_suffix="_gridU" description="ocean U grid variables" >
+          <field field_ref="e3u"          name="e3u"        />
+          <field field_ref="uocetr_eff"   name="uocetr_eff" /> 
+          <field field_ref="utau"         name="tauuo"      />
+        </file>
+
+        <file id="file14" name_suffix="_gridV" description="ocean V grid variables" >
+          <field field_ref="e3v"          name="e3v"        />
+          <field field_ref="vocetr_eff"   name="vocetr_eff" /> 
+          <field field_ref="vtau"         name="tauvo"      />
+        </file>
+
+        <file id="file15" name_suffix="_gridW" description="ocean W grid variables" >
+          <field field_ref="e3w"          name="e3w"        />
+          <field field_ref="wocetr_eff"   name="wocetr_eff" /> 
+        </file>
+
+        <file id="file16" name_suffix="_gridKZ" description="ocean W grid variables" >
+          <field field_ref="avt"          name="voddmavs"   />
+        </file>
+
+        <file id="file17" name_suffix="_gridH" description="ocean W grid variables" >
+          <field field_ref="hdiv"      name="hdivtr"  long_name="horizontal divergence transport"   operation="average"  freq_op="1d" > @hdiv * @e3t </field> 
+        </file>
+
+
+      </file_group>
+      
+   </file_definition>
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/iodef.xml
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/iodef.xml	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/iodef.xml	(revision 10321)
@@ -0,0 +1,194 @@
+<?xml version="1.0"?>
+<simulation> 
+
+ <context id="nemo" >
+    
+    <!-- $id$ -->
+    
+    <!-- 
+============================================================================================================
+=                                  definition of all existing variables                                    =
+=                                            DO NOT CHANGE                                                 =
+============================================================================================================
+    -->
+    <field_definition src="./field_def.xml"/>
+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files                                         =
+=                                         put the variables you want...                                    =
+============================================================================================================
+       -->
+
+    <file_definition src="./file_def.xml"/>
+
+    <!--
+ 
+============================================================================================================
+= grid definition = = DO NOT CHANGE =
+============================================================================================================
+    -->
+    
+   <axis_definition>  
+      <axis id="deptht"  long_name="Vertical T levels"  unit="m" positive="down" />
+      <axis id="depthu"  long_name="Vertical U levels"  unit="m" positive="down" />
+      <axis id="depthv"  long_name="Vertical V levels"  unit="m" positive="down" />
+      <axis id="depthw"  long_name="Vertical W levels"  unit="m" positive="down" />
+      <axis id="nfloat"  long_name="Float number"       unit="1"                 />
+      <axis id="icbcla"  long_name="Iceberg class"      unit="1"                 />
+      <axis id="ncatice" long_name="Ice category"       unit="1"                 />
+      <axis id="iax_20C" long_name="20 degC isotherm"   unit="degC"              />
+      <axis id="iax_28C" long_name="28 degC isotherm"   unit="degC"              />
+   </axis_definition> 
+    
+   <domain_definition src="./domain_def.xml"/>
+   
+   <grid_definition>    
+     <grid id="grid_T_2D" >
+       <domain id="grid_T" />
+     </grid>
+     <grid id="grid_T_3D" >
+       <domain id="grid_T" />
+       <axis id="deptht" />
+     </grid>
+     <grid id="grid_U_2D" >
+       <domain id="grid_U" />
+     </grid>
+     <grid id="grid_U_3D" >
+       <domain id="grid_U" />
+       <axis id="depthu" />
+     </grid>
+     <grid id="grid_V_2D" >
+       <domain id="grid_V" />
+     </grid>
+     <grid id="grid_V_3D" >
+       <domain id="grid_V" />
+       <axis id="depthv" />
+     </grid>
+     <grid id="grid_W_2D" >
+       <domain id="grid_W" />
+     </grid>
+     <grid id="grid_W_3D" >
+       <domain id="grid_W" />
+       <axis id="depthw" />
+     </grid>
+     <grid id="scalarpoint" />
+
+    </grid_definition> 
+
+  </context>
+  
+    <!-- 
+============================================================================================================
+============================================================================================================
+============================================================================================================
+=                                                    CRS context
+============================================================================================================
+============================================================================================================
+============================================================================================================
+    -->
+
+ <context id="nemo_crs" >
+
+    <!-- $id$ -->
+
+    <!-- 
+============================================================================================================
+=                                  definition of all existing variables                                    =
+=                                            DO NOT CHANGE                                                 =
+============================================================================================================
+    -->
+    <field_definition src="./field_def.xml"/>
+    <!-- 
+============================================================================================================
+=                                           output files definition                                        =
+=                                            Define your own files                                         =
+=                                         put the variables you want...                                    =
+============================================================================================================
+       -->
+
+    <file_definition src="./file_crs_def.xml"/>
+
+    <!--
+ 
+============================================================================================================
+= grid definition = = DO NOT CHANGE =
+============================================================================================================
+    -->
+
+   <axis_definition>
+      <axis id="deptht"  long_name="Vertical T levels"  unit="m" positive="down" />
+      <axis id="depthu"  long_name="Vertical U levels"  unit="m" positive="down" />
+      <axis id="depthv"  long_name="Vertical V levels"  unit="m" positive="down" />
+      <axis id="depthw"  long_name="Vertical W levels"  unit="m" positive="down" />
+      <axis id="nfloat"  long_name="Float number"       unit="1"                 />
+      <axis id="icbcla"  long_name="Iceberg class"      unit="1"                 />
+      <axis id="ncatice" long_name="Ice category"       unit="1"                 />
+      <axis id="iax_20C" long_name="20 degC isotherm"   unit="degC"              />
+      <axis id="iax_28C" long_name="28 degC isotherm"   unit="degC"              />
+   </axis_definition>
+
+   <domain_definition src="./domain_def.xml"/>
+
+   <grid_definition>
+     <grid id="grid_T_2D" >
+       <domain id="grid_T" />
+     </grid>
+     <grid id="grid_T_3D" >
+       <domain id="grid_T" />
+       <axis id="deptht" />
+     </grid>
+     <grid id="grid_U_2D" >
+       <domain id="grid_U" />
+     </grid>
+     <grid id="grid_U_3D" >
+       <domain id="grid_U" />
+       <axis id="depthu" />
+     </grid>
+     <grid id="grid_V_2D" >
+       <domain id="grid_V" />
+     </grid>
+     <grid id="grid_V_3D" >
+       <domain id="grid_V" />
+       <axis id="depthv" />
+     </grid>
+     <grid id="grid_W_2D" >
+       <domain id="grid_W" />
+     </grid>
+     <grid id="grid_W_3D" >
+       <domain id="grid_W" />
+       <axis id="depthw" />
+     </grid>
+     <grid id="scalarpoint" />
+
+    </grid_definition>
+
+  </context>
+
+    <!-- 
+============================================================================================================
+============================================================================================================
+============================================================================================================
+=                                                    XIOS context
+============================================================================================================
+============================================================================================================
+============================================================================================================
+    -->
+
+  <context id="xios">
+
+      <variable_definition>
+	
+     <!-- 
+        We must have buffer_size > jpi*jpj*jpk*8 (with jpi and jpj the subdomain size)
+-->
+	  <variable id="info_level"                type="int">0</variable>
+	  <variable id="using_server"              type="bool">true</variable>
+	  <variable id="using_oasis"               type="bool">false</variable>
+	  <variable id="oasis_codes_id"            type="string" >oceanx</variable>
+	
+      </variable_definition>
+               
+  </context>
+  
+</simulation>
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/style.css
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/style.css	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_static/style.css	(revision 10321)
@@ -0,0 +1,5 @@
+.rstblue               { color: blue    ; }
+.rstgrey , .rstgreysup { color: grey    ; }
+.rstgreen              { color: seagreen; }
+
+.logo { filter: invert(1) !important; }
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_templates/layout.html
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_templates/layout.html	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/_templates/layout.html	(revision 10321)
@@ -0,0 +1,18 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+	<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
+
+{% block sidebartitle %}
+
+	<a href="{{ pathto(master_doc) }}">
+		<img src="{{ pathto('_static/NEMO_grey.png', 1) }}" class="logo" alt="Logo"/>
+	</a>
+
+	<p>Community ocean model for multifarious space and time scales</p>
+
+	<div class="version">{{ release }}</div>
+
+	{% include "searchbox.html" %}
+
+{% endblock %}
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/assimilation.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/assimilation.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/assimilation.rst	(revision 10321)
@@ -0,0 +1,60 @@
+**************************************
+Data assimilation (OBS/SAO, ASM & TAM)
+**************************************
+
+.. contents::
+   :local:
+
+The assimilation interface to NEMO is split into three modules.
+- OBS for the observation operator
+- ASM for the application of increments and model bias correction (based on the assimilation increments).
+- TAM the tangent linear and adjoint model.
+
+Please see the `NEMO manual`_ for more details including information about the input file formats and
+the namelist settings.
+
+Observation and model comparison (OBS)
+======================================
+
+The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity,
+sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and
+calculates an interpolated model equivalent value at the observation location and nearest model timestep.
+The resulting data are saved in a feedback file (or files).
+The code was originally developed for use with the NEMOVAR data assimilation code, but
+can be used for validation or verification of model or any other data assimilation system.
+This is all controlled by the namelist.
+To build with the OBS code active ``key_diaobs`` must be set. 
+
+More details in the `NEMO manual`_ chapter 12.
+
+Standalone observation operator (SAO)
+-------------------------------------
+
+The OBS code can also be run after a model run using saved NEMO model data.
+This is accomplished using the standalone observation operator (SAO)
+(previously known the offline observation operator).
+
+To build the SAO use makenemo.
+This means compiling NEMO once (in the normal way) for the chosen configuration.
+Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file.
+Then recompile with the replacement main program in ``./src/SAO``.
+This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and
+observations and runs the OBS code.
+See section 12.4 of the `NEMO manual`_.
+
+Apply assimilation increments (ASM)
+===================================
+
+The ASM code adds the functionality to apply increments to the model variables:
+temperature, salinity, sea surface height, velocity and sea ice concentration.
+These are read into the model from a NetCDF file which may be produced by separate data assimilation code.
+The code can also output model background fields which are used as an input to data assimilation code.
+This is all controlled by the namelist nam_asminc.
+To build the ASM code ``key asminc`` must be set.
+
+More details in the `NEMO manual`_ chapter 13.
+
+Tangent linear and adjoint (TAM)
+================================
+
+This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coarsening.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coarsening.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coarsening.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../src/OCE/CRS/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/conf.py
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/conf.py	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/conf.py	(revision 10321)
@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'NEMO'
+copyright = ''
+author = 'NEMO System Team'
+
+# The short X.Y version
+version = '4.0'
+# The full version, including alpha/beta/rc tags
+release = '4.0rc'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'NEMO_guide'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['global.rst']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+#	Alabaster theme options
+#	'logo': 'NEMO_grey.png',
+#	'description': 'Community ocean model for multifarious space and time scales',
+#	'fixed_sidebar': True,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+html_favicon = '_static/ORCA.ico'
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'NEMOdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'NEMO_guide.tex', 'NEMO Quick Start Guide',
+     'NEMO System Team', 'howto'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'nemo', 'NEMO Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'NEMO', 'NEMO Documentation',
+     author, 'NEMO', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Customisation -----------------------------------------------------------
+
+import datetime
+year = datetime.date.today().year
+copyright = '2008-' + str( year ) + ', NEMO Consortium'
+
+# Link aliases
+extlinks = {
+	'doi'    : ('http://doi.org/%s'                       , None),
+	'forge'  : ('http://forge.ipsl.jussieu.fr/nemo/%s'    , None),
+	'github' : ('http://github.com/%s'                    , None),
+	'xios'   : ('http://forge.ipsl.jussieu.fr/ioserver/%s', None),
+	'website': ('http://www.nemo-ocean.eu/%s'             , None),
+	'zenodo' : ('http://zenodo.org/publication/%s'        , None)
+}
+
+# Include common directives for every rst file
+rst_epilog = open('global.rst', 'r').read()
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/configurations.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/configurations.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/configurations.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../cfgs/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coupling.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coupling.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/coupling.rst	(revision 10321)
@@ -0,0 +1,13 @@
+**********************
+Coupling (OASIS & SAS)
+**********************
+
+NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface
+(`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_).
+It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz),
+as well as to WRF (Weather Research and Forecasting Model), and to implement the coupling of
+two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand
+(`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_).
+
+To enable the OASIS interface the required compilation key is ``key_oasis3``.
+The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/definitions.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/definitions.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/definitions.rst	(revision 10321)
@@ -0,0 +1,33 @@
+***********
+Definitions
+***********
+
+`AGRIF`_
+	*Adaptive Grid Refinement In Fortran*, 
+	package for the integration of full adaptive mesh refinement features within 
+	an existing multidimensional finite difference model
+
+SI\ :sup:`3`\ 
+	*Sea Ice Integrated Initiative*, 
+	unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+`OASIS`_
+	*Ocean Atmosphere Sea Ice Soil*, 
+	coupling software to synchronise numerical codes representing different components of the climate system
+
+PISCES
+	*Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
+	biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+TAM
+	*Tangent linear and Adjoint Model*, 
+	tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+	sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+TOP
+	*Tracers in Ocean Paradigm*, 
+	on/off-line oceanic tracers transport and biogeochemistry models
+
+`XIOS`_
+	*XML Input Output Server*, 
+	library dedicated to input/output management of climate code
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/diagnostics.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/diagnostics.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/diagnostics.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/global.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/global.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/global.rst	(revision 10321)
@@ -0,0 +1,38 @@
+.. Roles (custom styles related to CSS classes in 'source/_static/style.css')
+
+.. role:: rstblue
+.. role:: rstgreen
+.. role:: rstgrey
+.. role:: rstgreysup(sup)
+.. role:: underline 
+   :class: underline
+
+.. Substitutions
+
+.. |OPA| replace:: :rstblue:`NEMO-OPA`
+.. |SI3| replace:: :rstgrey:`NEMO-SI`\ :rstgreysup:`3`
+.. |TOP| replace:: :rstgreen:`NEMO-TOP/PISCES`
+
+.. Institutes
+
+.. _CMCC:           http://www.cmcc.it 
+.. _CNRS:           http://www.cnrs.fr
+.. _Mercator Océan: http://www.mercator-ocean.fr
+.. _Met Office:     http://www.metoffice.gov.uk
+.. _MOI:            http://www.mercator-ocean.fr
+.. _NERC:           http://nerc.ukri.org
+
+.. Models / Softwares
+
+.. _AGRIF: http://agrif.imag.fr
+.. _OASIS: http://verc.enes.org/oasis
+.. _XIOS:  http://forge.ipsl.jussieu.fr/ioserver
+
+.. NEMO
+
+.. _NEMO:          http://www.nemo-ocean.eu
+.. _NEMO strategy: http://doi.org/10.5281/zenodo.1471663
+.. _NEMO guide:    http://doi.org/10.5281/zenodo.1475325
+.. _NEMO manual:   http://doi.org/10.5281/zenodo.1464816
+.. _SI3 manual:    http://doi.org/10.5281/zenodo.1471689
+.. _TOP manual:    http://doi.org/10.5281/zenodo.1471700
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/install.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/install.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/install.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../INSTALL.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/interfacing_options.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/interfacing_options.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/interfacing_options.rst	(revision 10321)
@@ -0,0 +1,36 @@
+===================
+Interfacing options
+===================
+
+..
+	contents::
+	:local:
+	:depth: 1
+
+.. include:: zooms.rst
+
+.. bibliography:: zooms.bib
+	:all:
+	:style: unsrt
+	:labelprefix: A
+	:keyprefix: a-
+
+----
+
+.. include:: coarsening.rst
+
+----
+
+.. include:: coupling.rst
+
+----
+
+.. include:: assimilation.rst
+
+----
+
+.. include:: input-output.rst
+
+----
+
+.. include:: tracers.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/readme.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/readme.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/readme.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/references.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/references.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/references.bib	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../REFERENCES.bib
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/release_notes.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/release_notes.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/release_notes.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../RELEASE_NOTES.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/setup.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/setup.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/setup.rst	(revision 10321)
@@ -0,0 +1,249 @@
+******************************
+Setting up a new configuration
+******************************
+
+.. contents::
+
+Starting from an existing configuration
+=======================================
+
+There are three options to build a new configuration from an existing one:
+
+Option 1: Duplicate an existing configuration
+---------------------------------------------
+
+The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
+(global, regional, 1D, using embeded zoom with AGRIF...)
+
+One can create a new configuration by duplicating one of the reference configurations
+(``ORCA2_LIM3_PISCES`` in the following example)
+
+.. code-block:: sh
+
+	makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES'
+
+Option 2: Duplicate with differences
+------------------------------------
+
+Create and compile a new configuration based on a reference configuration
+(``ORCA2_LIM3_PISCES`` in the following example) but with different pre-processor options.
+For this either add ``add_key`` or ``del_key`` keys as required; e.g.
+
+.. code-block:: sh
+
+	makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' del_key 'key_iomput' add_key 'key_xios'
+
+Option 3: Use the SIREN tools to subset an existing model
+---------------------------------------------------------
+
+Define a regional configuration which is a sub- or super-set of an existing configuration.
+
+This last option employs the SIREN software tools that are included in the standard distribution.
+The software is written in Fortran 95 and available in the ``./tools/SIREN`` directory.
+SIREN allows you to create your own regional configuration embedded in a wider one.
+
+SIREN is a set of programs to create all the input files you need to run a NEMO regional configuration.
+As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
+as well as examples of namelists are available `here`_.
+
+`SIREN documentation`_
+
+Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_.
+
+Creating a completely new configuration
+=======================================
+
+From NEMO version 4.0 there are two ways to build configurations from scratch.
+The appropriate method to use depends largely on the target configuration.
+Method 1 is for more complex/realistic global or regional configurations and
+method 2 is intended for simpler, idealised configurations whose
+domains and characteristics can be described in simple geometries and formulae.
+
+Option 1: Create and use a domain configuration file
+----------------------------------------------------
+
+This method is used by each of the reference configurations,
+so that downloading their input files linked to their description can help.
+Although starting from scratch it is advisable to create the directory structure to house your new configuration by
+duplicating the closest reference configuration to your target application.
+For example, if your application requires both ocean ice and passive tracers,
+then use the ``ORCA2_LIM3_PISCES`` as template,
+and execute following command to build your ``MY_NEW_CONFIG`` configuration:
+
+.. code-block:: sh
+
+	makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_LIM3_PISCES'
+
+where ``MY_NEW_CONFIG`` can be substituted with a suitably descriptive name for your new configuration.  
+
+The purpose of this step is simply to create and populate the appropriate ``WORK``, ``MY_SRC`` and
+``EXP00`` subdirectories for your new configuration.
+Other choices for the base reference configuration might be
+
+- ``GYRE``  - If your target application is ocean-only
+- ``AMM12`` - If your target application is regional with open boundaries
+
+All the domain information for your new configuration will be contained within
+a netcdf file called ``domain_cfg.nc`` which you will need to create and
+place in the ``./cfgs/MY_NEW_CONFIG/EXP00`` sub-directory.
+Firstly though, ensure that your configuration is set to use such a file by checking that
+
+.. code-block:: fortran
+
+	ln_read_cfg = .true.
+
+in	``./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg``
+
+Create the domain_cfg.nc file which must contain the following fields
+
+.. code-block:: c++
+
+	int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
+	int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
+	int    jperio                            /* lateral global domain b.c.                                   */
+	int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
+	int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
+	double glamt, glamu, glamv, glamf        /* geographic position                                          */
+	double gphit, gphiu, gphiv, gphif        /* geographic position                                          */
+	double iff, ff_f, ff_t                   /* Coriolis parameter (if not on the sphere)                    */
+	double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
+	double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
+	double ie1e2u_v, e1e2u, e1e2v            /* U and V surfaces (if grid size reduction in some straits)    */
+	double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
+	double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+	double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
+	int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+
+There are two options for creating a domain_cfg.nc file:
+
+- Users can use tools of their own choice to build a ``domain_cfg.nc`` with all mandatory fields.
+- Users can adapt and apply the supplied tool available in ``./tools/DOMAINcfg``.
+  This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
+  the horizontal and vertical grids that were available internally to that version.
+  See ``./tools/DOMAINcfg/README`` for details.
+
+Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
+-----------------------------------------------------------------------------
+
+This method is intended for configuring easily simple/idealised configurations which
+are often used as demonstrators or for process evaluation and comparison.
+This method can be used whenever the domain geometry has a simple mathematical description and
+the ocean initial state and boundary forcing is described analytically. 
+As a start, consider the case of starting a completely new ocean-only test case based on
+the ``LOCK_EXCHANGE`` example.
+[Note: we probably need an even more basic example than this with only one namelist and
+minimal changes to the usrdef modules]
+
+Firstly, construct the directory structure, starting in the ``cfgs`` directory:
+
+.. code-block:: sh
+
+	./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE'
+
+where the ``-t`` option has been used to locate the new configuration in the ``tests`` subdirectory
+(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
+This command will have created (amongst others) the following files and directories::
+
+	./tests/MY_NEW_TEST:
+	BLD	  MY_SRC cpp_MY_NEW_TEST.fcm
+	EXP00   WORK
+	#
+	./tests/MY_NEW_TEST/EXP00:
+	context_nemo.xml       domain_def_nemo.xml
+	field_def_nemo-opa.xml file_def_nemo-opa.xml
+	iodef.xml
+	namelist_cfg
+	namelist_ref
+	#
+	./tests/MY_NEW_TEST/MY_SRC:
+	usrdef_hgr.F90    usrdef_nam.F90 usrdef_zgr.F90
+	usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
+
+The key to setting up an idealised configuration lies in adapting a small set of short Fortran 90 modules which
+should be dropped into the ``MY_SRC`` directory.
+Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
+the ``src/OCE/USR`` directory is::
+
+	./src/OCE/USR:
+	usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90
+	usrdef_fmask.F90  usrdef_nam.F90
+	usrdef_hgr.F90    usrdef_sbc.F90
+
+Before discussing these in more detail it is worth noting the various namelist controls that
+engage the different user-defined aspects.
+These controls are set using two new logical switches or are implied by the settings of existing ones.
+For example, the mandatory requirement for an idealised configuration is to provide routines which
+define the horizontal and vertical domains.
+Templates for these are provided in the ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules.
+The application of these modules is activated whenever:
+
+.. code-block:: fortran
+
+	ln_read_cfg = .false.
+
+in any configuration's ``namelist_cfg`` file.
+This setting also activates the reading of an optional ``nam_usrdef`` namelist which can be used to
+supply configuration specific settings.
+These need to be declared and read in the ``usrdef_nam.F90`` module.
+
+Another explicit control is available in the ``namsbc`` namelist which activates the use of analytical forcing.
+With
+
+.. code-block:: fortran
+
+	ln_usr = .true.
+
+Other usrdef modules are activated by less explicit means.
+For example, code in ``usrdef_istate.F90`` is used to define initial temperature and salinity fields if
+
+.. code-block:: fortran
+
+	ln_tsd_init   = .false.
+
+in the ``namtsd`` namelist.
+The remaining modules, namely::
+
+	usrdef_closea.F90 usrdef_fmask.F90
+
+are specific to ORCA configurations and set local variations of some specific fields for
+the various resolutions of the global models.
+They do not need to be considered here in the context of idealised cases but it is worth noting that all
+configuration specific code has now been isolated in the usrdef modules.
+In the case of these last two modules, they are activated only if an ORCA configuration is detected.
+Currently this requires a specific integer variable named ``ORCA`` to be set in a ``domain_cfg.nc`` file.
+[Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from
+the ``domain_cfg.nc`` ]
+
+So, in most cases, the set up of idealised model configurations can be completed by
+copying the template routines from ``./src/OCE/USR`` into
+your new ``./cfgs/MY_NEW_TEST/MY_SRC`` directory and editing the appropriate modules as needed.
+The default set are those used for the GYRE reference configuration.
+The contents of ``MY_SRC`` directories from other idealised configurations may provide more convenient templates if
+they share common characteristics with your target application.
+
+Whatever the starting point it should not require too many changes or additional lines of code to
+produce routines in ``./src/OCE/USR`` that define analytically the domain,
+the initial state and the surface boundary conditions for your new configuration.
+
+To summarize, the base set of modules is:
+
+- ``usrdef_hgr.F90``   : define horizontal grid
+- ``usrdef_zgr.F90``   : define vertical grid
+- ``usrdef_sbc.F90``   : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
+- ``usrdef_istate.F90``: defines initialization of the dynamics and tracers
+- ``usrdef_nam.F90``   : configuration-specific namelist processing to set any associated run-time parameters
+
+with two specialised ORCA modules
+(not related to idealised configurations but used to isolate configuration specific code that is used in
+ORCA2 reference configurations and established global configurations using the ORCA tripolar grid):
+
+- ``usrdef_fmask.F90`` : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits
+- ``usrdef_closea.F90``: only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas
+
+From version 4.0, the NEMO release includes a ``tests`` subdirectory containing available and
+up to date test cases build by the community.
+These will not be fully supported as is NEMO reference but should provide a source of raw material.
+
+.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar
+.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2
+.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.bib	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../tests/test_cases.bib
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/test_cases.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../tests/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tools.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tools.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tools.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../tools/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tracers.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tracers.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/tracers.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../src/TOP/README.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.bib	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/zooms.bib
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/rst/source/zooms.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/README.rst
Index: MO/branches/UKMO/NEMO4_beta_mirror/doc/variables_checking.sh
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/doc/variables_checking.sh	(revision 10320)
+++ 	(revision )
@@ -1,15 +1,0 @@
-#!/bin/sh
-
-#set -euvx
-
-#shared_namelist_files=$( ls ../NEMOGCM/CONFIG/SHARED/namelist_* )
-shared_namelist_files=$( ls ~/Workspace/NEMO/branches/trunk/NEMOGCM/CONFIG/SHARED/namelist_* )
-
-namelist_variables=$( awk '($1 ~ /[cdlnrsy]n_/ ) {print $1}' ${shared_namelist_files} \
-								| sed 's/[=(].*//' | sort -u												)
-
-for variable in ${namelist_variables}; do
-	[[ $( grep ${variable/_/\\\\\\\\_} tex_sub/*.tex ) ]] && echo $variable ${variable//_/\\\\\\\\_} && exit 0
-done
-
-exit 0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice.F90	(revision 10321)
@@ -367,5 +367,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice1d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice1d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/ice1d.F90	(revision 10321)
@@ -165,5 +165,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icealb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icealb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icealb.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icecor.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icecor.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icecor.F90	(revision 10321)
@@ -39,5 +39,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icectl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icectl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icectl.F90	(revision 10321)
@@ -46,5 +46,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedia.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedia.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedia.F90	(revision 10321)
@@ -42,5 +42,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn.F90	(revision 10321)
@@ -53,5 +53,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_pra.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_pra.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_pra.F90	(revision 10321)
@@ -50,5 +50,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_umx.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_umx.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_adv_umx.F90	(revision 10321)
@@ -39,5 +39,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rdgrft.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rdgrft.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rdgrft.F90	(revision 10321)
@@ -79,5 +79,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg_evp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg_evp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icedyn_rhg_evp.F90	(revision 10321)
@@ -51,5 +51,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceforcing.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceforcing.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceforcing.F90	(revision 10321)
@@ -38,7 +38,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/ICE 4.0 , UCL NEMO Consortium (2018)
+   !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceistate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceistate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceistate.F90	(revision 10321)
@@ -64,5 +64,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceitd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceitd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceitd.F90	(revision 10321)
@@ -50,5 +50,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icerst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icerst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icerst.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icestp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icestp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icestp.F90	(revision 10321)
@@ -91,5 +91,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icetab.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icetab.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icetab.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd.F90	(revision 10321)
@@ -57,5 +57,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_da.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_da.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_da.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_dh.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_dh.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_dh.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_do.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_do.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_do.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_ent.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_ent.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_ent.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_pnd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_pnd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_pnd.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_sal.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_sal.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_sal.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf_bl99.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf_bl99.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icethd_zdf_bl99.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceupdate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceupdate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/iceupdate.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icevar.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icevar.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icevar.F90	(revision 10321)
@@ -78,5 +78,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icewri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icewri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/ICE/icewri.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/ICE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif2model.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif2model.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif2model.F90	(revision 10321)
@@ -1,18 +1,18 @@
 #if defined key_agrif
-!!----------------------------------------------------------------------
-!! NEMO/NST 3.6 , NEMO Consortium (2018)
-!! $Id$
-!! Software governed by the CeCILL licence (./LICENSE)
-!!----------------------------------------------------------------------
+   !!----------------------------------------------------------------------
+   !! NEMO/NST 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
+   !!----------------------------------------------------------------------
 SUBROUTINE Agrif2Model
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif2Model ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif2Model ***
+      !!--------------------------------------------- 
 END SUBROUTINE Agrif2model
 
 SUBROUTINE Agrif_Set_numberofcells(Agrif_Gr)
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif_Set_numberofcells ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif_Set_numberofcells ***
+      !!--------------------------------------------- 
    USE Agrif_Grids
    IMPLICIT NONE
@@ -27,7 +27,7 @@
 
 SUBROUTINE Agrif_Get_numberofcells(Agrif_Gr)
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif_Get_numberofcells ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif_Get_numberofcells ***
+      !!--------------------------------------------- 
    USE Agrif_Grids
    IMPLICIT NONE
@@ -42,7 +42,7 @@
 
 SUBROUTINE Agrif_Allocationcalls(Agrif_Gr)
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif_Allocationscalls ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif_Allocationscalls ***
+      !!--------------------------------------------- 
    USE Agrif_Grids 
 #include "include_use_Alloc_agrif.h"
@@ -56,7 +56,7 @@
 
 SUBROUTINE Agrif_probdim_modtype_def()
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif_probdim_modtype_def ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif_probdim_modtype_def ***
+      !!--------------------------------------------- 
    USE Agrif_Types
    IMPLICIT NONE
@@ -71,7 +71,7 @@
 
 SUBROUTINE Agrif_clustering_def()
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif_clustering_def ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif_clustering_def ***
+      !!--------------------------------------------- 
    IMPLICIT NONE
 
@@ -82,7 +82,7 @@
 #else
 SUBROUTINE Agrif2Model
-   !!---------------------------------------------
-   !!   *** ROUTINE Agrif2Model ***
-   !!--------------------------------------------- 
+      !!---------------------------------------------
+      !!   *** ROUTINE Agrif2Model ***
+      !!--------------------------------------------- 
    WRITE(*,*) 'Impossible to bet here'
 END SUBROUTINE Agrif2model
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_all_update.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_all_update.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_all_update.F90	(revision 10321)
@@ -30,5 +30,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice.F90	(revision 10321)
@@ -21,5 +21,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_interp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_interp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_interp.F90	(revision 10321)
@@ -31,7 +31,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/NST 3.6 , NEMO Consortium (2018)
+   !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_update.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_update.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_ice_update.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce.F90	(revision 10321)
@@ -70,5 +70,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_interp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_interp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_interp.F90	(revision 10321)
@@ -50,5 +50,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_sponge.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_sponge.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_sponge.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_update.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_update.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_oce_update.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_interp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_interp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_interp.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_sponge.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_sponge.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_sponge.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_update.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_update.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_top_update.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/NST 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_user.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_user.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/NST/agrif_user.F90	(revision 10321)
@@ -1,9 +1,9 @@
 #undef UPD_HIGH   /* MIX HIGH UPDATE */
 #if defined key_agrif
-!!----------------------------------------------------------------------
-!! NEMO/NST 4.0 , NEMO Consortium (2018)
-!! $Id$
-!! Software governed by the CeCILL licence (./LICENSE)
-!!----------------------------------------------------------------------
+   !!----------------------------------------------------------------------
+   !! NEMO/NST 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
+   !!----------------------------------------------------------------------
 SUBROUTINE agrif_user
 END SUBROUTINE agrif_user
@@ -13,14 +13,14 @@
 
 SUBROUTINE Agrif_InitWorkspace
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitWorkspace ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitWorkspace ***
+      !!----------------------------------------------------------------------
    USE par_oce
    USE dom_oce
    USE nemogcm
    USE mppini
-   !!
-   IMPLICIT NONE
-   !!----------------------------------------------------------------------
+      !!
+   IMPLICIT NONE
+      !!----------------------------------------------------------------------
    !
    IF( .NOT. Agrif_Root() ) THEN
@@ -37,9 +37,9 @@
 
 SUBROUTINE Agrif_InitValues
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitValues ***
-   !!
-   !! ** Purpose :: Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitValues ***
+      !!
+      !! ** Purpose :: Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE Agrif_Util
    USE oce 
@@ -50,5 +50,5 @@
    !!
    IMPLICIT NONE
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    CALL nemo_init       !* Initializations of each fine grid
@@ -69,9 +69,9 @@
 
 SUBROUTINE Agrif_InitValues_cont_dom
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitValues_cont ***
-   !!
-   !! ** Purpose ::   Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitValues_cont ***
+      !!
+      !! ** Purpose ::   Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE Agrif_Util
    USE oce 
@@ -84,5 +84,5 @@
    !
    IMPLICIT NONE
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    ! Declaration of the type of variable which have to be interpolated
@@ -94,9 +94,9 @@
 
 SUBROUTINE agrif_declare_var_dom
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE agrif_declare_var ***
-   !!
-   !! ** Purpose :: Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE agrif_declare_var ***
+      !!
+      !! ** Purpose :: Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE agrif_util
    USE par_oce       
@@ -106,8 +106,8 @@
    !
    INTEGER :: ind1, ind2, ind3
-   !!----------------------------------------------------------------------
-
-   ! 1. Declaration of the type of variable which have to be interpolated
-   !---------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+
+      ! 1. Declaration of the type of variable which have to be interpolated
+      !---------------------------------------------------------------------
    ind1 =     nbghostcells
    ind2 = 1 + nbghostcells
@@ -116,16 +116,16 @@
    CALL agrif_declare_variable((/2,1/),(/ind3,ind2/),(/'x','y'/),(/1,1/),(/nlci,nlcj/),e2v_id)
 
-   ! 2. Type of interpolation
-   !-------------------------
+      ! 2. Type of interpolation
+      !-------------------------
    CALL Agrif_Set_bcinterp( e1u_id, interp1=Agrif_linear, interp2=AGRIF_ppm    )
    CALL Agrif_Set_bcinterp( e2v_id, interp1=AGRIF_ppm   , interp2=Agrif_linear )
 
-   ! 3. Location of interpolation
-   !-----------------------------
+      ! 3. Location of interpolation
+      !-----------------------------
    CALL Agrif_Set_bc(e1u_id,(/0,ind1-1/))
    CALL Agrif_Set_bc(e2v_id,(/0,ind1-1/))
 
-   ! 4. Update type
-   !--------------- 
+      ! 4. Update type
+      !--------------- 
 # if defined UPD_HIGH
    CALL Agrif_Set_Updatetype(e1u_id,update1 = Agrif_Update_Average, update2=Agrif_Update_Full_Weighting)
@@ -140,9 +140,9 @@
 
 SUBROUTINE Agrif_InitValues_cont
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitValues_cont ***
-   !!
-   !! ** Purpose ::   Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitValues_cont ***
+      !!
+      !! ** Purpose ::   Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE agrif_oce_update
    USE agrif_oce_interp
@@ -161,5 +161,5 @@
    LOGICAL :: check_namelist
    CHARACTER(len=15) :: cl_check1, cl_check2, cl_check3, cl_check4 
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
 
    ! 1. Declaration of the type of variable which have to be interpolated
@@ -293,9 +293,9 @@
 
 SUBROUTINE agrif_declare_var
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE agrif_declarE_var ***
-   !!
-   !! ** Purpose :: Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE agrif_declarE_var ***
+      !!
+      !! ** Purpose :: Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE agrif_util
    USE agrif_oce
@@ -307,5 +307,5 @@
    !
    INTEGER :: ind1, ind2, ind3
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
 
    ! 1. Declaration of the type of variable which have to be interpolated
@@ -451,9 +451,9 @@
 #if defined key_si3
 SUBROUTINE Agrif_InitValues_cont_ice
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitValues_cont_ice ***
-   !!
-   !! ** Purpose :: Initialisation of variables to be interpolated for ice
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitValues_cont_ice ***
+      !!
+      !! ** Purpose :: Initialisation of variables to be interpolated for ice
+      !!----------------------------------------------------------------------
    USE Agrif_Util
    USE sbc_oce, ONLY : nn_fsbc  ! clem: necessary otherwise Agrif_Parent(nn_fsbc) = nn_fsbc
@@ -465,5 +465,5 @@
    !
    IMPLICIT NONE
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    ! Declaration of the type of variable which have to be interpolated (parent=>child)
@@ -495,9 +495,9 @@
 
 SUBROUTINE agrif_declare_var_ice
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE agrif_declare_var_ice ***
-   !!
-   !! ** Purpose :: Declaration of variables to be interpolated for ice
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE agrif_declare_var_ice ***
+      !!
+      !! ** Purpose :: Declaration of variables to be interpolated for ice
+      !!----------------------------------------------------------------------
    USE Agrif_Util
    USE ice
@@ -507,5 +507,5 @@
    !
    INTEGER :: ind1, ind2, ind3
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    ! 1. Declaration of the type of variable which have to be interpolated (parent=>child)
@@ -553,9 +553,9 @@
 # if defined key_top
 SUBROUTINE Agrif_InitValues_cont_top
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_InitValues_cont_top ***
-   !!
-   !! ** Purpose :: Declaration of variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_InitValues_cont_top ***
+      !!
+      !! ** Purpose :: Declaration of variables to be interpolated
+      !!----------------------------------------------------------------------
    USE Agrif_Util
    USE oce 
@@ -575,5 +575,5 @@
    CHARACTER(len=10) :: cl_check1, cl_check2, cl_check3
    LOGICAL :: check_namelist
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
 
 
@@ -634,9 +634,9 @@
 
 SUBROUTINE agrif_declare_var_top
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE agrif_declare_var_top ***
-   !!
-   !! ** Purpose :: Declaration of TOP variables to be interpolated
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE agrif_declare_var_top ***
+      !!
+      !! ** Purpose :: Declaration of TOP variables to be interpolated
+      !!----------------------------------------------------------------------
    USE agrif_util
    USE agrif_oce
@@ -647,5 +647,5 @@
    !
    INTEGER :: ind1, ind2, ind3
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
 
    ! 1. Declaration of the type of variable which have to be interpolated
@@ -684,10 +684,10 @@
 
 SUBROUTINE Agrif_detect( kg, ksizex )
-   !!----------------------------------------------------------------------
-   !!                      *** ROUTINE Agrif_detect ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                      *** ROUTINE Agrif_detect ***
+      !!----------------------------------------------------------------------
    INTEGER, DIMENSION(2) :: ksizex
    INTEGER, DIMENSION(ksizex(1),ksizex(2)) :: kg 
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    RETURN
@@ -697,7 +697,7 @@
 
 SUBROUTINE agrif_nemo_init
-   !!----------------------------------------------------------------------
-   !!                     *** ROUTINE agrif_init ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                     *** ROUTINE agrif_init ***
+      !!----------------------------------------------------------------------
    USE agrif_oce 
    USE agrif_ice
@@ -710,5 +710,5 @@
    INTEGER  ::   iminspon
    NAMELIST/namagrif/ rn_sponge_tra, rn_sponge_dyn, ln_spc_dyn, ln_chk_bathy
-   !!--------------------------------------------------------------------------------------
+      !!--------------------------------------------------------------------------------------
    !
    REWIND( numnam_ref )              ! Namelist namagrif in reference namelist : AGRIF zoom
@@ -747,7 +747,7 @@
 
 SUBROUTINE Agrif_InvLoc( indloc, nprocloc, i, indglob )
-   !!----------------------------------------------------------------------
-   !!                     *** ROUTINE Agrif_InvLoc ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                     *** ROUTINE Agrif_InvLoc ***
+      !!----------------------------------------------------------------------
    USE dom_oce
    !!
@@ -755,5 +755,5 @@
    !
    INTEGER :: indglob, indloc, nprocloc, i
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    SELECT CASE( i )
@@ -768,7 +768,7 @@
 
 SUBROUTINE Agrif_get_proc_info( imin, imax, jmin, jmax )
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_get_proc_info ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_get_proc_info ***
+      !!----------------------------------------------------------------------
    USE par_oce
    !!
@@ -777,5 +777,5 @@
    INTEGER, INTENT(out) :: imin, imax
    INTEGER, INTENT(out) :: jmin, jmax
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    imin = nimppt(Agrif_Procrank+1)  ! ?????
@@ -788,7 +788,7 @@
 
 SUBROUTINE Agrif_estimate_parallel_cost(imin, imax,jmin, jmax, nbprocs, grid_cost)
-   !!----------------------------------------------------------------------
-   !!                 *** ROUTINE Agrif_estimate_parallel_cost ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                 *** ROUTINE Agrif_estimate_parallel_cost ***
+      !!----------------------------------------------------------------------
    USE par_oce
    !!
@@ -799,5 +799,5 @@
    INTEGER,  INTENT(in)  :: nbprocs
    REAL(wp), INTENT(out) :: grid_cost
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
    !
    grid_cost = REAL(imax-imin+1,wp)*REAL(jmax-jmin+1,wp) / REAL(nbprocs,wp)
@@ -809,7 +809,7 @@
 #else
 SUBROUTINE Subcalledbyagrif
-   !!----------------------------------------------------------------------
-   !!                   *** ROUTINE Subcalledbyagrif ***
-   !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !!                   *** ROUTINE Subcalledbyagrif ***
+      !!----------------------------------------------------------------------
    WRITE(*,*) 'Impossible to be here'
 END SUBROUTINE Subcalledbyagrif
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/README.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/data_assimilation.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmbkg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmbkg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmbkg.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asminc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asminc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asminc.F90	(revision 10321)
@@ -98,5 +98,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmpar.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmpar.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ASM/asmpar.F90	(revision 10321)
@@ -25,5 +25,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE asmpar
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdy_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdy_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdy_oce.F90	(revision 10321)
@@ -142,5 +142,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydta.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydta.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydta.F90	(revision 10321)
@@ -60,5 +60,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn.F90	(revision 10321)
@@ -33,5 +33,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn2d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn2d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn2d.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn3d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn3d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdydyn3d.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyice.F90	(revision 10321)
@@ -42,5 +42,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyini.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdylib.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdylib.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdylib.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytides.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytides.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytides.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytra.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytra.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdytra.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyvol.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyvol.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/BDY/bdyvol.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/c1d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/c1d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/c1d.F90	(revision 10321)
@@ -31,7 +31,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/C1D 3.7 , NEMO Consortium (2018)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dtauvd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dtauvd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dtauvd.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyncor_c1d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyncor_c1d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyncor_c1d.F90	(revision 10321)
@@ -33,7 +33,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/C1D 3.7 , NEMO Consortium (2018)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyndmp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyndmp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/dyndmp.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/step_c1d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/step_c1d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/C1D/step_c1d.F90	(revision 10321)
@@ -28,7 +28,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/C1D 3.7 , NEMO Consortium (2018)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/README.rst	(revision 10321)
@@ -0,0 +1,149 @@
+**********************************
+On line biogeochemistry coarsening
+**********************************
+
+.. contents::
+   :local:
+
+Presentation
+============
+
+A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed.
+This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution,
+to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics.
+
+A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented.
+
+What is available and working for now in this version
+=====================================================
+
+[To be completed]
+
+Description of the successful validation tests
+==============================================
+
+[To be completed]
+
+What is not working yet with on line coarsening of biogeochemistry
+==================================================================
+
+[To be completed]
+
+''should include precise explanation on MPI decomposition problems too''
+
+How to set up and use on line biogeochemistry
+=============================================
+
+Extract the on line biogeochemistry branch
+------------------------------------------
+
+To get the appropriate source code with the on line coarsening of biogeochemistry feature:
+
+.. code-block:: console
+
+	$ svn co https://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2018/dev_r5003_MERCATOR6_CRS
+
+
+How to activate coarsening?
+---------------------------
+
+To activate the coarsening, ``key_crs`` should be added to list of CPP keys.
+This key will only activate the coarsening of dynamics.
+
+Some parameters are available in the namelist_cfg:
+
+.. code-block:: fortran
+
+	               !   passive tracer coarsened online simulations
+	!-----------------------------------------------------------------------
+	   nn_factx    = 3         !  Reduction factor of x-direction
+	   nn_facty    = 3         !  Reduction factor of y-direction
+	   nn_msh_crs  = 0         !  create (=1) a mesh file or not (=0)
+	   nn_crs_kz   = 3         ! 0, volume-weighted MEAN of KZ
+	                           ! 1, MAX of KZ
+	                           ! 2, MIN of KZ
+	                           ! 3, 10^(MEAN(LOG(KZ)) 
+	                           ! 4, MEDIANE of KZ 
+	   ln_crs_wn   = .false.   ! wn coarsened (T) or computed using horizontal divergence ( F )
+	                           !                           !
+	   ln_crs_top = .true.     !coarsening online for the bio
+	/
+
+- Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for
+  the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...).
+- ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask.
+- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient. 
+- ``ln_crs_wn``
+
+  - when ``key_vvl`` is activated, this logical has no effect;
+    the coarsened vertical velocities are computed using horizontal divergence.
+  - when ``key_vvl`` is not activated,
+
+    - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``) 
+    - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``)
+- ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space;
+  so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``.
+
+Choice of operator to coarsene KZ
+---------------------------------
+
+A sensiblity test has been done with an Age tracer to compare the different operators.
+The 3 and 4 options seems to provide the best results.
+
+Some results can be found [xxx here]
+
+Example of xml files to output coarsened variables with XIOS
+------------------------------------------------------------
+
+In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and
+some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.  
+To write variables on the coarsened grid, and in particular the passive tracers,
+a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and
+the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ].
+
+Passive tracers tracers initial conditions
+------------------------------------------
+
+When initial conditions are provided in NetCDF files, the field might be:
+
+- on the coarsened grid
+- or they can be on another grid and
+  interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_.
+  Example of namelist for PISCES :
+  
+	.. code-block:: fortran
+
+		!-----------------------------------------------------------------------
+		&namtrc_dta      !    Initialisation from data input file
+		!-----------------------------------------------------------------------
+		!
+		   sn_trcdta(1)  = 'DIC_REG1'        ,        -12        ,  'DIC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(2)  = 'ALK_REG1'        ,        -12        ,  'ALK'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(3)  = 'O2_REG1'         ,        -1         ,  'O2'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(5)  = 'PO4_REG1'        ,        -1         ,  'PO4'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(7)  = 'Si_REG1'         ,        -1         ,  'Si'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+	   	sn_trcdta(10) = 'DOC_REG1'        ,        -12        ,  'DOC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(14) = 'Fe_REG1'         ,        -12        ,  'Fe'      ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+		   sn_trcdta(23) = 'NO3_REG1'        ,        -1         ,  'NO3'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , ''
+	   	rn_trfac(1)   =   1.0e-06  !  multiplicative factor
+		   rn_trfac(2)   =   1.0e-06  !  -      -      -     -
+		   rn_trfac(3)   =  44.6e-06  !  -      -      -     -
+	   	rn_trfac(5)   = 122.0e-06  !  -      -      -     -
+		   rn_trfac(7)   =   1.0e-06  !  -      -      -     -
+		   rn_trfac(10)  =   1.0e-06  !  -      -      -     -
+	   	rn_trfac(14)  =   1.0e-06  !  -      -      -     -
+		   rn_trfac(23)  =   7.6e-06  !  -      -      -     -
+		
+	   	cn_dir        =  './'      !  root directory for the location of the data files
+
+PISCES forcing files
+--------------------
+
+They might be on the coarsened grid.
+
+Perspectives
+============
+
+For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and
+future releases.
+Those will be discussed in Autumn 2018
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crs.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crs.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crs.F90	(revision 10321)
@@ -156,5 +156,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdom.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdom.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdom.F90	(revision 10321)
@@ -55,5 +55,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdomwri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdomwri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsdomwri.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsfld.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsfld.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsfld.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crsini.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crslbclnk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crslbclnk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/CRS/crslbclnk.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dia25h.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dia25h.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dia25h.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaar5.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaar5.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaar5.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diacfl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diacfl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diacfl.F90	(revision 10321)
@@ -39,7 +39,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diadct.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diadct.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diadct.F90	(revision 10321)
@@ -100,5 +100,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaharm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaharm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaharm.F90	(revision 10321)
@@ -57,5 +57,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahsb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahsb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahsb.F90	(revision 10321)
@@ -54,5 +54,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahth.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahth.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diahth.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dianam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dianam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/dianam.F90	(revision 10321)
@@ -25,5 +25,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaptr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaptr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diaptr.F90	(revision 10321)
@@ -67,5 +67,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diatmb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diatmb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diatmb.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diawri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diawri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIA/diawri.F90	(revision 10321)
@@ -81,5 +81,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -125,6 +125,6 @@
       ! Output of initial vertical scale factor
       CALL iom_put("e3t_0", e3t_0(:,:,:) )
-      CALL iom_put("e3u_0", e3t_0(:,:,:) )
-      CALL iom_put("e3v_0", e3t_0(:,:,:) )
+      CALL iom_put("e3u_0", e3u_0(:,:,:) )
+      CALL iom_put("e3v_0", e3v_0(:,:,:) )
       !
       CALL iom_put( "e3t" , e3t_n(:,:,:) )
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/cool_skin.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/cool_skin.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/cool_skin.F90	(revision 10321)
@@ -44,7 +44,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------   
    CONTAINS 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/step_diu.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/step_diu.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DIU/step_diu.F90	(revision 10321)
@@ -25,5 +25,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/closea.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/closea.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/closea.F90	(revision 10321)
@@ -66,5 +66,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/daymod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/daymod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/daymod.F90	(revision 10321)
@@ -46,5 +46,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/depth_e3.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/depth_e3.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/depth_e3.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dom_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dom_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dom_oce.F90	(revision 10321)
@@ -216,5 +216,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domain.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domain.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domain.F90	(revision 10321)
@@ -54,5 +54,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence        (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!-------------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domhgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domhgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domhgr.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dommsk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dommsk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dommsk.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domngb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domngb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domngb.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domvvl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domvvl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domvvl.F90	(revision 10321)
@@ -64,7 +64,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -234,9 +234,11 @@
                END DO
             END DO
-            IF( cn_cfg == "orca" .AND. nn_cfg == 3 ) THEN   ! ORCA2: Suppress ztilde in the Foxe Basin for ORCA2
-               ii0 = 103   ;   ii1 = 111       
-               ij0 = 128   ;   ij1 = 135   ;   
-               frq_rst_e3t( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ) =  0.0_wp
-               frq_rst_hdv( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ) =  1.e0_wp / rdt
+            IF( cn_cfg == "orca" .OR. cn_cfg == "ORCA" ) THEN
+               IF( nn_cfg == 3 ) THEN   ! ORCA2: Suppress ztilde in the Foxe Basin for ORCA2
+                  ii0 = 103   ;   ii1 = 111       
+                  ij0 = 128   ;   ij1 = 135   ;   
+                  frq_rst_e3t( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ) =  0.0_wp
+                  frq_rst_hdv( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ) =  1.e0_wp / rdt
+               ENDIF
             ENDIF
          ENDIF
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domwri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domwri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domwri.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domzgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domzgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/domzgr.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS       
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dtatsd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dtatsd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/dtatsd.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -150,25 +150,27 @@
       !
       !                                   !==   ORCA_R2 configuration and T & S damping   ==! 
-      IF( cn_cfg == "orca" .AND. nn_cfg == 2 .AND. ln_tsd_dmp ) THEN    ! some hand made alterations
-         !
-         ij0 = 101   ;   ij1 = 109                       ! Reduced T & S in the Alboran Sea
-         ii0 = 141   ;   ii1 = 155
-         DO jj = mj0(ij0), mj1(ij1)
-            DO ji = mi0(ii0), mi1(ii1)
-               sf_tsd(jp_tem)%fnow(ji,jj,13:13) = sf_tsd(jp_tem)%fnow(ji,jj,13:13) - 0.20_wp
-               sf_tsd(jp_tem)%fnow(ji,jj,14:15) = sf_tsd(jp_tem)%fnow(ji,jj,14:15) - 0.35_wp
-               sf_tsd(jp_tem)%fnow(ji,jj,16:25) = sf_tsd(jp_tem)%fnow(ji,jj,16:25) - 0.40_wp
-               !
-               sf_tsd(jp_sal)%fnow(ji,jj,13:13) = sf_tsd(jp_sal)%fnow(ji,jj,13:13) - 0.15_wp
-               sf_tsd(jp_sal)%fnow(ji,jj,14:15) = sf_tsd(jp_sal)%fnow(ji,jj,14:15) - 0.25_wp
-               sf_tsd(jp_sal)%fnow(ji,jj,16:17) = sf_tsd(jp_sal)%fnow(ji,jj,16:17) - 0.30_wp
-               sf_tsd(jp_sal)%fnow(ji,jj,18:25) = sf_tsd(jp_sal)%fnow(ji,jj,18:25) - 0.35_wp
+      IF( cn_cfg == "orca" .OR. cn_cfg == "ORCA" ) THEN
+         IF( nn_cfg == 2 .AND. ln_tsd_dmp ) THEN    ! some hand made alterations
+            !
+            ij0 = 101   ;   ij1 = 109                       ! Reduced T & S in the Alboran Sea
+            ii0 = 141   ;   ii1 = 155
+            DO jj = mj0(ij0), mj1(ij1)
+               DO ji = mi0(ii0), mi1(ii1)
+                  sf_tsd(jp_tem)%fnow(ji,jj,13:13) = sf_tsd(jp_tem)%fnow(ji,jj,13:13) - 0.20_wp
+                  sf_tsd(jp_tem)%fnow(ji,jj,14:15) = sf_tsd(jp_tem)%fnow(ji,jj,14:15) - 0.35_wp
+                  sf_tsd(jp_tem)%fnow(ji,jj,16:25) = sf_tsd(jp_tem)%fnow(ji,jj,16:25) - 0.40_wp
+                  !
+                  sf_tsd(jp_sal)%fnow(ji,jj,13:13) = sf_tsd(jp_sal)%fnow(ji,jj,13:13) - 0.15_wp
+                  sf_tsd(jp_sal)%fnow(ji,jj,14:15) = sf_tsd(jp_sal)%fnow(ji,jj,14:15) - 0.25_wp
+                  sf_tsd(jp_sal)%fnow(ji,jj,16:17) = sf_tsd(jp_sal)%fnow(ji,jj,16:17) - 0.30_wp
+                  sf_tsd(jp_sal)%fnow(ji,jj,18:25) = sf_tsd(jp_sal)%fnow(ji,jj,18:25) - 0.35_wp
+               END DO
             END DO
-         END DO
-         ij0 =  87   ;   ij1 =  96                          ! Reduced temperature in Red Sea
-         ii0 = 148   ;   ii1 = 160
-         sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ,  4:10 ) = 7.0_wp
-         sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) , 11:13 ) = 6.5_wp
-         sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) , 14:20 ) = 6.0_wp
+            ij0 =  87   ;   ij1 =  96                          ! Reduced temperature in Red Sea
+            ii0 = 148   ;   ii1 = 160
+            sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) ,  4:10 ) = 7.0_wp
+            sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) , 11:13 ) = 6.5_wp
+            sf_tsd(jp_tem)%fnow( mi0(ii0):mi1(ii1) , mj0(ij0):mj1(ij1) , 14:20 ) = 6.0_wp
+         ENDIF
       ENDIF
 !!gm end
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplhsb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplhsb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplhsb.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplini.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplrst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplrst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/iscplrst.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/istate.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/phycst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/phycst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DOM/phycst.F90	(revision 10321)
@@ -69,5 +69,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
    
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/divhor.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/divhor.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/divhor.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_cen2.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_cen2.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_cen2.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_ubs.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_ubs.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynadv_ubs.F90	(revision 10321)
@@ -37,5 +37,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynhpg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynhpg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynhpg.F90	(revision 10321)
@@ -77,5 +77,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynkeg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynkeg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynkeg.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf.F90	(revision 10321)
@@ -39,5 +39,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_iso.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_iso.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_iso.F90	(revision 10321)
@@ -45,5 +45,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_lap_blp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_lap_blp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynldf_lap_blp.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynnxt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynnxt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynnxt.F90	(revision 10321)
@@ -60,5 +60,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_exp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_exp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_exp.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_ts.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_ts.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynspg_ts.F90	(revision 10321)
@@ -90,5 +90,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -1114,10 +1114,4 @@
                             &   ) * ssvmask(ji,jj)
  
-!jth implicit bottom friction:
-                  IF ( ll_wd ) THEN ! revert to explicit for bit comparison tests in non wad runs
-                     ua_e(ji,jj) =  ua_e(ji,jj) /(1.0 -   rdtbt * zCdU_u(ji,jj) * hur_e(ji,jj))
-                     va_e(ji,jj) =  va_e(ji,jj) /(1.0 -   rdtbt * zCdU_v(ji,jj) * hvr_e(ji,jj))
-                  ENDIF
-
                END DO
             END DO
@@ -1144,4 +1138,13 @@
                             &               +    hv_n(ji,jj)  * zv_frc(ji,jj) ) &
                             &   ) * zhvra
+               END DO
+            END DO
+         ENDIF
+!jth implicit bottom friction:
+         IF ( ll_wd ) THEN ! revert to explicit for bit comparison tests in non wad runs
+            DO jj = 2, jpjm1
+               DO ji = fs_2, fs_jpim1   ! vector opt.
+                     ua_e(ji,jj) =  ua_e(ji,jj) /(1.0 -   rdtbt * zCdU_u(ji,jj) * hur_e(ji,jj))
+                     va_e(ji,jj) =  va_e(ji,jj) /(1.0 -   rdtbt * zCdU_v(ji,jj) * hvr_e(ji,jj))
                END DO
             END DO
@@ -1393,5 +1396,5 @@
       IF( TRIM(cdrw) == 'READ' ) THEN        ! Read/initialise 
          !                                   ! ---------------
-         IF( ln_rstart .AND. ln_bt_fw ) THEN    !* Read the restart file
+         IF( ln_rstart .AND. ln_bt_fw .AND. (neuler/=0) ) THEN    !* Read the restart file
             CALL iom_get( numror, jpdom_autoglo, 'ub2_b'  , ub2_b  (:,:), ldxios = lrxios )   
             CALL iom_get( numror, jpdom_autoglo, 'vb2_b'  , vb2_b  (:,:), ldxios = lrxios ) 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynvor.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynvor.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynvor.F90	(revision 10321)
@@ -92,5 +92,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzad.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzad.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzad.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzdf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzdf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/dynzdf.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/sshwzv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/sshwzv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/DYN/sshwzv.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo4rk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo4rk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo4rk.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flo_oce.F90	(revision 10321)
@@ -52,5 +52,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floats.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floats.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floats.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floblk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floblk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/floblk.F90	(revision 10321)
@@ -25,5 +25,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flodom.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flodom.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flodom.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/florst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/florst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/florst.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flowri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flowri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/FLO/flowri.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icb_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icb_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icb_oce.F90	(revision 10321)
@@ -148,5 +148,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbclv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbclv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbclv.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdia.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdia.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdia.F90	(revision 10321)
@@ -92,5 +92,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbdyn.F90	(revision 10321)
@@ -27,5 +27,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbini.F90	(revision 10321)
@@ -42,5 +42,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icblbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icblbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icblbc.F90	(revision 10321)
@@ -66,5 +66,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbrst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbrst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbrst.F90	(revision 10321)
@@ -46,5 +46,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -60,5 +60,5 @@
       INTEGER                      ::   idim, ivar, iatt
       INTEGER                      ::   jn, iunlim_dim, ibergs_in_file
-      INTEGER                      ::   ii,ij,iclass
+      INTEGER                      ::   ii, ij, iclass, ibase_err, imax_icb
       REAL(wp), DIMENSION(nkounts) ::   zdata      
       LOGICAL                      ::   ll_found_restart
@@ -77,4 +77,5 @@
       CALL iom_open( TRIM(cl_path)//cl_filename, ncid )
 
+      imax_icb = 0
       IF( iom_file(ncid)%iduld .GE. 0) THEN
 
@@ -96,4 +97,5 @@
                CALL iom_get( ncid, jpdom_unknown, 'number'       , zdata(:) , ktime=jn, kstart=(/1/), kcount=(/nkounts/) )
                localberg%number(:) = INT(zdata(:))
+               imax_icb = MAX( imax_icb, INT(zdata(1)) )
                CALL iom_get( ncid, 'mass_scaling' , localberg%mass_scaling, ktime=jn )
                CALL iom_get( ncid, 'lon'          , localpt%lon           , ktime=jn )
@@ -129,6 +131,9 @@
       CALL iom_get( ncid, jpdom_unknown, 'kount' , zdata(:) )
       num_bergs(:) = INT(zdata(:))
-
-      ! Sanity check
+      ! Close file
+      CALL iom_close( ncid )
+      !
+
+      ! Sanity checks
       jn = icb_utl_count()
       IF ( lwp .AND. nn_verbose_level >= 0 )   &
@@ -142,6 +147,32 @@
          &                                    ' bergs in the restart file and', jn,' bergs have been read'
       !
-      ! Finish up
-      CALL iom_close( ncid )
+      ! Confirm that all areas have a suitable base for assigning new iceberg
+      ! numbers. This will not be the case if restarting from a collated dataset
+      ! (even if using the same processor decomposition)
+      !
+      ibase_err = 0
+      IF( num_bergs(1) < 0 .AND. num_bergs(1) /= narea - jpnij ) THEN
+         ! If this area has never calved a new berg then the base should be
+         ! set to narea - jpnij. If it is negative but something else then
+         ! a new base will be needed to guarantee unique, future iceberg numbers
+         ibase_err = 1
+      ELSEIF( MOD( num_bergs(1) - narea , jpnij ) /= 0 ) THEN
+         ! If this area has a base which is not in the set {narea + N*jpnij}
+         ! for positive integers N then a new base will be needed to guarantee 
+         ! unique, future iceberg numbers
+         ibase_err = 1
+      ENDIF
+      IF( lk_mpp ) THEN
+         CALL mpp_sum(ibase_err)
+      ENDIF
+      IF( ibase_err > 0 ) THEN
+         ! 
+         ! A new base is needed. The only secure solution is to set bases such that
+         ! all future icebergs numbers will be greater than the current global maximum
+         IF( lk_mpp ) THEN
+            CALL mpp_max(imax_icb)
+         ENDIF
+         num_bergs(1) = imax_icb - jpnij + narea
+      ENDIF
       !
       IF( lwp .AND. nn_verbose_level >= 0 )  WRITE(numout,'(a)') 'icebergs, icb_rst_read: completed'
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbstp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbstp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbstp.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbthm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbthm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbthm.F90	(revision 10321)
@@ -33,5 +33,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbtrj.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbtrj.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbtrj.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbutl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbutl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ICB/icbutl.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/in_out_manager.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/in_out_manager.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/in_out_manager.F90	(revision 10321)
@@ -160,5 +160,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!=====================================================================
 END MODULE in_out_manager
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom.F90	(revision 10321)
@@ -43,4 +43,7 @@
    USE ioipsl, ONLY :  ju2ymds    ! for calendar
    USE crs             ! Grid coarsening
+#if defined key_top
+   USE trc, ONLY    :  profsed
+#endif
    USE lib_fortran 
    USE diurnal_bulk, ONLY : ln_diurnal_only, ln_diurnal
@@ -87,5 +90,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -193,8 +196,8 @@
       ! vertical grid definition
       IF(.NOT.llrst_context) THEN
-          CALL iom_set_axis_attr( "deptht", paxis = gdept_1d )
-          CALL iom_set_axis_attr( "depthu", paxis = gdept_1d )
-          CALL iom_set_axis_attr( "depthv", paxis = gdept_1d )
-          CALL iom_set_axis_attr( "depthw", paxis = gdepw_1d )
+          CALL iom_set_axis_attr( "deptht",  paxis = gdept_1d )
+          CALL iom_set_axis_attr( "depthu",  paxis = gdept_1d )
+          CALL iom_set_axis_attr( "depthv",  paxis = gdept_1d )
+          CALL iom_set_axis_attr( "depthw",  paxis = gdepw_1d )
 
           ! Add vertical grid bounds
@@ -219,4 +222,7 @@
           CALL iom_set_axis_attr( "nstrait", (/ (REAL(ji,wp), ji=1,4) /) )
 # endif
+#if defined key_top
+          CALL iom_set_axis_attr( "profsed", paxis = profsed )
+#endif
           CALL iom_set_axis_attr( "icbcla", class_num )
           CALL iom_set_axis_attr( "iax_20C", (/ REAL(20,wp) /) )
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_def.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_def.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_def.F90	(revision 10321)
@@ -85,5 +85,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE iom_def
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_nf90.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_nf90.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/iom_nf90.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/prtctl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/prtctl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/prtctl.F90	(revision 10321)
@@ -37,5 +37,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/restart.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/restart.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/IOM/restart.F90	(revision 10321)
@@ -42,5 +42,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbclnk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbclnk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbclnk.F90	(revision 10321)
@@ -53,5 +53,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -90,5 +90,5 @@
    !
    INTERFACE lbc_bdy_lnk
-      MODULE PROCEDURE lbc_bdy_lnk_2d, lbc_bdy_lnk_3d
+      MODULE PROCEDURE lbc_bdy_lnk_2d, lbc_bdy_lnk_3d, lbc_bdy_lnk_4d
    END INTERFACE
    !
@@ -105,5 +105,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -173,5 +173,5 @@
 
    !!----------------------------------------------------------------------
-   !!                   ***  routine lbc_bdy_lnk_(2,3)d  ***
+   !!                   ***  routine lbc_bdy_lnk_(2,3,4)d  ***
    !!
    !!   wrapper rountine to 'lbc_lnk_3d'. This wrapper is used
@@ -179,4 +179,14 @@
    !!----------------------------------------------------------------------
    
+   SUBROUTINE lbc_bdy_lnk_4d( pt4d, cd_type, psgn, ib_bdy )
+      !!----------------------------------------------------------------------
+      REAL(wp), DIMENSION(:,:,:,:), INTENT(inout) ::   pt4d      ! 4D array on which the lbc is applied
+      CHARACTER(len=1)            , INTENT(in   ) ::   cd_type   ! nature of pt4d grid-points
+      REAL(wp)                    , INTENT(in   ) ::   psgn      ! sign used across north fold 
+      INTEGER                     , INTENT(in   ) ::   ib_bdy    ! BDY boundary set
+      !!----------------------------------------------------------------------
+      CALL lbc_lnk_4d( pt4d, cd_type, psgn)
+   END SUBROUTINE lbc_bdy_lnk_4d
+
    SUBROUTINE lbc_bdy_lnk_3d( pt3d, cd_type, psgn, ib_bdy )
       !!----------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbcnfd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbcnfd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lbcnfd.F90	(revision 10321)
@@ -58,5 +58,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lib_mpp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lib_mpp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/lib_mpp.F90	(revision 10321)
@@ -172,5 +172,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/mppini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/mppini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LBC/mppini.F90	(revision 10321)
@@ -39,5 +39,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfc1d_c2d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfc1d_c2d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfc1d_c2d.F90	(revision 10321)
@@ -33,5 +33,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfdyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfdyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfdyn.F90	(revision 10321)
@@ -77,5 +77,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfslp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfslp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldfslp.F90	(revision 10321)
@@ -77,5 +77,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldftra.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldftra.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/LDF/ldftra.F90	(revision 10321)
@@ -98,5 +98,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/README.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/data_assimilation.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/ddatetoymdhms.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/ddatetoymdhms.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/ddatetoymdhms.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/diaobs.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/diaobs.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/diaobs.F90	(revision 10321)
@@ -99,5 +99,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/find_obs_proc.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/find_obs_proc.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/find_obs_proc.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis_saa.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis_saa.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/grt_cir_dis_saa.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/linquad.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/linquad.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/linquad.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/maxdist.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/maxdist.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/maxdist.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/mpp_map.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/mpp_map.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/mpp_map.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_averg_h2d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_averg_h2d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_averg_h2d.F90	(revision 10321)
@@ -46,5 +46,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_const.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_const.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_const.F90	(revision 10321)
@@ -7,5 +7,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv.F90	(revision 10321)
@@ -37,5 +37,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv_functions.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv_functions.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_conv_functions.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_fbm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_fbm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_fbm.F90	(revision 10321)
@@ -130,5 +130,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_grid.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_grid.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_grid.F90	(revision 10321)
@@ -88,5 +88,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_h2d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_h2d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_h2d.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_sup.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_sup.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_sup.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_z1d.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_z1d.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_inter_z1d.F90	(revision 10321)
@@ -27,5 +27,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_level_search.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_level_search.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_level_search.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_mpp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_mpp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_mpp.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_oper.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_oper.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_oper.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_prep.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_prep.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_prep.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles.F90	(revision 10321)
@@ -8,5 +8,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles_def.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles_def.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_profiles_def.F90	(revision 10321)
@@ -192,5 +192,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_altbias.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_altbias.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_altbias.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_prof.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_prof.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_prof.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_surf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_surf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_read_surf.F90	(revision 10321)
@@ -33,5 +33,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_readmdt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_readmdt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_readmdt.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_rot_vel.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_rot_vel.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_rot_vel.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_sort.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_sort.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_sort.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_surf_def.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_surf_def.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_surf_def.F90	(revision 10321)
@@ -116,5 +116,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_types.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_types.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_types.F90	(revision 10321)
@@ -50,5 +50,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_utils.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_utils.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_utils.F90	(revision 10321)
@@ -37,5 +37,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_write.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_write.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obs_write.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_h2d.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_h2d.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_h2d.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_z1d.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_z1d.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/obsinter_z1d.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/str_c_to_for.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/str_c_to_for.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/OBS/str_c_to_for.h90	(revision 10321)
@@ -2,5 +2,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/README.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/coupling.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cpl_oasis3.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cpl_oasis3.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cpl_oasis3.F90	(revision 10321)
@@ -69,4 +69,7 @@
    INTEGER, PUBLIC, PARAMETER ::   nmaxcat=5    ! Maximum number of coupling fields
    INTEGER, PUBLIC, PARAMETER ::   nmaxcpl=5    ! Maximum number of coupling fields
+   LOGICAL, PARAMETER         ::   ltmp_wapatch = .TRUE.   ! patch to restore wraparound rows in cpl_send, cpl_rcv, cpl_define  
+   INTEGER                    ::   nldi_save, nlei_save
+   INTEGER                    ::   nldj_save, nlej_save
    
    TYPE, PUBLIC ::   FLD_CPL               !: Type for coupling field information
@@ -87,5 +90,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -145,4 +148,13 @@
       !!--------------------------------------------------------------------
 
+      ! patch to restore wraparound rows in cpl_send, cpl_rcv, cpl_define
+      IF ( ltmp_wapatch ) THEN
+         nldi_save = nldi   ;   nlei_save = nlei
+         nldj_save = nldj   ;   nlej_save = nlej
+         IF( nimpp           ==      1 ) nldi = 1
+         IF( nimpp + jpi - 1 == jpiglo ) nlei = jpi
+         IF( njmpp           ==      1 ) nldj = 1
+         IF( njmpp + jpj - 1 == jpjglo ) nlej = jpj
+      ENDIF 
       IF(lwp) WRITE(numout,*)
       IF(lwp) WRITE(numout,*) 'cpl_define : initialization in coupled ocean/atmosphere case'
@@ -296,4 +308,8 @@
       IF( nerror /= OASIS_Ok )   CALL oasis_abort ( ncomp_id, 'cpl_define', 'Failure in oasis_enddef')
       !
+      IF ( ltmp_wapatch ) THEN
+         nldi = nldi_save   ;   nlei = nlei_save
+         nldj = nldj_save   ;   nlej = nlej_save
+      ENDIF
    END SUBROUTINE cpl_define
    
@@ -313,4 +329,13 @@
       INTEGER                                   ::   jc,jm     ! local loop index
       !!--------------------------------------------------------------------
+      ! patch to restore wraparound rows in cpl_send, cpl_rcv, cpl_define
+      IF ( ltmp_wapatch ) THEN
+         nldi_save = nldi   ;   nlei_save = nlei
+         nldj_save = nldj   ;   nlej_save = nlej
+         IF( nimpp           ==      1 ) nldi = 1
+         IF( nimpp + jpi - 1 == jpiglo ) nlei = jpi
+         IF( njmpp           ==      1 ) nldj = 1
+         IF( njmpp + jpj - 1 == jpjglo ) nlej = jpj
+      ENDIF
       !
       ! snd data to OASIS3
@@ -341,4 +366,8 @@
          ENDDO
       ENDDO
+      IF ( ltmp_wapatch ) THEN
+         nldi = nldi_save   ;   nlei = nlei_save
+         nldj = nldj_save   ;   nlej = nlej_save
+      ENDIF
       !
     END SUBROUTINE cpl_snd
@@ -361,4 +390,9 @@
       LOGICAL                                   ::   llaction, llfisrt
       !!--------------------------------------------------------------------
+      ! patch to restore wraparound rows in cpl_send, cpl_rcv, cpl_define
+      IF ( ltmp_wapatch ) THEN
+         nldi_save = nldi   ;   nlei_save = nlei
+         nldj_save = nldj   ;   nlej_save = nlej
+      ENDIF
       !
       ! receive local data from OASIS3 on every process
@@ -367,4 +401,10 @@
       !
       DO jc = 1, srcv(kid)%nct
+         IF ( ltmp_wapatch ) THEN
+            IF( nimpp           ==      1 ) nldi = 1
+            IF( nimpp + jpi - 1 == jpiglo ) nlei = jpi
+            IF( njmpp           ==      1 ) nldj = 1
+            IF( njmpp + jpj - 1 == jpjglo ) nlej = jpj
+         ENDIF
          llfisrt = .TRUE.
 
@@ -408,4 +448,8 @@
          ENDDO
 
+         IF ( ltmp_wapatch ) THEN
+            nldi = nldi_save   ;   nlei = nlei_save
+            nldj = nldj_save   ;   nlej = nlej_save
+         ENDIF
          !--- Fill the overlap areas and extra hallows (mpp)
          !--- check periodicity conditions (all cases)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cyclone.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cyclone.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/cyclone.F90	(revision 10321)
@@ -39,7 +39,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/fldread.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/fldread.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/fldread.F90	(revision 10321)
@@ -125,5 +125,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/geo2ocean.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/geo2ocean.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/geo2ocean.F90	(revision 10321)
@@ -55,5 +55,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/ocealb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/ocealb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/ocealb.F90	(revision 10321)
@@ -22,5 +22,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_ice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_ice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_ice.F90	(revision 10321)
@@ -109,5 +109,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbc_oce.F90	(revision 10321)
@@ -154,5 +154,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcapr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcapr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcapr.F90	(revision 10321)
@@ -41,7 +41,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk.F90	(revision 10321)
@@ -136,5 +136,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -239,5 +239,5 @@
       !drag coefficient read from wave model definable only with mfs bulk formulae and core 
          ELSEIF (ln_cdgw .AND. .NOT. ln_NCAR )       THEN       
-             CALL ctl_stop( 'drag coefficient read from wave model definable only with mfs bulk formulae and core')
+             CALL ctl_stop( 'drag coefficient read from wave model definable only with NCAR and CORE bulk formulae')
          ELSEIF (ln_stcor .AND. .NOT. ln_sdw)                             THEN
              CALL ctl_stop( 'Stokes-Coriolis term calculated only if activated Stokes Drift ln_sdw=T')
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk_algo_ncar.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk_algo_ncar.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcblk_algo_ncar.F90	(revision 10321)
@@ -149,4 +149,6 @@
       Ch = 1.e-3*sqrt_Cd_n10*(18.*stab + 32.7*(1. - stab))
       stab = sqrt_Cd_n10   ! Temporaty array !!! stab == SQRT(Cd)
+ 
+      IF( ln_cdgw )   Cen = Ce  ; Chn = Ch
 
       !! Initializing values at z_u with z_t values:
@@ -186,5 +188,12 @@
          IF( ln_cdgw ) THEN      ! surface wave case
             stab = vkarmn / ( vkarmn / sqrt_Cd_n10 - ztmp2 )  ! (stab == SQRT(Cd))
-            Cd      = stab * stab
+            Cd   = stab * stab
+            ztmp0 = (LOG(zu/10.) - zpsi_h_u) / vkarmn / sqrt_Cd_n10
+            ztmp2 = stab / sqrt_Cd_n10   ! (stab == SQRT(Cd))
+            ztmp1 = 1. + Chn * ztmp0     
+            Ch    = Chn * ztmp2 / ztmp1  ! L&Y 2004 eq. (10b)
+            ztmp1 = 1. + Cen * ztmp0
+            Ce    = Cen * ztmp2 / ztmp1  ! L&Y 2004 eq. (10c)
+
          ELSE
             ! Update neutral wind speed at 10m and neutral Cd at 10m (L&Y 2004 eq. 9a)...
@@ -205,15 +214,15 @@
             Cd      = ztmp0 / ( ztmp1*ztmp1 )
             stab = SQRT( Cd ) ! Temporary array !!! (stab == SQRT(Cd))
-         ENDIF
-
-         ztmp0 = (LOG(zu/10.) - zpsi_h_u) / vkarmn / sqrt_Cd_n10
-         ztmp2 = stab / sqrt_Cd_n10   ! (stab == SQRT(Cd))
-         ztmp1 = 1. + Cx_n10*ztmp0    ! (Cx_n10 == Ch_n10)
-         Ch  = Cx_n10*ztmp2 / ztmp1   ! L&Y 2004 eq. (10b)
-
-         Cx_n10  = 1.e-3 * (34.6 * sqrt_Cd_n10)  ! L&Y 2004 eq. (6b)    ! Cx_n10 == Ce_n10
-         Cen(:,:) = Cx_n10
-         ztmp1 = 1. + Cx_n10*ztmp0
-         Ce  = Cx_n10*ztmp2 / ztmp1  ! L&Y 2004 eq. (10c)
+
+            ztmp0 = (LOG(zu/10.) - zpsi_h_u) / vkarmn / sqrt_Cd_n10
+            ztmp2 = stab / sqrt_Cd_n10   ! (stab == SQRT(Cd))
+            ztmp1 = 1. + Cx_n10*ztmp0    ! (Cx_n10 == Ch_n10)
+            Ch  = Cx_n10*ztmp2 / ztmp1   ! L&Y 2004 eq. (10b)
+
+            Cx_n10  = 1.e-3 * (34.6 * sqrt_Cd_n10)  ! L&Y 2004 eq. (6b)    ! Cx_n10 == Ce_n10
+            Cen(:,:) = Cx_n10
+            ztmp1 = 1. + Cx_n10*ztmp0
+            Ce  = Cx_n10*ztmp2 / ztmp1  ! L&Y 2004 eq. (10c)
+            ENDIF
          !
       END DO
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbccpl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbccpl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbccpl.F90	(revision 10321)
@@ -202,5 +202,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcdcy.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcdcy.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcdcy.F90	(revision 10321)
@@ -31,7 +31,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcflx.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcflx.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcflx.F90	(revision 10321)
@@ -40,7 +40,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcfwb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcfwb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcfwb.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_cice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_cice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_cice.F90	(revision 10321)
@@ -89,7 +89,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_if.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_if.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcice_if.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcisf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcisf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcisf.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcmod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcmod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcmod.F90	(revision 10321)
@@ -69,7 +69,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -157,7 +157,10 @@
          WRITE(numout,*) '               wave modified ocean stress component ln_tauw       = ', ln_tauw
          WRITE(numout,*) '               Stokes coriolis term                 ln_stcor      = ', ln_stcor
-         WRITE(numout,*) '               neutral drag coefficient (CORE, MFS) ln_cdgw       = ', ln_cdgw
-      ENDIF
-      !
+         WRITE(numout,*) '               neutral drag coefficient (CORE,NCAR) ln_cdgw       = ', ln_cdgw
+      ENDIF
+      !
+      IF( .NOT.ln_wave ) THEN
+         ln_sdw = .false. ; ln_cdgw = .false. ; ln_tauwoc = .false. ; ln_tauw = .false. ; ln_stcor = .false.
+      ENDIF 
       IF( ln_sdw ) THEN
          IF( .NOT.(nn_sdrift==jp_breivik_2014 .OR. nn_sdrift==jp_li_2017 .OR. nn_sdrift==jp_peakfr) ) &
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcrnf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcrnf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcrnf.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssm.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcssr.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbctide.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbctide.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbctide.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcwave.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcwave.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/sbcwave.F90	(revision 10321)
@@ -74,7 +74,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tide_mod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tide_mod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tide_mod.F90	(revision 10321)
@@ -34,7 +34,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tideini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tideini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/tideini.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/updtide.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/updtide.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/SBC/updtide.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopar.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopar.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopar.F90	(revision 10321)
@@ -115,5 +115,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopts.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopts.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/stopts.F90	(revision 10321)
@@ -30,5 +30,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/storng.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/storng.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/STO/storng.F90	(revision 10321)
@@ -60,5 +60,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/eosbn2.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/eosbn2.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/eosbn2.F90	(revision 10321)
@@ -182,5 +182,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_cen.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_cen.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_cen.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_fct.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_fct.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_fct.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_mus.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_mus.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_mus.F90	(revision 10321)
@@ -50,5 +50,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_qck.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_qck.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_qck.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_ubs.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_ubs.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traadv_ubs.F90	(revision 10321)
@@ -42,5 +42,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbc.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trabbl.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tradmp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tradmp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tradmp.F90	(revision 10321)
@@ -56,5 +56,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf.F90	(revision 10321)
@@ -43,5 +43,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_iso.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_iso.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_iso.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_lap_blp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_lap_blp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_lap_blp.F90	(revision 10321)
@@ -41,5 +41,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_triad.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_triad.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traldf_triad.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tramle.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tramle.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tramle.F90	(revision 10321)
@@ -52,5 +52,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (modipsl/doc/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -97,11 +97,13 @@
       !                                                ! compute from the 10m density to deal with the diurnal cycle
       inml_mle(:,:) = mbkt(:,:) + 1                    ! init. to number of ocean w-level (T-level + 1)
-      DO jk = jpkm1, nlb10, -1                         ! from the bottom to nlb10 (10m)
-         DO jj = 1, jpj
-            DO ji = 1, jpi                             ! index of the w-level at the ML based
-               IF( rhop(ji,jj,jk) > rhop(ji,jj,nla10) + rn_rho_c_mle )   inml_mle(ji,jj) = jk      ! Mixed layer
-            END DO
-         END DO
-      END DO
+      IF ( nla10 > 0 ) THEN                            ! avoid case where first level is thicker than 10m
+         DO jk = jpkm1, nlb10, -1                      ! from the bottom to nlb10 (10m)
+            DO jj = 1, jpj
+               DO ji = 1, jpi                          ! index of the w-level at the ML based
+                  IF( rhop(ji,jj,jk) > rhop(ji,jj,nla10) + rn_rho_c_mle )   inml_mle(ji,jj) = jk      ! Mixed layer
+               END DO
+            END DO
+         END DO
+      ENDIF
       ikmax = MIN( MAXVAL( inml_mle(:,:) ), jpkm1 )                  ! max level of the computation
       !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranpc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranpc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranpc.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranxt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranxt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/tranxt.F90	(revision 10321)
@@ -58,7 +58,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -291,5 +291,5 @@
          ztrd_atf(:,:,:,:) = 0.0_wp
       ENDIF
-      zfact = 1._wp / r2dt
+      zfact = 1._wp / p2dt
       zfact1 = atfp * p2dt
       zfact2 = zfact1 * r1_rau0
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traqsr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traqsr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/traqsr.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trasbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trasbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trasbc.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trazdf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trazdf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/trazdf.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/zpshde.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/zpshde.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRA/zpshde.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trd_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trd_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trd_oce.F90	(revision 10321)
@@ -78,5 +78,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trd_oce
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trddyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trddyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trddyn.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdglo.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdglo.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdglo.F90	(revision 10321)
@@ -55,5 +55,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdini.F90	(revision 10321)
@@ -30,5 +30,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdken.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdken.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdken.F90	(revision 10321)
@@ -44,5 +44,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl.F90	(revision 10321)
@@ -71,5 +71,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_oce.F90	(revision 10321)
@@ -84,5 +84,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_rst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_rst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdmxl_rst.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!---------------------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdpen.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdpen.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdpen.F90	(revision 10321)
@@ -40,5 +40,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtra.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtra.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtra.F90	(revision 10321)
@@ -45,5 +45,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtrc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtrc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdtrc.F90	(revision 10321)
@@ -19,5 +19,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trdtrc
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor.F90	(revision 10321)
@@ -60,5 +60,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/TRD/trdvor_oce.F90	(revision 10321)
@@ -30,5 +30,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trdvor_oce
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README-setup-configs
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README-setup-configs	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README-setup-configs	(revision 10321)
@@ -0,0 +1,53 @@
+==============================================================
+== HOW TO set up user’s configuration in NEMO version 4.0 : ==
+==============================================================
+This document describes how a configuration is set up in NEMO.
+
+In NEMO 4.0 two types of configurations can be build: global/regional and idealized.
+
+- create ./cfgs/your_config
+- case 1: regional or global 
+    => ln_read_cfg = .true. in ./cfgs/your_config/EXP00/namelist_cfg (i.e. read domain_cfg.nc)
+- case 2: idealized 
+    =>in ./cfgs/your_config/EXP00/namelist_cfg :
+      ln_read_cfg = .false. (need to define usrdef_hgr.F90 and usrdef_zgr.F90) 
+      ln_usr = .true.       (need to define usrdef_sbc.F90)    
+    => copy ./src/OCE/USR in ./cfgs/your_config/MY_SRC routines nedeed to set up domain, forcing fields and initial state
+    
+  Routines in NEMOGCM/NEMO/OCE/USR define analytically the domain, the initial state and the surface boundary conditions for the reference configuration GYRE.
+	  •	usrdef_hgr.F90 and usrdef_zgr.F90 : define horizontal and vertical grid
+	  •	usrdef_sbc.F90    : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
+	  •	usrdef_istate.F90 : defines initialization of the dynamics and tracers
+	  •	usrdef_fmask.F90  : used just in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits 
+	  •	usrdef_closea.F90 : used just in ORCA CONFIGURATIONS for specific treatments associated with closed seas
+	  •	usrdef_nam.F90    : set the domain characteristics of a user configuration
+
+  Other analytical examples are given in ./tests.
+
+===========================================
+== The domain_cfg.nc file must contain : ==
+===========================================
+   int ORCA  , ORCA_index            : configuration name, configuration resolution
+   int jpiglo, jpjglo , jpkglo       : global domain sizes 
+   int jperio                        : lateral global domain b.c. 
+   int ln_zco, ln_zps, ln_sco        : flags for z-coordinate, z-coordinate with partial steps and s-coordinate 
+   int ln_isfcav                     : flag  for ice shelf cavities 
+   double glamt, glamu, glamv, glamf : geographic position 
+   double gphit, gphiu, gphiv, gphif : geographic position
+   double iff, ff_f, ff_t            : Coriolis parameter (if not on the sphere)
+   double e1t, e1u, e1v, e1f         : horizontal scale factors
+   double e2t, e2u, e2v, e2f         : horizontal scale factors
+   double ie1e2u_v, e1e2u, e1e2v     : U and V surfaces (if grid size reduction in some straits)
+   double e3t_1d, e3w_1d             : reference vertical scale factors at T and W points
+   double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 : vertical scale factors 3D coordinate at T,U,V,F and W points
+   double e3uw_0,e3vw_0              : vertical scale factors 3D coordinate at UW and VW points
+   int bottom_level, top_level       : last wet T-points, 1st wet T-points (for ice shelf cavities)
+
+=======================================
+= HOW TO CREATE domain_cfg.nc file : ==
+=======================================
+Two options are possible :
+
+ - users can create with his own tool the domain_cfg.nc with all mandatory fields.  
+
+ - tool is available in ./tools/DOMAINcfg based on NEMO 3.6 version. See ./tools/DOMAINcfg/README.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/README.rst	(revision 10321)
@@ -0,0 +1,256 @@
+==============================
+Setting up a new configuration
+==============================
+
+.. include:: .global.rst
+
+.. contents::
+
+Starting from an existing configuration
+=======================================
+
+There are three options to build a new configuration from an existing one:
+
+---------------------------------------------
+Option 1: Duplicate an existing configuration
+---------------------------------------------
+
+The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
+(global, regional, 1D, using embeded zoom with AGRIF...)
+
+One can create a new configuration by duplicating one of the reference configurations
+(``ORCA2_LIM3_PISCES`` in the following example)
+
+.. code-block:: sh
+
+	makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES'
+
+------------------------------------
+Option 2: Duplicate with differences
+------------------------------------
+
+Create and compile a new configuration based on a reference configuration
+(``ORCA2_LIM3_PISCES`` in the following example) but with different pre-processor options.
+For this either add ``add_key`` or ``del_key`` keys as required; e.g.
+
+.. code-block:: sh
+
+	makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' del_key 'key_iomput' add_key 'key_xios'
+
+---------------------------------------------------------
+Option 3: Use the SIREN tools to subset an existing model
+---------------------------------------------------------
+
+Define a regional configuration which is a sub- or super-set of an existing configuration.
+
+This last option employs the SIREN software tools that are included in the standard distribution.
+The software is written in Fortran 95 and available in the ``./tools/SIREN`` directory.
+SIREN allows you to create your own regional configuration embedded in a wider one.
+
+SIREN is a set of programs to create all the input files you need to run a NEMO regional configuration.
+As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
+as well as examples of namelists are available `here`_.
+
+`SIREN documentation`_
+
+Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_.
+
+Creating a completely new configuration
+=======================================
+
+From NEMO version 4.0 there are two ways to build configurations from scratch.
+The appropriate method to use depends largely on the target configuration.
+Method 1 is for more complex/realistic global or regional configurations and
+method 2 is intended for simpler, idealised configurations whose
+domains and characteristics can be described in simple geometries and formulae.
+
+----------------------------------------------------
+Option 1: Create and use a domain configuration file
+----------------------------------------------------
+
+This method is used by each of the reference configurations,
+so that downloading their input files linked to their description can help.
+Although starting from scratch it is advisable to create the directory structure to house your new configuration by
+duplicating the closest reference configuration to your target application.
+For example, if your application requires both ocean ice and passive tracers,
+then use the ``ORCA2_LIM3_PISCES`` as template,
+and execute following command to build your ``MY_NEW_CONFIG`` configuration:
+
+.. code-block:: sh
+
+	makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_LIM3_PISCES'
+
+where ``MY_NEW_CONFIG`` can be substituted with a suitably descriptive name for your new configuration.  
+
+The purpose of this step is simply to create and populate the appropriate ``WORK``, ``MY_SRC`` and
+``EXP00`` subdirectories for your new configuration.
+Other choices for the base reference configuration might be
+
+- ``GYRE``  - If your target application is ocean-only
+- ``AMM12`` - If your target application is regional with open boundaries
+
+All the domain information for your new configuration will be contained within
+a netcdf file called ``domain_cfg.nc`` which you will need to create and
+place in the ``./cfgs/MY_NEW_CONFIG/EXP00`` sub-directory.
+Firstly though, ensure that your configuration is set to use such a file by checking that
+
+.. code-block:: fortran
+
+	ln_read_cfg = .true.
+
+in	``./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg``
+
+Create the domain_cfg.nc file which must contain the following fields
+
+.. code-block:: c++
+
+	int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
+	int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
+	int    jperio                            /* lateral global domain b.c.                                   */
+	int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
+	int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
+	double glamt, glamu, glamv, glamf        /* geographic position                                          */
+	double gphit, gphiu, gphiv, gphif        /* geographic position                                          */
+	double iff, ff_f, ff_t                   /* Coriolis parameter (if not on the sphere)                    */
+	double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
+	double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
+	double ie1e2u_v, e1e2u, e1e2v            /* U and V surfaces (if grid size reduction in some straits)    */
+	double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
+	double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+	double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
+	int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+
+There are two options for creating a domain_cfg.nc file:
+
+- Users can use tools of their own choice to build a ``domain_cfg.nc`` with all mandatory fields.
+- Users can adapt and apply the supplied tool available in ``./tools/DOMAINcfg``.
+  This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
+  the horizontal and vertical grids that were available internally to that version.
+  See ``./tools/DOMAINcfg/README`` for details.
+
+-----------------------------------------------------------------------------
+Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
+-----------------------------------------------------------------------------
+
+This method is intended for configuring easily simple/idealised configurations which
+are often used as demonstrators or for process evaluation and comparison.
+This method can be used whenever the domain geometry has a simple mathematical description and
+the ocean initial state and boundary forcing is described analytically. 
+As a start, consider the case of starting a completely new ocean-only test case based on
+the ``LOCK_EXCHANGE`` example.
+[Note: we probably need an even more basic example than this with only one namelist and
+minimal changes to the usrdef modules]
+
+Firstly, construct the directory structure, starting in the ``cfgs`` directory:
+
+.. code-block:: sh
+
+	./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE'
+
+where the ``-t`` option has been used to locate the new configuration in the ``tests`` subdirectory
+(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
+This command will have created (amongst others) the following files and directories::
+
+	./tests/MY_NEW_TEST:
+	BLD	  MY_SRC cpp_MY_NEW_TEST.fcm
+	EXP00   WORK
+	#
+	./tests/MY_NEW_TEST/EXP00:
+	context_nemo.xml       domain_def_nemo.xml
+	field_def_nemo-opa.xml file_def_nemo-opa.xml
+	iodef.xml
+	namelist_cfg
+	namelist_ref
+	#
+	./tests/MY_NEW_TEST/MY_SRC:
+	usrdef_hgr.F90    usrdef_nam.F90 usrdef_zgr.F90
+	usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
+
+The key to setting up an idealised configuration lies in adapting a small set of short Fortran 90 modules which
+should be dropped into the ``MY_SRC`` directory.
+Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
+the ``src/OCE/USR`` directory is::
+
+	./src/OCE/USR:
+	usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90
+	usrdef_fmask.F90  usrdef_nam.F90
+	usrdef_hgr.F90    usrdef_sbc.F90
+
+Before discussing these in more detail it is worth noting the various namelist controls that
+engage the different user-defined aspects.
+These controls are set using two new logical switches or are implied by the settings of existing ones.
+For example, the mandatory requirement for an idealised configuration is to provide routines which
+define the horizontal and vertical domains.
+Templates for these are provided in the ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules.
+The application of these modules is activated whenever:
+
+.. code-block:: fortran
+
+	ln_read_cfg = .false.
+
+in any configuration's ``namelist_cfg`` file.
+This setting also activates the reading of an optional ``nam_usrdef`` namelist which can be used to
+supply configuration specific settings.
+These need to be declared and read in the ``usrdef_nam.F90`` module.
+
+Another explicit control is available in the ``namsbc`` namelist which activates the use of analytical forcing.
+With
+
+.. code-block:: fortran
+
+	ln_usr = .true.
+
+Other usrdef modules are activated by less explicit means.
+For example, code in ``usrdef_istate.F90`` is used to define initial temperature and salinity fields if
+
+.. code-block:: fortran
+
+	ln_tsd_init   = .false.
+
+in the ``namtsd`` namelist.
+The remaining modules, namely::
+
+	usrdef_closea.F90 usrdef_fmask.F90
+
+are specific to ORCA configurations and set local variations of some specific fields for
+the various resolutions of the global models.
+They do not need to be considered here in the context of idealised cases but it is worth noting that all
+configuration specific code has now been isolated in the usrdef modules.
+In the case of these last two modules, they are activated only if an ORCA configuration is detected.
+Currently this requires a specific integer variable named ``ORCA`` to be set in a ``domain_cfg.nc`` file.
+[Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from
+the ``domain_cfg.nc`` ]
+
+So, in most cases, the set up of idealised model configurations can be completed by
+copying the template routines from ``./src/OCE/USR`` into
+your new ``./cfgs/MY_NEW_TEST/MY_SRC`` directory and editing the appropriate modules as needed.
+The default set are those used for the GYRE reference configuration.
+The contents of ``MY_SRC`` directories from other idealised configurations may provide more convenient templates if
+they share common characteristics with your target application.
+
+Whatever the starting point it should not require too many changes or additional lines of code to
+produce routines in ``./src/OCE/USR`` that define analytically the domain,
+the initial state and the surface boundary conditions for your new configuration.
+
+To summarize, the base set of modules is:
+
+- ``usrdef_hgr.F90``   : define horizontal grid
+- ``usrdef_zgr.F90``   : define vertical grid
+- ``usrdef_sbc.F90``   : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
+- ``usrdef_istate.F90``: defines initialization of the dynamics and tracers
+- ``usrdef_nam.F90``   : configuration-specific namelist processing to set any associated run-time parameters
+
+with two specialised ORCA modules
+(not related to idealised configurations but used to isolate configuration specific code that is used in
+ORCA2 reference configurations and established global configurations using the ORCA tripolar grid):
+
+- ``usrdef_fmask.F90`` : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits
+- ``usrdef_closea.F90``: only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas
+
+From version 4.0, the NEMO release includes a ``tests`` subdirectory containing available and
+up to date test cases build by the community.
+These will not be fully supported as is NEMO reference but should provide a source of raw material.
+
+.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar
+.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2
+.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_fmask.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_fmask.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_fmask.F90	(revision 10321)
@@ -31,5 +31,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_hgr.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_istate.F90	(revision 10321)
@@ -27,5 +27,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_nam.F90	(revision 10321)
@@ -33,5 +33,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_sbc.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/USR/usrdef_zgr.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdf_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdf_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdf_oce.F90	(revision 10321)
@@ -54,5 +54,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfddm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfddm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfddm.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfdrg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfdrg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfdrg.F90	(revision 10321)
@@ -77,5 +77,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfevd.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfevd.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfevd.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfgls.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfgls.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfgls.F90	(revision 10321)
@@ -108,5 +108,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfiwm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfiwm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfiwm.F90	(revision 10321)
@@ -53,5 +53,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfmxl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfmxl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfmxl.F90	(revision 10321)
@@ -38,5 +38,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfosm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfosm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfosm.F90	(revision 10321)
@@ -106,5 +106,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfphy.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfphy.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfphy.F90	(revision 10321)
@@ -57,5 +57,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfric.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfric.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfric.F90	(revision 10321)
@@ -54,5 +54,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfsh2.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfsh2.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfsh2.F90	(revision 10321)
@@ -24,5 +24,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfswm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfswm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdfswm.F90	(revision 10321)
@@ -28,7 +28,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdftke.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdftke.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/ZDF/zdftke.F90	(revision 10321)
@@ -93,5 +93,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_cray.f90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_cray.f90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_cray.f90	(revision 10321)
@@ -5,9 +5,9 @@
 !  
 !  wheneq
-!!----------------------------------------------------------------------
-!!  OPA 9.0 , NEMO Consortium (2018) 
-!! $Id$
-!! This software is governed by the CeCILL licence see modipsl/doc/NEMO_CeCILL.txt 
-!!----------------------------------------------------------------------
+   !!----------------------------------------------------------------------
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
+   !!----------------------------------------------------------------------
 SUBROUTINE lib_cray
       WRITE(*,*) 'lib_cray: You should not have seen this print! error?'
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_fortran.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_fortran.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/lib_fortran.F90	(revision 10321)
@@ -58,5 +58,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/module_example
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/module_example	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/module_example	(revision 10321)
@@ -53,5 +53,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id: module_example 9598 2018-05-15 22:47:16Z nicolasmartin $ 
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemo.f90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemo.f90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemo.f90	(revision 10321)
@@ -13,5 +13,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
    !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemogcm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemogcm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/nemogcm.F90	(revision 10321)
@@ -105,5 +105,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/oce.F90	(revision 10321)
@@ -70,5 +70,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_kind.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_kind.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_kind.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO 3.3 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 END MODULE par_kind
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/par_oce.F90	(revision 10321)
@@ -79,5 +79,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE par_oce
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step.F90	(revision 10321)
@@ -48,5 +48,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/step_oce.F90	(revision 10321)
@@ -112,5 +112,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE step_oce
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/stpctl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/stpctl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/stpctl.F90	(revision 10321)
@@ -36,5 +36,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/timing.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/timing.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/timing.F90	(revision 10321)
@@ -79,5 +79,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/trc_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/trc_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/trc_oce.F90	(revision 10321)
@@ -46,5 +46,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/vectopt_loop_substitute.h90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/vectopt_loop_substitute.h90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OCE/vectopt_loop_substitute.h90	(revision 10321)
@@ -8,5 +8,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 #if defined key_vectopt_loop
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/dtadyn.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/dtadyn.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/dtadyn.F90	(revision 10321)
@@ -46,7 +46,9 @@
    PRIVATE
 
-   PUBLIC   dta_dyn_init   ! called by opa.F90
-   PUBLIC   dta_dyn        ! called by step.F90
-   PUBLIC   dta_dyn_swp   ! called by step.F90
+   PUBLIC   dta_dyn_init       ! called by opa.F90
+   PUBLIC   dta_dyn            ! called by step.F90
+   PUBLIC   dta_dyn_sed_init   ! called by opa.F90
+   PUBLIC   dta_dyn_sed        ! called by step.F90
+   PUBLIC   dta_dyn_swp        ! called by step.F90
 
    CHARACTER(len=100) ::   cn_dir          !: Root directory for location of ssr files
@@ -88,5 +90,5 @@
    !! NEMO/OFF 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -164,4 +166,5 @@
       hmld(:,:)       = sf_dyn(jf_mld)%fnow(:,:,1) * tmask(:,:,1)    ! mixed layer depht
       avt(:,:,:)      = sf_dyn(jf_avt)%fnow(:,:,:) * tmask(:,:,:)    ! vertical diffusive coefficient 
+      avs(:,:,:)      = avt(:,:,:)
       !
       IF( ln_trabbl .AND. .NOT.lk_c1d ) THEN       ! diffusive Bottom boundary layer param 
@@ -182,10 +185,4 @@
          CALL prt_ctl(tab3d_1=uslp             , clinfo1=' slp  - u : ', tab3d_2=vslp, clinfo2=' v : ', kdim=jpk)
          CALL prt_ctl(tab3d_1=wslpi            , clinfo1=' slp  - wi: ', tab3d_2=wslpj, clinfo2=' wj: ', kdim=jpk)
-!         CALL prt_ctl(tab2d_1=fr_i             , clinfo1=' fr_i    - : ', mask1=tmask )
-!         CALL prt_ctl(tab2d_1=hmld             , clinfo1=' hmld    - : ', mask1=tmask )
-!         CALL prt_ctl(tab2d_1=fmmflx           , clinfo1=' fmmflx  - : ', mask1=tmask )
-!         CALL prt_ctl(tab2d_1=emp              , clinfo1=' emp     - : ', mask1=tmask )
-!         CALL prt_ctl(tab2d_1=wndm             , clinfo1=' wspd    - : ', mask1=tmask )
-!         CALL prt_ctl(tab2d_1=qsr              , clinfo1=' qsr     - : ', mask1=tmask )
       ENDIF
       !
@@ -418,4 +415,117 @@
    END SUBROUTINE dta_dyn_init
 
+   SUBROUTINE dta_dyn_sed( kt )
+      !!----------------------------------------------------------------------
+      !!                  ***  ROUTINE dta_dyn  ***
+      !!
+      !! ** Purpose :  Prepares dynamics and physics fields from a NEMO run
+      !!               for an off-line simulation of passive tracers
+      !!
+      !! ** Method : calculates the position of data
+      !!             - computes slopes if needed
+      !!             - interpolates data if needed
+      !!----------------------------------------------------------------------
+      INTEGER, INTENT(in) ::   kt   ! ocean time-step index
+      !
+      !!----------------------------------------------------------------------
+      !
+      IF( ln_timing )   CALL timing_start( 'dta_dyn_sed')
+      !
+      nsecdyn = nsec_year + nsec1jan000   ! number of seconds between Jan. 1st 00h of nit000 year and the middle of time step
+      !
+      IF( kt == nit000 ) THEN    ;    nprevrec = 0
+      ELSE                       ;    nprevrec = sf_dyn(jf_tem)%nrec_a(2)
+      ENDIF
+      CALL fld_read( kt, 1, sf_dyn )      !=  read data at kt time step   ==!
+      !
+      tsn(:,:,:,jp_tem) = sf_dyn(jf_tem)%fnow(:,:,:)  * tmask(:,:,:)    ! temperature
+      tsn(:,:,:,jp_sal) = sf_dyn(jf_sal)%fnow(:,:,:)  * tmask(:,:,:)    ! salinity
+      !
+      CALL eos    ( tsn, rhd, rhop, gdept_0(:,:,:) ) ! In any case, we need rhop
+
+      IF(ln_ctl) THEN                  ! print control
+         CALL prt_ctl(tab3d_1=tsn(:,:,:,jp_tem), clinfo1=' tn      - : ', mask1=tmask,  kdim=jpk   )
+         CALL prt_ctl(tab3d_1=tsn(:,:,:,jp_sal), clinfo1=' sn      - : ', mask1=tmask,  kdim=jpk   )
+      ENDIF
+      !
+      IF( ln_timing )   CALL timing_stop( 'dta_dyn_sed')
+      !
+   END SUBROUTINE dta_dyn_sed
+
+
+   SUBROUTINE dta_dyn_sed_init
+      !!----------------------------------------------------------------------
+      !!                  ***  ROUTINE dta_dyn_init  ***
+      !!
+      !! ** Purpose :   Initialisation of the dynamical data
+      !! ** Method  : - read the data namdta_dyn namelist
+      !!----------------------------------------------------------------------
+      INTEGER  :: ierr, ierr0, ierr1, ierr2, ierr3   ! return error code
+      INTEGER  :: ifpr                               ! dummy loop indice
+      INTEGER  :: jfld                               ! dummy loop arguments
+      INTEGER  :: inum, idv, idimv                   ! local integer
+      INTEGER  :: ios                                ! Local integer output status for namelist read
+      !!
+      CHARACTER(len=100)            ::  cn_dir        !   Root directory for location of core files
+      TYPE(FLD_N), DIMENSION(2) ::  slf_d         ! array of namelist informations on the fields to read
+      TYPE(FLD_N) :: sn_tem , sn_sal   !   "                 "
+      !!
+      NAMELIST/namdta_dyn/cn_dir, ln_dynrnf, ln_dynrnf_depth,  fwbcorr, &
+         &                sn_tem, sn_sal
+      !!----------------------------------------------------------------------
+      !
+      REWIND( numnam_ref )              ! Namelist namdta_dyn in reference namelist : Offline: init. of dynamical data
+      READ  ( numnam_ref, namdta_dyn, IOSTAT = ios, ERR = 901)
+901   IF( ios /= 0 )   CALL ctl_nam ( ios , 'namdta_dyn in reference namelist', lwp )
+      REWIND( numnam_cfg )              ! Namelist namdta_dyn in configuration namelist : Offline: init. of dynamical data
+      READ  ( numnam_cfg, namdta_dyn, IOSTAT = ios, ERR = 902 )
+902   IF( ios >  0 )   CALL ctl_nam ( ios , 'namdta_dyn in configuration namelist', lwp )
+      IF(lwm) WRITE ( numond, namdta_dyn )
+      !                                         ! store namelist information in an array
+      !                                         ! Control print
+      IF(lwp) THEN
+         WRITE(numout,*)
+         WRITE(numout,*) 'dta_dyn : offline dynamics '
+         WRITE(numout,*) '~~~~~~~ '
+         WRITE(numout,*) '   Namelist namdta_dyn'
+         WRITE(numout,*) '      runoffs option enabled (T) or not (F)            ln_dynrnf        = ', ln_dynrnf
+         WRITE(numout,*) '      runoffs is spread in vertical                    ln_dynrnf_depth  = ', ln_dynrnf_depth
+         WRITE(numout,*) '      annual global mean of empmr for ssh correction   fwbcorr          = ', fwbcorr
+         WRITE(numout,*)
+      ENDIF
+      !
+      jf_tem  = 1     ;   jf_sal  = 2    ;   jfld   = jf_sal
+      !
+      slf_d(jf_tem)  = sn_tem    ;   slf_d(jf_sal)  = sn_sal
+      !
+      ALLOCATE( sf_dyn(jfld), STAT=ierr )         ! set sf structure
+      IF( ierr > 0 )  THEN
+         CALL ctl_stop( 'dta_dyn: unable to allocate sf structure' )   ;   RETURN
+      ENDIF
+      !                                         ! fill sf with slf_i and control print
+      CALL fld_fill( sf_dyn, slf_d, cn_dir, 'dta_dyn_init', 'Data in file', 'namdta_dyn' )
+      !
+      ! Open file for each variable to get his number of dimension
+      DO ifpr = 1, jfld
+         CALL fld_clopn( sf_dyn(ifpr), nyear, nmonth, nday )
+         idv   = iom_varid( sf_dyn(ifpr)%num , slf_d(ifpr)%clvar )        ! id of the variable sdjf%clvar
+         idimv = iom_file ( sf_dyn(ifpr)%num )%ndims(idv)                 ! number of dimension for variable sdjf%clvar
+         IF( sf_dyn(ifpr)%num /= 0 )   CALL iom_close( sf_dyn(ifpr)%num ) ! close file if already open
+         ierr1=0
+         IF( idimv == 3 ) THEN    ! 2D variable
+                                      ALLOCATE( sf_dyn(ifpr)%fnow(jpi,jpj,1)    , STAT=ierr0 )
+            IF( slf_d(ifpr)%ln_tint ) ALLOCATE( sf_dyn(ifpr)%fdta(jpi,jpj,1,2)  , STAT=ierr1 )
+         ELSE                     ! 3D variable
+                                      ALLOCATE( sf_dyn(ifpr)%fnow(jpi,jpj,jpk)  , STAT=ierr0 )
+            IF( slf_d(ifpr)%ln_tint ) ALLOCATE( sf_dyn(ifpr)%fdta(jpi,jpj,jpk,2), STAT=ierr1 )
+         ENDIF
+         IF( ierr0 + ierr1 > 0 ) THEN
+            CALL ctl_stop( 'dta_dyn_init : unable to allocate sf_dyn array structure' )   ;   RETURN
+         ENDIF
+      END DO
+      !
+      CALL dta_dyn_sed( nit000 )
+      !
+   END SUBROUTINE dta_dyn_sed_init
 
    SUBROUTINE dta_dyn_swp( kt )
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/nemogcm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/nemogcm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/OFF/nemogcm.F90	(revision 10321)
@@ -70,5 +70,5 @@
    !! NEMO/OFF 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -110,7 +110,10 @@
          IF( istp /= nit000 )   CALL day        ( istp )         ! Calendar (day was already called at nit000 in day_init)
                                 CALL iom_setkt  ( istp - nit000 + 1, cxios_context )   ! say to iom that we are at time step kstp
+#if defined key_sed_off
+                                CALL dta_dyn_sed( istp )         ! Interpolation of the dynamical fields
+#else
                                 CALL dta_dyn    ( istp )         ! Interpolation of the dynamical fields
          IF( .NOT.ln_linssh )   CALL dta_dyn_swp( istp )         ! swap of sea  surface height and vertical scale factors
-
+#endif
                                 CALL trc_stp    ( istp )         ! time-stepping
                                 CALL stp_ctl    ( istp, indic )  ! Time loop: control and print
@@ -287,5 +290,9 @@
                            CALL trc_nam_run    ! Needed to get restart parameters for passive tracers
                            CALL trc_rst_cal( nit000, 'READ' )   ! calendar
+#if defined key_sed_off
+                           CALL dta_dyn_sed_init ! Initialization for the dynamics
+#else
                            CALL dta_dyn_init   ! Initialization for the dynamics
+#endif
 
                            CALL     trc_init   ! Passive tracers initialization
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/nemogcm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/nemogcm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/nemogcm.F90	(revision 10321)
@@ -49,5 +49,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/obs_fbm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/obs_fbm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/obs_fbm.F90	(revision 10321)
@@ -1,1 +1,1 @@
-link ../OCE/OBS/obs_fbm.F90
+MODULE obs_fbm
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_data.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_data.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_data.F90	(revision 10321)
@@ -22,5 +22,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_intp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_intp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_intp.F90	(revision 10321)
@@ -21,5 +21,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_read.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_read.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAO/sao_read.F90	(revision 10321)
@@ -24,5 +24,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/README.rst	(revision 10321)
@@ -0,0 +1,1 @@
+link ../../doc/rst/source/coupling.rst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/daymod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/daymod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/daymod.F90	(revision 10321)
@@ -44,7 +44,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/diawri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/diawri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/diawri.F90	(revision 10321)
@@ -60,7 +60,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/nemogcm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/nemogcm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/nemogcm.F90	(revision 10321)
@@ -53,7 +53,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/sbcssm.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/sbcssm.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/sbcssm.F90	(revision 10321)
@@ -56,7 +56,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OFF 3.3 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/step.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/step.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/step.F90	(revision 10321)
@@ -49,7 +49,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/stpctl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/stpctl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/SAS/stpctl.F90	(revision 10321)
@@ -33,7 +33,7 @@
    INTEGER  ::   idrun, idtime, idssh, idu, ids, istatus
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/SAS 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/par_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/par_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/par_age.F90	(revision 10321)
@@ -6,7 +6,7 @@
    !! History :   2.0  !  2007-12  (C. Ethe, G. Madec)  revised architecture
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
    IMPLICIT NONE
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcice_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcice_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcice_age.F90	(revision 10321)
@@ -13,7 +13,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcini_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcini_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcini_age.F90	(revision 10321)
@@ -19,7 +19,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcnam_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcnam_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcnam_age.F90	(revision 10321)
@@ -18,7 +18,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcsms_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcsms_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcsms_age.F90	(revision 10321)
@@ -31,7 +31,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcwri_age.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcwri_age.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/AGE/trcwri_age.F90	(revision 10321)
@@ -50,7 +50,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcwri_age
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/sms_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/sms_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/sms_c14.F90	(revision 10321)
@@ -53,7 +53,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
-   !! $                                                                    $ 
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcatm_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcatm_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcatm_c14.F90	(revision 10321)
@@ -22,7 +22,7 @@
    !
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcice_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcice_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcice_c14.F90	(revision 10321)
@@ -13,7 +13,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcini_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcini_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcini_c14.F90	(revision 10321)
@@ -25,7 +25,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcnam_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcnam_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcnam_c14.F90	(revision 10321)
@@ -19,7 +19,7 @@
    !!
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcsms_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcsms_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcsms_c14.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcwri_c14.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcwri_c14.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/C14/trcwri_c14.F90	(revision 10321)
@@ -131,7 +131,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcwri_c14
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/par_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/par_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/par_cfc.F90	(revision 10321)
@@ -6,7 +6,7 @@
    !! History :   2.0  !  2007-12  (C. Ethe, G. Madec)  revised architecture
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcice_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcice_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcice_cfc.F90	(revision 10321)
@@ -18,7 +18,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcini_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcini_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcini_cfc.F90	(revision 10321)
@@ -25,7 +25,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcnam_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcnam_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcnam_cfc.F90	(revision 10321)
@@ -20,7 +20,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcsms_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcsms_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcsms_cfc.F90	(revision 10321)
@@ -48,7 +48,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcwri_cfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcwri_cfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/CFC/trcwri_cfc.F90	(revision 10321)
@@ -50,7 +50,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcwri_cfc
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/par_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/par_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/par_my_trc.F90	(revision 10321)
@@ -6,7 +6,7 @@
    !! History :   2.0  !  2007-12  (C. Ethe, G. Madec)  revised architecture
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcice_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcice_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcice_my_trc.F90	(revision 10321)
@@ -19,5 +19,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcini_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcini_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcini_my_trc.F90	(revision 10321)
@@ -24,5 +24,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcnam_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcnam_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcnam_my_trc.F90	(revision 10321)
@@ -21,5 +21,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcsms_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcsms_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcsms_my_trc.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcwri_my_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcwri_my_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/MY_TRC/trcwri_my_trc.F90	(revision 10321)
@@ -21,5 +21,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zbio.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zbio.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zbio.F90	(revision 10321)
@@ -59,7 +59,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zexp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zexp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zexp.F90	(revision 10321)
@@ -40,7 +40,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zopt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zopt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zopt.F90	(revision 10321)
@@ -39,7 +39,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsed.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsed.F90	(revision 10321)
@@ -32,7 +32,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsms.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsms.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P2Z/p2zsms.F90	(revision 10321)
@@ -29,7 +29,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zagg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zagg.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zagg.F90	(revision 10321)
@@ -25,7 +25,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zbio.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zbio.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zbio.F90	(revision 10321)
@@ -15,10 +15,10 @@
    USE p4zsink         !  vertical flux of particulate matter due to sinking
    USE p4zopt          !  optical model
-   USE p4zice          !  Co-limitations of differents nutrients
+   USE p4zlim          !  Co-limitations of differents nutrients
    USE p4zprod         !  Growth rate of the 2 phyto groups
    USE p4zmort         !  Mortality terms for phytoplankton
    USE p4zmicro        !  Sources and sinks of microzooplankton
    USE p4zmeso         !  Sources and sinks of mesozooplankton
-   USE p5zice          !  Co-limitations of differents nutrients
+   USE p5zlim          !  Co-limitations of differents nutrients
    USE p5zprod         !  Growth rate of the 2 phyto groups
    USE p5zmort         !  Mortality terms for phytoplankton
@@ -39,7 +39,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zche.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zche.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zche.F90	(revision 10321)
@@ -37,15 +37,15 @@
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   tempis   ! In situ temperature
 
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akb3       !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akw3       !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akf3       !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   aks3       !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak1p3      !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak2p3      !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak3p3      !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   aksi3      !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   borat      !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   fluorid    !: ???
-   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   sulfat     !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akb3       !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akw3       !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   akf3       !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   aks3       !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak1p3      !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak2p3      !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   ak3p3      !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   aksi3      !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   borat      !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   fluorid    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   sulfat     !: ???
 
    !!* Variable for chemistry of the CO2 cycle
@@ -131,7 +131,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -233,6 +233,4 @@
         END DO
 
-
-
       ! CHEMICAL CONSTANTS - DEEP OCEAN
       ! -------------------------------
@@ -449,5 +447,4 @@
       !
    END SUBROUTINE p4z_che
-
 
    SUBROUTINE ahini_for_at(p_hini)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zfechem.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zfechem.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zfechem.F90	(revision 10321)
@@ -36,7 +36,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zflx.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zflx.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zflx.F90	(revision 10321)
@@ -53,7 +53,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: MO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zice.F90	(revision 10320)
+++ 	(revision )
@@ -1,313 +1,0 @@
-MODULE p4zice
-   !!======================================================================
-   !!                         ***  MODULE p4zice  ***
-   !! TOP :   PISCES 
-   !!======================================================================
-   !! History :   1.0  !  2004     (O. Aumont) Original code
-   !!             2.0  !  2007-12  (C. Ethe, G. Madec)  F90
-   !!             3.4  !  2011-04  (O. Aumont, C. Ethe) Limitation for iron modelled in quota 
-   !!----------------------------------------------------------------------
-   !!   p4z_lim        :   Compute the nutrients limitation terms 
-   !!   p4z_lim_init   :   Read the namelist 
-   !!----------------------------------------------------------------------
-   USE oce_trc         ! Shared ocean-passive tracers variables
-   USE trc             ! Tracers defined
-   USE sms_pisces      ! PISCES variables
-   USE iom             !  I/O manager
-
-   IMPLICIT NONE
-   PRIVATE
-
-   PUBLIC p4z_lim    
-   PUBLIC p4z_lim_init    
-   PUBLIC p4z_lim_alloc
-
-   !! * Shared module variables
-   REAL(wp), PUBLIC ::  concnno3    !:  NO3, PO4 half saturation   
-   REAL(wp), PUBLIC ::  concdno3    !:  Phosphate half saturation for diatoms  
-   REAL(wp), PUBLIC ::  concnnh4    !:  NH4 half saturation for phyto  
-   REAL(wp), PUBLIC ::  concdnh4    !:  NH4 half saturation for diatoms
-   REAL(wp), PUBLIC ::  concnfer    !:  Iron half saturation for nanophyto 
-   REAL(wp), PUBLIC ::  concdfer    !:  Iron half saturation for diatoms  
-   REAL(wp), PUBLIC ::  concbno3    !:  NO3 half saturation  for bacteria 
-   REAL(wp), PUBLIC ::  concbnh4    !:  NH4 half saturation for bacteria
-   REAL(wp), PUBLIC ::  xsizedia    !:  Minimum size criteria for diatoms
-   REAL(wp), PUBLIC ::  xsizephy    !:  Minimum size criteria for nanophyto
-   REAL(wp), PUBLIC ::  xsizern     !:  Size ratio for nanophytoplankton
-   REAL(wp), PUBLIC ::  xsizerd     !:  Size ratio for diatoms
-   REAL(wp), PUBLIC ::  xksi1       !:  half saturation constant for Si uptake 
-   REAL(wp), PUBLIC ::  xksi2       !:  half saturation constant for Si/C 
-   REAL(wp), PUBLIC ::  xkdoc       !:  2nd half-sat. of DOC remineralization  
-   REAL(wp), PUBLIC ::  concbfe     !:  Fe half saturation for bacteria 
-   REAL(wp), PUBLIC ::  oxymin      !:  half saturation constant for anoxia
-   REAL(wp), PUBLIC ::  qnfelim     !:  optimal Fe quota for nanophyto
-   REAL(wp), PUBLIC ::  qdfelim     !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  caco3r      !:  mean rainratio 
-
-   !!* Phytoplankton limitation terms
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanono3   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatno3   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanonh4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatnh4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanopo4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatpo4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimphy    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdia    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimnfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimsi     !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbac    !: ??
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbacl   !: ??
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   concdfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   concnfe    !: ???
-
-   ! Coefficient for iron limitation
-   REAL(wp) ::  xcoef1   = 0.0016  / 55.85  
-   REAL(wp) ::  xcoef2   = 1.21E-5 * 14. / 55.85 / 7.625 * 0.5 * 1.5
-   REAL(wp) ::  xcoef3   = 1.15E-4 * 14. / 55.85 / 7.625 * 0.5 
-
-   !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
-   !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
-   !!----------------------------------------------------------------------
-CONTAINS
-
-   SUBROUTINE p4z_lim( kt, knt )
-      !!---------------------------------------------------------------------
-      !!                     ***  ROUTINE p4z_lim  ***
-      !!
-      !! ** Purpose :   Compute the co-limitations by the various nutrients
-      !!              for the various phytoplankton species
-      !!
-      !! ** Method  : - ???
-      !!---------------------------------------------------------------------
-      INTEGER, INTENT(in)  :: kt, knt
-      !
-      INTEGER  ::   ji, jj, jk
-      REAL(wp) ::   zlim1, zlim2, zlim3, zlim4, zno3, zferlim
-      REAL(wp) ::   zconcd, zconcd2, zconcn, zconcn2
-      REAL(wp) ::   z1_trbdia, z1_trbphy, ztem1, ztem2, zetot1, zetot2
-      REAL(wp) ::   zdenom, zratio, zironmin
-      REAL(wp) ::   zconc1d, zconc1dnh4, zconc0n, zconc0nnh4   
-      !!---------------------------------------------------------------------
-      !
-      IF( ln_timing )   CALL timing_start('p4z_lim')
-      !
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               
-               ! Tuning of the iron concentration to a minimum level that is set to the detection limit
-               !-------------------------------------
-               zno3    = trb(ji,jj,jk,jpno3) / 40.e-6
-               zferlim = MAX( 3e-11 * zno3 * zno3, 5e-12 )
-               zferlim = MIN( zferlim, 7e-11 )
-               trb(ji,jj,jk,jpfer) = MAX( trb(ji,jj,jk,jpfer), zferlim )
-
-               ! Computation of a variable Ks for iron on diatoms taking into account
-               ! that increasing biomass is made of generally bigger cells
-               !------------------------------------------------
-               zconcd   = MAX( 0.e0 , trb(ji,jj,jk,jpdia) - xsizedia )
-               zconcd2  = trb(ji,jj,jk,jpdia) - zconcd
-               zconcn   = MAX( 0.e0 , trb(ji,jj,jk,jpphy) - xsizephy )
-               zconcn2  = trb(ji,jj,jk,jpphy) - zconcn
-               z1_trbphy   = 1. / ( trb(ji,jj,jk,jpphy) + rtrn )
-               z1_trbdia   = 1. / ( trb(ji,jj,jk,jpdia) + rtrn )
-
-               concdfe(ji,jj,jk) = MAX( concdfer, ( zconcd2 * concdfer + concdfer * xsizerd * zconcd ) * z1_trbdia )
-               zconc1d           = MAX( concdno3, ( zconcd2 * concdno3 + concdno3 * xsizerd * zconcd ) * z1_trbdia )
-               zconc1dnh4        = MAX( concdnh4, ( zconcd2 * concdnh4 + concdnh4 * xsizerd * zconcd ) * z1_trbdia )
-
-               concnfe(ji,jj,jk) = MAX( concnfer, ( zconcn2 * concnfer + concnfer * xsizern * zconcn ) * z1_trbphy )
-               zconc0n           = MAX( concnno3, ( zconcn2 * concnno3 + concnno3 * xsizern * zconcn ) * z1_trbphy )
-               zconc0nnh4        = MAX( concnnh4, ( zconcn2 * concnnh4 + concnnh4 * xsizern * zconcn ) * z1_trbphy )
-
-               ! Michaelis-Menten Limitation term for nutrients Small bacteria
-               ! -------------------------------------------------------------
-               zdenom = 1. /  ( concbno3 * concbnh4 + concbnh4 * trb(ji,jj,jk,jpno3) + concbno3 * trb(ji,jj,jk,jpnh4) )
-               xnanono3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * concbnh4 * zdenom
-               xnanonh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * concbno3 * zdenom
-               !
-               zlim1    = xnanono3(ji,jj,jk) + xnanonh4(ji,jj,jk)
-               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concbnh4 )
-               zlim3    = trb(ji,jj,jk,jpfer) / ( concbfe + trb(ji,jj,jk,jpfer) )
-               zlim4    = trb(ji,jj,jk,jpdoc) / ( xkdoc   + trb(ji,jj,jk,jpdoc) )
-               xlimbacl(ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
-               xlimbac (ji,jj,jk) = MIN( zlim1, zlim2, zlim3 ) * zlim4
-
-               ! Michaelis-Menten Limitation term for nutrients Small flagellates
-               ! -----------------------------------------------
-               zdenom = 1. /  ( zconc0n * zconc0nnh4 + zconc0nnh4 * trb(ji,jj,jk,jpno3) + zconc0n * trb(ji,jj,jk,jpnh4) )
-               xnanono3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * zconc0nnh4 * zdenom
-               xnanonh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * zconc0n    * zdenom
-               !
-               zlim1    = xnanono3(ji,jj,jk) + xnanonh4(ji,jj,jk)
-               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zconc0nnh4 )
-               zratio   = trb(ji,jj,jk,jpnfe) * z1_trbphy 
-               zironmin = xcoef1 * trb(ji,jj,jk,jpnch) * z1_trbphy + xcoef2 * zlim1 + xcoef3 * xnanono3(ji,jj,jk)
-               zlim3    = MAX( 0.,( zratio - zironmin ) / qnfelim )
-               xnanopo4(ji,jj,jk) = zlim2
-               xlimnfe (ji,jj,jk) = MIN( 1., zlim3 )
-               xlimphy (ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
-               !
-               !   Michaelis-Menten Limitation term for nutrients Diatoms
-               !   ----------------------------------------------
-               zdenom   = 1. / ( zconc1d * zconc1dnh4 + zconc1dnh4 * trb(ji,jj,jk,jpno3) + zconc1d * trb(ji,jj,jk,jpnh4) )
-               xdiatno3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * zconc1dnh4 * zdenom
-               xdiatnh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * zconc1d    * zdenom
-               !
-               zlim1    = xdiatno3(ji,jj,jk) + xdiatnh4(ji,jj,jk)
-               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zconc1dnh4  )
-               zlim3    = trb(ji,jj,jk,jpsil) / ( trb(ji,jj,jk,jpsil) + xksi(ji,jj) )
-               zratio   = trb(ji,jj,jk,jpdfe) * z1_trbdia
-               zironmin = xcoef1 * trb(ji,jj,jk,jpdch) * z1_trbdia + xcoef2 * zlim1 + xcoef3 * xdiatno3(ji,jj,jk)
-               zlim4    = MAX( 0., ( zratio - zironmin ) / qdfelim )
-               xdiatpo4(ji,jj,jk) = zlim2
-               xlimdfe (ji,jj,jk) = MIN( 1., zlim4 )
-               xlimdia (ji,jj,jk) = MIN( zlim1, zlim2, zlim3, zlim4 )
-               xlimsi  (ji,jj,jk) = MIN( zlim1, zlim2, zlim4 )
-           END DO
-         END DO
-      END DO
-
-      ! Compute the fraction of nanophytoplankton that is made of calcifiers
-      ! --------------------------------------------------------------------
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               zlim1 =  ( trb(ji,jj,jk,jpno3) * concnnh4 + trb(ji,jj,jk,jpnh4) * concnno3 )    &
-                  &   / ( concnno3 * concnnh4 + concnnh4 * trb(ji,jj,jk,jpno3) + concnno3 * trb(ji,jj,jk,jpnh4) ) 
-               zlim2  = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concnnh4 )
-               zlim3  = trb(ji,jj,jk,jpfer) / ( trb(ji,jj,jk,jpfer) +  5.E-11   )
-               ztem1  = MAX( 0., tsn(ji,jj,jk,jp_tem) )
-               ztem2  = tsn(ji,jj,jk,jp_tem) - 10.
-               zetot1 = MAX( 0., etot_ndcy(ji,jj,jk) - 1.) / ( 4. + etot_ndcy(ji,jj,jk) ) 
-               zetot2 = 30. / ( 30. + etot_ndcy(ji,jj,jk) ) 
-
-               xfracal(ji,jj,jk) = caco3r * MIN( zlim1, zlim2, zlim3 )                  &
-                  &                       * ztem1 / ( 0.1 + ztem1 )                     &
-                  &                       * MAX( 1., trb(ji,jj,jk,jpphy) * 1.e6 / 2. )  &
-                  &                       * zetot1 * zetot2               &
-                  &                       * ( 1. + EXP(-ztem2 * ztem2 / 25. ) )         &
-                  &                       * MIN( 1., 50. / ( hmld(ji,jj) + rtrn ) )
-               xfracal(ji,jj,jk) = MIN( 0.8 , xfracal(ji,jj,jk) )
-               xfracal(ji,jj,jk) = MAX( 0.02, xfracal(ji,jj,jk) )
-            END DO
-         END DO
-      END DO
-      !
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               ! denitrification factor computed from O2 levels
-               nitrfac(ji,jj,jk) = MAX(  0.e0, 0.4 * ( 6.e-6  - trb(ji,jj,jk,jpoxy) )    &
-                  &                                / ( oxymin + trb(ji,jj,jk,jpoxy) )  )
-               nitrfac(ji,jj,jk) = MIN( 1., nitrfac(ji,jj,jk) )
-               !
-               ! denitrification factor computed from NO3 levels
-               nitrfac2(ji,jj,jk) = MAX( 0.e0,       ( 1.E-6 - trb(ji,jj,jk,jpno3) )  &
-                  &                                / ( 1.E-6 + trb(ji,jj,jk,jpno3) ) )
-               nitrfac2(ji,jj,jk) = MIN( 1., nitrfac2(ji,jj,jk) )
-            END DO
-         END DO
-      END DO
-      !
-      IF( lk_iomput .AND. knt == nrdttrc ) THEN        ! save output diagnostics
-        IF( iom_use( "xfracal" ) )   CALL iom_put( "xfracal", xfracal(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
-        IF( iom_use( "LNnut"   ) )   CALL iom_put( "LNnut"  , xlimphy(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
-        IF( iom_use( "LDnut"   ) )   CALL iom_put( "LDnut"  , xlimdia(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
-        IF( iom_use( "LNFe"    ) )   CALL iom_put( "LNFe"   , xlimnfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "LDFe"    ) )   CALL iom_put( "LDFe"   , xlimdfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-      ENDIF
-      !
-      IF( ln_timing )   CALL timing_stop('p4z_lim')
-      !
-   END SUBROUTINE p4z_lim
-
-
-   SUBROUTINE p4z_lim_init
-      !!----------------------------------------------------------------------
-      !!                  ***  ROUTINE p4z_lim_init  ***
-      !!
-      !! ** Purpose :   Initialization of nutrient limitation parameters
-      !!
-      !! ** Method  :   Read the nampislim namelist and check the parameters
-      !!      called at the first timestep (nittrc000)
-      !!
-      !! ** input   :   Namelist nampislim
-      !!
-      !!----------------------------------------------------------------------
-      INTEGER ::   ios   ! Local integer
-      !
-      NAMELIST/namp4zice/ concnno3, concdno3, concnnh4, concdnh4, concnfer, concdfer, concbfe,   &
-         &                concbno3, concbnh4, xsizedia, xsizephy, xsizern, xsizerd,          & 
-         &                xksi1, xksi2, xkdoc, qnfelim, qdfelim, caco3r, oxymin
-      !!----------------------------------------------------------------------
-      !
-      IF(lwp) THEN
-         WRITE(numout,*)
-         WRITE(numout,*) 'p4z_lim_init : initialization of nutrient limitations'
-         WRITE(numout,*) '~~~~~~~~~~~~'
-      ENDIF
-      !
-      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
-      READ  ( numnatp_ref, namp4zice, IOSTAT = ios, ERR = 901)
-901   IF( ios /= 0 )   CALL ctl_nam ( ios , 'namp4zice in reference namelist', lwp )
-      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
-      READ  ( numnatp_cfg, namp4zice, IOSTAT = ios, ERR = 902 )
-902   IF( ios >  0 )   CALL ctl_nam ( ios , 'namp4zice in configuration namelist', lwp )
-      IF(lwm) WRITE( numonp, namp4zice )
-      !
-      IF(lwp) THEN                         ! control print
-         WRITE(numout,*) '   Namelist : namp4zice'
-         WRITE(numout,*) '      mean rainratio                           caco3r    = ', caco3r
-         WRITE(numout,*) '      NO3 half saturation of nanophyto         concnno3  = ', concnno3
-         WRITE(numout,*) '      NO3 half saturation of diatoms           concdno3  = ', concdno3
-         WRITE(numout,*) '      NH4 half saturation for phyto            concnnh4  = ', concnnh4
-         WRITE(numout,*) '      NH4 half saturation for diatoms          concdnh4  = ', concdnh4
-         WRITE(numout,*) '      half saturation constant for Si uptake   xksi1     = ', xksi1
-         WRITE(numout,*) '      half saturation constant for Si/C        xksi2     = ', xksi2
-         WRITE(numout,*) '      half-sat. of DOC remineralization        xkdoc     = ', xkdoc
-         WRITE(numout,*) '      Iron half saturation for nanophyto       concnfer  = ', concnfer
-         WRITE(numout,*) '      Iron half saturation for diatoms         concdfer  = ', concdfer
-         WRITE(numout,*) '      size ratio for nanophytoplankton         xsizern   = ', xsizern
-         WRITE(numout,*) '      size ratio for diatoms                   xsizerd   = ', xsizerd
-         WRITE(numout,*) '      NO3 half saturation of bacteria          concbno3  = ', concbno3
-         WRITE(numout,*) '      NH4 half saturation for bacteria         concbnh4  = ', concbnh4
-         WRITE(numout,*) '      Minimum size criteria for diatoms        xsizedia  = ', xsizedia
-         WRITE(numout,*) '      Minimum size criteria for nanophyto      xsizephy  = ', xsizephy
-         WRITE(numout,*) '      Fe half saturation for bacteria          concbfe   = ', concbfe
-         WRITE(numout,*) '      halk saturation constant for anoxia       oxymin   =' , oxymin
-         WRITE(numout,*) '      optimal Fe quota for nano.               qnfelim   = ', qnfelim
-         WRITE(numout,*) '      Optimal Fe quota for diatoms             qdfelim   = ', qdfelim
-      ENDIF
-      !
-      nitrfac (:,:,:) = 0._wp
-      !
-   END SUBROUTINE p4z_lim_init
-
-
-   INTEGER FUNCTION p4z_lim_alloc()
-      !!----------------------------------------------------------------------
-      !!                     ***  ROUTINE p5z_lim_alloc  ***
-      !!----------------------------------------------------------------------
-      USE lib_mpp , ONLY: ctl_warn
-      !!----------------------------------------------------------------------
-
-      !*  Biological arrays for phytoplankton growth
-      ALLOCATE( xnanono3(jpi,jpj,jpk), xdiatno3(jpi,jpj,jpk),       &
-         &      xnanonh4(jpi,jpj,jpk), xdiatnh4(jpi,jpj,jpk),       &
-         &      xnanopo4(jpi,jpj,jpk), xdiatpo4(jpi,jpj,jpk),       &
-         &      xlimphy (jpi,jpj,jpk), xlimdia (jpi,jpj,jpk),       &
-         &      xlimnfe (jpi,jpj,jpk), xlimdfe (jpi,jpj,jpk),       &
-         &      xlimbac (jpi,jpj,jpk), xlimbacl(jpi,jpj,jpk),       &
-         &      concnfe (jpi,jpj,jpk), concdfe (jpi,jpj,jpk),       &
-         &      xlimsi  (jpi,jpj,jpk), STAT=p4z_lim_alloc )
-      !
-      IF( p4z_lim_alloc /= 0 ) CALL ctl_warn('p4z_lim_alloc : failed to allocate arrays.')
-      !
-   END FUNCTION p4z_lim_alloc
-
-   !!======================================================================
-END MODULE p4zice
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zint.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zint.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zint.F90	(revision 10321)
@@ -20,7 +20,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zligand.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zligand.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zligand.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlim.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlim.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlim.F90	(revision 10321)
@@ -0,0 +1,313 @@
+MODULE p4zlim
+   !!======================================================================
+   !!                         ***  MODULE p4zlim  ***
+   !! TOP :   PISCES 
+   !!======================================================================
+   !! History :   1.0  !  2004     (O. Aumont) Original code
+   !!             2.0  !  2007-12  (C. Ethe, G. Madec)  F90
+   !!             3.4  !  2011-04  (O. Aumont, C. Ethe) Limitation for iron modelled in quota 
+   !!----------------------------------------------------------------------
+   !!   p4z_lim        :   Compute the nutrients limitation terms 
+   !!   p4z_lim_init   :   Read the namelist 
+   !!----------------------------------------------------------------------
+   USE oce_trc         ! Shared ocean-passive tracers variables
+   USE trc             ! Tracers defined
+   USE sms_pisces      ! PISCES variables
+   USE iom             !  I/O manager
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC p4z_lim    
+   PUBLIC p4z_lim_init    
+   PUBLIC p4z_lim_alloc
+
+   !! * Shared module variables
+   REAL(wp), PUBLIC ::  concnno3    !:  NO3, PO4 half saturation   
+   REAL(wp), PUBLIC ::  concdno3    !:  Phosphate half saturation for diatoms  
+   REAL(wp), PUBLIC ::  concnnh4    !:  NH4 half saturation for phyto  
+   REAL(wp), PUBLIC ::  concdnh4    !:  NH4 half saturation for diatoms
+   REAL(wp), PUBLIC ::  concnfer    !:  Iron half saturation for nanophyto 
+   REAL(wp), PUBLIC ::  concdfer    !:  Iron half saturation for diatoms  
+   REAL(wp), PUBLIC ::  concbno3    !:  NO3 half saturation  for bacteria 
+   REAL(wp), PUBLIC ::  concbnh4    !:  NH4 half saturation for bacteria
+   REAL(wp), PUBLIC ::  xsizedia    !:  Minimum size criteria for diatoms
+   REAL(wp), PUBLIC ::  xsizephy    !:  Minimum size criteria for nanophyto
+   REAL(wp), PUBLIC ::  xsizern     !:  Size ratio for nanophytoplankton
+   REAL(wp), PUBLIC ::  xsizerd     !:  Size ratio for diatoms
+   REAL(wp), PUBLIC ::  xksi1       !:  half saturation constant for Si uptake 
+   REAL(wp), PUBLIC ::  xksi2       !:  half saturation constant for Si/C 
+   REAL(wp), PUBLIC ::  xkdoc       !:  2nd half-sat. of DOC remineralization  
+   REAL(wp), PUBLIC ::  concbfe     !:  Fe half saturation for bacteria 
+   REAL(wp), PUBLIC ::  oxymin      !:  half saturation constant for anoxia
+   REAL(wp), PUBLIC ::  qnfelim     !:  optimal Fe quota for nanophyto
+   REAL(wp), PUBLIC ::  qdfelim     !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  caco3r      !:  mean rainratio 
+
+   !!* Phytoplankton limitation terms
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanono3   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatno3   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanonh4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatnh4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanopo4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatpo4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimphy    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdia    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimnfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimsi     !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbac    !: ??
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbacl   !: ??
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   concdfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   concnfe    !: ???
+
+   ! Coefficient for iron limitation
+   REAL(wp) ::  xcoef1   = 0.0016  / 55.85  
+   REAL(wp) ::  xcoef2   = 1.21E-5 * 14. / 55.85 / 7.625 * 0.5 * 1.5
+   REAL(wp) ::  xcoef3   = 1.15E-4 * 14. / 55.85 / 7.625 * 0.5 
+
+   !!----------------------------------------------------------------------
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
+   !!----------------------------------------------------------------------
+CONTAINS
+
+   SUBROUTINE p4z_lim( kt, knt )
+      !!---------------------------------------------------------------------
+      !!                     ***  ROUTINE p4z_lim  ***
+      !!
+      !! ** Purpose :   Compute the co-limitations by the various nutrients
+      !!              for the various phytoplankton species
+      !!
+      !! ** Method  : - ???
+      !!---------------------------------------------------------------------
+      INTEGER, INTENT(in)  :: kt, knt
+      !
+      INTEGER  ::   ji, jj, jk
+      REAL(wp) ::   zlim1, zlim2, zlim3, zlim4, zno3, zferlim
+      REAL(wp) ::   zconcd, zconcd2, zconcn, zconcn2
+      REAL(wp) ::   z1_trbdia, z1_trbphy, ztem1, ztem2, zetot1, zetot2
+      REAL(wp) ::   zdenom, zratio, zironmin
+      REAL(wp) ::   zconc1d, zconc1dnh4, zconc0n, zconc0nnh4   
+      !!---------------------------------------------------------------------
+      !
+      IF( ln_timing )   CALL timing_start('p4z_lim')
+      !
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               
+               ! Tuning of the iron concentration to a minimum level that is set to the detection limit
+               !-------------------------------------
+               zno3    = trb(ji,jj,jk,jpno3) / 40.e-6
+               zferlim = MAX( 3e-11 * zno3 * zno3, 5e-12 )
+               zferlim = MIN( zferlim, 7e-11 )
+               trb(ji,jj,jk,jpfer) = MAX( trb(ji,jj,jk,jpfer), zferlim )
+
+               ! Computation of a variable Ks for iron on diatoms taking into account
+               ! that increasing biomass is made of generally bigger cells
+               !------------------------------------------------
+               zconcd   = MAX( 0.e0 , trb(ji,jj,jk,jpdia) - xsizedia )
+               zconcd2  = trb(ji,jj,jk,jpdia) - zconcd
+               zconcn   = MAX( 0.e0 , trb(ji,jj,jk,jpphy) - xsizephy )
+               zconcn2  = trb(ji,jj,jk,jpphy) - zconcn
+               z1_trbphy   = 1. / ( trb(ji,jj,jk,jpphy) + rtrn )
+               z1_trbdia   = 1. / ( trb(ji,jj,jk,jpdia) + rtrn )
+
+               concdfe(ji,jj,jk) = MAX( concdfer, ( zconcd2 * concdfer + concdfer * xsizerd * zconcd ) * z1_trbdia )
+               zconc1d           = MAX( concdno3, ( zconcd2 * concdno3 + concdno3 * xsizerd * zconcd ) * z1_trbdia )
+               zconc1dnh4        = MAX( concdnh4, ( zconcd2 * concdnh4 + concdnh4 * xsizerd * zconcd ) * z1_trbdia )
+
+               concnfe(ji,jj,jk) = MAX( concnfer, ( zconcn2 * concnfer + concnfer * xsizern * zconcn ) * z1_trbphy )
+               zconc0n           = MAX( concnno3, ( zconcn2 * concnno3 + concnno3 * xsizern * zconcn ) * z1_trbphy )
+               zconc0nnh4        = MAX( concnnh4, ( zconcn2 * concnnh4 + concnnh4 * xsizern * zconcn ) * z1_trbphy )
+
+               ! Michaelis-Menten Limitation term for nutrients Small bacteria
+               ! -------------------------------------------------------------
+               zdenom = 1. /  ( concbno3 * concbnh4 + concbnh4 * trb(ji,jj,jk,jpno3) + concbno3 * trb(ji,jj,jk,jpnh4) )
+               xnanono3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * concbnh4 * zdenom
+               xnanonh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * concbno3 * zdenom
+               !
+               zlim1    = xnanono3(ji,jj,jk) + xnanonh4(ji,jj,jk)
+               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concbnh4 )
+               zlim3    = trb(ji,jj,jk,jpfer) / ( concbfe + trb(ji,jj,jk,jpfer) )
+               zlim4    = trb(ji,jj,jk,jpdoc) / ( xkdoc   + trb(ji,jj,jk,jpdoc) )
+               xlimbacl(ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
+               xlimbac (ji,jj,jk) = MIN( zlim1, zlim2, zlim3 ) * zlim4
+
+               ! Michaelis-Menten Limitation term for nutrients Small flagellates
+               ! -----------------------------------------------
+               zdenom = 1. /  ( zconc0n * zconc0nnh4 + zconc0nnh4 * trb(ji,jj,jk,jpno3) + zconc0n * trb(ji,jj,jk,jpnh4) )
+               xnanono3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * zconc0nnh4 * zdenom
+               xnanonh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * zconc0n    * zdenom
+               !
+               zlim1    = xnanono3(ji,jj,jk) + xnanonh4(ji,jj,jk)
+               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zconc0nnh4 )
+               zratio   = trb(ji,jj,jk,jpnfe) * z1_trbphy 
+               zironmin = xcoef1 * trb(ji,jj,jk,jpnch) * z1_trbphy + xcoef2 * zlim1 + xcoef3 * xnanono3(ji,jj,jk)
+               zlim3    = MAX( 0.,( zratio - zironmin ) / qnfelim )
+               xnanopo4(ji,jj,jk) = zlim2
+               xlimnfe (ji,jj,jk) = MIN( 1., zlim3 )
+               xlimphy (ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
+               !
+               !   Michaelis-Menten Limitation term for nutrients Diatoms
+               !   ----------------------------------------------
+               zdenom   = 1. / ( zconc1d * zconc1dnh4 + zconc1dnh4 * trb(ji,jj,jk,jpno3) + zconc1d * trb(ji,jj,jk,jpnh4) )
+               xdiatno3(ji,jj,jk) = trb(ji,jj,jk,jpno3) * zconc1dnh4 * zdenom
+               xdiatnh4(ji,jj,jk) = trb(ji,jj,jk,jpnh4) * zconc1d    * zdenom
+               !
+               zlim1    = xdiatno3(ji,jj,jk) + xdiatnh4(ji,jj,jk)
+               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zconc1dnh4  )
+               zlim3    = trb(ji,jj,jk,jpsil) / ( trb(ji,jj,jk,jpsil) + xksi(ji,jj) )
+               zratio   = trb(ji,jj,jk,jpdfe) * z1_trbdia
+               zironmin = xcoef1 * trb(ji,jj,jk,jpdch) * z1_trbdia + xcoef2 * zlim1 + xcoef3 * xdiatno3(ji,jj,jk)
+               zlim4    = MAX( 0., ( zratio - zironmin ) / qdfelim )
+               xdiatpo4(ji,jj,jk) = zlim2
+               xlimdfe (ji,jj,jk) = MIN( 1., zlim4 )
+               xlimdia (ji,jj,jk) = MIN( zlim1, zlim2, zlim3, zlim4 )
+               xlimsi  (ji,jj,jk) = MIN( zlim1, zlim2, zlim4 )
+           END DO
+         END DO
+      END DO
+
+      ! Compute the fraction of nanophytoplankton that is made of calcifiers
+      ! --------------------------------------------------------------------
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               zlim1 =  ( trb(ji,jj,jk,jpno3) * concnnh4 + trb(ji,jj,jk,jpnh4) * concnno3 )    &
+                  &   / ( concnno3 * concnnh4 + concnnh4 * trb(ji,jj,jk,jpno3) + concnno3 * trb(ji,jj,jk,jpnh4) ) 
+               zlim2  = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concnnh4 )
+               zlim3  = trb(ji,jj,jk,jpfer) / ( trb(ji,jj,jk,jpfer) +  5.E-11   )
+               ztem1  = MAX( 0., tsn(ji,jj,jk,jp_tem) )
+               ztem2  = tsn(ji,jj,jk,jp_tem) - 10.
+               zetot1 = MAX( 0., etot_ndcy(ji,jj,jk) - 1.) / ( 4. + etot_ndcy(ji,jj,jk) ) 
+               zetot2 = 30. / ( 30. + etot_ndcy(ji,jj,jk) ) 
+
+               xfracal(ji,jj,jk) = caco3r * MIN( zlim1, zlim2, zlim3 )                  &
+                  &                       * ztem1 / ( 0.1 + ztem1 )                     &
+                  &                       * MAX( 1., trb(ji,jj,jk,jpphy) * 1.e6 / 2. )  &
+                  &                       * zetot1 * zetot2               &
+                  &                       * ( 1. + EXP(-ztem2 * ztem2 / 25. ) )         &
+                  &                       * MIN( 1., 50. / ( hmld(ji,jj) + rtrn ) )
+               xfracal(ji,jj,jk) = MIN( 0.8 , xfracal(ji,jj,jk) )
+               xfracal(ji,jj,jk) = MAX( 0.02, xfracal(ji,jj,jk) )
+            END DO
+         END DO
+      END DO
+      !
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               ! denitrification factor computed from O2 levels
+               nitrfac(ji,jj,jk) = MAX(  0.e0, 0.4 * ( 6.e-6  - trb(ji,jj,jk,jpoxy) )    &
+                  &                                / ( oxymin + trb(ji,jj,jk,jpoxy) )  )
+               nitrfac(ji,jj,jk) = MIN( 1., nitrfac(ji,jj,jk) )
+               !
+               ! denitrification factor computed from NO3 levels
+               nitrfac2(ji,jj,jk) = MAX( 0.e0,       ( 1.E-6 - trb(ji,jj,jk,jpno3) )  &
+                  &                                / ( 1.E-6 + trb(ji,jj,jk,jpno3) ) )
+               nitrfac2(ji,jj,jk) = MIN( 1., nitrfac2(ji,jj,jk) )
+            END DO
+         END DO
+      END DO
+      !
+      IF( lk_iomput .AND. knt == nrdttrc ) THEN        ! save output diagnostics
+        IF( iom_use( "xfracal" ) )   CALL iom_put( "xfracal", xfracal(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
+        IF( iom_use( "LNnut"   ) )   CALL iom_put( "LNnut"  , xlimphy(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
+        IF( iom_use( "LDnut"   ) )   CALL iom_put( "LDnut"  , xlimdia(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
+        IF( iom_use( "LNFe"    ) )   CALL iom_put( "LNFe"   , xlimnfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "LDFe"    ) )   CALL iom_put( "LDFe"   , xlimdfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+      ENDIF
+      !
+      IF( ln_timing )   CALL timing_stop('p4z_lim')
+      !
+   END SUBROUTINE p4z_lim
+
+
+   SUBROUTINE p4z_lim_init
+      !!----------------------------------------------------------------------
+      !!                  ***  ROUTINE p4z_lim_init  ***
+      !!
+      !! ** Purpose :   Initialization of nutrient limitation parameters
+      !!
+      !! ** Method  :   Read the nampislim namelist and check the parameters
+      !!      called at the first timestep (nittrc000)
+      !!
+      !! ** input   :   Namelist nampislim
+      !!
+      !!----------------------------------------------------------------------
+      INTEGER ::   ios   ! Local integer
+      !
+      NAMELIST/namp4zlim/ concnno3, concdno3, concnnh4, concdnh4, concnfer, concdfer, concbfe,   &
+         &                concbno3, concbnh4, xsizedia, xsizephy, xsizern, xsizerd,          & 
+         &                xksi1, xksi2, xkdoc, qnfelim, qdfelim, caco3r, oxymin
+      !!----------------------------------------------------------------------
+      !
+      IF(lwp) THEN
+         WRITE(numout,*)
+         WRITE(numout,*) 'p4z_lim_init : initialization of nutrient limitations'
+         WRITE(numout,*) '~~~~~~~~~~~~'
+      ENDIF
+      !
+      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
+      READ  ( numnatp_ref, namp4zlim, IOSTAT = ios, ERR = 901)
+901   IF( ios /= 0 )   CALL ctl_nam ( ios , 'namp4zlim in reference namelist', lwp )
+      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
+      READ  ( numnatp_cfg, namp4zlim, IOSTAT = ios, ERR = 902 )
+902   IF( ios >  0 )   CALL ctl_nam ( ios , 'namp4zlim in configuration namelist', lwp )
+      IF(lwm) WRITE( numonp, namp4zlim )
+      !
+      IF(lwp) THEN                         ! control print
+         WRITE(numout,*) '   Namelist : namp4zlim'
+         WRITE(numout,*) '      mean rainratio                           caco3r    = ', caco3r
+         WRITE(numout,*) '      NO3 half saturation of nanophyto         concnno3  = ', concnno3
+         WRITE(numout,*) '      NO3 half saturation of diatoms           concdno3  = ', concdno3
+         WRITE(numout,*) '      NH4 half saturation for phyto            concnnh4  = ', concnnh4
+         WRITE(numout,*) '      NH4 half saturation for diatoms          concdnh4  = ', concdnh4
+         WRITE(numout,*) '      half saturation constant for Si uptake   xksi1     = ', xksi1
+         WRITE(numout,*) '      half saturation constant for Si/C        xksi2     = ', xksi2
+         WRITE(numout,*) '      half-sat. of DOC remineralization        xkdoc     = ', xkdoc
+         WRITE(numout,*) '      Iron half saturation for nanophyto       concnfer  = ', concnfer
+         WRITE(numout,*) '      Iron half saturation for diatoms         concdfer  = ', concdfer
+         WRITE(numout,*) '      size ratio for nanophytoplankton         xsizern   = ', xsizern
+         WRITE(numout,*) '      size ratio for diatoms                   xsizerd   = ', xsizerd
+         WRITE(numout,*) '      NO3 half saturation of bacteria          concbno3  = ', concbno3
+         WRITE(numout,*) '      NH4 half saturation for bacteria         concbnh4  = ', concbnh4
+         WRITE(numout,*) '      Minimum size criteria for diatoms        xsizedia  = ', xsizedia
+         WRITE(numout,*) '      Minimum size criteria for nanophyto      xsizephy  = ', xsizephy
+         WRITE(numout,*) '      Fe half saturation for bacteria          concbfe   = ', concbfe
+         WRITE(numout,*) '      halk saturation constant for anoxia       oxymin   =' , oxymin
+         WRITE(numout,*) '      optimal Fe quota for nano.               qnfelim   = ', qnfelim
+         WRITE(numout,*) '      Optimal Fe quota for diatoms             qdfelim   = ', qdfelim
+      ENDIF
+      !
+      nitrfac (:,:,:) = 0._wp
+      !
+   END SUBROUTINE p4z_lim_init
+
+
+   INTEGER FUNCTION p4z_lim_alloc()
+      !!----------------------------------------------------------------------
+      !!                     ***  ROUTINE p5z_lim_alloc  ***
+      !!----------------------------------------------------------------------
+      USE lib_mpp , ONLY: ctl_warn
+      !!----------------------------------------------------------------------
+
+      !*  Biological arrays for phytoplankton growth
+      ALLOCATE( xnanono3(jpi,jpj,jpk), xdiatno3(jpi,jpj,jpk),       &
+         &      xnanonh4(jpi,jpj,jpk), xdiatnh4(jpi,jpj,jpk),       &
+         &      xnanopo4(jpi,jpj,jpk), xdiatpo4(jpi,jpj,jpk),       &
+         &      xlimphy (jpi,jpj,jpk), xlimdia (jpi,jpj,jpk),       &
+         &      xlimnfe (jpi,jpj,jpk), xlimdfe (jpi,jpj,jpk),       &
+         &      xlimbac (jpi,jpj,jpk), xlimbacl(jpi,jpj,jpk),       &
+         &      concnfe (jpi,jpj,jpk), concdfe (jpi,jpj,jpk),       &
+         &      xlimsi  (jpi,jpj,jpk), STAT=p4z_lim_alloc )
+      !
+      IF( p4z_lim_alloc /= 0 ) CALL ctl_warn('p4z_lim_alloc : failed to allocate arrays.')
+      !
+   END FUNCTION p4z_lim_alloc
+
+   !!======================================================================
+END MODULE p4zlim
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlys.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlys.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zlys.F90	(revision 10321)
@@ -36,7 +36,7 @@
  
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmeso.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmeso.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmeso.F90	(revision 10321)
@@ -44,7 +44,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -108,5 +108,5 @@
                zdenom    = zfoodlim / ( xkgraz2 + zfoodlim )
                zdenom2   = zdenom / ( zfood + rtrn )
-               zgraze2   = grazrat2 * xstep * tgfunc2(ji,jj,jk) * trb(ji,jj,jk,jpmes) 
+               zgraze2   = grazrat2 * xstep * tgfunc2(ji,jj,jk) * trb(ji,jj,jk,jpmes) * (1. - nitrfac(ji,jj,jk)) 
 
                zgrazd    = zgraze2  * xprefc   * zcompadi  * zdenom2 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmicro.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmicro.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmicro.F90	(revision 10321)
@@ -14,5 +14,5 @@
    USE trc             ! passive tracers common variables 
    USE sms_pisces      ! PISCES Source Minus Sink variables
-   USE p4zice          ! Co-limitations
+   USE p4zlim          ! Co-limitations
    USE p4zprod         ! production
    USE iom             ! I/O manager
@@ -42,7 +42,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmort.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmort.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zmort.F90	(revision 10321)
@@ -14,5 +14,5 @@
    USE sms_pisces      ! PISCES Source Minus Sink variables
    USE p4zprod         ! Primary productivity 
-   USE p4zice          ! Phytoplankton limitation terms
+   USE p4zlim          ! Phytoplankton limitation terms
    USE prtctl_trc      ! print control for debugging
 
@@ -30,7 +30,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zopt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zopt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zopt.F90	(revision 10321)
@@ -43,7 +43,7 @@
    
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zpoc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zpoc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zpoc.F90	(revision 10321)
@@ -38,7 +38,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zprod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zprod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zprod.F90	(revision 10321)
@@ -15,5 +15,5 @@
    USE trc             ! passive tracers common variables 
    USE sms_pisces      ! PISCES Source Minus Sink variables
-   USE p4zice          ! Co-limitations of differents nutrients
+   USE p4zlim          ! Co-limitations of differents nutrients
    USE prtctl_trc      ! print control for debugging
    USE iom             ! I/O manager
@@ -49,7 +49,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zrem.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zrem.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zrem.F90	(revision 10321)
@@ -17,5 +17,5 @@
    USE p4zche          !  chemical model
    USE p4zprod         !  Growth rate of the 2 phyto groups
-   USE p4zice
+   USE p4zlim
    USE prtctl_trc      !  print control for debugging
    USE iom             !  I/O manager
@@ -43,7 +43,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -116,5 +116,6 @@
                   zammonic = zremik * nitrfac(ji,jj,jk) * trb(ji,jj,jk,jpdoc)
                   denitr(ji,jj,jk)  = zammonic * ( 1. - nitrfac2(ji,jj,jk) )
-                  zoxyrem           = zammonic *        nitrfac2(ji,jj,jk)
+                  denitr(ji,jj,jk)  = MIN( ( trb(ji,jj,jk,jpno3) - rtrn ) / rdenit, denitr(ji,jj,jk) )
+                  zoxyrem           = zammonic - denitr(ji,jj,jk)
                   !
                   zolimi (ji,jj,jk) = MAX( 0.e0, zolimi (ji,jj,jk) )
@@ -189,4 +190,5 @@
                &         / ( 1.+ emoy(ji,jj,jk) ) * ( 1. + fr_i(ji,jj) * emoy(ji,jj,jk) ) 
                zdenitnh4 = nitrif * xstep * trb(ji,jj,jk,jpnh4) * nitrfac(ji,jj,jk)
+               zdenitnh4 = MIN(  ( trb(ji,jj,jk,jpno3) - rtrn ) / rdenita, zdenitnh4 ) 
                ! Update of the tracers trends
                ! ----------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsbc.F90	(revision 10321)
@@ -37,4 +37,5 @@
    REAL(wp), PUBLIC ::   concfediaz   !: Fe half-saturation Cste for diazotrophs 
    REAL(wp)         ::   hratio       !: Fe:3He ratio assumed for vent iron supply
+   REAL(wp)         ::   distcoast    !: Distance off the coast for Iron from sediments
    REAL(wp), PUBLIC ::   fep_rats     !: Fep/Fer ratio from sed  sources
    REAL(wp), PUBLIC ::   fep_rath     !: Fep/Fer ratio from hydro sources
@@ -74,13 +75,14 @@
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   hydrofe          !: Hydrothermal vent supply of iron
 
-   REAL(wp), PUBLIC ::   rivalkinput, rivdicinput, nitdepinput, sumdepsi
-   REAL(wp), PUBLIC ::   rivdininput, rivdipinput, rivdsiinput
+   REAL(wp), PUBLIC :: sedsilfrac, sedcalfrac
+   REAL(wp), PUBLIC :: rivalkinput, rivdicinput
+   REAL(wp), PUBLIC :: rivdininput, rivdipinput, rivdsiinput
 
    !! * Substitutions
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -109,6 +111,6 @@
          IF( kt == nit000 .OR. ( kt /= nit000 .AND. ntimes_dust > 1 ) ) THEN
             CALL fld_read( kt, 1, sf_dust )
-            IF( nn_ice_tr == -1 .AND. .NOT.ln_ironice ) THEN   ;   dust(:,:) = sf_dust(1)%fnow(:,:,1)
-            ELSE                                               ;   dust(:,:) = sf_dust(1)%fnow(:,:,1) * ( 1.-fr_i(:,:) )
+            IF( nn_ice_tr == -1 .AND. .NOT.ln_ironice ) THEN   ;   dust(:,:) = MAX( rtrn, sf_dust(1)%fnow(:,:,1) )
+            ELSE                                               ;   dust(:,:) = MAX( rtrn, sf_dust(1)%fnow(:,:,1) * ( 1.-fr_i(:,:) ) )
             ENDIF
          ENDIF
@@ -173,9 +175,9 @@
              zcoef = rno3 * 14E6 * ryyss
              CALL fld_read( kt, 1, sf_ndepo )
-             nitdep(:,:) = sf_ndepo(1)%fnow(:,:,1) / zcoef / e3t_n(:,:,1) 
+             nitdep(:,:) = MAX( rtrn, sf_ndepo(1)%fnow(:,:,1) / zcoef / e3t_n(:,:,1) )
          ENDIF
          IF( .NOT.ln_linssh ) THEN
            zcoef = rno3 * 14E6 * ryyss
-           nitdep(:,:) = sf_ndepo(1)%fnow(:,:,1) / zcoef / e3t_n(:,:,1) 
+           nitdep(:,:) = MAX( rtrn, sf_ndepo(1)%fnow(:,:,1) / zcoef / e3t_n(:,:,1) )
          ENDIF
       ENDIF
@@ -205,9 +207,9 @@
       INTEGER  :: ik50                !  last level where depth less than 50 m
       INTEGER  :: isrow             ! index for ORCA1 starting row
-      REAL(wp) :: zexpide, zdenitide, zmaskt
+      REAL(wp) :: zexpide, zdenitide, zmaskt, zsurfc, zsurfp,ze3t, ze3t2, zcslp
       REAL(wp) :: ztimes_dust, ztimes_riv, ztimes_ndep 
       REAL(wp), DIMENSION(nbtimes) :: zsteps                 ! times records
       REAL(wp), DIMENSION(:), ALLOCATABLE :: rivinput
-      REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zdust, zndepo, zriver, zcmask
+      REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zriver, zcmask
       !
       CHARACTER(len=100) ::  cn_dir          ! Root directory for location of ssr files
@@ -220,5 +222,5 @@
         &                sn_riverdip, sn_riverdop, sn_riverdsi, sn_ndepo, sn_ironsed, sn_hydrofe, &
         &                ln_dust, ln_solub, ln_river, ln_ndepo, ln_ironsed, ln_ironice, ln_hydrofe,    &
-        &                sedfeinput, dustsolub, icefeinput, wdust, mfrac, nitrfix, diazolight, concfediaz, &
+        &                sedfeinput, distcoast, dustsolub, icefeinput, wdust, mfrac, nitrfix, diazolight, concfediaz, &
         &                hratio, fep_rats, fep_rath, lgw_rath
       !!----------------------------------------------------------------------
@@ -248,4 +250,5 @@
          WRITE(numout,*) '      fe input from hydrothermal vents         ln_hydrofe  = ', ln_hydrofe
          WRITE(numout,*) '      coastal release of iron                  sedfeinput  = ', sedfeinput
+         WRITE(numout,*) '      distance off the coast                   distcoast   = ', distcoast
          WRITE(numout,*) '      solubility of the dust                   dustsolub   = ', dustsolub
          WRITE(numout,*) '      Mineral Fe content of the dust           mfrac       = ', mfrac
@@ -307,19 +310,5 @@
             CALL iom_open (  TRIM( sn_dust%clname ) , numdust )
             CALL iom_gettime( numdust, zsteps, kntime=ntimes_dust)  ! get number of record in file
-            ALLOCATE( zdust(jpi,jpj,ntimes_dust) )
-            DO jm = 1, ntimes_dust
-               CALL iom_get( numdust, jpdom_data, TRIM( sn_dust%clvar ), zdust(:,:,jm), jm )
-            END DO
-            CALL iom_close( numdust )
-            ztimes_dust = 1._wp / REAL(ntimes_dust, wp) 
-            sumdepsi = 0.e0
-            DO jm = 1, ntimes_dust
-               sumdepsi = sumdepsi + glob_sum( zdust(:,:,jm) * e1e2t(:,:) * tmask(:,:,1) * ztimes_dust )
-            END DO
-            sumdepsi = sumdepsi / ( nyear_len(1) * rday ) * 12. * 8.8 * 0.075 * mfrac / 28.1 
-            DEALLOCATE( zdust)
-         ENDIF
-      ELSE
-         sumdepsi  = 0._wp
+         END IF
       END IF
 
@@ -419,19 +408,5 @@
             CALL iom_open ( TRIM( sn_ndepo%clname ), numdepo )
             CALL iom_gettime( numdepo, zsteps, kntime=ntimes_ndep)
-            ALLOCATE( zndepo(jpi,jpj,ntimes_ndep) )
-            DO jm = 1, ntimes_ndep
-               CALL iom_get( numdepo, jpdom_data, TRIM( sn_ndepo%clvar ), zndepo(:,:,jm), jm )
-            END DO
-            CALL iom_close( numdepo )
-            ztimes_ndep = 1._wp / REAL(ntimes_ndep, wp) 
-            nitdepinput = 0._wp
-            DO jm = 1, ntimes_ndep
-              nitdepinput = nitdepinput + glob_sum( zndepo(:,:,jm) * e1e2t(:,:) * tmask(:,:,1) * ztimes_ndep )
-            ENDDO
-            nitdepinput = nitdepinput / rno3 / 14E6 
-            DEALLOCATE( zndepo)
-         ENDIF
-      ELSE
-         nitdepinput = 0._wp
+         ENDIF
       ENDIF
 
@@ -459,9 +434,15 @@
             DO jj = 2, jpjm1
                DO ji = fs_2, fs_jpim1
-                  IF( tmask(ji,jj,jk) /= 0. ) THEN
-                     zmaskt = tmask(ji+1,jj,jk) * tmask(ji-1,jj,jk) * tmask(ji,jj+1,jk)    &
-                        &                       * tmask(ji,jj-1,jk) * tmask(ji,jj,jk+1)
-                     IF( zmaskt == 0. )   zcmask(ji,jj,jk ) = MAX( 0.1, zcmask(ji,jj,jk) ) 
-                  END IF
+                  ze3t   = e3t_0(ji,jj,jk)
+                  zsurfc =  e1u(ji,jj) * ( 1. - umask(ji  ,jj  ,jk) )   &
+                          + e1u(ji,jj) * ( 1. - umask(ji-1,jj  ,jk) )   &
+                          + e2v(ji,jj) * ( 1. - vmask(ji  ,jj  ,jk) )   &
+                          + e2v(ji,jj) * ( 1. - vmask(ji  ,jj-1,jk) )
+                  zsurfp = zsurfc * ze3t / e1e2t(ji,jj)
+                  ! estimation of the coastal slope : 5 km off the coast
+                  ze3t2 = ze3t * ze3t
+                  zcslp = SQRT( ( distcoast*distcoast + ze3t2 ) / ze3t2 )
+                  !
+                  zcmask(ji,jj,jk) = zcmask(ji,jj,jk) + zcslp * zsurfp
                END DO
             END DO
@@ -519,9 +500,8 @@
          WRITE(numout,*) '    DIC Supply : ', rivdicinput*1E3*12./1E12     ,' TgC/yr'
          WRITE(numout,*) 
-         WRITE(numout,*) '    Total input of elements from atmospheric supply'
-         WRITE(numout,*) '    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
-         WRITE(numout,*) '    N Supply   : ', nitdepinput*rno3*1E3/1E12*14.,' TgN/yr'
-         WRITE(numout,*) 
-      ENDIF
+      ENDIF
+      !
+      sedsilfrac = 0.03     ! percentage of silica loss in the sediments
+      sedcalfrac = 0.6      ! percentage of calcite loss in the sediments
       !
    END SUBROUTINE p4z_sbc_init
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsed.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsed.F90	(revision 10321)
@@ -14,7 +14,8 @@
    USE trc             !  passive tracers common variables 
    USE sms_pisces      !  PISCES Source Minus Sink variables
-   USE p4zice          !  Co-limitations of differents nutrients
+   USE p4zlim          !  Co-limitations of differents nutrients
    USE p4zsbc          !  External source of nutrients 
    USE p4zint          !  interpolation and computation of various fields
+   USE sed             !  Sediment module
    USE iom             !  I/O manager
    USE prtctl_trc      !  print control for debugging
@@ -29,9 +30,10 @@
    REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:  ) :: sdenit     !: Nitrate reduction in the sediments
    REAL(wp) :: r1_rday                  !: inverse of rday
+   LOGICAL, SAVE :: lk_sed
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -49,7 +51,6 @@
       !
       INTEGER, INTENT(in) ::   kt, knt ! ocean time step
-      INTEGER  ::   ji, jj, jk, ikt
-      REAL(wp) ::   zsumsedsi, zsumsedpo4, zsumsedcal
-      REAL(wp) ::   zrivalk, zrivsil, zrivno3
+      INTEGER  ::  ji, jj, jk, ikt
+      REAL(wp) ::  zrivalk, zrivsil, zrivno3
       REAL(wp) ::  zwflux, zfminus, zfplus
       REAL(wp) ::  zlim, zfact, zfactcal
@@ -62,6 +63,5 @@
       !
       CHARACTER (len=25) :: charout
-      REAL(wp), DIMENSION(jpi,jpj    ) :: zwork1, zwork2, zwork3
-      REAL(wp), DIMENSION(jpi,jpj    ) :: zdenit2d, zbureff
+      REAL(wp), DIMENSION(jpi,jpj    ) :: zdenit2d, zbureff, zwork
       REAL(wp), DIMENSION(jpi,jpj    ) :: zwsbio3, zwsbio4, zwscal
       REAL(wp), DIMENSION(jpi,jpj    ) :: zsedcal, zsedsi, zsedc
@@ -73,4 +73,13 @@
       IF( ln_timing )  CALL timing_start('p4z_sed')
       !
+      IF( kt == nittrc000 .AND. knt == 1 )   THEN
+          r1_rday  = 1. / rday
+          IF (ln_sediment .AND. ln_sed_2way) THEN
+             lk_sed = .TRUE.
+          ELSE
+             lk_sed = .FALSE.
+          ENDIF
+      ENDIF
+      !
       IF( kt == nittrc000 .AND. knt == 1 )   r1_rday  = 1. / rday
       !
@@ -82,7 +91,5 @@
       zdenit2d(:,:) = 0.e0
       zbureff (:,:) = 0.e0
-      zwork1  (:,:) = 0.e0
-      zwork2  (:,:) = 0.e0
-      zwork3  (:,:) = 0.e0
+      zwork   (:,:) = 0.e0
       zsedsi  (:,:) = 0.e0
       zsedcal (:,:) = 0.e0
@@ -189,14 +196,4 @@
       ENDIF
 
-      ! Add the external input of iron from sediment mobilization
-      ! ------------------------------------------------------
-      IF( ln_ironsed ) THEN
-                         tra(:,:,:,jpfer) = tra(:,:,:,jpfer) + ironsed(:,:,:) * rfact2
-         IF( ln_ligand ) tra(:,:,:,jpfep) = tra(:,:,:,jpfep) + ( ironsed(:,:,:) * fep_rats ) * rfact2
-         !
-         IF( lk_iomput .AND. knt == nrdttrc .AND. iom_use( "Ironsed" ) )   &
-            &   CALL iom_put( "Ironsed", ironsed(:,:,:) * 1.e+3 * tmask(:,:,:) ) ! iron inputs from sediments
-      ENDIF
-
       ! Add the external input of iron from hydrothermal vents
       ! ------------------------------------------------------
@@ -235,4 +232,15 @@
 
       IF( .NOT.lk_sed ) THEN
+!
+         ! Add the external input of iron from sediment mobilization
+         ! ------------------------------------------------------
+         IF( ln_ironsed ) THEN
+                            tra(:,:,:,jpfer) = tra(:,:,:,jpfer) + ironsed(:,:,:) * rfact2
+            IF( ln_ligand ) tra(:,:,:,jpfep) = tra(:,:,:,jpfep) + ( ironsed(:,:,:) * fep_rats ) * rfact2
+            !
+            IF( lk_iomput .AND. knt == nrdttrc .AND. iom_use( "Ironsed" ) )   &
+               &   CALL iom_put( "Ironsed", ironsed(:,:,:) * 1.e+3 * tmask(:,:,:) ) ! iron inputs from sediments
+         ENDIF
+
          ! Computation of the sediment denitrification proportion: The metamodel from midlleburg (2006) is being used
          ! Computation of the fraction of organic matter that is permanently buried from Dunne's model
@@ -255,28 +263,7 @@
                    &     + trb(ji,jj,ikt,jppoc) * zwsbio3(ji,jj) ) * 1E6
                  zbureff(ji,jj) = 0.013 + 0.53 * zflx**2 / ( 7.0 + zflx )**2
-                ENDIF
-              END DO
-           END DO 
-
-           ! Loss of biogenic silicon, Caco3 organic carbon in the sediments. 
-           ! First, the total loss is computed.
-           ! The factor for calcite comes from the alkalinity effect
-           ! -------------------------------------------------------------
-           DO jj = 1, jpj
-              DO ji = 1, jpi
-                 IF( tmask(ji,jj,1) == 1 ) THEN
-                    ikt = mbkt(ji,jj) 
-                    zwork1(ji,jj) = trb(ji,jj,ikt,jpgsi) * zwsbio4(ji,jj)
-                    zwork2(ji,jj) = trb(ji,jj,ikt,jpgoc) * zwsbio4(ji,jj) + trb(ji,jj,ikt,jppoc) * zwsbio3(ji,jj) 
-                    ! For calcite, burial efficiency is made a function of saturation
-                    zfactcal      = MIN( excess(ji,jj,ikt), 0.2 )
-                    zfactcal      = MIN( 1., 1.3 * ( 0.2 - zfactcal ) / ( 0.4 - zfactcal ) )
-                    zwork3(ji,jj) = trb(ji,jj,ikt,jpcal) * zwscal(ji,jj) * 2.e0 * zfactcal
-                ENDIF
-            END DO
-         END DO
-         zsumsedsi  = glob_sum( zwork1(:,:) * e1e2t(:,:) ) * r1_rday
-         zsumsedpo4 = glob_sum( zwork2(:,:) * e1e2t(:,:) ) * r1_rday
-         zsumsedcal = glob_sum( zwork3(:,:) * e1e2t(:,:) ) * r1_rday
+              ENDIF
+            END DO
+         END DO 
          !
       ENDIF
@@ -285,5 +272,5 @@
       ! Thus, the amount of silica lost in the sediments equal the supply at the surface (dust+rivers)
       ! ------------------------------------------------------
-      IF( .NOT.lk_sed )  zrivsil =  1._wp - ( sumdepsi + rivdsiinput * r1_ryyss ) / ( zsumsedsi + rtrn )
+      IF( .NOT.lk_sed )  zrivsil = 1._wp - sedsilfrac
 
       DO jj = 1, jpj
@@ -312,5 +299,5 @@
                zfactcal = MIN( excess(ji,jj,ikt), 0.2 )
                zfactcal = MIN( 1., 1.3 * ( 0.2 - zfactcal ) / ( 0.4 - zfactcal ) )
-               zrivalk  =  1._wp - ( rivalkinput * r1_ryyss ) * zfactcal / ( zsumsedcal + rtrn )
+               zrivalk  = sedcalfrac * zfactcal
                tra(ji,jj,ikt,jptal) =  tra(ji,jj,ikt,jptal) + zcaloss * zrivalk * 2.0
                tra(ji,jj,ikt,jpdic) =  tra(ji,jj,ikt,jpdic) + zcaloss * zrivalk
@@ -492,9 +479,9 @@
             IF( iom_use("Nfix"   ) ) CALL iom_put( "Nfix", nitrpot(:,:,:) * nitrfix * rno3 * zfact * tmask(:,:,:) )  ! nitrogen fixation 
             IF( iom_use("INTNFIX") ) THEN   ! nitrogen fixation rate in ocean ( vertically integrated )
-               zwork1(:,:) = 0.
+               zwork(:,:) = 0.
                DO jk = 1, jpkm1
-                 zwork1(:,:) = zwork1(:,:) + nitrpot(:,:,jk) * nitrfix * rno3 * zfact * e3t_n(:,:,jk) * tmask(:,:,jk)
+                 zwork(:,:) = zwork(:,:) + nitrpot(:,:,jk) * nitrfix * rno3 * zfact * e3t_n(:,:,jk) * tmask(:,:,jk)
                ENDDO
-               CALL iom_put( "INTNFIX" , zwork1 ) 
+               CALL iom_put( "INTNFIX" , zwork ) 
             ENDIF
             IF( iom_use("SedCal" ) ) CALL iom_put( "SedCal", zsedcal(:,:) * zfact )
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsink.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsink.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsink.F90	(revision 10321)
@@ -39,7 +39,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsms.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsms.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p4zsms.F90	(revision 10321)
@@ -40,7 +40,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -101,9 +101,10 @@
       ENDIF
       !
+      IF( ll_sbc ) CALL p4z_sbc( kt )   ! external sources of nutrients 
+      !
+#if ! defined key_sed_off
       CALL p4z_che              ! computation of chemical constants
       CALL p4z_int( kt )        ! computation of various rates for biogeochemistry
       !
-      IF( ll_sbc ) CALL p4z_sbc( kt )   ! external sources of nutrients 
-
       DO jnt = 1, nrdttrc          ! Potential time splitting if requested
          !
@@ -149,8 +150,15 @@
          END DO
       END IF
-      !
-      IF( lk_sed ) THEN 
+#endif
+      !
+      IF( ln_sediment ) THEN 
          !
          CALL sed_model( kt )     !  Main program of Sediment model
+         !
+         IF( ln_top_euler ) THEN
+            DO jn = jp_pcs0, jp_pcs1
+               trn(:,:,:,jn) = trb(:,:,:,jn)
+            END DO
+         ENDIF
          !
       ENDIF
@@ -352,45 +360,47 @@
       IF(lwp)  WRITE(numout,*)
 
-      IF( cn_cfg == "orca" .AND. .NOT. lk_c1d ) THEN      ! ORCA configuration (not 1D) !
-         !                                                ! --------------------------- !
-         ! set total alkalinity, phosphate, nitrate & silicate
-         zarea          = 1._wp / glob_sum( cvol(:,:,:) ) * 1e6              
-
-         zalksumn = glob_sum( trn(:,:,:,jptal) * cvol(:,:,:)  ) * zarea
-         zpo4sumn = glob_sum( trn(:,:,:,jppo4) * cvol(:,:,:)  ) * zarea * po4r
-         zno3sumn = glob_sum( trn(:,:,:,jpno3) * cvol(:,:,:)  ) * zarea * rno3
-         zsilsumn = glob_sum( trn(:,:,:,jpsil) * cvol(:,:,:)  ) * zarea
+      IF( cn_cfg == "ORCA" .OR. cn_cfg == "orca") THEN
+         IF( .NOT. lk_c1d ) THEN      ! ORCA configuration (not 1D) !
+            !                                                ! --------------------------- !
+            ! set total alkalinity, phosphate, nitrate & silicate
+            zarea          = 1._wp / glob_sum( cvol(:,:,:) ) * 1e6              
+
+            zalksumn = glob_sum( trn(:,:,:,jptal) * cvol(:,:,:)  ) * zarea
+            zpo4sumn = glob_sum( trn(:,:,:,jppo4) * cvol(:,:,:)  ) * zarea * po4r
+            zno3sumn = glob_sum( trn(:,:,:,jpno3) * cvol(:,:,:)  ) * zarea * rno3
+            zsilsumn = glob_sum( trn(:,:,:,jpsil) * cvol(:,:,:)  ) * zarea
  
-         IF(lwp) WRITE(numout,*) '       TALKN mean : ', zalksumn
-         trn(:,:,:,jptal) = trn(:,:,:,jptal) * alkmean / zalksumn
-
-         IF(lwp) WRITE(numout,*) '       PO4N  mean : ', zpo4sumn
-         trn(:,:,:,jppo4) = trn(:,:,:,jppo4) * po4mean / zpo4sumn
-
-         IF(lwp) WRITE(numout,*) '       NO3N  mean : ', zno3sumn
-         trn(:,:,:,jpno3) = trn(:,:,:,jpno3) * no3mean / zno3sumn
-
-         IF(lwp) WRITE(numout,*) '       SiO3N mean : ', zsilsumn
-         trn(:,:,:,jpsil) = MIN( 400.e-6,trn(:,:,:,jpsil) * silmean / zsilsumn )
-         !
-         !
-         IF( .NOT. ln_top_euler ) THEN
-            zalksumb = glob_sum( trb(:,:,:,jptal) * cvol(:,:,:)  ) * zarea
-            zpo4sumb = glob_sum( trb(:,:,:,jppo4) * cvol(:,:,:)  ) * zarea * po4r
-            zno3sumb = glob_sum( trb(:,:,:,jpno3) * cvol(:,:,:)  ) * zarea * rno3
-            zsilsumb = glob_sum( trb(:,:,:,jpsil) * cvol(:,:,:)  ) * zarea
+            IF(lwp) WRITE(numout,*) '       TALKN mean : ', zalksumn
+            trn(:,:,:,jptal) = trn(:,:,:,jptal) * alkmean / zalksumn
+
+            IF(lwp) WRITE(numout,*) '       PO4N  mean : ', zpo4sumn
+            trn(:,:,:,jppo4) = trn(:,:,:,jppo4) * po4mean / zpo4sumn
+
+            IF(lwp) WRITE(numout,*) '       NO3N  mean : ', zno3sumn
+            trn(:,:,:,jpno3) = trn(:,:,:,jpno3) * no3mean / zno3sumn
+
+            IF(lwp) WRITE(numout,*) '       SiO3N mean : ', zsilsumn
+            trn(:,:,:,jpsil) = MIN( 400.e-6,trn(:,:,:,jpsil) * silmean / zsilsumn )
+            !
+            !
+            IF( .NOT. ln_top_euler ) THEN
+               zalksumb = glob_sum( trb(:,:,:,jptal) * cvol(:,:,:)  ) * zarea
+               zpo4sumb = glob_sum( trb(:,:,:,jppo4) * cvol(:,:,:)  ) * zarea * po4r
+               zno3sumb = glob_sum( trb(:,:,:,jpno3) * cvol(:,:,:)  ) * zarea * rno3
+               zsilsumb = glob_sum( trb(:,:,:,jpsil) * cvol(:,:,:)  ) * zarea
  
-            IF(lwp) WRITE(numout,*) ' '
-            IF(lwp) WRITE(numout,*) '       TALKB mean : ', zalksumb
-            trb(:,:,:,jptal) = trb(:,:,:,jptal) * alkmean / zalksumb
-
-            IF(lwp) WRITE(numout,*) '       PO4B  mean : ', zpo4sumb
-            trb(:,:,:,jppo4) = trb(:,:,:,jppo4) * po4mean / zpo4sumb
-
-            IF(lwp) WRITE(numout,*) '       NO3B  mean : ', zno3sumb
-            trb(:,:,:,jpno3) = trb(:,:,:,jpno3) * no3mean / zno3sumb
-
-            IF(lwp) WRITE(numout,*) '       SiO3B mean : ', zsilsumb
-            trb(:,:,:,jpsil) = MIN( 400.e-6,trb(:,:,:,jpsil) * silmean / zsilsumb )
+               IF(lwp) WRITE(numout,*) ' '
+               IF(lwp) WRITE(numout,*) '       TALKB mean : ', zalksumb
+               trb(:,:,:,jptal) = trb(:,:,:,jptal) * alkmean / zalksumb
+
+               IF(lwp) WRITE(numout,*) '       PO4B  mean : ', zpo4sumb
+               trb(:,:,:,jppo4) = trb(:,:,:,jppo4) * po4mean / zpo4sumb
+
+               IF(lwp) WRITE(numout,*) '       NO3B  mean : ', zno3sumb
+               trb(:,:,:,jpno3) = trb(:,:,:,jpno3) * no3mean / zno3sumb
+
+               IF(lwp) WRITE(numout,*) '       SiO3B mean : ', zsilsumb
+               trb(:,:,:,jpsil) = MIN( 400.e-6,trb(:,:,:,jpsil) * silmean / zsilsumb )
+           ENDIF
         ENDIF
         !
Index: MO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zice.F90	(revision 10320)
+++ 	(revision )
@@ -1,602 +1,0 @@
-MODULE p5zice
-   !!======================================================================
-   !!                         ***  MODULE p5zice  ***
-   !! TOP :   PISCES with variable stoichiometry 
-   !!======================================================================
-   !! History :   1.0  !  2004     (O. Aumont) Original code
-   !!             2.0  !  2007-12  (C. Ethe, G. Madec)  F90
-   !!             3.4  !  2011-04  (O. Aumont, C. Ethe) Limitation for iron modelled in quota 
-   !!             3.6  !  2015-05  (O. Aumont) PISCES quota
-   !!----------------------------------------------------------------------
-   !!   p5z_lim        :   Compute the nutrients limitation terms 
-   !!   p5z_lim_init   :   Read the namelist 
-   !!----------------------------------------------------------------------
-   USE oce_trc         ! Shared ocean-passive tracers variables
-   USE trc             ! Tracers defined
-   USE sms_pisces      ! PISCES variables
-   USE iom             !  I/O manager
-
-   IMPLICIT NONE
-   PRIVATE
-
-   PUBLIC p5z_lim    
-   PUBLIC p5z_lim_init    
-   PUBLIC p5z_lim_alloc
-
-   !! * Shared module variables
-   REAL(wp), PUBLIC ::  concnno3    !:  NO3, PO4 half saturation   
-   REAL(wp), PUBLIC ::  concpno3    !:  NO3, PO4 half saturation   
-   REAL(wp), PUBLIC ::  concdno3    !:  Phosphate half saturation for diatoms  
-   REAL(wp), PUBLIC ::  concnnh4    !:  NH4 half saturation for phyto  
-   REAL(wp), PUBLIC ::  concpnh4    !:  NH4 half saturation for phyto  
-   REAL(wp), PUBLIC ::  concdnh4    !:  NH4 half saturation for diatoms
-   REAL(wp), PUBLIC ::  concnpo4    !:  NH4 half saturation for diatoms
-   REAL(wp), PUBLIC ::  concppo4    !:  NH4 half saturation for diatoms
-   REAL(wp), PUBLIC ::  concdpo4    !:  NH4 half saturation for diatoms
-   REAL(wp), PUBLIC ::  concnfer    !:  Iron half saturation for nanophyto 
-   REAL(wp), PUBLIC ::  concpfer    !:  Iron half saturation for nanophyto 
-   REAL(wp), PUBLIC ::  concdfer    !:  Iron half saturation for diatoms  
-   REAL(wp), PUBLIC ::  concbno3    !:  NO3 half saturation  for bacteria 
-   REAL(wp), PUBLIC ::  concbnh4    !:  NH4 half saturation for bacteria
-   REAL(wp), PUBLIC ::  concbpo4    !:  PO4 half saturation for bacteria
-   REAL(wp), PUBLIC ::  xsizedia    !:  Minimum size criteria for diatoms
-   REAL(wp), PUBLIC ::  xsizepic    !:  Minimum size criteria for diatoms
-   REAL(wp), PUBLIC ::  xsizephy    !:  Minimum size criteria for nanophyto
-   REAL(wp), PUBLIC ::  xsizern     !:  Size ratio for nanophytoplankton
-   REAL(wp), PUBLIC ::  xsizerp     !:  Size ratio for nanophytoplankton
-   REAL(wp), PUBLIC ::  xsizerd     !:  Size ratio for diatoms
-   REAL(wp), PUBLIC ::  xksi1       !:  half saturation constant for Si uptake 
-   REAL(wp), PUBLIC ::  xksi2       !:  half saturation constant for Si/C 
-   REAL(wp), PUBLIC ::  xkdoc       !:  2nd half-sat. of DOC remineralization  
-   REAL(wp), PUBLIC ::  concbfe     !:  Fe half saturation for bacteria 
-   REAL(wp), PUBLIC ::  oxymin      !:  half saturation constant for anoxia
-   REAL(wp), PUBLIC ::  qfnopt      !:  optimal Fe quota for nanophyto
-   REAL(wp), PUBLIC ::  qfpopt      !:  optimal Fe quota for nanophyto
-   REAL(wp), PUBLIC ::  qfdopt      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  caco3r      !:  mean rainratio 
-   REAL(wp), PUBLIC ::  qnnmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qnnmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qpnmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qpnmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qnpmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qnpmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qppmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qppmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qndmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qndmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qpdmin      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qpdmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qfnmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qfpmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  qfdmax      !:  optimal Fe quota for diatoms
-   REAL(wp), PUBLIC ::  zpsinh4
-   REAL(wp), PUBLIC ::  zpsino3
-   REAL(wp), PUBLIC ::  zpsiuptk
-
-   !!*  Allometric variations of the quotas
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnnmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnnmax    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpnmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpnmax    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnpmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnpmax    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqppmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqppmax    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqndmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqndmax    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpdmin    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpdmax    !: ???
-
-   !!* Phytoplankton limitation terms
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanono3   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatno3   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanonh4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatnh4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanopo4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatpo4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimphy    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdia    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimnfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimsi     !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbac    !: ??
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbacl   !: ??
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicono3   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpiconh4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicopo4   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanodop   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicodop   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatdop   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanofer   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicofer   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatfer   !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimpic    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimpfe    !: ???
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvnuptk
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvpuptk
-   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvduptk
-
-   ! Coefficient for iron limitation
-   REAL(wp) ::  xcoef1   = 0.00167  / 55.85
-   REAL(wp) ::  xcoef2   = 1.21E-5 * 14. / 55.85 / 7.625 * 0.5 * 1.5
-   REAL(wp) ::  xcoef3   = 1.15E-4 * 14. / 55.85 / 7.625 * 0.5 
-   !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
-   !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
-   !!----------------------------------------------------------------------
-
-CONTAINS
-
-   SUBROUTINE p5z_lim( kt, knt )
-      !!---------------------------------------------------------------------
-      !!                     ***  ROUTINE p5z_lim  ***
-      !!
-      !! ** Purpose :   Compute the co-limitations by the various nutrients
-      !!              for the various phytoplankton species
-      !!
-      !! ** Method  : - ???
-      !!---------------------------------------------------------------------
-      !
-      INTEGER, INTENT(in)  :: kt, knt
-      !
-      INTEGER  ::   ji, jj, jk
-      REAL(wp) ::   zlim1, zlim2, zlim3, zlim4, zno3, zferlim
-      REAL(wp) ::   z1_trndia, z1_trnpic, z1_trnphy, ztem1, ztem2, zetot1
-      REAL(wp) ::   zratio, zration, zratiof, znutlim, zfalim
-      REAL(wp) ::   zconc1d, zconc1dnh4, zconc0n, zconc0nnh4, zconc0npo4, zconc0dpo4
-      REAL(wp) ::   zconc0p, zconc0pnh4, zconc0ppo4, zconcpfe, zconcnfe, zconcdfe
-      REAL(wp) ::   fanano, fananop, fananof, fadiat, fadiatp, fadiatf
-      REAL(wp) ::   fapico, fapicop, fapicof
-      REAL(wp) ::   zrpho, zrass, zcoef, zfuptk, zratchl
-      REAL(wp) ::   zfvn, zfvp, zfvf, zsizen, zsizep, zsized, znanochl, zpicochl, zdiatchl
-      REAL(wp) ::   zqfemn, zqfemp, zqfemd, zbactno3, zbactnh4
-      !!---------------------------------------------------------------------
-      !
-      IF( ln_timing )   CALL timing_start('p5z_lim')
-      !
-      zratchl = 6.0
-      !
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               ! 
-               ! Tuning of the iron concentration to a minimum level that is set to the detection limit
-               !-------------------------------------
-               zno3    = trb(ji,jj,jk,jpno3) / 40.e-6
-               zferlim = MAX( 3e-11 * zno3 * zno3, 5e-12 )
-               zferlim = MIN( zferlim, 7e-11 )
-               trb(ji,jj,jk,jpfer) = MAX( trb(ji,jj,jk,jpfer), zferlim )
-
-               ! Computation of the mean relative size of each community
-               ! -------------------------------------------------------
-               z1_trnphy   = 1. / ( trb(ji,jj,jk,jpphy) + rtrn )
-               z1_trnpic   = 1. / ( trb(ji,jj,jk,jppic) + rtrn )
-               z1_trndia   = 1. / ( trb(ji,jj,jk,jpdia) + rtrn )
-               znanochl = trb(ji,jj,jk,jpnch) * z1_trnphy
-               zpicochl = trb(ji,jj,jk,jppch) * z1_trnpic
-               zdiatchl = trb(ji,jj,jk,jpdch) * z1_trndia
-
-               ! Computation of a variable Ks for iron on diatoms taking into account
-               ! that increasing biomass is made of generally bigger cells
-               !------------------------------------------------
-               zsized            = sized(ji,jj,jk)**0.81
-               zconcdfe          = concdfer * zsized
-               zconc1d           = concdno3 * zsized
-               zconc1dnh4        = concdnh4 * zsized
-               zconc0dpo4        = concdpo4 * zsized
-
-               zsizep            = 1.
-               zconcpfe          = concpfer * zsizep
-               zconc0p           = concpno3 * zsizep
-               zconc0pnh4        = concpnh4 * zsizep
-               zconc0ppo4        = concppo4 * zsizep
-
-               zsizen            = 1.
-               zconcnfe          = concnfer * zsizen
-               zconc0n           = concnno3 * zsizen
-               zconc0nnh4        = concnnh4 * zsizen
-               zconc0npo4        = concnpo4 * zsizen
-
-               ! Allometric variations of the minimum and maximum quotas
-               ! From Talmy et al. (2014) and Maranon et al. (2013)
-               ! -------------------------------------------------------
-               xqnnmin(ji,jj,jk) = qnnmin
-               xqnnmax(ji,jj,jk) = qnnmax
-               xqndmin(ji,jj,jk) = qndmin * sized(ji,jj,jk)**(-0.27) 
-               xqndmax(ji,jj,jk) = qndmax
-               xqnpmin(ji,jj,jk) = qnpmin
-               xqnpmax(ji,jj,jk) = qnpmax
-
-               ! Computation of the optimal allocation parameters
-               ! Based on the different papers by Pahlow et al., and Smith et al.
-               ! -----------------------------------------------------------------
-               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc0nnh4,    &
-                 &         trb(ji,jj,jk,jpno3) / zconc0n)
-               fanano = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = trb(ji,jj,jk,jppo4) / zconc0npo4
-               fananop = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = biron(ji,jj,jk) / zconcnfe
-               fananof = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc0pnh4,    &
-                 &         trb(ji,jj,jk,jpno3) / zconc0p)
-               fapico = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = trb(ji,jj,jk,jppo4) / zconc0ppo4
-               fapicop = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = biron(ji,jj,jk) / zconcpfe
-               fapicof = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc1dnh4,    &
-                 &         trb(ji,jj,jk,jpno3) / zconc1d )
-               fadiat = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = trb(ji,jj,jk,jppo4) / zconc0dpo4
-               fadiatp = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               znutlim = biron(ji,jj,jk) / zconcdfe
-               fadiatf = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
-               !
-               ! Michaelis-Menten Limitation term for nutrients Small bacteria
-               ! -------------------------------------------------------------
-               zbactnh4 = trb(ji,jj,jk,jpnh4) / ( concbnh4 + trb(ji,jj,jk,jpnh4) )
-               zbactno3 = trb(ji,jj,jk,jpno3) / ( concbno3 + trb(ji,jj,jk,jpno3) ) * (1. - zbactnh4)
-               !
-               zlim1    = zbactno3 + zbactnh4
-               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concbpo4)
-               zlim3    = biron(ji,jj,jk) / ( concbfe + biron(ji,jj,jk) )
-               zlim4    = trb(ji,jj,jk,jpdoc) / ( xkdoc   + trb(ji,jj,jk,jpdoc) )
-               xlimbacl(ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
-               xlimbac (ji,jj,jk) = xlimbacl(ji,jj,jk) * zlim4
-               !
-               ! Michaelis-Menten Limitation term for nutrients Small flagellates
-               ! -----------------------------------------------
-               zfalim = (1.-fanano) / fanano
-               xnanonh4(ji,jj,jk) = (1. - fanano) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc0nnh4 + trb(ji,jj,jk,jpnh4) )
-               xnanono3(ji,jj,jk) = (1. - fanano) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc0n + trb(ji,jj,jk,jpno3) )  &
-               &                    * (1. - xnanonh4(ji,jj,jk))
-               !
-               zfalim = (1.-fananop) / fananop
-               xnanopo4(ji,jj,jk) = (1. - fananop) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0npo4 )
-               xnanodop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )   &
-               &                    * ( 1.0 - xnanopo4(ji,jj,jk) )
-               xnanodop(ji,jj,jk) = 0.
-               !
-               zfalim = (1.-fananof) / fananof
-               xnanofer(ji,jj,jk) = (1. - fananof) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcnfe )
-               !
-               zratiof   = trb(ji,jj,jk,jpnfe) * z1_trnphy
-               zqfemn = xcoef1 * znanochl + xcoef2 + xcoef3 * xnanono3(ji,jj,jk)
-               !
-               zration = trb(ji,jj,jk,jpnph) * z1_trnphy
-               zration = MIN(xqnnmax(ji,jj,jk), MAX( 2. * xqnnmin(ji,jj,jk), zration ))
-               fvnuptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqnnmin(ji,jj,jk) / (zration + rtrn)  &
-               &                   * MAX(0., (1. - zratchl * znanochl / 12. ) )
-               !
-               zlim1    = max(0., (zration - 2. * xqnnmin(ji,jj,jk) )  &
-               &          / (xqnnmax(ji,jj,jk) - 2. * xqnnmin(ji,jj,jk) ) ) * xqnnmax(ji,jj,jk)  &
-               &          / (zration + rtrn)
-               zlim3    = MAX( 0.,( zratiof - zqfemn ) / qfnopt ) 
-               xlimnfe(ji,jj,jk) = MIN( 1., zlim3 )
-               xlimphy(ji,jj,jk) = MIN( 1., zlim1, zlim3 )
-               !
-               ! Michaelis-Menten Limitation term for nutrients picophytoplankton
-               ! ----------------------------------------------------------------
-               zfalim = (1.-fapico) / fapico 
-               xpiconh4(ji,jj,jk) = (1. - fapico) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc0pnh4 + trb(ji,jj,jk,jpnh4) )
-               xpicono3(ji,jj,jk) = (1. - fapico) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc0p + trb(ji,jj,jk,jpno3) )  &
-               &                    * (1. - xpiconh4(ji,jj,jk))
-               !
-               zfalim = (1.-fapicop) / fapicop 
-               xpicopo4(ji,jj,jk) = (1. - fapicop) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0ppo4 )
-               xpicodop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )   &
-               &                    * ( 1.0 - xpicopo4(ji,jj,jk) )
-               xpicodop(ji,jj,jk) = 0.
-               !
-               zfalim = (1.-fapicof) / fapicof
-               xpicofer(ji,jj,jk) = (1. - fapicof) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcpfe )
-               !
-               zratiof   = trb(ji,jj,jk,jppfe) * z1_trnpic
-               zqfemp = xcoef1 * zpicochl + xcoef2 + xcoef3 * xpicono3(ji,jj,jk)
-               !
-               zration   = trb(ji,jj,jk,jpnpi) * z1_trnpic
-               zration = MIN(xqnpmax(ji,jj,jk), MAX( 2. * xqnpmin(ji,jj,jk), zration ))
-               fvpuptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqnpmin(ji,jj,jk) / (zration + rtrn)  &
-               &                   * MAX(0., (1. - zratchl * zpicochl / 12. ) ) 
-               !
-               zlim1    = max(0., (zration - 2. * xqnpmin(ji,jj,jk) )  &
-               &          / (xqnpmax(ji,jj,jk) - 2. * xqnpmin(ji,jj,jk) ) ) * xqnpmax(ji,jj,jk)  &
-               &          / (zration + rtrn)
-               zlim3    = MAX( 0.,( zratiof - zqfemp ) / qfpopt )
-               xlimpfe(ji,jj,jk) = MIN( 1., zlim3 )
-               xlimpic(ji,jj,jk) = MIN( 1., zlim1, zlim3 )
-               !
-               !   Michaelis-Menten Limitation term for nutrients Diatoms
-               !   ------------------------------------------------------
-               zfalim = (1.-fadiat) / fadiat 
-               xdiatnh4(ji,jj,jk) = (1. - fadiat) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc1dnh4 + trb(ji,jj,jk,jpnh4) )
-               xdiatno3(ji,jj,jk) = (1. - fadiat) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc1d + trb(ji,jj,jk,jpno3) )  &
-               &                    * (1. - xdiatnh4(ji,jj,jk))
-               !
-               zfalim = (1.-fadiatp) / fadiatp
-               xdiatpo4(ji,jj,jk) = (1. - fadiatp) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0dpo4 )
-               xdiatdop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )  &
-               &                    * ( 1.0 - xdiatpo4(ji,jj,jk) )
-               xdiatdop(ji,jj,jk) = 0.
-               !
-               zfalim = (1.-fadiatf) / fadiatf
-               xdiatfer(ji,jj,jk) = (1. - fadiatf) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcdfe )
-               !
-               zratiof   = trb(ji,jj,jk,jpdfe) * z1_trndia
-               zqfemd = xcoef1 * zdiatchl + xcoef2 + xcoef3 * xdiatno3(ji,jj,jk)
-               !
-               zration   = trb(ji,jj,jk,jpndi) * z1_trndia
-               zration = MIN(xqndmax(ji,jj,jk), MAX( 2. * xqndmin(ji,jj,jk), zration ))
-               fvduptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqndmin(ji,jj,jk) / (zration + rtrn)   &
-               &                   * MAX(0., (1. - zratchl * zdiatchl / 12. ) ) 
-               !
-               zlim1    = max(0., (zration - 2. * xqndmin(ji,jj,jk) )    &
-               &          / (xqndmax(ji,jj,jk) - 2. * xqndmin(ji,jj,jk) ) )   &
-               &          * xqndmax(ji,jj,jk) / (zration + rtrn)
-               zlim3    = trb(ji,jj,jk,jpsil) / ( trb(ji,jj,jk,jpsil) + xksi(ji,jj) )
-               zlim4    = MAX( 0., ( zratiof - zqfemd ) / qfdopt )
-               xlimdfe(ji,jj,jk) = MIN( 1., zlim4 )
-               xlimdia(ji,jj,jk) = MIN( 1., zlim1, zlim3, zlim4 )
-               xlimsi(ji,jj,jk)  = MIN( zlim1, zlim4 )
-            END DO
-         END DO
-      END DO
-      !
-      ! Compute the phosphorus quota values. It is based on Litchmann et al., 2004 and Daines et al, 2013.
-      ! The relative contribution of three fonctional pools are computed: light harvesting apparatus, 
-      ! nutrient uptake pool and assembly machinery. DNA is assumed to represent 1% of the dry mass of 
-      ! phytoplankton (see Daines et al., 2013). 
-      ! --------------------------------------------------------------------------------------------------
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               ! Size estimation of nanophytoplankton
-               ! ------------------------------------
-               zfvn = 2. * fvnuptk(ji,jj,jk)
-               sizen(ji,jj,jk) = MAX(1., MIN(xsizern, 1.0 / ( MAX(rtrn, zfvn) ) ) )
-
-               ! N/P ratio of nanophytoplankton
-               ! ------------------------------
-               zfuptk = 0.23 * zfvn
-               zrpho = 2.24 * trb(ji,jj,jk,jpnch) / ( trb(ji,jj,jk,jpnph) * rno3 * 15. + rtrn )
-               zrass = 1. - 0.2 - zrpho - zfuptk
-               xqpnmax(ji,jj,jk) = ( zfuptk + zrpho ) * 0.0128 * 16. + zrass * 1./ 7.2 * 16.
-               xqpnmax(ji,jj,jk) = xqpnmax(ji,jj,jk) * trb(ji,jj,jk,jpnph) / ( trb(ji,jj,jk,jpphy) + rtrn ) + 0.13
-               xqpnmin(ji,jj,jk) = 0.13 + 0.23 * 0.0128 * 16.
-
-               ! Size estimation of picophytoplankton
-               ! ------------------------------------
-               zfvn = 2. * fvpuptk(ji,jj,jk)
-               sizep(ji,jj,jk) = MAX(1., MIN(xsizerp, 1.0 / ( MAX(rtrn, zfvn) ) ) )
-
-               ! N/P ratio of picophytoplankton
-               ! ------------------------------
-               zfuptk = 0.35 * zfvn
-               zrpho = 2.24 * trb(ji,jj,jk,jppch) / ( trb(ji,jj,jk,jpnpi) * rno3 * 15. + rtrn )
-               zrass = 1. - 0.4 - zrpho - zfuptk
-               xqppmax(ji,jj,jk) =  (zrpho + zfuptk) * 0.0128 * 16. + zrass * 1./ 9. * 16.
-               xqppmax(ji,jj,jk) = xqppmax(ji,jj,jk) * trb(ji,jj,jk,jpnpi) / ( trb(ji,jj,jk,jppic) + rtrn ) + 0.13
-               xqppmin(ji,jj,jk) = 0.13
-
-               ! Size estimation of diatoms
-               ! --------------------------
-               zfvn = 2. * fvduptk(ji,jj,jk)
-               sized(ji,jj,jk) = MAX(1., MIN(xsizerd, 1.0 / ( MAX(rtrn, zfvn) ) ) )
-               zcoef = trb(ji,jj,jk,jpdia) - MIN(xsizedia, trb(ji,jj,jk,jpdia) )
-               sized(ji,jj,jk) = 1. + xsizerd * zcoef *1E6 / ( 1. + zcoef * 1E6 )
-
-               ! N/P ratio of diatoms
-               ! --------------------
-               zfuptk = 0.2 * zfvn
-               zrpho = 2.24 * trb(ji,jj,jk,jpdch) / ( trb(ji,jj,jk,jpndi) * rno3 * 15. + rtrn )
-               zrass = 1. - 0.2 - zrpho - zfuptk
-               xqpdmax(ji,jj,jk) = ( zfuptk + zrpho ) * 0.0128 * 16. + zrass * 1./ 7.2 * 16.
-               xqpdmax(ji,jj,jk) = xqpdmax(ji,jj,jk) * trb(ji,jj,jk,jpndi) / ( trb(ji,jj,jk,jpdia) + rtrn ) + 0.13
-               xqpdmin(ji,jj,jk) = 0.13 + 0.2 * 0.0128 * 16.
-
-            END DO
-         END DO
-      END DO
-
-      ! Compute the fraction of nanophytoplankton that is made of calcifiers
-      ! --------------------------------------------------------------------
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               zlim1 =  trb(ji,jj,jk,jpnh4) / ( trb(ji,jj,jk,jpnh4) + concnnh4 ) + trb(ji,jj,jk,jpno3)    &
-               &        / ( trb(ji,jj,jk,jpno3) + concnno3 ) * ( 1.0 - trb(ji,jj,jk,jpnh4)   &
-               &        / ( trb(ji,jj,jk,jpnh4) + concnnh4 ) )
-               zlim2  = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concnpo4 )
-               zlim3  = trb(ji,jj,jk,jpfer) / ( trb(ji,jj,jk,jpfer) +  5.E-11 ) 
-               ztem1  = MAX( 0., tsn(ji,jj,jk,jp_tem) )
-               ztem2  = tsn(ji,jj,jk,jp_tem) - 10.
-               zetot1 = MAX( 0., etot(ji,jj,jk) - 1.) / ( 4. + etot(ji,jj,jk) ) * 20. / ( 20. + etot(ji,jj,jk) ) 
-
-!               xfracal(ji,jj,jk) = caco3r * MIN( zlim1, zlim2, zlim3 )                  &
-               xfracal(ji,jj,jk) = caco3r                 &
-               &                   * ztem1 / ( 1. + ztem1 ) * MAX( 1., trb(ji,jj,jk,jpphy)*1E6 )   &
-                  &                * ( 1. + EXP(-ztem2 * ztem2 / 25. ) )         &
-                  &                * zetot1 * MIN( 1., 50. / ( hmld(ji,jj) + rtrn ) )
-               xfracal(ji,jj,jk) = MAX( 0.02, MIN( 0.8 , xfracal(ji,jj,jk) ) )
-            END DO
-         END DO
-      END DO
-      !
-      DO jk = 1, jpkm1
-         DO jj = 1, jpj
-            DO ji = 1, jpi
-               ! denitrification factor computed from O2 levels
-               nitrfac(ji,jj,jk) = MAX(  0.e0, 0.4 * ( 6.e-6  - trb(ji,jj,jk,jpoxy) )    &
-                  &                                / ( oxymin + trb(ji,jj,jk,jpoxy) )  )
-               nitrfac(ji,jj,jk) = MIN( 1., nitrfac(ji,jj,jk) )
-            END DO
-         END DO
-      END DO
-      !
-      IF( lk_iomput .AND. knt == nrdttrc ) THEN        ! save output diagnostics
-        IF( iom_use( "xfracal" ) ) CALL iom_put( "xfracal", xfracal(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
-        IF( iom_use( "LNnut"   ) ) CALL iom_put( "LNnut"  , xlimphy(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
-        IF( iom_use( "LPnut"   ) ) CALL iom_put( "LPnut"  , xlimpic(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
-        IF( iom_use( "LDnut"   ) ) CALL iom_put( "LDnut"  , xlimdia(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
-        IF( iom_use( "LNFe"    ) ) CALL iom_put( "LNFe"   , xlimnfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "LPFe"    ) ) CALL iom_put( "LPFe"   , xlimpfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "LDFe"    ) ) CALL iom_put( "LDFe"   , xlimdfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "SIZEN"   ) ) CALL iom_put( "SIZEN"  , sizen(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "SIZEP"   ) ) CALL iom_put( "SIZEP"  , sizep(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-        IF( iom_use( "SIZED"   ) ) CALL iom_put( "SIZED"  , sized(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
-      ENDIF
-      !
-      IF( ln_timing )  CALL timing_stop('p5z_lim')
-      !
-   END SUBROUTINE p5z_lim
-
-
-   SUBROUTINE p5z_lim_init
-      !!----------------------------------------------------------------------
-      !!                  ***  ROUTINE p5z_lim_init  ***
-      !!
-      !! ** Purpose :   Initialization of nutrient limitation parameters
-      !!
-      !! ** Method  :   Read the nampislim and nampisquota namelists and check
-      !!      the parameters called at the first timestep (nittrc000)
-      !!
-      !! ** input   :   Namelist nampislim
-      !!
-      !!----------------------------------------------------------------------
-      INTEGER :: ios                 ! Local integer output status for namelist read
-      !!
-      NAMELIST/namp5zice/ concnno3, concpno3, concdno3, concnnh4, concpnh4, concdnh4,  &
-         &                concnfer, concpfer, concdfer, concbfe, concnpo4, concppo4,   &
-         &                concdpo4, concbno3, concbnh4, concbpo4, xsizedia, xsizepic,  &
-         &                xsizephy, xsizern, xsizerp, xsizerd, xksi1, xksi2, xkdoc,    &
-         &                caco3r, oxymin
-         !
-      NAMELIST/namp5zquota/ qnnmin, qnnmax, qpnmin, qpnmax, qnpmin, qnpmax, qppmin,      &
-         &                  qppmax, qndmin, qndmax, qpdmin, qpdmax, qfnmax, qfpmax, qfdmax,  &
-         &                  qfnopt, qfpopt, qfdopt
-      !!----------------------------------------------------------------------
-      !
-      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
-      READ  ( numnatp_ref, namp5zice, IOSTAT = ios, ERR = 901)
-901   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nampislim in reference namelist', lwp )
-      !
-      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
-      READ  ( numnatp_cfg, namp5zice, IOSTAT = ios, ERR = 902 )
-902   IF( ios >  0 ) CALL ctl_nam ( ios , 'nampislim in configuration namelist', lwp )
-      IF(lwm) WRITE ( numonp, namp5zice )
-      !
-      IF(lwp) THEN                         ! control print
-         WRITE(numout,*) ' '
-         WRITE(numout,*) ' Namelist parameters for nutrient limitations, namp5zice'
-         WRITE(numout,*) ' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
-         WRITE(numout,*) '    mean rainratio                           caco3r    = ', caco3r
-         WRITE(numout,*) '    NO3 half saturation of nanophyto         concnno3  = ', concnno3
-         WRITE(numout,*) '    NO3 half saturation of picophyto         concpno3  = ', concpno3
-         WRITE(numout,*) '    NO3 half saturation of diatoms           concdno3  = ', concdno3
-         WRITE(numout,*) '    NH4 half saturation for phyto            concnnh4  = ', concnnh4
-         WRITE(numout,*) '    NH4 half saturation for pico             concpnh4  = ', concpnh4
-         WRITE(numout,*) '    NH4 half saturation for diatoms          concdnh4  = ', concdnh4
-         WRITE(numout,*) '    PO4 half saturation for phyto            concnpo4  = ', concnpo4
-         WRITE(numout,*) '    PO4 half saturation for pico             concppo4  = ', concppo4
-         WRITE(numout,*) '    PO4 half saturation for diatoms          concdpo4  = ', concdpo4
-         WRITE(numout,*) '    half saturation constant for Si uptake   xksi1     = ', xksi1
-         WRITE(numout,*) '    half saturation constant for Si/C        xksi2     = ', xksi2
-         WRITE(numout,*) '    half-sat. of DOC remineralization        xkdoc     = ', xkdoc
-         WRITE(numout,*) '    Iron half saturation for nanophyto       concnfer  = ', concnfer
-         WRITE(numout,*) '    Iron half saturation for picophyto       concpfer  = ', concpfer
-         WRITE(numout,*) '    Iron half saturation for diatoms         concdfer  = ', concdfer
-         WRITE(numout,*) '    size ratio for nanophytoplankton         xsizern   = ', xsizern
-         WRITE(numout,*) '    size ratio for picophytoplankton         xsizerp   = ', xsizerp
-         WRITE(numout,*) '    size ratio for diatoms                   xsizerd   = ', xsizerd
-         WRITE(numout,*) '    NO3 half saturation of bacteria          concbno3  = ', concbno3
-         WRITE(numout,*) '    NH4 half saturation for bacteria         concbnh4  = ', concbnh4
-         WRITE(numout,*) '    Minimum size criteria for diatoms        xsizedia  = ', xsizedia
-         WRITE(numout,*) '    Minimum size criteria for picophyto      xsizepic  = ', xsizepic
-         WRITE(numout,*) '    Minimum size criteria for nanophyto      xsizephy  = ', xsizephy
-         WRITE(numout,*) '    Fe half saturation for bacteria          concbfe   = ', concbfe
-         WRITE(numout,*) '    halk saturation constant for anoxia       oxymin   =' , oxymin
-      ENDIF
-
-      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
-      READ  ( numnatp_ref, namp5zquota, IOSTAT = ios, ERR = 903)
-903   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nampisquota in reference namelist', lwp )
-      !
-      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
-      READ  ( numnatp_cfg, namp5zquota, IOSTAT = ios, ERR = 904 )
-904   IF( ios >  0 ) CALL ctl_nam ( ios , 'nampisquota in configuration namelist', lwp )
-      IF(lwm) WRITE ( numonp, namp5zquota )
-      !
-      IF(lwp) THEN                         ! control print
-         WRITE(numout,*) ' '
-         WRITE(numout,*) ' Namelist parameters for nutrient limitations, namp5zquota'
-         WRITE(numout,*) ' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
-         WRITE(numout,*) '    optimal Fe quota for nano.               qfnopt    = ', qfnopt
-         WRITE(numout,*) '    optimal Fe quota for pico.               qfpopt    = ', qfpopt
-         WRITE(numout,*) '    Optimal Fe quota for diatoms             qfdopt    = ', qfdopt
-         WRITE(numout,*) '    Minimal N quota for nano                 qnnmin    = ', qnnmin
-         WRITE(numout,*) '    Maximal N quota for nano                 qnnmax    = ', qnnmax
-         WRITE(numout,*) '    Minimal P quota for nano                 qpnmin    = ', qpnmin
-         WRITE(numout,*) '    Maximal P quota for nano                 qpnmax    = ', qpnmax
-         WRITE(numout,*) '    Minimal N quota for pico                 qnpmin    = ', qnpmin
-         WRITE(numout,*) '    Maximal N quota for pico                 qnpmax    = ', qnpmax
-         WRITE(numout,*) '    Minimal P quota for pico                 qppmin    = ', qppmin
-         WRITE(numout,*) '    Maximal P quota for pico                 qppmax    = ', qppmax
-         WRITE(numout,*) '    Minimal N quota for diatoms              qndmin    = ', qndmin
-         WRITE(numout,*) '    Maximal N quota for diatoms              qndmax    = ', qndmax
-         WRITE(numout,*) '    Minimal P quota for diatoms              qpdmin    = ', qpdmin
-         WRITE(numout,*) '    Maximal P quota for diatoms              qpdmax    = ', qpdmax
-         WRITE(numout,*) '    Maximal Fe quota for nanophyto.          qfnmax    = ', qfnmax
-         WRITE(numout,*) '    Maximal Fe quota for picophyto.          qfpmax    = ', qfpmax
-         WRITE(numout,*) '    Maximal Fe quota for diatoms             qfdmax    = ', qfdmax
-      ENDIF
-      !
-      zpsino3 = 2.3 * rno3
-      zpsinh4 = 1.8 * rno3
-      zpsiuptk = 2.3 * rno3
-      !
-      nitrfac (:,:,:) = 0._wp
-      !
-   END SUBROUTINE p5z_lim_init
-
-
-   INTEGER FUNCTION p5z_lim_alloc()
-      !!----------------------------------------------------------------------
-      !!                     ***  ROUTINE p5z_lim_alloc  ***
-      !!----------------------------------------------------------------------
-      USE lib_mpp , ONLY: ctl_warn
-      INTEGER ::   ierr(2)        ! Local variables
-      !!----------------------------------------------------------------------
-      ierr(:) = 0
-      !
-      !*  Biological arrays for phytoplankton growth
-      ALLOCATE( xpicono3(jpi,jpj,jpk), xpiconh4(jpi,jpj,jpk),       &
-         &      xpicopo4(jpi,jpj,jpk), xpicodop(jpi,jpj,jpk),       &
-         &      xnanodop(jpi,jpj,jpk), xdiatdop(jpi,jpj,jpk),       &
-         &      xnanono3(jpi,jpj,jpk), xdiatno3(jpi,jpj,jpk),       &
-         &      xnanonh4(jpi,jpj,jpk), xdiatnh4(jpi,jpj,jpk),       &
-         &      xnanopo4(jpi,jpj,jpk), xdiatpo4(jpi,jpj,jpk),       &
-         &      xlimphy (jpi,jpj,jpk), xlimdia (jpi,jpj,jpk),       &
-         &      xlimnfe (jpi,jpj,jpk), xlimdfe (jpi,jpj,jpk),       &
-         &      xlimbac (jpi,jpj,jpk), xlimbacl(jpi,jpj,jpk),       &
-         &      xnanofer(jpi,jpj,jpk), xdiatfer(jpi,jpj,jpk),       &
-         &      xpicofer(jpi,jpj,jpk), xlimpfe (jpi,jpj,jpk),       &
-         &      fvnuptk (jpi,jpj,jpk), fvduptk (jpi,jpj,jpk),       &
-         &      fvpuptk (jpi,jpj,jpk), xlimpic (jpi,jpj,jpk),       &
-         &      xlimsi  (jpi,jpj,jpk), STAT=ierr(1) )
-         !
-      !*  Minimum/maximum quotas of phytoplankton
-      ALLOCATE( xqnnmin (jpi,jpj,jpk), xqnnmax(jpi,jpj,jpk),       &
-         &      xqpnmin (jpi,jpj,jpk), xqpnmax(jpi,jpj,jpk),       &
-         &      xqnpmin (jpi,jpj,jpk), xqnpmax(jpi,jpj,jpk),       &
-         &      xqppmin (jpi,jpj,jpk), xqppmax(jpi,jpj,jpk),       &
-         &      xqndmin (jpi,jpj,jpk), xqndmax(jpi,jpj,jpk),       &
-         &      xqpdmin (jpi,jpj,jpk), xqpdmax(jpi,jpj,jpk),     STAT=ierr(2) )
-         !
-      p5z_lim_alloc = MAXVAL( ierr )
-      !
-      IF( p5z_lim_alloc /= 0 ) CALL ctl_warn('p5z_lim_alloc : failed to allocate arrays.')
-      !
-   END FUNCTION p5z_lim_alloc
-   !!======================================================================
-END MODULE p5zice
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zlim.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zlim.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zlim.F90	(revision 10321)
@@ -0,0 +1,602 @@
+MODULE p5zlim
+   !!======================================================================
+   !!                         ***  MODULE p5zlim  ***
+   !! TOP :   PISCES with variable stoichiometry 
+   !!======================================================================
+   !! History :   1.0  !  2004     (O. Aumont) Original code
+   !!             2.0  !  2007-12  (C. Ethe, G. Madec)  F90
+   !!             3.4  !  2011-04  (O. Aumont, C. Ethe) Limitation for iron modelled in quota 
+   !!             3.6  !  2015-05  (O. Aumont) PISCES quota
+   !!----------------------------------------------------------------------
+   !!   p5z_lim        :   Compute the nutrients limitation terms 
+   !!   p5z_lim_init   :   Read the namelist 
+   !!----------------------------------------------------------------------
+   USE oce_trc         ! Shared ocean-passive tracers variables
+   USE trc             ! Tracers defined
+   USE sms_pisces      ! PISCES variables
+   USE iom             !  I/O manager
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC p5z_lim    
+   PUBLIC p5z_lim_init    
+   PUBLIC p5z_lim_alloc
+
+   !! * Shared module variables
+   REAL(wp), PUBLIC ::  concnno3    !:  NO3, PO4 half saturation   
+   REAL(wp), PUBLIC ::  concpno3    !:  NO3, PO4 half saturation   
+   REAL(wp), PUBLIC ::  concdno3    !:  Phosphate half saturation for diatoms  
+   REAL(wp), PUBLIC ::  concnnh4    !:  NH4 half saturation for phyto  
+   REAL(wp), PUBLIC ::  concpnh4    !:  NH4 half saturation for phyto  
+   REAL(wp), PUBLIC ::  concdnh4    !:  NH4 half saturation for diatoms
+   REAL(wp), PUBLIC ::  concnpo4    !:  NH4 half saturation for diatoms
+   REAL(wp), PUBLIC ::  concppo4    !:  NH4 half saturation for diatoms
+   REAL(wp), PUBLIC ::  concdpo4    !:  NH4 half saturation for diatoms
+   REAL(wp), PUBLIC ::  concnfer    !:  Iron half saturation for nanophyto 
+   REAL(wp), PUBLIC ::  concpfer    !:  Iron half saturation for nanophyto 
+   REAL(wp), PUBLIC ::  concdfer    !:  Iron half saturation for diatoms  
+   REAL(wp), PUBLIC ::  concbno3    !:  NO3 half saturation  for bacteria 
+   REAL(wp), PUBLIC ::  concbnh4    !:  NH4 half saturation for bacteria
+   REAL(wp), PUBLIC ::  concbpo4    !:  PO4 half saturation for bacteria
+   REAL(wp), PUBLIC ::  xsizedia    !:  Minimum size criteria for diatoms
+   REAL(wp), PUBLIC ::  xsizepic    !:  Minimum size criteria for diatoms
+   REAL(wp), PUBLIC ::  xsizephy    !:  Minimum size criteria for nanophyto
+   REAL(wp), PUBLIC ::  xsizern     !:  Size ratio for nanophytoplankton
+   REAL(wp), PUBLIC ::  xsizerp     !:  Size ratio for nanophytoplankton
+   REAL(wp), PUBLIC ::  xsizerd     !:  Size ratio for diatoms
+   REAL(wp), PUBLIC ::  xksi1       !:  half saturation constant for Si uptake 
+   REAL(wp), PUBLIC ::  xksi2       !:  half saturation constant for Si/C 
+   REAL(wp), PUBLIC ::  xkdoc       !:  2nd half-sat. of DOC remineralization  
+   REAL(wp), PUBLIC ::  concbfe     !:  Fe half saturation for bacteria 
+   REAL(wp), PUBLIC ::  oxymin      !:  half saturation constant for anoxia
+   REAL(wp), PUBLIC ::  qfnopt      !:  optimal Fe quota for nanophyto
+   REAL(wp), PUBLIC ::  qfpopt      !:  optimal Fe quota for nanophyto
+   REAL(wp), PUBLIC ::  qfdopt      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  caco3r      !:  mean rainratio 
+   REAL(wp), PUBLIC ::  qnnmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qnnmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qpnmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qpnmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qnpmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qnpmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qppmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qppmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qndmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qndmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qpdmin      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qpdmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qfnmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qfpmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  qfdmax      !:  optimal Fe quota for diatoms
+   REAL(wp), PUBLIC ::  zpsinh4
+   REAL(wp), PUBLIC ::  zpsino3
+   REAL(wp), PUBLIC ::  zpsiuptk
+
+   !!*  Allometric variations of the quotas
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnnmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnnmax    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpnmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpnmax    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnpmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqnpmax    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqppmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqppmax    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqndmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqndmax    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpdmin    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE,   DIMENSION(:,:,:)  ::   xqpdmax    !: ???
+
+   !!* Phytoplankton limitation terms
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanono3   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatno3   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanonh4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatnh4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanopo4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatpo4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimphy    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdia    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimnfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimdfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimsi     !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbac    !: ??
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimbacl   !: ??
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicono3   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpiconh4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicopo4   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanodop   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicodop   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatdop   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xnanofer   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xpicofer   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xdiatfer   !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimpic    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   xlimpfe    !: ???
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvnuptk
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvpuptk
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:,:,:)  ::   fvduptk
+
+   ! Coefficient for iron limitation
+   REAL(wp) ::  xcoef1   = 0.00167  / 55.85
+   REAL(wp) ::  xcoef2   = 1.21E-5 * 14. / 55.85 / 7.625 * 0.5 * 1.5
+   REAL(wp) ::  xcoef3   = 1.15E-4 * 14. / 55.85 / 7.625 * 0.5 
+   !!----------------------------------------------------------------------
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
+   !! $Id$
+   !! Software governed by the CeCILL license (see ./LICENSE)
+   !!----------------------------------------------------------------------
+
+CONTAINS
+
+   SUBROUTINE p5z_lim( kt, knt )
+      !!---------------------------------------------------------------------
+      !!                     ***  ROUTINE p5z_lim  ***
+      !!
+      !! ** Purpose :   Compute the co-limitations by the various nutrients
+      !!              for the various phytoplankton species
+      !!
+      !! ** Method  : - ???
+      !!---------------------------------------------------------------------
+      !
+      INTEGER, INTENT(in)  :: kt, knt
+      !
+      INTEGER  ::   ji, jj, jk
+      REAL(wp) ::   zlim1, zlim2, zlim3, zlim4, zno3, zferlim
+      REAL(wp) ::   z1_trndia, z1_trnpic, z1_trnphy, ztem1, ztem2, zetot1
+      REAL(wp) ::   zratio, zration, zratiof, znutlim, zfalim
+      REAL(wp) ::   zconc1d, zconc1dnh4, zconc0n, zconc0nnh4, zconc0npo4, zconc0dpo4
+      REAL(wp) ::   zconc0p, zconc0pnh4, zconc0ppo4, zconcpfe, zconcnfe, zconcdfe
+      REAL(wp) ::   fanano, fananop, fananof, fadiat, fadiatp, fadiatf
+      REAL(wp) ::   fapico, fapicop, fapicof
+      REAL(wp) ::   zrpho, zrass, zcoef, zfuptk, zratchl
+      REAL(wp) ::   zfvn, zfvp, zfvf, zsizen, zsizep, zsized, znanochl, zpicochl, zdiatchl
+      REAL(wp) ::   zqfemn, zqfemp, zqfemd, zbactno3, zbactnh4
+      !!---------------------------------------------------------------------
+      !
+      IF( ln_timing )   CALL timing_start('p5z_lim')
+      !
+      zratchl = 6.0
+      !
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               ! 
+               ! Tuning of the iron concentration to a minimum level that is set to the detection limit
+               !-------------------------------------
+               zno3    = trb(ji,jj,jk,jpno3) / 40.e-6
+               zferlim = MAX( 3e-11 * zno3 * zno3, 5e-12 )
+               zferlim = MIN( zferlim, 7e-11 )
+               trb(ji,jj,jk,jpfer) = MAX( trb(ji,jj,jk,jpfer), zferlim )
+
+               ! Computation of the mean relative size of each community
+               ! -------------------------------------------------------
+               z1_trnphy   = 1. / ( trb(ji,jj,jk,jpphy) + rtrn )
+               z1_trnpic   = 1. / ( trb(ji,jj,jk,jppic) + rtrn )
+               z1_trndia   = 1. / ( trb(ji,jj,jk,jpdia) + rtrn )
+               znanochl = trb(ji,jj,jk,jpnch) * z1_trnphy
+               zpicochl = trb(ji,jj,jk,jppch) * z1_trnpic
+               zdiatchl = trb(ji,jj,jk,jpdch) * z1_trndia
+
+               ! Computation of a variable Ks for iron on diatoms taking into account
+               ! that increasing biomass is made of generally bigger cells
+               !------------------------------------------------
+               zsized            = sized(ji,jj,jk)**0.81
+               zconcdfe          = concdfer * zsized
+               zconc1d           = concdno3 * zsized
+               zconc1dnh4        = concdnh4 * zsized
+               zconc0dpo4        = concdpo4 * zsized
+
+               zsizep            = 1.
+               zconcpfe          = concpfer * zsizep
+               zconc0p           = concpno3 * zsizep
+               zconc0pnh4        = concpnh4 * zsizep
+               zconc0ppo4        = concppo4 * zsizep
+
+               zsizen            = 1.
+               zconcnfe          = concnfer * zsizen
+               zconc0n           = concnno3 * zsizen
+               zconc0nnh4        = concnnh4 * zsizen
+               zconc0npo4        = concnpo4 * zsizen
+
+               ! Allometric variations of the minimum and maximum quotas
+               ! From Talmy et al. (2014) and Maranon et al. (2013)
+               ! -------------------------------------------------------
+               xqnnmin(ji,jj,jk) = qnnmin
+               xqnnmax(ji,jj,jk) = qnnmax
+               xqndmin(ji,jj,jk) = qndmin * sized(ji,jj,jk)**(-0.27) 
+               xqndmax(ji,jj,jk) = qndmax
+               xqnpmin(ji,jj,jk) = qnpmin
+               xqnpmax(ji,jj,jk) = qnpmax
+
+               ! Computation of the optimal allocation parameters
+               ! Based on the different papers by Pahlow et al., and Smith et al.
+               ! -----------------------------------------------------------------
+               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc0nnh4,    &
+                 &         trb(ji,jj,jk,jpno3) / zconc0n)
+               fanano = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = trb(ji,jj,jk,jppo4) / zconc0npo4
+               fananop = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = biron(ji,jj,jk) / zconcnfe
+               fananof = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc0pnh4,    &
+                 &         trb(ji,jj,jk,jpno3) / zconc0p)
+               fapico = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = trb(ji,jj,jk,jppo4) / zconc0ppo4
+               fapicop = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = biron(ji,jj,jk) / zconcpfe
+               fapicof = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = MAX( trb(ji,jj,jk,jpnh4) / zconc1dnh4,    &
+                 &         trb(ji,jj,jk,jpno3) / zconc1d )
+               fadiat = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = trb(ji,jj,jk,jppo4) / zconc0dpo4
+               fadiatp = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               znutlim = biron(ji,jj,jk) / zconcdfe
+               fadiatf = MAX(0.01, MIN(0.99, 1. / ( SQRT(znutlim) + 1.) ) )
+               !
+               ! Michaelis-Menten Limitation term for nutrients Small bacteria
+               ! -------------------------------------------------------------
+               zbactnh4 = trb(ji,jj,jk,jpnh4) / ( concbnh4 + trb(ji,jj,jk,jpnh4) )
+               zbactno3 = trb(ji,jj,jk,jpno3) / ( concbno3 + trb(ji,jj,jk,jpno3) ) * (1. - zbactnh4)
+               !
+               zlim1    = zbactno3 + zbactnh4
+               zlim2    = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concbpo4)
+               zlim3    = biron(ji,jj,jk) / ( concbfe + biron(ji,jj,jk) )
+               zlim4    = trb(ji,jj,jk,jpdoc) / ( xkdoc   + trb(ji,jj,jk,jpdoc) )
+               xlimbacl(ji,jj,jk) = MIN( zlim1, zlim2, zlim3 )
+               xlimbac (ji,jj,jk) = xlimbacl(ji,jj,jk) * zlim4
+               !
+               ! Michaelis-Menten Limitation term for nutrients Small flagellates
+               ! -----------------------------------------------
+               zfalim = (1.-fanano) / fanano
+               xnanonh4(ji,jj,jk) = (1. - fanano) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc0nnh4 + trb(ji,jj,jk,jpnh4) )
+               xnanono3(ji,jj,jk) = (1. - fanano) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc0n + trb(ji,jj,jk,jpno3) )  &
+               &                    * (1. - xnanonh4(ji,jj,jk))
+               !
+               zfalim = (1.-fananop) / fananop
+               xnanopo4(ji,jj,jk) = (1. - fananop) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0npo4 )
+               xnanodop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )   &
+               &                    * ( 1.0 - xnanopo4(ji,jj,jk) )
+               xnanodop(ji,jj,jk) = 0.
+               !
+               zfalim = (1.-fananof) / fananof
+               xnanofer(ji,jj,jk) = (1. - fananof) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcnfe )
+               !
+               zratiof   = trb(ji,jj,jk,jpnfe) * z1_trnphy
+               zqfemn = xcoef1 * znanochl + xcoef2 + xcoef3 * xnanono3(ji,jj,jk)
+               !
+               zration = trb(ji,jj,jk,jpnph) * z1_trnphy
+               zration = MIN(xqnnmax(ji,jj,jk), MAX( 2. * xqnnmin(ji,jj,jk), zration ))
+               fvnuptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqnnmin(ji,jj,jk) / (zration + rtrn)  &
+               &                   * MAX(0., (1. - zratchl * znanochl / 12. ) )
+               !
+               zlim1    = max(0., (zration - 2. * xqnnmin(ji,jj,jk) )  &
+               &          / (xqnnmax(ji,jj,jk) - 2. * xqnnmin(ji,jj,jk) ) ) * xqnnmax(ji,jj,jk)  &
+               &          / (zration + rtrn)
+               zlim3    = MAX( 0.,( zratiof - zqfemn ) / qfnopt ) 
+               xlimnfe(ji,jj,jk) = MIN( 1., zlim3 )
+               xlimphy(ji,jj,jk) = MIN( 1., zlim1, zlim3 )
+               !
+               ! Michaelis-Menten Limitation term for nutrients picophytoplankton
+               ! ----------------------------------------------------------------
+               zfalim = (1.-fapico) / fapico 
+               xpiconh4(ji,jj,jk) = (1. - fapico) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc0pnh4 + trb(ji,jj,jk,jpnh4) )
+               xpicono3(ji,jj,jk) = (1. - fapico) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc0p + trb(ji,jj,jk,jpno3) )  &
+               &                    * (1. - xpiconh4(ji,jj,jk))
+               !
+               zfalim = (1.-fapicop) / fapicop 
+               xpicopo4(ji,jj,jk) = (1. - fapicop) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0ppo4 )
+               xpicodop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )   &
+               &                    * ( 1.0 - xpicopo4(ji,jj,jk) )
+               xpicodop(ji,jj,jk) = 0.
+               !
+               zfalim = (1.-fapicof) / fapicof
+               xpicofer(ji,jj,jk) = (1. - fapicof) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcpfe )
+               !
+               zratiof   = trb(ji,jj,jk,jppfe) * z1_trnpic
+               zqfemp = xcoef1 * zpicochl + xcoef2 + xcoef3 * xpicono3(ji,jj,jk)
+               !
+               zration   = trb(ji,jj,jk,jpnpi) * z1_trnpic
+               zration = MIN(xqnpmax(ji,jj,jk), MAX( 2. * xqnpmin(ji,jj,jk), zration ))
+               fvpuptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqnpmin(ji,jj,jk) / (zration + rtrn)  &
+               &                   * MAX(0., (1. - zratchl * zpicochl / 12. ) ) 
+               !
+               zlim1    = max(0., (zration - 2. * xqnpmin(ji,jj,jk) )  &
+               &          / (xqnpmax(ji,jj,jk) - 2. * xqnpmin(ji,jj,jk) ) ) * xqnpmax(ji,jj,jk)  &
+               &          / (zration + rtrn)
+               zlim3    = MAX( 0.,( zratiof - zqfemp ) / qfpopt )
+               xlimpfe(ji,jj,jk) = MIN( 1., zlim3 )
+               xlimpic(ji,jj,jk) = MIN( 1., zlim1, zlim3 )
+               !
+               !   Michaelis-Menten Limitation term for nutrients Diatoms
+               !   ------------------------------------------------------
+               zfalim = (1.-fadiat) / fadiat 
+               xdiatnh4(ji,jj,jk) = (1. - fadiat) * trb(ji,jj,jk,jpnh4) / ( zfalim * zconc1dnh4 + trb(ji,jj,jk,jpnh4) )
+               xdiatno3(ji,jj,jk) = (1. - fadiat) * trb(ji,jj,jk,jpno3) / ( zfalim * zconc1d + trb(ji,jj,jk,jpno3) )  &
+               &                    * (1. - xdiatnh4(ji,jj,jk))
+               !
+               zfalim = (1.-fadiatp) / fadiatp
+               xdiatpo4(ji,jj,jk) = (1. - fadiatp) * trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + zfalim * zconc0dpo4 )
+               xdiatdop(ji,jj,jk) = trb(ji,jj,jk,jpdop) / ( trb(ji,jj,jk,jpdop) + xkdoc )  &
+               &                    * ( 1.0 - xdiatpo4(ji,jj,jk) )
+               xdiatdop(ji,jj,jk) = 0.
+               !
+               zfalim = (1.-fadiatf) / fadiatf
+               xdiatfer(ji,jj,jk) = (1. - fadiatf) * biron(ji,jj,jk) / ( biron(ji,jj,jk) + zfalim * zconcdfe )
+               !
+               zratiof   = trb(ji,jj,jk,jpdfe) * z1_trndia
+               zqfemd = xcoef1 * zdiatchl + xcoef2 + xcoef3 * xdiatno3(ji,jj,jk)
+               !
+               zration   = trb(ji,jj,jk,jpndi) * z1_trndia
+               zration = MIN(xqndmax(ji,jj,jk), MAX( 2. * xqndmin(ji,jj,jk), zration ))
+               fvduptk(ji,jj,jk) = 1. / zpsiuptk * rno3 * 2. * xqndmin(ji,jj,jk) / (zration + rtrn)   &
+               &                   * MAX(0., (1. - zratchl * zdiatchl / 12. ) ) 
+               !
+               zlim1    = max(0., (zration - 2. * xqndmin(ji,jj,jk) )    &
+               &          / (xqndmax(ji,jj,jk) - 2. * xqndmin(ji,jj,jk) ) )   &
+               &          * xqndmax(ji,jj,jk) / (zration + rtrn)
+               zlim3    = trb(ji,jj,jk,jpsil) / ( trb(ji,jj,jk,jpsil) + xksi(ji,jj) )
+               zlim4    = MAX( 0., ( zratiof - zqfemd ) / qfdopt )
+               xlimdfe(ji,jj,jk) = MIN( 1., zlim4 )
+               xlimdia(ji,jj,jk) = MIN( 1., zlim1, zlim3, zlim4 )
+               xlimsi(ji,jj,jk)  = MIN( zlim1, zlim4 )
+            END DO
+         END DO
+      END DO
+      !
+      ! Compute the phosphorus quota values. It is based on Litchmann et al., 2004 and Daines et al, 2013.
+      ! The relative contribution of three fonctional pools are computed: light harvesting apparatus, 
+      ! nutrient uptake pool and assembly machinery. DNA is assumed to represent 1% of the dry mass of 
+      ! phytoplankton (see Daines et al., 2013). 
+      ! --------------------------------------------------------------------------------------------------
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               ! Size estimation of nanophytoplankton
+               ! ------------------------------------
+               zfvn = 2. * fvnuptk(ji,jj,jk)
+               sizen(ji,jj,jk) = MAX(1., MIN(xsizern, 1.0 / ( MAX(rtrn, zfvn) ) ) )
+
+               ! N/P ratio of nanophytoplankton
+               ! ------------------------------
+               zfuptk = 0.23 * zfvn
+               zrpho = 2.24 * trb(ji,jj,jk,jpnch) / ( trb(ji,jj,jk,jpnph) * rno3 * 15. + rtrn )
+               zrass = 1. - 0.2 - zrpho - zfuptk
+               xqpnmax(ji,jj,jk) = ( zfuptk + zrpho ) * 0.0128 * 16. + zrass * 1./ 7.2 * 16.
+               xqpnmax(ji,jj,jk) = xqpnmax(ji,jj,jk) * trb(ji,jj,jk,jpnph) / ( trb(ji,jj,jk,jpphy) + rtrn ) + 0.13
+               xqpnmin(ji,jj,jk) = 0.13 + 0.23 * 0.0128 * 16.
+
+               ! Size estimation of picophytoplankton
+               ! ------------------------------------
+               zfvn = 2. * fvpuptk(ji,jj,jk)
+               sizep(ji,jj,jk) = MAX(1., MIN(xsizerp, 1.0 / ( MAX(rtrn, zfvn) ) ) )
+
+               ! N/P ratio of picophytoplankton
+               ! ------------------------------
+               zfuptk = 0.35 * zfvn
+               zrpho = 2.24 * trb(ji,jj,jk,jppch) / ( trb(ji,jj,jk,jpnpi) * rno3 * 15. + rtrn )
+               zrass = 1. - 0.4 - zrpho - zfuptk
+               xqppmax(ji,jj,jk) =  (zrpho + zfuptk) * 0.0128 * 16. + zrass * 1./ 9. * 16.
+               xqppmax(ji,jj,jk) = xqppmax(ji,jj,jk) * trb(ji,jj,jk,jpnpi) / ( trb(ji,jj,jk,jppic) + rtrn ) + 0.13
+               xqppmin(ji,jj,jk) = 0.13
+
+               ! Size estimation of diatoms
+               ! --------------------------
+               zfvn = 2. * fvduptk(ji,jj,jk)
+               sized(ji,jj,jk) = MAX(1., MIN(xsizerd, 1.0 / ( MAX(rtrn, zfvn) ) ) )
+               zcoef = trb(ji,jj,jk,jpdia) - MIN(xsizedia, trb(ji,jj,jk,jpdia) )
+               sized(ji,jj,jk) = 1. + xsizerd * zcoef *1E6 / ( 1. + zcoef * 1E6 )
+
+               ! N/P ratio of diatoms
+               ! --------------------
+               zfuptk = 0.2 * zfvn
+               zrpho = 2.24 * trb(ji,jj,jk,jpdch) / ( trb(ji,jj,jk,jpndi) * rno3 * 15. + rtrn )
+               zrass = 1. - 0.2 - zrpho - zfuptk
+               xqpdmax(ji,jj,jk) = ( zfuptk + zrpho ) * 0.0128 * 16. + zrass * 1./ 7.2 * 16.
+               xqpdmax(ji,jj,jk) = xqpdmax(ji,jj,jk) * trb(ji,jj,jk,jpndi) / ( trb(ji,jj,jk,jpdia) + rtrn ) + 0.13
+               xqpdmin(ji,jj,jk) = 0.13 + 0.2 * 0.0128 * 16.
+
+            END DO
+         END DO
+      END DO
+
+      ! Compute the fraction of nanophytoplankton that is made of calcifiers
+      ! --------------------------------------------------------------------
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               zlim1 =  trb(ji,jj,jk,jpnh4) / ( trb(ji,jj,jk,jpnh4) + concnnh4 ) + trb(ji,jj,jk,jpno3)    &
+               &        / ( trb(ji,jj,jk,jpno3) + concnno3 ) * ( 1.0 - trb(ji,jj,jk,jpnh4)   &
+               &        / ( trb(ji,jj,jk,jpnh4) + concnnh4 ) )
+               zlim2  = trb(ji,jj,jk,jppo4) / ( trb(ji,jj,jk,jppo4) + concnpo4 )
+               zlim3  = trb(ji,jj,jk,jpfer) / ( trb(ji,jj,jk,jpfer) +  5.E-11 ) 
+               ztem1  = MAX( 0., tsn(ji,jj,jk,jp_tem) )
+               ztem2  = tsn(ji,jj,jk,jp_tem) - 10.
+               zetot1 = MAX( 0., etot(ji,jj,jk) - 1.) / ( 4. + etot(ji,jj,jk) ) * 20. / ( 20. + etot(ji,jj,jk) ) 
+
+!               xfracal(ji,jj,jk) = caco3r * MIN( zlim1, zlim2, zlim3 )                  &
+               xfracal(ji,jj,jk) = caco3r                 &
+               &                   * ztem1 / ( 1. + ztem1 ) * MAX( 1., trb(ji,jj,jk,jpphy)*1E6 )   &
+                  &                * ( 1. + EXP(-ztem2 * ztem2 / 25. ) )         &
+                  &                * zetot1 * MIN( 1., 50. / ( hmld(ji,jj) + rtrn ) )
+               xfracal(ji,jj,jk) = MAX( 0.02, MIN( 0.8 , xfracal(ji,jj,jk) ) )
+            END DO
+         END DO
+      END DO
+      !
+      DO jk = 1, jpkm1
+         DO jj = 1, jpj
+            DO ji = 1, jpi
+               ! denitrification factor computed from O2 levels
+               nitrfac(ji,jj,jk) = MAX(  0.e0, 0.4 * ( 6.e-6  - trb(ji,jj,jk,jpoxy) )    &
+                  &                                / ( oxymin + trb(ji,jj,jk,jpoxy) )  )
+               nitrfac(ji,jj,jk) = MIN( 1., nitrfac(ji,jj,jk) )
+            END DO
+         END DO
+      END DO
+      !
+      IF( lk_iomput .AND. knt == nrdttrc ) THEN        ! save output diagnostics
+        IF( iom_use( "xfracal" ) ) CALL iom_put( "xfracal", xfracal(:,:,:) * tmask(:,:,:) )  ! euphotic layer deptht
+        IF( iom_use( "LNnut"   ) ) CALL iom_put( "LNnut"  , xlimphy(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
+        IF( iom_use( "LPnut"   ) ) CALL iom_put( "LPnut"  , xlimpic(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
+        IF( iom_use( "LDnut"   ) ) CALL iom_put( "LDnut"  , xlimdia(:,:,:) * tmask(:,:,:) )  ! Nutrient limitation term
+        IF( iom_use( "LNFe"    ) ) CALL iom_put( "LNFe"   , xlimnfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "LPFe"    ) ) CALL iom_put( "LPFe"   , xlimpfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "LDFe"    ) ) CALL iom_put( "LDFe"   , xlimdfe(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "SIZEN"   ) ) CALL iom_put( "SIZEN"  , sizen(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "SIZEP"   ) ) CALL iom_put( "SIZEP"  , sizep(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+        IF( iom_use( "SIZED"   ) ) CALL iom_put( "SIZED"  , sized(:,:,:) * tmask(:,:,:) )  ! Iron limitation term
+      ENDIF
+      !
+      IF( ln_timing )  CALL timing_stop('p5z_lim')
+      !
+   END SUBROUTINE p5z_lim
+
+
+   SUBROUTINE p5z_lim_init
+      !!----------------------------------------------------------------------
+      !!                  ***  ROUTINE p5z_lim_init  ***
+      !!
+      !! ** Purpose :   Initialization of nutrient limitation parameters
+      !!
+      !! ** Method  :   Read the nampislim and nampisquota namelists and check
+      !!      the parameters called at the first timestep (nittrc000)
+      !!
+      !! ** input   :   Namelist nampislim
+      !!
+      !!----------------------------------------------------------------------
+      INTEGER :: ios                 ! Local integer output status for namelist read
+      !!
+      NAMELIST/namp5zlim/ concnno3, concpno3, concdno3, concnnh4, concpnh4, concdnh4,  &
+         &                concnfer, concpfer, concdfer, concbfe, concnpo4, concppo4,   &
+         &                concdpo4, concbno3, concbnh4, concbpo4, xsizedia, xsizepic,  &
+         &                xsizephy, xsizern, xsizerp, xsizerd, xksi1, xksi2, xkdoc,    &
+         &                caco3r, oxymin
+         !
+      NAMELIST/namp5zquota/ qnnmin, qnnmax, qpnmin, qpnmax, qnpmin, qnpmax, qppmin,      &
+         &                  qppmax, qndmin, qndmax, qpdmin, qpdmax, qfnmax, qfpmax, qfdmax,  &
+         &                  qfnopt, qfpopt, qfdopt
+      !!----------------------------------------------------------------------
+      !
+      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
+      READ  ( numnatp_ref, namp5zlim, IOSTAT = ios, ERR = 901)
+901   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nampislim in reference namelist', lwp )
+      !
+      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
+      READ  ( numnatp_cfg, namp5zlim, IOSTAT = ios, ERR = 902 )
+902   IF( ios >  0 ) CALL ctl_nam ( ios , 'nampislim in configuration namelist', lwp )
+      IF(lwm) WRITE ( numonp, namp5zlim )
+      !
+      IF(lwp) THEN                         ! control print
+         WRITE(numout,*) ' '
+         WRITE(numout,*) ' Namelist parameters for nutrient limitations, namp5zlim'
+         WRITE(numout,*) ' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
+         WRITE(numout,*) '    mean rainratio                           caco3r    = ', caco3r
+         WRITE(numout,*) '    NO3 half saturation of nanophyto         concnno3  = ', concnno3
+         WRITE(numout,*) '    NO3 half saturation of picophyto         concpno3  = ', concpno3
+         WRITE(numout,*) '    NO3 half saturation of diatoms           concdno3  = ', concdno3
+         WRITE(numout,*) '    NH4 half saturation for phyto            concnnh4  = ', concnnh4
+         WRITE(numout,*) '    NH4 half saturation for pico             concpnh4  = ', concpnh4
+         WRITE(numout,*) '    NH4 half saturation for diatoms          concdnh4  = ', concdnh4
+         WRITE(numout,*) '    PO4 half saturation for phyto            concnpo4  = ', concnpo4
+         WRITE(numout,*) '    PO4 half saturation for pico             concppo4  = ', concppo4
+         WRITE(numout,*) '    PO4 half saturation for diatoms          concdpo4  = ', concdpo4
+         WRITE(numout,*) '    half saturation constant for Si uptake   xksi1     = ', xksi1
+         WRITE(numout,*) '    half saturation constant for Si/C        xksi2     = ', xksi2
+         WRITE(numout,*) '    half-sat. of DOC remineralization        xkdoc     = ', xkdoc
+         WRITE(numout,*) '    Iron half saturation for nanophyto       concnfer  = ', concnfer
+         WRITE(numout,*) '    Iron half saturation for picophyto       concpfer  = ', concpfer
+         WRITE(numout,*) '    Iron half saturation for diatoms         concdfer  = ', concdfer
+         WRITE(numout,*) '    size ratio for nanophytoplankton         xsizern   = ', xsizern
+         WRITE(numout,*) '    size ratio for picophytoplankton         xsizerp   = ', xsizerp
+         WRITE(numout,*) '    size ratio for diatoms                   xsizerd   = ', xsizerd
+         WRITE(numout,*) '    NO3 half saturation of bacteria          concbno3  = ', concbno3
+         WRITE(numout,*) '    NH4 half saturation for bacteria         concbnh4  = ', concbnh4
+         WRITE(numout,*) '    Minimum size criteria for diatoms        xsizedia  = ', xsizedia
+         WRITE(numout,*) '    Minimum size criteria for picophyto      xsizepic  = ', xsizepic
+         WRITE(numout,*) '    Minimum size criteria for nanophyto      xsizephy  = ', xsizephy
+         WRITE(numout,*) '    Fe half saturation for bacteria          concbfe   = ', concbfe
+         WRITE(numout,*) '    halk saturation constant for anoxia       oxymin   =' , oxymin
+      ENDIF
+
+      REWIND( numnatp_ref )              ! Namelist nampislim in reference namelist : Pisces nutrient limitation parameters
+      READ  ( numnatp_ref, namp5zquota, IOSTAT = ios, ERR = 903)
+903   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nampisquota in reference namelist', lwp )
+      !
+      REWIND( numnatp_cfg )              ! Namelist nampislim in configuration namelist : Pisces nutrient limitation parameters 
+      READ  ( numnatp_cfg, namp5zquota, IOSTAT = ios, ERR = 904 )
+904   IF( ios >  0 ) CALL ctl_nam ( ios , 'nampisquota in configuration namelist', lwp )
+      IF(lwm) WRITE ( numonp, namp5zquota )
+      !
+      IF(lwp) THEN                         ! control print
+         WRITE(numout,*) ' '
+         WRITE(numout,*) ' Namelist parameters for nutrient limitations, namp5zquota'
+         WRITE(numout,*) ' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
+         WRITE(numout,*) '    optimal Fe quota for nano.               qfnopt    = ', qfnopt
+         WRITE(numout,*) '    optimal Fe quota for pico.               qfpopt    = ', qfpopt
+         WRITE(numout,*) '    Optimal Fe quota for diatoms             qfdopt    = ', qfdopt
+         WRITE(numout,*) '    Minimal N quota for nano                 qnnmin    = ', qnnmin
+         WRITE(numout,*) '    Maximal N quota for nano                 qnnmax    = ', qnnmax
+         WRITE(numout,*) '    Minimal P quota for nano                 qpnmin    = ', qpnmin
+         WRITE(numout,*) '    Maximal P quota for nano                 qpnmax    = ', qpnmax
+         WRITE(numout,*) '    Minimal N quota for pico                 qnpmin    = ', qnpmin
+         WRITE(numout,*) '    Maximal N quota for pico                 qnpmax    = ', qnpmax
+         WRITE(numout,*) '    Minimal P quota for pico                 qppmin    = ', qppmin
+         WRITE(numout,*) '    Maximal P quota for pico                 qppmax    = ', qppmax
+         WRITE(numout,*) '    Minimal N quota for diatoms              qndmin    = ', qndmin
+         WRITE(numout,*) '    Maximal N quota for diatoms              qndmax    = ', qndmax
+         WRITE(numout,*) '    Minimal P quota for diatoms              qpdmin    = ', qpdmin
+         WRITE(numout,*) '    Maximal P quota for diatoms              qpdmax    = ', qpdmax
+         WRITE(numout,*) '    Maximal Fe quota for nanophyto.          qfnmax    = ', qfnmax
+         WRITE(numout,*) '    Maximal Fe quota for picophyto.          qfpmax    = ', qfpmax
+         WRITE(numout,*) '    Maximal Fe quota for diatoms             qfdmax    = ', qfdmax
+      ENDIF
+      !
+      zpsino3 = 2.3 * rno3
+      zpsinh4 = 1.8 * rno3
+      zpsiuptk = 2.3 * rno3
+      !
+      nitrfac (:,:,:) = 0._wp
+      !
+   END SUBROUTINE p5z_lim_init
+
+
+   INTEGER FUNCTION p5z_lim_alloc()
+      !!----------------------------------------------------------------------
+      !!                     ***  ROUTINE p5z_lim_alloc  ***
+      !!----------------------------------------------------------------------
+      USE lib_mpp , ONLY: ctl_warn
+      INTEGER ::   ierr(2)        ! Local variables
+      !!----------------------------------------------------------------------
+      ierr(:) = 0
+      !
+      !*  Biological arrays for phytoplankton growth
+      ALLOCATE( xpicono3(jpi,jpj,jpk), xpiconh4(jpi,jpj,jpk),       &
+         &      xpicopo4(jpi,jpj,jpk), xpicodop(jpi,jpj,jpk),       &
+         &      xnanodop(jpi,jpj,jpk), xdiatdop(jpi,jpj,jpk),       &
+         &      xnanono3(jpi,jpj,jpk), xdiatno3(jpi,jpj,jpk),       &
+         &      xnanonh4(jpi,jpj,jpk), xdiatnh4(jpi,jpj,jpk),       &
+         &      xnanopo4(jpi,jpj,jpk), xdiatpo4(jpi,jpj,jpk),       &
+         &      xlimphy (jpi,jpj,jpk), xlimdia (jpi,jpj,jpk),       &
+         &      xlimnfe (jpi,jpj,jpk), xlimdfe (jpi,jpj,jpk),       &
+         &      xlimbac (jpi,jpj,jpk), xlimbacl(jpi,jpj,jpk),       &
+         &      xnanofer(jpi,jpj,jpk), xdiatfer(jpi,jpj,jpk),       &
+         &      xpicofer(jpi,jpj,jpk), xlimpfe (jpi,jpj,jpk),       &
+         &      fvnuptk (jpi,jpj,jpk), fvduptk (jpi,jpj,jpk),       &
+         &      fvpuptk (jpi,jpj,jpk), xlimpic (jpi,jpj,jpk),       &
+         &      xlimsi  (jpi,jpj,jpk), STAT=ierr(1) )
+         !
+      !*  Minimum/maximum quotas of phytoplankton
+      ALLOCATE( xqnnmin (jpi,jpj,jpk), xqnnmax(jpi,jpj,jpk),       &
+         &      xqpnmin (jpi,jpj,jpk), xqpnmax(jpi,jpj,jpk),       &
+         &      xqnpmin (jpi,jpj,jpk), xqnpmax(jpi,jpj,jpk),       &
+         &      xqppmin (jpi,jpj,jpk), xqppmax(jpi,jpj,jpk),       &
+         &      xqndmin (jpi,jpj,jpk), xqndmax(jpi,jpj,jpk),       &
+         &      xqpdmin (jpi,jpj,jpk), xqpdmax(jpi,jpj,jpk),     STAT=ierr(2) )
+         !
+      p5z_lim_alloc = MAXVAL( ierr )
+      !
+      IF( p5z_lim_alloc /= 0 ) CALL ctl_warn('p5z_lim_alloc : failed to allocate arrays.')
+      !
+   END FUNCTION p5z_lim_alloc
+   !!======================================================================
+END MODULE p5zlim
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmeso.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmeso.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmeso.F90	(revision 10321)
@@ -51,7 +51,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmicro.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmicro.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmicro.F90	(revision 10321)
@@ -15,5 +15,5 @@
    USE trc             !  passive tracers common variables 
    USE sms_pisces      !  PISCES Source Minus Sink variables
-   USE p5zice          !  Phytoplankton limitation terms
+   USE p5zlim          !  Phytoplankton limitation terms
    USE iom             !  I/O manager
    USE prtctl_trc      !  print control for debugging
@@ -51,7 +51,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmort.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmort.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zmort.F90	(revision 10321)
@@ -14,5 +14,5 @@
    USE trc             !  passive tracers common variables 
    USE sms_pisces      !  PISCES Source Minus Sink variables
-   USE p5zice          !  Phytoplankton limitation terms
+   USE p5zlim          !  Phytoplankton limitation terms
    USE prtctl_trc      !  print control for debugging
 
@@ -33,7 +33,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zprod.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zprod.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/P4Z/p5zprod.F90	(revision 10321)
@@ -16,5 +16,5 @@
    USE trc             !  passive tracers common variables 
    USE sms_pisces      !  PISCES Source Minus Sink variables
-   USE p5zice          !  Co-limitations of differents nutrients
+   USE p5zlim          !  Co-limitations of differents nutrients
    USE prtctl_trc      !  print control for debugging
    USE iom             !  I/O manager
@@ -53,7 +53,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/oce_sed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/oce_sed.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/oce_sed.F90	(revision 10321)
@@ -0,0 +1,60 @@
+MODULE oce_sed
+   !!======================================================================
+   !!                        ***  sed  ***
+   !! Sediment :   set sediment global variables
+   !!======================================================================
+   !! History :
+   !!        !  06-12  (C. Ethe)  Orignal
+   !!----------------------------------------------------------------------
+   USE par_sed
+   USE timing
+   USE par_trc
+
+   USE dom_oce , ONLY :   nidom     =>   nidom          !:
+   USE dom_oce , ONLY :   glamt     =>   glamt          !: longitude of t-point (degre)
+   USE dom_oce , ONLY :   gphit     =>   gphit          !: latitude  of t-point (degre)
+   USE dom_oce , ONLY :   e3t_n     =>   e3t_n          !: latitude  of t-point (degre)
+   USE dom_oce , ONLY :   e3t_1d    =>   e3t_1d         !: reference depth of t-points (m)
+   USE dom_oce , ONLY :   gdepw_0   =>   gdepw_0        !: reference depth of t-points (m)
+   USE dom_oce , ONLY :   mbkt      =>   mbkt           !: vertical index of the bottom last T- ocean level
+   USE dom_oce , ONLY :   tmask     =>   tmask          !: land/ocean mask at t-points
+   USE dom_oce , ONLY :   rdt       =>   rdt            !: time step for the dynamics
+   USE dom_oce , ONLY :   nyear     =>   nyear          !: Current year
+   USE dom_oce , ONLY :   nmonth    =>   nmonth         !: Current month
+   USE dom_oce , ONLY :   nday      =>   nday           !: Current day
+   USE dom_oce , ONLY :   ndastp    =>   ndastp         !: time step date in year/month/day aammjj
+   USE dom_oce , ONLY :   nday_year =>   nday_year      !: curent day counted from jan 1st of the current year
+   USE dom_oce , ONLY :   adatrj    =>   adatrj         !: number of elapsed days since the begining of the run
+   USE trc     , ONLY :  nittrc000  =>   nittrc000
+   !                                !: it is the accumulated duration of previous runs
+   !                                !: that may have been run with different time steps.
+
+   USE oce     , ONLY :  tsn        =>   tsn             !: pot. temperature (celsius) and salinity (psu)
+   USE trc     , ONLY :  trb        =>   trb             !: pot. temperature (celsius) and salinity (psu)
+
+   USE sms_pisces, ONLY : wsbio4    =>   wsbio4          !: sinking flux for POC
+   USE sms_pisces, ONLY : wsbio3    =>   wsbio3          !: sinking flux for GOC
+   USE sms_pisces, ONLY : wscal     =>   wscal           !: sinking flux for calcite
+   USE sms_pisces, ONLY : wsbio2    =>   wsbio2           !: sinking flux for calcite
+   USE sms_pisces, ONLY : wsbio     =>   wsbio           !: sinking flux for calcite
+   USE p4zche, ONLY     : akb3      =>   akb3            !: Chemical constants  
+   USE sms_pisces, ONLY : ak13      =>   ak13            !: Chemical constants  
+   USE sms_pisces, ONLY : ak23      =>   ak23            !: Chemical constants  
+   USE p4zche, ONLY     : akw3      =>   akw3            !: Chemical constants  
+   USE sms_pisces, ONLY : aksp      =>   aksp            !: Chemical constants  
+   USE p4zche, ONLY     : borat     =>   borat           !: Chemical constants ( borat ) 
+   USE p4zche, ONLY     : ak1p3     =>   ak1p3           !: Chemical constants  
+   USE p4zche, ONLY     : ak2p3     =>   ak2p3           !: Chemical constants  
+   USE p4zche, ONLY     : ak3p3     =>   ak3p3           !: Chemical constants  
+   USE p4zche, ONLY     : aksi3     =>   aksi3           !: Chemical constants  
+   USE p4zche, ONLY     : aks3      =>   aks3            !: Chemical constants  
+   USE p4zche, ONLY     : akf3      =>   akf3            !: Chemical constants  
+   USE p4zche, ONLY     : fluorid   =>   fluorid         !: Chemical constants  
+   USE p4zche, ONLY     : sulfat    =>   sulfat          !: Chemical constants  
+   USE p4zche, ONLY     : sio3eq    =>   sio3eq          !: Chemical constants  
+   USE p4zsbc, ONLY     : dust      =>   dust
+   USE trc       , ONLY : r2dttrc   =>   r2dttrc
+
+END MODULE oce_sed
+
+
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/par_sed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/par_sed.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/par_sed.F90	(revision 10321)
@@ -7,8 +7,5 @@
    !!        !  06-12  (C. Ethe)  Orignal
    !!----------------------------------------------------------------------
-#if defined key_sed
-   !!----------------------------------------------------------------------
-   !!   'key_sed'                                                  Sediment 
-   !!----------------------------------------------------------------------
+   !! $Id$
 
    !! Domain characteristics
@@ -19,25 +16,22 @@
       jpim1    =>   jpim1 ,  & !: jpi - 1
       jpjm1    =>   jpjm1 ,  & !: jpj - 1
-      jpij     =>   jpij       !: jpi x jpj
-      jp_tem   =>   jp_tem     !: indice of temperature
+      jpij     =>   jpij  ,  & !: jpi x jpj
+      jp_tem   =>   jp_tem,  & !: indice of temperature
       jp_sal   =>   jp_sal     !: indice of salintity
 
-#if ! defined key_sed_off
-   USE par_pisces
-#endif
-
-   INTEGER, PARAMETER :: jpdta = 12
-
+   INTEGER, PARAMETER :: jpdta = 17
 
    ! Vertical sediment geometry
-   INTEGER, PARAMETER :: &
-      jpksed   = 11         ,   & !: number of sediment layers
-      jpksedm1 = jpksed - 1 
-      
+   INTEGER, PUBLIC   ::      &
+      jpksed   = 11 ,        &
+      jpksedm1 = 10
+
    ! sediment tracer species
-   INTEGER, PARAMETER :: &
-      jpsol = 4,         &  !: number of solid component
-      jpwat = 7,         &   !: number of pore water component
-      jpwatp1 = jpwat + 1
+   INTEGER, PARAMETER ::    &
+      jpsol =  8,           &  !: number of solid component
+      jpwat = 10,           &   !: number of pore water component
+      jpwatp1 = jpwat +1,   &
+      jpsol1 = jpsol - 1
+
    
    ! pore water components       
@@ -49,5 +43,8 @@
       jwpo4  = 5,        & !: phosphate
       jwalk  = 6,        & !: alkalinity
-      jwc13  = 7           !: dissolved inorganic carbon 13
+      jwnh4  = 7,        & !: Ammonium
+      jwh2s  = 8,        & !: Sulfate
+      jwso4  = 9,        & !: H2S
+      jwfe2  = 10          !: Fe2+
 
    ! solid components       
@@ -56,16 +53,14 @@
       jsclay  = 2,        & !: clay
       jspoc   = 3,        & !: organic carbon
-      jscal   = 4           !: calcite
+      jscal   = 4,        & !: calcite
+      jspos   = 5,        & !: semi-ref POC
+      jspor   = 6,        & !: refractory POC
+      jsfeo   = 7,        & !: iron hydroxides
+      jsfes   = 8           !: FeS
 
    INTEGER, PARAMETER ::  &
       jptrased   = jpsol + jpwat , &
-      jpdia3dsed = 3          , &
-      jpdia2dsed = 7
-#endif
+      jpdia3dsed = 2             , &
+      jpdia2dsed = 12
 
-   !!----------------------------------------------------------------------
-   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
-   !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
-   !!======================================================================
 END MODULE par_sed
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed.F90	(revision 10321)
@@ -7,79 +7,55 @@
    !!        !  06-12  (C. Ethe)  Orignal
    !!----------------------------------------------------------------------
-#if defined key_sed
-   !!----------------------------------------------------------------------
-   !!   'key_sed'                                                  Sediment 
-   !!----------------------------------------------------------------------
    USE par_sed
+   USE oce_sed
    USE in_out_manager
+
 
    IMPLICIT NONE
    PUBLIC
 
-   PUBLIC sed_alloc   
-
-   USE dom_oce , ONLY :   nidom     =>   nidom          !:
-   USE dom_oce , ONLY :   glamt     =>   glamt          !: longitude of t-point (degre)
-   USE dom_oce , ONLY :   gphit     =>   gphit          !: latitude  of t-point (degre)
-   USE dom_oce , ONLY :   e3t_1d    =>   e3t_1d         !: reference depth of t-points (m)
-   USE dom_oce , ONLY :   mbkt      =>   mbkt           !: vertical index of the bottom last T- ocean level
-   USE dom_oce , ONLY :   tmask     =>   tmask          !: land/ocean mask at t-points
-   USE dom_oce , ONLY :   rdt       =>   rdt            !: time step for the dynamics
-   USE dom_oce , ONLY :   nyear     =>   nyear          !: Current year
-   USE dom_oce , ONLY :   nmonth    =>   nmonth         !: Current month
-   USE dom_oce , ONLY :   nday      =>   nday           !: Current day
-   USE dom_oce , ONLY :   ndastp    =>   ndastp         !: time step date in year/month/day aammjj
-   USE dom_oce , ONLY :   nday_year =>   nday_year      !: curent day counted from jan 1st of the current year
-   USE dom_oce , ONLY :   adatrj    =>   adatrj         !: number of elapsed days since the begining of the run
-   !                                !: it is the accumulated duration of previous runs
-   !                                !: that may have been run with different time steps.
-
-#if ! defined key_sed_off
-
-   USE oce     , ONLY :  tsn        =>   tsn             !: pot. temperature (celsius) and salinity (psu)
-
-   USE trc     , ONLY :  trn        =>   trc             !: tracer 
-   USE trc     , ONLY :  nwritetrc  =>   nwritetrc       !: outputs frequency of tracer model
-
-   USE p4zsink , ONLY :  sinking    =>   sinking         !: sinking flux for POC
-   USE p4zsink , ONLY :  sinking2   =>   sinking2        !: sinking flux for GOC
-   USE p4zsink , ONLY :  sinkcal    =>   sinkcal         !: sinking flux for calcite
-   USE p4zsink , ONLY :  sinksil    =>   sinksil         !: sinking flux for opal ( dsi )
-
-   USE sms_pisces, ONLY : akb3      =>   akb3            !: Chemical constants  
-   USE sms_pisces, ONLY : ak13      =>   ak13            !: Chemical constants  
-   USE sms_pisces, ONLY : ak23      =>   ak23            !: Chemical constants  
-   USE sms_pisces, ONLY : akw3      =>   akw3            !: Chemical constants  
-   USE sms_pisces, ONLY : aksp      =>   aksp            !: Chemical constants  
-   USE sms_pisces, ONLY : borat     =>   borat           !: Chemical constants ( borat ) 
-
-#endif   
-
+   PUBLIC sed_alloc
 
    !! Namelist
-   REAL(wp), PUBLIC, DIMENSION(5) ::  reac                !: reactivity rc in  [l.mol-1.s-1]
    REAL(wp), PUBLIC               ::  reac_sil            !: reactivity of silicate in  [l.mol-1.s-1]
    REAL(wp), PUBLIC               ::  reac_clay           !: reactivity of clay in  [l.mol-1.s-1]
-   REAL(wp), PUBLIC               ::  reac_poc            !: reactivity of poc in  [l.mol-1.s-1]
-   REAL(wp), PUBLIC               ::  reac_no3            !: reactivity of no3 in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_ligc           !: reactivity of Ligands [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_pocl           !: reactivity of pocl in  [s-1]
+   REAL(wp), PUBLIC               ::  reac_pocs           !: reactivity of pocs in  [s-1]
+   REAL(wp), PUBLIC               ::  reac_pocr           !: reactivity of pocr in  [s-1]
+   REAL(wp), PUBLIC               ::  reac_nh4            !: reactivity of NH4 in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_h2s            !: reactivity of ODU in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_fe2            !: reactivity of Fe2+ in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_feh2s          !: reactivity of Fe2+ in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_fes            !: reactivity of Fe with H2S in  [l.mol-1.s-1]
+   REAL(wp), PUBLIC               ::  reac_feso           !: reactivity of FeS with O2 in  [l.mol-1.s-1]
    REAL(wp), PUBLIC               ::  reac_cal            !: reactivity of cal in  [l.mol-1.s-1]
-   REAL(wp), PUBLIC               ::  sat_sil             !: saturation concentration for silicate in [mol.l-1]
-   REAL(wp), PUBLIC               ::  sat_clay            !: saturation concentration for clay in [mol.l-1]
+   REAL(wp), PUBLIC               ::  adsnh4              !: adsorption coefficient of NH4
+   REAL(wp), PUBLIC               ::  ratligc             !: C/L ratio in POC
    REAL(wp), PUBLIC               ::  so2ut 
    REAL(wp), PUBLIC               ::  srno3 
    REAL(wp), PUBLIC               ::  spo4r 
    REAL(wp), PUBLIC               ::  srDnit 
-   REAL(wp), PUBLIC               ::  sthro2              !: threshold O2 concen. in [mol.l-1]
-   REAL(wp), PUBLIC               ::  pdb = 0.0112372     !: 13C/12C in PD Belemnite
-   REAL(wp), PUBLIC               ::  rc13P  = 0.980      !: 13C/12C in POC = rc13P*PDB
-   REAL(wp), PUBLIC               ::  rc13Ca = 1.001      !: 13C/12C in CaCO3 = rc13Ca*PDB
    REAL(wp), PUBLIC               ::  dtsed               !: sedimentation time step
-   REAL(wp), PUBLIC               ::  db                  !: bioturb coefficient in [cm2.s-1]
-
+   REAL(wp), PUBLIC               ::  dtsed2              !: sedimentation time step
    INTEGER , PUBLIC               ::  nitsed000
    INTEGER , PUBLIC               ::  nitsedend
-   INTEGER , PUBLIC               ::  nwrised
-   INTEGER , PUBLIC               ::  nfreq
-   REAL(wp), PUBLIC               ::  dens                !: density of solid material
+   INTEGER, PUBLIC                ::  nrseddt
+   REAL    , PUBLIC               ::  sedmask
+   REAL(wp), PUBLIC               ::  denssol                !: density of solid material
+   INTEGER , PUBLIC               ::  numrsr, numrsw   !: logical unit for sed restart (read and write)
+   LOGICAL , PUBLIC               ::  lrst_sed       !: logical to control the trc restart write
+   LOGICAL , PUBLIC               ::  ln_rst_sed  = .TRUE.     !: initialisation from a restart file or not
+   LOGICAL , PUBLIC               ::  ln_btbz     = .FALSE.    !: Depth variation of the bioturbation coefficient
+   LOGICAL , PUBLIC               ::  ln_irrig    = .FALSE.    !: iActivation of the bioirrigation
+   LOGICAL , PUBLIC               ::  ln_sed_2way = .FALSE.    !: 2 way coupling with PISCES
+   LOGICAL , PUBLIC               ::  ln_sediment_offline = .FALSE. !: Offline mode for sediment module
+   INTEGER             , PUBLIC   ::  nn_rstsed      !: control of the time step ( 0 or 1 ) for pass. tr.
+   INTEGER , PUBLIC               ::  nn_dtsed = 1   !: frequency of step on passive tracers
+   CHARACTER(len = 80) , PUBLIC   ::  cn_sedrst_in   !: suffix of pass. tracer restart name (input)
+   CHARACTER(len = 256), PUBLIC   ::  cn_sedrst_indir  !: restart input directory
+   CHARACTER(len = 80) , PUBLIC   ::  cn_sedrst_out  !: suffix of pass. tracer restart name (output)
+   CHARACTER(len = 256), PUBLIC   ::  cn_sedrst_outdir  !: restart output directory
+
    !
    REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  pwcp       !: pore water sediment data at given time-step
@@ -87,4 +63,6 @@
    REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  solcp      !: solid sediment data at given time-step
    REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  solcp0     !: solid sediment data at initial time
+   REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  trc_dta
+   REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  diff
 
    !! * Shared module variables
@@ -102,5 +80,8 @@
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  press      !: pressure
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  raintg     !: total massic flux rained in each cell (sum of sol. comp.)
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  fecratio   !: Fe/C ratio in falling particles to the sediments
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  dzdep      !: total thickness of solid material rained [cm] in each cell
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  zkbot      !: total thickness of solid material rained [cm] in each cell
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  wacc       !: total thickness of solid material rained [cm] in each cell
    !
    REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  hipor      !: [h+] in mol/kg*densSW 
@@ -127,4 +108,9 @@
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  aksis 
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  aksps 
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  sieqs
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  aks3s
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  akf3s
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  sulfats
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  fluorids
 
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  mol_wgt    !: molecular weight of solid sediment data
@@ -133,17 +119,17 @@
    !! Geometry
    INTEGER , PUBLIC, SAVE                          ::  jpoce, indoce !: Ocean points ( number/indices )
-   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  iarroce       !: Computation of 1D array of sediments points
+   INTEGER , PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  iarroce       !: Computation of 1D array of sediments points
    REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  epkbot        !: ocean bottom layer thickness
+   REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  gdepbot       !: Depth of the sediment
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  dzkbot        !: ocean bottom layer thickness in meters
-   REAL(wp), PUBLIC, DIMENSION(:,:,:), ALLOCATABLE ::  tmasksed      !: sediment mask
-   REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  sbathy        !: bathymetry
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  dz            !: sediment layers thickness
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  por           !: porosity profile     
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  por1          !: 1-por 
-   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  profsed       !: depth of middle of each layer
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  volw          !: volume of pore water cell fraction
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  vols          !: volume of solid cell fraction
-   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  diff          !: diffusion ceofficient
+   REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  db            !: bioturbation ceofficient
+   REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE ::  irrig        !: bioturbation ceofficient
    REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  rdtsed        !:  sediment model time-step
+   REAL(wp), PUBLIC, DIMENSION(:,:  ), ALLOCATABLE :: sedligand
    REAL(wp)  ::   dens               !: density of solid material
    !! Inputs / Outputs
@@ -171,12 +157,11 @@
       !!-------------------------------------------------------------------
       !
-      ALLOCATE( trc_dta(jpi,jpj,jdta)                                     ,   &
-         &      epkbot(jpi,jpj), sbathy(jpi,jpj)                          ,   &
-         &      tmasksed(jpi,jpj,jpksed)                                  ,   &
-         &      dz(jpksed)  , por(jpksed) , por1(jpksed), profsed(jpksed) ,   &
-         &      volw(jpksed), vols(jpksed), diff(jpksed), rdtsed(jpksed)  ,   &
+      ALLOCATE( trc_data(jpi,jpj,jpdta)                                   ,   &
+         &      epkbot(jpi,jpj), gdepbot(jpi,jpj)        ,   &
+         &      dz(jpksed)  , por(jpksed) , por1(jpksed)                  ,   &
+         &      volw(jpksed), vols(jpksed), rdtsed(jpksed)  ,   &
          &      trcsedi  (jpi,jpj,jpksed,jptrased)                        ,   &
          &      flxsedi3d(jpi,jpj,jpksed,jpdia3dsed)                      ,   &
-         &      flxsedi2d(jpi,jpj,jpksed,jpdia2dsed)                      ,   &
+         &      flxsedi2d(jpi,jpj,jpdia2dsed)                             ,   &
          &      mol_wgt(jpsol),                                           STAT=sed_alloc )
 
@@ -185,9 +170,3 @@
    END FUNCTION sed_alloc
 
-#else
-   !!======================================================================
-   !! No Sediment model
-   !!======================================================================
-#endif
-
 END MODULE sed
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed_oce.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sed_oce.F90	(revision 10321)
@@ -0,0 +1,36 @@
+MODULE sed_oce
+   !!======================================================================
+   !!                        ***  sed  ***
+   !! Sediment :   set sediment global variables
+   !!======================================================================
+
+   !! History :
+   !!        !  06-12  (C. Ethe)  Orignal
+   !!----------------------------------------------------------------------
+   USE par_sed
+   USE trc, ONLY : profsed
+
+   IMPLICIT NONE
+   PUBLIC
+
+   PUBLIC sed_oce_alloc
+
+   REAL(wp), PUBLIC, DIMENSION(:    ), ALLOCATABLE ::  profsedw       !: depth of middle of each layer
+
+   !! $Id$
+CONTAINS
+
+   INTEGER FUNCTION sed_oce_alloc()
+      !!-------------------------------------------------------------------
+      !!                    *** ROUTINE sed_alloc ***
+      !!-------------------------------------------------------------------
+      USE lib_mpp, ONLY: ctl_warn
+      !!-------------------------------------------------------------------
+      !
+      ALLOCATE( profsed(jpksed) , profsedw(jpksed) , STAT=sed_oce_alloc )
+
+      IF( sed_oce_alloc /= 0 )   CALL ctl_warn('sed_oce_alloc: failed to allocate arrays')
+      !
+   END FUNCTION sed_oce_alloc
+
+END MODULE sed_oce
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedadv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedadv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedadv.F90	(revision 10321)
@@ -4,19 +4,19 @@
    !!    Sediment : vertical advection and burial
    !!=====================================================================
-#if defined key_sed
-   !!----------------------------------------------------------------------
-   !!   'key_sed'                                                  Sediment 
+   !! * Modules used
    !!----------------------------------------------------------------------
    !!   sed_adv :
    !!----------------------------------------------------------------------
    USE sed     ! sediment global variable
+   USE lib_mpp         ! distribued memory computing library
+
+   IMPLICIT NONE
+   PRIVATE
 
    PUBLIC sed_adv
-
-   !! * Module variable
-   INTEGER, PARAMETER  ::  nztime = jpksed         ! number of time step between sunrise and sunset
-
-   REAL(wp), DIMENSION(jpksed), SAVE :: dvolsp, dvolsm
-   REAL(wp), DIMENSION(jpksed), SAVE :: c2por, ckpor
+   PUBLIC sed_adv_alloc
+
+   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:) :: dvolsp, dvolsm
+   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:) :: c2por, ckpor
 
    REAL(wp) :: cpor
@@ -49,22 +49,26 @@
       ! * local variables
       INTEGER :: ji, jk, js 
-      INTEGER :: jn, ntimes, ikwneg
+      INTEGER :: jn, ntimes, nztime, ikwneg
       
-      REAL(wp), DIMENSION(:,:), ALLOCATABLE :: zsolcpno
-      REAL(wp), DIMENSION(:  ), ALLOCATABLE :: zfilled, zfull, zfromup, zempty
-      REAL(wp), DIMENSION(:,:), ALLOCATABLE :: zgap, zwb
-      REAL(wp), DIMENSION(:,:), ALLOCATABLE :: zrainrf
-      REAL(wp), DIMENSION(nztime) ::  zraipush
-
-      REAL(wp) :: zkwnup, zkwnlo, zfrac,  zfromce, zrest
+      REAL(wp), DIMENSION(jpksed,jpsol) :: zsolcpno
+      REAL(wp), DIMENSION(jpksed)       :: zfilled, zfull, zfromup, zempty
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zgap, zwb
+      REAL(wp), DIMENSION(jpoce,jpsol) :: zrainrf
+      REAL(wp), DIMENSION(:  ), ALLOCATABLE :: zraipush
+
+      REAL(wp) :: zkwnup, zkwnlo, zfrac,  zfromce, zrest, sumtot, zsumtot1
 
       !------------------------------------------------------------------------
 
 
+      IF( ln_timing )  CALL timing_start('sed_adv')
+!
       IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' '
-         WRITE(numsed,*) ' sed_adv : vertical sediment advection  '
-         WRITE(numsed,*) ' '
-         por1clay = dens * por1(jpksed) * dz(jpksed) / mol_wgt(jsclay)
+         IF (lwp) THEN
+            WRITE(numsed,*) ' '
+            WRITE(numsed,*) ' sed_adv : vertical sediment advection  '
+            WRITE(numsed,*) ' '
+         ENDIF
+         por1clay = denssol * por1(jpksed) * dz(jpksed)
          cpor     = por1(jpksed) / por1(2)
          DO jk = 2, jpksed
@@ -80,8 +84,4 @@
       ENDIF
 
-      ALLOCATE( zsolcpno(jpksed,jpsol), zrainrf(jpoce,jpsol) )
-      ALLOCATE( zfilled(jpksed), zfull(jpksed), zfromup(jpksed), zempty(jpksed) )
-      ALLOCATE( zgap (jpoce,jpksed)   , zwb(jpoce,jpksed)  )  
-
       ! Initialization of data for mass balance calculation
       !---------------------------------------------------
@@ -89,5 +89,8 @@
       tosed  (:,:) = 0. 
       rloss  (:,:) = 0.
-
+      ikwneg = 1
+      nztime = jpksed
+
+      ALLOCATE( zraipush(nztime) )
 
       ! Initiate gap 
@@ -104,10 +107,9 @@
       zgap(1:jpoce,1:jpksed) = 1. - zgap(1:jpoce,1:jpksed)   
 
-
       ! Initiate burial rates
       !-----------------------
       zwb(:,:) = 0.
       DO jk = 2, jpksed
-         zfrac =  dtsed / ( dens * por1(jk) )     
+         zfrac =  dtsed / ( denssol * por1(jk) )     
          DO ji = 1, jpoce
             zwb(ji,jk) = zfrac * raintg(ji)
@@ -127,5 +129,4 @@
       ENDDO
 
-
       zrainrf(:,:) = 0.
       DO ji = 1, jpoce
@@ -206,14 +207,11 @@
                   ! quantities to push in deeper sediment
                   tosed  (ji,js) = zsolcpno(jpksed,js) &
-                     &           * zwb(ji,jpksed) * dens * por1(jpksed) / mol_wgt(js)
-               ENDDO
-               
+                     &           * zwb(ji,jpksed) * denssol * por1(jpksed)
+               ENDDO
+
             ELSE ! what is remaining is great than dz(2)
 
                ntimes = INT( zrest / dz(2) ) + 1
-               IF( ntimes > nztime ) THEN
-                  WRITE( numsed,* ) ' sedadv : rest too large at sediment point ji = ', ji
-                  STOP
-               ENDIF
+               IF( ntimes > nztime ) CALL ctl_stop( 'STOP', 'sed_adv : rest too large ' )
                zraipush(1) = dz(2)
                zrest = zrest - zraipush(1)
@@ -249,5 +247,5 @@
                      fromsed(ji,js) = 0.
                      tosed  (ji,js) = tosed(ji,js) + zsolcpno(jpksed,js) * zraipush(jn) &
-                        &             * dens * por1(2) / mol_wgt(js)
+                        &             * denssol * por1(2) 
                   ENDDO
                ENDDO
@@ -279,7 +277,5 @@
             ! for the last layer, one make go up clay 
             solcp(ji,jpksed,jsclay) = solcp(ji,jpksed,jsclay) + zempty(jpksed) * 1.
-            !! C. Heinze      fromsed(ji,jsclay) = zempty(jpksed) * 1. * dens * por1(jpksed) / mol_wgt(jsclay)
             fromsed(ji,jsclay) = zempty(jpksed) * 1. * por1clay
-
          ELSE  ! rain > 0 and rain < total reaction loss
 
@@ -323,5 +319,5 @@
                ENDDO
                solcp(ji,jpksed,jsclay) =  solcp(ji,jpksed,jsclay) + zempty(jpksed) * 1.
-               !! C. Heinze  fromsed(ji,jsclay) = zempty(jpksed) * 1. * dens * por1(jpksed) / mol_wgt(jsclay)
+               !! C. Heinze  fromsed(ji,jsclay) = zempty(jpksed) * 1. * denssol * por1(jpksed) / mol_wgt(jsclay)
                fromsed(ji,jsclay) = zempty(jpksed) * 1. * por1clay
                
@@ -339,5 +335,5 @@
                   solcp(ji,2,js) = zfull(2) * zsolcpno(2,js) + zempty(2) * zrainrf(ji,js)
                ENDDO
-               DO  js = 1, jpsol              
+               DO  js = 1, jpsol
                   DO jk = jpksedm1, 3, -1
                      solcp(ji,jk,js) = zfull(jk) * zsolcpno(jk,js) + zempty(jk) * zsolcpno(jk-1,js)
@@ -349,5 +345,5 @@
                ENDDO
                solcp(ji,jpksed,jsclay) = solcp(ji,jpksed,jsclay) + zkwnlo * 1.
-               ! Heinze  fromsed(ji,jsclay) = zkwnlo * 1. * dens * por1(jpksed) / mol_wgt(jsclay)
+               ! Heinze  fromsed(ji,jsclay) = zkwnlo * 1. * denssol * por1(jpksed) / mol_wgt(jsclay)
                fromsed(ji,jsclay) = zkwnlo * 1.* por1clay
             ELSE   ! 2 < ikwneg(ji) <= jpksedm1
@@ -415,6 +411,7 @@
                   fromsed(ji,js)   = 0.
                ENDDO
-               ! Heinze  fromsed(ji,jsclay) = zempty * 1. * dens * por1(jpksed) / mol_wgt(jsclay)
+               ! Heinze  fromsed(ji,jsclay) = zempty * 1. * denssol * por1(jpksed) / mol_wgt(jsclay)
                fromsed(ji,jsclay) = zempty(jpksed) * 1. * por1clay
+
             ENDIF ! ikwneg(ji) = 2
          ENDIF  ! zwb > 0
@@ -425,28 +422,21 @@
       raintg(:)   = 0.
 
-      DEALLOCATE( zsolcpno )   
-      DEALLOCATE( zrainrf  )
-      DEALLOCATE( zfilled  )
-      DEALLOCATE( zfull    )
-      DEALLOCATE( zfromup  )
-      DEALLOCATE( zempty   )
-      DEALLOCATE( zgap     )  
-      DEALLOCATE( zwb      )
-
+      DEALLOCATE( zraipush )
+
+      IF( ln_timing )  CALL timing_stop('sed_adv')
 
    END SUBROUTINE sed_adv
-#else
-   !!======================================================================
-   !! MODULE sedbtb  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_adv( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_adv: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_adv
-
-   !!======================================================================
-
-#endif
+
+
+   INTEGER FUNCTION sed_adv_alloc()
+      !!----------------------------------------------------------------------
+      !!                     ***  ROUTINE p4z_prod_alloc  ***
+      !!----------------------------------------------------------------------
+      ALLOCATE( dvolsp(jpksed), dvolsm(jpksed), c2por(jpksed),         &
+      &         ckpor(jpksed) ,           STAT = sed_adv_alloc )
+      !
+      IF( sed_adv_alloc /= 0 ) CALL ctl_warn('sed_adv_alloc : failed to allocate arrays.')
+      !
+   END FUNCTION sed_adv_alloc
+
 END MODULE sedadv
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedarr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedarr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedarr.F90	(revision 10321)
@@ -4,5 +4,5 @@
    !!              transform 1D (2D) array to a 2D (1D) table
    !!======================================================================
-#if defined key_sed
+
    !!----------------------------------------------------------------------
    !!   arr_2d_1d  : 2-D to 1-D
@@ -11,4 +11,6 @@
    !! * Modules used
    USE par_sed
+   USE dom_oce
+   USE sed
 
    IMPLICIT NONE
@@ -28,7 +30,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 3.3 , NEMO Consortium (2010)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL licence (NEMOGCM/NEMO_CeCILL.txt)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -42,4 +44,6 @@
 
       INTEGER ::  jn, jid, jjd
+
+      IF( ln_timing )   CALL timing_start('pack_arr_2d_1d')
         
       DO jn = 1, ndim1d
@@ -48,4 +52,6 @@
          tab1d(jn)  = tab2d(jid, jjd)
       END DO 
+
+      IF( ln_timing )   CALL timing_stop('pack_arr_2d_1d')
 
    END SUBROUTINE pack_arr_2d_1d
@@ -59,4 +65,6 @@
       INTEGER ::  jn, jid, jjd
 
+      IF( ln_timing )   CALL timing_start('unpack_arr_1d_2d')
+
       DO jn = 1, ndim1d
          jid             = MOD( tab_ind(jn) - 1, jpi) + 1
@@ -64,4 +72,6 @@
          tab2d(jid, jjd) = tab1d(jn)
       END DO
+
+      IF( ln_timing )   CALL timing_stop('unpack_arr_1d_2d')
 
    END SUBROUTINE unpack_arr_1d_2d
@@ -75,4 +85,6 @@
       INTEGER, DIMENSION(ndim1d) ::  jid, jjd        
       INTEGER ::    jk, jn , ji, jj
+
+      IF( ln_timing )   CALL timing_start('pack_arr_2d_3d')
       
       DO jn = 1, ndim1d
@@ -88,4 +100,6 @@
          ENDDO
       ENDDO
+
+      IF( ln_timing )   CALL timing_stop('pack_arr_2d_3d')
       
    END SUBROUTINE pack_arr_3d_2d
@@ -100,6 +114,8 @@
       INTEGER, DIMENSION(ndim1d) ::  jid, jjd        
       INTEGER ::   jk, jn , ji, jj
-
-     DO jn = 1, ndim1d
+      !
+      IF( ln_timing )   CALL timing_start('unpack_arr_2d_3d')
+      !
+      DO jn = 1, ndim1d
          jid(jn) = MOD( tab_ind(jn) - 1, jpi ) + 1
          jjd(jn) = ( tab_ind(jn) - 1 ) / jpi + 1
@@ -114,16 +130,7 @@
       ENDDO
 
+      IF( ln_timing )   CALL timing_stop('unpack_arr_2d_3d')
+
    END SUBROUTINE unpack_arr_2d_3d
 
-#else
-   !!======================================================================
-   !! MODULE sedarr  :   Dummy module
-   !!======================================================================
-CONTAINS
-   SUBROUTINE pack_arr         ! Empty routine
-   END SUBROUTINE  pack_arr
-   SUBROUTINE unpack_arr         ! Empty routine
-   END SUBROUTINE  unpack_arr
-   !!======================================================================
-#endif
 END MODULE sedarr
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedbtb.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedbtb.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedbtb.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedbtb
-#if defined key_sed
    !!======================================================================
    !!              ***  MODULE  sedbtb  ***
@@ -8,4 +7,8 @@
    USE sed     ! sediment global variable
    USE sedmat  ! linear system of equations
+   USE lib_mpp         ! distribued memory computing library
+
+   IMPLICIT NONE
+   PRIVATE
 
    PUBLIC sed_btb
@@ -33,18 +36,17 @@
       ! * local variables
       INTEGER :: ji, jk, js
-      REAL(wp), DIMENSION(:,:,:) , ALLOCATABLE ::  zsol  !   solution
+      REAL(wp), DIMENSION(jpoce,jpksedm1,jpsol) ::  zsol  !   solution
       !------------------------------------------------------------------------
 
+      IF( ln_timing )  CALL timing_start('sed_btb')
+
       IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' sed_btb : Bioturbation  '
-         WRITE(numsed,*) ' '
+         IF (lwp) WRITE(numsed,*) ' sed_btb : Bioturbation  '
+         IF (lwp) WRITE(numsed,*) ' '
       ENDIF
 
       ! Initializations
       !----------------
-      ALLOCATE( zsol(jpoce,jpksedm1,jpsol) )
-
       zsol(:,:,:) = 0.
-
 
       ! right hand side of coefficient matrix
@@ -58,5 +60,5 @@
       ENDDO
 
-      CALL sed_mat( jpsol, jpoce, jpksedm1, zsol )
+      CALL sed_mat( jpsol, jpoce, jpksedm1, zsol, dtsed / 2.0 )
 
 
@@ -70,21 +72,8 @@
          ENDDO
       ENDDO
-     
-      DEALLOCATE( zsol )
+
+      IF( ln_timing )  CALL timing_stop('sed_btb')
 
    END SUBROUTINE sed_btb
-#else
-   !!======================================================================
-   !! MODULE sedbtb  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_btb( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_btb: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_btb
 
-   !!======================================================================
-
-#endif
 END MODULE sedbtb
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedchem.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedchem.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedchem.F90	(revision 10321)
@@ -1,5 +1,4 @@
 MODULE sedchem
 
-#if defined key_sed 
    !!======================================================================
    !!                        ***  Module sedchem  ***
@@ -9,145 +8,24 @@
    USE sed     ! sediment global variable
    USE sedarr
+   USE eosbn2, ONLY : neos
+   USE lib_mpp         ! distribued memory computing library
+
+   IMPLICIT NONE
+   PRIVATE
 
    !! * Accessibility
-   PUBLIC sed_chem   
+   PUBLIC sed_chem
+   PUBLIC ahini_for_at_sed     !
+   PUBLIC solve_at_general_sed !
+
+   ! Maximum number of iterations for each method
+   INTEGER, PARAMETER :: jp_maxniter_atgen    = 20
+   REAL(wp), PARAMETER :: pp_rdel_ah_target = 1.E-4_wp
 
    !! * Module variables
    REAL(wp) :: &
-      salchl = 1./1.80655 , & ! conversion factor for salinity --> chlorinity (Wooster et al. 1969)
       calcon = 1.03E-2        ! mean calcite concentration [Ca2+] in sea water [mole/kg solution] 
 
-   REAL(wp) :: &              ! coeff. for 1. dissoc. of carbonic acid (Millero, 1995)   
-      c10 = 3670.7   , &
-      c11 = 62.008   , &
-      c12 = 9.7944   , &
-      c13 = 0.0118   , &
-      c14 = 0.000116
-
-   REAL(wp) :: &              ! coeff. for 2. dissoc. of carbonic acid (Millero, 1995)   
-      c20 = 1394.7   , &
-      c21 = 4.777    , &
-      c22 = 0.       , &
-      c23 = 0.0184   , &
-      c24 = 0.000118
-
-   REAL(wp) :: &              ! coeff. for 1. dissoc. of boric acid (Dickson and Goyet, 1994)
-      cb0  = -8966.90, &
-      cb1  = -2890.53, &
-      cb2  = -77.942 , &
-      cb3  = 1.728   , &
-      cb4  = -0.0996 , &
-      cb5  = 148.0248, &
-      cb6  = 137.1942, &
-      cb7  = 1.62142 , &
-      cb8  = -24.4344, &
-      cb9  = -25.085 , &
-      cb10 = -0.2474 , &
-      cb11 = 0.053105
-
-   REAL(wp) :: &             ! borat constants
-      bor1 = 0.000232, &
-      bor2 = 1./10.811
-
-   REAL(wp) :: &             ! constants for calculate concentrations 
-      st1  = 0.14     , &    ! for sulfate (Morris & Riley 1966)
-      st2  = 1./96.062, &
-      ks0  = 141.328  , &
-      ks1  = -4276.1  , &
-      ks2  = -23.093  , &
-      ks3  = -13856.  , &
-      ks4  = 324.57   , &
-      ks5  = -47.986  , &
-      ks6  = 35474.   , &
-      ks7  = -771.54  , &
-      ks8  = 114.723  , &
-      ks9  = -2698.   , &
-      ks10 = 1776.    , &
-      ks11 = 1.       , &
-      ks12 = -0.001005 
-
-   REAL(wp) :: &             ! constants for calculate concentrations 
-      ft1  = 0.000067   , &  ! fluorides (Dickson & Riley 1979 )
-      ft2  = 1./18.9984 , &
-      kf0  = -12.641    , &
-      kf1  = 1590.2     , &
-      kf2  = 1.525      , &
-      kf3  = 1.0        , &
-      kf4  =-0.001005
-
-   REAL(wp) :: &             ! coeff. for dissoc. of water (Dickson and Riley, 1979 )
-      cw0 = -13847.26  , &
-      cw1 = 148.9802   , &
-      cw2 = -23.6521   , &
-      cw3 = 118.67     , &
-      cw4 = -5.977     , &
-      cw5 = 1.0495     , &
-      cw6 = -0.01615
- 
-   REAL(wp) :: &             ! coeff. for dissoc. of phosphate (Millero (1974)
-      cp10 = 115.54    , &
-      cp11 = -4576.752 , &
-      cp12 = -18.453   , &
-      cp13 = -106.736  , &
-      cp14 = 0.69171   , &
-      cp15 = -0.65643  , &
-      cp16 = -0.01844  , &
-      cp20 = 172.1033  , &
-      cp21 = -8814.715 , &
-      cp22 = -27.927   , &
-      cp23 = -160.340  , &
-      cp24 = 1.3566    , &
-      cp25 = 0.37335   , &
-      cp26 = -0.05778  , &
-      cp30 = -18.126   , &
-      cp31 = -3070.75  , &
-      cp32 = 17.27039  , &
-      cp33 = 2.81197   , &
-      cp34 = -44.99486 , &
-      cp35 = -0.09984
-
-   REAL(wp) :: &             ! coeff. for dissoc. of silicates (Millero (1974)  
-      cs10 = 117.40    , &  
-      cs11 = -8904.2   , & 
-      cs12 = -19.334   , & 
-      cs13 = -458.79   , & 
-      cs14 = 3.5913    , & 
-      cs15 = 188.74    , & 
-      cs16 = -1.5998   , & 
-      cs17 = -12.1652  , & 
-      cs18 = 0.07871   , & 
-      cs19 = 0.        , & 
-      cs20 = 1.        , & 
-      cs21 = -0.001005
-
-   REAL(wp) :: &            ! coeff. for apparent solubility equilibrium 
-      ! akcc1 = -34.452 , & ! of calcite (Ingle,1975,  1800, eq. 6)
-      ! akcc2 = -39.866 , &  
-      ! akcc3 = 110.21  , &  
-      ! akcc4 = -7.5752E-6  
-      akcc1 = -171.9065 , &    ! Millero et al. 1995 from Mucci 1983
-      akcc2 = -0.077993 , &  
-      akcc3 = 2839.319  , &  
-      akcc4 = 71.595    , &  
-      akcc5 = -0.77712  , &  
-      akcc6 = 0.0028426 , &  
-      akcc7 = 178.34    , &  
-      akcc8 = -0.07711  , &  
-      akcc9 = 0.0041249
-
-   REAL(wp) :: &                 ! universal gas constant
-      rgas = 83.145              ! bar.cm3/(mol.K) or R=8.31451 J/(g.mol.K)
-
-
-   ! coeff. for seawater pressure correction (millero 95)		
-   REAL(wp), DIMENSION(8)  :: & 
-      devk1, devk2, devk3, devk4, devk5
-
-   DATA devk1/ -25.5   , -15.82    , -29.48  , -25.60    , -48.76    , -14.51   , -23.12   , -26.57   /   
-   DATA devk2/ 0.1271  , -0.0219   , 0.1622  , 0.2324    , -0.5304   , 0.1211   ,  0.1758  , 0.2020   /   
-   DATA devk3/ 0.      , 0.        , 2.608E-3, -3.6246E-3, 0.        , -0.321E-3, -2.647E-3, -3.042E-3/   
-   DATA devk4/-3.08E-3 , 1.13E-3   , -2.84E-3, -5.13E-3  , -11.76E-3 , -2.67E-3 , -5.15E-3 , -4.08E-3 /   
-   DATA devk5/0.0877E-3, -0.1475E-3, 0.      , 0.0794E-3 , -0.3692E-3, 0.0427E-3,  0.09E-3 , 0.0714E-3/
-
+   REAL(wp) ::   rgas   = 83.14472      ! universal gas constants
 
    ! coeff. for density of sea water (Millero & Poisson 1981) 
@@ -162,4 +40,64 @@
    REAL(wp), DIMENSION(6)  :: Ddsw                    
    DATA Ddsw / 999.842594 , 6.793952E-2 , -9.095290E-3, 1.001685E-4, -1.120083E-6, 6.536332E-9/
+
+  REAL(wp) :: devk10  = -25.5
+   REAL(wp) :: devk11  = -15.82
+   REAL(wp) :: devk12  = -29.48
+   REAL(wp) :: devk13  = -20.02
+   REAL(wp) :: devk14  = -18.03
+   REAL(wp) :: devk15  = -9.78
+   REAL(wp) :: devk16  = -48.76
+   REAL(wp) :: devk17  = -14.51
+   REAL(wp) :: devk18  = -23.12
+   REAL(wp) :: devk19  = -26.57
+   REAL(wp) :: devk110  = -29.48
+   !
+   REAL(wp) :: devk20  = 0.1271
+   REAL(wp) :: devk21  = -0.0219
+   REAL(wp) :: devk22  = 0.1622
+   REAL(wp) :: devk23  = 0.1119
+   REAL(wp) :: devk24  = 0.0466
+   REAL(wp) :: devk25  = -0.0090
+   REAL(wp) :: devk26  = 0.5304
+   REAL(wp) :: devk27  = 0.1211
+   REAL(wp) :: devk28  = 0.1758
+   REAL(wp) :: devk29  = 0.2020
+   REAL(wp) :: devk210  = 0.1622
+   !
+   REAL(wp) :: devk30  = 0.
+   REAL(wp) :: devk31  = 0.
+   REAL(wp) :: devk32  = 2.608E-3
+   REAL(wp) :: devk33  = -1.409e-3
+   REAL(wp) :: devk34  = 0.316e-3
+   REAL(wp) :: devk35  = -0.942e-3
+   REAL(wp) :: devk36  = 0.
+   REAL(wp) :: devk37  = -0.321e-3
+   REAL(wp) :: devk38  = -2.647e-3
+   REAL(wp) :: devk39  = -3.042e-3
+   REAL(wp) :: devk310  = -2.6080e-3
+   !
+   REAL(wp) :: devk40  = -3.08E-3
+   REAL(wp) :: devk41  = 1.13E-3
+   REAL(wp) :: devk42  = -2.84E-3
+   REAL(wp) :: devk43  = -5.13E-3
+   REAL(wp) :: devk44  = -4.53e-3
+   REAL(wp) :: devk45  = -3.91e-3
+   REAL(wp) :: devk46  = -11.76e-3
+   REAL(wp) :: devk47  = -2.67e-3
+   REAL(wp) :: devk48  = -5.15e-3
+   REAL(wp) :: devk49  = -4.08e-3
+   REAL(wp) :: devk410  = -2.84e-3
+   !
+   REAL(wp) :: devk50  = 0.0877E-3
+   REAL(wp) :: devk51  = -0.1475E-3
+   REAL(wp) :: devk52  = 0.
+   REAL(wp) :: devk53  = 0.0794E-3
+   REAL(wp) :: devk54  = 0.09e-3
+   REAL(wp) :: devk55  = 0.054e-3
+   REAL(wp) :: devk56  = 0.3692E-3
+   REAL(wp) :: devk57  = 0.0427e-3
+   REAL(wp) :: devk58  = 0.09e-3
+   REAL(wp) :: devk59  = 0.0714e-3
+   REAL(wp) :: devk510  = 0.0
 
    !! $Id$
@@ -179,69 +117,69 @@
       INTEGER, INTENT(in) :: kt                     ! time step
 
-#if ! defined key_sed_off
       INTEGER  :: ji, jj, ikt
-      REAL(wp) :: ztkel, ztc, ztc2, zpres, ztr 
-      REAL(wp) :: zsal, zsal2, zsqrt, zsal15  
-      REAL(wp) :: zis, zis2, zisqrt          
+      REAL(wp) :: ztc, ztc2
+      REAL(wp) :: zsal, zsal15  
       REAL(wp) :: zdens0, zaw, zbw, zcw    
-      REAL(wp) :: zbuf1, zbuf2 
-      REAL(wp) :: zcpexp, zcpexp2
-      REAL(wp) :: zck1p, zck2p, zck3p, zcksi   
-      REAL(wp), ALLOCATABLE, DIMENSION(:,:,:) ::   zchem_data
-
-#endif
+      REAL(wp), DIMENSION(jpi,jpj,15) ::   zchem_data
       !!----------------------------------------------------------------------
 
-      IF( MOD( kt - 1, nfreq ) /= 0 ) RETURN
-
-      WRITE(numsed,*) ' Getting Chemical constants from tracer model at time kt = ', kt
-      WRITE(numsed,*) ' '
-
-
-#if defined key_sed_off
-      CALL sed_chem_off
-#else
+
+      IF( ln_timing )  CALL timing_start('sed_chem')
+
+      IF (lwp) WRITE(numsed,*) ' Getting Chemical constants from tracer model at time kt = ', kt
+      IF (lwp) WRITE(numsed,*) ' '
+
       ! reading variables
-      ALLOCATE( zchem_data(jpi,jpj,6) )   ;   zchem_data(:,:,:) = 0.
-
-      DO jj = 1,jpj
-         DO ji = 1, jpi
-            ikt = mbkt(ji,jj) 
-            IF ( tmask(ji,jj,ikt) == 1 ) THEN
-               zchem_data(ji,jj,1) = ak13 (ji,jj,ikt)
-               zchem_data(ji,jj,2) = ak23 (ji,jj,ikt)
-               zchem_data(ji,jj,3) = akb3 (ji,jj,ikt)
-               zchem_data(ji,jj,4) = akw3 (ji,jj,ikt)
-               zchem_data(ji,jj,5) = aksp (ji,jj,ikt)
-               zchem_data(ji,jj,6) = borat(ji,jj,ikt)
-            ENDIF
+      zchem_data(:,:,:) = rtrn
+
+      IF (ln_sediment_offline) THEN
+         CALL sed_chem_cst
+      ELSE
+         DO jj = 1,jpj
+            DO ji = 1, jpi
+               ikt = mbkt(ji,jj) 
+               IF ( tmask(ji,jj,ikt) == 1 ) THEN
+                  zchem_data(ji,jj,1) = ak13  (ji,jj,ikt)
+                  zchem_data(ji,jj,2) = ak23  (ji,jj,ikt)
+                  zchem_data(ji,jj,3) = akb3  (ji,jj,ikt)
+                  zchem_data(ji,jj,4) = akw3  (ji,jj,ikt)
+                  zchem_data(ji,jj,5) = aksp  (ji,jj,ikt)
+                  zchem_data(ji,jj,6) = borat (ji,jj,ikt)
+                  zchem_data(ji,jj,7) = ak1p3 (ji,jj,ikt)
+                  zchem_data(ji,jj,8) = ak2p3 (ji,jj,ikt)
+                  zchem_data(ji,jj,9) = ak3p3 (ji,jj,ikt)
+                  zchem_data(ji,jj,10)= aksi3 (ji,jj,ikt)
+                  zchem_data(ji,jj,11)= sio3eq(ji,jj,ikt)
+                  zchem_data(ji,jj,12)= aks3  (ji,jj,ikt)
+                  zchem_data(ji,jj,13)= akf3  (ji,jj,ikt)
+                  zchem_data(ji,jj,14)= sulfat(ji,jj,ikt)
+                  zchem_data(ji,jj,15)= fluorid(ji,jj,ikt)
+               ENDIF
+            ENDDO
          ENDDO
-      ENDDO
-
-      CALL pack_arr ( jpoce, ak1s  (1:jpoce), zchem_data(1:jpi,1:jpj,1), iarroce(1:jpoce) )
-      CALL pack_arr ( jpoce, ak2s  (1:jpoce), zchem_data(1:jpi,1:jpj,2), iarroce(1:jpoce) )
-      CALL pack_arr ( jpoce, akbs  (1:jpoce), zchem_data(1:jpi,1:jpj,3), iarroce(1:jpoce) )
-      CALL pack_arr ( jpoce, akws  (1:jpoce), zchem_data(1:jpi,1:jpj,4), iarroce(1:jpoce) )
-      CALL pack_arr ( jpoce, aksps (1:jpoce), zchem_data(1:jpi,1:jpj,5), iarroce(1:jpoce) )
-      CALL pack_arr ( jpoce, borats(1:jpoce), zchem_data(1:jpi,1:jpj,6), iarroce(1:jpoce) )
-
-      DEALLOCATE( zchem_data )
+
+         CALL pack_arr ( jpoce, ak1s  (1:jpoce), zchem_data(1:jpi,1:jpj,1) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, ak2s  (1:jpoce), zchem_data(1:jpi,1:jpj,2) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, akbs  (1:jpoce), zchem_data(1:jpi,1:jpj,3) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, akws  (1:jpoce), zchem_data(1:jpi,1:jpj,4) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, aksps (1:jpoce), zchem_data(1:jpi,1:jpj,5) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, borats(1:jpoce), zchem_data(1:jpi,1:jpj,6) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, ak1ps (1:jpoce), zchem_data(1:jpi,1:jpj,7) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, ak2ps (1:jpoce), zchem_data(1:jpi,1:jpj,8) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, ak3ps (1:jpoce), zchem_data(1:jpi,1:jpj,9) , iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, aksis (1:jpoce), zchem_data(1:jpi,1:jpj,10), iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, sieqs (1:jpoce), zchem_data(1:jpi,1:jpj,11), iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, aks3s (1:jpoce), zchem_data(1:jpi,1:jpj,12), iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, akf3s (1:jpoce), zchem_data(1:jpi,1:jpj,13), iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, sulfats(1:jpoce), zchem_data(1:jpi,1:jpj,14), iarroce(1:jpoce) )
+         CALL pack_arr ( jpoce, fluorids(1:jpoce), zchem_data(1:jpi,1:jpj,15), iarroce(1:jpoce) )
+      ENDIF
 
       DO ji = 1, jpoce
-         ztkel   = temp(ji) + 273.16
          ztc     = temp(ji)
          ztc2    = ztc * ztc
-         zpres   = press(ji)
          ! zqtt    = ztkel * 0.01
          zsal    = salt(ji)
-         zsal2   = zsal * zsal 
-         zsqrt   = SQRT( zsal )
-         zsal15  = zsqrt * zsal
-         zlogt   = LOG( ztkel )
-         ztr     = 1./ ztkel
-         ! zis=ionic strength (ORNL/CDIAC-74, DOE 94,Dickson and Goyet)
-         zis     = 19.924 * zsal / ( 1000. - 1.005 * zsal )
-         zis2    = zis * zis
-         zisqrt  = SQRT( zis )
+         zsal15  = SQRT( zsal ) * zsal
 
          ! Density of Sea Water - F(temp,sal) [kg/m3]
@@ -256,55 +194,4 @@
          densSW(ji) = densSW(ji) * 1E-3   ! to get dens in [kg/l]
 
-         ! FORMULA FOR CPEXP AFTER EDMOND AND GIESKES (1970) 
-         ! (REFERENCE TO CULBERSON AND PYTKOQICZ (1968) AS MADE IN BROECKER ET AL. (1982) 
-         ! IS INCORRECT; HERE RGAS IS TAKEN TENFOLD TO CORRECT FOR THE NOTATION OF pres  IN
-         ! DBAR INSTEAD OF BAR AND THE EXPRESSION FOR CPEXP IS MULTIPLIED BY LN(10.) 
-         ! TO ALLOW USE OF EXP-FUNCTION WITH BASIS E IN THE FORMULA FOR AKSPP 
-         ! (CF. EDMOND AND GIESKES (1970), P. 1285 AND P. 1286 (THE SMALL FORMULA ON P. 1286 
-         ! IS RIGHT AND CONSISTENT WITH THE SIGN IN PARTIAL MOLAR VOLUME CHANGE AS SHOWN ON P. 1285)
-         !-----------------------------------------------------------------------------------------
-         zcpexp  = zpres / ( rgas*ztkel )
-         zcpexp2 = zpres * zcpexp
-
-         ! For Phodphates (phosphoric acid) (DOE 1994)
-         !----------------------------------------------
-         zck1p = cp10 + cp11*ztr + cp12*zlogt + ( cp13*ztr + cp14 ) * zsqrt &
-            &      + ( cp15*ztr + cp16 ) * zsal
-         zck2p = cp20 + cp21*ztr + cp22*zlogt + ( cp23*ztr + cp24 ) * zsqrt &
-            &      + ( cp25*ztr + cp26 ) * zsal
-         zck3p = cp30 + cp31*ztr + ( cp32*ztr + cp33 ) *  zsqrt &
-            &      + ( cp34*ztr + cp35 ) * zsal
-
-         ! For silicates (DOE 1994) change to mol/kg soln) (OCMIP)
-         !--------------------------------------------------------
-         zcksi = cs10 + cs11*ztr + cs12*zlogt + ( cs13*ztr + cs14) * zisqrt &
-            &      + ( cs15*ztr + cs16 ) * zis &
-            &      + ( cs17*ztr + cs18 ) * zis2 &
-            &      + LOG( 1. + cs19*zsal ) + LOG( cs20 + cs21*zsal )
-
-
-         !K1, K2 of carbonic acid, KB of boric acid, KW (H2O)
-         !---------------------------------------------------
-         zak1p  = EXP ( zck1p  )
-         zak2p  = EXP ( zck2p  )
-         zak3p  = EXP ( zck3p  )
-         zaksil = EXP ( zcksi  )
-
-         zbuf1       = - ( devk1(3) + devk2(3)*ztc + devk3(3)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(3) + devk5(3)*ztc )
-         aksis(ji)     = zaksil * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(6) + devk2(6)*ztc + devk3(6)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(6) + devk5(6)*ztc )
-         ak1ps(ji)   = zak1p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
- 
-         zbuf1       = - ( devk1(7) + devk2(7)*ztc + devk3(7)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(7) + devk5(7)*ztc )
-         ak2ps(ji)   = zak2p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(8) + devk2(8)*ztc + devk3(8)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(8) + devk5(8)*ztc )
-         ak3ps(ji)   = zak3p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
          ak12s  (ji) = ak1s (ji) * ak2s (ji)
          ak12ps (ji) = ak1ps(ji) * ak2ps(ji)
@@ -313,261 +200,584 @@
          calcon2(ji) = 0.01028 * ( salt(ji) / 35. ) * densSW(ji)
       ENDDO
-
        
-#endif
+      IF( ln_timing )  CALL timing_stop('sed_chem')
 
    END SUBROUTINE sed_chem
 
-#if defined key_sed_off
-
-   SUBROUTINE sed_chem_off
-      !!----------------------------------------------------------------------
-      !!                   ***  ROUTINE sed_chem_off  ***
-      !!                    
-      !! ** Purpose :   compute chemical constants
+   SUBROUTINE ahini_for_at_sed(p_hini)
+      !!---------------------------------------------------------------------
+      !!                     ***  ROUTINE ahini_for_at  ***
       !!
-      !!   History :
-      !!        !  04-10  (N. Emprin, M. Gehlen )  Original code
-      !!        !  06-04  (C. Ethe)  Re-organization 
-      !!----------------------------------------------------------------------  
-      !! * Local declarations
-      INTEGER :: ji
-
-      REAL(wp) ::  ztkel, ztc, ztc2, zpres, ztr 
-      REAL(wp) ::  zsal, zsal2, zsqrt, zsal15   
-      REAL(wp) ::  zis, zis2, zisqrt            
-      REAL(wp) ::  zdens0, zaw, zbw, zcw        
-      REAL(wp) ::  zchl, zst, zft, zbuf1, zbuf2 
-      REAL(wp) ::  zcpexp, zcpexp2              
-      REAL(wp) ::  zckb, zck1, zck2, zckw       
-      REAL(wp) ::  zck1p, zck2p, zck3p, zcksi   
-      REAL(wp) ::  zak1, zak2, zakb, zakw              
-      REAL(wp) ::  zaksp0, zksp, zks, zkf 
-
+      !! Subroutine returns the root for the 2nd order approximation of the
+      !! DIC -- B_T -- A_CB equation for [H+] (reformulated as a cubic 
+      !! polynomial) around the local minimum, if it exists.
+      !! Returns * 1E-03_wp if p_alkcb <= 0
+      !!         * 1E-10_wp if p_alkcb >= 2*p_dictot + p_bortot
+      !!         * 1E-07_wp if 0 < p_alkcb < 2*p_dictot + p_bortot
+      !!                    and the 2nd order approximation does not have 
+      !!                    a solution
+      !!---------------------------------------------------------------------
+      REAL(wp), DIMENSION(jpoce,jpksed), INTENT(OUT)  ::  p_hini
+      INTEGER  ::   ji, jk
+      REAL(wp)  ::  zca1, zba1
+      REAL(wp)  ::  zd, zsqrtd, zhmin
+      REAL(wp)  ::  za2, za1, za0
+      REAL(wp)  ::  p_dictot, p_bortot, p_alkcb
+
+      IF( ln_timing )  CALL timing_start('ahini_for_at_sed')
+      !
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            p_alkcb  = pwcp(ji,jk,jwalk) / densSW(ji)
+            p_dictot = pwcp(ji,jk,jwdic) / densSW(ji) 
+            p_bortot = borats(ji) / densSW(ji)
+            IF (p_alkcb <= 0.) THEN
+                p_hini(ji,jk) = 1.e-3
+            ELSEIF (p_alkcb >= (2.*p_dictot + p_bortot)) THEN
+                p_hini(ji,jk) = 1.e-10_wp
+            ELSE
+                zca1 = p_dictot/( p_alkcb + rtrn )
+                zba1 = p_bortot/ (p_alkcb + rtrn )
+           ! Coefficients of the cubic polynomial
+                za2 = aKbs(ji)*(1. - zba1) + ak1s(ji)*(1.-zca1)
+                za1 = ak1s(ji)*akbs(ji)*(1. - zba1 - zca1)    &
+                &     + ak1s(ji)*ak2s(ji)*(1. - (zca1+zca1))
+                za0 = ak1s(ji)*ak2s(ji)*akbs(ji)*(1. - zba1 - (zca1+zca1))
+                                        ! Taylor expansion around the minimum
+                zd = za2*za2 - 3.*za1   ! Discriminant of the quadratic equation
+                                        ! for the minimum close to the root
+
+                IF(zd > 0.) THEN        ! If the discriminant is positive
+                  zsqrtd = SQRT(zd)
+                  IF(za2 < 0) THEN
+                    zhmin = (-za2 + zsqrtd)/3.
+                  ELSE
+                    zhmin = -za1/(za2 + zsqrtd)
+                  ENDIF
+                  p_hini(ji,jk) = zhmin + SQRT(-(za0 + zhmin*(za1 + zhmin*(za2 + zhmin)))/zsqrtd)
+                ELSE
+                  p_hini(ji,jk) = 1.e-7
+                ENDIF
+             !
+            ENDIF
+         END DO
+      END DO
+      !
+      IF( ln_timing )  CALL timing_stop('ahini_for_at_sed')
+      !
+   END SUBROUTINE ahini_for_at_sed
+
+   !===============================================================================
+   SUBROUTINE anw_infsup_sed( p_alknw_inf, p_alknw_sup )
+
+   ! Subroutine returns the lower and upper bounds of "non-water-selfionization"
+   ! contributions to total alkalinity (the infimum and the supremum), i.e
+   ! inf(TA - [OH-] + [H+]) and sup(TA - [OH-] + [H+])
+
+   ! Argument variables
+   INTEGER :: jk
+   REAL(wp), DIMENSION(jpoce,jpksed), INTENT(OUT) :: p_alknw_inf
+   REAL(wp), DIMENSION(jpoce,jpksed), INTENT(OUT) :: p_alknw_sup
+
+   DO jk = 1, jpksed
+      p_alknw_inf(:,jk) =  -pwcp(:,jk,jwpo4) / densSW(:)
+      p_alknw_sup(:,jk) =   (2. * pwcp(:,jk,jwdic) + 2. * pwcp(:,jk,jwpo4) + pwcp(:,jk,jwsil)     &
+   &                        + borats(:) ) / densSW(:)
+   END DO
+
+   END SUBROUTINE anw_infsup_sed
+
+
+   SUBROUTINE solve_at_general_sed( p_hini, zhi )
+
+   ! Universal pH solver that converges from any given initial value,
+   ! determines upper an lower bounds for the solution if required
+
+   ! Argument variables
+   !--------------------
+   REAL(wp), DIMENSION(jpoce,jpksed), INTENT(IN)   :: p_hini
+   REAL(wp), DIMENSION(jpoce,jpksed), INTENT(OUT)  :: zhi
+
+   ! Local variables
+   !-----------------
+   INTEGER   ::  ji, jk, jn
+   REAL(wp)  ::  zh_ini, zh, zh_prev, zh_lnfactor
+   REAL(wp)  ::  zdelta, zh_delta
+   REAL(wp)  ::  zeqn, zdeqndh, zalka
+   REAL(wp)  ::  aphscale
+   REAL(wp)  ::  znumer_dic, zdnumer_dic, zdenom_dic, zalk_dic, zdalk_dic
+   REAL(wp)  ::  znumer_bor, zdnumer_bor, zdenom_bor, zalk_bor, zdalk_bor
+   REAL(wp)  ::  znumer_po4, zdnumer_po4, zdenom_po4, zalk_po4, zdalk_po4
+   REAL(wp)  ::  znumer_sil, zdnumer_sil, zdenom_sil, zalk_sil, zdalk_sil
+   REAL(wp)  ::  znumer_so4, zdnumer_so4, zdenom_so4, zalk_so4, zdalk_so4
+   REAL(wp)  ::  znumer_flu, zdnumer_flu, zdenom_flu, zalk_flu, zdalk_flu
+   REAL(wp)  ::  zalk_wat, zdalk_wat
+   REAL(wp)  ::  zfact, p_alktot, zdic, zbot, zpt, zst, zft, zsit
+   LOGICAL   ::  l_exitnow
+   REAL(wp), PARAMETER :: pz_exp_threshold = 1.0
+   REAL(wp), DIMENSION(jpoce,jpksed) :: zalknw_inf, zalknw_sup, rmask, zh_min, zh_max, zeqn_absmin
+
+   IF( ln_timing )  CALL timing_start('solve_at_general_sed')
+      !  Allocate temporary workspace
+   CALL anw_infsup_sed( zalknw_inf, zalknw_sup )
+
+   rmask(:,:) = 1.0
+   zhi(:,:)   = 0.
+
+   ! TOTAL H+ scale: conversion factor for Htot = aphscale * Hfree
+   DO jk = 1, jpksed
+      DO ji = 1, jpoce
+         IF (rmask(ji,jk) == 1.) THEN
+            p_alktot = pwcp(ji,jk,jwalk) / densSW(ji)
+            aphscale = 1. + sulfats(ji)/aks3s(ji)
+            zh_ini = p_hini(ji,jk)
+
+            zdelta = (p_alktot-zalknw_inf(ji,jk))**2 + 4.*akws(ji) / aphscale
+
+            IF(p_alktot >= zalknw_inf(ji,jk)) THEN
+               zh_min(ji,jk) = 2.*akws(ji) /( p_alktot-zalknw_inf(ji,jk) + SQRT(zdelta) )
+            ELSE
+               zh_min(ji,jk) = aphscale * (-(p_alktot-zalknw_inf(ji,jk)) + SQRT(zdelta) ) / 2.
+            ENDIF
+
+            zdelta = (p_alktot-zalknw_sup(ji,jk))**2 + 4.*akws(ji) / aphscale
+
+            IF(p_alktot <= zalknw_sup(ji,jk)) THEN
+               zh_max(ji,jk) = aphscale * (-(p_alktot-zalknw_sup(ji,jk)) + SQRT(zdelta) ) / 2.
+            ELSE
+               zh_max(ji,jk) = 2.*akws(ji) /( p_alktot-zalknw_sup(ji,jk) + SQRT(zdelta) )
+            ENDIF
+
+            zhi(ji,jk) = MAX(MIN(zh_max(ji,jk), zh_ini), zh_min(ji,jk))
+         ENDIF
+      END DO
+   END DO
+
+   zeqn_absmin(:,:) = HUGE(1._wp)
+
+   DO jn = 1, jp_maxniter_atgen
+   DO jk = 1, jpksed
+      DO ji = 1, jpoce
+         IF (rmask(ji,jk) == 1.) THEN
+
+            p_alktot = pwcp(ji,jk,jwalk) / densSW(ji)
+            zdic  = pwcp(ji,jk,jwdic) / densSW(ji)
+            zbot  = borats(ji) / densSW(ji)
+            zpt =  pwcp(ji,jk,jwpo4) / densSW(ji)
+            zsit = pwcp(ji,jk,jwsil) / densSW(ji)
+            zst = sulfats(ji)
+            zft = fluorids(ji)
+            aphscale = 1. + sulfats(ji)/aks3s(ji)
+            zh = zhi(ji,jk)
+            zh_prev = zh
+
+            ! H2CO3 - HCO3 - CO3 : n=2, m=0
+            znumer_dic = 2.*ak1s(ji)*ak2s(ji) + zh*ak1s(ji)
+            zdenom_dic = ak1s(ji)*ak2s(ji) + zh*(ak1s(ji) + zh)
+            zalk_dic   = zdic * (znumer_dic/zdenom_dic)
+            zdnumer_dic = ak1s(ji)*ak1s(ji)*ak2s(ji) + zh     &
+                          *(4.*ak1s(ji)*ak2s(ji) + zh*ak1s(ji))
+            zdalk_dic   = -zdic*(zdnumer_dic/zdenom_dic**2)
+
+
+            ! B(OH)3 - B(OH)4 : n=1, m=0
+            znumer_bor = akbs(ji)
+            zdenom_bor = akbs(ji) + zh
+            zalk_bor   = zbot * (znumer_bor/zdenom_bor)
+            zdnumer_bor = akbs(ji)
+            zdalk_bor   = -zbot*(zdnumer_bor/zdenom_bor**2)
+
+
+            ! H3PO4 - H2PO4 - HPO4 - PO4 : n=3, m=1
+            znumer_po4 = 3.*ak1ps(ji)*ak2ps(ji)*ak3ps(ji)  &
+            &            + zh*(2.*ak1ps(ji)*ak2ps(ji) + zh* ak1ps(ji))
+            zdenom_po4 = ak1ps(ji)*ak2ps(ji)*ak3ps(ji)     &
+            &            + zh*( ak1ps(ji)*ak2ps(ji) + zh*(ak1ps(ji) + zh))
+            zalk_po4   = zpt * (znumer_po4/zdenom_po4 - 1.) ! Zero level of H3PO4 = 1
+            zdnumer_po4 = ak1ps(ji)*ak2ps(ji)*ak1ps(ji)*ak2ps(ji)*ak3ps(ji)  &
+            &             + zh*(4.*ak1ps(ji)*ak1ps(ji)*ak2ps(ji)*ak3ps(ji)         &
+            &             + zh*(9.*ak1ps(ji)*ak2ps(ji)*ak3ps(ji)                         &
+            &             + ak1ps(ji)*ak1ps(ji)*ak2ps(ji)                                &
+            &             + zh*(4.*ak1ps(ji)*ak2ps(ji) + zh * ak1ps(ji) ) ) )
+            zdalk_po4   = -zpt * (zdnumer_po4/zdenom_po4**2)
+
+            ! H4SiO4 - H3SiO4 : n=1, m=0
+            znumer_sil = aksis(ji)
+            zdenom_sil = aksis(ji) + zh
+            zalk_sil   = zsit * (znumer_sil/zdenom_sil)
+            zdnumer_sil = aksis(ji)
+            zdalk_sil   = -zsit * (zdnumer_sil/zdenom_sil**2)
+
+            ! HSO4 - SO4 : n=1, m=1
+            aphscale = 1.0 + zst/aks3s(ji)
+            znumer_so4 = aks3s(ji) * aphscale
+            zdenom_so4 = aks3s(ji) * aphscale + zh
+            zalk_so4   = zst * (znumer_so4/zdenom_so4 - 1.)
+            zdnumer_so4 = aks3s(ji) * aphscale
+            zdalk_so4   = -zst * (zdnumer_so4/zdenom_so4**2)
+
+            ! HF - F : n=1, m=1
+            znumer_flu =  akf3s(ji)
+            zdenom_flu =  akf3s(ji) + zh
+            zalk_flu   =  zft * (znumer_flu/zdenom_flu - 1.)
+            zdnumer_flu = akf3s(ji)
+            zdalk_flu   = -zft * (zdnumer_flu/zdenom_flu**2)
+
+            ! H2O - OH
+            zalk_wat   = akws(ji)/zh - zh/aphscale
+            zdalk_wat  = -akws(ji)/zh**2 - 1./aphscale
+
+            ! CALCULATE [ALK]([CO3--], [HCO3-])
+            zeqn = zalk_dic + zalk_bor + zalk_po4 + zalk_sil   &
+            &      + zalk_so4 + zalk_flu                       &
+            &      + zalk_wat - p_alktot
+
+            zalka = p_alktot - (zalk_bor + zalk_po4 + zalk_sil   &
+            &       + zalk_so4 + zalk_flu + zalk_wat)
+
+            zdeqndh = zdalk_dic + zdalk_bor + zdalk_po4 + zdalk_sil &
+            &         + zdalk_so4 + zdalk_flu + zdalk_wat
+
+            ! Adapt bracketing interval
+            IF(zeqn > 0._wp) THEN
+               zh_min(ji,jk) = zh_prev
+            ELSEIF(zeqn < 0._wp) THEN
+               zh_max(ji,jk) = zh_prev
+            ENDIF
+
+            IF(ABS(zeqn) >= 0.5_wp*zeqn_absmin(ji,jk)) THEN
+            ! if the function evaluation at the current point is
+            ! not decreasing faster than with a bisection step (at least linearly)
+            ! in absolute value take one bisection step on [ph_min, ph_max]
+            ! ph_new = (ph_min + ph_max)/2d0
+            !
+            ! In terms of [H]_new:
+            ! [H]_new = 10**(-ph_new)
+            !         = 10**(-(ph_min + ph_max)/2d0)
+            !         = SQRT(10**(-(ph_min + phmax)))
+            !         = SQRT(zh_max * zh_min)
+               zh = SQRT(zh_max(ji,jk) * zh_min(ji,jk))
+               zh_lnfactor = (zh - zh_prev)/zh_prev ! Required to test convergence below
+            ELSE
+            ! dzeqn/dpH = dzeqn/d[H] * d[H]/dpH
+            !           = -zdeqndh * LOG(10) * [H]
+            ! \Delta pH = -zeqn/(zdeqndh*d[H]/dpH) = zeqn/(zdeqndh*[H]*LOG(10))
+            !
+            ! pH_new = pH_old + \deltapH
+            !
+            ! [H]_new = 10**(-pH_new)
+            !         = 10**(-pH_old - \Delta pH)
+            !         = [H]_old * 10**(-zeqn/(zdeqndh*[H]_old*LOG(10)))
+            !         = [H]_old * EXP(-LOG(10)*zeqn/(zdeqndh*[H]_old*LOG(10)))
+            !         = [H]_old * EXP(-zeqn/(zdeqndh*[H]_old))
+
+               zh_lnfactor = -zeqn/(zdeqndh*zh_prev)
+
+               IF(ABS(zh_lnfactor) > pz_exp_threshold) THEN
+                  zh          = zh_prev*EXP(zh_lnfactor)
+               ELSE
+                  zh_delta    = zh_lnfactor*zh_prev
+                  zh          = zh_prev + zh_delta
+               ENDIF
+
+               IF( zh < zh_min(ji,jk) ) THEN
+               ! if [H]_new < [H]_min
+               ! i.e., if ph_new > ph_max then
+               ! take one bisection step on [ph_prev, ph_max]
+               ! ph_new = (ph_prev + ph_max)/2d0
+               ! In terms of [H]_new:
+               ! [H]_new = 10**(-ph_new)
+               !         = 10**(-(ph_prev + ph_max)/2d0)
+               !         = SQRT(10**(-(ph_prev + phmax)))
+               !         = SQRT([H]_old*10**(-ph_max))
+               !         = SQRT([H]_old * zh_min)
+                  zh                = SQRT(zh_prev * zh_min(ji,jk))
+                  zh_lnfactor       = (zh - zh_prev)/zh_prev ! Required to test convergence below
+               ENDIF
+
+               IF( zh > zh_max(ji,jk) ) THEN
+               ! if [H]_new > [H]_max
+               ! i.e., if ph_new < ph_min, then
+               ! take one bisection step on [ph_min, ph_prev]
+               ! ph_new = (ph_prev + ph_min)/2d0
+               ! In terms of [H]_new:
+               ! [H]_new = 10**(-ph_new)
+               !         = 10**(-(ph_prev + ph_min)/2d0)
+               !         = SQRT(10**(-(ph_prev + ph_min)))
+               !         = SQRT([H]_old*10**(-ph_min))
+               !         = SQRT([H]_old * zhmax)
+                  zh                = SQRT(zh_prev * zh_max(ji,jk))
+                  zh_lnfactor       = (zh - zh_prev)/zh_prev ! Required to test convergence below
+               ENDIF
+            ENDIF
+
+            zeqn_absmin(ji,jk) = MIN( ABS(zeqn), zeqn_absmin(ji,jk))
+
+            ! Stop iterations once |\delta{[H]}/[H]| < rdel
+            ! <=> |(zh - zh_prev)/zh_prev| = |EXP(-zeqn/(zdeqndh*zh_prev)) -1| < rdel
+            ! |EXP(-zeqn/(zdeqndh*zh_prev)) -1| ~ |zeqn/(zdeqndh*zh_prev)|
+            ! Alternatively:
+            ! |\Delta pH| = |zeqn/(zdeqndh*zh_prev*LOG(10))|
+            !             ~ 1/LOG(10) * |\Delta [H]|/[H]
+            !             < 1/LOG(10) * rdel
+
+            ! Hence |zeqn/(zdeqndh*zh)| < rdel
+
+            ! rdel <-- pp_rdel_ah_target
+            l_exitnow = (ABS(zh_lnfactor) < pp_rdel_ah_target)
+
+            IF(l_exitnow) THEN
+               rmask(ji,jk) = 0.
+            ENDIF
+
+            zhi(ji,jk) =  zh
+
+            IF(jn >= jp_maxniter_atgen) THEN
+               zhi(ji,jk) = -1._wp
+            ENDIF
+
+         ENDIF
+      END DO
+   END DO
+   END DO
+   !
+   IF( ln_timing )  CALL timing_stop('solve_at_general_sed')
+
+   END SUBROUTINE solve_at_general_sed
+
+   SUBROUTINE sed_chem_cst
+      !!---------------------------------------------------------------------
+      !!                     ***  ROUTINE sed_chem_cst  ***
+      !!
+      !! ** Purpose :   Sea water chemistry computed following MOCSY protocol
+      !!                Computation is done at the bottom of the ocean only
+      !!
+      !! ** Method  : - ...
+      !!---------------------------------------------------------------------
+      INTEGER  ::   ji
+      REAL(wp), DIMENSION(jpoce) :: saltprac, temps
+      REAL(wp) ::   ztkel, ztkel1, zt , zsal  , zsal2 , zbuf1 , zbuf2
+      REAL(wp) ::   ztgg , ztgg2, ztgg3 , ztgg4 , ztgg5
+      REAL(wp) ::   zpres, ztc  , zcl   , zcpexp, zoxy  , zcpexp2
+      REAL(wp) ::   zsqrt, ztr  , zlogt , zcek1, zc1, zplat
+      REAL(wp) ::   zis  , zis2 , zsal15, zisqrt, za1, za2
+      REAL(wp) ::   zckb , zck1 , zck2  , zckw  , zak1 , zak2  , zakb , zaksp0, zakw
+      REAL(wp) ::   zck1p, zck2p, zck3p, zcksi, zak1p, zak2p, zak3p, zaksi
+      REAL(wp) ::   zst  , zft  , zcks  , zckf  , zaksp1
+      REAL(wp) ::   total2free, free2SWS, total2SWS, SWS2total
+      !!---------------------------------------------------------------------
+      !
+      IF( ln_timing )   CALL timing_start('sed_chem_cst')
+      !
+      ! Computation of chemical constants require practical salinity
+      ! Thus, when TEOS08 is used, absolute salinity is converted to
+      ! practical salinity
+      ! -------------------------------------------------------------
+      IF (neos == -1) THEN
+         saltprac(:) = salt(:) * 35.0 / 35.16504
+      ELSE
+         saltprac(:) = temp(:)
+      ENDIF
+
+      !
+      ! Computations of chemical constants require in situ temperature
+      ! Here a quite simple formulation is used to convert
+      ! potential temperature to in situ temperature. The errors is less than
+      ! 0.04°C relative to an exact computation
+      ! ---------------------------------------------------------------------
+         DO ji = 1, jpoce
+            zpres = zkbot(ji) / 1000.
+            za1 = 0.04 * ( 1.0 + 0.185 * temp(ji) + 0.035 * (saltprac(ji) - 35.0) )
+            za2 = 0.0075 * ( 1.0 - temp(ji) / 30.0 )
+            temps(ji) = temp(ji) - za1 * zpres + za2 * zpres**2
+         END DO
 
       ! CHEMICAL CONSTANTS - DEEP OCEAN
-      !-------------------------------------
-      ! [chem constants]=mol/kg solution (or (mol/kg sol)2 for akws and aksp)
-
+      ! -------------------------------
       DO ji = 1, jpoce
-         ztkel   = temp(ji) + 273.16
-         ztc     = temp(ji)
-         ztc2    = ztc * ztc
-         zpres   = press(ji)
-         ! zqtt    = ztkel * 0.01
-         zsal    = salt(ji)
-         zsal2   = zsal * zsal 
-         zsqrt   = SQRT( zsal )
+         ! SET PRESSION ACCORDING TO SAUNDER (1980)
+         zc1 = 5.92E-3 
+         zpres = ((1-zc1)-SQRT(((1-zc1)**2)-(8.84E-6*zkbot(ji)))) / 4.42E-6
+         zpres = zpres / 10.0
+
+         ! SET ABSOLUTE TEMPERATURE
+         ztkel   = temps(ji) + 273.15
+         zsal    = saltprac(ji)
+         zsqrt  = SQRT( zsal )
          zsal15  = zsqrt * zsal
-         zlogt   = LOG( ztkel )
-         ztr     = 1./ ztkel
-         ! zis=ionic strength (ORNL/CDIAC-74, DOE 94,Dickson and Goyet)
-         zis     = 19.924 * zsal / ( 1000. - 1.005 * zsal )
-         zis2    = zis * zis
-         zisqrt  = SQRT( zis )
-
-
-         ! Density of Sea Water - F(temp,sal) [kg/m3]
-         zdens0 =  Ddsw(1) + Ddsw(2) * ztc + Ddsw(3) * ztc2 &
-                  + Ddsw(4) * ztc * ztc2 + Ddsw(5) * ztc2 * ztc2 &
-                  + Ddsw(6) * ztc * ztc2 * ztc2
-         zaw =  Adsw(1) + Adsw(2) * ztc + Adsw(3)* ztc2 + Adsw(4) * ztc * ztc2 &
-              + Adsw(5) * ztc2 * ztc2
-         zbw =  Bdsw(1) + Bdsw(2) * ztc + Bdsw(3) * ztc2
-         zcw =  Cdsw
-         densSW(ji) = zdens0 + zaw * zsal + zbw * zsal15 + zcw * zsal * zsal
-         densSW(ji) = densSW(ji) * 1E-3   ! to get dens in [kg/l]
-
-
-         ! FORMULA FOR CPEXP AFTER EDMOND AND GIESKES (1970) 
-         ! (REFERENCE TO CULBERSON AND PYTKOQICZ (1968) AS MADE IN BROECKER ET AL. (1982) 
-         ! IS INCORRECT; HERE RGAS IS TAKEN TENFOLD TO CORRECT FOR THE NOTATION OF pres  IN
-         ! DBAR INSTEAD OF BAR AND THE EXPRESSION FOR CPEXP IS MULTIPLIED BY LN(10.) 
-         ! TO ALLOW USE OF EXP-FUNCTION WITH BASIS E IN THE FORMULA FOR AKSPP 
-         ! (CF. EDMOND AND GIESKES (1970), P. 1285 AND P. 1286 (THE SMALL FORMULA ON P. 1286 
-         ! IS RIGHT AND CONSISTENT WITH THE SIGN IN PARTIAL MOLAR VOLUME CHANGE AS SHOWN ON P. 1285)
-         !-----------------------------------------------------------------------------------------
-         zcpexp  = zpres / ( rgas*ztkel )
+         zlogt  = LOG( ztkel )
+         ztr    = 1. / ztkel
+         zis    = 19.924 * zsal / ( 1000.- 1.005 * zsal )
+         zis2   = zis * zis
+         zisqrt = SQRT( zis )
+         ztc    = temps(ji)
+
+         ! CHLORINITY (WOOSTER ET AL., 1969)
+         zcl     = zsal / 1.80655
+
+         ! TOTAL SULFATE CONCENTR. [MOLES/kg soln]
+         zst     = 0.14 * zcl /96.062
+
+         ! TOTAL FLUORIDE CONCENTR. [MOLES/kg soln]
+         zft     = 0.000067 * zcl /18.9984
+
+         ! DISSOCIATION CONSTANT FOR SULFATES on free H scale (Dickson 1990)
+         zcks    = EXP(-4276.1 * ztr + 141.328 - 23.093 * zlogt         &
+         &         + (-13856. * ztr + 324.57 - 47.986 * zlogt) * zisqrt &
+         &         + (35474. * ztr - 771.54 + 114.723 * zlogt) * zis    &
+         &         - 2698. * ztr * zis**1.5 + 1776.* ztr * zis2         &
+         &         + LOG(1.0 - 0.001005 * zsal))
+
+         ! DISSOCIATION CONSTANT FOR FLUORIDES on free H scale (Dickson and Riley 79)
+         zckf    = EXP( 1590.2*ztr - 12.641 + 1.525*zisqrt   &
+         &         + LOG(1.0d0 - 0.001005d0*zsal)            &
+         &         + LOG(1.0d0 + zst/zcks))
+
+         ! DISSOCIATION CONSTANT FOR CARBONATE AND BORATE
+         zckb=  (-8966.90 - 2890.53*zsqrt - 77.942*zsal        &
+         &      + 1.728*zsal15 - 0.0996*zsal*zsal)*ztr         &
+         &      + (148.0248 + 137.1942*zsqrt + 1.62142*zsal)   &
+         &      + (-24.4344 - 25.085*zsqrt - 0.2474*zsal)      &
+         &      * zlogt + 0.053105*zsqrt*ztkel
+
+         ! DISSOCIATION COEFFICIENT FOR CARBONATE ACCORDING TO
+         ! MEHRBACH (1973) REFIT BY MILLERO (1995), seawater scale
+         zck1    = -1.0*(3633.86*ztr - 61.2172 + 9.6777*zlogt  &
+                   - 0.011555*zsal + 0.0001152*zsal*zsal)
+         zck2    = -1.0*(471.78*ztr + 25.9290 - 3.16967*zlogt      &
+                   - 0.01781*zsal + 0.0001122*zsal*zsal)
+
+         ! PKW (H2O) (MILLERO, 1995) from composite data
+         zckw    = -13847.26 * ztr + 148.9652 - 23.6521 * zlogt + ( 118.67 * ztr    &
+                   - 5.977 + 1.0495 * zlogt ) * zsqrt - 0.01615 * zsal
+
+         ! CONSTANTS FOR PHOSPHATE (MILLERO, 1995)
+         zck1p    = -4576.752*ztr + 115.540 - 18.453*zlogt   &
+         &          + (-106.736*ztr + 0.69171) * zsqrt       &
+         &          + (-0.65643*ztr - 0.01844) * zsal
+
+         zck2p    = -8814.715*ztr + 172.1033 - 27.927*zlogt  &
+         &          + (-160.340*ztr + 1.3566)*zsqrt          &
+         &          + (0.37335*ztr - 0.05778)*zsal
+
+         zck3p    = -3070.75*ztr - 18.126                    &
+         &          + (17.27039*ztr + 2.81197) * zsqrt       &
+         &          + (-44.99486*ztr - 0.09984) * zsal
+
+         ! CONSTANT FOR SILICATE, MILLERO (1995)
+         zcksi    = -8904.2*ztr  + 117.400 - 19.334*zlogt   &
+         &          + (-458.79*ztr + 3.5913) * zisqrt       &
+         &          + (188.74*ztr - 1.5998) * zis           &
+         &          + (-12.1652*ztr + 0.07871) * zis2       &
+         &          + LOG(1.0 - 0.001005*zsal)
+
+         ! APPARENT SOLUBILITY PRODUCT K'SP OF CALCITE IN SEAWATER
+         !       (S=27-43, T=2-25 DEG C) at pres =0 (atmos. pressure) (MUCCI 1983)
+         zaksp0  = -171.9065 -0.077993*ztkel + 2839.319*ztr + 71.595*LOG10( ztkel )   &
+         &         + (-0.77712 + 0.00284263*ztkel + 178.34*ztr) * zsqrt  &
+         &         - 0.07711*zsal + 0.0041249*zsal15
+
+         ! K1, K2 OF CARBONIC ACID, KB OF BORIC ACID, KW (H2O) (LIT.?)
+         zak1    = 10**(zck1) * total2SWS
+         zak2    = 10**(zck2) * total2SWS
+         zakb    = EXP( zckb ) * total2SWS
+         zakw    = EXP( zckw )
+         zaksp1  = 10**(zaksp0)
+         zak1p   = exp( zck1p )
+         zak2p   = exp( zck2p )
+         zak3p   = exp( zck3p )
+         zaksi   = exp( zcksi )
+         zckf    = zckf * total2SWS
+
+         ! FORMULA FOR CPEXP AFTER EDMOND & GIESKES (1970)
+         !        (REFERENCE TO CULBERSON & PYTKOQICZ (1968) AS MADE
+         !        IN BROECKER ET AL. (1982) IS INCORRECT; HERE RGAS IS
+         !        TAKEN TENFOLD TO CORRECT FOR THE NOTATION OF pres  IN
+         !        DBAR INSTEAD OF BAR AND THE EXPRESSION FOR CPEXP IS
+         !        MULTIPLIED BY LN(10.) TO ALLOW USE OF EXP-FUNCTION
+         !        WITH BASIS E IN THE FORMULA FOR AKSPP (CF. EDMOND
+         !        & GIESKES (1970), P. 1285-1286 (THE SMALL
+         !        FORMULA ON P. 1286 IS RIGHT AND CONSISTENT WITH THE
+         !        SIGN IN PARTIAL MOLAR VOLUME CHANGE AS SHOWN ON P. 1285))
+         zcpexp  = zpres / (rgas*ztkel)
          zcpexp2 = zpres * zcpexp
 
-
-         ! chlorinity (WOOSTER ET AL., 1969)
-         !---------------------------------------
-         zchl = zsal * salchl
-
-         ! total sulfate concentration [mol/kg soln]
-         ! --------------------------------------
-         zst = st1 * zchl * st2
-
-         ! total fluoride concentration [mol/kg soln]
-         ! --------------------------------------
-         zft = ft1 * zchl * ft2
-
-         ! dissociation constant for carbonate (Mehrback 74 - Dickson & Millero 87)
-         !---------------------------------------------------------------------------
-         zck1 = c10*ztr - c11 + c12*zlogt - c13*zsal + c14*zsal2
-         zck2 = c20*ztr + c21 - c22*zlogt - c23*zsal + c24*zsal2
-
-         ! dissociation constant for sulfates (Dickson 1990)
-         !--------------------------------------------------
-         zks = EXP(  ks0 + ks1*ztr + ks2*zlogt &
-            &    + ( ks3*ztr + ks4 + ks5*zlogt ) * zisqrt &
-            &    + ( ks6*ztr + ks7 + ks8*zlogt ) * zis    &
-            &    +   ks9*ztr*zis*zisqrt + ks10*ztr*zis2   &
-            &    +   LOG( ks11 + ks12*zsal ) )
-
-         ! dissociation constant for fluorides (Dickson and Riley 79)
-         !--------------------------------------------------
-         zkf = EXP( kf0 + kf1*ztr + kf2*zisqrt + LOG( kf3 + kf4*zsal ) )
-
-         ! dissociation constant for borates (Doe 94)
-         !--------------------------------------------------
-         zckb = (  cb0 + cb1*zsqrt + cb2*zsal + cb3*zsal15 + cb4*zsal2) * ztr &
-            &  + ( cb5 + cb6*zsqrt + cb7*zsal) &
-            &  + ( cb8 + cb9*zsqrt + cb10*zsal) * zlogt &
-            &  +   cb11*zsqrt*ztkel + LOG( ( 1. + zst/zks + zft/zkf ) / ( 1. + zst/zks ) ) 
-
-         ! PKW (H2O) (DICKSON AND RILEY, 1979)
-         !--------------------------------------
-         zckw =   cw0*ztr + cw1 + cw2*zlogt &
-            & +( cw3*ztr + cw4 + cw5*zlogt )* zsqrt + cw6*zsal
-         
-         ! For Phodphates (phosphoric acid) (DOE 1994)
-         !----------------------------------------------
-         zck1p = cp10 + cp11*ztr + cp12*zlogt + ( cp13*ztr + cp14 ) * zsqrt &
-            &      + ( cp15*ztr + cp16 ) * zsal
-         zck2p = cp20 + cp21*ztr + cp22*zlogt + ( cp23*ztr + cp24 ) * zsqrt &
-            &      + ( cp25*ztr + cp26 ) * zsal
-         zck3p = cp30 + cp31*ztr + ( cp32*ztr + cp33 ) *  zsqrt &
-            &      + ( cp34*ztr + cp35 ) * zsal
-
-         ! For silicates (DOE 1994) change to mol/kg soln) (OCMIP)
-         !--------------------------------------------------------
-         zcksi = cs10 + cs11*ztr + cs12*zlogt + ( cs13*ztr + cs14) * zisqrt &
-            &      + ( cs15*ztr + cs16 ) * zis &
-            &      + ( cs17*ztr + cs18 ) * zis2 &
-            &      + LOG( 1. + cs19*zsal ) + LOG( cs20 + cs21*zsal )
-
-         ! apparent solublity product K'SP of calcite in seawater
-         ! (S=27-43, T=2-25 DEG C) AT pres =0 (INGLE, 1975, EQ. 6)
-         ! prob: olivier a log = ln et C. Heize a LOG10(sal)
-         ! aksp0 = 1.E-7*(akcc1+akcc2*sal**(1./3.)+akcc3*log(sal)+akcc4*tkel*tkel)
-         ! aksp0 = 1.E-7*(akcc1+akcc2*sal**(1./3.)+akcc3*log10(sal)+akcc4*tkel*tkel)
-         !--------------------------------------------------------------------
-         zaksp0 = akcc1 + akcc2*ztkel + akcc3*ztr + akcc4 * LOG10(ztkel) &
-            &  + ( akcc5 + akcc6*ztkel+ akcc7*ztr ) * zsqrt &
-            &  +  akcc8*zsal + akcc9*zsal15
-
-         !K1, K2 of carbonic acid, KB of boric acid, KW (H2O)
-         !---------------------------------------------------
-         zak1   = 10**( -zck1  )
-         zak2   = 10**( -zck2  )
-         zakb   = EXP ( zckb   ) 
-         zakw   = EXP ( zckw   )
-         zksp   = 10**( zaksp0 )
-
-
-
-         ! KB of boric acid, K1,K2 of carbonic acid pressure correction 
-         ! after Culberson and  AND Pytkowicz (1968) (CF. BROECKER ET AL., 1982) Millero 95
-         !--------------------------------------------------------------------------------
-         zbuf1       = - ( devk1(1) + devk2(1)*ztc + devk3(1)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(1) + devk5(1)*ztc )
-         ak1s(ji)    = zak1 * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = -( devk1(2) + devk2(2)*ztc + devk3(2)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(2) + devk5(2)*ztc )
-         ak2s(ji)    = zak2 * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(3) + devk2(3)*ztc + devk3(3)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(3) + devk5(3) * ztc )
-         akbs(ji)    = zakb * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(4) + devk2(4)*ztc + devk3(4)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(4) + devk5(4)*ztc )
-         akws(ji)    = zakw * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-
-         ! APPARENT SOLUBILITY PRODUCT K''SP OF CALCITE (OR ARAGONITE)
-         ! AS FUNCTION OF PRESSURE FOLLWING EDMOND AND GIESKES (1970)
-         ! (P. 1285) AND BERNER (1976)
-         !-----------------------------------------------------------------
-         ! aksp(ji) = aksp0*exp(zcpexp*(devks-devkst*tc))
-         ! or following Mucci
-         zbuf1      = - ( devk1(5) + devk2(5)*ztc + devk3(5)*ztc2 )
-         zbuf2      = 0.5 *( devk4(5) + devk5(5)*ztc )
-         aksps(ji)   = zksp * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         ! For Phodphates (phosphoric acid) (DOE 1994)
-         !----------------------------------------------
-         zck1p = cp10 + cp11*ztr + cp12*zlogt + ( cp13*ztr + cp14 ) * zsqrt &
-            &      + ( cp15*ztr + cp16 ) * zsal
-         zck2p = cp20 + cp21*ztr + cp22*zlogt + ( cp23*ztr + cp24 ) * zsqrt &
-            &      + ( cp25*ztr + cp26 ) * zsal
-         zck3p = cp30 + cp31*ztr + ( cp32*ztr + cp33 ) *  zsqrt &
-            &      + ( cp34*ztr + cp35 ) * zsal
-
-         ! For silicates (DOE 1994) change to mol/kg soln) (OCMIP)
-         !--------------------------------------------------------
-         zcksi = cs10 + cs11*ztr + cs12*zlogt + ( cs13*ztr + cs14) * zisqrt &
-            &      + ( cs15*ztr + cs16 ) * zis &
-            &      + ( cs17*ztr + cs18 ) * zis2 &
-            &      + LOG( 1. + cs19*zsal ) + LOG( cs20 + cs21*zsal )
-
-
-         !K1, K2 of carbonic acid, KB of boric acid, KW (H2O)
-         !---------------------------------------------------
-         zak1p  = EXP ( zck1p  )
-         zak2p  = EXP ( zck2p  )
-         zak3p  = EXP ( zck3p  )
-         zaksil = EXP ( zcksi  )
-
-         zbuf1       = - ( devk1(3) + devk2(3)*ztc + devk3(3)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(3) + devk5(3)*ztc )
-         aksis(ji)     = zaksil * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(6) + devk2(6)*ztc + devk3(6)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(6) + devk5(6)*ztc )
-         ak1ps(ji)   = zak1p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
- 
-         zbuf1       = - ( devk1(7) + devk2(7)*ztc + devk3(7)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(7) + devk5(7)*ztc )
-         ak2ps(ji)   = zak2p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         zbuf1       = - ( devk1(8) + devk2(8)*ztc + devk3(8)*ztc2 )
-         zbuf2       = 0.5 * ( devk4(8) + devk5(8)*ztc )
-         ak3ps(ji)   = zak3p * EXP( zbuf1*zcpexp + zbuf2*zcpexp2 )
-
-         ! total borat concentration. [mol/l]
-         ! or from Millero 1995 [mol/l] : borat(l) = 0.000416_8*(sal/35._8)*densSW(l)
-         ! --------------------------------------------------------------------------
-         borats(ji) = bor1 * zchl * bor2 * densSW(ji)
-
-         ak12s  (ji) = ak1s (ji) * ak2s (ji)
-         ak12ps (ji) = ak1ps(ji) * ak2ps(ji)
-         ak123ps(ji) = ak1ps(ji) * ak2ps(ji) * ak3ps(ji)
-
-         calcon2(ji) = 0.01028 * ( zsal / 35. ) * densSW(ji)
-
-      ENDDO
-
-   END SUBROUTINE sed_chem_off
-
-#endif
-
-#else
-   !!======================================================================
-   !! MODULE sedchem  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_chem( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'trc_stp: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_chem
-
-   !!======================================================================
-
-#endif
+         ! KB OF BORIC ACID, K1,K2 OF CARBONIC ACID PRESSURE
+         !        CORRECTION AFTER CULBERSON AND PYTKOWICZ (1968)
+         !        (CF. BROECKER ET AL., 1982)
+
+         zbuf1  = -     ( devk10 + devk20 * ztc + devk30 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk40 + devk50 * ztc )
+         ak1s(ji) = zak1 * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk11 + devk21 * ztc + devk31 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk41 + devk51 * ztc )
+         ak2s(ji) = zak2 * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk12 + devk22 * ztc + devk32 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk42 + devk52 * ztc )
+         akbs(ji) = zakb * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk13 + devk23 * ztc + devk33 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk43 + devk53 * ztc )
+         akws(ji) = zakw * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk14 + devk24 * ztc + devk34 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk44 + devk54 * ztc )
+         aks3s(ji) = zcks * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk15 + devk25 * ztc + devk35 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk45 + devk55 * ztc )
+         akf3s(ji) = zckf * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk17 + devk27 * ztc + devk37 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk47 + devk57 * ztc )
+         ak1ps(ji) = zak1p * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk18 + devk28 * ztc + devk38 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk48 + devk58 * ztc )
+         ak2ps(ji) = zak2p * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         zbuf1  =     - ( devk110 + devk210 * ztc + devk310 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk410 + devk510 * ztc )
+         aksis(ji) = zaksi * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         ! CONVERT FROM DIFFERENT PH SCALES
+         total2free  = 1.0/(1.0 + zst/aks3s(ji))
+         free2SWS    = 1. + zst/aks3s(ji) + zft/akf3s(ji)
+         total2SWS   = total2free * free2SWS
+         SWS2total   = 1.0 / total2SWS
+
+         ! Convert to total scale
+         ak1s(ji)  = ak1s(ji)  * SWS2total
+         ak2s(ji)  = ak2s(ji)  * SWS2total
+         akbs(ji)  = akbs(ji)  * SWS2total
+         akws(ji)  = akws(ji)  * SWS2total
+         ak1ps(ji) = ak1ps(ji) * SWS2total
+         ak2ps(ji) = ak2ps(ji) * SWS2total
+         ak3ps(ji) = ak3ps(ji) * SWS2total
+         aksis(ji) = aksis(ji) * SWS2total
+         akf3s(ji) = akf3s(ji) / total2free
+
+         ! APPARENT SOLUBILITY PRODUCT K'SP OF CALCITE
+         !        AS FUNCTION OF PRESSURE FOLLOWING MILLERO
+         !        (P. 1285) AND BERNER (1976)
+         zbuf1  =     - ( devk16 + devk26 * ztc + devk36 * ztc * ztc )
+         zbuf2  = 0.5 * ( devk46 + devk56 * ztc )
+         aksps(ji) = zaksp1 * EXP( zbuf1 * zcpexp + zbuf2 * zcpexp2 )
+
+         ! TOTAL F, S, and BORATE CONCENTR. [MOLES/L]
+         borats(ji)   = 0.0002414 * zcl / 10.811
+         sulfats(ji)  = zst
+         fluorids(ji) = zft
+
+         ! Iron and SIO3 saturation concentration from ...
+         sieqs(ji) = EXP(  LOG( 10.) * ( 6.44 - 968. / ztkel )  ) * 1.e-6
+      END DO
+      !
+      IF( ln_timing )  CALL timing_stop('sed_chem_cst')
+      !
+   END SUBROUTINE sed_chem_cst
+
 
 END MODULE sedchem
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedco3.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedco3.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedco3.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedco3
-#if defined key_sed
    !!======================================================================
    !!              ***  MODULE  sedco3  ***
@@ -7,4 +6,6 @@
    !! * Modules used
    USE sed     ! sediment global variable
+   USE sedchem
+   USE lib_mpp         ! distribued memory computing library
 
 
@@ -15,10 +16,6 @@
    PUBLIC sed_co3     
 
-
-   !! * Module variables
-   REAL(wp) :: epsmax   =  1.e-12      ! convergence limite value
-
    !!----------------------------------------------------------------------
-   !!   OPA 9.0   !   NEMO Consortium   (2003)
+   !!   OPA 9.0   !   LODYC-IPSL   (2003)
    !!----------------------------------------------------------------------
 
@@ -45,155 +42,39 @@
       !! * Arguments
       INTEGER, INTENT(in)  :: kt   ! time step
-
       !
       !---Local variables
-      INTEGER  :: jiter, ji, jk, ipt  ! dummy loop indices
+      INTEGER  :: ji, jk           ! dummy loop indices
 
-      INTEGER  :: itermax             ! maximum number of Newton-Raphson iterations
-      INTEGER  :: itime               ! number of time to perform Newton-Raphson algorithm
-      LOGICAL  :: lconv = .FALSE.     ! flag for convergence
-      REAL(wp) :: brems               !  relaxation. parameter
-      REAL(wp) :: zresm, zresm1, zhipor_min 
-      REAL(wp) :: zalk, zbor, zsil, zpo4, zdic
-      REAL(wp) :: zh_old, zh_old2, zh_old3, zh_old4
-      REAL(wp) :: zuu, zvv, zduu, zdvv 
-      REAL(wp) :: zup, zvp, zdup, zdvp
-      REAL(wp) :: zah_old, zah_olds
-      REAL(wp) :: zh_new, zh_new2, zco3
-
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zhinit, zhi
      !!----------------------------------------------------------------------
 
+      IF( ln_timing )  CALL timing_start('sed_co3')
+
       IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' sed_co3 : carbonate ion and proton concentration calculation  '
-         WRITE(numsed,*) ' '
+         IF (lwp) WRITE(numsed,*) ' sed_co3 : carbonate ion and proton concentration calculation  '
+         IF (lwp) WRITE(numsed,*) ' '
       ENDIF
 
-      itermax     = 30
-      brems       = 1.
-      itime       = 0
+      DO jk = 1, jpksed
+         zhinit(:,jk)   = hipor(:,jk) / densSW(:)
+      END DO
 
+      !     -------------------------------------------
+      !     COMPUTE [CO3--] and [H+] CONCENTRATIONS
+      !     -------------------------------------------
+
+      CALL solve_at_general_sed(zhinit, zhi)
 
       DO jk = 1, jpksed
-         DO WHILE( itime <= 2 )
-            lconv  = .FALSE.
-            IF( itime > 0 ) THEN  
-               ! increase max number of iterations and relaxation parameter
-               itermax = 200
-!!               brems   = 0.3
-               IF( itime == 2 ) hipor(1:jpoce,jk) = 3.e-9 ! re-initilazation of [H] values
-            ENDIF
+         DO ji = 1, jpoce
+            co3por(ji,jk) = pwcp(ji,jk,jwdic) * ak1s(ji) * ak2s(ji) / (zhi(ji,jk)**2   &
+            &               + ak1s(ji) * zhi(ji,jk) + ak1s(ji) * ak2s(ji) + rtrn )
+            hipor(ji,jk)  = zhi(ji,jk) * densSW(ji)
+         END DO
+      END DO
 
-iflag:      DO jiter = 1, itermax
-
-                ! Store previous hi field.   
-               zresm = -1.e10
-               ipt = 1
-               DO ji = 1, jpoce
-                  ! dissociation constant are in mol/kg of solution
-                  ! convert pwcp concentration [mol/l] in mol/kg for solution
-                  zalk    = pwcp(ji,jk,jwalk) / densSW(ji)
-                  zh_old  = hipor(ji,jk) / densSW(ji)
-                  zh_old2 = zh_old  * zh_old
-                  zh_old3 = zh_old2 * zh_old
-                  zh_old4 = zh_old3 * zh_old
-                  zbor    = borats(ji) / densSW(ji)
-                  zsil    = pwcp(ji,jk,jwsil) / densSW(ji)
-                  zpo4    = pwcp(ji,jk,jwpo4) / densSW(ji)
-                  zdic    = pwcp(ji,jk,jwdic) / densSW(ji)               
-                  ! intermediate calculation 
-                  zuu     = zdic * ( ak1s(ji) / zh_old + 2.* ak12s(ji) / zh_old2 )
-                  zvv     = 1. + ak1s(ji) / zh_old + ak12s(ji) / zh_old2
-                  zduu    = zdic * ( -ak1s(ji) / zh_old2 - 4. * ak12s(ji) / zh_old3 )
-                  zdvv    = -ak1s(ji) / zh_old2 - 2. * ak12s(ji) / zh_old3
-                  zup     = zpo4 * ( ak12ps(ji) / zh_old2 + 2. * ak123ps(ji) / zh_old3 - 1.)
-                  zvp     = 1. + ak1ps(ji) / zh_old + ak12ps(ji) / zh_old2 + ak123ps(ji) / zh_old3
-                  zdup    = zpo4 * ( -2. * ak12ps(ji) / zh_old3 - 6. * ak123ps(ji) / zh_old4 )
-                  zdvp    = -ak1ps(ji) / zh_old2 - 2.* ak12ps(ji) / zh_old3 - 3. * ak123ps(ji) / zh_old4
-                  
-                  zah_old  = zuu / zvv + zbor / ( 1. + zh_old / akbs(ji) ) + &
-                     &      akws(ji) / zh_old - zh_old + zsil / ( 1. + zh_old / aksis(ji) ) + &
-                     &      zup / zvp
-                  
-                  zah_olds = ( ( zduu * zvv - zdvv * zuu ) / ( zvv * zvv ) )      - &
-                     &        zbor / akbs(ji) * ( 1. + zh_old / akbs(ji) )**(-2) - &
-                     &        akws(ji) / zh_old2 - 1. -                            &
-                     &        zsil / aksis(ji) * ( 1. + zh_old / aksis(ji) )**(-2) + &
-                     &       ( ( zdup * zvp - zdvp * zup ) / ( zvp * zvp ) )
-                  !
-                  zh_new = zh_old - brems * ( zah_old - zalk ) / zah_olds
-                  ! 
-                  zresm1 = ABS( zh_new - zh_old )
-                  IF( zresm1 > zresm ) THEN 
-                     zresm = zresm1  
-                  ENDIF
-                  !
-                  zh_new2  = zh_new * zh_new
-                  zco3   = ( ak12s(ji) * zdic ) / ( ak12s(ji) + ak1s(ji) * zh_new + zh_new2)
-                  ! again in mol/l
-                  hipor (ji,jk) = zh_new * densSW(ji)
-                  co3por(ji,jk) = zco3   * densSW(ji)
-                  
-               ENDDO  ! end loop ji
-               
-               ! convergence test
-               IF( zresm <= epsmax ) THEN
-                  lconv = .TRUE.
-                  !minimum value of hipor
-                  zhipor_min = MINVAL( hipor(1:jpoce,jk ) )
-                  EXIT iflag
-               ENDIF
-
-            ENDDO iflag
-
-            IF( lconv ) THEN
-!               WRITE(numsed,*) ' convergence after iter =', jiter, ' iterations ;  res =',zresm  
-               IF( zhipor_min < 0. ) THEN 
-                  IF ( itime == 0 ) THEN
-!                     WRITE(numsed,*) '    but hipor < 0 ; try one more time for jk = ', jk 
-!                     WRITE(numsed,*) '    with re-initialization of initial PH field '       
-                     itime = 2
-                  ELSE
-!                     WRITE(numsed,*) ' convergence after iter =', jiter, ' iterations ;  res =',zresm 
-!                     WRITE(numsed,*) '    but hipor < 0, again for second time for jk = ', jk 
-!                     WRITE(numsed,*) ' We stop : STOP '
-                     STOP
-                  ENDIF
-               ELSE
-!                  WRITE(numsed,*) ' successfull convergence for level jk = ',jk,&
-!                     &               '  after iter =', jiter, ' iterations ;  res =',zresm  
-!                  WRITE(numsed,*) ' '
-                  itime = 3
-               ENDIF
-            ELSE
-               itime = itime + 1
-               WRITE(numsed,*) ' No convergence for jk = ', jk, ' after ', itime, '  try'            
-               IF ( itime == 1 ) THEN
-                  WRITE(numsed,*) ' try one more time with more iterations and higher relax. value'
-               ELSE IF ( itime == 2 ) THEN
-                  WRITE(numsed,*) ' try one more time for with more iterations, higher relax. value'               
-                  WRITE(numsed,*) ' and with re-initialization of initial PH field ' 
-               ELSE       
-                  WRITE(numsed,*) ' No more... we stop '
-                  STOP
-               ENDIF
-            ENDIF
-         ENDDO ! End of WHILE LOOP
-     ENDDO
+     IF( ln_timing )  CALL timing_stop('sed_co3')
 
    END SUBROUTINE sed_co3
-#else
-   !!======================================================================
-   !! MODULE sedco3  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_co3( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_co3: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_co3
-
-   !!======================================================================
-
-#endif
 
 END MODULE sedco3
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddiff.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddiff.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddiff.F90	(revision 10321)
@@ -0,0 +1,120 @@
+MODULE seddiff
+   !!======================================================================
+   !!              ***  MODULE  seddsr  ***
+   !!    Sediment : dissolution and reaction in pore water related 
+   !!    related to organic matter
+   !!=====================================================================
+   !! * Modules used
+   USE sed     ! sediment global variable
+   USE sed_oce
+   USE sedmat  ! linear system of equations
+   USE sedini
+   USE lib_mpp         ! distribued memory computing library
+   USE lib_fortran
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC sed_diff
+
+   !! * Module variables
+
+   !! $Id$
+CONTAINS
+   
+   SUBROUTINE sed_diff( kt, knt ) 
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_diff  ***
+      !! 
+      !!  ** Purpose :  computes pore water diffusion
+      !!
+      !!  ** Methode :  implicit computation of undersaturation
+      !!               resulting from diffusive pore water transport.
+      !!
+      !!  ** Remarks :
+      !!              - undersaturation : deviation from saturation concentration
+      !!   History :
+      !!        !  98-08 (E. Maier-Reimer, Christoph Heinze )  Original code
+      !!        !  04-10 (N. Emprin, M. Gehlen ) f90
+      !!        !  06-04 (C. Ethe)  Re-organization
+      !!        !  19-08 (O. Aumont) Debugging and improvement of the model
+      !!----------------------------------------------------------------------
+      !! Arguments
+      INTEGER, INTENT(in) ::   kt, knt       ! number of iteration
+      ! --- local variables
+      INTEGER :: ji, jk, js   ! dummy looop indices
+
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zrearat1, zrearat2   ! reaction rate in pore water
+      !!
+      !!----------------------------------------------------------------------
+
+      IF( ln_timing )  CALL timing_start('sed_diff')
+!
+      IF( kt == nitsed000 .AND. knt == 1 ) THEN
+         IF (lwp) THEN
+            WRITE(numsed,*) ' sed_diff : pore-water diffusion '
+            WRITE(numsed,*) ' '
+         ENDIF
+      ENDIF
+
+     ! Initializations
+     !----------------------
+      zrearat1(:,:)   = 0.
+      zrearat2(:,:) = 0.
+
+      !---------------------------
+      ! Solves PO4 diffusion 
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwpo4, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwpo4), dtsed2 / 2.0 )
+
+      !---------------------------
+      ! Solves NH4 diffusion 
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwnh4, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwnh4), dtsed2 / 2.0 )
+
+      !---------------------------
+      ! Solves Fe2+ diffusion 
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwfe2, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwfe2), dtsed2 / 2.0 )
+
+      !---------------------------
+      ! Solves H2S diffusion 
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwh2s, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwh2s), dtsed2 / 2.0  )
+
+      !---------------------------
+      ! Solves SO4 diffusion 
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwso4, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwso4), dtsed2 / 2.0 )
+
+      !---------------------------
+      ! Solves O2 diffusion
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwoxy, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwoxy), dtsed2 / 2.0 )
+
+      !---------------------------
+      ! Solves NO3 diffusion
+      !----------------------------
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwno3, jpoce, jpksed, zrearat1, zrearat2, pwcp(:,:,jwno3), dtsed2 / 2.0 )
+
+      CALL sed_mat( jwdic, jpoce, jpksed, zrearat1, zrearat2, sedligand(:,:), dtsed2 / 2.0 )
+
+      IF( ln_timing )  CALL timing_stop('sed_diff')
+!      
+   END SUBROUTINE sed_diff
+
+END MODULE seddiff
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddsr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddsr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddsr.F90	(revision 10321)
@@ -1,12 +1,17 @@
 MODULE seddsr
-#if defined key_sed
    !!======================================================================
    !!              ***  MODULE  seddsr  ***
-   !!    Sediment : dissolution and reaction in pore water
+   !!    Sediment : dissolution and reaction in pore water related 
+   !!    related to organic matter
    !!=====================================================================
    !! * Modules used
    USE sed     ! sediment global variable
-   USE sedmat  ! linear system of equations
-   USE sedco3  ! carbonate ion and proton concentration 
+   USE sed_oce
+   USE sedini
+   USE lib_mpp         ! distribued memory computing library
+   USE lib_fortran
+
+   IMPLICIT NONE
+   PRIVATE
 
    PUBLIC sed_dsr
@@ -14,14 +19,13 @@
    !! * Module variables
 
-   REAL(wp), DIMENSION(:), ALLOCATABLE, PUBLIC :: cons_o2
-   REAL(wp), DIMENSION(:), ALLOCATABLE, PUBLIC :: cons_no3
-   REAL(wp), DIMENSION(:), ALLOCATABLE, PUBLIC :: sour_no3
-   REAL(wp), DIMENSION(:), ALLOCATABLE, PUBLIC :: sour_c13
-   REAL(wp), DIMENSION(:), ALLOCATABLE, PUBLIC ::  dens_mol_wgt  ! molecular density 
+   REAL(wp) :: zadsnh4
+   REAL(wp), DIMENSION(jpsol), PUBLIC      :: dens_mol_wgt  ! molecular density 
+   REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zvolc    ! temp. variables
+
 
    !! $Id$
 CONTAINS
    
-   SUBROUTINE sed_dsr( kt ) 
+   SUBROUTINE sed_dsr( kt, knt ) 
       !!----------------------------------------------------------------------
       !!                   ***  ROUTINE sed_dsr  ***
@@ -29,13 +33,9 @@
       !!  ** Purpose :  computes pore water dissolution and reaction
       !!
-      !!  ** Methode :  implicit simultaneous computation of undersaturation
-      !!               resulting from diffusive pore water transport and chemical
-      !!               pore water reactions. Solid material is consumed according
-      !!               to redissolution and remineralisation
-      !!
-      !!  ** Remarks :
-      !!              - undersaturation : deviation from saturation concentration
-      !!              - reaction rate   : sink of undersaturation from dissolution
-      !!                                 of solid material 
+      !!  ** Methode :  Computation of the redox reactions in sediment.
+      !!                The main redox reactions are solved in sed_dsr whereas
+      !!                the secondary reactions are solved in sed_dsr_redoxb.
+      !!                A strand spliting approach is being used here (see 
+      !!                sed_dsr_redoxb for more information). 
       !!
       !!   History :
@@ -43,76 +43,55 @@
       !!        !  04-10 (N. Emprin, M. Gehlen ) f90
       !!        !  06-04 (C. Ethe)  Re-organization
+      !!        !  19-08 (O. Aumont) Debugging and improvement of the model.
+      !!                             The original method is replaced by a 
+      !!                              Strand splitting method which deals 
+      !!                              well with stiff reactions.
       !!----------------------------------------------------------------------
       !! Arguments
-      INTEGER, INTENT(in) ::   kt       ! number of iteration
+      INTEGER, INTENT(in) ::   kt, knt       ! number of iteration
       ! --- local variables
-      INTEGER :: ji, jk, js, jw   ! dummy looop indices
-      INTEGER :: nv               ! number of variables in linear tridiagonal eq
-
-      REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zrearat    ! reaction rate in pore water
-      REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zundsat    ! undersaturation ; indice jpwatp1 is for calcite   
-      REAL(wp), DIMENSION(:    ), ALLOCATABLE :: zmo2_0, zmo2_1  ! temp. array for mass balance calculation
-      REAL(wp), DIMENSION(:    ), ALLOCATABLE :: zmno3_0, zmno3_1, zmno3_2
-      REAL(wp), DIMENSION(:    ), ALLOCATABLE :: zmc13_0, zmc13_1, zmc13_2, zmc13_3
-      REAL(wp), DIMENSION(:,:,:), ALLOCATABLE :: zvolc    ! temp. variables
+      INTEGER :: ji, jk, js, jw, jn   ! dummy looop indices
+
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zrearat1, zrearat2, zrearat3    ! reaction rate in pore water
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zundsat    ! undersaturation ; indice jpwatp1 is for calcite   
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zkpoc, zkpos, zkpor, zlimo2, zlimno3, zlimso4, zlimfeo    ! undersaturation ; indice jpwatp1 is for calcite   
+      REAL(wp), DIMENSION(jpoce)        :: zsumtot
       REAL(wp)  ::  zsolid1, zsolid2, zsolid3, zvolw, zreasat
-
+      REAL(wp)  ::  zsatur, zsatur2, znusil, zkpoca, zkpocb, zkpocc
+      REAL(wp)  ::  zratio, zgamma, zbeta, zlimtmp, zundsat2
       !!
       !!----------------------------------------------------------------------
 
-      IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' sed_dsr : Dissolution reaction '
-         WRITE(numsed,*) ' '
-         ! 
-         ALLOCATE( dens_mol_wgt((jpoce) ) 
-         dens_mol_wgt(1:jpsol) = dens / mol_wgt(1:jpsol)
-         ! 
-         ALLOCATE( cons_o2 (jpoce) ) ;   ALLOCATE( cons_no3(jpoce) ) 
-         ALLOCATE( sour_no3(jpoce) ) ;   ALLOCATE( sour_c13(jpoce) )  
+      IF( ln_timing )  CALL timing_start('sed_dsr')
+!
+      IF( kt == nitsed000 .AND. knt == 1 ) THEN
+         IF (lwp) THEN
+            WRITE(numsed,*) ' sed_dsr : Dissolution reaction '
+            WRITE(numsed,*) ' '
+         ENDIF
       ENDIF
 
-      ! Initialization of data for mass balance calculation
-      !---------------------------------------------------
-
-      tokbot(:,:)  = 0.
-      cons_o2 (:)  = 0. 
-      cons_no3(:)  = 0.  
-      sour_no3(:)  = 0.  
-      sour_c13(:)  = 0.       
-   
-      ! Initializations
-      !----------------------
-      ALLOCATE( zmo2_0 (jpoce) ) ;  ALLOCATE( zmo2_1 (jpoce) ) 
-      ALLOCATE( zmno3_0(jpoce) ) ;  ALLOCATE( zmno3_1(jpoce) )  ;  ALLOCATE( zmno3_2(jpoce) ) 
-      ALLOCATE( zmc13_0(jpoce) ) ;  ALLOCATE( zmc13_1(jpoce) )  ;  ALLOCATE( zmc13_2(jpoce) ) ;  ALLOCATE( zmc13_3(jpoce) ) 
-
-      zmo2_0 (:) = 0.  ; zmo2_1 (:) = 0.
-      zmno3_0(:) = 0.  ; zmno3_1(:) = 0.  ;  zmno3_2(:) = 0.
-      zmc13_0(:) = 0.  ; zmc13_1(:) = 0.  ;  zmc13_2(:) = 0.  ; zmc13_3(:) = 0.
+     ! Initializations
+     !----------------------
       
-      ALLOCATE( zrearat(jpoce,jpksed,3) ) ;  ALLOCATE( zundsat(jpoce,jpksed,3) )      
-      zrearat(:,:,:)   = 0.    ;   zundsat(:,:,:) = 0. 
-
-
-      ALLOCATE( zvolc(jpoce,jpksed,jpsol) ) 
-      zvolc(:,:,:)   = 0.
-
-      !--------------------------------------------------------------------
-      ! Temporary accomodation to take account of  particule rain deposition
-      !---------------------------------------------------------------------
-      
-      
-      ! 1. Change of geometry
-      !    Increase of dz3d(2) thickness : dz3d(2) = dz3d(2)+dzdep
-      !    Warning : no change for dz(2)
-      !---------------------------------------------------------
-      dz3d(1:jpoce,2) = dz3d(1:jpoce,2) + dzdep(1:jpoce)
-
-      
-      ! New values for volw3d(:,2) and vols3d(:,2)
-      ! Warning : no change neither for volw(2) nor  vols(2)
-      !------------------------------------------------------
-      volw3d(1:jpoce,2) = dz3d(1:jpoce,2) * por(2)
-      vols3d(1:jpoce,2) = dz3d(1:jpoce,2) * por1(2)
+      zrearat1(:,:)   = 0.    ;   zundsat(:,:) = 0. ; zkpoc(:,:) = 0.
+      zlimo2 (:,:)    = 0.    ;   zlimno3(:,:) = 0. ; zrearat2(:,:) = 0.
+      zlimso4(:,:)    = 0.    ;   zkpor(:,:)   = 0. ; zrearat3(:,:) = 0.
+      zkpos  (:,:)    = 0.
+      zsumtot(:)      = rtrn
+  
+      ALLOCATE( zvolc(jpoce, jpksed, jpsol) )
+      zvolc(:,:,:)    = 0.
+      zadsnh4 = 1.0 / ( 1.0 + adsnh4 )
+
+      ! Inhibition terms for the different redox equations
+      ! --------------------------------------------------
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            zkpoc(ji,jk) = reac_pocl 
+            zkpos(ji,jk) = reac_pocs
+            zkpor(ji,jk) = reac_pocr
+         END DO
+      END DO
 
       ! Conversion of volume units
@@ -120,160 +99,104 @@
       DO js = 1, jpsol
          DO jk = 1, jpksed
-            DO ji = 1, jpoce    
+            DO ji = 1, jpoce
                zvolc(ji,jk,js) = ( vols3d(ji,jk) * dens_mol_wgt(js) ) /  &
-                  &              ( volw3d(ji,jk) * 1.e-3 )     
+                  &              ( volw3d(ji,jk) * 1.e-3 )
             ENDDO
          ENDDO
       ENDDO
 
-      ! 2. Change of previous solid fractions (due to volum changes) for k=2
-      !---------------------------------------------------------------------
-
-      DO js = 1, jpsol
-         DO ji = 1, jpoce
-            solcp(ji,2,js) = solcp(ji,2,js) * dz(2) / dz3d(ji,2)
-         ENDDO
-      END DO
-
-      ! 3. New solid fractions (including solid rain fractions) for k=2  
-      !------------------------------------------------------------------   
-      DO js = 1, jpsol
-         DO ji = 1, jpoce
-            solcp(ji,2,js) = solcp(ji,2,js) + &
-            &           ( rainrg(ji,js) / raintg(ji) ) * ( dzdep(ji) / dz3d(ji,2) )
-            ! rainrm are temporary cancel
-            rainrm(ji,js) = 0.
-         END DO
-      ENDDO
-
-      ! 4.  Adjustment of bottom water concen.(pwcp(1)): 
-      !     We impose that pwcp(2) is constant. Including dzdep in dz3d(:,2) we assume 
-      !     that dzdep has got a porosity of por(2). So pore water volum of jk=2 increase.
-      !     To keep pwcp(2) cste we must compensate this "increase" by a slight adjusment
-      !     of bottom water concentration.
-      !     This adjustment is compensate at the end of routine
-      !-------------------------------------------------------------
-      DO jw = 1, jpwat
-         DO ji = 1, jpoce
-            pwcp(ji,1,jw) = pwcp(ji,1,jw) - &
-               &            pwcp(ji,2,jw) * dzdep(ji) * por(2) / dzkbot(ji)
-         END DO
-      ENDDO
-
- 
       !----------------------------------------------------------
-      ! 5.  Beginning of  Pore Water diffusion and solid reaction
+      ! 5.  Beginning of solid reaction
       !---------------------------------------------------------
-      
-      !-----------------------------------------------------------------------------
-      ! For jk=2,jpksed, and for couple 
-      !  1 : jwsil/jsopal  ( SI/Opal )
-      !  2 : jsclay/jsclay ( clay/clay ) 
-      !  3 : jwoxy/jspoc   ( O2/POC )
-      !  reaction rate is a function of solid=concentration in solid reactif in [mol/l] 
-      !  and undersaturation in [mol/l].
-      !  Solid weight fractions should be in ie [mol/l])
-      !  second member and solution are in zundsat variable
-      !-------------------------------------------------------------------------
-
-      !number of variables
-      nv  = 3
-     
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            ! For Silicic Acid and clay
-            zundsat(ji,jk,1) = sat_sil   - pwcp(ji,jk,jwsil)
-            zundsat(ji,jk,2) = sat_clay
-            ! For O2
-            zundsat(ji,jk,3) = pwcp(ji,jk,jwoxy) / so2ut 
-         ENDDO
-      ENDDO
-      
       
       ! Definition of reaction rates [rearat]=sans dim 
       ! For jk=1 no reaction (pure water without solid) for each solid compo
-      DO ji = 1, jpoce
-         zrearat(ji,1,:) = 0.
-      ENDDO
-
+      zrearat1(:,:) = 0.
+      zrearat2(:,:) = 0.
+      zrearat3(:,:) = 0.
+
+      zundsat(:,:) = pwcp(:,:,jwoxy)
+
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zlimo2(ji,jk) = 1.0 / ( zundsat(ji,jk) + xksedo2 )
+            zsolid1 = zvolc(ji,jk,jspoc)  * solcp(ji,jk,jspoc)
+            zsolid2 = zvolc(ji,jk,jspos)  * solcp(ji,jk,jspos)
+            zsolid3 = zvolc(ji,jk,jspor)  * solcp(ji,jk,jspor)
+            zkpoca  = zkpoc(ji,jk) * zlimo2(ji,jk)
+            zkpocb  = zkpos(ji,jk) * zlimo2(ji,jk)
+            zkpocc  = zkpor(ji,jk) * zlimo2(ji,jk)
+            zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+            &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+            zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+            &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+            zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+            &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+         ENDDO
+      ENDDO
 
       ! left hand side of coefficient matrix
-      DO jk = 2, jpksed
-         DO ji = 1, jpoce
-            zsolid1 = zvolc(ji,jk,jsopal) * solcp(ji,jk,jsopal)
-            zsolid2 = zvolc(ji,jk,jsclay) * solcp(ji,jk,jsclay)
-            zsolid3 = zvolc(ji,jk,jspoc)  * solcp(ji,jk,jspoc)
-
-            zrearat(ji,jk,1)  = ( reac_sil * dtsed * zsolid1 ) / &
-               &                ( 1. + reac_sil * dtsed * zundsat(ji,jk,1 ) )
-            zrearat(ji,jk,2)  = ( reac_clay * dtsed * zsolid2 ) / &
-               &                ( 1. + reac_clay * dtsed * zundsat(ji,jk,2 ) )
-            zrearat(ji,jk,3)  = ( reac_poc  * dtsed * zsolid3 ) / &
-               &                ( 1. + reac_poc  * dtsed * zundsat(ji,jk,3 ) )
-         ENDDO
-      ENDDO
-
-
-      CALL sed_mat( nv, jpoce, jpksed, zrearat, zundsat )
-
+!      DO jn = 1, 5
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+jflag1:     DO jn = 1, 10
+               zsolid1 = zvolc(ji,jk,jspoc)  * solcp(ji,jk,jspoc)
+               zsolid2 = zvolc(ji,jk,jspos)  * solcp(ji,jk,jspos)
+               zsolid3 = zvolc(ji,jk,jspor)  * solcp(ji,jk,jspor)
+               zbeta   = xksedo2 - pwcp(ji,jk,jwoxy) + so2ut * ( zrearat1(ji,jk)    &
+               &         + zrearat2(ji,jk) + zrearat3(ji,jk) )
+               zgamma = - xksedo2 * pwcp(ji,jk,jwoxy)
+               zundsat2 = zundsat(ji,jk)
+               zundsat(ji,jk) = ( - zbeta + SQRT( zbeta**2 - 4.0 * zgamma ) ) / 2.0
+               zlimo2(ji,jk) = 1.0 / ( zundsat(ji,jk) + xksedo2 )
+               zkpoca  = zkpoc(ji,jk) * zlimo2(ji,jk)
+               zkpocb  = zkpos(ji,jk) * zlimo2(ji,jk)
+               zkpocc  = zkpor(ji,jk) * zlimo2(ji,jk)
+               zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+               &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+               zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+               &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+               zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+               &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+               IF ( ABS( (zundsat(ji,jk)-zundsat2)/(zundsat2+rtrn)) < 1E-8 ) THEN
+                  EXIT jflag1
+               ENDIF
+            END DO jflag1
+         END DO
+      END DO
 
       ! New solid concentration values (jk=2 to jksed) for each couple 
-      DO js = 1, nv
-         DO jk = 2, jpksed
-            DO ji = 1, jpoce
-               zreasat = zrearat(ji,jk,js) * zundsat(ji,jk,js) / zvolc(ji,jk,js)
-               solcp(ji,jk,js) = solcp(ji,jk,js) - zreasat
-            ENDDO
-         ENDDO
-      ENDDO
-      ! mass of O2/NO3 before POC remin. for mass balance check 
-      ! det. of o2 consomation/NO3 production Mc13
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zvolw = volw3d(ji,jk) * 1.e-3
-            zmo2_0 (ji)  = zmo2_0 (ji) + pwcp(ji,jk,jwoxy) * zvolw
-            zmno3_0(ji)  = zmno3_0(ji) + pwcp(ji,jk,jwno3) * zvolw
-            zmc13_0(ji)  = zmc13_0(ji) + pwcp(ji,jk,jwc13) * zvolw
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zlimo2(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspoc)
+            solcp(ji,jk,jspoc) = solcp(ji,jk,jspoc) - zreasat
+            zreasat = zrearat2(ji,jk) * zlimo2(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspos)
+            solcp(ji,jk,jspos) = solcp(ji,jk,jspos) - zreasat
+            zreasat = zrearat3(ji,jk) * zlimo2(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspor)
+            solcp(ji,jk,jspor) = solcp(ji,jk,jspor) - zreasat
          ENDDO
       ENDDO
 
       ! New pore water concentrations    
-      DO jk = 1, jpksed
+      DO jk = 2, jpksed
          DO ji = 1, jpoce
             ! Acid Silicic 
-            pwcp(ji,jk,jwsil)  = sat_sil - zundsat(ji,jk,1)            
-            ! For O2 (in mol/l)
-            pwcp(ji,jk,jwoxy)  = zundsat(ji,jk,3) * so2ut 
-            zreasat = zrearat(ji,jk,3) * zundsat(ji,jk,3)    ! oxygen         
+            pwcp(ji,jk,jwoxy)  = zundsat(ji,jk)
+            zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) * zlimo2(ji,jk) * zundsat(ji,jk)    ! oxygen         
             ! For DIC
             pwcp(ji,jk,jwdic)  = pwcp(ji,jk,jwdic) + zreasat
-            ! For nitrates
-            pwcp(ji,jk,jwno3)  = pwcp(ji,jk,jwno3) + zreasat * srno3            
+            zsumtot(ji) = zsumtot(ji) + zreasat / dtsed2 * volw3d(ji,jk) * 1.e-3 * 86400. * 365. * 1E3
             ! For Phosphate (in mol/l)
-            pwcp(ji,jk,jwpo4)  = pwcp(ji,jk,jwpo4) + zreasat * spo4r            
+            pwcp(ji,jk,jwpo4)  = pwcp(ji,jk,jwpo4) + zreasat * spo4r
+            ! For iron (in mol/l)
+            pwcp(ji,jk,jwfe2)  = pwcp(ji,jk,jwfe2) + fecratio(ji) * zreasat
             ! For alkalinity
-            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) - zreasat * ( srno3 + 2.* spo4r )           
-            ! For DIC13
-            pwcp(ji,jk,jwc13)  = pwcp(ji,jk,jwc13) + zreasat * rc13P * pdb
-         ENDDO
-      ENDDO
-
-
-      ! Mass of O2 for mass balance check and det. of o2 consomation
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zvolw = volw3d(ji,jk) * 1.e-3
-            zmo2_1 (ji) = zmo2_1 (ji) + pwcp(ji,jk,jwoxy) * zvolw
-            zmno3_1(ji) = zmno3_1(ji) + pwcp(ji,jk,jwno3) * zvolw
-            zmc13_1(ji) = zmc13_1(ji) + pwcp(ji,jk,jwc13) * zvolw
-         ENDDO
-      ENDDO
-
-      DO ji = 1, jpoce
-         cons_o2 (ji) = zmo2_0 (ji) - zmo2_1 (ji)
-         sour_no3(ji) = zmno3_1(ji) - zmno3_0(ji)     
-         sour_c13(ji) = zmc13_1(ji) - zmc13_0(ji) 
-      ENDDO
- 
+            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + zreasat * ( srno3 * zadsnh4 - 2.* spo4r )
+            ! Ammonium
+            pwcp(ji,jk,jwnh4)  = pwcp(ji,jk,jwnh4) + zreasat * srno3 * zadsnh4
+            ! Ligands
+            sedligand(ji,jk)   = sedligand(ji,jk) + ratligc * zreasat - reac_ligc * sedligand(ji,jk)
+         ENDDO
+      ENDDO
 
       !--------------------------------------------------------------------
@@ -282,25 +205,57 @@
       !--------------------------------------------------------------------
 
-      nv = 1
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zundsat(ji,jk,1) = pwcp(ji,jk,jwno3) / srDnit
-         ENDDO
-      ENDDO
-      DO jk = 2, jpksed
-         DO ji = 1, jpoce
-            IF( pwcp(ji,jk,jwoxy) < sthrO2 ) THEN
+      zrearat1(:,:) = 0.
+      zrearat2(:,:) = 0.
+      zrearat3(:,:) = 0.
+
+      zundsat(:,:) = pwcp(:,:,jwno3)
+
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zlimno3(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) / ( zundsat(ji,jk) + xksedno3 )
+            zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
+            zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+            zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+            zkpoca = zkpoc(ji,jk) * zlimno3(ji,jk)
+            zkpocb = zkpos(ji,jk) * zlimno3(ji,jk)
+            zkpocc = zkpor(ji,jk) * zlimno3(ji,jk)
+            zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+            &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+            zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+            &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+            zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+            &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+        END DO
+      END DO
+
+!      DO jn = 1, 5
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+jflag2:    DO jn = 1, 10
+               zlimtmp = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) )
                zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
-               zrearat(ji,jk,1) = ( reac_no3 * dtsed * zsolid1 ) / &
-                  &                    ( 1. + reac_no3 * dtsed * zundsat(ji,jk,1 ) )
-            ELSE
-               zrearat(ji,jk,1) = 0.
-            ENDIF
-         END DO
-      END DO
-
-
-      ! solves tridiagonal system
-      CALL sed_mat( nv, jpoce, jpksed, zrearat, zundsat )
+               zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+               zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+               zbeta   = xksedno3 - pwcp(ji,jk,jwno3) + srDnit * ( zrearat1(ji,jk)    &
+               &         + zrearat2(ji,jk) + zrearat3(ji,jk) ) * zlimtmp
+               zgamma = - xksedno3 * pwcp(ji,jk,jwno3)
+               zundsat2 = zundsat(ji,jk)
+               zundsat(ji,jk) = ( - zbeta + SQRT( zbeta**2 - 4.0 * zgamma ) ) / 2.0
+               zlimno3(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) / ( zundsat(ji,jk) + xksedno3 )
+               zkpoca  = zkpoc(ji,jk) * zlimno3(ji,jk)
+               zkpocb  = zkpos(ji,jk) * zlimno3(ji,jk)
+               zkpocc  = zkpor(ji,jk) * zlimno3(ji,jk)
+               zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+               &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+               zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+               &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+               zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+               &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+               IF ( ABS( (zundsat(ji,jk)-zundsat2)/(zundsat2+rtrn)) < 1E-8 ) THEN
+                  EXIT jflag2
+               ENDIF
+            END DO jflag2
+         END DO
+      END DO
 
 
@@ -308,234 +263,443 @@
       DO jk = 2, jpksed
          DO ji = 1, jpoce
-            zreasat = zrearat(ji,jk,1) * zundsat(ji,jk,1) / zvolc(ji,jk,jspoc)
+            zreasat = zrearat1(ji,jk) * zlimno3(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspoc)
             solcp(ji,jk,jspoc) = solcp(ji,jk,jspoc) - zreasat
+            zreasat = zrearat2(ji,jk) * zlimno3(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspos)
+            solcp(ji,jk,jspos) = solcp(ji,jk,jspos) - zreasat
+            zreasat = zrearat3(ji,jk) * zlimno3(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspor)
+            solcp(ji,jk,jspor) = solcp(ji,jk,jspor) - zreasat
          ENDDO
       ENDDO
 
       ! New dissolved concentrations
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zreasat = zrearat(ji,jk,1) * zundsat(ji,jk,1)    
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
             ! For nitrates
-            pwcp(ji,jk,jwno3)  =  zundsat(ji,jk,1) * srDnit
+            pwcp(ji,jk,jwno3)  =  zundsat(ji,jk)
+            zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) * zlimno3(ji,jk) * zundsat(ji,jk)
             ! For DIC
             pwcp(ji,jk,jwdic)  = pwcp(ji,jk,jwdic) + zreasat
+            zsumtot(ji) = zsumtot(ji) + zreasat / dtsed2 * volw3d(ji,jk) * 1.e-3 * 86400. * 365. * 1E3
             ! For Phosphate (in mol/l)
             pwcp(ji,jk,jwpo4)  = pwcp(ji,jk,jwpo4) + zreasat * spo4r            
+            ! Ligands
+            sedligand(ji,jk)   = sedligand(ji,jk) + ratligc * zreasat
+            ! For iron (in mol/l)
+            pwcp(ji,jk,jwfe2)  = pwcp(ji,jk,jwfe2) + fecratio(ji) * zreasat
             ! For alkalinity
-            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + zreasat * ( srDnit - 2.* spo4r )           
-            ! For DIC13
-            pwcp(ji,jk,jwc13)  = pwcp(ji,jk,jwc13) + zreasat * rc13P * pdb
-         ENDDO
-      ENDDO
-
-
-      ! Mass of O2 for mass balance check and det. of o2 consomation
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zvolw = volw3d(ji,jk) * 1.e-3
-            zmno3_2(ji) = zmno3_2(ji) + pwcp(ji,jk ,jwno3) * zvolw
-            zmc13_2(ji) = zmc13_2(ji) + pwcp(ji,jk ,jwc13) * zvolw   
-         ENDDO
-      ENDDO
-
-      DO ji = 1, jpoce
-         cons_no3(ji) = zmno3_1(ji) - zmno3_2(ji)  
-         sour_c13(ji) = sour_c13(ji) + zmc13_2(ji) - zmc13_1(ji)     
-      ENDDO
-
-
-      !---------------------------
-      ! Solves PO4 diffusion 
-      !----------------------------
-
-      nv = 1
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zundsat(ji,jk,1) = pwcp(ji,jk,jwpo4)
-            zrearat(ji,jk,1) = 0.
-         ENDDO
-      ENDDO
-
-
-      ! solves tridiagonal system
-      CALL sed_mat( nv, jpoce, jpksed, zrearat, zundsat )
-
-
-      ! New undsaturation values and dissolved concentrations
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            pwcp(ji,jk,jwpo4) = zundsat(ji,jk,1)
-         ENDDO
-      ENDDO
-
-
-      !---------------------------------------------------------------
-      ! Performs CaCO3 particle deposition and redissolution (indice 9)
-      !--------------------------------------------------------------
-
-      ! computes co3por from the updated pwcp concentrations (note [co3por] = mol/l)
-
-      CALL sed_co3( kt )
-
-
-      nv = 1
-      ! *densSW(l)**2 converts aksps [mol2/kg sol2] into [mol2/l2] to get [undsat] in [mol/l]
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zundsat(ji,jk,1) = aksps(ji) * densSW(ji) * densSW(ji) / calcon2(ji) &
-               &                     - co3por(ji,jk)
-            ! positive values of undersaturation
-            zundsat(ji,jk,1) = MAX( 0., zundsat(ji,jk,1) )            
-         ENDDO
-      ENDDO
-
-      DO jk = 2, jpksed
-         DO ji = 1, jpoce
-            zsolid1 = zvolc(ji,jk,jscal) * solcp(ji,jk,jscal)
-            zrearat(ji,jk,1) = ( reac_cal * dtsed * zsolid1 ) / &
-                  &               ( 1. + reac_cal * dtsed * zundsat(ji,jk,1) )
-         END DO
-      END DO
-
-
-      ! solves tridiagonal system
-      CALL sed_mat( nv, jpoce, jpksed, zrearat, zundsat )
-
-
-      ! New solid concentration values (jk=2 to jksed) for cacO3
-      DO jk = 2, jpksed
-         DO ji = 1, jpoce
-            zreasat = zrearat(ji,jk,1) * zundsat(ji,jk,1) / zvolc(ji,jk,jscal)
-            solcp(ji,jk,jscal) = solcp(ji,jk,jscal) - zreasat
-         ENDDO
-      ENDDO
+            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + zreasat * ( srDnit + srno3 * zadsnh4 - 2.* spo4r )           
+            ! Ammonium
+            pwcp(ji,jk,jwnh4)  = pwcp(ji,jk,jwnh4) + zreasat * srno3 * zadsnh4
+         ENDDO
+      ENDDO
+
+      !--------------------------------------------------------------------
+      ! Begining POC iron reduction
+      ! (indice nï¿½5 for couple POFe(OH)3 ie solcp(:,:,jspoc)/pwcp(:,:,jsfeo))
+      !--------------------------------------------------------------------
+
+      zrearat1(:,:) = 0.
+      zrearat2(:,:) = 0.
+      zrearat3(:,:) = 0.
+
+      zundsat(:,:) = solcp(:,:,jsfeo)
+
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zlimfeo(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+            &                / ( pwcp(ji,jk,jwno3) + xksedno3 ) ) / ( zundsat(ji,jk) + xksedfeo )
+            zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
+            zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+            zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+            zkpoca = zkpoc(ji,jk) * zlimfeo(ji,jk)
+            zkpocb = zkpos(ji,jk) * zlimfeo(ji,jk)
+            zkpocc = zkpor(ji,jk) * zlimfeo(ji,jk)
+            zrearat1(ji,jk) = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+            &                    ( 1. + zkpoca * zundsat(ji,jk) * dtsed2 )
+            zrearat2(ji,jk) = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+            &                    ( 1. + zkpocb * zundsat(ji,jk) * dtsed2 )
+            zrearat3(ji,jk) = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+            &                    ( 1. + zkpocc * zundsat(ji,jk) * dtsed2 )
+         END DO
+      END DO
+
+!      DO jn = 1, 5
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+jflag3:     DO jn = 1, 10
+               zlimtmp = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+               &                / ( pwcp(ji,jk,jwno3) + xksedno3 ) )
+               zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
+               zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+               zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+               zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) / zvolc(ji,jk,jsfeo)
+               zbeta   = xksedfeo - solcp(ji,jk,jsfeo) + 4.0 * zreasat * zlimtmp
+               zgamma  = -xksedfeo * solcp(ji,jk,jsfeo)
+               zundsat2 = zundsat(ji,jk)
+               zundsat(ji,jk) = ( - zbeta + SQRT( zbeta**2 - 4.0 * zgamma ) ) / 2.0
+               zlimfeo(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+               &                / ( pwcp(ji,jk,jwno3) + xksedno3 ) ) / ( zundsat(ji,jk) + xksedfeo )
+               zkpoca  = zkpoc(ji,jk) * zlimfeo(ji,jk)
+               zkpocb  = zkpos(ji,jk) * zlimfeo(ji,jk)
+               zkpocc  = zkpor(ji,jk) * zlimfeo(ji,jk)
+               zrearat1(ji,jk) = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+               &                    ( 1. + zkpoca * zundsat(ji,jk) * dtsed2 )
+               zrearat2(ji,jk) = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+               &                    ( 1. + zkpocb * zundsat(ji,jk) * dtsed2 )
+               zrearat3(ji,jk) = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+               &                    ( 1. + zkpocc * zundsat(ji,jk) * dtsed2 )
+               IF ( ABS( (zundsat(ji,jk)-zundsat2)/( MAX(0.,zundsat2)+rtrn)) < 1E-8 ) THEN
+                  EXIT jflag3
+               ENDIF
+            END DO jflag3
+         END DO
+      END DO
+
+
+         ! New solid concentration values (jk=2 to jksed) for each couple 
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zlimfeo(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspoc)
+            solcp(ji,jk,jspoc) = solcp(ji,jk,jspoc) - zreasat
+            zreasat = zrearat2(ji,jk) * zlimfeo(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspos)
+            solcp(ji,jk,jspos) = solcp(ji,jk,jspos) - zreasat
+            zreasat = zrearat3(ji,jk) * zlimfeo(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspor)
+            solcp(ji,jk,jspor) = solcp(ji,jk,jspor) - zreasat
+         END DO
+      END DO
 
       ! New dissolved concentrations
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zreasat = zrearat(ji,jk,1) * zundsat(ji,jk,1)    
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) * zlimfeo(ji,jk) * zundsat(ji,jk)
+            ! For FEOH
+            solcp(ji,jk,jsfeo) = zundsat(ji,jk)
             ! For DIC
             pwcp(ji,jk,jwdic)  = pwcp(ji,jk,jwdic) + zreasat
+            zsumtot(ji) = zsumtot(ji) + zreasat / dtsed2 * volw3d(ji,jk) * 1.e-3 * 86400. * 365. * 1E3
+            ! For Phosphate (in mol/l)
+            pwcp(ji,jk,jwpo4)  = pwcp(ji,jk,jwpo4) + zreasat * ( spo4r + 4.0 * redfep )
+            ! Ligands
+            sedligand(ji,jk)   = sedligand(ji,jk) + ratligc * zreasat
+            ! For iron (in mol/l)
+            pwcp(ji,jk,jwfe2)  = pwcp(ji,jk,jwfe2) + fecratio(ji) * zreasat
             ! For alkalinity
-            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + 2.* zreasat 
-            ! For DIC13
-            pwcp(ji,jk,jwc13)  = pwcp(ji,jk,jwc13) + zreasat * rc13Ca * pdb
-         ENDDO
-      ENDDO
-
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zmc13_3(ji) = zmc13_3(ji) + pwcp(ji,jk,jwc13) * volw3d(ji,jk) * 1.e-3                  
-         ENDDO
-      ENDDO
-
-      DO ji = 1, jpoce     
-         sour_c13(ji) = sour_c13(ji) + zmc13_3(ji) - zmc13_2(ji)   
-      ENDDO
-      
-      !-------------------------------------------------
-      ! Beginning DIC, Alkalinity and DIC13 diffusion
-      !-------------------------------------------------
-      
-      nv = 3
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce      
-            zundsat(ji,jk,1) = pwcp(ji,jk,jwdic)
-            zundsat(ji,jk,2) = pwcp(ji,jk,jwalk)
-            zundsat(ji,jk,3) = pwcp(ji,jk,jwc13)
-      
-            zrearat(ji,jk,1) = 0.
-            zrearat(ji,jk,2) = 0.
-            zrearat(ji,jk,3) = 0.
-      
-         ENDDO
-      ENDDO
-
-
-      ! solves tridiagonal system
-      CALL sed_mat( nv, jpoce, jpksed, zrearat, zundsat )
-
-
-      ! New dissolved concentrations      
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce                      
-            pwcp(ji,jk,jwdic) = zundsat(ji,jk,1)
-            pwcp(ji,jk,jwalk) = zundsat(ji,jk,2)
-            pwcp(ji,jk,jwc13) = zundsat(ji,jk,3)
-         ENDDO
-      ENDDO            
-      
-      !----------------------------------
-      !   Back to initial geometry
-      !-----------------------------
-      
-      !---------------------------------------------------------------------
-      !   1/ Compensation for ajustement of the bottom water concentrations
-      !      (see note n° 1 about *por(2))
+            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + zreasat * ( srno3 * zadsnh4 - 2.* spo4r ) + 8.0 * zreasat
+            ! Ammonium
+            pwcp(ji,jk,jwnh4)  = pwcp(ji,jk,jwnh4) + zreasat * srno3 * zadsnh4
+            pwcp(ji,jk,jwfe2)  = pwcp(ji,jk,jwfe2) + zreasat * 4.0
+         ENDDO
+      ENDDO
+
       !--------------------------------------------------------------------
-      DO jw = 1, jpwat
-         DO ji = 1, jpoce
-            pwcp(ji,1,jw) = pwcp(ji,1,jw) + &
-               &            pwcp(ji,2,jw) * dzdep(ji) * por(2) / dzkbot(ji)
-         END DO
-      ENDDO
-      
-      !-----------------------------------------------------------------------
-      !    2/ Det of new rainrg taking account of the new weight fraction obtained 
-      !      in dz3d(2) after diffusion/reaction (react/diffu are also in dzdep!)
-      !      This new rain (rgntg rm) will be used in advection/burial routine
-      !------------------------------------------------------------------------
-      DO js = 1, jpsol
-         DO ji = 1, jpoce
-            rainrg(ji,js) = raintg(ji) * solcp(ji,2,js)
-            rainrm(ji,js) = rainrg(ji,js) / mol_wgt(js)
-         END DO
-      ENDDO
-      
-      !  New raintg
-      raintg(:) = 0.
-      DO js = 1, jpsol
-         DO ji = 1, jpoce
-            raintg(ji) = raintg(ji) + rainrg(ji,js)
-         END DO
-      ENDDO
-      
-      !--------------------------------
-      !    3/ back to initial geometry
-      !--------------------------------
+      ! Begining POC denitrification and NO3- diffusion
+      ! (indice nï¿½5 for couple POC/NO3- ie solcp(:,:,jspoc)/pwcp(:,:,jwno3))
+      !--------------------------------------------------------------------
+
+      zrearat1(:,:) = 0.
+      zrearat2(:,:) = 0.
+      zrearat3(:,:) = 0.
+
+      zundsat(:,:) = pwcp(:,:,jwso4)
+
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zlimso4(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+            &                / ( pwcp(ji,jk,jwno3) + xksedno3 ) ) * ( 1. - solcp(ji,jk,jsfeo)  &
+            &                / ( solcp(ji,jk,jsfeo) + xksedfeo ) ) / ( zundsat(ji,jk) + xksedso4 )
+            zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
+            zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+            zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+            zkpoca = zkpoc(ji,jk) * zlimso4(ji,jk)
+            zkpocb = zkpos(ji,jk) * zlimso4(ji,jk)
+            zkpocc = zkpor(ji,jk) * zlimso4(ji,jk)
+            zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+            &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+            zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+            &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+            zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+            &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+        END DO
+      END DO
+!
+!      DO jn = 1, 5 
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+jflag4:     DO jn = 1, 10
+               zlimtmp = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+               &         / ( pwcp(ji,jk,jwno3) + xksedno3 ) ) * ( 1. - solcp(ji,jk,jsfeo)  &
+               &         / ( solcp(ji,jk,jsfeo) + xksedfeo ) ) 
+               zsolid1 = zvolc(ji,jk,jspoc) * solcp(ji,jk,jspoc)
+               zsolid2 = zvolc(ji,jk,jspos) * solcp(ji,jk,jspos)
+               zsolid3 = zvolc(ji,jk,jspor) * solcp(ji,jk,jspor)
+               zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) 
+               zbeta   = xksedso4 - pwcp(ji,jk,jwso4) + 0.5 * zreasat * zlimtmp
+               zgamma = - xksedso4 * pwcp(ji,jk,jwso4)
+               zundsat2 = zundsat(ji,jk)
+               zundsat(ji,jk) = ( - zbeta + SQRT( zbeta**2 - 4.0 * zgamma ) ) / 2.0
+               zlimso4(ji,jk) = ( 1.0 - pwcp(ji,jk,jwoxy) * zlimo2(ji,jk) ) * ( 1.0 - pwcp(ji,jk,jwno3)    &
+               &                / ( pwcp(ji,jk,jwno3) + xksedno3 ) ) * ( 1. - solcp(ji,jk,jsfeo)  &
+               &                / ( solcp(ji,jk,jsfeo) + xksedfeo ) ) / ( zundsat(ji,jk) + xksedso4 )
+               zkpoca  = zkpoc(ji,jk) * zlimso4(ji,jk)
+               zkpocb  = zkpos(ji,jk) * zlimso4(ji,jk)
+               zkpocc  = zkpor(ji,jk) * zlimso4(ji,jk)
+               zrearat1(ji,jk)  = ( zkpoc(ji,jk) * dtsed2 * zsolid1 ) / &
+               &                 ( 1. + zkpoca * zundsat(ji,jk ) * dtsed2 )
+               zrearat2(ji,jk)  = ( zkpos(ji,jk) * dtsed2 * zsolid2 ) / &
+               &                 ( 1. + zkpocb * zundsat(ji,jk ) * dtsed2 )
+               zrearat3(ji,jk)  = ( zkpor(ji,jk) * dtsed2 * zsolid3 ) / &
+               &                 ( 1. + zkpocc * zundsat(ji,jk ) * dtsed2 )
+               IF ( ABS( (zundsat(ji,jk)-zundsat2)/(zundsat2+rtrn)) < 1E-8 ) THEN
+                  EXIT jflag4
+               ENDIF
+            END DO jflag4
+         END DO
+      END DO
+
+     ! New solid concentration values (jk=2 to jksed) for each couple 
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zlimso4(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspoc)
+            solcp(ji,jk,jspoc) = solcp(ji,jk,jspoc) - zreasat
+            zreasat = zrearat2(ji,jk) * zlimso4(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspos)
+            solcp(ji,jk,jspos) = solcp(ji,jk,jspos) - zreasat
+            zreasat = zrearat3(ji,jk) * zlimso4(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jspor)
+            solcp(ji,jk,jspor) = solcp(ji,jk,jspor) - zreasat
+         ENDDO
+      ENDDO
+!
+      ! New dissolved concentrations
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            ! For sulfur
+            pwcp(ji,jk,jwh2s)  = pwcp(ji,jk,jwh2s) - ( zundsat(ji,jk) - pwcp(ji,jk,jwso4) ) 
+            pwcp(ji,jk,jwso4)  =  zundsat(ji,jk)
+            zreasat = ( zrearat1(ji,jk) + zrearat2(ji,jk) + zrearat3(ji,jk) ) * zlimso4(ji,jk) * zundsat(ji,jk)
+            ! For DIC
+            pwcp(ji,jk,jwdic)  = pwcp(ji,jk,jwdic) + zreasat
+            zsumtot(ji) = zsumtot(ji) + zreasat / dtsed2 * volw3d(ji,jk) * 1.e-3 * 86400. * 365. * 1E3
+            ! For Phosphate (in mol/l)
+            pwcp(ji,jk,jwpo4)  = pwcp(ji,jk,jwpo4) + zreasat * spo4r
+            ! Ligands
+            sedligand(ji,jk)   = sedligand(ji,jk) + ratligc * zreasat
+            ! For iron (in mol/l)
+            pwcp(ji,jk,jwfe2)  = pwcp(ji,jk,jwfe2) + fecratio(ji) * zreasat
+            ! For alkalinity
+            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + zreasat * ( srno3 * zadsnh4 - 2.* spo4r ) + zreasat
+            ! Ammonium
+            pwcp(ji,jk,jwnh4)  = pwcp(ji,jk,jwnh4) + zreasat * srno3 * zadsnh4
+         ENDDO
+      ENDDO
+
+      ! Oxydation of the reduced products. Here only ammonium and ODU is accounted for
+      ! There are two options here: A simple time splitting scheme and a modified 
+     ! Patankar scheme
+      ! ------------------------------------------------------------------------------
+
+      call sed_dsr_redoxb
+
+      ! -------------------------------------------------------------- 
+      !    4/ Computation of the bioturbation coefficient
+      !       This parameterization is taken from Archer et al. (2002)
+      ! --------------------------------------------------------------
+
       DO ji = 1, jpoce
-         dz3d  (ji,2) = dz(2)
-         volw3d(ji,2) = dz3d(ji,2) * por(2)
-         vols3d(ji,2) = dz3d(ji,2) * por1(2)
-      ENDDO
-      
-      !----------------------------------------------------------------------
-      !    4/ Saving new amount of material in dzkbot for mass balance check
-      !       tokbot in [mol] (implicit *1cm*1cm for spacial dim)
-      !----------------------------------------------------------------------
-      DO jw = 1, jpwat 
-         DO ji = 1, jpoce
-            tokbot(ji,jw) = pwcp(ji,1,jw) * 1.e-3 * dzkbot(ji)
-         END DO
-      ENDDO
-
-      DEALLOCATE( zmo2_0  ) ;  DEALLOCATE( zmno3_1 )  ;  DEALLOCATE( zmno3_2 ) 
-      DEALLOCATE( zmc13_0 ) ;  DEALLOCATE( zmc13_1 )  ;  DEALLOCATE( zmc13_2 ) ;  DEALLOCATE( zmc13_3 ) 
-      
-      DEALLOCATE( zrearat ) ;  DEALLOCATE( zundsat )  ;  DEALLOCATE( zvolc )   
-      
+         db(ji,:) = dbiot * zsumtot(ji) * pwcp(ji,1,jwoxy) / (pwcp(ji,1,jwoxy) + 20.E-6)
+      END DO
+
+      ! ------------------------------------------------------
+      !    Vertical variations of the bioturbation coefficient
+      ! ------------------------------------------------------
+      IF (ln_btbz) THEN
+         DO ji = 1, jpoce
+            db(ji,:) = db(ji,:) * exp( -(profsedw(:) / dbtbzsc)**2 ) / (365.0 * 86400.0)
+         END DO
+      ELSE
+         DO jk = 1, jpksed
+            IF (profsedw(jk) > dbtbzsc) THEN
+                db(:,jk) = 0.0
+            ENDIF
+         END DO
+      ENDIF
+
+      IF (ln_irrig) THEN
+         DO jk = 1, jpksed
+            DO ji = 1, jpoce
+               irrig(ji,jk) = ( 7.63752 - 7.4465 * exp( -0.89603 * zsumtot(ji) ) ) * pwcp(ji,1,jwoxy)  &
+               &             / (pwcp(ji,1,jwoxy) + 20.E-6) 
+               irrig(ji,jk) = irrig(ji,jk) * exp( -(profsedw(jk) / xirrzsc) )
+            END DO
+         END DO
+      ELSE
+         irrig(:,:) = 0.0
+      ENDIF
+
+      DEALLOCATE( zvolc )
+
+      IF( ln_timing )  CALL timing_stop('sed_dsr')
+!      
    END SUBROUTINE sed_dsr
-#else
-   !!======================================================================
-   !! MODULE seddsr  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_dsr ( kt )
-     INTEGER, INTENT(in) :: kt
-     WRITE(*,*) 'sed_dsr: You should not have seen this print! error?', kt
-  END SUBROUTINE sed_dsr
-#endif
-   
+
+   SUBROUTINE sed_dsr_redoxb
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_dsr_redox  ***
+      !! 
+      !!  ** Purpose :  computes secondary redox reactions
+      !!
+      !!  ** Methode :  It uses Strand splitter algorithm proposed by 
+      !!                Nguyen et al. (2009) and modified by Wang et al. (2018)
+      !!                Basically, each equation is solved analytically when 
+      !!                feasible, otherwise numerically at t+1/2. Then 
+      !!                the last equation is solved at t+1. The other equations
+      !!                are then solved at t+1 starting in the reverse order.
+      !!                Ideally, it's better to start from the fastest reaction
+      !!                to the slowest and then reverse the order to finish up
+      !!                with the fastest one. But random order works well also.
+      !!                The scheme is second order, positive and mass 
+      !!                conserving. It works well for stiff systems.
+      !! 
+      !!   History :
+      !!        !  18-08 (O. Aumont)  Original code
+      !!----------------------------------------------------------------------
+      !! Arguments
+      ! --- local variables
+      INTEGER   ::  ji, jk, jn   ! dummy looop indices
+
+      REAL, DIMENSION(6)  :: zsedtrn, zsedtra
+      REAL(wp)  ::  zalpha, zbeta, zgamma, zdelta, zepsi, zsedfer
+      !!
+      !!----------------------------------------------------------------------
+
+      IF( ln_timing )  CALL timing_start('sed_dsr_redoxb')
+
+      DO ji = 1, jpoce
+         DO jk = 2, jpksed
+            zsedtrn(1)  = pwcp(ji,jk,jwoxy)
+            zsedtrn(2)  = MAX(0., pwcp(ji,jk,jwh2s) )
+            zsedtrn(3)  = pwcp(ji,jk,jwnh4)
+            zsedtrn(4)  = MAX(0., pwcp(ji,jk,jwfe2) - sedligand(ji,jk) )
+            zsedfer     = MIN(0., pwcp(ji,jk,jwfe2) - sedligand(ji,jk) )
+            zsedtrn(5)  = solcp(ji,jk,jsfeo) * zvolc(ji,jk,jsfeo)
+            zsedtrn(6)  = solcp(ji,jk,jsfes) * zvolc(ji,jk,jsfes)
+            zsedtra(:)  = zsedtrn(:) 
+
+            ! First pass of the scheme. At the end, it is 1st order 
+            ! -----------------------------------------------------
+            ! Fe + O2
+            zalpha = zsedtra(1) - 0.25 * zsedtra(4)
+            zbeta  = zsedtra(4) + zsedtra(5) 
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(4)
+            zdelta = pwcp(ji,jk,jwpo4) - redfep * zsedtra(4)
+            zsedtra(4) = ( zsedtra(4) * zalpha ) / ( 0.25 * zsedtra(4) * ( exp( reac_fe2 * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_fe2 * zalpha * dtsed2 / 2. ) + rtrn )
+            zsedtra(1) = zalpha + 0.25 * zsedtra(4) 
+            zsedtra(5) = zbeta  - zsedtra(4)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(4)
+            pwcp(ji,jk,jwpo4) = zdelta + redfep * zsedtra(4)
+            ! H2S + O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(2)
+            zbeta  = pwcp(ji,jk,jwso4) + zsedtra(2)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(2)
+            zsedtra(2) = ( zsedtra(2) * zalpha ) / ( 2.0 * zsedtra(2) * ( exp( reac_h2s * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_h2s * zalpha * dtsed2 / 2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(2)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(2)
+            pwcp(ji,jk,jwso4) = zbeta - zsedtra(2)
+            ! NH4 + O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(3)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(3)
+            zsedtra(3) = ( zsedtra(3) * zalpha ) / ( 2.0 * zsedtra(3) * ( exp( reac_nh4 * zadsnh4 * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_nh4 * zadsnh4 * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(3)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(3)
+            ! FeS - O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(6)
+            zbeta  = zsedtra(4) + zsedtra(6)
+            zgamma = pwcp(ji,jk,jwso4) + zsedtra(6)
+            zsedtra(6) = ( zsedtra(6) * zalpha ) / ( 2.0 * zsedtra(6) * ( exp( reac_feso * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_feso * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(6)
+            zsedtra(4) = zbeta  - zsedtra(6)
+            pwcp(ji,jk,jwso4) = zgamma - zsedtra(6)
+!            ! Fe - H2S
+            zalpha = zsedtra(2) - zsedtra(4)
+            zbeta  = zsedtra(4) + zsedtra(6)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(4)
+            zsedtra(4) = ( zsedtra(4) * zalpha ) / ( zsedtra(4) * ( exp( reac_fes * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_fes * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(2) = zalpha + zsedtra(4)
+            zsedtra(6) = zbeta  - zsedtra(4)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(4)
+            ! FEOH + H2S
+            zalpha = zsedtra(5) - 2.0 * zsedtra(2)
+            zbeta  = zsedtra(5) + zsedtra(4)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(4)
+            zdelta = pwcp(ji,jk,jwso4) + zsedtra(2)
+            zepsi  = pwcp(ji,jk,jwpo4) + redfep * zsedtra(5)
+            zsedtra(2) = ( zsedtra(2) * zalpha ) / ( 2.0 * zsedtra(2) * ( exp( reac_feh2s * zalpha * dtsed2 ) - 1.0 )  &
+            &            + zalpha * exp( reac_feh2s * zalpha * dtsed2 ) + rtrn )
+            zsedtra(5) = zalpha + 2.0 * zsedtra(2)
+            zsedtra(4) = zbeta  - zsedtra(5)
+            pwcp(ji,jk,jwso4) = zdelta - zsedtra(2)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(4)
+            pwcp(ji,jk,jwpo4) = zepsi - redfep * zsedtra(5)
+            ! Fe - H2S
+            zalpha = zsedtra(2) - zsedtra(4)
+            zbeta  = zsedtra(4) + zsedtra(6)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(4)
+            zsedtra(4) = ( zsedtra(4) * zalpha ) / ( zsedtra(4) * ( exp( reac_fes * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_fes * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(2) = zalpha + zsedtra(4)
+            zsedtra(6) = zbeta  - zsedtra(4)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(4)
+            ! FeS - O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(6)
+            zbeta  = zsedtra(4) + zsedtra(6)
+            zgamma = pwcp(ji,jk,jwso4) + zsedtra(6)
+            zsedtra(6) = ( zsedtra(6) * zalpha ) / ( 2.0 * zsedtra(6) * ( exp( reac_feso * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_feso * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(6)
+            zsedtra(4) = zbeta  - zsedtra(6)
+            pwcp(ji,jk,jwso4) = zgamma - zsedtra(6)
+            ! NH4 + O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(3)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(3)
+            zsedtra(3) = ( zsedtra(3) * zalpha ) / ( 2.0 * zsedtra(3) * ( exp( reac_nh4 * zadsnh4 * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_nh4 * zadsnh4 * zalpha * dtsed2 /2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(3)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(3)
+            ! H2S + O2
+            zalpha = zsedtra(1) - 2.0 * zsedtra(2)
+            zbeta  = pwcp(ji,jk,jwso4) + zsedtra(2)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(2)
+            zsedtra(2) = ( zsedtra(2) * zalpha ) / ( 2.0 * zsedtra(2) * ( exp( reac_h2s * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_h2s * zalpha * dtsed2 / 2. ) + rtrn )
+            zsedtra(1) = zalpha + 2.0 * zsedtra(2)
+            pwcp(ji,jk,jwso4) = zbeta - zsedtra(2)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(2)
+            ! Fe + O2
+            zalpha = zsedtra(1) - 0.25 * zsedtra(4)
+            zbeta  = zsedtra(4) + zsedtra(5)
+            zgamma = pwcp(ji,jk,jwalk) - 2.0 * zsedtra(4)
+            zdelta = pwcp(ji,jk,jwpo4) - redfep * zsedtra(4)
+            zsedtra(4) = ( zsedtra(4) * zalpha ) / ( 0.25 * zsedtra(4) * ( exp( reac_fe2 * zalpha * dtsed2 / 2. ) - 1.0 )  &
+            &            + zalpha * exp( reac_fe2 * zalpha * dtsed2 / 2. ) + rtrn )
+            zsedtra(1) = zalpha + 0.25 * zsedtra(4)
+            zsedtra(5) = zbeta  - zsedtra(4)
+            pwcp(ji,jk,jwpo4) = zdelta + redfep * zsedtra(4)
+            pwcp(ji,jk,jwalk) = zgamma + 2.0 * zsedtra(4)
+            pwcp(ji,jk,jwoxy)  = zsedtra(1)
+            pwcp(ji,jk,jwh2s)  = zsedtra(2)
+            pwcp(ji,jk,jwnh4)  = zsedtra(3)
+            pwcp(ji,jk,jwfe2)  = zsedtra(4) + sedligand(ji,jk) + zsedfer
+            pwcp(ji,jk,jwno3)  = pwcp(ji,jk,jwno3)  + ( zsedtrn(3) - pwcp(ji,jk,jwnh4) )
+            solcp(ji,jk,jsfeo) = zsedtra(5) / zvolc(ji,jk,jsfeo)
+            solcp(ji,jk,jsfes) = zsedtra(6) / zvolc(ji,jk,jsfes)
+         END DO
+      END DO
+
+      IF( ln_timing )  CALL timing_stop('sed_dsr_redoxb')
+
+  END SUBROUTINE sed_dsr_redoxb
+
 END MODULE seddsr
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddta.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddta.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/seddta.F90	(revision 10321)
@@ -4,9 +4,10 @@
    !! Sediment data  :  read sediment input data from a file
    !!=====================================================================
-#if defined key_sed
+
    !! * Modules used
    USE sed
    USE sedarr
    USE iom
+   USE lib_mpp         ! distribued memory computing library
 
    IMPLICIT NONE
@@ -17,14 +18,6 @@
 
    !! *  Module variables
-   REAL(wp), DIMENSION(:), ALLOCATABLE ::  smask       ! mask for sediments points
    REAL(wp) ::  rsecday  ! number of second per a day
-   REAL(wp) ::  conv1    ! [m/day]--->[cm/s]  
    REAL(wp) ::  conv2    ! [kg/m2/month]-->[g/cm2/s] ( 1 month has 30 days )
-
-   INTEGER ::  numbio
-
-#if defined key_sed_off
-   INTEGER ::  numoce
-#endif
 
    !! $Id$
@@ -54,7 +47,7 @@
       INTEGER  ::  ji, jj, js, jw, ikt
 
-      REAL(wp), DIMENSION(:,:), ALLOCATABLE :: zdta
-      REAL(wp), DIMENSION(:)  , ALLOCATABLE :: zdtap, zdtag
-
+      REAL(wp), DIMENSION(jpoce) :: zdtap, zdtag
+      REAL(wp), DIMENSION(jpi,jpj) :: zwsbio4, zwsbio3, zwscal
+      REAL(wp) :: zf0, zf1, zf2, zkapp, zratio, zdep
 
       !----------------------------------------------------------------------
@@ -64,136 +57,145 @@
       !-------------------------------------------------------------
 
-      WRITE(numsed,*)
-      WRITE(numsed,*) ' sed_dta : Bottom layer fields'
-      WRITE(numsed,*) ' ~~~~~~'
-      WRITE(numsed,*) ' Data from SMS model'
-      WRITE(numsed,*)
+      IF( ln_timing )  CALL timing_start('sed_dta')
+
+      IF (lwp) THEN
+         WRITE(numsed,*)
+         WRITE(numsed,*) ' sed_dta : Bottom layer fields'
+         WRITE(numsed,*) ' ~~~~~~'
+         WRITE(numsed,*) ' Data from SMS model'
+         WRITE(numsed,*)
+      ENDIF
 
 
       ! open file
       IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' sed_dta : Sediment fields'
-         CALL iom_open ( 'data_bio_bot'     , numbio )
-#if defined key_sed_off
-         CALL iom_open( 'data_oce_bot', numoce)
-#endif
+         IF (lwp) WRITE(numsed,*) ' sed_dta : Sediment fields'
+         dtsed = r2dttrc
          rsecday = 60.* 60. * 24.
-         conv1   = 1.0e+2 / rsecday 
-         conv2   = 1.0e+3 / ( 1.0e+4 * rsecday * 30. ) 
-
-         ! Compute sediment mask
-         ALLOCATE( zdta(jpi,jpj) ) 
+!         conv2   = 1.0e+3 / ( 1.0e+4 * rsecday * 30. )
+         conv2 = 1.0e+3 /  1.0e+4 
+         rdtsed(2:jpksed) = dtsed / ( denssol * por1(2:jpksed) )
+      ENDIF
+
+      ! Initialization of temporaries arrays  
+      zdtap(:)    = 0. 
+      zdtag(:)    = 0.  
+
+      ! reading variables
+      IF (lwp) WRITE(numsed,*)
+      IF (lwp) WRITE(numsed,*) ' sed_dta : Bottom layer fields at time  kt = ', kt
+      ! reading variables
+      !
+      !    Sinking speeds of detritus is increased with depth as shown
+      !    by data and from the coagulation theory
+      !    -----------------------------------------------------------
+      IF (ln_sediment_offline) THEN
          DO jj = 1, jpj
             DO ji = 1, jpi
-               ikt = MAX( INT( sbathy(ji,jj) ) - 1, 1 )
-               zdta(ji,jj) = tmask(ji,jj,ikt) 
-            ENDDO
-         ENDDO
-         ALLOCATE( smask(jpoce) )
-         smask(:) = 0.
-         CALL pack_arr( jpoce, smask(1:jpoce), zdta(1:jpi,1:jpj), iarroce(1:jpoce) )
-      ENDIF
-
-      ! Initialization of temporaries arrays  
-      ALLOCATE( zdtap(jpoce) )    ;   zdtap(:)    = 0. 
-      ALLOCATE( zdtag(jpoce) )    ;   zdtag(:)    = 0.  
-
-      IF( MOD( kt - 1, nfreq ) == 0 ) THEN
-         ! reading variables
-         WRITE(numsed,*)
-         WRITE(numsed,*) ' sed_dta : Bottom layer fields at time  kt = ', kt
-         ! reading variables
-         trc_data(:,:,:) = 0.
-#if ! defined key_sed_off
-         DO jj = 1,jpj
+               ikt = mbkt(ji,jj)
+               zwsbio4(ji,jj) = wsbio2 / rday
+               zwsbio3(ji,jj) = wsbio  / rday
+               zwscal (ji,jj) = wsbio2 / rday
+            END DO
+         END DO
+      ELSE
+         DO jj = 1, jpj
             DO ji = 1, jpi
                ikt = mbkt(ji,jj)
-               IF ( tmask(ji,jj,ikt) == 1 ) THEN
-                  trc_data(ji,jj,1)  = trn  (ji,jj,ikt,jptal)
-                  trc_data(ji,jj,2)  = trn  (ji,jj,ikt,jpdic)
-                  trc_data(ji,jj,3)  = trn  (ji,jj,ikt,jpno3) / 7.6
-                  trc_data(ji,jj,4)  = trn  (ji,jj,ikt,jppo4) / 122.
-                  trc_data(ji,jj,5)  = trn  (ji,jj,ikt,jpoxy)
-                  trc_data(ji,jj,6)  = trn  (ji,jj,ikt,jpsil)
-                  trc_data(ji,jj,7 ) = sinksil (ji,jj,ikt)
-                  trc_data(ji,jj,8 ) = sinking (ji,jj,ikt)
-                  trc_data(ji,jj,9 ) = sinking2(ji,jj,ikt)
-                  trc_data(ji,jj,10) = sinkcal (ji,jj,ikt)
-                  trc_data(ji,jj,11) = tsn     (ji,jj,ikt,jp_tem)
-                  trc_data(ji,jj,12) = tsn     (ji,jj,ikt,jp_sal)
-               ENDIF
-            ENDDO
+               zdep = e3t_n(ji,jj,ikt) / r2dttrc
+               zwsbio4(ji,jj) = MIN( 0.99 * zdep, wsbio4(ji,jj,ikt) / rday )
+               zwscal (ji,jj) = MIN( 0.99 * zdep, wscal (ji,jj,ikt) / rday )
+               zwsbio3(ji,jj) = MIN( 0.99 * zdep, wsbio3(ji,jj,ikt) / rday )
+            END DO
+         END DO
+      ENDIF
+
+      trc_data(:,:,:) = 0.
+      DO jj = 1,jpj
+         DO ji = 1, jpi
+            ikt = mbkt(ji,jj)
+            IF ( tmask(ji,jj,ikt) == 1 ) THEN
+               trc_data(ji,jj,1)   = trb(ji,jj,ikt,jpsil)
+               trc_data(ji,jj,2)   = trb(ji,jj,ikt,jpoxy)
+               trc_data(ji,jj,3)   = trb(ji,jj,ikt,jpdic)
+               trc_data(ji,jj,4)   = trb(ji,jj,ikt,jpno3) / 7.625
+               trc_data(ji,jj,5)   = trb(ji,jj,ikt,jppo4) / 122.
+               trc_data(ji,jj,6)   = trb(ji,jj,ikt,jptal)
+               trc_data(ji,jj,7)   = trb(ji,jj,ikt,jpnh4) / 7.625
+               trc_data(ji,jj,8)   = 0.0
+               trc_data(ji,jj,9)   = 28.0E-3
+               trc_data(ji,jj,10)  = trb(ji,jj,ikt,jpfer)
+               trc_data(ji,jj,11 ) = MIN(trb(ji,jj,ikt,jpgsi), 1E-4) * zwsbio4(ji,jj) * 1E3
+               trc_data(ji,jj,12 ) = MIN(trb(ji,jj,ikt,jppoc), 1E-4) * zwsbio3(ji,jj) * 1E3
+               trc_data(ji,jj,13 ) = MIN(trb(ji,jj,ikt,jpgoc), 1E-4) * zwsbio4(ji,jj) * 1E3
+               trc_data(ji,jj,14)  = MIN(trb(ji,jj,ikt,jpcal), 1E-4) * zwscal (ji,jj) * 1E3
+               trc_data(ji,jj,15)  = tsn(ji,jj,ikt,jp_tem)
+               trc_data(ji,jj,16)  = tsn(ji,jj,ikt,jp_sal)
+               trc_data(ji,jj,17 ) = ( trb(ji,jj,ikt,jpsfe) * zwsbio3(ji,jj) + trb(ji,jj,ikt,jpbfe)  &
+               &                     * zwsbio4(ji,jj)  ) * 1E3 / ( trc_data(ji,jj,12 ) + trc_data(ji,jj,13 ) + rtrn )
+               trc_data(ji,jj,17 ) = MIN(1E-3, trc_data(ji,jj,17 ) )
+            ENDIF
          ENDDO
-
-#else
-         CALL iom_get( numbio, jpdom_data, 'ALKBOT'     , trc_data(:,:,1 ) )
-         CALL iom_get( numbio, jpdom_data, 'DICBOT'     , trc_data(:,:,2 ) )
-         CALL iom_get( numbio, jpdom_data, 'NO3BOT'     , trc_data(:,:,3 ) )
-         CALL iom_get( numbio, jpdom_data, 'PO4BOT'     , trc_data(:,:,4 ) )
-         CALL iom_get( numbio, jpdom_data, 'O2BOT'      , trc_data(:,:,5 ) )
-         CALL iom_get( numbio, jpdom_data, 'SIBOT'      , trc_data(:,:,6 ) )
-         CALL iom_get( numbio, jpdom_data, 'OPALFLXBOT' , trc_data(:,:,7 ) ) 
-         CALL iom_get( numbio, jpdom_data, 'POCFLXBOT'  , trc_data(:,:,8 ) ) 
-         CALL iom_get( numbio, jpdom_data, 'GOCFLXBOT'  , trc_data(:,:,9 ) ) 
-         CALL iom_get( numbio, jpdom_data, 'CACO3FLXBOT', trc_data(:,:,10) ) 
-         CALL iom_get( numoce, jpdom_data, 'TBOT'       , trc_data(:,:,11) ) 
-         CALL iom_get( numoce, jpdom_data, 'SBOT'       , trc_data(:,:,12) ) 
-#endif
-
-         ! Pore water initial concentration [mol/l] in  k=1
-         !-------------------------------------------------
-
-          ! Alkalinity ( 1 umol = 10-6equivalent )
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwalk), trc_data(1:jpi,1:jpj,1), iarroce(1:jpoce) )
-         ! DIC 
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwdic), trc_data(1:jpi,1:jpj,2), iarroce(1:jpoce) )
-         ! Nitrates (1 umol/l = 10-6 mol/l)
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwno3), trc_data(1:jpi,1:jpj,3), iarroce(1:jpoce) )
-         ! Phosphates (1 umol/l = 10-6 mol/l)
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwpo4), trc_data(1:jpi,1:jpj,4), iarroce(1:jpoce) )
-         ! Oxygen (1 umol/l = 10-6 mol/l)
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwoxy), trc_data(1:jpi,1:jpj,5), iarroce(1:jpoce) )        
-         ! Silicic Acid [mol.l-1]
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwsil), trc_data(1:jpi,1:jpj,6), iarroce(1:jpoce) )                  
-         ! DIC13 (mol/l)obtained from dc13 and DIC (12) and PDB 
-         CALL iom_get ( numbio,jpdom_data,'DC13',zdta(:,:) )
-         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jwc13), zdta(1:jpi,1:jpj), iarroce(1:jpoce) )
-         pwcp_dta(1:jpoce,jwc13) = pdb * ( pwcp_dta(1:jpoce,jwc13) * 1.0e-3 + 1.0 )  &
-            &                          *   pwcp_dta(1:jpoce,jwdic)         
-         
-         !  Solid components : 
-         !-----------------------
-         !  Sinking fluxes for OPAL in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
-         CALL pack_arr ( jpoce, rainrm_dta(1:jpoce,jsopal), trc_data(1:jpi,1:jpj,7), iarroce(1:jpoce) ) 
-         rainrm_dta(1:jpoce,jsopal) = rainrm_dta(1:jpoce,jsopal) * 1e-4
-         !  Sinking fluxes for POC in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
-         CALL pack_arr ( jpoce, zdtap(1:jpoce), trc_data(1:jpi,1:jpj,8) , iarroce(1:jpoce) )      
-         CALL pack_arr ( jpoce, zdtag(1:jpoce), trc_data(1:jpi,1:jpj,9) , iarroce(1:jpoce) )
-         rainrm_dta(1:jpoce,jspoc) =   ( zdtap(1:jpoce) +  zdtag(1:jpoce) ) * 1e-4
-         !  Sinking fluxes for Calcite in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
-         CALL pack_arr ( jpoce,  rainrm_dta(1:jpoce,jscal), trc_data(1:jpi,1:jpj,10), iarroce(1:jpoce) )
-         rainrm_dta(1:jpoce,jscal) = rainrm_dta(1:jpoce,jscal) * 1e-4
-         ! vector temperature [°C] and salinity 
-         CALL pack_arr ( jpoce,  temp(1:jpoce), trc_data(1:jpi,1:jpj,11), iarroce(1:jpoce) )
-         CALL pack_arr ( jpoce,  salt(1:jpoce), trc_data(1:jpi,1:jpj,12), iarroce(1:jpoce) )
-        
-         ! Clay rain rate in [mol/(cm**2.s)] 
-         ! inputs data in [kg.m-2.mois-1] ---> 1e+3/(1e+4*60*24*60*60) [g.cm-2.s-1]   
-         ! divided after by molecular weight g.mol-1      
-         zdta(:,:)   = 0.
-         CALL iom_get( numbio, jpdom_data, 'CLAY', zdta(:,:) ) 
-         CALL pack_arr ( jpoce, rainrm_dta(1:jpoce,jsclay) , zdta(1:jpi,1:jpj), iarroce(1:jpoce) )      
-         rainrm_dta(1:jpoce,jsclay) = rainrm_dta(1:jpoce,jsclay) * conv2 / mol_wgt(jsclay)
-
-      ENDIF
+      ENDDO
+
+      ! Pore water initial concentration [mol/l] in  k=1
+      !-------------------------------------------------
+      DO jw = 1, jpwat
+         CALL pack_arr ( jpoce,  pwcp_dta(1:jpoce,jw), trc_data(1:jpi,1:jpj,jw), iarroce(1:jpoce) )
+      END DO
+      !  Solid components : 
+      !-----------------------
+      !  Sinking fluxes for OPAL in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
+      CALL pack_arr ( jpoce, rainrm_dta(1:jpoce,jsopal), trc_data(1:jpi,1:jpj,11), iarroce(1:jpoce) ) 
+      rainrm_dta(1:jpoce,jsopal) = rainrm_dta(1:jpoce,jsopal) * 1e-4
+      !  Sinking fluxes for POC in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
+      CALL pack_arr ( jpoce, zdtap(1:jpoce), trc_data(1:jpi,1:jpj,12) , iarroce(1:jpoce) )      
+      CALL pack_arr ( jpoce, zdtag(1:jpoce), trc_data(1:jpi,1:jpj,13) , iarroce(1:jpoce) )
+      DO ji = 1, jpoce
+!        zkapp  = MIN( (1.0 - 0.02 ) * reac_poc, 3731.0 * max(100.0, zkbot(ji) )**(-1.011) / ( 365.0 * 24.0 * 3600.0 ) )
+!        zkapp   = MIN( 0.98 * reac_poc, 100.0 * max(100.0, zkbot(ji) )**(-0.6) / ( 365.0 * 24.0 * 3600.0 ) )
+!        zratio = ( ( 1.0 - 0.02 ) * reac_poc + 0.02 * reac_poc * 0. - zkapp) / ( ( 0.02 - 1.0 ) * reac_poc / 100. - 0.02 * reac_poc * 0. + zkapp )
+!        zf1    = ( 0.02 * (reac_poc - reac_poc * 0.) + zkapp - reac_poc ) / ( reac_poc / 100. - reac_poc )
+!        zf1    = MIN(0.98, MAX(0., zf1 ) )
+         zf1    = 0.48
+         zf0    = 1.0 - 0.02 - zf1
+         zf2    = 0.02
+         rainrm_dta(ji,jspoc) =   ( zdtap(ji) +  zdtag(ji) ) * 1e-4 * zf0
+         rainrm_dta(ji,jspos) =   ( zdtap(ji) +  zdtag(ji) ) * 1e-4 * zf1
+         rainrm_dta(ji,jspor) =   ( zdtap(ji) +  zdtag(ji) ) * 1e-4 * zf2
+      END DO
+      !  Sinking fluxes for Calcite in mol.m-2.s-1 ; conversion in mol.cm-2.s-1
+      CALL pack_arr ( jpoce,  rainrm_dta(1:jpoce,jscal), trc_data(1:jpi,1:jpj,14), iarroce(1:jpoce) )
+      rainrm_dta(1:jpoce,jscal) = rainrm_dta(1:jpoce,jscal) * 1e-4
+      ! vector temperature [°C] and salinity 
+      CALL pack_arr ( jpoce,  temp(1:jpoce), trc_data(1:jpi,1:jpj,15), iarroce(1:jpoce) )
+      CALL pack_arr ( jpoce,  salt(1:jpoce), trc_data(1:jpi,1:jpj,16), iarroce(1:jpoce) )
+      
+      ! Clay rain rate in [mol/(cm**2.s)] 
+      ! inputs data in [kg.m-2.sec-1] ---> 1e+3/(1e+4) [g.cm-2.s-1]   
+      ! divided after by molecular weight g.mol-1      
+      CALL pack_arr ( jpoce,  rainrm_dta(1:jpoce,jsclay), dust(1:jpi,1:jpj), iarroce(1:jpoce) )
+      rainrm_dta(1:jpoce,jsclay) = rainrm_dta(1:jpoce,jsclay) * conv2 / mol_wgt(jsclay)   &
+      &                            + wacc(1:jpoce) * por1(2) * denssol / mol_wgt(jsclay) / ( rsecday * 365.0 )
+      rainrm_dta(1:jpoce,jsclay) = rainrm_dta(1:jpoce,jsclay) * 0.965
+      rainrm_dta(1:jpoce,jsfeo)  = rainrm_dta(1:jpoce,jsclay) * mol_wgt(jsclay) / mol_wgt(jsfeo) * 0.035 / 0.965
+!    rainrm_dta(1:jpoce,jsclay) = 1.0E-4 * conv2 / mol_wgt(jsclay)
+
+      ! Iron monosulphide rain rates. Set to 0
+      rainrm_dta(1:jpoce,jsfes)  = 0. 
+
+      ! Fe/C ratio in sinking particles that fall to the sediments
+      CALL pack_arr ( jpoce,  fecratio(1:jpoce), trc_data(1:jpi,1:jpj,17), iarroce(1:jpoce) )
+
+      sedligand(:,1) = 1.E-9
 
       ! sediment pore water at 1st layer (k=1)
       DO jw = 1, jpwat
-         pwcp(1:jpoce,1,jw) = pwcp_dta(1:jpoce,jw) * smask(1:jpoce)
+         pwcp(1:jpoce,1,jw) = pwcp_dta(1:jpoce,jw)
       ENDDO
 
       !  rain
       DO js = 1, jpsol
-         rainrm(1:jpoce,js) = rainrm_dta(1:jpoce,js) * smask(1:jpoce)
+         rainrm(1:jpoce,js) = rainrm_dta(1:jpoce,js)
       ENDDO
 
@@ -212,28 +214,14 @@
       dzdep(1:jpoce) = raintg(1:jpoce) * rdtsed(2) 
 
-
-      DEALLOCATE( zdta ) 
-      DEALLOCATE( zdtap    ) ;  DEALLOCATE( zdtag    ) 
-
-      IF( kt == nitsedend )   THEN
-         CALL iom_close ( numbio )
-#if defined key_sed_off
-         CALL iom_close ( numoce )
-#endif
-      ENDIF
+      IF( lk_iomput ) THEN
+          IF( iom_use("sflxclay" ) ) CALL iom_put( "sflxclay", dust(:,:) * conv2 * 1E4 )
+          IF( iom_use("sflxcal" ) )  CALL iom_put( "sflxcal", trc_data(:,:,13) )
+          IF( iom_use("sflxbsi" ) )  CALL iom_put( "sflxbsi", trc_data(:,:,10) )
+          IF( iom_use("sflxpoc" ) )  CALL iom_put( "sflxpoc", trc_data(:,:,11) + trc_data(:,:,12) )
+      ENDIF
+
+      IF( ln_timing )  CALL timing_stop('sed_dta')
       
    END SUBROUTINE sed_dta
 
-#else
-   !!======================================================================
-   !! MODULE seddta  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_dta ( kt )
-     INTEGER, INTENT(in) :: kt
-     WRITE(*,*) 'sed_stp: You should not have seen this print! error?', kt 
-  END SUBROUTINE sed_dta
-#endif
-
 END MODULE seddta
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedini.F90	(revision 10321)
@@ -4,5 +4,4 @@
    !! Sediment : define sediment variables
    !!=====================================================================
-#if defined key_sed
 
    !!----------------------------------------------------------------------
@@ -11,10 +10,11 @@
    !! * Modules used
    USE sed     ! sediment global variable
-   USE seddta
-   USE sedrst
-   USE sedco3
-   USE sedchem
+   USE sed_oce
    USE sedarr
+   USE sedadv
+   USE trcdmp_sed
+   USE trcdta
    USE iom
+   USE lib_mpp         ! distribued memory computing library
 
 
@@ -24,31 +24,55 @@
    !! Module variables
    REAL(wp)    ::  &
-      sisat   =  800.  ,  &  !: saturation for si    [ mol.l-1]
-      claysat =    0.  ,  &  !: saturation for clay  [ mol.l-1]
+      sedzmin = 0.3    ,  &  !: Minimum vertical spacing
+      sedhmax = 10.0   ,  &  !: Maximum depth of the sediment
+      sedkth  = 5.0    ,  &  !: Default parameters
+      sedacr  = 3.0          !: Default parameters
+      
+   REAL(wp)    ::  &
+      porsurf =  0.95  ,  &  !: Porosity at the surface
+      porinf  =  0.75  ,  &  !: Porosity at infinite depth
+      rhox    =  2.0         !: Vertical length scale of porosity variation 
+
+   REAL(wp)    ::  &
       rcopal  =   40.  ,  &  !: reactivity for si    [l.mol-1.an-1]
-      rcclay  =    0.  ,  &  !: reactivity for clay  [l.mol-1.an-1]
       dcoef   =  8.e-6       !: diffusion coefficient (*por)   [cm**2/s]
 
+   REAL(wp), PUBLIC    ::  &
+      redO2    =  172.  ,  &  !: Redfield coef for Oxygen
+      redNo3   =   16.  ,  &  !: Redfield coef for Nitrate
+      redPo4   =    1.  ,  &  !: Redfield coef for Phosphate
+      redC     =  122.  ,  &  !: Redfield coef for Carbon
+      redfep   =  0.175 ,  &  !: Ratio for iron bound phosphorus
+      rcorgl   =   50.  ,  &  !: reactivity for POC/O2 [l.mol-1.an-1]    
+      rcorgs   =   0.5  ,  &  !: reactivity of the semi-labile component
+      rcorgr   =   1E-4 ,  &  !: reactivity of the refractory component
+      rcnh4    =   10E6 ,  &  !: reactivity for O2/NH4 [l.mol-1.an-1]  
+      rch2s    =   1.E5 ,  &  !: reactivity for O2/ODU [l.mol-1.an-1] 
+      rcfe2    =   5.E8 ,  &  !: reactivity for O2/Fe2+ [l.mol-1.an-1]
+      rcfeh2s  =   1.E4 ,  &  !: Reactivity for FEOH/H2S [l.mol-1.an-1]
+      rcfes    =   1.E5 ,  &  !: Reactivity for FE2+/H2S [l.mol-1.an-1]
+      rcfeso   =   3.E5 ,  &  !: Reactivity for FES/O2 [l.mol-1.an-1]
+      xksedo2  =   5E-6 ,  &  !: half-sturation constant for oxic remin.
+      xksedno3 =   5E-6 ,  &  !: half-saturation constant for denitrification
+      xksedfeo =   0.6  ,  & !: half-saturation constant for iron remin
+      xksedso4 =   2E-3       !: half-saturation constant for SO4 remin
+
    REAL(wp)    ::  &
-      redO2   =  172.  ,  &  !: Redfield coef for Oxygene
-      redNo3  =   16.  ,  &  !: Redfield coef for Nitrates
-      redPo4  =    1.  ,  &  !: Redfield coef for Phosphates
-      redC    =  122.  ,  &  !: Redfield coef for Carbone
-      redDnit =  97.6  ,  &  !: Redfield coef for denitrification    
-      rcorg   =   50.  ,  &  !: reactivity for POC/O2 [l.mol-1.an-1]    
-      o2seuil =    1.  ,  &  !: threshold O2 concentration for [mol.l-1]     
-      rcorgN  =   50.       !: reactivity for POC/No3 [l.mol-1.an-1]
-
-   REAL(wp)    ::  &
-      rccal   = 1000.        !: reactivity for calcite         [l.mol-1.an-1]
-
-   REAL(wp)    ::  &
-      dbiot   = 15.          !: coefficient for bioturbation    [cm**2.(1000an-1)]
-
-   LOGICAL     :: &
-      ln_rst_sed = .TRUE.    !: initialisation from a restart file or not
-
+      rccal   = 1000.,      & !: reactivity for calcite         [l.mol-1.an-1]
+      rcligc  = 1.E-4         !: L/C ratio in POC
+
+   REAL(wp), PUBLIC    ::  dbiot   = 15. , &  !: coefficient for bioturbation    [cm**2.(n-1)]
+      dbtbzsc =  10.0  ,    &  !: Vertical scale of variation. If no variation, mixed layer in the sed [cm]
+      xirrzsc = 2.0            !: Vertical scale of irrigation variation.
    REAL(wp)    ::  &
       ryear = 365. * 24. * 3600. !:  1 year converted in second
+
+   REAL(wp), DIMENSION(jpwat), PUBLIC  :: diff1
+   DATA diff1/4.59E-6, 1.104E-5, 4.81E-6 , 9.78E-6, 3.58E-6, 4.01E-6, 9.8E-6, 9.73E-6, 5.0E-6, 3.31E-6 /
+
+   REAL(wp), DIMENSION(jpwat), PUBLIC  :: diff2
+   DATA diff2/1.74E-7, 4.47E-7, 2.51E-7, 3.89E-7, 1.77E-7, 2.5E-7, 3.89E-7, 3.06E-7, 2.5E-7, 1.5E-7 /
+
+
 
    !! *  Routine accessibility
@@ -76,10 +100,5 @@
       !!        !  06-07  (C. Ethe)  Re-organization
       !!----------------------------------------------------------------------
-      INTEGER :: ji, jj, ikt
-#if defined key_sed_off
-      INTEGER  :: numblt         
-      INTEGER  :: nummsh   
-      REAL(wp), ALLOCATABLE, DIMENSION(:,:) :: zdta
-#endif
+      INTEGER :: ji, jj, ikt, ierr
       !!----------------------------------------------------------------------
 
@@ -90,53 +109,27 @@
       CALL ctl_opn( numsed, 'sediment.output', 'REPLACE', 'FORMATTED', 'SEQUENTIAL', -1, numout, .FALSE. )
 
-      WRITE(numsed,*)
-      WRITE(numsed,*) '                 L S C E - C E A'
-      WRITE(numsed,*) '                 SEDIMENT model'
-      WRITE(numsed,*) '                version 2.0  (2007) '
-      WRITE(numsed,*)
-      WRITE(numsed,*)
-
-    
-      WRITE(numsed,*) ' sed_init : Initialization of sediment module  '
-      WRITE(numsed,*) ' '
-
-      !                                ! Allocate LOBSTER arrays
-      IF( sed_alloc() /= 0 )   CALL ctl_stop( 'STOP', 'sed_ini: unable to allocate sediment model arrays' )
-
+      IF (lwp) THEN
+         WRITE(numsed,*)
+         WRITE(numsed,*) '                 PISCES framework'
+         WRITE(numsed,*) '                 SEDIMENT model'
+         WRITE(numsed,*) '                version 3.0  (2018) '
+         WRITE(numsed,*)
+         WRITE(numsed,*)
+      ENDIF
+
+      IF(lwp) WRITE(numsed,*) ' sed_init : Initialization of sediment module  '
+      IF(lwp) WRITE(numsed,*) ' '
+
+      ! Read sediment Namelist
+      !-------------------------
+      CALL sed_init_nam
+
+      ! Allocate SEDIMENT arrays
+      ierr =        sed_alloc()
+      ierr = ierr + sed_oce_alloc()
+      ierr = ierr + sed_adv_alloc() 
+      IF( ierr /= 0 )   CALL ctl_stop( 'STOP', 'sed_ini: unable to allocate sediment model arrays' )
 
       ! Determination of sediments number of points and allocate global variables
-#if defined key_sed_off
-      ! Reading Netcdf Pisces file for deepest water layer thickness [m]
-      ! This data will be used as mask to merdge space in 1D vector
-      !----------------------------------------------------------------
-
-      CALL iom_open ( 'mesh_mask'  , nummsh )   
-      CALL iom_open ( 'e3tbot'     , numblt )
-
-      ! mask sediment points for outputs
-      CALL iom_get( nummsh, jpdom_data, 'tmask' , tmask )
-      CALL iom_get( nummsh, jpdom_data, 'mbathy', sbathy )
-      
-      ! longitude/latitude values
-      CALL iom_get ( nummsh, jpdom_data,'nav_lon', glamt(:,:) )
-      CALL iom_get ( nummsh, jpdom_data,'nav_lat', gphit(:,:) )
-    
-      ! bottom layer thickness
-      ALLOCATE( zdta(jpi,jpj) )
-      CALL iom_get  ( numblt, jpdom_data, 'E3TBOT', zdta(:,:) )
-      epkbot(:,:) = 0.
-      DO jj = 1, jpj
-         DO ji = 1, jpi
-            ikt = MAX( INT( sbathy(ji,jj) ), 1 )
-            IF( tmask(ji,jj,ikt) == 1 ) epkbot(ji,jj) = zdta(ji,jj)
-         ENDDO
-      ENDDO
-
-      CALL iom_close( nummsh )  
-      CALL iom_close( numblt ) 
-
-      DEALLOCATE( zdta )
-#else
-
       epkbot(:,:) = 0.
       DO jj = 1, jpj
@@ -144,13 +137,17 @@
             ikt = mbkt(ji,jj) 
             IF( tmask(ji,jj,ikt) == 1 ) epkbot(ji,jj) = e3t_1d(ikt)
+            gdepbot(ji,jj) = gdepw_0(ji,jj,ikt)
          ENDDO
       ENDDO
-#endif     
-
 
       ! computation of total number of ocean points
       !--------------------------------------------
-      jpoce  = COUNT( epkbot(:,:) > 0. )
-
+      sedmask = 0.
+      IF ( COUNT( epkbot(:,:) > 0. ) == 0 ) THEN 
+          sedmask = 0.
+      ELSE
+          sedmask = 1.
+      ENDIF 
+      jpoce  = MAX( COUNT( epkbot(:,:) > 0. ) , 1 )
 
       ! Allocate memory size of global variables
@@ -159,18 +156,24 @@
       ALLOCATE( rainrm(jpoce,jpsol) )        ;  ALLOCATE( rainrg(jpoce,jpsol) )        ;  ALLOCATE( raintg(jpoce) ) 
       ALLOCATE( dzdep(jpoce) )               ;  ALLOCATE( iarroce(jpoce) )             ;  ALLOCATE( dzkbot(jpoce) )
-      ALLOCATE( temp(jpoce) )                ;  ALLOCATE( salt(jpoce) )                
+      ALLOCATE( zkbot(jpoce) )               ;  ALLOCATE( db(jpoce,jpksed) )
+      ALLOCATE( temp(jpoce) )                ;  ALLOCATE( salt(jpoce) )  
+      ALLOCATE( diff(jpoce,jpksed,jpwat ) )  ;  ALLOCATE( irrig(jpoce, jpksed) )
+      ALLOCATE( wacc(jpoce) )                ;  ALLOCATE( fecratio(jpoce) )
       ALLOCATE( press(jpoce) )               ;  ALLOCATE( densSW(jpoce) ) 
-      ALLOCATE( hipor(jpoce,jpksed) )        ;  ALLOCATE( co3por(jpoce,jpksed) ) 
+      ALLOCATE( hipor(jpoce,jpksed) )        ;  ALLOCATE( co3por(jpoce,jpksed) )
       ALLOCATE( dz3d(jpoce,jpksed) )         ;  ALLOCATE( volw3d(jpoce,jpksed) )       ;  ALLOCATE( vols3d(jpoce,jpksed) )
+      ALLOCATE( sedligand(jpoce, jpksed) )
 
       ! Initialization of global variables
-      pwcp  (:,:,:) = 0.  ;  pwcp0 (:,:,:) = 0.  ; pwcp_dta  (:,:) = 0.  
-      solcp (:,:,:) = 0.  ;  solcp0(:,:,:) = 0.  ; rainrm_dta(:,:) = 0.
-      rainrm(:,:  ) = 0.  ;  rainrg(:,:  ) = 0.  ; raintg    (:  ) = 0. 
-      dzdep (:    ) = 0.  ;  iarroce(:   ) = 0   ; dzkbot    (:  ) = 0.
-      temp  (:    ) = 0.  ;  salt   (:   ) = 0.  
-      press (:    ) = 0.  ;  densSW (:   ) = 0. 
-      hipor (:,:  ) = 0.  ;  co3por (:,: ) = 0.  
-      dz3d  (:,:  ) = 0.  ;  volw3d (:,: ) = 0.  ;  vols3d   (:,:) = 0. 
+      pwcp  (:,:,:) = 0.   ;  pwcp0 (:,:,:) = 0.  ; pwcp_dta  (:,:) = 0.  
+      solcp (:,:,:) = 0.   ;  solcp0(:,:,:) = 0.  ; rainrm_dta(:,:) = 0.
+      rainrm(:,:  ) = 0.   ;  rainrg(:,:  ) = 0.  ; raintg    (:  ) = 0. 
+      dzdep (:    ) = 0.   ;  iarroce(:   ) = 0   ; dzkbot    (:  ) = 0.
+      temp  (:    ) = 0.   ;  salt   (:   ) = 0.  ; zkbot     (:  ) = 0.
+      press (:    ) = 0.   ;  densSW (:   ) = 0.  ; db        (:,:) = 0. 
+      hipor (:,:  ) = 0.   ;  co3por (:,: ) = 0.  ; irrig     (:,:) = 0. 
+      dz3d  (:,:  ) = 0.   ;  volw3d (:,: ) = 0.  ; vols3d    (:,:) = 0. 
+      fecratio(:)   = 1E-5 
+      sedligand(:,:) = 0.6E-9
 
       ! Chemical variables      
@@ -178,10 +181,13 @@
       ALLOCATE( ak1ps (jpoce) )  ;  ALLOCATE( ak2ps  (jpoce) )  ;  ALLOCATE( ak3ps (jpoce) ) ;  ALLOCATE( aksis (jpoce) )    
       ALLOCATE( aksps (jpoce) )  ;  ALLOCATE( ak12s  (jpoce) )  ;  ALLOCATE( ak12ps(jpoce) ) ;  ALLOCATE( ak123ps(jpoce) )    
-      ALLOCATE( borats(jpoce) )  ;  ALLOCATE( calcon2(jpoce) )    
+      ALLOCATE( borats(jpoce) )  ;  ALLOCATE( calcon2(jpoce) )  ;  ALLOCATE( sieqs (jpoce) ) 
+      ALLOCATE( aks3s(jpoce) )   ;  ALLOCATE( akf3s(jpoce) )    ;  ALLOCATE( sulfats(jpoce) )
+      ALLOCATE( fluorids(jpoce) )
 
       akbs  (:) = 0. ;   ak1s   (:) = 0. ;  ak2s  (:) = 0. ;   akws   (:) = 0.
       ak1ps (:) = 0. ;   ak2ps  (:) = 0. ;  ak3ps (:) = 0. ;   aksis  (:) = 0.
       aksps (:) = 0. ;   ak12s  (:) = 0. ;  ak12ps(:) = 0. ;   ak123ps(:) = 0.
-      borats(:) = 0. ;   calcon2(:) = 0.
+      borats(:) = 0. ;   calcon2(:) = 0. ;  sieqs (:) = 0.
+      aks3s(:)  = 0. ;   akf3s(:)   = 0. ;  sulfats(:) = 0. ;  fluorids(:) = 0.
 
       ! Mass balance calculation  
@@ -191,24 +197,28 @@
       fromsed(:,:) = 0.    ;   tosed(:,:) = 0. ;  rloss(:,:) = 0.  ;   tokbot(:,:) = 0. 
 
-      ! Read sediment Namelist
-      !-------------------------
-      CALL sed_init_nam
-    
       ! Initialization of sediment geometry
       !------------------------------------
       CALL sed_init_geom
 
-
-      ! sets initial sediment composition
-      ! ( only clay or reading restart file )
-      !---------------------------------------
-      CALL sed_init_data
-
-
-      CALL sed_init_wri
-
+      ! Offline specific mode
+      ! ---------------------
+      ln_sediment_offline = .FALSE.
+
+#if defined key_sed_off
+      ln_sediment_offline = .TRUE.
+      IF (lwp) write(numsed,*) 'Sediment module is run in offline mode'
+      IF (lwp) write(numsed,*) 'key_sed_off is activated at compilation time'
+      IF (lwp) write(numsed,*) 'ln_sed_2way is forced to false'
+      IF (lwp) write(numsed,*) '--------------------------------------------'
+      ln_sed_2way = .FALSE.
+#endif
+      ! Initialisation of tracer damping
+      ! --------------------------------
+      IF (ln_sediment_offline) THEN
+         CALL trc_dta_ini(jptra)
+         CALL trc_dmp_sed_ini
+      ENDIF
 
    END SUBROUTINE sed_init
-
 
    SUBROUTINE sed_init_geom
@@ -227,15 +237,11 @@
       !! * Modules used
       !! * local declarations
-      INTEGER ::  &
-        ji, jj, jk
- 
-#if defined key_sed_off
-      REAL(wp) , DIMENSION (jpi,jpj) :: zdta
-      INTEGER  ::  numpres
-#endif
+      INTEGER  :: ji, jj, jk, jn
+      REAL(wp) :: za0, za1, zt, zw, zsum, zsur, zprof, zprofw
+      REAL(wp) :: ztmp1, ztmp2
       !---------------------------------------------------------- 
 
-      WRITE(numsed,*) ' sed_init_geom : Initialization of sediment geometry '
-      WRITE(numsed,*) ' '
+      IF(lwp) WRITE(numsed,*) ' sed_init_geom : Initialization of sediment geometry '
+      IF(lwp) WRITE(numsed,*) ' '
 
       ! Computation of 1D array of sediments points
@@ -250,37 +256,16 @@
       END DO
 
+      IF ( indoce .EQ. 0 ) THEN
+         indoce = 1
+         iarroce(indoce) = 1
+      ENDIF
+
       IF( indoce .NE. jpoce ) THEN
-         WRITE(numsed,*) ' '
-         WRITE(numsed,*) 'Warning : number of ocean points indoce = ', indoce, &
-            &     ' doesn''t match  number of point where epkbot>0  jpoce = ', jpoce
-         WRITE(numsed,*) ' '
-         WRITE(numsed,*) ' '
-         STOP
+         CALL ctl_stop( 'STOP', 'sed_ini: number of ocean points indoce doesn''t match  number of point' )
       ELSE
-         WRITE(numsed,*) ' '
-         WRITE(numsed,*) ' total number of ocean points jpoce =  ',jpoce
-         WRITE(numsed,*) ' '
-      ENDIF
-
-#if defined key_sed_off
-
-      ! Reading Netcdf Pisces file for deepest water layer thickness [m]
-      ! This data will be used as mask to merdge space in 1D vector
-      !----------------------------------------------------------------
-      CALL iom_open ( 'pressbot'   , numpres )
-      
-      ! pressure  in  bars      
-      CALL iom_get ( numpres, jpdom_data,'BATH', zdta(:,:) )
-      CALL pack_arr ( jpoce, press(1:jpoce), zdta(1:jpi,1:jpj), iarroce(1:jpoce) )
-      press(1:jpoce) = press(1:jpoce) * 1.025e-1 
-
-      CALL iom_close ( numpres )
-#endif
-
-
-      ! mask sediment points for outputs
-      DO jk = 1, jpksed
-         tmasksed(:,:,jk) = tmask(:,:,1)
-      ENDDO
+         IF (lwp) WRITE(numsed,*) ' '
+         IF (lwp) WRITE(numsed,*) ' total number of ocean points jpoce =  ',jpoce
+         IF (lwp) WRITE(numsed,*) ' '
+      ENDIF
 
       ! initialization of dzkbot in [cm]
@@ -288,4 +273,5 @@
       CALL pack_arr ( jpoce, dzkbot(1:jpoce), epkbot(1:jpi,1:jpj), iarroce(1:jpoce) )
       dzkbot(1:jpoce) = dzkbot(1:jpoce) * 1.e+2 
+      CALL pack_arr ( jpoce, zkbot(1:jpoce), gdepbot(1:jpi,1:jpj), iarroce(1:jpoce) )
 
       ! Geometry and  constants 
@@ -293,15 +279,23 @@
       ! (1st layer= diffusive layer = pur water) 
       !------------------------------------------
-      dz(1)  = 0.1
-      dz(2)  = 0.3
-      dz(3)  = 0.3
-      dz(4)  = 0.5
-      dz(5)  = 0.5
-      dz(6)  = 0.5
-      dz(7)  = 1.
-      dz(8)  = 1.
-      dz(9)  = 1.
-      dz(10) = 2.45
-      dz(11) = 2.45
+      za1  = (  sedzmin - sedhmax / FLOAT(jpksed-1)  )                                                      &
+         & / ( TANH((1-sedkth)/sedacr) - sedacr/FLOAT(jpksed-1) * (  LOG( COSH( (jpksed - sedkth) / sedacr) )      &
+         &                                                   - LOG( COSH( ( 1  - sedkth) / sedacr) )  )  )
+      za0  = sedzmin - za1 * TANH( (1-sedkth) / sedacr )
+      zsur = - za0 - za1 * sedacr * LOG( COSH( (1-sedkth) / sedacr )  )
+
+      profsedw(1) = 0.0
+      profsed(1) = -dz(1) / 2.
+      DO jk = 2, jpksed
+         zw = REAL( jk , wp )
+         zt = REAL( jk , wp ) - 0.5_wp
+         profsed(jk)  = ( zsur + za0 * zt + za1 * sedacr * LOG ( COSH( (zt-sedkth) / sedacr ) )  ) 
+         profsedw(jk) = ( zsur + za0 * zw + za1 * sedacr * LOG ( COSH( (zw-sedkth) / sedacr ) )  )
+      END DO
+
+      dz(1) = 0.1
+      DO jk = 2, jpksed
+         dz(jk) = profsedw(jk) - profsedw(jk-1)
+      END DO
 
       DO jk = 1, jpksed
@@ -311,24 +305,10 @@
       ENDDO
 
-      ! Depth(jk)= depth of middle of each layer
-      !----------------------------------------
-      profsed(1) = -dz(1)/ 2.
-      DO jk = 2, jpksed
-         profsed(jk) = profsed(jk-1) + dz(jk-1) / 2. + dz(jk) / 2.
-      ENDDO
-
       !  Porosity profile [0]
       !---------------------
-      por(1)  = 1.
-      por(2)  = 0.95
-      por(3)  = 0.9
-      por(4)  = 0.85
-      por(5)  = 0.81
-      por(6)  = 0.75
-      por(7)  = 0.75      
-      por(8)  = 0.75      
-      por(9)  = 0.75      
-      por(10) = 0.75
-      por(11) = 0.75
+      por(1) = 1.0
+      DO jk = 2, jpksed
+         por(jk) = porinf + ( porsurf-porinf) * exp(-rhox * (profsed(jk) ) )
+      END DO
  
       ! inverse of  Porosity profile
@@ -353,9 +333,7 @@
       dz3d(1:jpoce,1) = dz(1)
 
-
       !---------------------------------------------
       ! Molecular weight [g/mol] for solid species
       !---------------------------------------------
-
 
       ! opal=sio2*0.4(h20)=28+2*16+0.4*(2+16)
@@ -371,4 +349,8 @@
          &              0.59 * 27. + 10. * 16.
 
+      mol_wgt(jsfeo)  = 55.0 + 3.0 * ( 16.0 + 1.0)
+
+      mol_wgt(jsfes)  = 55.0 + 32.0
+
       ! for chemistry Poc : C(122)H(244)O(86)N(16)P(1)
       ! But den sity of Poc is an Hydrated material (= POC + 30H2O)
@@ -377,4 +359,6 @@
       mol_wgt(jspoc) = ( 122. * 12. + 355. + 120. * 16.+ &
          &                16. * 14. + 31. ) / 122.
+      mol_wgt(jspos) = mol_wgt(jspoc)
+      mol_wgt(jspor) = mol_wgt(jspoc)
 
       ! CaCO3
@@ -384,15 +368,28 @@
       ! Density of solid material in sediment [g/cm**3]
       !------------------------------------------------
-      dens = 2.6
+      denssol = 2.6
 
       ! Initialization of diffusion coefficient as function of porosity [cm**2/s]
       !--------------------------------------------------------------------
-      diff(:) = dcoef * por(:)
+!      DO jn = 1, jpsol
+!         DO jk = 1, jpksed
+!            DO ji = 1, jpoce
+!               diff(ji,jk,jn) = dcoef / ( 1.0 - 2.0 * log(por(jk)) )
+!            END DO
+!         END DO
+!      END DO
+
+      ! Accumulation rate from Burwicz et al. (2011). This is used to
+      ! compute the flux of clays and minerals
+      ! --------------------------------------------------------------
+      DO ji = 1, jpoce
+          ztmp1 = 0.117 / ( 1.0 + ( zkbot(ji) / 200.)**3 )
+          ztmp2 = 0.006 / ( 1.0 + ( zkbot(ji) / 4000.)**10 )
+          wacc(ji) = ztmp1 + ztmp2
+      END DO
 
 
       ! Initialization of time step as function of porosity [cm**2/s]
       !------------------------------------------------------------------
-      rdtsed(2:jpksed) = dtsed / ( dens * por1(2:jpksed) )
-     
    END SUBROUTINE sed_init_geom
 
@@ -408,6 +405,8 @@
       !!----------------------------------------------------------------------
 
-      INTEGER :: &
-         numnamsed = 28
+      INTEGER ::   numnamsed_ref = -1           !! Logical units for namelist sediment
+      INTEGER ::   numnamsed_cfg = -1           !! Logical units for namelist sediment
+      INTEGER :: ios                 ! Local integer output status for namelist read
+      CHARACTER(LEN=20)   ::   clname
 
       TYPE PSED
@@ -422,57 +421,84 @@
       TYPE(PSED) , DIMENSION(jpdia2dsed) :: seddiag2d
 
-      NAMELIST/nam_time/nfreq
+      NAMELIST/nam_run/nrseddt,ln_sed_2way
+      NAMELIST/nam_geom/jpksed, sedzmin, sedhmax, sedkth, sedacr, porsurf, porinf, rhox
       NAMELIST/nam_trased/sedsol, sedwat
       NAMELIST/nam_diased/seddiag3d, seddiag2d
-      NAMELIST/nam_reac/sisat, claysat, rcopal, rcclay, dcoef 
-      NAMELIST/nam_poc/redO2, redNo3, redPo4, redC, redDnit, &
-         &           rcorg, o2seuil, rcorgN
-      NAMELIST/nam_cal/rccal
-      NAMELIST/nam_dc13/pdb, rc13P, rc13Ca
-      NAMELIST/nam_btb/dbiot
-      NAMELIST/nam_rst/ln_rst_sed
-
-      INTEGER :: jn, jn1
+      NAMELIST/nam_inorg/rcopal, dcoef, rccal, ratligc, rcligc
+      NAMELIST/nam_poc/redO2, redNo3, redPo4, redC, redfep, rcorgl, rcorgs,  &
+         &             rcorgr, rcnh4, rch2s, rcfe2, rcfeh2s, rcfes, rcfeso,  &
+         &             xksedo2, xksedno3, xksedfeo, xksedso4
+      NAMELIST/nam_btb/dbiot, ln_btbz, dbtbzsc, adsnh4, ln_irrig, xirrzsc
+      NAMELIST/nam_rst/ln_rst_sed, cn_sedrst_indir, cn_sedrst_outdir, cn_sedrst_in, cn_sedrst_out
+
+      INTEGER :: ji, jn, jn1
       !-------------------------------------------------------
 
-      WRITE(numsed,*) ' sed_init_nam : Read namelists '
-      WRITE(numsed,*) ' '
+      IF(lwp) WRITE(numsed,*) ' sed_init_nam : Read namelists '
+      IF(lwp) WRITE(numsed,*) ' '
 
       ! ryear = 1 year converted in second
       !------------------------------------
-      WRITE(numsed,*) ' '
-      WRITE(numsed,*) 'number of seconds in one year : ryear = ', ryear
-      WRITE(numsed,*) ' '     
+      IF (lwp) THEN
+         WRITE(numsed,*) ' '
+         WRITE(numsed,*) 'number of seconds in one year : ryear = ', ryear
+         WRITE(numsed,*) ' '     
+      ENDIF
 
       ! Reading namelist.sed variables
       !---------------------------------
-      CALL ctl_opn( numnamsed, 'namelist.sediment', 'OLD', 'FORMATTED', 'SEQUENTIAL', -1, numout, .FALSE. )
-
-      dtsed = rdt
+      clname = 'namelist_sediment'
+      IF(lwp) WRITE(numsed,*) ' sed_init_nam : read SEDIMENT namelist'
+      IF(lwp) WRITE(numsed,*) ' ~~~~~~~~~~~~~~'
+      CALL ctl_opn( numnamsed_ref, TRIM( clname )//'_ref', 'OLD'    , 'FORMATTED', 'SEQUENTIAL', -1, numout, .FALSE. )
+      CALL ctl_opn( numnamsed_cfg, TRIM( clname )//'_cfg', 'OLD'    , 'FORMATTED', 'SEQUENTIAL', -1, numout, .FALSE. )
+
       nitsed000 = nittrc000
       nitsedend = nitend
-#if ! defined key_sed_off
-      nwrised   = nwritetrc
-#else
-      nwrised   = nwrite
-#endif
-     ! Diffraction/reaction parameters
-      !----------------------------------
-      READ( numnamsed, nam_time )
-      WRITE(numsed,*) ' namelist nam_time'
-
-#if ! defined key_sed_off
-      nfreq     = 1
-#endif
-
-      WRITE(numsed,*) ' sedimentation time step              dtsed      = ', dtsed
-      WRITE(numsed,*) ' 1st time step for sediment.          nitsed000  = ', nitsed000
-      WRITE(numsed,*) ' last time step for sediment.         nitsedend  = ', nitsedend
-      WRITE(numsed,*) ' frequency of sediment outputs        nwrised    = ', nwrised
-      WRITE(numsed,*) ' frequency of restoring inputs data   nfreq      = ', nfreq
-      WRITE(numsed,*) ' '
-
-      REWIND( numnamsed )               ! read nattrc
-      READ  ( numnamsed, nam_trased )
+      ! Namelist nam_run
+      REWIND( numnamsed_ref )              ! Namelist nam_run in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_run, IOSTAT = ios, ERR = 901)
+901   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_run in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_run in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_run, IOSTAT = ios, ERR = 902)
+902   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_run in configuration namelist', lwp )
+
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_run'
+         WRITE(numsed,*) ' Nb of iterations for fast species    nrseddt = ', nrseddt
+         WRITE(numsed,*) ' 2-way coupling between PISCES and Sed ln_sed_2way = ', ln_sed_2way
+      ENDIF
+
+      REWIND( numnamsed_ref )              ! Namelist nam_geom in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_geom, IOSTAT = ios, ERR = 903)
+903   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_geom in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_geom in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_geom, IOSTAT = ios, ERR = 904)
+904   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_geom in configuration namelist', lwp )
+
+      IF (lwp) THEN 
+         WRITE(numsed,*) ' namelist nam_geom'
+         WRITE(numsed,*) ' Number of vertical layers            jpksed  = ', jpksed
+         WRITE(numsed,*) ' Minimum vertical spacing             sedzmin = ', sedzmin
+         WRITE(numsed,*) ' Maximum depth of the sediment        sedhmax = ', sedhmax
+         WRITE(numsed,*) ' Default parameter                    sedkth  = ', sedkth
+         WRITE(numsed,*) ' Default parameter                    sedacr  = ', sedacr
+         WRITE(numsed,*) ' Sediment porosity at the surface     porsurf = ', porsurf
+         WRITE(numsed,*) ' Sediment porosity at infinite depth  porinf  = ', porinf
+         WRITE(numsed,*) ' Length scale of porosity variation   rhox    = ', rhox
+      ENDIF
+
+      jpksedm1  = jpksed - 1
+      dtsed = r2dttrc
+
+      REWIND( numnamsed_ref )              ! Namelist nam_trased in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_trased, IOSTAT = ios, ERR = 905)
+905   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_trased in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_trased in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_trased, IOSTAT = ios, ERR = 906)
+906   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_trased in configuration namelist', lwp )
 
       DO jn = 1, jpsol
@@ -489,18 +515,24 @@
       END DO
 
-      WRITE(numsed,*) ' namelist nam_trased'
-      WRITE(numsed,*) ' '
-      DO jn = 1, jptrased
-         WRITE(numsed,*) 'name of 3d output sediment field number :',jn,' : ',TRIM(sedtrcd(jn))
-         WRITE(numsed,*) 'long name ', TRIM(sedtrcl(jn))
-         WRITE(numsed,*) ' in unit = ', TRIM(sedtrcu(jn))
-         WRITE(numsed,*) ' '
-      END DO
-      WRITE(numsed,*) ' '
-
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_trased'
+         WRITE(numsed,*) ' '
+         DO jn = 1, jptrased
+            WRITE(numsed,*) 'name of 3d output sediment field number :',jn,' : ',TRIM(sedtrcd(jn))
+            WRITE(numsed,*) 'long name ', TRIM(sedtrcl(jn))
+            WRITE(numsed,*) ' in unit = ', TRIM(sedtrcu(jn))
+            WRITE(numsed,*) ' '
+         END DO
+         WRITE(numsed,*) ' '
+      ENDIF
+
+      REWIND( numnamsed_ref )              ! Namelist nam_diased in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_diased, IOSTAT = ios, ERR = 907)
+907   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_diased in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_diased in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_diased, IOSTAT = ios, ERR = 908)
+908   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_diased in configuration namelist', lwp )
       
-      REWIND( numnamsed )
-      READ( numnamsed, nam_diased )
-
       DO jn = 1, jpdia3dsed
          seddia3d(jn) = seddiag3d(jn)%snamesed
@@ -515,352 +547,144 @@
       END DO
 
-      WRITE(numsed,*) ' namelist nam_diased'
-      WRITE(numsed,*) ' '
-      DO jn = 1, jpdia3dsed
-         WRITE(numsed,*) 'name of 3D output diag number :',jn, ' : ', TRIM(seddia3d(jn))
-         WRITE(numsed,*) 'long name ', TRIM(seddia3l(jn))
-         WRITE(numsed,*) ' in unit = ',TRIM(seddia3u(jn))
-         WRITE(numsed,*) ' '
-      END DO
-
-      DO jn = 1, jpdia2dsed
-         WRITE(numsed,*) 'name of 2D output diag number :',jn, ' : ', TRIM(seddia2d(jn))
-         WRITE(numsed,*) 'long name ', TRIM(seddia2l(jn))
-         WRITE(numsed,*) ' in unit = ',TRIM(seddia2u(jn))
-         WRITE(numsed,*) ' '
-      END DO
-
-      WRITE(numsed,*) ' '
-
-
-      ! Diffraction/reaction parameters
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_diased'
+         WRITE(numsed,*) ' '
+         DO jn = 1, jpdia3dsed
+            WRITE(numsed,*) 'name of 3D output diag number :',jn, ' : ', TRIM(seddia3d(jn))
+            WRITE(numsed,*) 'long name ', TRIM(seddia3l(jn))
+            WRITE(numsed,*) ' in unit = ',TRIM(seddia3u(jn))
+            WRITE(numsed,*) ' '
+         END DO
+
+         DO jn = 1, jpdia2dsed
+            WRITE(numsed,*) 'name of 2D output diag number :',jn, ' : ', TRIM(seddia2d(jn))
+            WRITE(numsed,*) 'long name ', TRIM(seddia2l(jn))
+            WRITE(numsed,*) ' in unit = ',TRIM(seddia2u(jn))
+            WRITE(numsed,*) ' '
+         END DO
+
+         WRITE(numsed,*) ' '
+      ENDIF
+
+      ! Inorganic chemistry parameters
       !----------------------------------
-      REWIND( numnamsed )
-      READ( numnamsed, nam_reac )
-      WRITE(numsed,*) ' namelist nam_reac'
-      WRITE(numsed,*) ' saturation for si    sisat   = ', sisat
-      WRITE(numsed,*) ' saturation for clay  claysat = ', claysat
-      WRITE(numsed,*) ' reactivity for Si    rcopal  = ', rcopal
-      WRITE(numsed,*) ' reactivity for clay  rcclay  = ', rcclay
-      WRITE(numsed,*) ' diff. coef for por.  dcoef   = ', dcoef
-      WRITE(numsed,*) ' '
-
+      REWIND( numnamsed_ref )              ! Namelist nam_inorg in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_inorg, IOSTAT = ios, ERR = 909)
+909   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_inorg in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_inorg in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_inorg, IOSTAT = ios, ERR = 910)
+910   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_inorg in configuration namelist', lwp )
+
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_inorg'
+         WRITE(numsed,*) ' reactivity for Si      rcopal  = ', rcopal
+         WRITE(numsed,*) ' diff. coef for por.    dcoef   = ', dcoef
+         WRITE(numsed,*) ' reactivity for calcite rccal   = ', rccal
+         WRITE(numsed,*) ' L/C ratio in POC       ratligc = ', ratligc
+         WRITE(numsed,*) ' reactivity for ligands rcligc  = ', rcligc
+         WRITE(numsed,*) ' '
+      ENDIF
 
       ! Unity conversion to get saturation conc. psat in [mol.l-1]
       ! and reactivity rc in  [l.mol-1.s-1]
       !----------------------------------------------------------
-      sat_sil   = sisat   * 1.e-6   
-      sat_clay  = claysat * 1.e-6
-
-      reac_sil  = rcopal / ryear     
-      reac_clay  = rcclay / ryear
-
+      reac_sil   = rcopal / ryear     
+      reac_ligc  = rcligc / ryear
 
       ! Additional parameter linked to POC/O2/No3/Po4
       !----------------------------------------------
-      REWIND( numnamsed )
-      READ( numnamsed, nam_poc )
-      WRITE(numsed,*) ' namelist nam_poc'
-      WRITE(numsed,*) ' Redfield coef for oxy     redO2   = ', redO2
-      WRITE(numsed,*) ' Redfield coef for no3     redNo3  = ', redNo3
-      WRITE(numsed,*) ' Redfield coef for po4     redPo4  = ', redPo4
-      WRITE(numsed,*) ' Redfield coef for carbone redC    = ', redC
-      WRITE(numsed,*) ' Redfield coef for denitri redDnit = ', redDnit
-      WRITE(numsed,*) ' reactivity for POC/O2     rcorg   = ', rcorg
-      WRITE(numsed,*) ' threshold O2 concen.      o2seuil = ', o2seuil
-      WRITE(numsed,*) ' reactivity for POC/NO3    rcorgN  = ', rcorgN
-      WRITE(numsed,*) ' '
-
-
-      so2ut  = redO2   / redC
-      srno3  = redNo3  / redC
-      spo4r  = redPo4  / redC
-      srDnit = redDnit / redC
-      sthro2 = o2seuil * 1.e-6 ! threshold O2 concen. in [mol.l-1]
+      REWIND( numnamsed_ref )              ! Namelist nam_poc in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_poc, IOSTAT = ios, ERR = 911)
+911   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_poc in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_poc in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_poc, IOSTAT = ios, ERR = 912)
+912   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_poc in configuration namelist', lwp )
+
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_poc'
+         WRITE(numsed,*) ' Redfield coef for oxy            redO2    = ', redO2
+         WRITE(numsed,*) ' Redfield coef for no3            redNo3   = ', redNo3
+         WRITE(numsed,*) ' Redfield coef for po4            redPo4   = ', redPo4
+         WRITE(numsed,*) ' Redfield coef for carbon         redC     = ', redC
+         WRITE(numsed,*) ' Ration for iron bound P          redfep   = ', redfep
+         WRITE(numsed,*) ' reactivity for labile POC        rcorgl   = ', rcorgl
+         WRITE(numsed,*) ' reactivity for semi-refract. POC rcorgs   = ', rcorgs
+         WRITE(numsed,*) ' reactivity for refractory POC    rcorgr   = ', rcorgr
+         WRITE(numsed,*) ' reactivity for NH4               rcnh4    = ', rcnh4
+         WRITE(numsed,*) ' reactivity for H2S               rch2s    = ', rch2s
+         WRITE(numsed,*) ' reactivity for Fe2+              rcfe2    = ', rcfe2
+         WRITE(numsed,*) ' reactivity for FeOH/H2S          rcfeh2s  = ', rcfeh2s
+         WRITE(numsed,*) ' reactivity for Fe2+/H2S          rcfes    = ', rcfes
+         WRITE(numsed,*) ' reactivity for FeS/O2            rcfeso   = ', rcfeso
+         WRITE(numsed,*) ' Half-sat. cste for oxic remin    xksedo2  = ', xksedo2
+         WRITE(numsed,*) ' Half-sat. cste for denit.        xksedno3 = ', xksedno3
+         WRITE(numsed,*) ' Half-sat. cste for iron remin    xksedfeo = ', xksedfeo
+         WRITE(numsed,*) ' Half-sat. cste for SO4 remin     xksedso4 = ', xksedso4
+         WRITE(numsed,*) ' '
+      ENDIF
+
+
+      so2ut  = redO2    / redC
+      srno3  = redNo3   / redC
+      spo4r  = redPo4   / redC
+      srDnit = ( (redO2 + 32. ) * 0.8 - redNo3 - redNo3 * 0.6 ) / redC
       ! reactivity rc in  [l.mol-1.s-1]
-      reac_poc  = rcorg / ryear
-      reac_no3 = rcorgN  / ryear
-
-
-      ! Carbonate parameters
-      !---------------------
-      READ( numnamsed, nam_cal )
-      WRITE(numsed,*) ' namelist  nam_cal'
-      WRITE(numsed,*) ' reactivity for calcite rccal = ', rccal
-      WRITE(numsed,*) ' '
+      reac_pocl  = rcorgl / ryear
+      reac_pocs  = rcorgs / ryear
+      reac_pocr  = rcorgr / ryear
+      reac_nh4   = rcnh4  / ryear
+      reac_h2s   = rch2s  / ryear
+      reac_fe2   = rcfe2  / ryear
+      reac_feh2s = rcfeh2s/ ryear
+      reac_fes   = rcfes  / ryear
+      reac_feso  = rcfeso / ryear
 
       ! reactivity rc in  [l.mol-1.s-1]      
       reac_cal = rccal / ryear
 
-
-      ! C13  parameters
-      !----------------
-      READ( numnamsed, nam_dc13 )
-      WRITE(numsed,*) ' namelist nam_dc13 ' 
-      WRITE(numsed,*) ' 13C/12C in PD Belemnite        PDB    = ', pdb
-      WRITE(numsed,*) ' 13C/12C in POC = rc13P*PDB     rc13P  = ', rc13P
-      WRITE(numsed,*) ' 13C/12C in CaCO3 = rc13Ca*PDB  rc13Ca = ', rc13Ca
-      WRITE(numsed,*) ' '
-
-      
       ! Bioturbation parameter
       !------------------------
-      READ( numnamsed, nam_btb )
-      WRITE(numsed,*) ' namelist nam_btb ' 
-      WRITE(numsed,*) ' coefficient for bioturbation   dbiot    = ', dbiot
-      WRITE(numsed,*) ' '
-
-      ! Unity convertion to get bioturb coefficient in [cm2.s-1]
-      db = dbiot / ( ryear * 1000. )
+      REWIND( numnamsed_ref )              ! Namelist nam_btb in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_btb, IOSTAT = ios, ERR = 913)
+913   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_btb in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_btb in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_btb, IOSTAT = ios, ERR = 914)
+914   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_btb in configuration namelist', lwp )
+
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist nam_btb ' 
+         WRITE(numsed,*) ' coefficient for bioturbation      dbiot    = ', dbiot
+         WRITE(numsed,*) ' Depth varying bioturbation        ln_btbz  = ', ln_btbz
+         WRITE(numsed,*) ' coefficient for btb attenuation   dbtbzsc  = ', dbtbzsc
+         WRITE(numsed,*) ' Adsorption coefficient of NH4     adsnh4   = ', adsnh4
+         WRITE(numsed,*) ' Bioirrigation in sediment         ln_irrig = ', ln_irrig
+         WRITE(numsed,*) ' coefficient for irrig attenuation xirrzsc  = ', xirrzsc
+         WRITE(numsed,*) ' '
+      ENDIF
 
       ! Initial value (t=0) for sediment pore water and solid components
       !----------------------------------------------------------------
-      READ( numnamsed, nam_rst )
-      WRITE(numsed,*) ' namelist  nam_rst ' 
-      WRITE(numsed,*) '  boolean term for restart (T or F) ln_rst_sed = ', ln_rst_sed 
-      WRITE(numsed,*) ' '
-
-      CLOSE( numnamsed )
+      REWIND( numnamsed_ref )              ! Namelist nam_rst in reference namelist : Pisces variables
+      READ  ( numnamsed_ref, nam_rst, IOSTAT = ios, ERR = 915)
+915   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_rst in reference namelist', lwp )
+
+      REWIND( numnamsed_cfg )              ! Namelist nam_rst in reference namelist : Pisces variables
+      READ  ( numnamsed_cfg, nam_rst, IOSTAT = ios, ERR = 916)
+916   IF( ios /= 0 ) CALL ctl_nam ( ios , 'nam_rst in configuration namelist', lwp )
+
+      IF (lwp) THEN
+         WRITE(numsed,*) ' namelist  nam_rst ' 
+         WRITE(numsed,*) '  boolean term for restart (T or F) ln_rst_sed = ', ln_rst_sed 
+         WRITE(numsed,*) ' '
+      ENDIF
+      nn_dtsed = nn_dttrc
+
+      CLOSE( numnamsed_cfg )
+      CLOSE( numnamsed_ref )
 
    END SUBROUTINE sed_init_nam
 
-   SUBROUTINE sed_init_data
-      !!----------------------------------------------------------------------
-      !!                   ***  ROUTINE sed_init_data  ***
-      !!
-      !! ** Purpose :  Initialization of sediment module
-      !!               - sets initial sediment composition
-      !!                 ( only clay or reading restart file )
-      !!
-      !!   History :
-      !!        !  06-07  (C. Ethe)  original
-      !!----------------------------------------------------------------------
- 
-      ! local variables
-      INTEGER :: &
-         ji, jk, zhipor
-
-      !--------------------------------------------------------------------
- 
-
-      IF( .NOT. ln_rst_sed ) THEN
-
-          WRITE(numsed,*) ' Initilization of default values of sediment components'
-
-         ! default values for initial pore water concentrations [mol/l]
-         pwcp(:,:,:) = 0.
-         ! default value for initial solid component (fraction of dry weight dim=[0])
-         ! clay
-         solcp(:,:,:) = 0.
-         solcp(:,2:jpksed,jsclay) = 1.
-
-         ! Initialization of [h+] and [co3--]
-
-         zhipor = 8.
-         ! Initialization of [h+] in mol/kg
-         DO jk = 1, jpksed
-            DO ji = 1, jpoce
-               hipor (ji,jk) = 10.**( -1. * zhipor )
-            ENDDO
-         ENDDO
-
-         co3por(:,:) = 0.
-
-      ELSE   
-  
-         WRITE(numsed,*) ' Initilization of Sediment components from restart'
-
-         CALL sed_rst_read
-
-      ENDIF
-
-
-      ! Load initial Pisces Data for bot. wat. Chem and fluxes
-      CALL sed_dta ( nitsed000 ) 
-
-      ! Initialization of chemical constants
-      CALL sed_chem ( nitsed000 )
-
-      ! Stores initial sediment data for mass balance calculation
-      pwcp0 (1:jpoce,1:jpksed,1:jpwat ) = pwcp (1:jpoce,1:jpksed,1:jpwat ) 
-      solcp0(1:jpoce,1:jpksed,1:jpsol ) = solcp(1:jpoce,1:jpksed,1:jpsol) 
-
-      ! Conversion of [h+] in mol/Kg to get it in mol/l ( multiplication by density)
-      DO jk = 1, jpksed
-         hipor(1:jpoce,jk) = hipor(1:jpoce,jk) * densSW(1:jpoce)
-      ENDDO
-
-
-      ! In default case - no restart - sedco3 is run to initiate [h+] and [co32-]
-      ! Otherwise initiate values of pH and co3 read in restart
-      IF( .NOT. ln_rst_sed ) THEN
-         ! sedco3 is run to initiate[h+] [co32-] in mol/l of solution
-         CALL sed_co3 ( nitsed000 )
-
-      ENDIF
-            
-   END SUBROUTINE sed_init_data
-
-   SUBROUTINE sed_init_wri
-
-      INTEGER :: jk
-
-      WRITE(numsed,*)' '
-      WRITE(numsed,*)'======== Write summary of initial state   ============'
-      WRITE(numsed,*)' '
-      WRITE(numsed,*)' '
-      WRITE(numsed,*)'-------------------------------------------------------------------'
-      WRITE(numsed,*)' Initial Conditions '
-      WRITE(numsed,*)'-------------------------------------------------------------------'
-      WRITE(numsed,*)'dzm = dzkbot minimum to calculate ', 0.
-      WRITE(numsed,*)'Local zone : jpi, jpj : ',jpi, jpj
-      WRITE(numsed,*)'jpoce = ',jpoce,' nbtot pts = ',jpij,' nb earth pts = ',jpij - jpoce
-      WRITE(numsed,*)'sublayer thickness dz(1) [cm] : ', dz(1)
-      WRITE(numsed,*)'Coeff diff for k=1 (cm2/s) : ',diff(1)
-      WRITE(numsed,*)' nb solid comp : ',jpsol
-      WRITE(numsed,*)'(1=opal,2=clay,3=POC,4=CaCO3)'
-      WRITE(numsed,*)'weight mol 1,2,3,4'
-      WRITE(numsed,'(4(F0.2,3X))')mol_wgt(jsopal),mol_wgt(jsclay),mol_wgt(jspoc),mol_wgt(jscal)
-      WRITE(numsed,*)'nb dissolved comp',jpwat
-      WRITE(numsed,*)'(1=silicic acid,2="dissolved" clay,3=O2,4=DIC,5=Nitrate,&
-         &6=Phosphates,7=Alk))'
-      WRITE(numsed,*)'Psat (umol/l) for silicic Acid and "dissolved" clay'
-      WRITE(numsed,'(2(F0.2,3X))') sat_sil * 1e+6,  sat_clay * 1e+6
-      WRITE(numsed,*)'reaction rate rc for Op/si,Clay,POC/O2,caco3, POC/No3 (an-1)'
-      WRITE(numsed,'(5(F0.2,3X))') reac_sil * ryear, reac_clay * ryear, reac_poc * ryear, &
-                                   reac_cal * ryear, reac_no3 * ryear
-      WRITE(numsed,*)'redfield coef C,O,N P Dit '
-      WRITE(numsed,'(5(F0.2,3X))')1./spo4r,so2ut/spo4r,srno3/spo4r,spo4r/spo4r,srDnit/spo4r
-      WRITE(numsed,*)'threshold for stating denitrification [mol/l]'
-      WRITE(numsed,'(1PE8.2)') sthrO2
-      WRITE(numsed,*)'-------------------------------------------------------------------'
-      WRITE(numsed,*)'Min-Max-Mean'
-      WRITE(numsed,*)'For each variable : min, max, moy value observed on selected local zone'
-      WRITE(numsed,*)'-------------------------------------------------------------------'
-      WRITE(numsed,*)'thickness of the last wet layer dzkbot [m]'
-      WRITE(numsed,'(3(F0.2,3X))') MINVAL(dzkbot(1:jpoce))/100.,MAXVAL(dzkbot(1:jpoce))/100.,&
-         &SUM(dzkbot(1:jpoce))/jpoce/100.
-      WRITE(numsed,*)'temp [°C]'
-      WRITE(numsed,'(3(F0.2,3X))') MINVAL(temp(1:jpoce)),MAXVAL(temp(1:jpoce)),&
-         &                         SUM(temp(1:jpoce))/jpoce
-      WRITE(numsed,*)'salt o/oo'
-      WRITE(numsed,'(3(F0.2,3X))')MINVAL(salt(1:jpoce)),MAXVAL(salt(1:jpoce)),&
-         &                        SUM(salt(1:jpoce))/jpoce
-#if defined key_sed_off
-      WRITE(numsed,*)'pressure [bar] (depth in m is about 10*pressure)'
-      WRITE(numsed,'(3(F0.2,3X))') MINVAL(press(1:jpoce)),MAXVAL(press(1:jpoce)),&
-         &                         SUM(press(1:jpoce))/jpoce
-#endif
-      WRITE(numsed,*)'density of Sea Water'
-      WRITE(numsed,'(3(F0.2,3X))') MINVAL(densSW(1:jpoce)), MAXVAL(densSW(1:jpoce)),&
-         &                         SUM(densSW(1:jpoce))/jpoce
-      WRITE(numsed,*)''
-      WRITE(numsed,*)'     Dissolved Components '
-      WRITE(numsed,*)'     ====================='
-      WRITE(numsed,*)'[Si(OH)4] dissolved (1)(k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwsil))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwsil))*1.e+6,&
-         &                         SUM(pwcp(1:jpoce,1,jwsil))*1.e+6/jpoce,&
-         &                         MINVAL(pwcp(1:jpoce,1,jwsil)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[O2]    dissolved (3) (k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwoxy))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwoxy))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwoxy))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwoxy)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[DIC]    dissolved (4) (k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwdic))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwdic))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwdic))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwdic)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[NO3]    dissolved (5) (k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwno3))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwno3))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwno3))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwno3)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[PO4]    dissolved (6) (k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwpo4))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwpo4))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwpo4))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwpo4)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[Alk]    dissolved (7) (k=1)(µequi)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwalk))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwalk))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwalk))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwalk)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)'[DIC13]  dissolved (8) (k=1)(µmol/l)(and min value in mol/kg  of solution)'
-      WRITE(numsed,'(4(F0.3,2X))') MINVAL(pwcp(1:jpoce,1,jwc13))*1.e+6,MAXVAL(pwcp(1:jpoce,1,jwc13))*1.e+6,&
-         &SUM(pwcp(1:jpoce,1,jwc13))*1.e+6/jpoce,&
-         &MINVAL(pwcp(1:jpoce,1,jwc13)*1.e+6/densSW(1:jpoce))
-      WRITE(numsed,*)''
-      WRITE(numsed,*)'     Solid Components '
-      WRITE(numsed,*)'     ====================='
-      WRITE(numsed,*)'nmole of Opale rained per dt'
-      WRITE(numsed,'(3(1PE9.3,2X))') MINVAL(rainrm(1:jpoce,jsopal))*dtsed,MAXVAL(rainrm(1:jpoce,jsopal))*dtsed,&
-         &SUM(rainrm(1:jpoce,1))*dtsed/jpoce
-      WRITE(numsed,*)'nmole of Clay rained per dt'
-      WRITE(numsed,'(3(1PE9.3,2X))') MINVAL(rainrm(1:jpoce,jsclay))*dtsed,MAXVAL(rainrm(1:jpoce,jsclay))*dtsed,&
-         &SUM(rainrm(1:jpoce,jsclay))*dtsed/jpoce
-      WRITE(numsed,*)'nmole of POC rained per dt'
-      WRITE(numsed,'(3(1PE9.3,2X))') MINVAL(rainrm(1:jpoce,jspoc))*dtsed,MAXVAL(rainrm(1:jpoce,jspoc))*dtsed,&
-         &SUM(rainrm(1:jpoce,jspoc))*dtsed/jpoce
-      WRITE(numsed,*)'nmole of CaCO3 rained per dt'
-      WRITE(numsed,'(3(1PE9.3,2X))') MINVAL(rainrm(1:jpoce,jscal))*dtsed,MAXVAL(rainrm(1:jpoce,jscal))*dtsed,&
-         &SUM(rainrm(1:jpoce,jscal))*dtsed/jpoce
-      WRITE(numsed,*)' '
-      WRITE(numsed,*)'Weight frac of opal rained (%) '
-      WRITE(numsed,'(3(F0.3,7X))') MINVAL(rainrg(1:jpoce,jsopal)/raintg(1:jpoce))*100.,&
-         &MAXVAL(rainrg(1:jpoce,jsopal)/raintg(1:jpoce))*100.,&
-         & SUM(rainrg(1:jpoce,jsopal)/raintg(1:jpoce))*100./jpoce
-      WRITE(numsed,*)'Weight frac of clay  rained (%) '
-      WRITE(numsed,'(3(F0.3,7X))') MINVAL(rainrg(1:jpoce,jsclay)/raintg(1:jpoce))*100.,&
-         &MAXVAL(rainrg(1:jpoce,jsclay)/raintg(1:jpoce))*100.,&
-         &SUM(rainrg(1:jpoce,jsclay)/raintg(1:jpoce))*100./jpoce
-      WRITE(numsed,*)'Weight frac of POC rained (%)'
-      WRITE(numsed,'(3(F0.3,7X))') MINVAL(rainrg(1:jpoce,jspoc)/raintg(1:jpoce))*100.,&
-         &MAXVAL(rainrg(1:jpoce,jspoc)/raintg(1:jpoce))*100.,&
-         &SUM(rainrg(1:jpoce,jspoc)/raintg(1:jpoce))*100./jpoce
-      WRITE(numsed,*)'Weight frac of CaCO3  rained (%)'
-      WRITE(numsed,'(3(F0.3,7X))') MINVAL(rainrg(1:jpoce,jscal)/raintg(1:jpoce))*100.,&
-         &MAXVAL(rainrg(1:jpoce,jscal)/raintg(1:jpoce))*100.,&
-         &SUM(rainrg(1:jpoce,jscal)/raintg(1:jpoce))*100./jpoce
-      WRITE(numsed,*)''
-      WRITE(numsed,*)' Thickness of sediment layer added by particule rain, dzdep cm '
-      WRITE(numsed,*)' =============================================================='
-      WRITE(numsed,'(3(F0.5,2X))') MINVAL(dzdep(1:jpoce)),MAXVAL(dzdep(1:jpoce)),SUM(dzdep(1:jpoce))/jpoce
-      WRITE(numsed,*)''
-      WRITE(numsed,*)' chemical constants K1,pK1,K2,pK2,Kw,pKw and Kb pKb (min max) [mol/kgsol] or [mol/kgsol]2 '
-      WRITE(numsed,*)' ========================================================================================='
-      WRITE(numsed,'(4(1PE10.3,2X))')MINVAL(ak1s(1:jpoce)),MAXVAL(ak1s(1:jpoce)),-LOG10(MINVAL(ak1s(1:jpoce))),&
-         &-LOG10(MAXVAL(ak1s(1:jpoce)))
-      WRITE(numsed,'(4(1PE10.3,2X))')MINVAL(ak2s(1:jpoce)),MAXVAL(ak2s(1:jpoce)),-LOG10(MINVAL(ak2s(1:jpoce))),&
-         &-LOG10(MAXVAL(ak2s(1:jpoce)))
-      WRITE(numsed,'(4(1PE10.3,2X))')MINVAL(akws(1:jpoce)),MAXVAL(akws(1:jpoce)),-LOG10(MINVAL(akws(1:jpoce))),&
-         &-LOG10(MAXVAL(akws(1:jpoce)))
-      WRITE(numsed,'(4(1PE10.3,2X))')MINVAL(akbs(1:jpoce)),MAXVAL(akbs(1:jpoce)),-LOG10(MINVAL(akbs(1:jpoce))),&
-         &-LOG10(MAXVAL(akbs(1:jpoce)))
-      WRITE(numsed,*)'and boron'
-      WRITE(numsed,'(2(1PE10.3,2X))')MINVAL(borats(1:jpoce)),MAXVAL(borats(1:jpoce))
-      WRITE(numsed,*)''
-      WRITE(numsed,*)' Compo of initial sediment for point jpoce'
-      WRITE(numsed,*)' ========================================='
-      WRITE(numsed,*)'solcp(1),   solcp(2),   solcp(3),   solcp(4),   hipor,      pH,         co3por'
-      DO jk = 1,jpksed
-         WRITE(numsed,'(7(1PE10.3,2X))')solcp(jpoce,jk,jsopal),solcp(jpoce,jk,jsclay),solcp(jpoce,jk,jspoc),solcp(jpoce,jk,jscal),&
-            &       hipor(jpoce,jk),-LOG10(hipor(jpoce,jk)/densSW(jpoce)),co3por(jpoce,jk)
-      ENDDO
-      WRITE(numsed,'(A82)')'pwcp(1),    pwcp(2),    pwcp(3),    pwcp(4),    pwcp(5),    pwcp(6),    pwcp(7)'
-      DO jk = 1, jpksed
-         WRITE(numsed,'(7(1PE10.3,2X))')pwcp(jpoce,jk,jwsil),pwcp(jpoce,jk,jwoxy),pwcp(jpoce,jk,jwdic),&
-            & pwcp(jpoce,jk,jwno3),pwcp(jpoce,jk,jwpo4),pwcp(jpoce,jk,jwalk),pwcp(jpoce,jk,jwc13)
-      ENDDO
-      WRITE(numsed,*) ' '
-      WRITE(numsed,*) ' End Of Initialization '
-      WRITE(numsed,*) ' '
-!
-   END SUBROUTINE sed_init_wri
-#else
-   !!----------------------------------------------------------------------
-   !!   Dummy module :                      NO Sediment model
-   !!----------------------------------------------------------------------
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_ini              ! Empty routine
-   END SUBROUTINE sed_ini
-#endif
-
-
 END MODULE sedini
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinitrc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinitrc.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinitrc.F90	(revision 10321)
@@ -0,0 +1,192 @@
+MODULE sedinitrc
+   !!======================================================================
+   !!              ***  MODULE  sedinitrc  ***
+   !! Sediment : define sediment variables
+   !!=====================================================================
+
+   !!----------------------------------------------------------------------
+   !!   sed_init    : initialization, namelist read, and parameters control
+   !!----------------------------------------------------------------------
+   !! * Modules used
+   USE sed     ! sediment global variable
+   USE sed_oce
+   USE sedini
+   USE seddta
+   USE sedrst
+   USE sedco3
+   USE sedchem
+   USE sedarr
+   USE lib_mpp         ! distribued memory computing library
+
+
+   IMPLICIT NONE
+   PRIVATE
+
+   REAL(wp)    ::  &
+      ryear = 365. * 24. * 3600. !:  1 year converted in second
+
+   !! *  Routine accessibility
+   PUBLIC sed_initrc          ! routine called by opa.F90
+
+   !! $Id$
+CONTAINS
+
+
+   SUBROUTINE sed_initrc
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_init  ***
+      !!
+      !! ** Purpose :  Initialization of sediment module
+      !!               - Reading namelist
+      !!               - Read the deepest water layer thickness
+      !!                 ( using as mask ) in Netcdf file
+      !!               - Convert unity if necessary
+      !!               - sets initial sediment composition
+      !!                 ( only clay or reading restart file )
+      !!               - sets sediment grid, porosity and others constants
+      !!
+      !!   History :
+      !!        !  04-10  (N. Emprin, M. Gehlen )  Original code
+      !!        !  06-07  (C. Ethe)  Re-organization
+      !!----------------------------------------------------------------------
+      INTEGER :: ji, jj, ikt
+      !!----------------------------------------------------------------------
+
+
+      ! Initialize the sediment tracers concentrations
+      !------------------------------------------------
+
+      IF(lwp) WRITE(numsed,*) ' sed_initrc : Initialization of sediment concentration '
+      IF(lwp) WRITE(numsed,*) ' '
+
+      ! Determination of sediments number of points and allocate global variables
+
+      ! sets initial sediment composition
+      ! ( only clay or reading restart file )
+      !---------------------------------------
+      CALL sed_init_data
+
+
+      CALL sed_init_wri
+
+
+   END SUBROUTINE sed_initrc
+
+
+   SUBROUTINE sed_init_data
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_init_data  ***
+      !!
+      !! ** Purpose :  Initialization of sediment module
+      !!               - sets initial sediment composition
+      !!                 ( only clay or reading restart file )
+      !!
+      !!   History :
+      !!        !  06-07  (C. Ethe)  original
+      !!----------------------------------------------------------------------
+ 
+      ! local variables
+      INTEGER :: &
+         ji, jk, zhipor
+
+      !--------------------------------------------------------------------
+ 
+
+      IF( .NOT. ln_rst_sed ) THEN
+
+         IF (lwp) WRITE(numsed,*) ' Initilization of default values of sediment components'
+
+         ! default values for initial pore water concentrations [mol/l]
+         pwcp(:,:,:) = 0.
+         ! default value for initial solid component (fraction of dry weight dim=[0])
+         ! clay
+         solcp(:,:,:) = 0.
+         solcp(:,2:jpksed,jsclay) = 1.0 * 0.965
+         solcp(:,2:jpksed,jsfeo)  = 1.0 * 0.035
+
+         ! Initialization of [h+] and [co3--]
+
+         zhipor = 8.0
+         ! Initialization of [h+] in mol/kg
+         DO jk = 1, jpksed
+            DO ji = 1, jpoce
+               hipor (ji,jk) = 10.**( -1. * zhipor )
+            ENDDO
+         ENDDO
+
+         co3por(:,:) = 1E-6
+
+      ELSE   
+  
+         IF (lwp) WRITE(numsed,*) ' Initilization of Sediment components from restart'
+
+         CALL sed_rst_cal( nitsed000, 'READ' )
+         CALL sed_rst_read
+
+      ENDIF
+
+
+      ! Load initial Pisces Data for bot. wat. Chem and fluxes
+      CALL sed_dta ( nitsed000 ) 
+
+      ! Initialization of chemical constants
+      CALL sed_chem ( nitsed000 )
+
+      ! Stores initial sediment data for mass balance calculation
+      pwcp0 (1:jpoce,1:jpksed,1:jpwat ) = pwcp (1:jpoce,1:jpksed,1:jpwat ) 
+      solcp0(1:jpoce,1:jpksed,1:jpsol ) = solcp(1:jpoce,1:jpksed,1:jpsol) 
+
+      ! Conversion of [h+] in mol/Kg to get it in mol/l ( multiplication by density)
+      DO jk = 1, jpksed
+         hipor(1:jpoce,jk) = hipor(1:jpoce,jk) * densSW(1:jpoce)
+      ENDDO
+
+
+      ! In default case - no restart - sedco3 is run to initiate [h+] and [co32-]
+      ! Otherwise initiate values of pH and co3 read in restart
+      IF( .NOT. ln_rst_sed ) THEN
+         ! sedco3 is run to initiate[h+] [co32-] in mol/l of solution
+         CALL sed_co3 ( nitsed000 )
+
+      ENDIF
+            
+   END SUBROUTINE sed_init_data
+
+   SUBROUTINE sed_init_wri
+
+      INTEGER :: jk
+
+      IF (lwp) THEN
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)'======== Write summary of sediment char.  ============'
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)'-------------------------------------------------------------------'
+         WRITE(numsed,*)' Initial Conditions '
+         WRITE(numsed,*)'-------------------------------------------------------------------'
+         WRITE(numsed,*)'dzm = dzkbot minimum to calculate ', 0.
+         WRITE(numsed,*)'Local zone : jpi, jpj, jpksed : ',jpi, jpj, jpksed
+         WRITE(numsed,*)'jpoce = ',jpoce,' nbtot pts = ',jpij,' nb earth pts = ',jpij - jpoce
+         WRITE(numsed,*)'sublayer thickness dz(1) [cm] : ', dz(1)
+         WRITE(numsed,*)'Vertical domain of the sediment'
+         WRITE(numsed,*)'-------------------------------'
+         WRITE(numsed,*)' Indice, profsed, dz'
+         DO jk = 2, jpksed
+            WRITE(numsed,*) jk,profsed(jk),dz(jk) 
+         END DO
+         WRITE(numsed,*)' nb solid comp : ',jpsol
+         WRITE(numsed,*)'(1=opal,2=clay,3=POC,4=CaCO3), 5=POS, 6=POR, 7=FEO, 8=FeS'
+         WRITE(numsed,*)'weight mol 1,2,3,4,5,6,7'
+         WRITE(numsed,'(8(F0.2,3X))')mol_wgt(jsopal),mol_wgt(jsclay),mol_wgt(jspoc),mol_wgt(jscal),mol_wgt(jspos),mol_wgt(jspor),mol_wgt(jsfeo),mol_wgt(jsfes)
+         WRITE(numsed,*)'nb dissolved comp',jpwat
+         WRITE(numsed,*)'1=silicic acid,,2=O2,3=DIC,4=NO3,5=PO4,6=Alk,7=NH4,8=ODU'
+         WRITE(numsed,*)'redfield coef C,O,N P Dit '
+         WRITE(numsed,'(5(F0.2,3X))')1./spo4r,so2ut/spo4r,srno3/spo4r,spo4r/spo4r,srDnit/spo4r
+         WRITE(numsed,*) ' '
+         WRITE(numsed,*) ' End Of Initialization '
+         WRITE(numsed,*) ' '
+      ENDIF
+!
+   END SUBROUTINE sed_init_wri
+
+END MODULE sedinitrc
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinorg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinorg.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedinorg.F90	(revision 10321)
@@ -0,0 +1,300 @@
+MODULE sedinorg
+   !!======================================================================
+   !!              ***  MODULE  sedinorg  ***
+   !!    Sediment : dissolution and reaction in pore water of 
+   !!               inorganic species
+   !!=====================================================================
+   !! * Modules used
+   USE sed     ! sediment global variable
+   USE sed_oce
+   USE sedmat  ! linear system of equations
+   USE sedco3  ! carbonate ion and proton concentration 
+   USE sedini
+   USE seddsr
+   USE lib_mpp         ! distribued memory computing library
+   USE lib_fortran
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC sed_inorg
+
+   !! $Id$
+CONTAINS
+   
+   SUBROUTINE sed_inorg( kt ) 
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_inorg  ***
+      !! 
+      !!  ** Purpose :  computes pore water dissolution and reaction
+      !!
+      !!  ** Methode :  implicit simultaneous computation of undersaturation
+      !!               resulting from diffusive pore water transport and chemical
+      !!               pore water reactions. Solid material is consumed according
+      !!               to redissolution and remineralisation
+      !!
+      !!  ** Remarks :
+      !!              - undersaturation : deviation from saturation concentration
+      !!              - reaction rate   : sink of undersaturation from dissolution
+      !!                                 of solid material 
+      !!
+      !!   History :
+      !!        !  98-08 (E. Maier-Reimer, Christoph Heinze )  Original code
+      !!        !  04-10 (N. Emprin, M. Gehlen ) f90
+      !!        !  06-04 (C. Ethe)  Re-organization
+      !!        !  19-08 (O. Aumont) Debugging and improvement of the model
+      !!----------------------------------------------------------------------
+      !! Arguments
+      INTEGER, INTENT(in) ::   kt       ! number of iteration
+      ! --- local variables
+      INTEGER :: ji, jk, js, jw         ! dummy looop indices
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zrearat1, zrearat2    ! reaction rate in pore water
+      REAL(wp), DIMENSION(jpoce,jpksed) :: zundsat    ! undersaturation ; indice jpwatp1 is for calcite   
+      REAL(wp), DIMENSION(jpoce) :: zco3eq
+      REAL(wp), DIMENSION(jpoce,jpksed,jpsol) :: zvolc    ! temp. variables
+      REAL(wp), DIMENSION(jpoce) :: zsieq
+      REAL(wp)  ::  zsolid1, zvolw, zreasat
+      REAL(wp)  ::  zsatur, zsatur2, znusil, zsolcpcl, zsolcpsi
+      !!
+      !!----------------------------------------------------------------------
+
+      IF( ln_timing )  CALL timing_start('sed_inorg')
+!
+      IF( kt == nitsed000 ) THEN
+         IF (lwp) THEN
+            WRITE(numsed,*) ' sed_inorg : Dissolution reaction '
+            WRITE(numsed,*) ' '
+         ENDIF
+!         ! 
+      ENDIF
+
+     ! Initializations
+     !----------------------
+      
+      zrearat1(:,:) = 0.    ;   zundsat(:,:)  = 0. 
+      zrearat2(:,:) = 0.    ;   zrearat2(:,:) = 0.
+      zco3eq(:)     = rtrn
+      zvolc(:,:,:)  = 0.
+
+      ! -----------------------------------------------
+      ! Computation of Si solubility
+      ! Param of Ridgwell et al. 2002
+      ! -----------------------------------------------
+
+      DO ji = 1, jpoce
+         zsolcpcl = 0.0
+         zsolcpsi = 0.0
+         DO jk = 1, jpksed
+            zsolcpsi = zsolcpsi + solcp(ji,jk,jsopal) * dz(jk)
+            zsolcpcl = zsolcpcl + solcp(ji,jk,jsclay) * dz(jk)
+         END DO
+         zsieq(ji) = sieqs(ji) * MAX(0.25, 1.0 - (0.045 * zsolcpcl / zsolcpsi )**0.58 )
+         zsieq(ji) = MAX( rtrn, sieqs(ji) )
+      END DO
+
+      DO js = 1, jpsol
+         DO jk = 1, jpksed
+            DO ji = 1, jpoce    
+               zvolc(ji,jk,js) = ( vols3d(ji,jk) * dens_mol_wgt(js) ) /  &
+                  &              ( volw3d(ji,jk) * 1.e-3  )     
+            ENDDO
+         ENDDO
+      ENDDO
+
+      !----------------------------------------------------------
+      ! 5.  Beginning of  Pore Water diffusion and solid reaction
+      !---------------------------------------------------------
+      
+      !-----------------------------------------------------------------------------
+      ! For jk=2,jpksed, and for couple 
+      !  1 : jwsil/jsopal  ( SI/Opal )
+      !  2 : jsclay/jsclay ( clay/clay ) 
+      !  3 : jwoxy/jspoc   ( O2/POC )
+      !  reaction rate is a function of solid=concentration in solid reactif in [mol/l] 
+      !  and undersaturation in [mol/l].
+      !  Solid weight fractions should be in ie [mol/l])
+      !  second member and solution are in zundsat variable
+      !-------------------------------------------------------------------------
+
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            ! For Silicic Acid and clay
+            zundsat(ji,jk) = zsieq(ji) - pwcp(ji,jk,jwsil)
+         ENDDO
+      ENDDO
+      
+      ! Definition of reaction rates [rearat]=sans dim 
+      ! For jk=1 no reaction (pure water without solid) for each solid compo
+      DO ji = 1, jpoce
+         zrearat1(ji,:) = 0.
+         zrearat2(ji,:) = 0.
+      ENDDO
+
+      ! left hand side of coefficient matrix
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zsolid1 = zvolc(ji,jk,jsopal) * solcp(ji,jk,jsopal)
+            zsatur = MAX(0., zundsat(ji,jk) / zsieq(ji) )
+            zsatur2 = (1.0 + temp(ji) / 400.0 )**37
+            znusil = ( 0.225 * ( 1.0 + temp(ji) / 15.) + 0.775 * zsatur2 * zsatur**2.25 ) / zsieq(ji)
+            zrearat1(ji,jk)  = ( reac_sil * znusil * dtsed * zsolid1 ) / &
+               &                ( 1. + reac_sil * znusil * dtsed * zundsat(ji,jk) )
+         ENDDO
+      ENDDO
+
+      CALL sed_mat( jwsil, jpoce, jpksed, zrearat1, zrearat2, zundsat, dtsed )
+
+      ! New solid concentration values (jk=2 to jksed) for each couple 
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zundsat(ji,jk) / ( zvolc(ji,jk,jsopal) )
+            solcp(ji,jk,jsopal) = solcp(ji,jk,jsopal) - zreasat
+         ENDDO
+      ENDDO
+
+      ! New pore water concentrations    
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            ! Acid Silicic 
+            pwcp(ji,jk,jwsil)  = zsieq(ji) - zundsat(ji,jk)
+         ENDDO
+      ENDDO
+
+      !---------------------------------------------------------------
+      ! Performs CaCO3 particle deposition and redissolution (indice 9)
+      !--------------------------------------------------------------
+
+      ! computes co3por from the updated pwcp concentrations (note [co3por] = mol/l)
+
+      CALL sed_co3( kt )
+
+      ! *densSW(l)**2 converts aksps [mol2/kg sol2] into [mol2/l2] to get [undsat] in [mol/l]
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            zco3eq(ji)     = aksps(ji) * densSW(ji) * densSW(ji) / ( calcon2(ji) + rtrn )
+            zco3eq(ji)     = MAX( rtrn, zco3eq(ji) ) 
+            zundsat(ji,jk) = MAX(0., zco3eq(ji) - co3por(ji,jk) )
+         ENDDO
+      ENDDO
+
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zsolid1 = zvolc(ji,jk,jscal) * solcp(ji,jk,jscal)
+            zrearat1(ji,jk) = ( reac_cal * dtsed * zsolid1 / zco3eq(ji) ) / &
+                  &               ( 1. + reac_cal * dtsed * zundsat(ji,jk) / zco3eq(ji) )
+         END DO
+      END DO
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwdic, jpoce, jpksed, zrearat1, zrearat2, zundsat, dtsed )
+
+      ! New solid concentration values (jk=2 to jksed) for cacO3
+      DO jk = 2, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zundsat(ji,jk) / zvolc(ji,jk,jscal)
+            solcp(ji,jk,jscal) = solcp(ji,jk,jscal) - zreasat
+         ENDDO
+      ENDDO
+
+      ! New dissolved concentrations
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            zreasat = zrearat1(ji,jk) * zundsat(ji,jk)    
+            ! For DIC
+            pwcp(ji,jk,jwdic)  = pwcp(ji,jk,jwdic) + zreasat
+            ! For alkalinity
+            pwcp(ji,jk,jwalk)  = pwcp(ji,jk,jwalk) + 2.0 * zreasat 
+         ENDDO
+      ENDDO
+
+      !-------------------------------------------------
+      ! Beginning DIC, Alkalinity 
+      !-------------------------------------------------
+      
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce      
+            zundsat(ji,jk)   = pwcp(ji,jk,jwdic)
+            zrearat1(ji,jk)  = 0.
+         ENDDO
+      ENDDO
+
+      ! solves tridiagonal system
+      CALL sed_mat( jwdic, jpoce, jpksed, zrearat1, zrearat2, zundsat, dtsed )
+
+     ! New dissolved concentrations      
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce                      
+            pwcp(ji,jk,jwdic) = zundsat(ji,jk)
+         ENDDO
+      ENDDO            
+
+      !-------------------------------------------------
+      ! Beginning DIC, Alkalinity 
+      !-------------------------------------------------
+
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            zundsat(ji,jk) = pwcp(ji,jk,jwalk)
+            zrearat1(ji,jk) = 0.
+         ENDDO
+      ENDDO
+!
+!      ! solves tridiagonal system
+      CALL sed_mat( jwalk, jpoce, jpksed, zrearat1, zrearat2, zundsat, dtsed )
+!
+!      ! New dissolved concentrations      
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            pwcp(ji,jk,jwalk) = zundsat(ji,jk)
+         ENDDO
+      ENDDO
+      
+      !----------------------------------
+      !   Back to initial geometry
+      !-----------------------------
+      
+      !---------------------------------------------------------------------
+      !   1/ Compensation for ajustement of the bottom water concentrations
+      !      (see note n° 1 about *por(2))
+      !--------------------------------------------------------------------
+      DO jw = 1, jpwat
+         DO ji = 1, jpoce
+            pwcp(ji,1,jw) = pwcp(ji,1,jw) + &
+               &            pwcp(ji,2,jw) * dzdep(ji) * por(2) / dzkbot(ji)
+         END DO
+      ENDDO
+      
+      !-----------------------------------------------------------------------
+      !    2/ Det of new rainrg taking account of the new weight fraction obtained 
+      !      in dz3d(2) after diffusion/reaction (react/diffu are also in dzdep!)
+      !      This new rain (rgntg rm) will be used in advection/burial routine
+      !------------------------------------------------------------------------
+      DO js = 1, jpsol
+         DO ji = 1, jpoce
+            rainrg(ji,js) = raintg(ji) * solcp(ji,2,js)
+            rainrm(ji,js) = rainrg(ji,js) / mol_wgt(js)
+         END DO
+      ENDDO
+
+      !  New raintg
+      raintg(:) = 0.
+      DO js = 1, jpsol
+         DO ji = 1, jpoce
+            raintg(ji) = raintg(ji) + rainrg(ji,js)
+         END DO
+      ENDDO
+      
+      !--------------------------------
+      !    3/ back to initial geometry
+      !--------------------------------
+      DO ji = 1, jpoce
+         dz3d  (ji,2) = dz(2)
+         volw3d(ji,2) = dz3d(ji,2) * por(2)
+         vols3d(ji,2) = dz3d(ji,2) * por1(2)
+      ENDDO
+
+      IF( ln_timing )  CALL timing_stop('sed_inorg')
+!      
+   END SUBROUTINE sed_inorg
+
+END MODULE sedinorg
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmat.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmat.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmat.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedmat
-#if defined key_sed
    !!======================================================================
    !!              ***  MODULE  sedmat  ***
@@ -9,4 +8,6 @@
 
    USE sed     ! sediment global variable
+   USE lib_mpp         ! distribued memory computing library
+
 
    IMPLICIT NONE
@@ -25,5 +26,5 @@
  CONTAINS
 
-    SUBROUTINE sed_mat_dsr( nvar, ndim, nlev, preac, psol )
+    SUBROUTINE sed_mat_dsr( nvar, ndim, nlev, preac, psms, psol, dtsed_in )
        !!---------------------------------------------------------------------
        !!                  ***  ROUTINE sed_mat_dsr  ***
@@ -48,10 +49,12 @@
        !!----------------------------------------------------------------------
        !! * Arguments
-       INTEGER , INTENT(in) ::  nvar  ! number of variables
+       INTEGER , INTENT(in) ::  nvar  ! number of variable
        INTEGER , INTENT(in) ::  ndim  ! number of points
        INTEGER , INTENT(in) ::  nlev  ! number of sediment levels
 
-       REAL(wp), DIMENSION(ndim,nlev,nvar), INTENT(in   ) :: preac  ! reaction rates
-       REAL(wp), DIMENSION(ndim,nlev,nvar), INTENT(inout) :: psol   ! solution ( undersaturation values )
+       REAL(wp), DIMENSION(ndim,nlev), INTENT(in   ) :: preac  ! reaction rates
+       REAL(wp), DIMENSION(ndim,nlev), INTENT(in   ) :: psms  ! reaction rates
+       REAL(wp), DIMENSION(ndim,nlev), INTENT(inout) :: psol   ! solution ( undersaturation values )
+       REAL(wp), INTENT(in) ::  dtsed_in
  
        !---Local declarations
@@ -67,4 +70,5 @@
        !----------------------------------------------------------------------
 
+       IF( ln_timing )  CALL timing_start('sed_mat_dsr')
 
        ! Computation left hand side of linear system of 
@@ -73,10 +77,11 @@
 
 
+       jn = nvar
        ! first sediment level          
        DO ji = 1, ndim
-          aplus  = ( ( volw3d(ji,1) / dz3d(ji,1) ) + &
-                     ( volw3d(ji,2) / dz3d(ji,2) ) ) / 2.
+          aplus  = ( ( volw3d(ji,1) / ( dz3d(ji,1) ) ) + &
+                        ( volw3d(ji,2) / ( dz3d(ji,2) ) ) ) / 2.
           dxplus = ( dz3d(ji,1) + dz3d(ji,2) ) / 2.
-          rplus  = ( dtsed / volw3d(ji,1) ) * diff(1) * aplus / dxplus 
+          rplus  = ( dtsed_in / ( volw3d(ji,1) ) ) * diff(ji,1,jn) * aplus / dxplus 
 
           za(ji,1) = 0.
@@ -87,15 +92,15 @@
        DO jk = 2, nlev - 1
           DO ji = 1, ndim
-             aminus  = ( ( volw3d(ji,jk-1) / dz3d(ji,jk-1) ) + &
-                &        ( volw3d(ji,jk  ) / dz3d(ji,jk  ) ) ) / 2.
+             aminus  = ( ( volw3d(ji,jk-1) / ( dz3d(ji,jk-1) ) ) + &
+             &        ( volw3d(ji,jk  ) / ( dz3d(ji,jk  ) ) ) ) / 2.
              dxminus = ( dz3d(ji,jk-1) + dz3d(ji,jk) ) / 2.
 
-             aplus   = ( ( volw3d(ji,jk  ) / dz3d(ji,jk  ) ) + &
-                &        ( volw3d(ji,jk+1) / dz3d(ji,jk+1) ) ) / 2.
+             aplus   = ( ( volw3d(ji,jk  ) / ( dz3d(ji,jk  ) ) ) + &
+             &        ( volw3d(ji,jk+1) / ( dz3d(ji,jk+1) ) ) ) / 2.
              dxplus  = ( dz3d(ji,jk) + dz3d(ji,jk+1) ) / 2
-             !
-             rminus  = ( dtsed / volw3d(ji,jk) ) * diff(jk-1) * aminus / dxminus
-             rplus   = ( dtsed / volw3d(ji,jk) ) * diff(jk)   * aplus / dxplus
-             !     
+                !
+             rminus  = ( dtsed_in / volw3d(ji,jk) ) * diff(ji,jk-1,jn) * aminus / dxminus
+             rplus   = ( dtsed_in / volw3d(ji,jk) ) * diff(ji,jk,jn)   * aplus / dxplus
+                !     
              za(ji,jk) = -rminus
              zb(ji,jk) = 1. + rminus + rplus 
@@ -105,8 +110,8 @@
 
        DO ji = 1, ndim
-          aminus  = ( ( volw3d(ji,nlev-1) / dz3d(ji,nlev-1) ) + &
-             &        ( volw3d(ji,nlev)  / dz3d(ji,nlev) ) ) / 2.
+          aminus  = ( ( volw3d(ji,nlev-1) / dz3d(ji,nlev-1)  ) + &
+          &        ( volw3d(ji,nlev)  / dz3d(ji,nlev) ) ) / 2.
           dxminus = ( dz3d(ji,nlev-1) + dz3d(ji,nlev) ) / 2.
-          rminus  = ( dtsed / volw3d(ji,nlev) ) * diff(nlev-1) * aminus / dxminus
+          rminus  = ( dtsed_in / volw3d(ji,nlev) ) * diff(ji,nlev-1,jn) * aminus / dxminus
           !
           za(ji,nlev) = -rminus
@@ -119,31 +124,30 @@
        ! -----------------------------------------------
 
-       DO jn = 1, nvar
-
-          zr  (:,:)    = psol(:,:,jn)
-          zbet(:  )    = zb(:,1) + preac(:,1,jn)
-          psol(:,1,jn) = zr(:,1) / zbet(:)
+       zr  (:,:) = psol(:,:) + psms(:,:)
+       zb  (:,:) = zb(:,:) + preac(:,:)
+       zbet(:  ) = zb(:,1)
+       psol(:,1) = zr(:,1) / zbet(:)
+
           ! 
-          DO jk = 2, nlev
-             DO ji = 1, ndim
-                zgamm(ji,jk)   =  zc(ji,jk-1) / zbet(ji)
-                zbet(ji)       = ( zb(ji,jk) + preac(ji,jk,jn) ) - za(ji,jk) * zgamm(ji,jk)
-                psol(ji,jk,jn) = ( zr(ji,jk) - za(ji,jk) * psol(ji,jk-1,jn) ) / zbet(ji)
-             END DO
-          ENDDO
+       DO jk = 2, nlev
+          DO ji = 1, ndim
+             zgamm(ji,jk) =  zc(ji,jk-1) / zbet(ji)
+             zbet(ji)     =  zb(ji,jk) - za(ji,jk) * zgamm(ji,jk)
+             psol(ji,jk)  = ( zr(ji,jk) - za(ji,jk) * psol(ji,jk-1) ) / zbet(ji)
+          END DO
+       ENDDO
           ! 
-          DO jk = nlev - 1, 1, -1
-             DO ji = 1,ndim
-                psol(ji,jk,jn) = psol(ji,jk,jn) - zgamm(ji,jk+1) * psol(ji,jk+1,jn)
-             END DO
-          ENDDO
-
+       DO jk = nlev - 1, 1, -1
+          DO ji = 1,ndim
+             psol(ji,jk) = psol(ji,jk) - zgamm(ji,jk+1) * psol(ji,jk+1)
+          END DO
        ENDDO
 
+       IF( ln_timing )  CALL timing_stop('sed_mat_dsr')
+
 
     END SUBROUTINE sed_mat_dsr
 
-    
-    SUBROUTINE sed_mat_btb( nvar, ndim, nlev, psol )
+    SUBROUTINE sed_mat_btb( nvar, ndim, nlev, psol, dtsed_in )
        !!---------------------------------------------------------------------
        !!                  ***  ROUTINE sed_mat_btb  ***
@@ -170,4 +174,6 @@
           psol      ! solution
 
+      REAL(wp), INTENT(in) :: dtsed_in
+
        !---Local declarations
        INTEGER  ::  &
@@ -192,76 +198,68 @@
 
 
+      IF( ln_timing )  CALL timing_start('sed_mat_btb')
+
        ! first sediment level          
-       aplus  = ( ( vols(2) / dz(2) ) + ( vols(3) / dz(3) ) ) / 2.
-       dxplus = ( dz(2) + dz(3) ) / 2.
-       rplus  = ( dtsed / vols(2) ) * db * aplus / dxplus 
-
-       za(1) = 0.
-       zb(1) = 1. + rplus
-       zc(1) = -rplus
+      DO ji = 1, ndim
+         aplus  = ( ( vols(2) / dz(2) ) + ( vols(3) / dz(3) ) ) / 2.
+         dxplus = ( dz(2) + dz(3) ) / 2.
+         rplus  = ( dtsed_in / vols(2) ) * db(ji,2) * aplus / dxplus 
+
+         za(1) = 0.
+         zb(1) = 1. + rplus
+         zc(1) = -rplus
 
              
-       DO jk = 2, nlev - 1
-          aminus  = ( ( vols(jk) / dz(jk) ) + ( vols(jk+1) / dz(jk+1) ) ) / 2.
-          dxminus = ( dz(jk) + dz(jk+1) ) / 2.
-          rminus  = ( dtsed / vols(jk+1) ) * db * aminus / dxminus
-          !
-          aplus   = ( ( vols(jk+1) / dz(jk+1  ) ) + ( vols(jk+2) / dz(jk+2) ) ) / 2.
-          dxplus  = ( dz(jk+1) + dz(jk+2) ) / 2.
-          rplus   = ( dtsed / vols(jk+1) ) * db * aplus / dxplus
-          !     
-          za(jk) = -rminus
-          zb(jk) = 1. + rminus + rplus 
-          zc(jk) = -rplus
-       ENDDO
- 
-       aminus  = ( ( vols(nlev) / dz(nlev) ) + ( vols(nlev+1) / dz(nlev+1) ) ) / 2.
-       dxminus = ( dz(nlev) + dz(nlev+1) ) / 2.
-       rminus  = ( dtsed / vols(nlev+1) ) * db * aminus / dxminus
+         DO jk = 2, nlev - 1
+            aminus  = ( ( vols(jk) / dz(jk) ) + ( vols(jk+1) / dz(jk+1) ) ) / 2.
+            dxminus = ( dz(jk) + dz(jk+1) ) / 2.
+            rminus  = ( dtsed_in / vols(jk+1) ) * db(ji,jk) * aminus / dxminus
+            !
+            aplus   = ( ( vols(jk+1) / dz(jk+1  ) ) + ( vols(jk+2) / dz(jk+2) ) ) / 2.
+            dxplus  = ( dz(jk+1) + dz(jk+2) ) / 2.
+            rplus   = ( dtsed_in / vols(jk+1) ) * db(ji,jk+1) * aplus / dxplus
+            !     
+            za(jk) = -rminus
+            zb(jk) = 1. + rminus + rplus 
+            zc(jk) = -rplus
+         ENDDO
+ 
+         aminus  = ( ( vols(nlev) / dz(nlev) ) + ( vols(nlev+1) / dz(nlev+1) ) ) / 2.
+         dxminus = ( dz(nlev) + dz(nlev+1) ) / 2.
+         rminus  = ( dtsed_in / vols(nlev+1) ) * db(ji,nlev) * aminus / dxminus
+         !
+         za(nlev) = -rminus
+         zb(nlev) = 1. + rminus
+         zc(nlev) = 0.
+
+
+         ! solves tridiagonal system of linear equations 
+         ! -----------------------------------------------    
+         DO jn = 1, nvar
+          
+            DO jk = 1, nlev
+               zr  (ji,jk)    = psol(ji,jk,jn)
+            END DO
+            zbet          = zb(1)
+            psol(ji,1,jn) = zr(ji,1) / zbet
+            ! 
+            DO jk = 2, nlev
+               zgamm(jk) =  zc(jk-1) / zbet
+               zbet      =  zb(jk) - za(jk) * zgamm(jk)
+               psol(ji,jk,jn) = ( zr(ji,jk) - za(jk) * psol(ji,jk-1,jn) ) / zbet
+            ENDDO
+            ! 
+            DO jk = nlev - 1, 1, -1
+                psol(ji,jk,jn) = psol(ji,jk,jn) - zgamm(jk+1) * psol(ji,jk+1,jn)
+            ENDDO
+
+         ENDDO
+
+       END DO
        !
- 
-       za(nlev) = -rminus
-       zb(nlev) = 1. + rminus
-       zc(nlev) = 0.
-
-
-       ! solves tridiagonal system of linear equations 
-       ! -----------------------------------------------    
-       DO jn = 1, nvar
-          
-          zr  (:,:)    = psol(:,:,jn)
-          zbet         = zb(1)
-          psol(:,1,jn) = zr(:,1) / zbet
-          ! 
-          DO jk = 2, nlev
-             zgamm(jk) =  zc(jk-1) / zbet
-             zbet      =  zb(jk) - za(jk) * zgamm(jk)
-             DO ji = 1, ndim
-                psol(ji,jk,jn) = ( zr(ji,jk) - za(jk) * psol(ji,jk-1,jn) ) / zbet
-             END DO
-          ENDDO
-          ! 
-          DO jk = nlev - 1, 1, -1
-             DO ji = 1,ndim
-                psol(ji,jk,jn) = psol(ji,jk,jn) - zgamm(jk+1) * psol(ji,jk+1,jn)
-             END DO
-          ENDDO
-
-       ENDDO
+       IF( ln_timing )  CALL timing_stop('sed_mat_btb')
 
        
     END SUBROUTINE sed_mat_btb
 
-
-#else
-   !!======================================================================
-   !! MODULE sedmat  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_mat         ! Empty routine
-   END SUBROUTINE sed_mat
-   !!======================================================================
-#endif
-
  END MODULE sedmat
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmbc.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedmbc
-#if defined key_sed
    !!======================================================================
    !!              ***  MODULE  sedmbc  ***
@@ -12,4 +11,5 @@
    USE sed     ! sediment global variable
    USE seddsr
+   USE lib_mpp         ! distribued memory computing library
 
    IMPLICIT NONE
@@ -27,12 +27,4 @@
    REAL(wp), DIMENSION(jpwat) :: diss_in_tot   ! total input in pore water
    REAL(wp), DIMENSION(jpwat) :: diss_out_tot  ! total output from pore water
-
-   REAL(wp)  :: cons_tot_o2                   ! cumulative o2 consomation
-   REAL(wp)  :: sour_tot_no3                  ! cumulative no3 source
-   REAL(wp)  :: cons_tot_no3                  ! cumulative no3 consomation
-   REAL(wp)  :: sour_tot_c13                  ! cumulative o2 source
-
-   REAL(wp)  :: src13p  
-   REAL(wp)  :: src13ca  
 
    !! $Id$
@@ -67,16 +59,13 @@
       REAL, DIMENSION(jpwat) :: zpwcp_inv_i, zpwcp_inv_f
       REAL(wp) ::  zdelta_sil, zdelta_clay
-      REAL(wp) ::  zdelta_co2, zdelta_oxy
+      REAL(wp) ::  zdelta_co2, zdelta_fe
       REAL(wp) ::  zdelta_po4, zdelta_no3
-      REAL(wp) ::  zdelta_c13, zdelta_c13b
 
       !!----------------------------------------------------------------------
       ! Initilization
       !---------------
+      IF( ln_timing )  CALL timing_start('sed_mbc')
+!
       IF( kt == nitsed000 ) THEN
-         cons_tot_o2  = 0.
-         sour_tot_no3 = 0.
-         cons_tot_no3 = 0.
-         sour_tot_c13 = 0.
 
          DO js = 1, jpsol
@@ -92,6 +81,4 @@
          ENDDO
 
-         src13p  = rc13P  * pdb
-         src13ca = rc13Ca * pdb
       ENDIF
 
@@ -106,8 +93,8 @@
             ! input [mol]
             rain_tot   (js) = rain_tot   (js) + dtsed * rainrm_dta(ji,js)
-            fromsed_tot(js) = fromsed_tot(js) + fromsed(ji,js)
+            fromsed_tot(js) = fromsed_tot(js) + fromsed(ji,js) / mol_wgt(js)
             ! output [mol]
-            tosed_tot  (js) = tosed_tot (js) + tosed(ji,js)
-            rloss_tot  (js) = rloss_tot (js) + rloss(ji,js)
+            tosed_tot  (js) = tosed_tot (js) + tosed(ji,js) / mol_wgt(js)
+            rloss_tot  (js) = rloss_tot (js) + rloss(ji,js) / mol_wgt(js)
          ENDDO
       ENDDO
@@ -122,13 +109,4 @@
          ENDDO
       ENDDO
-
-      ! cumulativ o2 and no3 consomation
-      DO ji = 1, jpoce
-         cons_tot_o2  = cons_tot_o2  + cons_o2 (ji)
-         sour_tot_no3 = sour_tot_no3 + sour_no3(ji)
-         cons_tot_no3 = cons_tot_no3 + cons_no3(ji)
-         sour_tot_c13 = sour_tot_c13 + sour_c13(ji)
-      ENDDO
-     
 
       ! Mass balance check
@@ -141,5 +119,5 @@
          zpwcp_inv_f (:) = 0.        
          DO js = 1, jpsol
-            zdsw = dens / mol_wgt(js)
+            zdsw = denssol / mol_wgt(js)
             DO jk = 2, jpksed
                DO ji = 1, jpoce
@@ -178,52 +156,36 @@
 
          ! mass balance for carbon ( carbon in POC, CaCo3, DIC )
-         zinit      = zsolcp_inv_i(jspoc) + zsolcp_inv_i(jscal) + zpwcp_inv_i(jwdic)
-         zfinal     = zsolcp_inv_f(jspoc) + zsolcp_inv_f(jscal) + zpwcp_inv_f(jwdic)
-         zinput     = rain_tot   (jspoc) + rain_tot   (jscal) + diss_in_tot(jwdic)
-         zoutput    = tosed_tot  (jspoc) + tosed_tot  (jscal) + diss_out_tot(jwdic) &
-            &       + rloss_tot  (jspoc) + rloss_tot  (jscal) 
+         zinit      = zsolcp_inv_i(jspoc) + zsolcp_inv_i(jspos) + zsolcp_inv_i(jspor) &
+         &          + zsolcp_inv_i(jscal) + zpwcp_inv_i(jwdic)
+         zfinal     = zsolcp_inv_f(jspoc) + zsolcp_inv_f(jspos) + zsolcp_inv_f(jspor) &
+         &          + zsolcp_inv_f(jscal) + zpwcp_inv_f(jwdic)
+         zinput     = rain_tot (jspoc) + rain_tot   (jspos)  +  rain_tot   (jspor) &
+         &          + rain_tot (jscal) + diss_in_tot(jwdic)
+         zoutput    = tosed_tot(jspoc) + tosed_tot(jspos) + tosed_tot(jspor) + tosed_tot(jscal) + diss_out_tot(jwdic) &
+            &       + rloss_tot(jspoc) + rloss_tot(jspos) + rloss_tot(jspor) + rloss_tot(jscal) 
          zdelta_co2 = ( zfinal + zoutput ) - ( zinit + zinput )
 
-         ! mass balance for oxygen : O2 is in POC remineralization
-         zinit      = zpwcp_inv_i(jwoxy)
-         zfinal     = zpwcp_inv_f(jwoxy)
-         zinput     = diss_in_tot(jwoxy)
-         zoutput    = diss_out_tot(jwoxy) + cons_tot_o2
-         zdelta_oxy = ( zfinal + zoutput ) - ( zinit + zinput )
-
-         ! mass balance for phosphate ( PO4 in POC and dissolved phosphates )
-         zinit      = zsolcp_inv_i(jspoc) * spo4r + zpwcp_inv_i(jwpo4)
-         zfinal     = zsolcp_inv_f(jspoc) * spo4r + zpwcp_inv_f(jwpo4)
-         zinput     = rain_tot   (jspoc) * spo4r + diss_in_tot(jwpo4)
-         zoutput    = tosed_tot  (jspoc) * spo4r + diss_out_tot(jwpo4) &
-            &       + rloss_tot  (jspoc) * spo4r
-         zdelta_po4 = ( zfinal + zoutput ) - ( zinit + zinput )
-
-
-         ! mass balance for Nitrate
-         zinit      = zpwcp_inv_i  (jwno3)
-         zfinal     = zpwcp_inv_f  (jwno3)
-         zinput     = diss_in_tot (jwno3) + sour_tot_no3
-         zoutput    = diss_out_tot(jwno3) + cons_tot_no3
+         ! mass balance for Sulfur
+         zinit      = zpwcp_inv_i(jwso4) + zpwcp_inv_i(jwh2s)   &
+         &          + zsolcp_inv_i(jsfes) 
+         zfinal     = zpwcp_inv_f(jwso4) + zpwcp_inv_f(jwh2s)   &
+         &          + zsolcp_inv_f(jsfes)
+         zinput     = diss_in_tot (jwso4) + diss_in_tot (jwh2s) &
+         &          + rain_tot (jsfes)
+         zoutput    = diss_out_tot(jwso4) + diss_out_tot(jwh2s) &
+         &          + tosed_tot(jsfes)    + rloss_tot(jsfes)
          zdelta_no3 = ( zfinal + zoutput ) - ( zinit + zinput )
 
-         ! mass balance for DIC13
-         zinit      =  zpwcp_inv_i(jwc13)   &
-            &        + src13p * zsolcp_inv_i(jspoc) + src13Ca * zsolcp_inv_i(jscal) 
-         zfinal     =  zpwcp_inv_f(jwc13)   &
-            &        + src13p * zsolcp_inv_f(jspoc) + src13Ca * zsolcp_inv_f(jscal)
-         zinput     =  diss_in_tot (jwc13)  &
-            &        + src13p * rain_tot(jspoc) + src13Ca * rain_tot(jscal)
-         zoutput    =  diss_out_tot(jwc13)  &
-            &        + src13p * tosed_tot(jspoc) + src13Ca * tosed_tot(jscal) &   
-            &        + src13p * rloss_tot(jspoc) + src13Ca * rloss_tot(jscal)
-         zdelta_c13 = ( zfinal + zoutput ) - ( zinit + zinput )
-
-         ! other mass balance for DIC13
-         zinit      = zpwcp_inv_i  (jwc13)
-         zfinal     = zpwcp_inv_f  (jwc13)
-         zinput     = diss_in_tot (jwc13) + sour_tot_c13
-         zoutput    = diss_out_tot(jwc13)
-         zdelta_c13b= ( zfinal + zoutput ) - ( zinit + zinput )    
+         ! mass balance for iron
+         zinit      = zpwcp_inv_i(jwfe2)  + zsolcp_inv_i(jsfeo)   &
+         &          + zsolcp_inv_i(jsfes)
+         zfinal     = zpwcp_inv_f(jwfe2)  + zsolcp_inv_f(jsfeo)   &
+         &          + zsolcp_inv_f(jsfes)
+         zinput     = diss_in_tot (jwfe2) + rain_tot (jsfeo) &
+         &          + rain_tot (jsfes)
+         zoutput    = diss_out_tot(jwfe2) + tosed_tot(jsfeo) &
+         &          + tosed_tot(jsfes)    + rloss_tot(jsfes) + rloss_tot(jsfeo)
+         zdelta_fe  = ( zfinal + zoutput ) - ( zinit + zinput )
+
 
       END IF
@@ -231,91 +193,65 @@
       IF( kt == nitsedend) THEN 
 
+         IF (lwp) THEN
          WRITE(numsed,*)
          WRITE(numsed,*)'==================    General mass balance   ==================  '
          WRITE(numsed,*)' '
          WRITE(numsed,*)' '
-         WRITE(numsed,*)' Initial total solid Masses (mole/dx.dy) (k=2-11) '
+         WRITE(numsed,*)' Initial total solid Masses (mole/dx.dy)        '
          WRITE(numsed,*)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
-         WRITE(numsed,*)'    Opale,      Clay,       POC,        CaCO3,         C13'
-         WRITE(numsed,'(4x,5(1PE10.3,2X))')zsolcp_inv_i(jsopal),zsolcp_inv_i(jsclay),zsolcp_inv_i(jspoc), &
-            & zsolcp_inv_i(jscal),( src13P * zsolcp_inv_i(jspoc) + src13Ca * zsolcp_inv_i(jscal) )
-         WRITE(numsed,*)' '
-         WRITE(numsed,*)' Initial total dissolved Masses (mole/dx.dy) (k=2-11) '
+         WRITE(numsed,*)'    Opal,      Clay,       POC,       POS,      POR,        CaCO3,     FeOH,     FeS'
+         WRITE(numsed,'(8x,4(1PE10.3,2X))')zsolcp_inv_i(jsopal),zsolcp_inv_i(jsclay),zsolcp_inv_i(jspoc), &
+            & zsolcp_inv_i(jspos),zsolcp_inv_i(jspor),zsolcp_inv_i(jscal),zsolcp_inv_i(jsfeo),zsolcp_inv_i(jsfes)
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)' Initial total dissolved Masses (mole/dx.dy)    '
          WRITE(numsed,*)' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'
-         WRITE(numsed,*)'    Si,         O2,         DIC,        Nit         Phos,       DIC13'
-         WRITE(numsed,'(4x,6(1PE10.3,2X))') zpwcp_inv_i(jwsil), zpwcp_inv_i(jwoxy), &
-            & zpwcp_inv_i(jwdic), zpwcp_inv_i(jwno3), zpwcp_inv_i(jwpo4), zpwcp_inv_i(jwc13)
-         WRITE(numsed,*)' '
-         WRITE(numsed,*)'  Solid inputs :  Opale,      Clay,       POC,        CaCO3,         C13'
-         WRITE(numsed,'(A4,10X,5(1PE10.3,2X))')'Rain : ',rain_tot(jsopal),rain_tot(jsclay),rain_tot(jspoc),&
-            & rain_tot(jscal),( src13P * rain_tot(jspoc) + src13Ca * rain_tot(jscal) )
-         WRITE(numsed,'(A12,6x,4(1PE10.3,2X))')' From Sed : ',fromsed_tot(jsopal), fromsed_tot(jsclay), &
-            & fromsed_tot(jspoc), fromsed_tot(jscal)
-         WRITE(numsed,*)'Diss. inputs : Si,    O2,         DIC,         Nit,       Phos,       DIC13'
+         WRITE(numsed,*)'    Si,         O2,         DIC,        Nit,         Phos,         Fe2+'
+         WRITE(numsed,'(5x,5(1PE10.3,2X))') zpwcp_inv_i(jwsil), zpwcp_inv_i(jwoxy), &
+            & zpwcp_inv_i(jwdic), zpwcp_inv_i(jwno3), zpwcp_inv_i(jwpo4), zpwcp_inv_i(jwfe2)
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)'  Solid inputs :  Opale,      Clay,       POC,        CaCO3,        Fe'
+         WRITE(numsed,'(A4,10X,5(1PE10.3,2X))')'Rain : ',rain_tot(jsopal),rain_tot(jsclay),rain_tot(jspoc) + rain_tot(jspos) + rain_tot(jspor),&
+            & rain_tot(jscal), rain_tot(jsfeo)
+         WRITE(numsed,'(A12,6x,5(1PE10.3,2X))')' From Sed : ',fromsed_tot(jsopal), fromsed_tot(jsclay), &
+            & fromsed_tot(jspoc)+fromsed_tot(jspos)+fromsed_tot(jspor), fromsed_tot(jscal),    &
+            & fromsed_tot(jsfeo) + fromsed_tot(jsfes)
+         WRITE(numsed,*)'Diss. inputs : Si,    O2,         DIC,         Nit,       Phos,      Fe'
          WRITE(numsed,'(A9,1x,6(1PE10.3,2X))')' From Pisc : ', diss_in_tot(jwsil), &
-            & diss_in_tot(jwoxy), diss_in_tot(jwdic), diss_in_tot(jwno3), diss_in_tot(jwpo4), &
-            & diss_in_tot(jwc13)
-         WRITE(numsed,*)' '
-         WRITE(numsed,*)'Solid output : Opale,      Clay,       POC,        CaCO3,          C13'
-         WRITE(numsed,'(A6,8x,5(1PE10.3,2X))')'To sed', tosed_tot(jsopal),tosed_tot(jsclay),tosed_tot(jspoc),&
-            & tosed_tot(jscal),( src13P * tosed_tot(jspoc) + src13Ca * tosed_tot(jscal) )
-         WRITE(numsed,'(A5,9x,5(1PE10.3,2X))')'Perdu', rloss_tot(jsopal),rloss_tot(jsclay),rloss_tot(jspoc),&
-            & rloss_tot(jscal),( src13P * rloss_tot(jspoc) + src13Ca * rloss_tot(jscal) )
-         WRITE(numsed,*)'Diss. output : Si,     O2,        DIC,          Nit,       Phos,       DIC13 '  
+            & diss_in_tot(jwoxy), diss_in_tot(jwdic), diss_in_tot(jwno3), diss_in_tot(jwpo4), diss_in_tot(jwfe2)
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)'Solid output : Opale,      Clay,       POC,        CaCO3,        Fe'
+         WRITE(numsed,'(A6,8x,5(1PE10.3,2X))')'To sed', tosed_tot(jsopal),tosed_tot(jsclay),tosed_tot(jspoc) &
+            & +tosed_tot(jspos)+tosed_tot(jspor),tosed_tot(jscal), tosed_tot(jsfeo)+tosed_tot(jsfes)
+         WRITE(numsed,'(A5,9x,5(1PE10.3,2X))')'Perdu', rloss_tot(jsopal),rloss_tot(jsclay),rloss_tot(jspoc) &
+            & +rloss_tot(jspos)+rloss_tot(jspor),rloss_tot(jscal),rloss_tot(jsfeo)+rloss_tot(jsfes)
+         WRITE(numsed,*)'Diss. output : Si,     O2,        DIC,          Nit,       Phos,        Fe '  
          WRITE(numsed,'(A7,2x,6(1PE10.3,2X))')'To kbot', diss_out_tot(jwsil), &
-            & diss_out_tot(jwoxy), diss_out_tot(jwdic), diss_out_tot(jwno3), diss_out_tot(jwpo4), &
-            & diss_out_tot(jwc13)
-         WRITE(numsed,*)' '
-         WRITE(numsed,*)' Total consomation in POC remineralization [mol]:  O2,         NO3'
-         WRITE(numsed,'(51x,2(1PE10.3,2X))') cons_tot_o2,cons_tot_no3
-         WRITE(numsed,*)' '
-         WRITE(numsed,*)'Final solid  Masses (mole/dx.dy) (k=2-11)'
-         WRITE(numsed,*)'    Opale,      Clay,       POC,        CaCO3,          C13'
-         WRITE(numsed,'(4x,5(1PE10.3,2X))')zsolcp_inv_f(jsopal),zsolcp_inv_f(jsclay),zsolcp_inv_f(jspoc), &
-            & zsolcp_inv_f(jscal),( src13P * zsolcp_inv_f(jspoc) + src13Ca * zsolcp_inv_f(jscal) )
+            & diss_out_tot(jwoxy), diss_out_tot(jwdic), diss_out_tot(jwno3), diss_out_tot(jwpo4), diss_out_tot(jwfe2)
+         WRITE(numsed,*)' '
+         WRITE(numsed,*)'Final solid  Masses (mole/dx.dy) '
+         WRITE(numsed,*)'    Opale,      Clay,       POC,        CaCO3,      Fe'
+         WRITE(numsed,'(4x,5(1PE10.3,2X))')zsolcp_inv_f(jsopal),zsolcp_inv_f(jsclay),zsolcp_inv_f(jspoc)  &
+            & +zsolcp_inv_f(jspos)+zsolcp_inv_f(jspor),zsolcp_inv_f(jscal),zsolcp_inv_f(jsfeo)+zsolcp_inv_f(jsfes)
          WRITE(numsed,*)' '
          WRITE(numsed,*)'Final dissolved  Masses (mole/dx.dy) (k=2-11)'
-         WRITE(numsed,*)'    Si,        O2,         DIC,        Nit,        Phos,    DIC13'
+         WRITE(numsed,*)'    Si,        O2,         DIC,        Nit,        Phos,        Fe'
          WRITE(numsed,'(4x,6(1PE10.3,2X))') zpwcp_inv_f(jwsil), zpwcp_inv_f(jwoxy), &
-            & zpwcp_inv_f(jwdic), zpwcp_inv_f(jwno3), zpwcp_inv_f(jwpo4), zpwcp_inv_f(jwc13)
+            & zpwcp_inv_f(jwdic), zpwcp_inv_f(jwno3), zpwcp_inv_f(jwpo4), zpwcp_inv_f(jwfe2)
          WRITE(numsed,*)' '     
-         WRITE(numsed,*)'Delta : Opale,      Clay,       C,          O,          N,          P,        C13'
-         WRITE(numsed,'(7x,7(1PE11.3,1X))') zdelta_sil, zdelta_clay, zdelta_co2, zdelta_oxy, zdelta_no3,&
-            &                          zdelta_po4, zdelta_c13
-         WRITE(numsed,*)' ' 
-         WRITE(numsed,*)'deltaC13bis : ',zdelta_c13b     
-
+         WRITE(numsed,*)'Delta : Opale,      Clay,       C,         Fe,          S,'
+         WRITE(numsed,'(7x,6(1PE11.3,1X))') zdelta_sil / ( zsolcp_inv_i(jsopal) + zpwcp_inv_i(jwsil) ) , &
+         &            zdelta_clay / ( zsolcp_inv_i(jsclay) ) ,      & 
+         &            zdelta_co2 / ( zsolcp_inv_i(jspoc) + zsolcp_inv_i(jspos) + zsolcp_inv_i(jspor) &
+         &          + zsolcp_inv_i(jscal) + zpwcp_inv_i(jwdic) ),     &
+         &            zdelta_fe / ( zpwcp_inv_i(jwfe2) + zsolcp_inv_i(jsfeo) + zsolcp_inv_i(jsfes) ) ,  &
+         &            zdelta_no3 / ( zpwcp_inv_i(jwso4) + zpwcp_inv_i(jwh2s) + zsolcp_inv_i(jsfes) )
          WRITE(numsed,*)'=========================================================================='
-         WRITE(numsed,*)' Composition of final sediment for point jpoce'
-         WRITE(numsed,*)' ========================================='
-         WRITE(numsed,*)'Opale,      Clay,       POC,        CaCo3,      hipor,      pH,         co3por'
-         DO jk = 1,jpksed
-            WRITE(numsed,'(4(F8.4,4X),3(1PE10.3,2X))') solcp(jpoce,jk,jsopal)*100.,solcp(jpoce,jk,jsclay)*100.,&
-               &       solcp(jpoce,jk,jspoc)*100.,solcp(jpoce,jk,jscal)*100.,&
-               &       hipor(jpoce,jk),-LOG10(hipor(jpoce,jk)/densSW(jpoce)),co3por(jpoce,jk)
-         ENDDO
-         WRITE(numsed,*)'Silicic A.,  Oxygen,     DIC,        Nitrats,    Phosphats,  Alkal.,     DIC13'
-         DO jk = 1, jpksed
-            WRITE(numsed,'(8(1PE10.3,2X))')pwcp(jpoce,jk,jwsil),pwcp(jpoce,jk,jwoxy),&
-               & pwcp(jpoce,jk,jwdic),pwcp(jpoce,jk,jwno3),pwcp(jpoce,jk,jwpo4),pwcp(jpoce,jk,jwalk),pwcp(jpoce,jk,jwc13)
-         ENDDO
-         WRITE(numsed,*)'densSW at the end : ',densSW(jpoce)
-         WRITE(numsed,*)'=========================================================================='
 
       ENDIF
+      ENDIF
+
+      IF( ln_timing )  CALL timing_stop('sed_mbc')
   
    END SUBROUTINE sed_mbc
 
-
-#else
-   !!======================================================================
-   !! MODULE sedmbc :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_mbc( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_mbc: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_mbc
-#endif
 END MODULE sedmbc
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmodel.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmodel.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedmodel.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedmodel
-#if defined key_sed
    !!======================================================================
    !!                       ***  MODULE sedmodel   ***
@@ -6,6 +5,6 @@
    !!======================================================================
    USE sed
-   USE sedini   ! sediment variables initialization
    USE sedstp   ! time stepping
+   USE sedinitrc
 
    IMPLICIT NONE
@@ -33,21 +32,12 @@
 
 
-      IF( kt == nittrc000 ) CALL sed_init       ! Initialization of sediment model
+      IF( ln_timing )  CALL timing_start('sed_model')
 
-                         CALL sed_stp( kt )  ! Time stepping of Sediment model
+      IF( kt == nittrc000 ) CALL sed_initrc       ! Initialization of sediment model
+                            CALL sed_stp( kt )  ! Time stepping of Sediment model
 
+      IF( ln_timing )  CALL timing_stop('sed_model')
 
    END SUBROUTINE sed_model
 
-#else
-   !!======================================================================
-   !! MODULE sedmodel  :   Dummy module 
-   !!======================================================================
-CONTAINS
-   SUBROUTINE sed_model( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_stp: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_model
-#endif
-
 END MODULE sedmodel
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedorg.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedorg.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedorg.F90	(revision 10321)
@@ -0,0 +1,159 @@
+MODULE sedorg
+   !!======================================================================
+   !!              ***  MODULE  seddsr  ***
+   !!    Sediment : dissolution and reaction in pore water related 
+   !!    related to organic matter
+   !!=====================================================================
+   !! * Modules used
+   USE sed     ! sediment global variable
+   USE sed_oce
+   USE sedini
+   USE seddiff
+   USE seddsr
+   USE lib_mpp         ! distribued memory computing library
+   USE lib_fortran
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC sed_org
+
+   !! * Module variables
+
+   REAL(wp) :: zadsnh4
+
+   !! $Id$
+CONTAINS
+   
+   SUBROUTINE sed_org( kt ) 
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_org  ***
+      !! 
+      !!  ** Purpose :  computes pore water diffusion and reaction
+      !!
+      !!  ** Methode :  Computation of the redox reactions in sediment.
+      !!                The main redox reactions are solved in sed_dsr whereas
+      !!                the secondary reactions are solved in sed_dsr_redoxb.
+      !!                A strand spliting approach is being used here (see 
+      !!                sed_dsr_redoxb for more information). 
+      !!                Diffusive fluxes are computed in sed_diff
+      !!
+      !!   History :
+      !!        !  98-08 (E. Maier-Reimer, Christoph Heinze )  Original code
+      !!        !  04-10 (N. Emprin, M. Gehlen ) f90
+      !!        !  06-04 (C. Ethe)  Re-organization
+      !!        !  19-08 (O. Aumont) Debugging and improvement of the model.
+      !!                             The original method is replaced by a 
+      !!                             Strand splitting method which deals 
+      !!                             well with stiff reactions.
+      !!----------------------------------------------------------------------
+      !! Arguments
+      INTEGER, INTENT(in) ::   kt
+      ! --- local variables
+      INTEGER  :: ji, jk, js, jw, jnt   ! dummy looop indices
+      REAL(wp) :: zadsnh4
+      !!
+      !!----------------------------------------------------------------------
+
+      IF( ln_timing )  CALL timing_start('sed_org')
+!
+      IF( kt == nitsed000 ) THEN
+         IF (lwp) THEN
+            WRITE(numsed,*) ' sed_org : Organic degradation related reactions and diffusion'
+            WRITE(numsed,*) ' '
+         ENDIF
+!         ! 
+         dens_mol_wgt(1:jpsol) = denssol / mol_wgt(1:jpsol)
+         ! 
+      ENDIF
+
+      dtsed2 = dtsed / REAL( nrseddt, wp )
+
+      ! 1. Change of geometry
+      !    Increase of dz3d(2) thickness : dz3d(2) = dz3d(2)+dzdep
+      !    Warning : no change for dz(2)
+      !---------------------------------------------------------
+      dz3d(1:jpoce,2) = dz3d(1:jpoce,2) + dzdep(1:jpoce)
+
+      ! New values for volw3d(:,2) and vols3d(:,2)
+      ! Warning : no change neither for volw(2) nor  vols(2)
+      !------------------------------------------------------
+      volw3d(1:jpoce,2) = dz3d(1:jpoce,2) * por(2)
+      vols3d(1:jpoce,2) = dz3d(1:jpoce,2) * por1(2)
+
+      ! 2. Change of previous solid fractions (due to volum changes) for k=2
+      !---------------------------------------------------------------------
+
+      DO js = 1, jpsol
+         DO ji = 1, jpoce
+            solcp(ji,2,js) = solcp(ji,2,js) * dz(2) / dz3d(ji,2)
+         ENDDO
+      END DO
+
+      ! 3. New solid fractions (including solid rain fractions) for k=2
+      !------------------------------------------------------------------
+      DO js = 1, jpsol
+         DO ji = 1, jpoce
+            IF (raintg(ji) .ne. 0) THEN
+               solcp(ji,2,js) = solcp(ji,2,js) + &
+               &           ( rainrg(ji,js) / raintg(ji) ) * ( dzdep(ji) / dz3d(ji,2) )
+               ! rainrm are temporary cancel
+               rainrm(ji,js) = 0.
+            ENDIF
+         END DO
+      ENDDO
+
+      ! 4.  Adjustment of bottom water concen.(pwcp(1)):
+      !     We impose that pwcp(2) is constant. Including dzdep in dz3d(:,2) we assume
+      !     that dzdep has got a porosity of por(2). So pore water volum of jk=2 increase.
+      !     To keep pwcp(2) cste we must compensate this "increase" by a slight adjusment
+      !     of bottom water concentration.
+      !     This adjustment is compensate at the end of routine
+      !-------------------------------------------------------------
+      DO jw = 1, jpwat
+         DO ji = 1, jpoce
+            pwcp(ji,1,jw) = pwcp(ji,1,jw) - &
+               &            pwcp(ji,2,jw) * dzdep(ji) * por(2) / ( dzkbot(ji) + rtrn )
+         END DO
+      ENDDO
+
+      zadsnh4 = 1.0 / ( 1.0 + adsnh4 )
+
+      ! --------------------------------------------------
+      ! Computation of the diffusivities
+      ! --------------------------------------------------
+
+      DO js = 1, jpwat
+         DO jk = 1, jpksed
+            DO ji = 1, jpoce
+               diff(ji,jk,js) = ( diff1(js) + diff2(js) * temp(ji) ) / ( 1.0 - 2.0 * log( por(jk) ) )
+            END DO
+         END DO
+      END DO
+
+      ! Impact of bioirrigation and adsorption on diffusion
+      ! ---------------------------------------------------
+
+      diff(:,:,jwnh4) = diff(:,:,jwnh4) * ( 1.0 + irrig(:,:) ) * zadsnh4
+      diff(:,:,jwsil) = diff(:,:,jwsil) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwoxy) = diff(:,:,jwoxy) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwdic) = diff(:,:,jwdic) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwno3) = diff(:,:,jwno3) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwpo4) = diff(:,:,jwpo4) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwalk) = diff(:,:,jwalk) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwh2s) = diff(:,:,jwh2s) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwso4) = diff(:,:,jwso4) * ( 1.0 + irrig(:,:) )
+      diff(:,:,jwfe2) = diff(:,:,jwfe2) * ( 1.0 + 0.2 * irrig(:,:) )
+
+      DO jnt = 1, nrseddt
+         CALL sed_diff( kt, jnt )        ! 1st pass in diffusion to get values at t+1/2
+         CALL sed_dsr ( kt, jnt )        ! Dissolution reaction
+         CALL sed_diff( kt, jnt )        ! 2nd pass in diffusion to get values at t+1
+      END DO
+
+
+      IF( ln_timing )  CALL timing_stop('sed_org')
+!      
+   END SUBROUTINE sed_org
+
+END MODULE sedorg
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedrst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedrst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedrst.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedrst
-#if defined key_sed
    !!======================================================================
    !!                       *** MODULE sedrst ***
@@ -11,4 +10,8 @@
    USE sed
    USE sedarr
+   USE trc_oce, ONLY: l_offline         ! ocean space and time domain variables
+   USE iom
+   USE daymod
+   USE lib_mpp         ! distribued memory computing library
 
 
@@ -18,14 +21,65 @@
 
    !! * Accessibility
+   PUBLIC sed_rst_opn       ! called by ???
    PUBLIC sed_rst_read
    PUBLIC sed_rst_wri
-
-   !! * Module variables
-   INTEGER, PUBLIC ::   numrsr, numrsw   !: logical unit for sed restart (read and write)
-   
-   
+   PUBLIC sed_rst_cal
+
    !! $Id$
 CONTAINS
 
+
+   SUBROUTINE sed_rst_opn( kt )
+      !!----------------------------------------------------------------------
+      !!                    ***  sed_rst_opn  ***
+      !!
+      !! ** purpose  :   output of sed-trc variable in a netcdf file
+      !!----------------------------------------------------------------------
+      INTEGER, INTENT(in) ::   kt       ! number of iteration
+      !
+      CHARACTER(LEN=20)   ::   clkt     ! ocean time-step define as a character
+      CHARACTER(LEN=50)   ::   clname   ! trc output restart file name
+      CHARACTER(LEN=256)  ::   clpath   ! full path to ocean output restart file
+      !!----------------------------------------------------------------------
+      !
+      IF( l_offline ) THEN
+         IF( kt == nittrc000 ) THEN
+            lrst_sed = .FALSE.
+            IF( ln_rst_list ) THEN
+               nrst_lst = 1
+               nitrst = nstocklist( nrst_lst )
+            ELSE
+               nitrst = nitend
+            ENDIF
+         ENDIF
+         IF( .NOT. ln_rst_list .AND. MOD( kt - 1, nstock ) == 0 ) THEN
+            ! we use kt - 1 and not kt - nittrc000 to keep the same periodicity from the beginning of the experiment
+            nitrst = kt + nstock - 1                  ! define the next value of nitrst for restart writing
+            IF( nitrst > nitend )   nitrst = nitend   ! make sure we write a restart at the end of the run
+         ENDIF
+      ELSE
+         IF( kt == nittrc000 ) lrst_sed = .FALSE.
+      ENDIF
+
+      ! to get better performances with NetCDF format:
+      ! we open and define the tracer restart file one tracer time step before writing the data (-> at nitrst - 2*nn_dttrc + 1)
+      ! except if we write tracer restart files every tracer time step or if a tracer restart file was writen at nitend - 2*nn_dttrc + 1
+      IF( kt == nitrst - 2*nn_dtsed .OR. nstock == nn_dtsed .OR. ( kt == nitend - nn_dtsed .AND. .NOT. lrst_sed ) ) THEN
+         ! beware of the format used to write kt (default is i8.8, that should be large enough)
+         IF( nitrst > 1.0e9 ) THEN   ;   WRITE(clkt,*       ) nitrst
+         ELSE                        ;   WRITE(clkt,'(i8.8)') nitrst
+         ENDIF
+         ! create the file
+         IF(lwp) WRITE(numsed,*)
+         clname = TRIM(cexper)//"_"//TRIM(ADJUSTL(clkt))//"_"//TRIM(cn_sedrst_out)
+         clpath = TRIM(cn_sedrst_outdir)
+         IF( clpath(LEN_TRIM(clpath):) /= '/' ) clpath = TRIM(clpath) // '/'
+         IF(lwp) WRITE(numsed,*) &
+             '             open sed restart.output NetCDF file: ',TRIM(clpath)//clname
+         CALL iom_open( TRIM(clpath)//TRIM(clname), numrsw, ldwrt = .TRUE., kiolib = jprstlib, kdlev = jpksed )
+         lrst_sed = .TRUE.
+      ENDIF
+      !
+   END SUBROUTINE sed_rst_opn
 
    SUBROUTINE sed_rst_read 
@@ -40,74 +94,54 @@
       !!        !  06-07  (C. Ethe)  original
       !!----------------------------------------------------------------------
-      !! * Modules used
-      USE iom
 
       !! * local declarations
-      INTEGER :: ji, jk, jn 
-      REAL(wp), ALLOCATABLE, DIMENSION(:,:,:,:) :: zdta
-      REAL(wp), ALLOCATABLE, DIMENSION(:,:,:  ) :: zdta1 
-      REAL(wp), ALLOCATABLE, DIMENSION(:,:    ) :: zhipor
+      INTEGER :: ji, jj, jk, jn 
+      REAL(wp), DIMENSION(jpi,jpj,jpksed,jptrased) :: zdta
+      REAL(wp), DIMENSION(jpi,jpj,jpksed,2)        :: zdta1 
+      REAL(wp), DIMENSION(jpi,jpj,jpksed)          :: zdta2
+      REAL(wp), DIMENSION(jpoce,jpksed)            :: zhipor
       REAL(wp) :: zkt
       CHARACTER(len = 20) ::   cltra
+      CHARACTER(LEN=20)   ::   name1
       INTEGER             ::   jlibalt = jprstlib
       LOGICAL             ::   llok
       !--------------------------------------------------------------------
- 
-
-      WRITE(numsed,*) ' '      
-      WRITE(numsed,*) ' Initilization of Sediment components from restart'
-      WRITE(numsed,*) ' '
-
-      ALLOCATE( zdta(jpi,jpj,jpksed,jptrased), zdta1(jpi,jpj,jpksed,2), zhipor(jpoce,jpksed) ) 
-
-      CALL iom_open( 'restart_sed', numrsr, kiolib = jlibalt )     
-      CALL iom_get( numrsr, 'kt'     , zkt      )   ! time-step
- 
+
+      IF( ln_timing )  CALL timing_start('sed_rst_read')
+
+      IF (lwp) WRITE(numsed,*) ' '      
+      IF (lwp) WRITE(numsed,*) ' Initilization of Sediment components from restart'
+      IF (lwp) WRITE(numsed,*) ' '
+
+      zdta  = 1.
+      zdta1 = 1.
+      zdta2 = 0.
+
       DO jn = 1, jptrased
-         cltra = sedtrcd(jn)
-         CALL iom_get( numrsr, jpdom_unknown, cltra, zdta(:,:,:,jn), &
-            &          kstart=(/1,1,1/), kcount=(/jpi,jpj,jpksed/) )
-      ENDDO
-        
-
-      CALL pack_arr( jpoce, solcp(1:jpoce,1:jpksed,jsopal), &
-         &            zdta(1:jpi,1:jpj,1:jpksed,1), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, solcp(1:jpoce,1:jpksed,jsclay), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,2), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, solcp(1:jpoce,1:jpksed,jspoc), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,3), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, solcp(1:jpoce,1:jpksed,jscal), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,4), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwsil), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,5), iarroce(1:jpoce) )
-
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwoxy), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,6), iarroce(1:jpoce) )
-
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwdic), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,7), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwno3), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,8), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwpo4), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,9), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwalk), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,10), iarroce(1:jpoce) )
-
-      CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jwc13), &
-         &             zdta(1:jpi,1:jpj,1:jpksed,11), iarroce(1:jpoce) )
+         cltra = TRIM(sedtrcd(jn))
+         IF( iom_varid( numrsr, TRIM(cltra) , ldstop = .FALSE. ) > 0 ) THEN
+            CALL iom_get( numrsr, jpdom_autoglo, TRIM(cltra), zdta(:,:,:,jn) )
+         ELSE
+            zdta(:,:,:,jn) = 0.0
+         ENDIF
+      ENDDO
+
+      DO jn = 1, jpsol
+         CALL pack_arr( jpoce, solcp(1:jpoce,1:jpksed,jn), &
+         &              zdta(1:jpi,1:jpj,1:jpksed,jn), iarroce(1:jpoce) )
+      END DO
+
+      DO jn = 1, jpwat
+         CALL pack_arr( jpoce, pwcp(1:jpoce,1:jpksed,jn), &
+         &              zdta(1:jpi,1:jpj,1:jpksed,jpsol+jn), iarroce(1:jpoce) )
+      END DO
 
       DO jn = 1, 2
-         cltra = seddia3d(jn)
-         CALL iom_get( numrsr, jpdom_unknown, cltra, zdta1(:,:,:,jn), &
-            &          kstart=(/1,1,1/), kcount=(/jpi,jpj,jpksed/) )
+         cltra = TRIM(seddia3d(jn))
+         IF( iom_varid( numrsr, TRIM(cltra) , ldstop = .FALSE. ) > 0 ) THEN
+            CALL iom_get( numrsr, jpdom_autoglo, TRIM(cltra), zdta1(:,:,:,jn) )
+         ELSE
+            zdta1(:,:,:,jn) = 0.0
+         ENDIF
       ENDDO
 
@@ -122,5 +156,5 @@
          ENDDO
       ENDDO
-      
+
       CALL pack_arr( jpoce, co3por(1:jpoce,1:jpksed), &
          &             zdta1(1:jpi,1:jpj,1:jpksed,2), iarroce(1:jpoce) )
@@ -131,7 +165,35 @@
       pwcp (1:jpoce,1,:) = 0.
 
-      DEALLOCATE( zdta   )
-      DEALLOCATE( zdta1  )
-      DEALLOCATE( zhipor )
+      cltra = "dbioturb"
+      IF( iom_varid( numrsr, TRIM(cltra) , ldstop = .FALSE. ) > 0 ) THEN
+         CALL iom_get( numrsr, jpdom_autoglo, TRIM(cltra), zdta2(:,:,:) )
+      ELSE
+         zdta2(:,:,:) = 0.0
+      ENDIF
+
+      CALL pack_arr( jpoce, db(1:jpoce,1:jpksed), &
+         &             zdta2(1:jpi,1:jpj,1:jpksed), iarroce(1:jpoce) )
+
+      cltra = "irrig"
+      IF( iom_varid( numrsr, TRIM(cltra) , ldstop = .FALSE. ) > 0 ) THEN
+         CALL iom_get( numrsr, jpdom_autoglo, TRIM(cltra), zdta2(:,:,:) )
+      ELSE
+         zdta2(:,:,:) = 0.0
+      ENDIF
+
+      CALL pack_arr( jpoce, irrig(1:jpoce,1:jpksed), &
+         &             zdta2(1:jpi,1:jpj,1:jpksed), iarroce(1:jpoce) )
+
+      cltra = "sedligand"
+      IF( iom_varid( numrsr, TRIM(cltra) , ldstop = .FALSE. ) > 0 ) THEN
+         CALL iom_get( numrsr, jpdom_autoglo, TRIM(cltra), zdta2(:,:,:) )
+      ELSE
+         zdta2(:,:,:) = 0.0
+      ENDIF
+
+      CALL pack_arr( jpoce, sedligand(1:jpoce,1:jpksed), &
+         &             zdta2(1:jpi,1:jpj,1:jpksed), iarroce(1:jpoce) )
+
+      IF( ln_timing )  CALL timing_stop('sed_rst_read')
      
    END SUBROUTINE sed_rst_read
@@ -147,130 +209,204 @@
       !!----------------------------------------------------------------------
       !!* Modules used
-      USE ioipsl
-      !! *Arguments
       INTEGER, INTENT(in) ::   kt       ! number of iteration
       !! * local declarations
-      INTEGER  :: ji, jk
-      INTEGER  :: ic, jc, jn, itime 
-      REAL(wp) :: zdate0
+      INTEGER  :: ji, jj, jk, jn
       REAL(wp), DIMENSION(1) ::  zinfo
-      CHARACTER(len=50) :: clname,cln
-      CHARACTER(len=20) :: cltra 
-      REAL(wp), DIMENSION(:,:) , ALLOCATABLE  :: zdta   
+      CHARACTER(len=50) :: clname
+      CHARACTER(len=20) :: cltra, name1 
+      REAL(wp), DIMENSION(jpoce,jpksed)   :: zdta   
+      REAL(wp), DIMENSION(jpi,jpj,jpksed) :: zdta2
       !! -----------------------------------------------------------------------
 
-      ALLOCATE( zdta(jpoce,jpksed) )
-
-      IF( MOD(kt,nstock) == 0 .OR. kt == nitsedend ) THEN
-         
+      IF( ln_timing )  CALL timing_start('sed_rst_wri')
+
          !! 0. initialisations
          !! ------------------
          
-         IF(lwp) WRITE(numsed,*) ' '
-         IF(lwp) WRITE(numsed,*) 'sed_rst_write : write the sediment restart file in NetCDF format ',   &
+      IF(lwp) WRITE(numsed,*) ' '
+      IF(lwp) WRITE(numsed,*) 'sed_rst_write : write the sediment restart file in NetCDF format ',   &
             'at it= ',kt
-         IF(lwp) WRITE(numsed,*) '~~~~~~~~~'
+      IF(lwp) WRITE(numsed,*) '~~~~~~~~~'
+
+
+      trcsedi(:,:,:,:)   = 0.0
+      flxsedi3d(:,:,:,:) = 0.0
+      zdta(:,:)          = 1.0
+      zdta2(:,:,:)       = 0.0
+
          
-         !! 1. WRITE in nutwrs
-         !! ------------------
-
-         ic = 1
-         DO jc = 1,16
-            IF( cexper(jc:jc) /= ' ') ic = jc
-         END DO
-         WRITE( cln,'("_",i5.5,i2.2,i2.2,"_restart.sed")') nyear, nmonth, nday
-         clname = cexper(1:ic)//cln
-         itime = 0
-         CALL ymds2ju( nyear, nmonth, nday, rdt, zdate0 )
-         zdate0 = zdate0 - adatrj   !   set calendar origin to the beginning of the experiment
-         CALL restini( 'NONE', jpi, jpj, glamt, gphit, jpksed, dz, &
-            &         clname, itime, zdate0, dtsed*nstock, numrsw, domain_id=nidom )
-         zinfo(1) = REAL( kt)
-         CALL restput( numrsw, 'kt', 1,1, 1,0, zinfo  )
-
-
-
-         ! Back to 2D geometry
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,1) , iarroce(1:jpoce), &
-            &                    solcp(1:jpoce,1:jpksed,jsopal ) )
+      !! 1. WRITE in nutwrs
+      !! ------------------
+
+      zinfo(1) = REAL( kt)
+      CALL iom_rstput( kt, nitrst, numrsw, 'kt', zinfo  )
+
+      ! Back to 2D geometry
+      DO jn = 1, jpsol
+         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,jn) , iarroce(1:jpoce), &
+         &                       solcp(1:jpoce,1:jpksed,jn ) )
+      END DO
+
+      DO jn = 1, jpwat
+         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,jpsol+jn) , iarroce(1:jpoce), &
+         &                       pwcp(1:jpoce,1:jpksed,jn  )  )
+      END DO
+      ! pH
+      DO jk = 1, jpksed
+         DO ji = 1, jpoce
+            zdta(ji,jk) = -LOG10( hipor(ji,jk) / ( densSW(ji) + rtrn ) + rtrn )
+         ENDDO
+      ENDDO
+
+      CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,1)  , iarroce(1:jpoce), &
+      &                   zdta(1:jpoce,1:jpksed)  )
          
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,2) , iarroce(1:jpoce), &
-            &                    solcp(1:jpoce,1:jpksed,jsclay ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,3) , iarroce(1:jpoce), &
-            &                    solcp(1:jpoce,1:jpksed,jspoc  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,4) , iarroce(1:jpoce), &
-            &                    solcp(1:jpoce,1:jpksed,jscal  ) )   
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,5) , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwsil  )  )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,6)  , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwoxy  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,7)  , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwdic  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,8)  , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwno3  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,9)  , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwpo4  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,10)  , iarroce(1:jpoce), &
-            &                    pwcp(1:jpoce,1:jpksed,jwalk  ) )
-         
-         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,11)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwc13  ) )
-         
-         ! porosity
-         zdta(:,:) = 0.
-         DO jk = 1, jpksed
-            DO ji = 1, jpoce
-               zdta(ji,jk) = -LOG10( hipor(ji,jk) / densSW(ji) )
-            ENDDO
-         ENDDO
-         CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,1)  , iarroce(1:jpoce), &
-            &                   zdta(1:jpoce,1:jpksed)  )
-         
-         CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,2)  , iarroce(1:jpoce), &
-            &                   co3por(1:jpoce,1:jpksed)  )
-      
-         ! prognostic variables
-         ! --------------------
-
-
-         DO jn = 1, jptrased
-            cltra = sedtrcd(jn)
-            CALL restput( numrsw, cltra, jpi, jpj, jpksed, 0, trcsedi(:,:,:,jn) )
-         ENDDO
-
-         DO jn = 1, 2
-            cltra = seddia3d(jn)
-            CALL restput( numrsw, cltra, jpi, jpj, jpksed, 0, flxsedi3d(:,:,:,jn) )
-         ENDDO
-
-
-         CALL restclo( numrsw )
-
-      ENDIF
-
-      DEALLOCATE( zdta )  
+      CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,2)  , iarroce(1:jpoce), &
+      &                   co3por(1:jpoce,1:jpksed)  )
+
+      ! prognostic variables
+      ! --------------------
+
+      DO jn = 1, jptrased
+         cltra = TRIM(sedtrcd(jn))
+         CALL iom_rstput( kt, nitrst, numrsw, TRIM(cltra), trcsedi(:,:,:,jn) )
+      ENDDO
+
+      DO jn = 1, 2
+         cltra = TRIM(seddia3d(jn))
+         CALL iom_rstput( kt, nitrst, numrsw, TRIM(cltra), flxsedi3d(:,:,:,jn) )
+      ENDDO
+
+      CALL unpack_arr( jpoce, zdta2(1:jpi,1:jpj,1:jpksed)  , iarroce(1:jpoce), &
+      &                   db(1:jpoce,1:jpksed)  )
+
+      cltra = "dbioturb"
+      CALL iom_rstput( kt, nitrst, numrsw, TRIM(cltra), zdta2(:,:,:) )
+
+      CALL unpack_arr( jpoce, zdta2(1:jpi,1:jpj,1:jpksed)  , iarroce(1:jpoce), &
+      &                   irrig(1:jpoce,1:jpksed)  )
+
+      cltra = "irrig"
+      CALL iom_rstput( kt, nitrst, numrsw, TRIM(cltra), zdta2(:,:,:) )
+
+      CALL unpack_arr( jpoce, zdta2(1:jpi,1:jpj,1:jpksed)  , iarroce(1:jpoce), &
+      &                   sedligand(1:jpoce,1:jpksed)  )
+
+      cltra = "sedligand"
+      CALL iom_rstput( kt, nitrst, numrsw, TRIM(cltra), zdta2(:,:,:) )
+
+      IF( kt == nitrst ) THEN
+          CALL iom_close( numrsw )     ! close the restart file (only at last time step)
+          IF( l_offline .AND. ln_rst_list ) THEN
+             nrst_lst = nrst_lst + 1
+             nitrst = nstocklist( nrst_lst )
+          ENDIF
+      ENDIF
+
+      IF( ln_timing )  CALL timing_stop('sed_rst_wri')
          
    END SUBROUTINE sed_rst_wri
-#else
-   !!======================================================================
-   !! MODULE sedrst :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_rst_read                      ! Empty routines
-   END SUBROUTINE sed_rst_read
-   SUBROUTINE sed_rst_wri( kt )
-      INTEGER, INTENT ( in ) :: kt
-      WRITE(*,*) 'sed_rst_wri: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_rst_wri   
-#endif
+
+
+   SUBROUTINE sed_rst_cal( kt, cdrw )
+      !!---------------------------------------------------------------------
+      !!                   ***  ROUTINE sed_rst_cal  ***
+      !!
+      !!  ** Purpose : Read or write calendar in restart file:
+      !!
+      !!  WRITE(READ) mode:
+      !!       kt        : number of time step since the begining of the experiment at the
+      !!                   end of the current(previous) run
+      !!       adatrj(0) : number of elapsed days since the begining of the experiment at the
+      !!                   end of the current(previous) run (REAL -> keep fractions of day)
+      !!       ndastp    : date at the end of the current(previous) run (coded as yyyymmdd integer)
+      !!
+      !!   According to namelist parameter nrstdt,
+      !!       nn_rsttr = 0  no control on the date (nittrc000 is  arbitrary).
+      !!       nn_rsttr = 1  we verify that nittrc000 is equal to the last
+      !!                   time step of previous run + 1.
+      !!       In both those options, the  exact duration of the experiment
+      !!       since the beginning (cumulated duration of all previous restart runs)
+      !!       is not stored in the restart and is assumed to be (nittrc000-1)*rdt.
+      !!       This is valid is the time step has remained constant.
+      !!
+      !!       nn_rsttr = 2  the duration of the experiment in days (adatrj)
+      !!                    has been stored in the restart file.
+      !!----------------------------------------------------------------------
+      INTEGER         , INTENT(in) ::   kt         ! ocean time-step
+      CHARACTER(len=*), INTENT(in) ::   cdrw       ! "READ"/"WRITE" flag
+      !
+      INTEGER  ::  jlibalt = jprstlib
+      LOGICAL  ::  llok
+      REAL(wp) ::  zkt, zrdttrc1
+      REAL(wp) ::  zndastp
+
+      ! Time domain : restart
+      ! ---------------------
+
+      IF( TRIM(cdrw) == 'READ' ) THEN
+
+         IF(lwp) WRITE(numsed,*)
+         IF(lwp) WRITE(numsed,*) 'sed_rst_cal : read the SED restart file for calendar'
+         IF(lwp) WRITE(numsed,*) '~~~~~~~~~~~~'
+
+         IF( ln_rst_sed ) THEN
+            CALL iom_open( TRIM(cn_sedrst_indir)//'/'//cn_sedrst_in, numrsr, kiolib = jlibalt )
+            CALL iom_get ( numrsr, 'kt', zkt )   ! last time-step of previous run
+
+            IF(lwp) THEN
+               WRITE(numsed,*) ' *** Info read in restart : '
+               WRITE(numsed,*) '   previous time-step                               : ', NINT( zkt )
+               WRITE(numsed,*) ' *** restart option'
+               SELECT CASE ( nn_rstsed )
+               CASE ( 0 )   ;   WRITE(numsed,*) ' nn_rstsed = 0 : no control of nittrc000'
+               CASE ( 1 )   ;   WRITE(numsed,*) ' nn_rstsed = 1 : no control the date at nittrc000 (use ndate0 read in the namelist)'
+               CASE ( 2 )   ;   WRITE(numsed,*) ' nn_rstsed = 2 : calendar parameters read in restart'
+               END SELECT
+               WRITE(numsed,*)
+            ENDIF
+            ! Control of date 
+            IF( nittrc000  - NINT( zkt ) /= nn_dtsed .AND.  nn_rstsed /= 0 )                                  &
+               &   CALL ctl_stop( ' ===>>>> : problem with nittrc000 for the restart',                 &
+               &                  ' verify the restart file or rerun with nn_rsttr = 0 (namelist)' )
+         ENDIF
+         !
+         IF( l_offline ) THEN
+            !                                          ! set the date in offline mode
+            IF( ln_rst_sed .AND. nn_rstsed == 2 ) THEN
+               CALL iom_get( numrsr, 'ndastp', zndastp )
+               ndastp = NINT( zndastp )
+               CALL iom_get( numrsr, 'adatrj', adatrj  )
+             ELSE
+               ndastp = ndate0 - 1     ! ndate0 read in the namelist in dom_nam
+               adatrj = ( REAL( nittrc000-1, wp ) * rdt ) / rday
+               ! note this is wrong if time step has changed during run
+            ENDIF
+            !
+            IF(lwp) THEN
+              WRITE(numsed,*) ' *** Info used values : '
+              WRITE(numsed,*) '   date ndastp                                      : ', ndastp
+              WRITE(numsed,*) '   number of elapsed days since the begining of run : ', adatrj
+              WRITE(numsed,*)
+            ENDIF
+            !
+            CALL day_init          ! compute calendar
+            !
+         ENDIF
+         !
+      ELSEIF( TRIM(cdrw) == 'WRITE' ) THEN
+         !
+         IF(  kt == nitrst ) THEN
+            IF(lwp) WRITE(numsed,*)
+            IF(lwp) WRITE(numsed,*) 'trc_wri : write the TOP restart file (NetCDF) at it= ', kt, ' date= ', ndastp
+            IF(lwp) WRITE(numsed,*) '~~~~~~~'
+         ENDIF
+         CALL iom_rstput( kt, nitrst, numrsw, 'kt'     , REAL( kt    , wp) )   ! time-step
+         CALL iom_rstput( kt, nitrst, numrsw, 'ndastp' , REAL( ndastp, wp) )   ! date
+         CALL iom_rstput( kt, nitrst, numrsw, 'adatrj' , adatrj            )   ! number of elapsed days since
+         !                                                                     ! the begining of the run [s]
+      ENDIF
+
+   END SUBROUTINE sed_rst_cal
 
 END MODULE sedrst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedsfc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedsfc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedsfc.F90	(revision 10321)
@@ -4,5 +4,4 @@
    !!    Sediment : Data at sediment surface
    !!=====================================================================
-#if defined key_sed && ! defined key_sed_off
    !! * Modules used
    USE sed     ! sediment global variable
@@ -32,11 +31,7 @@
 
       !------------------------------------------------------------------------
+      ! reading variables
 
-      IF( kt == nitsed000 ) THEN
-         WRITE(numsed,*) ' sed_sfc : Give data from sediment model to tracer model  '
-         WRITE(numsed,*) ' '
-      ENDIF
-
-      ! reading variables
+      IF( ln_timing )  CALL timing_start('sed_sfc')
 
       CALL unpack_arr ( jpoce, trc_data(1:jpi,1:jpj,1), iarroce(1:jpoce), pwcp(1:jpoce,1,jwalk) )
@@ -46,4 +41,6 @@
       CALL unpack_arr ( jpoce, trc_data(1:jpi,1:jpj,5), iarroce(1:jpoce), pwcp(1:jpoce,1,jwoxy) )
       CALL unpack_arr ( jpoce, trc_data(1:jpi,1:jpj,6), iarroce(1:jpoce), pwcp(1:jpoce,1,jwsil) )
+      CALL unpack_arr ( jpoce, trc_data(1:jpi,1:jpj,7), iarroce(1:jpoce), pwcp(1:jpoce,1,jwnh4) )
+      CALL unpack_arr ( jpoce, trc_data(1:jpi,1:jpj,8), iarroce(1:jpoce), pwcp(1:jpoce,1,jwfe2) )
 
 
@@ -52,27 +49,19 @@
             ikt = mbkt(ji,jj)
             IF ( tmask(ji,jj,ikt) == 1 ) THEN
-               trn(ji,jj,ikt,jptal) = trc_data(ji,jj,1)
-               trn(ji,jj,ikt,jpdic) = trc_data(ji,jj,2)
-               trn(ji,jj,ikt,jpno3) = trc_data(ji,jj,3) * 7.6
-               trn(ji,jj,ikt,jppo4) = trc_data(ji,jj,4) * 122.
-               trn(ji,jj,ikt,jpoxy) = trc_data(ji,jj,5)
-               trn(ji,jj,ikt,jpsil) = trc_data(ji,jj,6)
+               trb(ji,jj,ikt,jptal) = trc_data(ji,jj,1)
+               trb(ji,jj,ikt,jpdic) = trc_data(ji,jj,2)
+               trb(ji,jj,ikt,jpno3) = trc_data(ji,jj,3) * 7.625
+               trb(ji,jj,ikt,jppo4) = trc_data(ji,jj,4) * 122.
+               trb(ji,jj,ikt,jpoxy) = trc_data(ji,jj,5)
+               trb(ji,jj,ikt,jpsil) = trc_data(ji,jj,6)
+               trb(ji,jj,ikt,jpnh4) = trc_data(ji,jj,7) * 7.625
+               trb(ji,jj,ikt,jpfer) = trc_data(ji,jj,8)
             ENDIF
          ENDDO
       ENDDO
 
+      IF( ln_timing )  CALL timing_stop('sed_sfc')
+
    END SUBROUTINE sed_sfc
 
-#else
-   !!======================================================================
-   !! MODULE sedsfc  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_sfc ( kt )
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_sfc: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_sfc
-#endif
-
 END MODULE sedsfc
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedstp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedstp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedstp.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedstp
-#if defined key_sed
    !!======================================================================
    !!                       ***  MODULE sedstp   ***
@@ -9,5 +8,6 @@
    USE sedchem  ! chemical constant
    USE sedco3   ! carbonate in sediment pore water
-   USE seddsr   ! dissolution reaction
+   USE sedorg   ! Organic reactions and diffusion
+   USE sedinorg ! Inorganic dissolution
    USE sedbtb   ! bioturbation
    USE sedadv   ! vertical advection
@@ -16,4 +16,7 @@
    USE sedrst   ! restart
    USE sedwri   ! outputs
+   USE trcdmp_sed
+   USE lib_mpp         ! distribued memory computing library
+   USE iom
 
    IMPLICIT NONE
@@ -42,38 +45,53 @@
       !!----------------------------------------------------------------------
       INTEGER, INTENT(in) ::   kt       ! number of iteration
+      INTEGER :: ji,jk,js,jn,jw
+      !!----------------------------------------------------------------------
+      IF( ln_timing )      CALL timing_start('sed_stp')
+        !
+                                CALL sed_rst_opn  ( kt )       ! Open tracer restart file 
+      IF( lrst_sed )            CALL sed_rst_cal  ( kt, 'WRITE' )   ! calenda
 
-      !!----------------------------------------------------------------------
+      IF(ln_sediment_offline)   CALL trc_dmp_sed  ( kt )
 
-      IF( kt /= nitsed000 )  THEN
-        CALL sed_dta( kt )       ! Load  Data for bot. wat. Chem and fluxes
-        CALL sed_chem( kt )      ! update of chemical constant to account for salinity, temperature changes
+      dtsed  = r2dttrc
+!      dtsed2 = dtsed
+      IF (kt /= nitsed000) THEN
+         CALL sed_dta( kt )       ! Load  Data for bot. wat. Chem and fluxes
       ENDIF
-      CALL sed_dsr( kt )         ! Dissolution reaction
-      CALL sed_adv( kt )         ! advection
-      CALL sed_btb( kt )         ! Bioturbation
 
-      IF ( ( MOD( kt, nwrised ) == 0 ) .OR. ( MOD( kt, nstock ) == 0 ) .OR. ( kt == nitsedend )  )   &
-      CALL sed_co3( kt )         ! pH actualization for saving
-      CALL sed_mbc( kt )         ! cumulation for mass balance calculation
-#if ! defined key_sed_off
-      CALL sed_sfc( kt )         ! Give back new bottom wat chem to tracer model
-#endif
-      CALL sed_rst_wri( kt )   ! restart file output
+      IF (sedmask == 1. ) THEN
+         IF( kt /= nitsed000 )  THEN
+           CALL sed_chem( kt )      ! update of chemical constant to account for salinity, temperature changes
+         ENDIF
+
+         CALL sed_btb( kt )         ! 1st pass of bioturbation at t+1/2
+         CALL sed_org( kt )         ! Organic related reactions and diffusion
+         CALL sed_inorg( kt )       ! Dissolution reaction
+         CALL sed_btb( kt )         ! 2nd pass of bioturbation at t+1
+         tokbot(:,:) = 0.0
+         DO jw = 1, jpwat
+            DO ji = 1, jpoce
+               tokbot(ji,jw) = pwcp(ji,1,jw) * 1.e-3 * dzkbot(ji)
+            END DO
+         ENDDO
+         CALL sed_adv( kt )         ! advection
+         CALL sed_co3( kt )         ! pH actualization for saving
+         ! This routine is commented out since it does not work at all
+         CALL sed_mbc( kt )         ! cumulation for mass balance calculation
+
+         IF (ln_sed_2way) CALL sed_sfc( kt )         ! Give back new bottom wat chem to tracer model
+      ENDIF
       CALL sed_wri( kt )         ! outputs
+      IF( kt == nitsed000 ) THEN
+          CALL iom_close( numrsr )       ! close input tracer restart file
+!          IF(lwm) CALL FLUSH( numont )   ! flush namelist output
+      ENDIF
+      IF( lrst_sed )            CALL sed_rst_wri( kt )   ! restart file output
 
       IF( kt == nitsedend )  CLOSE( numsed )
 
+      IF( ln_timing )   CALL timing_stop('sed_stp')
+
    END SUBROUTINE sed_stp
 
-#else
-   !!======================================================================
-   !! MODULE sedstp  :   Dummy module 
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_stp( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_stp: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_stp
-#endif
 END MODULE sedstp
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedwri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedwri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/sedwri.F90	(revision 10321)
@@ -1,4 +1,3 @@
 MODULE sedwri
-#if defined key_sed
    !!======================================================================
    !!                     ***  MODULE  sedwri  ***
@@ -7,6 +6,6 @@
    USE sed
    USE sedarr
-   USE ioipsl
-   USE dianam    ! build name of file (routine)
+   USE lib_mpp         ! distribued memory computing library
+   USE iom
 
    IMPLICIT NONE
@@ -15,13 +14,4 @@
    !! * Accessibility
    PUBLIC sed_wri 
-
-   INTEGER  :: nised
-   INTEGER  :: nhorised
-   INTEGER  :: ndimt52
-   INTEGER  :: ndimt51
-   INTEGER  :: ndepsed
-   REAL(wp) :: zjulian
-   INTEGER, ALLOCATABLE, SAVE, DIMENSION(:) :: ndext52  
-   INTEGER, ALLOCATABLE, SAVE, DIMENSION(:) :: ndext51
 
    !! $Id$
@@ -43,10 +33,7 @@
       INTEGER, INTENT(in) :: kt
 
-      CHARACTER(len = 60)  ::  clhstnam, clop
-      INTEGER  :: ji, jk, js, jw, jn
-      REAL(wp) :: zsto,zout, zdt
-      INTEGER  :: iimi, iima, ijmi, ijma,ipk, it, itmod
-      CHARACTER(len = 20)  ::  cltra , cltrau
-      CHARACTER(len = 80)  ::  cltral
+      INTEGER  :: ji, jj, jk, js, jw, jn
+      INTEGER  :: it
+      CHARACTER(len = 20)  ::  cltra 
       REAL(wp)  :: zrate
       REAL(wp), ALLOCATABLE, DIMENSION(:,:) :: zdta, zflx
@@ -57,81 +44,42 @@
       ! Initialisation
       ! ----------------- 
-      IF( kt == nittrc000 )   ALLOCATE( ndext52(jpij*jpksed), ndext51(jpij) )
-
-      ! Define frequency of output and means
-      zdt = dtsed
-      IF( ln_mskland )   THEN   ;   clop = "only(x)"   ! put 1.e+20 on land (very expensive!!)
-      ELSE                      ;   clop = "x"         ! no use of the mask value (require less cpu time)
-      ENDIF
-#if defined key_diainstant
-      zsto = nwrised * zdt
-      clop = "inst("//TRIM(clop)//")"
-#else
-      zsto = zdt
-      clop = "ave("//TRIM(clop)//")"
-#endif
-      zout = nwrised * zdt
-
-      ! Define indices of the horizontal output zoom and vertical limit storage
-      iimi = 1      ;      iima = jpi
-      ijmi = 1      ;      ijma = jpj
-      ipk = jpksed
-
-      ! define time axis
-      it = kt
-      itmod = kt - nitsed000 + 1
-
 
       ! 1.  Initilisations
       ! -----------------------------------------------------------------
-      WRITE(numsed,*) ' '
-      WRITE(numsed,*) 'sed_wri kt = ', kt
-      WRITE(numsed,*) ' '
+      IF( ln_timing )  CALL timing_start('sed_wri')
+!
+      IF (lwp) WRITE(numsed,*) ' '
+      IF (lwp) WRITE(numsed,*) 'sed_wri kt = ', kt
+      IF (lwp) WRITE(numsed,*) ' '
       
       ALLOCATE( zdta(jpoce,jpksed) )    ;   ALLOCATE( zflx(jpoce,jpwatp1) )
 
+      ! Initialize variables
+      ! --------------------
+
+      trcsedi(:,:,:,:)   = 0.0
+      flxsedi3d(:,:,:,:) = 0.0
+      flxsedi2d(:,:,:)   = 0.0
 
       ! 2.  Back to 2D geometry
       ! -----------------------------------------------------------------
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,1) , iarroce(1:jpoce), &
-         &                    solcp(1:jpoce,1:jpksed,jsopal ) )
+      DO jn = 1, jpsol
+         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,jn) , iarroce(1:jpoce), &
+         &                       solcp(1:jpoce,1:jpksed,jn ) )
+      END DO
       
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,2) , iarroce(1:jpoce), &
-         &                    solcp(1:jpoce,1:jpksed,jsclay ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,3) , iarroce(1:jpoce), &
-         &                    solcp(1:jpoce,1:jpksed,jspoc  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,4) , iarroce(1:jpoce), &
-         &                    solcp(1:jpoce,1:jpksed,jscal  ) )   
-            
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,5) , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwsil  )  )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,6)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwoxy  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,7)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwdic  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,8)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwno3  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,9)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwpo4  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,10)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwalk  ) )
-      
-      CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,11)  , iarroce(1:jpoce), &
-         &                    pwcp(1:jpoce,1:jpksed,jwc13  ) )
-      
+      DO jn = 1, jpwat
+         CALL unpack_arr( jpoce, trcsedi(1:jpi,1:jpj,1:jpksed,jpsol + jn) , iarroce(1:jpoce), &
+         &                       pwcp(1:jpoce,1:jpksed,jn  )  )
+      END DO      
+
       ! porosity
       zdta(:,:) = 0.
       DO jk = 1, jpksed
          DO ji = 1, jpoce
-            zdta(ji,jk) = -LOG10( hipor(ji,jk) / densSW(ji) )
+            zdta(ji,jk) = -LOG10( hipor(ji,jk) / ( densSW(ji) + rtrn ) + rtrn )
          ENDDO
       ENDDO
+
       CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,1)  , iarroce(1:jpoce), &
          &                   zdta(1:jpoce,1:jpksed)  )
@@ -140,17 +88,5 @@
          &                   co3por(1:jpoce,1:jpksed)  )
       
-      
-      ! computation of delta 13C
-      zdta(:,:) = 0.
-      DO jk = 1, jpksed
-         DO ji = 1, jpoce
-            zdta(ji,jk) = ( ( pwcp(ji,jk,jwc13) / pwcp(ji,jk,jwdic) / pdb ) - 1. ) &
-               &              * 1000.
-         ENDDO
-      ENDDO
-      CALL unpack_arr( jpoce, flxsedi3d(1:jpi,1:jpj,1:jpksed,3)  , iarroce(1:jpoce), &
-         &                   zdta(1:jpoce,1:jpksed)  )
-      
- 
+!      flxsedi3d = 0.
       zflx(:,:) = 0.    
       ! Calculation of fluxes mol/cm2/s
@@ -158,10 +94,11 @@
          DO ji = 1, jpoce
             zflx(ji,jw) = ( pwcp(ji,1,jw) - pwcp_dta(ji,jw) ) &
-               &         * 1.e-3 * dzkbot(ji) / dtsed
+               &         * 1.e3 / 1.e2 * dzkbot(ji) / r2dttrc
          ENDDO
       ENDDO
+
       ! Calculation of accumulation rate per dt
       DO js = 1, jpsol
-         zrate =  mol_wgt(js) / ( dens * por1(jpksed) ) / dtsed
+         zrate =  1.0 / ( denssol * por1(jpksed) ) / r2dttrc
          DO ji = 1, jpoce
             zflx(ji,jpwatp1) = zflx(ji,jpwatp1) + ( tosed(ji,js) - fromsed(ji,js) ) * zrate
@@ -169,67 +106,9 @@
       ENDDO
 
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,1), iarroce(1:jpoce), zflx(1:jpoce,1)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,2), iarroce(1:jpoce), zflx(1:jpoce,2)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,3), iarroce(1:jpoce), zflx(1:jpoce,3)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,4), iarroce(1:jpoce), zflx(1:jpoce,4)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,5), iarroce(1:jpoce), zflx(1:jpoce,5)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,6), iarroce(1:jpoce), zflx(1:jpoce,6)  )
-      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,7), iarroce(1:jpoce), zflx(1:jpoce,8)  )
-
-
-      ! 3. Define NETCDF files and fields at beginning of first time step
-      ! -----------------------------------------------------------------
-
-      IF( kt == nitsed000 ) THEN
-
-         ! Define the NETCDF files        
-         CALL ymds2ju ( nyear, nmonth, nday, rdt, zjulian )
-         zjulian = zjulian - adatrj   !   set calendar origin to the beginning of the experiment
-         CALL dia_nam ( clhstnam, nwrised, 'sed_T' )
-         CALL histbeg ( clhstnam, jpi, glamt, jpj, gphit,     &
-            &             iimi, iima-iimi+1, ijmi, ijma-ijmi+1,         &
-            &             nitsed000-1, zjulian, zdt,  nhorised, nised , domain_id=nidom, snc4chunks=snc4set )
-         CALL histvert( nised,'deptht','Vertic.sed.T levels','m',ipk, profsed, ndepsed, 'down' )
-         CALL wheneq  ( jpi*jpj*ipk, tmasksed, 1, 1., ndext52, ndimt52 )
-         CALL wheneq  ( jpi*jpj, tmasksed(:,:,1), 1, 1., ndext51, ndimt51 )
-
-         ! Declare all the output fields as NETCDF variables
-
-         DO jn = 1, jptrased
-            cltra  = sedtrcd(jn)   ! short title for sediment variable
-            cltral = sedtrcl(jn)   ! long title for  sediment variable
-            cltrau = sedtrcu(jn)   ! unit for  sediment variable
-
-            CALL histdef( nised, cltra,cltral,cltrau, jpi, jpj, nhorised, &
-               &          ipk, 1, ipk, ndepsed, 32, clop, zsto, zout )
-         ENDDO
-
-         ! 3D diagnostic
-         DO jn = 1, jpdia3dsed
-            cltra  = seddia3d(jn)   ! short title for 3D diagnostic
-            cltral = seddia3l(jn)   ! long title for 3D diagnostic
-            cltrau = seddia3u(jn)   ! UNIT for 3D diagnostic
-
-            CALL histdef( nised, cltra,cltral,cltrau, jpi, jpj, nhorised, &
-               &          ipk, 1, ipk, ndepsed, 32, clop, zsto, zout  )
-         ENDDO
-
-         ! Fluxes
-         DO jn = 1, jpdia2dsed
-            cltra  = seddia2d(jn)   ! short title for 2D diagnostic
-            cltral = seddia2l(jn)   ! long title for 2D diagnostic
-            cltrau = seddia2u(jn)   ! UNIT for 2D diagnostic
-            
-            CALL histdef( nised, cltra,cltral,cltrau, jpi, jpj, nhorised, &
-               &          1, 1, 1, -99, 32, clop, zsto, zout )
-         ENDDO
-
-
-         CALL histend( nised, snc4set )
-
-         WRITE(numsed,*)
-         WRITE(numsed,*) 'End of NetCDF sediment output file Initialization'
-
-       ENDIF
+      DO jn = 1, jpdia2dsed - 1 
+         CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,jn), iarroce(1:jpoce), zflx(1:jpoce,jn)  )
+      END DO
+      zflx(:,1) = dzdep(:) / dtsed
+      CALL unpack_arr( jpoce, flxsedi2d(1:jpi,1:jpj,jpdia2dsed), iarroce(1:jpoce), zflx(1:jpoce,1) )
 
        ! Start writing data
@@ -237,41 +116,23 @@
        DO jn = 1, jptrased
           cltra = sedtrcd(jn) ! short title for 3D diagnostic
-          CALL histwrite( nised, cltra, it, trcsedi(:,:,:,jn), ndimt52, ndext52 )
+          CALL iom_put( cltra, trcsedi(:,:,:,jn) )
        END DO
 
        DO jn = 1, jpdia3dsed
           cltra = seddia3d(jn) ! short title for 3D diagnostic
-          CALL histwrite( nised, cltra, it, flxsedi3d(:,:,:,jn), ndimt52, ndext52 )
+          CALL iom_put( cltra, flxsedi3d(:,:,:,jn) )
        END DO
 
        DO jn = 1, jpdia2dsed
-             cltra = seddia2d(jn) ! short title for 2D diagnostic
-             CALL histwrite( nised, cltra, it, flxsedi2d(:,:,jn  ), ndimt51, ndext51 )
+          cltra = seddia2d(jn) ! short title for 2D diagnostic
+          CALL iom_put( cltra, flxsedi2d(:,:,jn) )
        END DO
 
 
-      ! 3. Closing all files
-      ! --------------------
-      IF( kt == nitsedend  ) THEN
-          CALL histclo( nised )
-      ENDIF
+      DEALLOCATE( zdta )    ;   DEALLOCATE( zflx )
 
-      DEALLOCATE( zdta )    ;   DEALLOCATE( zflx )
+      IF( ln_timing )  CALL timing_stop('sed_wri')
 
    END SUBROUTINE sed_wri
 
-#else
-   !!======================================================================
-   !! MODULE sedwri  :   Dummy module
-   !!======================================================================
-   !! $Id$
-CONTAINS
-   SUBROUTINE sed_wri( kt )         ! Empty routine
-      INTEGER, INTENT(in) :: kt
-      WRITE(*,*) 'sed_adv: You should not have seen this print! error?', kt
-   END SUBROUTINE sed_wri
-
-   !!======================================================================
-#endif
-
 END MODULE sedwri
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/trcdmp_sed.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/trcdmp_sed.F90	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/SED/trcdmp_sed.F90	(revision 10321)
@@ -0,0 +1,157 @@
+MODULE trcdmp_sed
+   !!======================================================================
+   !!                       ***  MODULE  trcdmp  ***
+   !! Ocean physics: internal restoring trend on passive tracers
+   !!======================================================================
+   !! History :  OPA  !  1991-03  (O. Marti, G. Madec)  Original code
+   !!                 !  1996-01  (G. Madec) statement function for e3
+   !!                 !  1997-05  (H. Loukos)  adapted for passive tracers
+   !!    NEMO    9.0  !  2004-03  (C. Ethe)    free form + modules
+   !!            3.2  !  2007-02  (C. Deltel)  Diagnose ML trends for passive tracers
+   !!            3.3  !  2010-06  (C. Ethe, G. Madec) merge TRA-TRC 
+   !!----------------------------------------------------------------------
+#if  defined key_top
+   !!----------------------------------------------------------------------
+   !!   trc_dmp      : update the tracer trend with the internal damping
+   !!   trc_dmp_init : initialization, namlist read, parameters control
+   !!----------------------------------------------------------------------
+   USE oce_trc         ! ocean dynamics and tracers variables
+   USE trc             ! ocean passive tracers variables
+   USE sed , ONLY : dtsed => dtsed      ! ocean dynamics and tracers variables
+   USE trc             ! ocean passive tracers variables
+   USE trcdta
+   USE prtctl_trc      ! Print control for debbuging
+   USE iom
+
+
+   IMPLICIT NONE
+   PRIVATE
+
+   PUBLIC trc_dmp_sed      
+   PUBLIC trc_dmp_sed_alloc  
+   PUBLIC trc_dmp_sed_ini    
+
+   REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   restosed   ! restoring coeff. on tracers (s-1)
+
+   !! * Substitutions
+#  include "vectopt_loop_substitute.h90"
+   !!----------------------------------------------------------------------
+   !! NEMO/TOP 3.3 , NEMO Consortium (2010)
+   !! $Id$
+   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !!----------------------------------------------------------------------
+CONTAINS
+
+   INTEGER FUNCTION trc_dmp_sed_alloc()
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE trc_dmp_alloc  ***
+      !!----------------------------------------------------------------------
+      ALLOCATE( restosed(jpi,jpj,jpk) , STAT=trc_dmp_sed_alloc )
+      !
+      IF( trc_dmp_sed_alloc /= 0 )   CALL ctl_warn('trc_dmp_sed_alloc: failed to allocate array')
+      !
+   END FUNCTION trc_dmp_sed_alloc
+
+
+   SUBROUTINE trc_dmp_sed( kt )
+      !!----------------------------------------------------------------------
+      !!                   ***  ROUTINE trc_dmp_sed  ***
+      !!                  
+      !! ** Purpose :   Compute the passive tracer trend due to a newtonian damping
+      !!      of the tracer field towards given data field and add it to the
+      !!      general tracer trends.
+      !!
+      !! ** Method  :   Newtonian damping towards trdta computed 
+      !!      and add to the general tracer trends:
+      !!                     trn = tra + restotr * (trdta - trb)
+      !!         The trend is computed either throughout the water column
+      !!      (nlmdmptr=0) or in area of weak vertical mixing (nlmdmptr=1) or
+      !!      below the well mixed layer (nlmdmptr=2)
+      !!
+      !! ** Action  : - update the tracer trends tra with the newtonian 
+      !!                damping trends.
+      !!              - save the trends ('key_trdmxl_trc')
+      !!----------------------------------------------------------------------
+      INTEGER, INTENT(in) ::   kt   ! ocean time-step index
+      !
+      INTEGER ::   ji, jj, jk, jn, jl, ikt   ! dummy loop indices
+      CHARACTER (len=22) ::   charout
+      REAL(wp), DIMENSION(jpi,jpj,jpk) ::   ztrcdta   ! 3D  workspace
+      !!----------------------------------------------------------------------
+      !
+      IF( ln_timing )  CALL timing_start('trc_dmp_sed')
+      !
+      !
+      IF( nb_trcdta > 0 ) THEN  ! Initialisation of tracer from a file that may also be used for damping
+         !
+         DO jn = 1, jptra                                           ! tracer loop
+            !                                                       ! ===========
+            IF( ln_trc_ini(jn) ) THEN      ! update passive tracers arrays with input data read from file
+               !
+               jl = n_trc_index(jn) 
+               CALL trc_dta( kt, sf_trcdta(jl), rf_trfac(jl), ztrcdta )   ! read tracer data at nit000
+               !
+               DO jj = 1, jpj
+                  DO ji = 1, jpi   ! vector opt.
+                     ikt = mbkt(ji,jj)
+                     trb(ji,jj,ikt,jn) = ztrcdta(ji,jj,ikt) + ( trb(ji,jj,ikt,jn) -  ztrcdta(ji,jj,ikt) )     &
+                     &                  * exp( -restosed(ji,jj,ikt) * dtsed )
+                  END DO
+               END DO
+               ! 
+            ENDIF
+         END DO                                                     ! tracer loop
+         !                                                          ! ===========
+      ENDIF
+      !
+      !                                          ! print mean trends (used for debugging)
+      IF( ln_ctl ) THEN
+         WRITE(charout, FMT="('dmp ')")
+         CALL prt_ctl_trc_info(charout)
+         CALL prt_ctl_trc( tab4d=tra, mask=tmask, clinfo=ctrcnm, clinfo2='trd' )
+      ENDIF
+      !
+      IF( ln_timing )  CALL timing_stop('trc_dmp_sed')
+      !
+   END SUBROUTINE trc_dmp_sed
+
+
+   SUBROUTINE trc_dmp_sed_ini
+      !!----------------------------------------------------------------------
+      !!                  ***  ROUTINE trc_dmp_ini  ***
+      !! 
+      !! ** Purpose :   Initialization for the newtonian damping 
+      !!
+      !! ** Method  :   read the nammbf namelist and check the parameters
+      !!              called by trc_dmp at the first timestep (nittrc000)
+      !!----------------------------------------------------------------------
+      !!----------------------------------------------------------------------
+      !
+      IF( ln_timing )  CALL timing_start('trc_dmp_sed_ini')
+
+      IF (lwp) WRITE(numout,*) '   tracer damping throughout the water column'
+      !
+      IF( trc_dmp_sed_alloc() /= 0 )   CALL ctl_stop( 'STOP', 'trc_dmp_sed_ini: unable to allocate arrays' )
+      !
+      IF( .NOT.lk_c1d ) THEN
+         !Read in mask from file
+          restosed(:,:,:) = 0.5 / rday
+         !
+      ENDIF
+      IF( ln_timing )  CALL timing_stop('trc_dmp_sed_ini')
+     !
+   END SUBROUTINE trc_dmp_sed_ini
+
+#else
+   !!----------------------------------------------------------------------
+   !!  Dummy module :                                     No passive tracer
+   !!----------------------------------------------------------------------
+CONTAINS
+   SUBROUTINE trc_dmp_sed( kt )        ! Empty routine
+      INTEGER, INTENT(in) :: kt
+      WRITE(*,*) 'trc_dmp_sed: You should not have seen this print! error?', kt
+   END SUBROUTINE trc_dmp_sed
+#endif
+
+   !!======================================================================
+END MODULE trcdmp_sed
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/par_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/par_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/par_pisces.F90	(revision 10321)
@@ -65,7 +65,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE par_pisces
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/sms_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/sms_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/sms_pisces.F90	(revision 10321)
@@ -24,4 +24,5 @@
    LOGICAL  ::  ln_p5z            !: Flag to use PISCES  quota model
    LOGICAL  ::  ln_ligand         !: Flag to enable organic ligands
+   LOGICAL  ::  ln_sediment       !: Flag to enable sediment module
 
    !!*  Time variables
@@ -123,14 +124,8 @@
    REAL(wp), ALLOCATABLE, SAVE, DIMENSION(:,:,:) ::   tgfunc2   !: Temp. dependancy of mesozooplankton rates
 
-#if defined key_sed
-   LOGICAL, PUBLIC, PARAMETER ::   lk_sed = .TRUE.     !: sediment flag
-#else
-   LOGICAL, PUBLIC, PARAMETER ::   lk_sed = .FALSE.     !: sediment flag
-#endif
-
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcice_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcice_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcice_pisces.F90	(revision 10321)
@@ -23,5 +23,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -273,5 +273,5 @@
             WHERE( gphit(:,:) <  0._wp ) ; trc_o(:,:,jn) = zpisc(jn,3) ; END WHERE ! Antarctic 
          ENDIF
-         IF( cn_cfg == "orca" ) THEN     !  Baltic Sea particular case for ORCA configurations
+         IF( cn_cfg == "orca" .OR. cn_cfg == "ORCA" ) THEN     !  Baltic Sea particular case for ORCA configurations
              WHERE( 14._wp <= glamt(:,:) .AND. glamt(:,:) <= 32._wp .AND.    &
                     54._wp <= gphit(:,:) .AND. gphit(:,:) <= 66._wp )
@@ -312,5 +312,5 @@
        
          !-- Baltic
-         IF( cn_cfg == "orca" ) THEN  ! Baltic treated seperately for ORCA configs
+         IF( cn_cfg == "orca" .OR. cn_cfg == "ORCA" ) THEN     
             IF ( trc_ice_ratio(jn) >= - 1._wp ) THEN ! no prescribed conc. ; typically everything but iron) 
                WHERE( 14._wp <= glamt(:,:) .AND. glamt(:,:) <= 32._wp .AND.    &
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcini_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcini_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcini_pisces.F90	(revision 10321)
@@ -18,4 +18,5 @@
    USE trcnam_pisces   !  PISCES namelist
    USE sms_pisces      !  PISCES Source Minus Sink variables
+   USE sedini          !  SEDIMENTS initialization routine
 
    IMPLICIT NONE
@@ -25,7 +26,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -61,5 +62,5 @@
       USE p4zrem          !  Remineralisation of organic matter
       USE p4zflx          !  Gas exchange
-      USE p4zice          !  Co-limitations of differents nutrients
+      USE p4zlim          !  Co-limitations of differents nutrients
       USE p4zprod         !  Growth rate of the 2 phyto groups
       USE p4zmicro        !  Sources and sinks of microzooplankton
@@ -70,5 +71,5 @@
       USE p4zpoc          !  Remineralization of organic particles
       USE p4zligand       !  Remineralization of organic ligands
-      USE p5zice          !  Co-limitations of differents nutrients
+      USE p5zlim          !  Co-limitations of differents nutrients
       USE p5zprod         !  Growth rate of the 2 phyto groups
       USE p5zmicro        !  Sources and sinks of microzooplankton
@@ -269,4 +270,11 @@
         & CALL p4z_flx_init      !  gas exchange 
 
+      ! Initialization of the sediment model
+      IF( ln_sediment) THEN
+         CALL sed_init
+      ELSE
+         ALLOCATE( profsed(2) )
+      ENDIF
+
       IF(lwp) WRITE(numout,*) 
       IF(lwp) WRITE(numout,*) '   ==>>>   Initialization of PISCES tracers done'
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcnam_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcnam_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcnam_pisces.F90	(revision 10321)
@@ -24,7 +24,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -43,5 +43,5 @@
       CHARACTER(LEN=20)::   clname
       !!
-      NAMELIST/nampismod/ln_p2z, ln_p4z, ln_p5z, ln_ligand
+      NAMELIST/nampismod/ln_p2z, ln_p4z, ln_p5z, ln_ligand, ln_sediment
       !!----------------------------------------------------------------------
 
@@ -65,16 +65,18 @@
       IF(lwp) THEN                  ! control print
          WRITE(numout,*) '   Namelist : nampismod '
-         WRITE(numout,*) '      Flag to use LOBSTER model            ln_p2z    = ', ln_p2z
-         WRITE(numout,*) '      Flag to use PISCES standard model    ln_p4z    = ', ln_p4z
-         WRITE(numout,*) '      Flag to use PISCES quota    model    ln_p5z    = ', ln_p5z
-         WRITE(numout,*) '      Flag to ligand                       ln_ligand = ', ln_ligand
+         WRITE(numout,*) '      Flag to use LOBSTER model            ln_p2z      = ', ln_p2z
+         WRITE(numout,*) '      Flag to use PISCES standard model    ln_p4z      = ', ln_p4z
+         WRITE(numout,*) '      Flag to use PISCES quota    model    ln_p5z      = ', ln_p5z
+         WRITE(numout,*) '      Flag to ligand                       ln_ligand   = ', ln_ligand
+         WRITE(numout,*) '      Flag to use sediment                 ln_sediment = ', ln_sediment
       ENDIF
       !
       IF(lwp) THEN                         ! control print
          WRITE(numout,*)
-         IF( ln_p5z    )  WRITE(numout,*) '   ==>>>   PISCES QUOTA model is used'
-         IF( ln_p4z    )  WRITE(numout,*) '   ==>>>   PISCES STANDARD model is used'
-         IF( ln_p2z    )  WRITE(numout,*) '   ==>>>   LOBSTER model is used'
+         IF( ln_p5z      )  WRITE(numout,*) '   ==>>>   PISCES QUOTA model is used'
+         IF( ln_p4z      )  WRITE(numout,*) '   ==>>>   PISCES STANDARD model is used'
+         IF( ln_p2z      )  WRITE(numout,*) '   ==>>>   LOBSTER model is used'
          IF( ln_ligand )  WRITE(numout,*) '   ==>>>   Compute remineralization/dissolution of organic ligands'
+         IF( ln_sediment )  WRITE(numout,*) '   ==>>>   Sediment module is used'
       ENDIF
     
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcsms_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcsms_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcsms_pisces.F90	(revision 10321)
@@ -19,7 +19,7 @@
    PUBLIC   trc_sms_pisces    ! called in trcsms.F90
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcwri_pisces.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcwri_pisces.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/PISCES/trcwri_pisces.F90	(revision 10321)
@@ -20,7 +20,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -97,7 +97,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcwri_pisces
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/README.rst	(revision 10321)
@@ -0,0 +1,362 @@
+*********************
+Oceanic tracers (TOP)
+*********************
+
+.. contents::
+	:local:
+
+TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and
+provide the physical constraints/boundaries for oceanic tracers.
+It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules.
+
+This component of the NEMO framework allows one to exploit available modules (see below) and
+further develop a range of applications, spanning from the implementation of a dye passive tracer to
+evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module),
+assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs),
+up to the full set of equations involving marine biogeochemical cycles.
+
+Structure
+=========
+
+TOP interface has the following location in the source code ``./src/MBG/`` and
+the following modules are available:
+
+``TRP``
+	Interface to NEMO physical core for computing tracers transport
+
+``CFC``
+	Inert carbon tracers (CFC11,CFC12, SF6)
+
+``C14``
+	Radiocarbon passive tracer
+
+``AGE``
+	Water age tracking
+
+``MY_TRC``
+	Template for creation of new modules and external BGC models coupling
+
+``PISCES``
+	Built in BGC model.
+	See [https://www.geosci-model-dev.net/8/2465/2015/gmd-8-2465-2015-discussion.html Aumont et al. (2015)] for
+	a throughout description. |
+
+The usage of TOP is activated i) by including in the configuration definition  the component ``MBG`` and
+ii) by adding the macro ``key_top`` in the configuration CPP file
+(see for more details [http://forge.ipsl.jussieu.fr/nemo/wiki/Users "Learn more about the model"]).
+
+As an example, the user can refer to already available configurations in the code,
+``GYRE_PISCES`` being the NEMO biogeochemical demonstrator and
+``GYRE_BFM`` to see the required configuration elements to couple with an external biogeochemical model
+(see also Section 4) .
+
+Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and
+all submodules preprocessing macros from previous versions were removed.
+
+Here below the list of preprocessing keys that applies to the TOP interface (beside ``key_top``):
+
+``key_iomput``
+	use XIOS I/O
+
+``key_zdfddm`` & ``key_zdftke`` & ``key_zdfgls``
+	vertical schemes (need to be updated after Merge2017 finalization)
+
+``key_trabbl``
+	bottom boundary layer parameterization
+
+``key_agrif``
+	enable AGRIF coupling
+
+``key_trdtrc`` & ``key_trdmxl_trc``
+	trend computation for tracers
+
+Synthetic Workflow
+==================
+
+A synthetic description of the TOP interface workflow is given below to summarize the steps involved in
+the computation of biogeochemical and physical trends and their time integration and outputs,
+by reporting also the principal Fortran subroutine herein involved.
+
+**Model initialization (OPA_SRC/nemogcm.F90)**
+
+call to trc_init (trcini.F90)
+
+  ↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting
+
+  ↳ call trc_ini_sms, to initialize each submodule
+
+  ↳ call trc_ini_trp, to initialize transport for tracers
+
+  ↳ call trc_ice_ini, to initialize tracers in seaice
+
+  ↳ call trc_ini_state, read passive tracers from a restart or input data
+
+  ↳ call trc_sub_ini, setup substepping if {{{nn_dttrc /= 1}}}
+
+**Time marching procedure (OPA_SRC/stp.F90)**
+
+call to trc_stp.F90 (trcstp.F90)
+
+  ↳ call trc_sub_stp, averaging physical variables for sub-stepping
+
+  ↳ call trc_wri, call XIOS for output of data
+
+  ↳ call trc_sms, compute BGC trends for each submodule
+
+    ↳ call trc_sms_my_trc, includes also surface and coastal BCs trends
+
+  ↳ call trc_trp (TRP/trctrp.F90), compute physical trends
+
+    ↳ call trc_sbc, get trend due to surface concentration/dilution
+
+    ↳ call trc_adv, compute tracers advection
+
+    ↳ call to trc_ldf, compute tracers lateral diffusion
+
+    ↳ call to trc_zdf, vertical mixing and after tracer fields
+
+    ↳ call to trc_nxt, tracer fields at next time step. Lateral Boundary Conditions are solved in here.
+
+    ↳ call to trc_rad, Correct artificial negative concentrations
+
+  ↳ call trc_rst_wri, output tracers restart files
+
+Namelists walkthrough
+=====================
+
+namelist_top
+------------
+
+Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and
+modifiable by means of namelist_top_cfg (as for NEMO physical ones).
+
+Note that ## is used to refer to a number in an array field.
+
+.. literalinclude:: ../../namelists/namtrc_run
+
+.. literalinclude:: ../../namelists/namtrc
+
+.. literalinclude:: ../../namelists/namtrc_dta
+
+.. literalinclude:: ../../namelists/namtrc_adv
+
+.. literalinclude:: ../../namelists/namtrc_ldf
+
+.. literalinclude:: ../../namelists/namtrc_rad
+
+.. literalinclude:: ../../namelists/namtrc_dmp
+
+.. literalinclude:: ../../namelists/namtrc_ice
+
+.. literalinclude:: ../../namelists/namtrc_trd
+
+.. literalinclude:: ../../namelists/namtrc_bc
+
+.. literalinclude:: ../../namelists/namtrc_bdy
+
+.. literalinclude:: ../../namelists/namage
+
+Two main types of data structure are used within TOP interface to initialize tracer properties (1) and
+to provide related initial and boundary conditions (2).
+
+**1. TOP tracers initialization**: sn_tracer (namtrc)
+
+Beside providing name and metadata for tracers,
+here are also defined the use of initial ({{{sn_tracer%llinit}}}) and
+boundary ({{{sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc}}}) conditions.
+
+In the following, an example of the full structure definition is given for two idealized tracers both with
+initial conditions given, while the first has only surface boundary forcing and
+the second both surface and coastal forcings:
+
+.. code-block:: fortran
+
+	!             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  !
+	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true.
+	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false.
+
+As tracers in BGC models are increasingly growing,
+the same structure can be written also in a more compact and readable way:
+
+.. code-block:: fortran
+
+	!             !    name   !           title of the field            !   units    ! initial data !
+	sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true.
+	sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true.
+	! sbc
+	sn_tracer(1)%llsbc = .true.
+	sn_tracer(2)%llsbc = .true.
+	! cbc
+	sn_tracer(2)%llcbc = .true.
+
+The data structure is internally initialized by code with dummy names and
+all initialization/forcing logical fields set to .false. .
+
+**2. Structures to read input initial and boundary conditions**: namtrc_dta (sn_trcdta), namtrc_bc (sn_trcsbc/sn_trccbc/sn_trcobc)
+
+The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
+(see details in User Manual SBC Chapter on Input Data specification).
+
+Input fields are prescribed within namtrc_dta (with sn_trcdta structure),
+while Boundary Conditions are applied to the model by means of namtrc_bc,
+with dedicated structure fields for surface (sn_trcsbc), riverine (sn_trccbc), and
+lateral open (sn_trcobc) boundaries.
+
+The following example illustrates the data structure in the case of initial condition for
+a single tracer contained in the file named tracer_1_data.nc (.nc is implicitly assumed in namelist filename),
+with a doubled initial value, and located in the usr/work/model/inputdata/ folder:
+
+.. code-block:: fortran
+
+	!               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask !
+	!               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      !
+	  sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , ''
+	  rf_trfac(1) = 2.0
+	  cn_dir = “usr/work/model/inputdata/”
+
+Note that, the Lateral Open Boundaries conditions are applied on the segments defined for the physical core of NEMO
+(see BDY description in the User Manual).
+
+namelist_trc
+------------
+
+Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14.
+
+|||| &'''namcfc'''     !   CFC ||
+
+|||| &'''namc14_typ'''     !  C14 - type of C14 tracer, default values of C14/C and pco2 ||
+
+|||| &'''namc14_sbc'''     !  C14 - surface BC ||
+
+|||| &'''namc14_fcg'''     !  files & dates ||
+
+``MY_TRC`` interface for coupling external BGC models
+=====================================================
+
+The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between
+NEMO and any external BGC model.
+
+The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in namtrc)
+
+The following 6 fortran files are available in MY_TRC with the specific purposes here described.
+
+``par_my_trc.F90``
+	This module allows to define additional arrays and public variables to be used within the MY_TRC interface
+
+``trcini_my_trc.F90``
+	Here are initialized user defined namelists and the call to the external BGC model initialization procedures to
+	populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to
+	system metrics that could be needed by the BGC model.
+
+``trcnam_my_trc.F90``
+	This routine is called at the beginning of trcini_my_trc and should contain the initialization of
+	additional namelists for the BGC model or user-defined code.
+
+``trcsms_my_trc.F90``
+	The routine performs the call to Boundary Conditions and its main purpose is to
+	contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
+	Be aware that lateral boundary conditions are applied in trcnxt routine.
+	IMPORTANT: the routines to compute the light penetration along the water column and
+	the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in
+	the code.
+
+``trcice_my_trc.F90``
+	Here it is possible to prescribe the tracers concentrations in the seaice that will be used as
+	boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice).
+	See e.g. the correspondent PISCES subroutine.
+
+``trcwri_my_trc.F90``
+	This routine performs the output of the model tracers (only those defined in namtrc) using IOM module
+	(see Manual Chapter “Output and Diagnostics”).
+	It is possible to place here the output of additional variables produced by the model,
+	if not done elsewhere in the code, using the call to iom_put.
+
+Coupling an external BGC model using NEMO framework
+===================================================
+
+The coupling with an external BGC model through the NEMO compilation framework can be achieved in
+different ways according to the degree of coding complexity of the Biogeochemical model, like e.g.,
+the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders.
+
+Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and constituted by
+a rather essential coding structure, likely few Fortran files.
+The new coupled configuration name is *NEMO_MYBGC*.
+
+The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) placed in
+a unique folder with root ``MYBGCPATH`` and to use the makenemo external readdressing of ``MY_SRC`` folder.
+
+The coupled configuration listed in ``work_cfgs.txt`` will look like
+
+::
+
+	NEMO_MYBGC OPA_SRC TOP_SRC
+
+and the related ``cpp_MYBGC.fcm`` content will be
+
+.. code-block:: perl
+
+	bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+
+the compilation with ``makenemo`` will be executed through the following syntax
+
+.. code-block:: console
+
+	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
+
+The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder
+(usually found in NEMO configurations) with a user defined external one.
+
+The compilation of more articulated BGC model code & infrastructure, like in the case of BFM
+([http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf BFM-NEMO coupling manual]),
+requires some additional features.
+
+As before, let’s assume a coupled configuration name *NEMO_MYBGC*,
+but in this case MYBGC model root becomes ``<MYBGCPATH>`` that contains 4 different subfolders for
+biogeochemistry, named ``initialization``, ``pelagic``, and ``benthic``, and
+a separate one named ``nemo_coupling`` including the modified ``MY_SRC`` routines.
+The latter folder containing the modified NEMO coupling interface will be still linked using
+the makenemo “-e” option.
+
+In order to include the BGC model subfolders in the compilation of NEMO code,
+it will be necessary to extend the configuration ``cpp_NEMO_MYBGC.fcm`` file to include the specific paths of
+``MYBGC`` folders, as in the following example
+
+.. code-block:: perl
+
+	bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+	
+	src::MYBGC::initialization         <MYBGCPATH>/initialization
+	src::MYBGC::pelagic                <MYBGCPATH>/pelagic
+	src::MYBGC::benthic                <MYBGCPATH>/benthic
+	
+	bld::pp::MYBGC      1
+	bld::tool::fppflags::MYBGC   %FPPFLAGS
+	bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS
+
+where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for
+selecting/excluding specific parts of the code.
+The BGC model code will be preprocessed in the configuration ``BLD`` folder as for NEMO,
+but with an independent path, like ``NEMO_MYBGC/BLD/MYBGC/<subforlders>``.
+
+The compilation will be performed similarly to in the previous case with the following
+
+.. code-block:: console
+
+	$ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
+
+Note that, the additional lines specific for the BGC model source and build paths can be written into
+a separate file, e.g. named ``MYBGC.fcm``, and then simply included in the ``cpp_NEMO_MYBGC.fcm`` as follow
+
+.. code-block:: perl
+
+	bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top
+	inc <MYBGCPATH>/MYBGC.fcm
+
+This will enable a more portable compilation structure for all MYBGC related configurations.
+
+**Important**: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax,
+as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to
+avoid compilation conflicts due to duplicate routines.
+
+All modifications illustrated above, can be easily implemented using shell or python scripting to
+edit the NEMO configuration CPP.fcm file and to create the BGC model specific FCM compilation file with code paths.
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcadv.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcadv.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcadv.F90	(revision 10321)
@@ -64,5 +64,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcbbl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcbbl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcbbl.F90	(revision 10321)
@@ -32,5 +32,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcdmp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcdmp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcdmp.F90	(revision 10321)
@@ -46,7 +46,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -251,5 +251,5 @@
          ! -------------------
 
-         IF( cn_cfg == "orca" ) THEN
+         IF( cn_cfg == "orca" .OR. cn_cfg == "ORCA") THEN
             !
             SELECT CASE ( nn_cfg )
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcldf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcldf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcldf.F90	(revision 10321)
@@ -45,7 +45,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.7 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcnxt.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcnxt.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcnxt.F90	(revision 10321)
@@ -48,7 +48,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -103,5 +103,38 @@
       IF( l_trdtrc )  THEN             ! trends: store now fields before the Asselin filter application
          ALLOCATE( ztrdt(jpi,jpj,jpk,jptra) )
-         ztrdt(:,:,:,:)  = trn(:,:,:,:)
+         ztrdt(:,:,:,:)  = 0._wp
+         IF( ln_traldf_iso ) THEN                       ! diagnose the "pure" Kz diffusive trend 
+            DO jn = 1, jptra
+               CALL trd_tra( kt, 'TRC', jn, jptra_zdfp, ztrdt(:,:,:,jn) )
+            ENDDO
+         ENDIF
+
+         ! total trend for the non-time-filtered variables. 
+         zfact = 1.0 / rdttrc
+         ! G Nurser 23 Mar 2017. Recalculate trend as Delta(e3t*T)/e3tn; e3tn cancel from tsn terms
+         IF( ln_linssh ) THEN       ! linear sea surface height only
+            DO jn = 1, jptra
+               DO jk = 1, jpkm1
+                  ztrdt(:,:,jk,jn) = ( tra(:,:,jk,jn)*e3t_a(:,:,jk) / e3t_n(:,:,jk) - trn(:,:,jk,jn)) * zfact
+               END DO
+            END DO
+         ELSE
+            DO jn = 1, jptra
+               DO jk = 1, jpkm1
+                  ztrdt(:,:,jk,jn) = ( tra(:,:,jk,jn) - trn(:,:,jk,jn) ) * zfact
+               END DO
+            END DO
+         ENDIF
+         !
+         DO jn = 1, jptra
+            CALL trd_tra( kt, 'TRC', jn, jptra_tot, ztrdt(:,:,:,jn) )
+         ENDDO
+         !
+         IF( ln_linssh ) THEN       ! linear sea surface height only
+            ! Store now fields before applying the Asselin filter 
+            ! in order to calculate Asselin filter trend later.
+            ztrdt(:,:,:,:) = trn(:,:,:,:) 
+         ENDIF
+
       ENDIF
       !                                ! Leap-Frog + Asselin filter time stepping
@@ -113,4 +146,12 @@
             END DO
          END DO
+         IF (l_trdtrc .AND. .NOT. ln_linssh ) THEN   ! Zero Asselin filter contribution must be explicitly written out since for vvl
+            !                                        ! Asselin filter is output by tra_nxt_vvl that is not called on this time step
+            ztrdt(:,:,:,:) = 0._wp            
+            DO jn = 1, jptra
+               CALL trd_tra( kt, 'TRC', jn, jptra_atf, ztrdt(:,:,:,jn) )
+            ENDDO
+         END IF
+         !
       ELSE     
          IF( .NOT. l_offline ) THEN ! Leap-Frog + Asselin filter time stepping
@@ -126,14 +167,14 @@
       ENDIF
       !
-      IF( l_trdtrc ) THEN              ! trends: send Asselin filter trends to trdtra manager for further diagnostics
+      IF( l_trdtrc .AND. ln_linssh ) THEN      ! trend of the Asselin filter (tb filtered - tb)/dt )
          DO jn = 1, jptra
             DO jk = 1, jpkm1
                zfact = 1._wp / r2dttrc  
                ztrdt(:,:,jk,jn) = ( trb(:,:,jk,jn) - ztrdt(:,:,jk,jn) ) * zfact 
-               CALL trd_tra( kt, 'TRC', jn, jptra_atf, ztrdt )
-            END DO
+            END DO
+            CALL trd_tra( kt, 'TRC', jn, jptra_atf, ztrdt(:,:,:,jn) )
          END DO
-         DEALLOCATE( ztrdt ) 
       END IF
+      IF( l_trdtrc ) DEALLOCATE( ztrdt ) 
       !
       IF(ln_ctl)   THEN  ! print mean trends (used for debugging)
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcrad.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcrad.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcrad.F90	(revision 10321)
@@ -29,7 +29,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcsbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcsbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trcsbc.F90	(revision 10321)
@@ -31,7 +31,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trctrp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trctrp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trctrp.F90	(revision 10321)
@@ -37,7 +37,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trczdf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trczdf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trczdf.F90	(revision 10321)
@@ -30,7 +30,7 @@
    
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.7 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc.F90	(revision 10321)
@@ -51,7 +51,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc_rst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc_rst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdmxl_trc_rst.F90	(revision 10321)
@@ -23,7 +23,7 @@
    
    !!---------------------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!---------------------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc.F90	(revision 10321)
@@ -25,7 +25,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 
@@ -81,19 +81,19 @@
          !
          SELECT CASE( ktrd )
-         CASE( jptra_xad  )       ;    WRITE (cltra,'("XAD_",4a)')
-         CASE( jptra_yad  )       ;    WRITE (cltra,'("YAD_",4a)')
-         CASE( jptra_zad  )       ;    WRITE (cltra,'("ZAD_",4a)')
-         CASE( jptra_ldf  )       ;    WRITE (cltra,'("LDF_",4a)')
-         CASE( jptra_bbl  )       ;    WRITE (cltra,'("BBL_",4a)')
-         CASE( jptra_nsr  )       ;    WRITE (cltra,'("FOR_",4a)')
-         CASE( jptra_zdf  )       ;    WRITE (cltra,'("ZDF_",4a)')
-         CASE( jptra_dmp  )       ;    WRITE (cltra,'("DMP_",4a)')
-         CASE( jptra_sms  )       ;    WRITE (cltra,'("SMS_",4a)')
-         CASE( jptra_atf  )       ;    WRITE (cltra,'("ATF_",4a)')
-         CASE( jptra_radb )       ;    WRITE (cltra,'("RDB_",4a)')
-         CASE( jptra_radn )       ;    WRITE (cltra,'("RDN_",4a)')
+         CASE( jptra_xad  )  ;  WRITE (cltra,'("XAD_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_yad  )  ;  WRITE (cltra,'("YAD_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_zad  )  ;  WRITE (cltra,'("ZAD_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_ldf  )  ;  WRITE (cltra,'("LDF_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_bbl  )  ;  WRITE (cltra,'("BBL_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_nsr  )  ;  WRITE (cltra,'("FOR_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_zdf  )  ;  WRITE (cltra,'("ZDF_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_zdfp )  ;  WRITE (cltra,'("ZDP_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_dmp  )  ;  WRITE (cltra,'("DMP_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_sms  )  ;  WRITE (cltra,'("SMS_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_tot  )  ;  WRITE (cltra,'("TOT_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_atf  )  ;  WRITE (cltra,'("ATF_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_radb )  ;  WRITE (cltra,'("RDB_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
+         CASE( jptra_radn )  ;  WRITE (cltra,'("RDN_",4a)')  ; cltra = TRIM(cltra)//TRIM(ctrcnm(kjn)) ; CALL iom_put( cltra,  ptrtrd(:,:,:) )
          END SELECT
-                                          cltra = TRIM(cltra)//TRIM(ctrcnm(kjn))
-                                          CALL iom_put( cltra,  ptrtrd(:,:,:) )
          !
       END IF
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc_oce.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc_oce.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/TRP/trdtrc_oce.F90	(revision 10321)
@@ -107,7 +107,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/oce_trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/oce_trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/oce_trc.F90	(revision 10321)
@@ -82,5 +82,6 @@
    USE ldfslp , ONLY :   wslpi      =>   wslpi        !: i-slope at w-point
    USE ldfslp , ONLY :   wslpj      =>   wslpj        !: j-slope at w-point
-   USE ldfslp , ONLY :  ln_traldf_triad => ln_traldf_triad   !: use of triad scheme
+   USE ldfslp , ONLY :   ln_traldf_triad => ln_traldf_triad   !: use of triad scheme
+   USE ldfslp , ONLY :   ln_traldf_iso => ln_traldf_iso   !: use of isopycnal scheme
 !!gm end
 
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trc.F90	(revision 10321)
@@ -122,4 +122,7 @@
    CHARACTER(len=20), PUBLIC, DIMENSION(jp_bdy) :: cn_trc        ! Choice of boundary condition for tracers
    INTEGER,           PUBLIC, DIMENSION(jp_bdy) :: nn_trcdmp_bdy !: =T Tracer damping
+   !
+   ! Vertical axis used in the sediment module
+   REAL(wp), PUBLIC, ALLOCATABLE, SAVE, DIMENSION(:) ::   profsed
 !$AGRIF_DO_NOT_TREAT
    ! External data structure of BDY for TOP. Available elements: cn_obc, ll_trc, trcnow, dmp
@@ -130,5 +133,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbc.F90	(revision 10321)
@@ -51,5 +51,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbdy.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbdy.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcbdy.F90	(revision 10321)
@@ -31,7 +31,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcdta.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcdta.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcdta.F90	(revision 10321)
@@ -40,7 +40,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -217,20 +217,20 @@
          ELSE                                !==   z- or zps- coordinate   ==!
             ! zps-coordinate (partial steps) interpolation at the last ocean level
-            IF( ln_zps ) THEN
-               DO jj = 1, jpj
-                  DO ji = 1, jpi
-                     ik = mbkt(ji,jj) 
-                     IF( ik > 1 ) THEN
-                        zl = ( gdept_1d(ik) - gdept_0(ji,jj,ik) ) / ( gdept_1d(ik) - gdept_1d(ik-1) )
-                        ptrcdta(ji,jj,ik) = (1.-zl) * ptrcdta(ji,jj,ik) + zl * ptrcdta(ji,jj,ik-1)
-                     ENDIF
-                     ik = mikt(ji,jj)
-                     IF( ik > 1 ) THEN
-                        zl = ( gdept_0(ji,jj,ik) - gdept_1d(ik) ) / ( gdept_1d(ik+1) - gdept_1d(ik) )
-                        ptrcdta(ji,jj,ik) = (1.-zl) * ptrcdta(ji,jj,ik) + zl * ptrcdta(ji,jj,ik+1)
-                     ENDIF
-                  END DO
-              END DO
-            ENDIF
+!            IF( ln_zps ) THEN
+!               DO jj = 1, jpj
+!                  DO ji = 1, jpi
+!                     ik = mbkt(ji,jj) 
+!                     IF( ik > 1 ) THEN
+!                        zl = ( gdept_1d(ik) - gdept_0(ji,jj,ik) ) / ( gdept_1d(ik) - gdept_1d(ik-1) )
+!                        ptrcdta(ji,jj,ik) = (1.-zl) * ptrcdta(ji,jj,ik) + zl * ptrcdta(ji,jj,ik-1)
+!                     ENDIF
+!                     ik = mikt(ji,jj)
+!                     IF( ik > 1 ) THEN
+!                        zl = ( gdept_0(ji,jj,ik) - gdept_1d(ik) ) / ( gdept_1d(ik+1) - gdept_1d(ik) )
+!                        ptrcdta(ji,jj,ik) = (1.-zl) * ptrcdta(ji,jj,ik) + zl * ptrcdta(ji,jj,ik+1)
+!                     ENDIF
+!                  END DO
+!              END DO
+!            ENDIF
             !
          ENDIF
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcice.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcice.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcice.F90	(revision 10321)
@@ -28,5 +28,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcini.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -174,9 +174,10 @@
       END DO
       !    
-      IF( ln_pisces  )   CALL trc_ini_pisces     !  PISCES model
-      IF( ln_my_trc  )   CALL trc_ini_my_trc     !  MY_TRC model
-      IF( ll_cfc     )   CALL trc_ini_cfc        !  CFC's
-      IF( ln_c14     )   CALL trc_ini_c14        !  C14 model
-      IF( ln_age     )   CALL trc_ini_age        !  AGE
+      IF( ln_pisces      )   CALL trc_ini_pisces     !  PISCES model
+      IF( ln_my_trc      )   CALL trc_ini_my_trc     !  MY_TRC model
+      IF( ll_cfc         )   CALL trc_ini_cfc        !  CFC's
+      IF( ln_c14         )   CALL trc_ini_c14        !  C14 model
+      IF( ln_age         )   CALL trc_ini_age        !  AGE
+      IF( .NOT.ln_pisces ) ALLOCATE( profsed(2) )
       !
       IF(lwp) THEN                   ! control print
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcnam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcnam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcnam.F90	(revision 10321)
@@ -33,7 +33,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcrst.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcrst.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcrst.F90	(revision 10321)
@@ -33,7 +33,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.7 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -252,5 +252,5 @@
                ! parameters corresponding to nit000 - 1 (as we start the step
                ! loop with a call to day)
-               ndastp = ndate0        ! ndate0 read in the namelist in dom_nam
+               ndastp = ndate0 - 1       ! ndate0 read in the namelist in dom_nam
                nhour   =   nn_time0 / 100
                nminute = ( nn_time0 - nhour * 100 )
@@ -347,7 +347,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcrst
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsms.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsms.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsms.F90	(revision 10321)
@@ -28,7 +28,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcstp.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcstp.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcstp.F90	(revision 10321)
@@ -37,7 +37,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsub.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsub.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcsub.F90	(revision 10321)
@@ -78,5 +78,5 @@
    !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcwri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcwri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/src/TOP/trcwri.F90	(revision 10321)
@@ -76,7 +76,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/TOP 3.3 , NEMO Consortium (2018)
+   !! NEMO/TOP 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!======================================================================
 END MODULE trcwri
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/EXPREF/namelist_cfg	(revision 10321)
@@ -31,11 +31,11 @@
    rn_ppgphi0  =    38.5   !  Reference latitude      [degrees]
    rn_u10      =      0.   !  10m wind speed              [m/s]
-     rn_windszx=   4000.   !  longitudinal wind extension   [km]
-     rn_windszy=   4000.   !  latitudinal wind extension    [km]
+     rn_windszx =   4000.   !  longitudinal wind extension   [km]
+     rn_windszy =   4000.   !  latitudinal wind extension    [km]
      rn_uofac  =      0.   !  Uoce multiplicative factor (0.:absolute or 1.:relative winds)
    rn_vtxmax   =      1.   !  initial vortex max current  [m/s]
    rn_uzonal   =      1.   !  initial zonal current       [m/s]
-     rn_ujetszx=   4000.   !  longitudinal jet extension   [km]
-     rn_ujetszy=   4000.   !  latitudinal jet extension    [km]
+     rn_ujetszx =   4000.   !  longitudinal jet extension   [km]
+     rn_ujetszy =   4000.   !  latitudinal jet extension    [km]
    nn_botcase  =      0    !  bottom definition (0:flat, 1:bump)
    nn_initcase =      1    !  initial condition case (0:rest, 1:zonal current, 2:current shear, 3: gaussian zonal current,
@@ -182,5 +182,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
       nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/diawri.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/diawri.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/diawri.F90	(revision 10321)
@@ -79,7 +79,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 3.3 , NEMO Consortium (2010)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/domvvl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/domvvl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/domvvl.F90	(revision 10321)
@@ -64,7 +64,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 3.7 , NEMO-Consortium (2015) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/stpctl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/stpctl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/stpctl.F90	(revision 10321)
@@ -34,7 +34,7 @@
    INTEGER  ::   idrun, idtime, idssh, idu, ids, istatus
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2017)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/trazdf.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/trazdf.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/trazdf.F90	(revision 10321)
@@ -38,7 +38,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2017)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0, NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -29,7 +29,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -52,7 +52,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -34,7 +34,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/CANAL/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -34,7 +34,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/1_namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/1_namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/1_namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!               ICEDYN (SAS BIPERIODIC) configuration                !!
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!               ICEDYN (SAS BIPERIODIC) configuration                !!
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_ice_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_ice_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/EXPREF/namelist_ice_cfg	(revision 10321)
@@ -95,5 +95,5 @@
    sn_tmi = 'initice'                 , -12 ,'tmi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
    sn_smi = 'initice'                 , -12 ,'smi'   ,  .false.  , .true., 'yearly'  , '' , '', ''
-   cn_dir='./'
+   cn_dir ='./'
 /
 !------------------------------------------------------------------------------
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -34,7 +34,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
@@ -61,5 +61,5 @@
       REAL(wp)::   zlx, zly  ! Local scalars
       !!
-      NAMELIST/namusr_def/ ln_zco, rn_dx, rn_dy, ln_corio, rn_ppgphi0
+      NAMELIST/namusr_def/ rn_dx, rn_dy, ln_corio, rn_ppgphi0
       !!----------------------------------------------------------------------
       !
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -36,7 +36,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ICEDYN/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -28,7 +28,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                         ISOMIP configuration                       !!
@@ -140,5 +140,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .true.     !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .false.    !  implicit top/bottom friction flag
@@ -153,5 +153,5 @@
    rn_z0      =  3.0e-3    !  roughness [m] (ln_loglayer=T)
    ln_boost   = .false.    !  =T regional boost of Cd0 ; =F constant
-      rn_boost=  50.          !  local boost factor  [-]
+      rn_boost =  50.          !  local boost factor  [-]
 /
 !-----------------------------------------------------------------------
@@ -164,5 +164,5 @@
    rn_z0      =  3.e-3    !  roughness [m] (ln_loglayer=T)
    ln_boost   = .false.   !  =T regional boost of Cd0 ; =F constant
-      rn_boost=  50.         !  local boost factor  [-]
+      rn_boost =  50.         !  local boost factor  [-]
 /
 !!======================================================================
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -28,7 +28,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2017)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -36,7 +36,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2017)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -35,7 +35,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/ISOMIP/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -33,7 +33,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_cen2_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_cen2_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_cen2_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .true.  !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .true.  !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                    LOCK EXCHANGE configuration                     !!
@@ -40,5 +40,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -188,5 +188,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_eenH_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_eenH_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_eenH_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 1       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_een_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_een_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_een_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ene_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ene_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ene_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ens_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ens_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT2_vect_ens_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_cen2_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_cen2_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_cen2_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .true.  !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .true.  !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_eenH_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_eenH_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_eenH_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 1       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_een_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_een_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_een_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ene_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ene_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ene_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ens_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ens_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/EXPREF/namelist_FCT4_vect_ens_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -26,5 +26,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .false.   !  (=T) create the domain configuration file
+   ln_write_cfg = .false.   !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -116,5 +116,5 @@
    ln_dynadv_vec = .true.  !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -26,7 +26,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -32,7 +32,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -34,7 +34,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/LOCK_EXCHANGE/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -30,7 +30,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_cen-ahm1000_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .true.  !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .true.  !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT2_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_cen-ahm1000_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_cen-ahm1000_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_cen-ahm1000_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .true.  !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .true.  !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_sco_FCT4_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT2_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_flux_ubs_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                        OVERFLOW configuration                      !!
@@ -118,5 +118,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -192,5 +192,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/EXPREF/namelist_zps_FCT4_vect_een_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : used to overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !
@@ -74,5 +74,5 @@
    ln_lin     = .false.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin = .false.    !  non-linear  drag: Cd = Cd0 |U|
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    !
    ln_drgimp  = .true.     !  implicit top/bottom friction flag
@@ -125,5 +125,5 @@
    ln_dynadv_vec = .true. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -26,7 +26,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 3.7 , NEMO Consortium (2014)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -33,7 +33,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -34,7 +34,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/OVERFLOW/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -32,7 +32,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: MO/branches/UKMO/NEMO4_beta_mirror/tests/README
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/README	(revision 10320)
+++ 	(revision )
@@ -1,7 +1,0 @@
-## List of available test cases is in demo_cfgs.txt
-
-## HOW TO COMPILE TEST CASES :
-
-In the same manner as ref. cfg with '-r' option, use makenemo with '-a' option
-
-./makenemo -n WAD2 -a WAD -m macport_osx -j 4
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/README.rst
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/README.rst	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/README.rst	(revision 10321)
@@ -0,0 +1,119 @@
+**********************
+Explore the test cases
+**********************
+
+.. contents::
+	:local:
+
+List
+====
+
+  The description below is a brief description of the test cases available in NEMO. 
+
+ICEDYN
+------
+  
+  This test case illustrates the advection of an ice patch across a East/West and North/South periodic channel. 
+  This configuration can be used to test the advection of the ice patch in an AGRIF zoom (1:3) 
+  and across the AGRIF boundary or to test the ice advection schemes (Prather and Ultimate-Macho). 
+  In the latest case user need to remove ``key_agrif`` out of the CPP keys list. 
+
+  .. image:: _static/ICEDYN_UDIAG_43days_UM5.gif
+
+VORTEX
+------
+  
+  This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
+  It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates.
+  It serves as a benchmark for quantitative estimates of nesting errors as in Debreu et al. (2012) :cite:`DEBREU2012`,
+  Penven et al. (2006) :cite:`PENVEN2006` or Spall and Holland (1991) :cite:`SPALL1991`.
+  
+  The animation below (sea level anomaly in meters) illustrates with two 1:2 successively nested grids how
+  the vortex smoothly propagates out of the refined grids.
+  
+  .. image:: _static/VORTEX_anim.gif
+
+ISOMIP
+------
+
+  The purpose of this test case is to evaluate the impact of various schemes and new development with the iceshelf cavities circulation and melt.
+  This configuration served as initial assesment of the ice shelf module in Losh et al. (2008) :cite:`LOSCH2008` and Mathiot et al. (2017) :cite:`MATHIOT2017`. 
+  The default setup is the one described `here <http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf>`_.
+  
+  The figure below (meridional overturning circulation) illustrates the circulation generated after 10000 days by the ice shelf melting (ice pump).
+
+  .. image:: _static/ISOMIP_moc.png
+
+LOCK_EXCHANGE
+-------------
+
+  The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
+  by Haidvogel and Beckmann (1999) :cite:`HAIDVOGEL1999` for testing advection schemes in ocean circulation models.
+  It has been used by several authors including Burchard and Bolding (2002) :cite:`BURCHARD2002` and Ilicak et al. (2012) :cite:`ILICAK2012`.
+  The LOCK EXCHANGE experiment can in particular illustrate the impact of different choices of numerical schemes 
+  and/or subgrid closures on spurious interior mixing.
+
+  Below the animation of the LOCK_EXCHANGE test case using the advection scheme FCT4 (forth order) for tracer and ubs for dynamics.
+
+  .. image:: _static/LOCK-FCT4_flux_ubs.gif
+
+OVERFLOW
+--------
+
+  The OVERFLOW experiment illustrates the impact of different choices of numerical schemes 
+  and/or subgrid closures on spurious interior mixing close to bottom topography. 
+  The OVERFLOW experiment is adapted from the non-rotating overflow configuration described 
+  in Haidvogel and Beckmann (1999) :cite:`HAIDVOGEL1999` and further used by Ilicak et al. (2012) :cite:`ILICAK2012`.
+  Here we can assess the behaviour of the second-order tracer advection scheme FCT2 and fortht-order FCT4, z-coordinate and sigma coordinate (...).
+
+  Below the animation of the OVERFLOW test case in sigma coordinate with the forth-order advection scheme FCT4.
+
+  .. image:: _static/OVF-sco_FCT4_flux_cen-ahm1000.gif
+
+WAD
+---
+
+  A set of simple closed basin geometries for testing the Wetting and drying capabilities. 
+  Examples range from a closed channel with EW linear bottom slope to a parabolic EW channel with a Gaussian ridge.
+  
+  Below the animation of the test case 7. This test case is a simple linear slope with a mid-depth shelf with an open boundary forced with a sinusoidally varying ssh.
+  This test case has been introduced to emulate a typical coastal application with a tidally forced open boundary with an adverse SSH gradient that, when released, creates a surge up the slope.
+  The parameters are chosen such that the surge rises above sea-level before falling back and oscillating towards an equilibrium position
+
+  .. image:: _static/wad_testcase_7.gif
+
+CANAL
+-----
+
+  East-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex).
+
+  .. image::_static/CANAL_image.gif
+
+Compile test cases
+==================
+
+The compilation of the test cases is very similar to the manner the reference configurations are compiled.
+If you are not familiar on how to compile NEMO, it is first recomended to read :doc:`the instructions <install>`
+
+| In the same manner as the ref. cfg are compiled with '-r' option, test cases can be compile by the use of makenemo with '-a' option.
+
+| Here an example to compile a copy named WAD2 of the wetting and drying test case (WAD) on the macport_osx architecture on 4 cores:
+
+.. code-block:: console
+ 
+	$ ./makenemo -n WAD2 -a WAD -m macport_osx -j 4
+
+Run and analyse the test cases
+==============================
+
+There no requirement of specific input file for the test_cases presented here. The XIOS xml input files and namelist are already setup correctly. 
+For detailed description and Jupyter notebook, the reader is directed on
+the `NEMO test cases repository <http://github.com/NEMO-ocean/NEMO-examples>`_
+
+References
+==========
+
+.. bibliography:: test_cases.bib
+	:all:
+	:style: unsrt
+	:labelprefix: T
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/1_namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/1_namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/1_namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite defaults values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite defaults values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                         VORTEX configuration                       !!
@@ -187,5 +187,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                         VORTEX configuration                       !!
@@ -178,5 +178,5 @@
    ln_dynadv_vec = .false. !  vector form (T) or flux form (F)
    nn_dynkeg     = 0       ! scheme for grad(KE): =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .true.  !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/domvvl.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/domvvl.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/domvvl.F90	(revision 10321)
@@ -64,7 +64,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OCE 4.0 , NEMO Consortium (2018) 
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -27,7 +27,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0, NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -29,7 +29,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -34,7 +34,7 @@
 
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -33,7 +33,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/VORTEX/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -32,7 +32,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/EXPREF/namelist_cfg
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/EXPREF/namelist_cfg	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/EXPREF/namelist_cfg	(revision 10321)
@@ -1,4 +1,4 @@
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-!! NEMO/OPA  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
+!! NEMO/OCE  Configuration namelist : overwrite default values defined in SHARED/namelist_ref
 !!>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 !!                      Wetting & Drying configuration                !!
@@ -50,5 +50,5 @@
    ln_read_cfg = .false.   !  (=T) read the domain configuration file
       !                    !  (=F) user defined configuration  ==>>>  see usrdef(_...) modules
-   ln_write_cfg= .true.    !  (=T) create the domain configuration file
+   ln_write_cfg = .true.    !  (=T) create the domain configuration file
 /
 !-----------------------------------------------------------------------
@@ -58,5 +58,5 @@
    ln_wd_dl    = .true.    ! T/F activation of directional limiter
    ln_wd_dl_bc = .true.    ! T/F Directional limiteer Baroclinic option
-   ln_wd_dl_rmp= .true.    ! T/F Turn on directional limiter ramp
+   ln_wd_dl_rmp = .true.    ! T/F Turn on directional limiter ramp
    rn_wdmin0   =  0.30     ! depth at which WaD starts
    rn_wdmin1   =  0.2      ! Minimum wet depth on dried cells
@@ -205,5 +205,5 @@
 &namdrg        !   top/bottom drag coefficient                          (default: NO selection)
 !-----------------------------------------------------------------------
-   ln_loglayer= .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
+   ln_loglayer = .false.    !  logarithmic drag: Cd = vkarmn/log(z/z0) |U|
    ln_lin      = .true.    !      linear  drag: Cd = Cd0 Uc0                   &   namdrg_top)
    ln_non_lin  = .false.   !  non-linear  drag: Cd = Cd0 |U|
@@ -222,5 +222,5 @@
    rn_z0      =  3.e-3    !  roughness [m] (ln_loglayer=T)
    ln_boost   = .false.   !  =T regional boost of Cd0 ; =F constant
-      rn_boost=  50.         !  local boost factor  [-]
+      rn_boost =  50.         !  local boost factor  [-]
 /
 !-----------------------------------------------------------------------
@@ -316,5 +316,5 @@
    ln_dynadv_vec = .true. !  vector form - 2nd centered scheme
      nn_dynkeg     = 0        ! grad(KE) scheme: =0   C2  ;  =1   Hollingsworth correction
-   ln_dynadv_cen2= .false. !  flux form - 2nd order centered scheme
+   ln_dynadv_cen2 = .false. !  flux form - 2nd order centered scheme
    ln_dynadv_ubs = .false. !  flux form - 3rd order UBS      scheme
 /
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/bdyini.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/bdyini.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/bdyini.F90	(revision 10321)
@@ -47,5 +47,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_hgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_hgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_hgr.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_istate.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_istate.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_istate.F90	(revision 10321)
@@ -29,5 +29,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_nam.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_nam.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_nam.F90	(revision 10321)
@@ -35,5 +35,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_sbc.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_sbc.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_sbc.F90	(revision 10321)
@@ -34,7 +34,7 @@
 #  include "vectopt_loop_substitute.h90"
    !!----------------------------------------------------------------------
-   !! NEMO/OPA 4.0 , NEMO Consortium (2016)
+   !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (NEMOGCM/NEMO_CeCILL.txt)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_zgr.F90
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_zgr.F90	(revision 10320)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/WAD/MY_SRC/usrdef_zgr.F90	(revision 10321)
@@ -34,5 +34,5 @@
    !! NEMO/OCE 4.0 , NEMO Consortium (2018)
    !! $Id$
-   !! Software governed by the CeCILL licence     (./LICENSE)
+   !! Software governed by the CeCILL license (see ./LICENSE)
    !!----------------------------------------------------------------------
 CONTAINS             
Index: /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/test_cases.bib
===================================================================
--- /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/test_cases.bib	(revision 10321)
+++ /NEMO/branches/UKMO/NEMO4_beta_mirror/tests/test_cases.bib	(revision 10321)
@@ -0,0 +1,88 @@
+@book{HAIDVOGEL1999,
+   author = {D. B. Haidvogel and A. Beckmann},
+   publisher = {Imperial College Press, London},
+   year = {1999},
+   title = {Numerical ocean circulation modeling}
+}
+
+@book{BURCHARD2002,
+   title={GETM: A General Estuarine Transport Model; Scientific Documentation},
+   author={Burchard, Hans and Bolding, Karsten},
+   year={2002},
+   publisher={European Commission, Joint Research Centre, Institute for Environment and Sustainability}
+}
+
+@article{ILICAK2012,
+   title = "Spurious dianeutral mixing and the role of momentum closure",
+   journal = "Ocean Modelling",
+   volume = "45-46",
+   pages = "37 - 58",
+   year = "2012",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2011.10.003",
+   author = "Mehmet Ilicak and Alistair J. Adcroft and Stephen M. Griffies and Robert W. Hallberg",
+   keywords = "Spurious dianeutral transport, Cabbeling, Overflows, Exchange-flow, Ocean models, Momentum transport, Tracer advection, Reference potential energy"
+}
+
+@article{DEBREU2012,
+   title = "Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation",
+   journal = "Ocean Modelling",
+   volume = "49-50",
+   pages = "1 - 21",
+   year = "2012",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2012.03.003",
+   author = "Laurent Debreu and Patrick Marchesiello and Pierrick Penven and Gildas Cambon",
+   keywords = "Two-way nesting, Finite difference method, Modeling, Boundary conditions, Coastal upwelling"
+}
+
+@article{PENVEN2006,
+   title = "Evaluation and application of the ROMS 1-way embedding procedure to the central california upwelling system",
+   journal = "Ocean Modelling",
+   volume = "12",
+   number = "1",
+   pages = "157 - 187",
+   year = "2006",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2005.05.002",
+   author = "Pierrick Penven and Laurent Debreu and Patrick Marchesiello and James C. McWilliams",
+   keywords = "Ocean models, Boundary conditions, Embedding, Coastal upwelling, Mesoscale eddies, Eddy kinetic energy, North America, West Coast, Central upwelling system, Monterey Bay, 35–41°N, 128–121°W"
+}
+
+@article{SPALL1991,
+   author = {Spall, M. A. and Holland, W. R.},
+   title = {A Nested Primitive Equation Model for Oceanic Applications},
+   journal = {Journal of Physical Oceanography},
+   volume = {21},
+   number = {2},
+   pages = {205-220},
+   year = {1991},
+   doi = {10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2},
+}
+
+@article{MATHIOT2017,
+   author = {Mathiot, P. and Jenkins, A. and Harris, C. and Madec, G.},
+   title = {Explicit representation and parametrised impacts of under ice shelf seas in the ${z}^{\ast}$ coordinate ocean model NEMO 3.6},
+   journal = {Geoscientific Model Development},
+   volume = {10},
+   year = {2017},
+   number = {7},
+   pages = {2849--2874},
+   url = {https://www.geosci-model-dev.net/10/2849/2017/},
+   doi = {10.5194/gmd-10-2849-2017}
+}
+
+@article{LOSCH2008,
+   author = {Losch, M.},
+   title = {Modeling ice shelf cavities in a z coordinate ocean general circulation model},
+   journal = {Journal of Geophysical Research: Oceans},
+   volume = {113},
+   year = {2008},
+   number = {C8},
+   pages = {},
+   keywords = {Ice shelf cavities, numerical ocean modeling, z coordinates},
+   doi = {10.1029/2007JC004368},
+   url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2007JC004368},
+   eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2007JC004368},
+   abstract = {Processes at the ice shelf-ocean interface and in particular in ice shelf cavities around Antarctica have an observable effect on the solutions of basin scale to global coupled ice-ocean models. Despite this, these processes are not routinely represented in global ocean and climate models. It is shown that a new ice shelf cavity model for z coordinate models can reproduce results from an intercomparison project of earlier approaches with vertical ?~C or isopycnic coordinates. As a proof of concept, ice shelves are incorporated in a 100-year global integration of a z coordinate model. In this simulation, glacial meltwater can be traced as far as north as 15??S. The observed effects of processes in the ice shelf cavities agree with previous results from a ?~C coordinate model, notably the increase in sea ice thickness. However, melt rates are overestimated probably because the parameterization of basal melting does not suit the low resolution of this configuration.}
+}
