Changeset 10186 for NEMO/trunk

Timestamp:

2018-10-09T18:46:38+02:00 (6 years ago)

Author:

nicolasmartin

Message:

Preliminary implementation of a NEMO Quick Start Guide via RST files and Sphinx installation

Location:

NEMO/trunk/doc/rst

Files:

• Makefile (added)
• build (added)
• source (added)
• source/NEMO_guide.rst (added)
• source/_static (added)
• source/_static/AGRIF_DEMO.jpg (added)
• source/_static/NEMO_grey.png (added)
• source/_static/ORCA.ico (added)
• source/_static/VORTEX_anim.gif (added)
• source/_static/agrif_grid_position.jpg (added)
• source/_static/crs_wiki_1.1.pdf (added)
• source/_static/file_crs_def.xml (added)
• source/_static/file_def.xml (added)
• source/_static/iodef.xml (added)
• source/_templates (added)
• source/conf.py (added)
• source/install.rst (added)
• source/interfacing_options.rst (moved) (moved from NEMO/trunk/doc/rst/model_interfacing.rst) (1 diff)
• source/readme.rst (added)
• source/reference_configurations.rst (moved) (moved from NEMO/trunk/doc/rst/reference_configurations.rst) (1 diff)
• source/references.rst (added)
• source/release_notes.rst (added)
• source/setup_configuration.rst (moved) (moved from NEMO/trunk/doc/rst/setup_configuration.rst) (1 diff)
• source/test_cases.rst (moved) (moved from NEMO/trunk/doc/rst/test_cases.rst) (1 diff)

NEMO/trunk/doc/rst/source/interfacing_options.rst

@@ +1 @@
+===================
+Interfacing options
+===================
+
+.. 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>`_
+
+----
+
+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
+
+----
+
+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``.
+
+----
+
+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.
+
+----
+
+Inputs-Outputs (using XIOS)
+===========================
+
+.. contents::
+   :local:
+
+| Output of diagnostics in NEMO is usually done using XIOS.
+  This is an efficient way of writing diagnostics because the time averaging, file writing and even
+  some simple arithmetic or regridding is carried out in parallel to the NEMO model run.
+| This page gives a basic introduction to using XIOS with NEMO.
+  Much more information is available from the XIOS homepage above and from the `NEMO 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

NEMO/trunk/doc/rst/source/reference_configurations.rst

@@ +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

NEMO/trunk/doc/rst/source/setup_configuration.rst

@@ +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

NEMO/trunk/doc/rst/source/test_cases.rst

@@ +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