Index: /NEMO/trunk/INSTALL.rst
===================================================================
--- /NEMO/trunk/INSTALL.rst	(revision 10200)
+++ /NEMO/trunk/INSTALL.rst	(revision 10201)
@@ -2,4 +2,6 @@
 Install the framework
 =====================
+
+.. include:: .global.rst
 
 .. contents:: \
@@ -116,7 +118,6 @@
 More options
 
-.. includefile::
-
-	
+..
+	.. literalinclude::
 
 -----------------
@@ -166,6 +167,6 @@
 -----------------
 
-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
Index: /NEMO/trunk/README.rst
===================================================================
--- /NEMO/trunk/README.rst	(revision 10200)
+++ /NEMO/trunk/README.rst	(revision 10201)
@@ -1,10 +1,13 @@
-.. role:: rstblue
-.. role:: rstgreen
-.. role:: rstgrey
-.. role:: rstgreysup(sup)
+.. include:: .global.rst
 
+:Release: |release|
+:Date:    |today|
+            
 NEMO for *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
@@ -15,11 +18,11 @@
 
 - :rstblue:`OPA` is fundamental to all users by modelling the ocean [thermo]dynamics and 
-  solving the primitive equations         (``./src/OCE``); 
+  solving the primitive equations         (``./src/OCE``); :cite:`madec_bk08`
 - :rstgrey:`SI`\ :rstgreysup:`3` for sea-ice simulates ice [thermo]dynamics, brine inclusions and 
-  subgrid-scale thickness variations      (``./src/ICE``); 
+  subgrid-scale thickness variations      (``./src/ICE``); :cite:`gmd-8-2991-2015,vancoppenolle200933`
 - :rstgreen:`TOP-PISCES` models biogeochemistry with TOP for the on/offline oceanic tracers transport and 
-  PISCES for the biogeochemical processes (``./src/MBG``).
+  PISCES for the biogeochemical processes (``./src/MBG``). :cite:`gmd-8-2465-2015`
 
-These physical engines are described in their respective reference publications that must be cited for 
+These physical engines are described in their respective reference publications that must be cited for
 any work related to their use.
 
@@ -30,14 +33,14 @@
 it offers various features to enable
 
-- 2-way nesting package `AGRIF`_ to create embedded zooms seamlessly
-- Flexible biogeomchemistry with online coarsening and possible integration of a customized model 
-- Versatile data assimilation interface with 3 different modules
-  (tangent linear, observational operators and increments)
+- 2-way nesting package `AGRIF`_ to create :doc:`embedded zooms <zooms>` seamlessly
+- Flexible biogeochemistry with :doc:`online coarsening <coarsening>` and
+  opportunity to integrate an :doc:`alternative model <tracers>`
+- Versatile :doc:`data assimilation interface <data_assimilation>`
 
 lation a efficient XIOS_ server for outputing diagnostics a coupled via OASIS_ to alternative components or other models to enable Earth system modelling.
 
-| Several builtins configurations are provided to assess the skills and performances of the model which
-	can be used as templates for setting up a new configuration (``./cfgs``).
-| The end user could also find some idealised test cases on the web to serve as examples and
+| Several :doc:`builtins configurations <reference_configurations>` are provided to assess the skills and
+	performances of the model which can be used as templates for setting up a new configuration (``./cfgs``).
+| The end user could also find some :doc:`idealised test cases <test_cases>` on the web to serve as examples and
 	to study particular processes (``./tests``).
 
@@ -51,8 +54,8 @@
 | In any case, both formats are available online: `HTML`_ | `PDF`_
 
-| Since 2014 the project has a `Special Issue`_ in the Geoscientific Model Development (GMD) open-access journal
+| Since 2014 the project has a `Special Issue`_ in the open-access journal Geoscientific Model Development (GMD) 
 	from the European Geosciences Union (EGU).
 	The main scope is to collect relevant manuscripts which cover a wide variety of topics like
-   process studies, new parameterizations, implementation of new model features and new NEMO configurations.
+	process studies, new parameterizations, implementation of new model features and new NEMO configurations.
 | Also it provides a single portal to search, discover and understand about
 	the NEMO modelling framework potential and evolution and to submit their contributions. 
@@ -61,50 +64,18 @@
 =====================
 
-| The NEMO Consortium gathering 6 European institutes organises the sustainable development in order to 
-	keep a reliable evolving system since 2008.
+| The NEMO Consortium gathering 6 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_)
+	organises the sustainable development in order to keep a reliable evolving system since 2008.
 | It defines the multi-year development strategy which is implemented by the NEMO System Team.
 
-`Working groups`_ are regularly created or resumed to gather the expertise in the NEMO community in order to 
-focus the development work on a specific subject or major component of NEMO.
+When the need arises, `Working Groups`_ are created or resumed to gather the expertise in the community in order to
+focus the development work on a specific subject or major component of the framework.
 
-Definitions
-===========
+How to cite NEMO
+================
 
-AGRIF
-	*Adaptive Grid Refinement In Fortran*, 
-	package for the integration of full adaptive mesh refinement features within 
-	an existing multidimensional finite difference model
+..	bibliography:: references.bib
+	:all:
+	:style: unsrt
 
-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
-
-.. _AGRIF:          http://agrif.imag.fr
 .. _HTML:           http://www.nemo-ocean.eu/doc
-.. _NEMO:           http://www.nemo-ocean.eu
-.. _OASIS:          http://verc.enes.org/oasis
 .. _PDF:            http://www.nemo-ocean.eu/wp-content/uploads/NEMO_book.pdf
-.. _Special Issue:  http://www.geosci-model-dev.net/special_issue40.html
-.. _Working groups: http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups
-.. _XIOS:           http://forge.ipsl.jussieu.fr/ioserver
Index: /NEMO/trunk/REFERENCES.bib
===================================================================
--- /NEMO/trunk/REFERENCES.bib	(revision 10201)
+++ /NEMO/trunk/REFERENCES.bib	(revision 10201)
@@ -0,0 +1,53 @@
+@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 and NEMO System Team}
+}
+
+@Article{gmd-8-2465-2015,
+   author = {Aumont, O. and Eth\'e, C. and Tagliabue, A. and Bopp, L. and Gehlen, M.},
+   title = {{PISCES}-v2: an ocean biogeochemical model for carbon and ecosystem studies},
+   journal = {Geoscientific Model Development},
+   volume = {8},
+   year = {2015},
+   number = {8},
+   pages = {2465--2513},
+   doi = {10.5194/gmd-8-2465-2015}
+}
+
+@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}
+}
+
+@Article{gmd-8-2991-2015,
+   author = {Rousset, C. and Vancoppenolle, M. and Madec, G. and Fichefet, T. and Flavoni, S. and Barth\'elemy, A. and Benshila, R. and Chanut, J. and Levy, C. and Masson, S. and Vivier, F.},
+   title = {The {L}ouvain-la-{N}euve sea ice model {LIM}3.6: global and regional capabilities},
+   journal = {Geoscientific Model Development},
+   volume = {8},
+   year = {2015},
+   number = {10},
+   pages = {2991--3005},
+   doi = {10.5194/gmd-8-2991-2015}
+}
+
+@Article{vancoppenolle200933,
+   title = "Simulating the mass balance and salinity of Arctic and Antarctic sea ice. 1. Model description and validation",
+   journal = "Ocean Modelling",
+   volume = "27",
+   number = "1–2",
+   pages = "33 - 53",
+   year = "2009",
+   issn = "1463-5003",
+   doi = "10.1016/j.ocemod.2008.10.005",
+   author = "Martin Vancoppenolle and Thierry Fichefet and Hugues Goosse and Sylvain Bouillon and Gurvan Madec and Miguel Angel Morales Maqueda",
+   keywords = "sea ice, model, thickness, salinity, age, arctic, antarctic"
+}
Index: /NEMO/trunk/RELEASE_NOTES.rst
===================================================================
--- /NEMO/trunk/RELEASE_NOTES.rst	(revision 10200)
+++ /NEMO/trunk/RELEASE_NOTES.rst	(revision 10201)
@@ -2,4 +2,6 @@
 What's new in NEMO 4.0
 ======================
+
+.. include:: .global.rst
 
 .. contents::
@@ -46,54 +48,4 @@
 
 Define and install a separate repository for test cases to all easy contributions from the NEMO Users Community
-
-+-------------------+--------------------------------------------------------+------------------------------------+
-| Name              | Purpose                                                | References                         |
-+===================+=================+======================================+====================================+
-| ``CANAL``         | East-west periodic canal of variable size with several |                                    |
-|                   | initial states and associated geostrophic currents     |                                    |
-|                   | (zonal jets or vortex).                                |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``ICEDYN``        | East-west + north-south periodic channel.              |                                    |
-|                   | The common configuration includes an AGRIF zoom (1:3)  |                                    |
-|                   | in the middle of the basin to test how an ice patch is |                                    |
-|                   | advected through it but one can also test the          |                                    |
-|                   | advection schemes (Prather and Ultimate-Macho) by      |                                    |
-|                   | removing the ``key_agrif`` in the CPP keys.            |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``ISOMIP``        | Simple box configuration with an iceshelf with simple  | `Hunter 2006`_                     |
-|                   | geometry on top.                                       |                                    |
-|                   | The purpose of this test case is to evaluate the       |                                    |
-|                   | impact of various schemes and new development with     |                                    |
-|                   | iceshelf cavities.                                     |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``LOCK_EXCHANGE`` | Classical fluid dynamics experiment that has been      | - `Haidvogel and Beckmann 1999`_   |
-|                   | adapted for testing advection schemes in ocean         | - `Burchard and Bolding 2002`_     |
-|                   | circulation models.                                    | - `Ilıcak 2012`_                   |
-|                   | This experiment can in particular illustrate the       |                                    |
-|                   | impact of different choices of numerical schemes       |                                    |
-|                   | and/or subgrid closures on spurious interior mixing.   |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``OVERFLOW``      | Adapted from the non-rotating overflow configuration   | - `Haidvogel and Beckmann 1999`_   |
-|                   | Illustrates the impact of different choices of         | - `Ilıcak 2012`_                   |
-|                   | numerical schemes and/or subgrid closures on spurious  |                                    |
-|                   | interior mixing close to bottom topography.            |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``VORTEX``        | Illustrates the propagation of an anticyclonic eddy    | - `Debreu 2012`_                   |
-|                   | over a Beta plan and flat bottom.                      | - `Penven 2006`_                   |
-|                   | It is implemented here with an online refined          | - `Spall and Holland 1991`_        |
-|                   | subdomain (thanks to AGRIF library) out of which the   |                                    |
-|                   | vortex propagates and serves as a benchmark to         |                                    |
-|                   | diagnose nesting errors.                               |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-| ``WAD``           | 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.                                                 |                                    |
-+-------------------+--------------------------------------------------------+------------------------------------+
-
------------
-Improvments
------------
 
 Core components
@@ -256,12 +208,5 @@
 .. _TOP User Quick Guide:        http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/top-dg/TOP-UserQuickGuide
 
-.. _Hunter 2006:                 http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf
 .. _Brodeau 2017:                http://doi.org/10.1175/JPO-D-16-0169.1
-.. _Haidvogel and Beckmann 1999: http://hdl.handle.net/10013/epic.11761
-.. _Burchard and Bolding 2002:   http://www.researchgate.net/publication/258128069_GETM_A_General_Estuarine_Transport_Model_Scientific_Documentation
-.. _Ilıcak 2012:                 http://doi.org/10.1016/j.ocemod.2011.10.003
-.. _Debreu 2012:                 http://doi.org/10.1016/j.ocemod.2012.03.003
-.. _Penven 2006:                 http://doi.org/10.1016/j.ocemod.2005.05.002
-.. _Spall and Holland 1991:      http://www.researchgate.net/publication/232101325_A_Nested_Primitive_Equation_Model_for_Oceanic_Applications
 .. _Holland 2012:                http://doi.org/10.1175/JCLI-D-11-00078.1
 .. _Lupkes 2012:                 http://doi.org/10.1029/2012JD017630
Index: /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst
===================================================================
--- /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10201)
+++ /NEMO/trunk/cfgs/AGRIF_DEMO/README.rst	(revision 10201)
@@ -0,0 +1,112 @@
+Embedded zooms with AGRIF
+=========================
+
+.. include:: .global.rst
+
+.. 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
Index: /NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib
===================================================================
--- /NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib	(revision 10201)
+++ /NEMO/trunk/cfgs/AGRIF_DEMO/zooms.bib	(revision 10201)
@@ -0,0 +1,35 @@
+@article{DEBREU20121,
+   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{PENVEN2006157,
+   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{doi:10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2,
+   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/trunk/cfgs/README.rst
===================================================================
--- /NEMO/trunk/cfgs/README.rst	(revision 10201)
+++ /NEMO/trunk/cfgs/README.rst	(revision 10201)
@@ -0,0 +1,365 @@
+=====================
+Build a configuration
+=====================
+
+.. include:: .global.rst
+
+.. contents::
+	:local:
+	:depth: 1
+      
+.. role:: underline 
+   :class: underline
+
+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 Reference 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
+.. _NEMO Reference manual:        http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO
+.. _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/trunk/cfgs/SHARED/README.rst
===================================================================
--- /NEMO/trunk/cfgs/SHARED/README.rst	(revision 10201)
+++ /NEMO/trunk/cfgs/SHARED/README.rst	(revision 10201)
@@ -0,0 +1,107 @@
+Inputs-Outputs with XIOS
+========================
+
+.. include:: .global.rst
+
+.. contents::
+
+| 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 `Reference 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 documentation`_ to compile it.
+   If you find problems at this stage, support can be found by subscribing to the `XIOS users mailing list`_ 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 to NEMO
+------------------------------
+
+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/trunk/doc/namelists/namage
===================================================================
--- /NEMO/trunk/doc/namelists/namage	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namage	(revision 10201)
@@ -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/trunk/doc/namelists/namalb
===================================================================
--- /NEMO/trunk/doc/namelists/namalb	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namalb	(revision 10201)
@@ -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/trunk/doc/namelists/namdia
===================================================================
--- /NEMO/trunk/doc/namelists/namdia	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namdia	(revision 10201)
@@ -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/trunk/doc/namelists/namdyn
===================================================================
--- /NEMO/trunk/doc/namelists/namdyn	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namdyn	(revision 10201)
@@ -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/trunk/doc/namelists/namdyn_rdgrft
===================================================================
--- /NEMO/trunk/doc/namelists/namdyn_rdgrft	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namdyn_rdgrft	(revision 10201)
@@ -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/trunk/doc/namelists/namdyn_rhg
===================================================================
--- /NEMO/trunk/doc/namelists/namdyn_rhg	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namdyn_rhg	(revision 10201)
@@ -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/trunk/doc/namelists/namforcing
===================================================================
--- /NEMO/trunk/doc/namelists/namforcing	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namforcing	(revision 10201)
@@ -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/trunk/doc/namelists/namini
===================================================================
--- /NEMO/trunk/doc/namelists/namini	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namini	(revision 10201)
@@ -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/trunk/doc/namelists/namitd
===================================================================
--- /NEMO/trunk/doc/namelists/namitd	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namitd	(revision 10201)
@@ -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/trunk/doc/namelists/nampar
===================================================================
--- /NEMO/trunk/doc/namelists/nampar	(revision 10201)
+++ /NEMO/trunk/doc/namelists/nampar	(revision 10201)
@@ -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/trunk/doc/namelists/namthd
===================================================================
--- /NEMO/trunk/doc/namelists/namthd	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd	(revision 10201)
@@ -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/trunk/doc/namelists/namthd_da
===================================================================
--- /NEMO/trunk/doc/namelists/namthd_da	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd_da	(revision 10201)
@@ -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/trunk/doc/namelists/namthd_do
===================================================================
--- /NEMO/trunk/doc/namelists/namthd_do	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd_do	(revision 10201)
@@ -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/trunk/doc/namelists/namthd_pnd
===================================================================
--- /NEMO/trunk/doc/namelists/namthd_pnd	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd_pnd	(revision 10201)
@@ -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/trunk/doc/namelists/namthd_sal
===================================================================
--- /NEMO/trunk/doc/namelists/namthd_sal	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd_sal	(revision 10201)
@@ -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/trunk/doc/namelists/namthd_zdf
===================================================================
--- /NEMO/trunk/doc/namelists/namthd_zdf	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namthd_zdf	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_adv
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_adv	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_adv	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_bc
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_bc	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_bc	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_bdy
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_bdy	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_bdy	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_dmp
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_dmp	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_dmp	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_dta
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_dta	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_dta	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_ice
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_ice	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_ice	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_ldf
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_ldf	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_ldf	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_rad
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_rad	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_rad	(revision 10201)
@@ -0,0 +1,5 @@
+!-----------------------------------------------------------------------
+&namtrc_rad      !  treatment of negative concentrations 
+!-----------------------------------------------------------------------
+   ln_trcrad     =  .true.   !  artificially correct negative concentrations (T) or not (F)
+/
Index: /NEMO/trunk/doc/namelists/namtrc_run
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_run	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_run	(revision 10201)
@@ -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/trunk/doc/namelists/namtrc_trd
===================================================================
--- /NEMO/trunk/doc/namelists/namtrc_trd	(revision 10201)
+++ /NEMO/trunk/doc/namelists/namtrc_trd	(revision 10201)
@@ -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/trunk/doc/rst/source/.global.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/.global.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/.global.rst	(revision 10201)
@@ -0,0 +1,35 @@
+.. Roles (custom styles related to CSS classes)
+
+.. role:: rstblue
+.. role:: rstgreen
+.. role:: rstgrey
+.. role:: rstgreysup(sup)
+
+.. Links
+
+	.. 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
+
+	.. NEMO
+
+.. _NEMO:             http://www.nemo-ocean.eu
+.. _Reference Manual: http://doi.org/10.5281/zenodo.1137733
+.. _Special Issue:    http://www.geosci-model-dev.net/special_issue40.html
+.. _Working Groups:   http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups
+
+	.. XIOS
+
+.. _XIOS:                    http://forge.ipsl.jussieu.fr/ioserver
+.. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
+.. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users
Index: /NEMO/trunk/doc/rst/source/NEMO_guide.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/NEMO_guide.rst	(revision 10201)
@@ -4,7 +4,18 @@
    contain the root `toctree` directive.
 
-=================
+#################
 Quick Start Guide
-=================
+#################
+
+..
+	A hidden .global.rst should be included in every subfiles with `include` directive
+   It contains a list of common URL links 
+     
+.. include:: .global.rst
+
+.. include:: readme.rst
+
+Summary
+=======
 
 .. toctree::
@@ -18,12 +29,19 @@
 	setup_configuration.rst
 	interfacing_options.rst
-	references.rst
+	definitions.rst
 
-.. include:: readme.rst
+..
+   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
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+..
+	Indices and tables
+	==================
+	* :ref:`genindex`
+	* :ref:`modindex`
+	* :ref:`search`
Index: MO/trunk/doc/rst/source/README-setup-configs
===================================================================
--- /NEMO/trunk/doc/rst/source/README-setup-configs	(revision 10200)
+++ 	(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/trunk/doc/rst/source/coarsening.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/coarsening.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/coarsening.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../src/OCE/CRS/README.rst
Index: /NEMO/trunk/doc/rst/source/conf.py
===================================================================
--- /NEMO/trunk/doc/rst/source/conf.py	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/conf.py	(revision 10201)
@@ -25,7 +25,7 @@
 
 # The short X.Y version
-version = ''
+version = '4.0'
 # The full version, including alpha/beta/rc tags
-release = '4.0'
+release = '4.0rc'
 
 
@@ -39,6 +39,5 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ['sphinxcontrib.bibtex']
 
 # Add any paths that contain templates here, relative to this directory.
Index: /NEMO/trunk/doc/rst/source/coupling.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/coupling.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/coupling.rst	(revision 10201)
@@ -0,0 +1,14 @@
+Coupling with other models (OASIS, SAS, ...)
+============================================
+
+.. include:: .global.rst
+
+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/trunk/doc/rst/source/data_assimilation.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/data_assimilation.rst	(revision 10201)
@@ -0,0 +1,66 @@
+Data assimilation
+=================
+
+.. include:: .global.rst
+
+.. 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 reference 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 reference 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 reference 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 reference 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.
+
+.. _NEMO reference manual: http://doi.org/10.5281/zenodo.
Index: /NEMO/trunk/doc/rst/source/definitions.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/definitions.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/definitions.rst	(revision 10201)
@@ -0,0 +1,35 @@
+===========
+Definitions
+===========
+
+.. include:: .global.rst
+
+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/trunk/doc/rst/source/input-output.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/input-output.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/input-output.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/SHARED/README.rst
Index: /NEMO/trunk/doc/rst/source/interfacing_options.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/interfacing_options.rst	(revision 10201)
@@ -3,454 +3,29 @@
 ===================
 
+.. include:: .global.rst
+
 .. contents::
 	:local:
 	:depth: 1
-           
-Embedded zooms with 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
-----------
-
-`Debreu, L., P. Marchesiello, P. Penven and G. Cambon, 2012: Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation. Ocean Modelling, 49-50, 1-21. <http://doi.org/10.1016/j.ocemod.2012.03.003>`_
-
-`Penven, P., L. Debreu, P. Marchesiello and J. C. Mc Williams, 2006: Evaluation and application of the ROMS 1-way embedding procedure to the central california upwelling system. Ocean Modelling, 12, 157-187. <http://doi.org/10.1016/j.ocemod.2005.05.002>`_
-
-`Spall, M. A. and W. R. Holland, 1991: A Nested Primitive Equation Model for Oceanic Applications. J. Phys. Ocean., 21, 205-220. <https://doi.org/10.1175/1520-0485(1991)021\<0205:ANPEMF\>2.0.CO;2>`_
+.. include:: zooms.rst
 
 ----
 
-On line biogeochemistry coarsening
-==================================
-
-.. contents::
-   :local:
-
-.. role:: underline 
-   :class: underline
-
-------------
-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
----------------------------------------------
-
-:underline:`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``.
-
-:underline:`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]
-
-:underline:`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 ].
-
-:underline:`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
-
-:underline:`PISCES forcing files`
-
-They might be on the coarsened grid.
-
-:underline:`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
+.. include:: coarsening.rst
 
 ----
 
-Coupling with other models (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``.
+.. include:: coupling.rst
 
 ----
 
-With data assimilation
-======================
-
-.. 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 reference 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 reference 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 reference 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 reference 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.
+.. include:: data_assimilation.rst
 
 ----
 
-Inputs-Outputs (using XIOS)
-===========================
+.. include:: input-output.rst
 
-.. 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 reference 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 documentation`_ to compile it.
-   If you find problems at this stage, support can be found by subscribing to the `XIOS users mailing list`_ 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 to NEMO
-------------------------------
-
-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.
-
-.. _NEMO reference manual:   http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO
-.. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation
-.. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users
+.. include:: tracers.rst
Index: /NEMO/trunk/doc/rst/source/reference_configurations.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/reference_configurations.rst	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/reference_configurations.rst	(revision 10201)
@@ -1,364 +1,1 @@
-=====================
-Build a configuration
-=====================
-
-.. contents::
-	:local:
-	:depth: 1
-      
-.. role:: underline 
-   :class: underline
-
-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 `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html>`_
-monthly mean outputs of 1 year run
-
-----------------
-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
-  `here <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 Reference 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
-.. _NEMO Reference manual:        http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO
-.. _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
+link ../../../cfgs/README.rst
Index: MO/trunk/doc/rst/source/references.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/references.rst	(revision 10200)
+++ 	(revision )
@@ -1,1 +1,0 @@
-link ../../../REFERENCES.rst
Index: /NEMO/trunk/doc/rst/source/setup_configuration.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/setup_configuration.rst	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/setup_configuration.rst	(revision 10201)
@@ -1,254 +1,1 @@
-==============================
-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
+link ../../../src/OCE/USR/README.rst
Index: /NEMO/trunk/doc/rst/source/test_cases.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/test_cases.rst	(revision 10200)
+++ /NEMO/trunk/doc/rst/source/test_cases.rst	(revision 10201)
@@ -1,23 +1,1 @@
-======================
-Explore the test cases
-======================
-
-- ``tests/ICEDYN``:
-  
-  [Clement to add an illustration here ?]
-
-  This is an East-west + north-south periodic channel.
-  The configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how
-  an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by
-  removing the ``key_agrif`` in the CPP keys.
-
-- ``tests/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),
-  Penven et al. (2006) or Spall and Holland (1991).
-  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
+link ../../../tests/README.rst
Index: /NEMO/trunk/doc/rst/source/tools.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/tools.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/tools.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../tools/README.rst
Index: /NEMO/trunk/doc/rst/source/tracers.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/tracers.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/tracers.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../src/TOP/README.rst
Index: /NEMO/trunk/doc/rst/source/zooms.bib
===================================================================
--- /NEMO/trunk/doc/rst/source/zooms.bib	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/zooms.bib	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/zooms.bib
Index: /NEMO/trunk/doc/rst/source/zooms.rst
===================================================================
--- /NEMO/trunk/doc/rst/source/zooms.rst	(revision 10201)
+++ /NEMO/trunk/doc/rst/source/zooms.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../cfgs/AGRIF_DEMO/README.rst
Index: /NEMO/trunk/src/OCE/ASM/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/ASM/README.rst	(revision 10201)
+++ /NEMO/trunk/src/OCE/ASM/README.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/data_assimilation.rst
Index: /NEMO/trunk/src/OCE/CRS/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/CRS/README.rst	(revision 10201)
+++ /NEMO/trunk/src/OCE/CRS/README.rst	(revision 10201)
@@ -0,0 +1,142 @@
+On line biogeochemistry coarsening
+==================================
+
+.. include:: .global.rst
+
+.. contents::
+   :local:
+
+.. role:: underline 
+   :class: underline
+
+------------
+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
+---------------------------------------------
+
+:underline:`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``.
+
+:underline:`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]
+
+:underline:`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 ].
+
+:underline:`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
+
+:underline:`PISCES forcing files`
+
+They might be on the coarsened grid.
+
+:underline:`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/trunk/src/OCE/OBS/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/OBS/README.rst	(revision 10201)
+++ /NEMO/trunk/src/OCE/OBS/README.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/data_assimilation.rst
Index: /NEMO/trunk/src/OCE/SBC/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/SBC/README.rst	(revision 10201)
+++ /NEMO/trunk/src/OCE/SBC/README.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../../doc/rst/source/coupling.rst
Index: /NEMO/trunk/src/OCE/USR/README-setup-configs
===================================================================
--- /NEMO/trunk/src/OCE/USR/README-setup-configs	(revision 10201)
+++ /NEMO/trunk/src/OCE/USR/README-setup-configs	(revision 10201)
@@ -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/trunk/src/OCE/USR/README.rst
===================================================================
--- /NEMO/trunk/src/OCE/USR/README.rst	(revision 10201)
+++ /NEMO/trunk/src/OCE/USR/README.rst	(revision 10201)
@@ -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/trunk/src/SAS/README.rst
===================================================================
--- /NEMO/trunk/src/SAS/README.rst	(revision 10201)
+++ /NEMO/trunk/src/SAS/README.rst	(revision 10201)
@@ -0,0 +1,1 @@
+link ../../doc/rst/source/coupling.rst
Index: /NEMO/trunk/src/TOP/README.rst
===================================================================
--- /NEMO/trunk/src/TOP/README.rst	(revision 10201)
+++ /NEMO/trunk/src/TOP/README.rst	(revision 10201)
@@ -0,0 +1,368 @@
+TOP interface
+=============
+
+.. include:: .global.rst
+
+.. 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/trunk/tests/README.rst
===================================================================
--- /NEMO/trunk/tests/README.rst	(revision 10201)
+++ /NEMO/trunk/tests/README.rst	(revision 10201)
@@ -0,0 +1,60 @@
+======================
+Explore the test cases
+======================
+
+.. include:: .global.rst
+
+``CANAL``
+	| [Illustration here ?]
+	| East-west periodic canal of variable size with several initial states and associated geostrophic currents
+		(zonal jets or vortex).
+
+``ICEDYN``
+	| [Illustration here ?]
+	| East-west + north-south periodic channel inlcuding an AGRIF zoom (1:3) in the middle of the basin to test how
+		an ice patch is advected through it but one can also test the advection schemes
+		(Prather and Ultimate-Macho) by removing the ``key_agrif`` in the CPP keys.
+
+``ISOMIP``
+	| [Illustration here ?]
+	| Simple box configuration with an iceshelf with simple geometry on top to evaluate the impact of
+		various schemes and new development with iceshelf cavities.
+	| `test cavities <http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf>`_
+
+``LOCK_EXCHANGE``
+	| [Illustration here ?]
+	| Classical fluid dynamics experiment that has been adapted for testing advection schemes in
+		ocean circulation models.
+	| This experiment can in particular illustrate the impact of different choices of numerical schemes and/or
+		subgrid closures on spurious interior mixing.
+	| :cite:`epic31172,burchard2002getm,ILICAK201237`
+
+``OVERFLOW``
+	| [Illustration here ?]
+	| Adapted from the non-rotating overflow configuration,
+		it illustrates the impact of different choices of numerical schemes and/or subgrid closures on
+		spurious interior mixing close to bottom topography.
+	| :cite:`epic31172,ILICAK201237`
+
+``VORTEX``
+	.. figure:: _static/VORTEX_anim.gif
+
+		Vortex smoothly propagates out of two 1:2 successive nested grids (sea level anomaly in meters)
+
+	| Illustrates the propagation of an anticyclonic eddy over a Beta plan and flat bottom.
+	| It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates and
+		serves as a benchmark to diagnose nesting errors.
+	| :cite:`DEBREU20121,PENVEN2006157,SPALL1991205`
+
+``WAD``
+	| [Illustration here ?]
+	| 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.
+
+References
+==========
+
+.. bibliography:: test_cases.bib
+	:all:
+	:style: unsrt
Index: /NEMO/trunk/tests/test_cases.bib
===================================================================
--- /NEMO/trunk/tests/test_cases.bib	(revision 10201)
+++ /NEMO/trunk/tests/test_cases.bib	(revision 10201)
@@ -0,0 +1,61 @@
+@book{epic31172,
+   author = {D. B. Haidvogel and A. Beckmann},
+   publisher = {Imperial College Press, London},
+   year = {1999},
+   title = {Numerical ocean circulation modeling}
+}
+
+@book{burchard2002getm,
+   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{ILICAK201237,
+   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 Ilıcak 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{DEBREU20121,
+   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{PENVEN2006157,
+   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{SPALL1991205,
+   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},
+}
