New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
Changeset 10201 – NEMO

Changeset 10201


Ignore:
Timestamp:
2018-10-18T12:53:04+02:00 (4 years ago)
Author:
nicolasmartin
Message:

Various modifications related to the setting of a NEMO Quick Start Guide

  • Add missing namelist blocks from ICE and TOP
  • Create a hidden .global.rst to gather common URL links
  • Convert animated gif to frames images for PDF export
  • Place different README.rst appropriately in the code structure and refer to them with symbolic links in doc/rst/source
Location:
NEMO/trunk
Files:
152 added
1 deleted
7 edited
3 copied
1 moved

Legend:

Unmodified
Added
Removed

  • NEMO/trunk/INSTALL.rst

    r10187 r10201  
    22Install the framework 
    33===================== 
     4 
     5.. include:: .global.rst 
    46 
    57.. contents:: \ 
    … …  
    116118More options 
    117119 
    118 .. includefile:: 
    119  
    120     
     120.. 
     121   .. literalinclude:: 
    121122 
    122123----------------- 
    … …  
    166167----------------- 
    167168 
    168 Once makenemo has run successfully, the opa executable is available in CONFIG/"MY_CONFIG"/EXP00 
    169 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 
     169Once makenemo has run successfully, the opa executable is available in ``CONFIG/MY_CONFIG/EXP00`` 
     170For 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 
    170171 
    171172   cd 'MY_CONFIG'/EXP00 

  • NEMO/trunk/README.rst

    r10187 r10201  
    1 .. role:: rstblue 
    2 .. role:: rstgreen 
    3 .. role:: rstgrey 
    4 .. role:: rstgreysup(sup) 
     1.. include:: .global.rst 
    52 
     3:Release: |release| 
     4:Date:    |today| 
     5             
    66NEMO for *Nucleus for European Modelling of the Ocean* is a state-of-the-art modelling framework of  
    77ocean related engines for oceanographic research, operational oceanography, seasonal forecast and  
    88[paleo]climate studies. 
     9 
     10.. contents:: 
     11   :local: 
    912 
    1013Overview 
    … …  
    1518 
    1619- :rstblue:`OPA` is fundamental to all users by modelling the ocean [thermo]dynamics and  
    17   solving the primitive equations         (``./src/OCE``);  
     20  solving the primitive equations         (``./src/OCE``); :cite:`madec_bk08` 
    1821- :rstgrey:`SI`\ :rstgreysup:`3` for sea-ice simulates ice [thermo]dynamics, brine inclusions and  
    19   subgrid-scale thickness variations      (``./src/ICE``);  
     22  subgrid-scale thickness variations      (``./src/ICE``); :cite:`gmd-8-2991-2015,vancoppenolle200933` 
    2023- :rstgreen:`TOP-PISCES` models biogeochemistry with TOP for the on/offline oceanic tracers transport and  
    21   PISCES for the biogeochemical processes (``./src/MBG``). 
     24  PISCES for the biogeochemical processes (``./src/MBG``). :cite:`gmd-8-2465-2015` 
    2225 
    23 These physical engines are described in their respective reference publications that must be cited for  
     26These physical engines are described in their respective reference publications that must be cited for 
    2427any work related to their use. 
    2528 
    … …  
    3033it offers various features to enable 
    3134 
    32 - 2-way nesting package `AGRIF`_ to create embedded zooms seamlessly 
    33 - Flexible biogeomchemistry with online coarsening and possible integration of a customized model  
    34 - Versatile data assimilation interface with 3 different modules 
    35   (tangent linear, observational operators and increments) 
     35- 2-way nesting package `AGRIF`_ to create :doc:`embedded zooms <zooms>` seamlessly 
     36- Flexible biogeochemistry with :doc:`online coarsening <coarsening>` and 
     37  opportunity to integrate an :doc:`alternative model <tracers>` 
     38- Versatile :doc:`data assimilation interface <data_assimilation>` 
    3639 
    3740lation a efficient XIOS_ server for outputing diagnostics a coupled via OASIS_ to alternative components or other models to enable Earth system modelling. 
    3841 
    39 | Several builtins configurations are provided to assess the skills and performances of the model which 
    40    can be used as templates for setting up a new configuration (``./cfgs``). 
    41 | The end user could also find some idealised test cases on the web to serve as examples and 
     42| Several :doc:`builtins configurations <reference_configurations>` are provided to assess the skills and 
     43   performances of the model which can be used as templates for setting up a new configuration (``./cfgs``). 
     44| The end user could also find some :doc:`idealised test cases <test_cases>` on the web to serve as examples and 
    4245   to study particular processes (``./tests``). 
    4346 
    … …  
    5154| In any case, both formats are available online: `HTML`_ | `PDF`_ 
    5255 
    53 | Since 2014 the project has a `Special Issue`_ in the Geoscientific Model Development (GMD) open-access journal 
     56| Since 2014 the project has a `Special Issue`_ in the open-access journal Geoscientific Model Development (GMD)  
    5457   from the European Geosciences Union (EGU). 
    5558   The main scope is to collect relevant manuscripts which cover a wide variety of topics like 
    56    process studies, new parameterizations, implementation of new model features and new NEMO configurations. 
     59   process studies, new parameterizations, implementation of new model features and new NEMO configurations. 
    5760| Also it provides a single portal to search, discover and understand about 
    5861   the NEMO modelling framework potential and evolution and to submit their contributions.  
    … …  
    6164===================== 
    6265 
    63 | The NEMO Consortium gathering 6 European institutes organises the sustainable development in order to  
    64    keep a reliable evolving system since 2008. 
     66| The NEMO Consortium gathering 6 European institutes (`CMCC`_, `CNRS`_, `MOI`_, `Met Office`_ and `NERC`_) 
     67   organises the sustainable development in order to keep a reliable evolving system since 2008. 
    6568| It defines the multi-year development strategy which is implemented by the NEMO System Team. 
    6669 
    67 `Working groups`_ are regularly created or resumed to gather the expertise in the NEMO community in order to  
    68 focus the development work on a specific subject or major component of NEMO. 
     70When the need arises, `Working Groups`_ are created or resumed to gather the expertise in the community in order to 
     71focus the development work on a specific subject or major component of the framework. 
    6972 
    70 Definitions 
    71 =========== 
     73How to cite NEMO 
     74================ 
    7275 
    73 AGRIF 
    74    *Adaptive Grid Refinement In Fortran*,  
    75    package for the integration of full adaptive mesh refinement features within  
    76    an existing multidimensional finite difference model 
     76.. bibliography:: references.bib 
     77   :all: 
     78   :style: unsrt 
    7779 
    78 SI\ :sup:`3`\  
    79    *Sea Ice Integrated Initiative*,  
    80    unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
    81  
    82 OASIS 
    83    *Ocean Atmosphere Sea Ice Soil*,  
    84    coupling software to synchronise numerical codes representing different components of the climate system 
    85  
    86 PISCES 
    87    *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,  
    88    biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients 
    89  
    90 TAM 
    91    *Tangent linear and Adjoint Model*,  
    92    tools to analyse and control the NEMO dynamical core for a wide range of applications such as 
    93    sensitivity analysis, parameter estimation, vectors computation or data assimilation. 
    94  
    95 TOP 
    96    *Tracers in Ocean Paradigm*,  
    97    on/off-line oceanic tracers transport and biogeochemistry models 
    98  
    99 XIOS 
    100    *XML Input Output Server*,  
    101    library dedicated to input/output management of climate code 
    102  
    103 .. _AGRIF:          http://agrif.imag.fr 
    10480.. _HTML:           http://www.nemo-ocean.eu/doc 
    105 .. _NEMO:           http://www.nemo-ocean.eu 
    106 .. _OASIS:          http://verc.enes.org/oasis 
    10781.. _PDF:            http://www.nemo-ocean.eu/wp-content/uploads/NEMO_book.pdf 
    108 .. _Special Issue:  http://www.geosci-model-dev.net/special_issue40.html 
    109 .. _Working groups: http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups 
    110 .. _XIOS:           http://forge.ipsl.jussieu.fr/ioserver 

  • NEMO/trunk/RELEASE_NOTES.rst

    r10187 r10201  
    22What's new in NEMO 4.0 
    33====================== 
     4 
     5.. include:: .global.rst 
    46 
    57.. contents:: 
    … …  
    4648 
    4749Define and install a separate repository for test cases to all easy contributions from the NEMO Users Community 
    48  
    49 +-------------------+--------------------------------------------------------+------------------------------------+ 
    50 | Name              | Purpose                                                | References                         | 
    51 +===================+=================+======================================+====================================+ 
    52 | ``CANAL``         | East-west periodic canal of variable size with several |                                    | 
    53 |                   | initial states and associated geostrophic currents     |                                    | 
    54 |                   | (zonal jets or vortex).                                |                                    | 
    55 +-------------------+--------------------------------------------------------+------------------------------------+ 
    56 | ``ICEDYN``        | East-west + north-south periodic channel.              |                                    | 
    57 |                   | The common configuration includes an AGRIF zoom (1:3)  |                                    | 
    58 |                   | in the middle of the basin to test how an ice patch is |                                    | 
    59 |                   | advected through it but one can also test the          |                                    | 
    60 |                   | advection schemes (Prather and Ultimate-Macho) by      |                                    | 
    61 |                   | removing the ``key_agrif`` in the CPP keys.            |                                    | 
    62 +-------------------+--------------------------------------------------------+------------------------------------+ 
    63 | ``ISOMIP``        | Simple box configuration with an iceshelf with simple  | `Hunter 2006`_                     | 
    64 |                   | geometry on top.                                       |                                    | 
    65 |                   | The purpose of this test case is to evaluate the       |                                    | 
    66 |                   | impact of various schemes and new development with     |                                    | 
    67 |                   | iceshelf cavities.                                     |                                    | 
    68 +-------------------+--------------------------------------------------------+------------------------------------+ 
    69 | ``LOCK_EXCHANGE`` | Classical fluid dynamics experiment that has been      | - `Haidvogel and Beckmann 1999`_   | 
    70 |                   | adapted for testing advection schemes in ocean         | - `Burchard and Bolding 2002`_     | 
    71 |                   | circulation models.                                    | - `Ilıcak 2012`_                   | 
    72 |                   | This experiment can in particular illustrate the       |                                    | 
    73 |                   | impact of different choices of numerical schemes       |                                    | 
    74 |                   | and/or subgrid closures on spurious interior mixing.   |                                    | 
    75 +-------------------+--------------------------------------------------------+------------------------------------+ 
    76 | ``OVERFLOW``      | Adapted from the non-rotating overflow configuration   | - `Haidvogel and Beckmann 1999`_   | 
    77 |                   | Illustrates the impact of different choices of         | - `Ilıcak 2012`_                   | 
    78 |                   | numerical schemes and/or subgrid closures on spurious  |                                    | 
    79 |                   | interior mixing close to bottom topography.            |                                    | 
    80 +-------------------+--------------------------------------------------------+------------------------------------+ 
    81 | ``VORTEX``        | Illustrates the propagation of an anticyclonic eddy    | - `Debreu 2012`_                   | 
    82 |                   | over a Beta plan and flat bottom.                      | - `Penven 2006`_                   | 
    83 |                   | It is implemented here with an online refined          | - `Spall and Holland 1991`_        | 
    84 |                   | subdomain (thanks to AGRIF library) out of which the   |                                    | 
    85 |                   | vortex propagates and serves as a benchmark to         |                                    | 
    86 |                   | diagnose nesting errors.                               |                                    | 
    87 +-------------------+--------------------------------------------------------+------------------------------------+ 
    88 | ``WAD``           | Set of simple closed basin geometries for testing the  |                                    | 
    89 |                   | wetting and drying capabilities.                       |                                    | 
    90 |                   | Examples range from a closed channel with EW linear    |                                    | 
    91 |                   | bottom slope to a parabolic EW channel with a Gaussian |                                    | 
    92 |                   | ridge.                                                 |                                    | 
    93 +-------------------+--------------------------------------------------------+------------------------------------+ 
    94  
    95 ----------- 
    96 Improvments 
    97 ----------- 
    9850 
    9951Core components 
    … …  
    256208.. _TOP User Quick Guide:        http://forge.ipsl.jussieu.fr/nemo/wiki/WorkingGroups/top-dg/TOP-UserQuickGuide 
    257209 
    258 .. _Hunter 2006:                 http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf 
    259210.. _Brodeau 2017:                http://doi.org/10.1175/JPO-D-16-0169.1 
    260 .. _Haidvogel and Beckmann 1999: http://hdl.handle.net/10013/epic.11761 
    261 .. _Burchard and Bolding 2002:   http://www.researchgate.net/publication/258128069_GETM_A_General_Estuarine_Transport_Model_Scientific_Documentation 
    262 .. _Ilıcak 2012:                 http://doi.org/10.1016/j.ocemod.2011.10.003 
    263 .. _Debreu 2012:                 http://doi.org/10.1016/j.ocemod.2012.03.003 
    264 .. _Penven 2006:                 http://doi.org/10.1016/j.ocemod.2005.05.002 
    265 .. _Spall and Holland 1991:      http://www.researchgate.net/publication/232101325_A_Nested_Primitive_Equation_Model_for_Oceanic_Applications 
    266211.. _Holland 2012:                http://doi.org/10.1175/JCLI-D-11-00078.1 
    267212.. _Lupkes 2012:                 http://doi.org/10.1029/2012JD017630 

  • NEMO/trunk/cfgs/README.rst

    r10186 r10201  
    22Build a configuration 
    33===================== 
     4 
     5.. include:: .global.rst 
    46 
    57.. contents:: 
    … …  
    201203(``./cfgs/GYRE`` and ``./cfgs/GYRE/EXP00``). 
    202204 
    203 Find `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html>`_ 
    204 monthly mean outputs of 1 year run 
     205Find monthly mean outputs of 1 year run here: 
     206http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html 
    205207 
    206208---------------- 
    … …  
    284286| NEMO allows to use the interpolation on the fly option allowing to interpolate input data during the run. 
    285287  If you want to use this option you need files giving informations on weights, which have been created. 
    286 | You can find 
    287   `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/WEIGHTS/catalog.html>`_ 
     288| You can find at http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/WEIGHTS/catalog.html 
    288289  2 weights files `bil_weights` for scalar field (bilinear interpolation) and `bic_weights` for 
    289290  vector field (bicubic interpolation). 

  • NEMO/trunk/doc/rst/build

    • Property svn:ignore set to
      *

  • NEMO/trunk/doc/rst/source/NEMO_guide.rst

    r10186 r10201  
    44   contain the root `toctree` directive. 
    55 
    6 ================= 
     6################# 
    77Quick Start Guide 
    8 ================= 
     8################# 
     9 
     10.. 
     11   A hidden .global.rst should be included in every subfiles with `include` directive 
     12   It contains a list of common URL links  
     13      
     14.. include:: .global.rst 
     15 
     16.. include:: readme.rst 
     17 
     18Summary 
     19======= 
    920 
    1021.. toctree:: 
    … …  
    1829   setup_configuration.rst 
    1930   interfacing_options.rst 
    20    references.rst 
     31   definitions.rst 
    2132 
    22 .. include:: readme.rst 
     33.. 
     34   For headings markup, this convention is recommended from Python’s Style Guide 
     35   # with overline, for parts 
     36   * with overline, for chapters 
     37   =, for sections 
     38   -, for subsections 
     39   ^, for subsubsections 
     40   ", for paragraphs 
    2341 
    24 Indices and tables 
    25 ================== 
    26  
    27 * :ref:`genindex` 
    28 * :ref:`modindex` 
    29 * :ref:`search` 
     42.. 
     43   Indices and tables 
     44   ================== 
     45   * :ref:`genindex` 
     46   * :ref:`modindex` 
     47   * :ref:`search` 

  • NEMO/trunk/doc/rst/source/conf.py

    r10186 r10201  
    2525 
    2626# The short X.Y version 
    27 version = '' 
     27version = '4.0' 
    2828# The full version, including alpha/beta/rc tags 
    29 release = '4.0' 
     29release = '4.0rc' 
    3030 
    3131 
    … …  
    3939# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 
    4040# ones. 
    41 extensions = [ 
    42 ] 
     41extensions = ['sphinxcontrib.bibtex'] 
    4342 
    4443# Add any paths that contain templates here, relative to this directory. 

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

    r10186 r10201  
    33=================== 
    44 
     5.. include:: .global.rst 
     6 
    57.. contents:: 
    68   :local: 
    79   :depth: 1 
    8             
    9 Embedded zooms with AGRIF 
    10 ========================= 
    1110 
    12 .. contents:: 
    13    :local: 
    14  
    15 -------- 
    16 Overview 
    17 -------- 
    18  
    19 AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over 
    20 rectangular regions in NEMO. 
    21 Refinement factors can be odd or even (usually lower than 5 to maintain stability). 
    22 Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and 
    23 the child grid provides volume averages of prognostic variables once a given number of time step is completed. 
    24 These pages provide guidelines how to use AGRIF in NEMO. 
    25 For a more technical description of the library itself, please refer to http://agrif.imag.fr. 
    26  
    27 ----------- 
    28 Compilation 
    29 ----------- 
    30  
    31 Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:  
    32  
    33 .. code-block:: sh 
    34  
    35    ./makenemo add_key 'key_agrif' 
    36  
    37 Although this is transparent to users, the way the code is processed during compilation is different from 
    38 the standard case: 
    39 a preprocessing stage (the so called "conv" program) translates the actual code so that 
    40 saved arrays may be switched in memory space from one domain to an other. 
    41  
    42 -------------------------------- 
    43 Definition of the grid hierarchy 
    44 -------------------------------- 
    45  
    46 An additional text file ``AGRIF_FixedGrids.in`` is required at run time. 
    47 This is where the grid hierarchy is defined. 
    48 An example of such a file, here taken from the ``ICEDYN`` test case, is given below:: 
    49  
    50    1 
    51    34 63 34 63 3 3 3 
    52    0 
    53  
    54 The first line indicates the number of zooms (1). 
    55 The second line contains the starting and ending indices in both directions on the root grid 
    56 (imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3). 
    57 The last line is the number of child grid nested in the refined region (0). 
    58 A more complex example with telescoping grids can be found below and 
    59 in the ``AGRIF_DEMO`` reference configuration directory. 
    60  
    61 [Add some plots here with grid staggering and positioning ?] 
    62  
    63 When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and 
    64 depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and 
    65 nbghostcells=3. 
    66 The grid refinement is 3 and nxfin is the number of child grid points in i-direction.   
    67  
    68 .. image:: _static/agrif_grid_position.jpg 
    69  
    70 Note that rectangular regions must be defined so that they are connected to a single parent grid. 
    71 Hence, defining overlapping grids with the same refinement ratio will not work properly, 
    72 boundary data exchange and update being only performed between root and child grids. 
    73 Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either. 
    74 Defining for instance a circumpolar zoom in a global model is therefore not possible.  
    75  
    76 ------------- 
    77 Preprocessing 
    78 ------------- 
    79  
    80 Knowing the refinement factors and area, a ``NESTING`` pre-processing tool may help to create needed input files 
    81 (mesh file, restart, climatological and forcing files). 
    82 The key is to ensure volume matching near the child grid interface, 
    83 a step done by invoking the ``Agrif_create_bathy.exe`` program. 
    84 You may use the namelists provided in the ``NESTING`` directory as a guide. 
    85 These correspond to the namelists used to create ``AGRIF_DEMO`` inputs. 
    86  
    87 ---------------- 
    88 Namelist options 
    89 ---------------- 
    90  
    91 Each child grid expects to read its own namelist so that different numerical choices can be made 
    92 (these should be stored in the form ``1_namelist_cfg``, ``2_namelist_cfg``, etc... according to their rank in 
    93 the grid hierarchy). 
    94 Consistent time steps and number of steps with the chosen time refinement have to be provided. 
    95 Specific to AGRIF is the following block: 
    96  
    97 .. code-block:: fortran 
    98  
    99    !----------------------------------------------------------------------- 
    100    &namagrif      !  AGRIF zoom                                            ("key_agrif") 
    101    !----------------------------------------------------------------------- 
    102       ln_spc_dyn    = .true.  !  use 0 as special value for dynamics 
    103       rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s] 
    104       rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s] 
    105       ln_chk_bathy  = .false. !  =T  check the parent bathymetry 
    106    /              
    107  
    108 where sponge layer coefficients have to be chosen according to the child grid mesh size. 
    109 The sponge area is hard coded in NEMO and applies on the following grid points: 
    110 2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area)  
    111  
    112 ----------    
    113 References 
    114 ---------- 
    115  
    116 `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>`_ 
    117  
    118 `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>`_ 
    119  
    120 `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>`_ 
     11.. include:: zooms.rst 
    12112 
    12213---- 
    12314 
    124 On line biogeochemistry coarsening 
    125 ================================== 
    126  
    127 .. contents:: 
    128    :local: 
    129  
    130 .. role:: underline  
    131    :class: underline 
    132  
    133 ------------ 
    134 Presentation 
    135 ------------ 
    136  
    137 A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed. 
    138 This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution, 
    139 to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics. 
    140  
    141 A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented. 
    142  
    143 ----------------------------------------------------- 
    144 What is available and working for now in this version 
    145 ----------------------------------------------------- 
    146  
    147 [To be completed] 
    148  
    149 ---------------------------------------------- 
    150 Description of the successful validation tests 
    151 ---------------------------------------------- 
    152  
    153 [To be completed] 
    154  
    155 ------------------------------------------------------------------ 
    156 What is not working yet with on line coarsening of biogeochemistry 
    157 ------------------------------------------------------------------ 
    158  
    159 [To be completed] 
    160  
    161 ''should include precise explanation on MPI decomposition problems too'' 
    162  
    163 --------------------------------------------- 
    164 How to set up and use on line biogeochemistry 
    165 --------------------------------------------- 
    166  
    167 :underline:`How to activate coarsening?` 
    168  
    169 To activate the coarsening, ``key_crs`` should be added to list of CPP keys. 
    170 This key will only activate the coarsening of dynamics. 
    171  
    172 Some parameters are available in the namelist_cfg: 
    173  
    174 .. code-block:: fortran 
    175  
    176                   !   passive tracer coarsened online simulations 
    177    !----------------------------------------------------------------------- 
    178       nn_factx    = 3         !  Reduction factor of x-direction 
    179       nn_facty    = 3         !  Reduction factor of y-direction 
    180       nn_msh_crs  = 0         !  create (=1) a mesh file or not (=0) 
    181       nn_crs_kz   = 3         ! 0, volume-weighted MEAN of KZ 
    182                               ! 1, MAX of KZ 
    183                               ! 2, MIN of KZ 
    184                               ! 3, 10^(MEAN(LOG(KZ))  
    185                               ! 4, MEDIANE of KZ  
    186       ln_crs_wn   = .false.   ! wn coarsened (T) or computed using horizontal divergence ( F ) 
    187                               !                           ! 
    188       ln_crs_top = .true.     !coarsening online for the bio 
    189    / 
    190  
    191 - Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for 
    192   the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...). 
    193 - ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask. 
    194 - ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient.  
    195 - ``ln_crs_wn`` 
    196  
    197   - when ``key_vvl`` is activated, this logical has no effect; 
    198     the coarsened vertical velocities are computed using horizontal divergence. 
    199   - when ``key_vvl`` is not activated, 
    200  
    201     - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``)  
    202     - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``) 
    203 - ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space; 
    204   so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``. 
    205  
    206 :underline:`Choice of operator to coarsene KZ` 
    207  
    208 A sensiblity test has been done with an Age tracer to compare the different operators. 
    209 The 3 and 4 options seems to provide the best results. 
    210  
    211 Some results can be found [xxx here] 
    212  
    213 :underline:`Example of xml files to output coarsened variables with XIOS` 
    214  
    215 In the [attachment:iodef.xml iodef.xml]  file, a "nemo" context is defined and 
    216 some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.   
    217 To write variables on the coarsened grid, and in particular the passive tracers, 
    218 a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and 
    219 the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ]. 
    220  
    221 :underline:`Passive tracers tracers initial conditions` 
    222  
    223 When initial conditions are provided in NetCDF files, the field might be: 
    224  
    225 - on the coarsened grid 
    226 - or they can be on another grid and 
    227   interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_. 
    228   Example of namelist for PISCES : 
    229    
    230    .. code-block:: fortran 
    231  
    232       !----------------------------------------------------------------------- 
    233       &namtrc_dta      !    Initialisation from data input file 
    234       !----------------------------------------------------------------------- 
    235       ! 
    236          sn_trcdta(1)  = 'DIC_REG1'        ,        -12        ,  'DIC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    237          sn_trcdta(2)  = 'ALK_REG1'        ,        -12        ,  'ALK'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    238          sn_trcdta(3)  = 'O2_REG1'         ,        -1         ,  'O2'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    239          sn_trcdta(5)  = 'PO4_REG1'        ,        -1         ,  'PO4'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    240          sn_trcdta(7)  = 'Si_REG1'         ,        -1         ,  'Si'      ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    241          sn_trcdta(10) = 'DOC_REG1'        ,        -12        ,  'DOC'     ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    242          sn_trcdta(14) = 'Fe_REG1'         ,        -12        ,  'Fe'      ,    .false.   , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    243          sn_trcdta(23) = 'NO3_REG1'        ,        -1         ,  'NO3'     ,    .true.    , .true. , 'yearly'  , 'reshape_REG1toeORCA075_bilin.nc'       , ''   , '' 
    244          rn_trfac(1)   =   1.0e-06  !  multiplicative factor 
    245          rn_trfac(2)   =   1.0e-06  !  -      -      -     - 
    246          rn_trfac(3)   =  44.6e-06  !  -      -      -     - 
    247          rn_trfac(5)   = 122.0e-06  !  -      -      -     - 
    248          rn_trfac(7)   =   1.0e-06  !  -      -      -     - 
    249          rn_trfac(10)  =   1.0e-06  !  -      -      -     - 
    250          rn_trfac(14)  =   1.0e-06  !  -      -      -     - 
    251          rn_trfac(23)  =   7.6e-06  !  -      -      -     - 
    252        
    253          cn_dir        =  './'      !  root directory for the location of the data files 
    254  
    255 :underline:`PISCES forcing files` 
    256  
    257 They might be on the coarsened grid. 
    258  
    259 :underline:`Perspectives` 
    260  
    261 For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and 
    262 future releases. 
    263 Those will be discussed in Autumn 2018 
     15.. include:: coarsening.rst 
    26416 
    26517---- 
    26618 
    267 Coupling with other models (OASIS, SAS, ...) 
    268 ============================================ 
    269  
    270 NEMO currently exploits OASIS-3-MCT to implement a generalised coupled interface 
    271 (`Coupled Formulation <http://forge.ipsl.jussieu.fr/nemo/doxygen/node50.html?doc=NEMO>`_). 
    272 It can be used to interface with most of the European atmospheric GCM (ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), 
    273 as well as to WRF (Weather Research and Forecasting Model), and to implement the coupling of 
    274 two independent NEMO components, ocean on one hand and sea-ice plus other surface processes on the other hand 
    275 (`Standalone Surface Module - SAS <http://forge.ipsl.jussieu.fr/nemo/doxygen/node46.html?doc=NEMO>`_). 
    276  
    277 To enable the OASIS interface the required compilation key is ``key_oasis3``. 
    278 The parameters to set are in sections ``namsbc_cpl`` and in case of using of SAS also in section ``namsbc_sas``. 
     19.. include:: coupling.rst 
    27920 
    28021---- 
    28122 
    282 With data assimilation 
    283 ====================== 
    284  
    285 .. contents:: 
    286    :local: 
    287  
    288 The assimilation interface to NEMO is split into three modules. 
    289 - OBS for the observation operator 
    290 - ASM for the application of increments and model bias correction (based on the assimilation increments). 
    291 - TAM the tangent linear and adjoint model. 
    292  
    293 Please see the `NEMO reference manual`_ for more details including information about the input file formats and 
    294 the namelist settings. 
    295  
    296 -------------------------------------- 
    297 Observation and model comparison (OBS) 
    298 -------------------------------------- 
    299  
    300 The observation and model comparison code (OBS) reads in observation files (profile temperature and salinity, 
    301 sea surface temperature, sea level anomaly, sea ice concentration, and velocity) and 
    302 calculates an interpolated model equivalent value at the observation location and nearest model timestep. 
    303 The resulting data are saved in a feedback file (or files). 
    304 The code was originally developed for use with the NEMOVAR data assimilation code, but 
    305 can be used for validation or verification of model or any other data assimilation system. 
    306 This is all controlled by the namelist. 
    307 To build with the OBS code active ``key_diaobs`` must be set.  
    308  
    309 More details in the `NEMO reference manual`_ chapter 12. 
    310  
    311 Standalone observation operator (SAO) 
    312 ------------------------------------- 
    313  
    314 The OBS code can also be run after a model run using saved NEMO model data. 
    315 This is accomplished using the standalone observation operator (SAO) 
    316 (previously known the offline observation operator). 
    317  
    318 To build the SAO use makenemo. 
    319 This means compiling NEMO once (in the normal way) for the chosen configuration. 
    320 Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file. 
    321 Then recompile with the replacement main program in ``./src/SAO``. 
    322 This is a special version of ``nemogcm.F90`` (which doesn't run the model, but reads in the model fields, and 
    323 observations and runs the OBS code. 
    324 See section 12.4 of the `NEMO reference manual`_. 
    325  
    326 ----------------------------------- 
    327 Apply assimilation increments (ASM) 
    328 ----------------------------------- 
    329  
    330 The ASM code adds the functionality to apply increments to the model variables: 
    331 temperature, salinity, sea surface height, velocity and sea ice concentration. 
    332 These are read into the model from a NetCDF file which may be produced by separate data assimilation code. 
    333 The code can also output model background fields which are used as an input to data assimilation code. 
    334 This is all controlled by the namelist nam_asminc. 
    335 To build the ASM code ``key asminc`` must be set. 
    336  
    337 More details in the `NEMO reference manual`_ chapter 13. 
    338  
    339 -------------------------------- 
    340 Tangent linear and adjoint (TAM) 
    341 -------------------------------- 
    342  
    343 This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation. 
     23.. include:: data_assimilation.rst 
    34424 
    34525---- 
    34626 
    347 Inputs-Outputs (using XIOS) 
    348 =========================== 
     27.. include:: input-output.rst 
    34928 
    350 .. contents:: 
    351    :local: 
     29---- 
    35230 
    353 | Output of diagnostics in NEMO is usually done using XIOS. 
    354   This is an efficient way of writing diagnostics because the time averaging, file writing and even 
    355   some simple arithmetic or regridding is carried out in parallel to the NEMO model run. 
    356 | This page gives a basic introduction to using XIOS with NEMO. 
    357   Much more information is available from the XIOS homepage above and from the `NEMO reference manual`_. 
    358  
    359 Use of XIOS for diagnostics is activated using the pre-compiler key ``key_iomput``. 
    360 The default version of XIOS is the 2.0 release.  
    361  
    362 ------------------------------ 
    363 Extracting and installing XIOS 
    364 ------------------------------ 
    365  
    366 1. Install the NetCDF4 library. 
    367    If you want to use single file output you will need to compile the HDF & NetCDF libraries to allow parallel IO. 
    368 2. Download the version of XIOS that you wish to use. 
    369    The recommended version is now XIOS 2.0: 
    370     
    371    .. code-block:: console 
    372  
    373       $ svn co ​http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.0 xios-2.0 
    374  
    375    and follow the instructions in `XIOS documentation`_ to compile it. 
    376    If you find problems at this stage, support can be found by subscribing to the `XIOS users mailing list`_ and 
    377    sending a mail message to it.  
    378  
    379 --------- 
    380 Namelists 
    381 --------- 
    382  
    383 XIOS is controlled using xml input files that should be copied to your model run directory before 
    384 running the model. 
    385 The exact setup differs slightly between 1.0 and 2.0 releases. 
    386  
    387 An ``iodef.xml`` file is still required in the run directory. 
    388 For XIOS 2.0 the ``field_def.xml`` file has been further split into ``field_def-oce.xml`` (for physics), 
    389 ``field_def-ice.xml`` (for ice) and ``field_def-bgc.xml`` (for biogeochemistry). 
    390 Also the definition of the output files has been moved from the ``iodef.xml`` file into 
    391 separate ``file_definition.xml`` files which are included in the ``iodef.xml`` file. 
    392 Note that the ``domain_def.xml`` file is also different for XIOS 2.0. 
    393  
    394 ----- 
    395 Modes 
    396 ----- 
    397  
    398 Detached Mode 
    399 ------------- 
    400  
    401 In detached mode the XIOS executable is executed on separate cores from the NEMO model. 
    402 This is the recommended method for using XIOS for realistic model runs. 
    403 To use this mode set ``using_server`` to ``true`` at the bottom of the ``iodef.xml`` file: 
    404  
    405 .. code-block:: xml 
    406  
    407    <variable id="using_server" type="boolean">true</variable> 
    408  
    409 Make sure there is a copy (or link to) your XIOS executable in the working directory and 
    410 in your job submission script allocate processors to XIOS. 
    411  
    412 Attached Mode 
    413 ------------- 
    414  
    415 In attached mode XIOS runs on each of the cores used by NEMO. 
    416 This method is less efficient than the detached mode but can be more convenient for testing or 
    417 with small configurations. 
    418 To activate this mode simply set ``using_server`` to false in the ``iodef.xml`` file 
    419  
    420 .. code-block:: xml 
    421  
    422    <variable id="using_server" type="boolean">false</variable> 
    423  
    424 and don't allocate any cores to XIOS. 
    425 Note that due to the different domain decompositions between XIOS and NEMO if 
    426 the total number of cores is larger than the number of grid points in the j direction then the model run will fail. 
    427  
    428 ------------------------------ 
    429 Adding new diagnostics to NEMO 
    430 ------------------------------ 
    431  
    432 If you want to add a NEMO diagnostic to the NEMO code you will need to do the following: 
    433  
    434 1. Add any necessary code to calculate you new diagnostic in NEMO 
    435 2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where ``field_id`` is a unique id for 
    436    your new diagnostics and variable is the fortran variable containing the data. 
    437    This should be called at every model timestep regardless of how often you want to output the field. 
    438    No time averaging should be done in the model code.  
    439 3. If it is computationally expensive to calculate your new diagnostic you should also use "iom_use" to 
    440    determine if it is requested in the current model run. For example, 
    441     
    442    .. code-block:: fortran 
    443  
    444       IF iom_use('field_id') THEN 
    445          !Some expensive computation 
    446          !... 
    447          !... 
    448          iom_put('field_id', variable) 
    449       ENDIF 
    450  
    451 4. Add a variable definition to the ``field_def.xml`` (or ``field_def-???.xml``) file 
    452 5. Add the variable to the ``iodef.xml`` or ``file_definition.xml`` file. 
    453  
    454 .. _NEMO reference manual:   http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO 
    455 .. _XIOS documentation:      http://forge.ipsl.jussieu.fr/ioserver/wiki/documentation 
    456 .. _XIOS users mailing list: http://forge.ipsl.jussieu.fr/mailman/listinfo.cgi/xios-users 
     31.. include:: tracers.rst 

  • NEMO/trunk/src/OCE/USR/README.rst

    r10186 r10201  
    22Setting up a new configuration 
    33============================== 
     4 
     5.. include:: .global.rst 
    46 
    57.. contents:: 

  • NEMO/trunk/tests/README.rst

    r10186 r10201  
    33====================== 
    44 
    5 - ``tests/ICEDYN``: 
    6    
    7   [Clement to add an illustration here ?] 
     5.. include:: .global.rst 
    86 
    9   This is an East-west + north-south periodic channel. 
    10   The configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how 
    11   an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by 
    12   removing the ``key_agrif`` in the CPP keys. 
     7``CANAL`` 
     8   | [Illustration here ?] 
     9   | East-west periodic canal of variable size with several initial states and associated geostrophic currents 
     10      (zonal jets or vortex). 
    1311 
    14 - ``tests/VORTEX``: 
    15    
    16   This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom. 
    17   It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates. 
    18   It serves as a benchmark for quantitative estimates of nesting errors as in Debreu et al. (2012), 
    19   Penven et al. (2006) or Spall and Holland (1991). 
    20   The animation below (sea level anomaly in meters) illustrates with two 1:2 successively nested grids how 
    21   the vortex smoothly propagates out of the refined grids. 
    22    
    23   .. image:: _static/VORTEX_anim.gif 
     12``ICEDYN`` 
     13   | [Illustration here ?] 
     14   | East-west + north-south periodic channel inlcuding an AGRIF zoom (1:3) in the middle of the basin to test how 
     15      an ice patch is advected through it but one can also test the advection schemes 
     16      (Prather and Ultimate-Macho) by removing the ``key_agrif`` in the CPP keys. 
     17 
     18``ISOMIP`` 
     19   | [Illustration here ?] 
     20   | Simple box configuration with an iceshelf with simple geometry on top to evaluate the impact of 
     21      various schemes and new development with iceshelf cavities. 
     22   | `test cavities <http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf>`_ 
     23 
     24``LOCK_EXCHANGE`` 
     25   | [Illustration here ?] 
     26   | Classical fluid dynamics experiment that has been adapted for testing advection schemes in 
     27      ocean circulation models. 
     28   | This experiment can in particular illustrate the impact of different choices of numerical schemes and/or 
     29      subgrid closures on spurious interior mixing. 
     30   | :cite:`epic31172,burchard2002getm,ILICAK201237` 
     31 
     32``OVERFLOW`` 
     33   | [Illustration here ?] 
     34   | Adapted from the non-rotating overflow configuration, 
     35      it illustrates the impact of different choices of numerical schemes and/or subgrid closures on 
     36      spurious interior mixing close to bottom topography. 
     37   | :cite:`epic31172,ILICAK201237` 
     38 
     39``VORTEX`` 
     40   .. figure:: _static/VORTEX_anim.gif 
     41 
     42      Vortex smoothly propagates out of two 1:2 successive nested grids (sea level anomaly in meters) 
     43 
     44   | Illustrates the propagation of an anticyclonic eddy over a Beta plan and flat bottom. 
     45   | It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates and 
     46      serves as a benchmark to diagnose nesting errors. 
     47   | :cite:`DEBREU20121,PENVEN2006157,SPALL1991205` 
     48 
     49``WAD`` 
     50   | [Illustration here ?] 
     51   | Set of simple closed basin geometries for testing the wetting and drying capabilities. 
     52      Examples range from a closed channel with EW linear bottom slope to a parabolic EW channel with 
     53      a Gaussian ridge. 
     54 
     55References 
     56========== 
     57 
     58.. bibliography:: test_cases.bib 
     59   :all: 
     60   :style: unsrt 
Note: See TracChangeset for help on using the changeset viewer.