Ignore:
Timestamp:
2018-10-09T18:46:38+02:00 (2 years ago)
Author:
nicolasmartin
Message:

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

Location:
NEMO/trunk/doc/rst/source
Files:
1 added
1 moved

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/doc/rst/source/reference_configurations.rst

    r10182 r10186  
     1===================== 
     2Build a configuration 
     3===================== 
     4 
     5.. contents:: 
     6   :local: 
     7   :depth: 1 
     8       
     9.. role:: underline  
     10   :class: underline 
     11 
     12Official configurations 
     13======================= 
     14 
     15| NEMO is distributed with some reference configurations allowing both the user to set up a first application and 
     16  the developer to validate their developments. 
     17| :underline:`The NEMO System Team is in charge of these configurations`. 
     18 
     19+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     20|                      | OPA | SI3 | TOP | PISCES | AGRIF | Inputs                        | 
     21+======================+=====+=====+=====+========+=======+===============================+ 
     22| `AGRIF_DEMO`_        |  X  |  X  |     |        |   X   | - `AGRIF_DEMO_v4.0.tar`_      | 
     23|                      |     |     |     |        |       | - `ORCA2_ICE_v4.0.tar`_       | 
     24+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     25| `AMM12`_             |  X  |     |     |        |       | `AMM12_v4.0.tar`_             | 
     26+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     27| `C1D_PAPA`_          |  X  |     |     |        |       | `INPUTS_C1D_PAPA_v4.0.tar`_   | 
     28+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     29| `GYRE_BFM`_          |  X  |     |  X  |        |       | ``-``                         | 
     30+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     31| `GYRE_PISCES`_       |  X  |     |  X  |   X    |       | ``-``                         | 
     32+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     33| `ORCA2_ICE_PISCES`_  |  X  |  X  |  X  |   X    |       | - `ORCA2_ICE_v4.0.tar`_       | 
     34|                      |     |     |     |        |       | - `INPUTS_PISCES_v4.0.tar`_   | 
     35+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     36| `ORCA2_OFF_PISCES`_  |     |     |  X  |   X    |       | - `INPUTS_PISCES_v4.0.tar`_   | 
     37|                      |     |     |     |        |       | - `ORCA2_OFF_v4.0.tar`_       | 
     38+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     39| `ORCA2_OFF_TRC`_     |     |     |  X  |        |       | `ORCA2_OFF_v4.0.tar`_         | 
     40+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     41| `ORCA2_SAS_ICE`_     |     |  X  |     |        |       | - `ORCA2_ICE_v4.0.tar`_       | 
     42|                      |     |     |     |        |       | - `INPUTS_SAS_v4.0.tar`_      | 
     43+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     44| `SPITZ12`_           |  X  |  X  |     |        |       | `SPITZ12_v4.0.tar`_           | 
     45+----------------------+-----+-----+-----+--------+-------+-------------------------------+ 
     46 
     47---------- 
     48AGRIF_DEMO 
     49---------- 
     50 
     51.. image:: _static/AGRIF_DEMO.jpg 
     52 
     53``AGRIF_DEMO`` is based on the ``ORCA2_LIM3_PISCES`` global 2° configuration but 
     54it includes 3 online nested grids that demonstrate the overall capabilities of AGRIF in a realistic context, 
     55including nesting sea ice models. 
     56 
     57The configuration includes a 1:1 grid in the Pacific and two successively nested grids with odd and 
     58even refinement ratios over the Arctic ocean. 
     59The finest grid spanning the whole Svalbard archipelago is of particular interest to check that 
     60sea ice coupling is done properly. 
     61The 1:1 grid, used alone, is used as a benchmark to check that the solution is not corrupted by grid exchanges. 
     62 
     63Note that since grids interact only at the baroclinic time level, 
     64numerically exact results can not be achieved in the 1:1 case. 
     65One has to switch to a fully explicit in place of a split explicit free surface scheme in order to 
     66retrieve perfect reproducibility. 
     67 
     68Corresponding ``AGRIF_FixedGrids.in`` file is given by:: 
     69 
     70   2 
     71   42 82 49 91 1 1 1 
     72   122 153 110 143 4 4 4 
     73   0 
     74   1 
     75   38 80 71 111 3 3 3 
     76   0 
     77 
     78----- 
     79AMM12 
     80----- 
     81 
     82``AMM12`` for *Atlantic Margin Model 12kms* is a `regional model`_ covering the Northwest European Shelf domain on 
     83a regular lat-lon grid at approximately 12km horizontal resolution. 
     84The key ``key_amm_12km`` is used to create the correct dimensions of the AMM domain. 
     85 
     86| This configuration tests several features of NEMO functionality specific to the shelf seas. 
     87| In particular, the AMM uses s-coordinates in the vertical rather than z-coordinates and is forced with 
     88  tidal lateral boundary conditions using a flather boundary condition from the BDY module (``key_bdy``). 
     89 
     90The AMM configuration uses the GLS (``key_zdfgls``) turbulence scheme, 
     91the VVL non-linear free surface (``key_vvl``) and time-splitting (``key_dynspg_ts``). 
     92 
     93In addition to the tidal boundary condition, the model may also take open boundary conditions from 
     94a North Atlantic model. 
     95Boundaries may be completely ommited by removing the BDY key (key_bdy) in ``./cfgs/AMM12/cpp_AMM12_fcm``. 
     96 
     97Sample surface fluxes, river forcing and a sample initial restart file are included to test a realistic model run. 
     98The Baltic boundary is included within the river input file and is specified as a river source. 
     99Unlike ordinary river points the Baltic inputs also include salinity and temperature data. 
     100 
     101-------- 
     102C1D_PAPA 
     103-------- 
     104 
     105``C1D_PAPA`` is a 1D configuration (one water column called NEMO1D, activated with CPP key ``key_c1d``), 
     106located at the `PAPA station 145W-50N <http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml>`_. 
     107 
     108| NEMO1D is useful to test vertical physics in NEMO 
     109  (turbulent closure scheme, solar penetration, interaction ocean/atmosphere.,...) 
     110| Size of the horizontal domain is 3x3 grid points. 
     111 
     112This reference configuration uses a 75 vertical levels grid (1m at the surface), 
     113the GLS (key_zdfgls) turbulence scheme with K-epsilon closure and the CORE BULK formulae. 
     114The atmospheric forcing comes from ECMWF operational analysis with a modification of the long and short waves flux. 
     115This set has been rescaled at a frequency of 1h. 1 year is simulated in outputs, 
     116see below (June,15 2010 to June,14 2011) 
     117 
     118`Reffray 2015`_ describes some tests on vertical physic using this configuration. 
     119 
     120The inputs tar file includes: 
     121 
     122- forcing files covering the years 2010 and 2011 (``forcing_PAPASTATION_1h_y201*.nc``) 
     123- initialization file for June,15 2010 deduced from observed data and Levitus 2009 climatology 
     124  (``init_PAPASTATION_m06d15.nc``) 
     125- surface chlorophyll file (``chlorophyll_PAPASTATION.nc``) deduced from Seawifs data. 
     126 
     127-------- 
     128GYRE_BFM 
     129-------- 
     130 
     131``GYRE_BFM`` is the same configuration as `GYRE_PISCES`_, except that PISCES is replaced by 
     132BFM biogeochemichal model in coupled mode. 
     133 
     134----------- 
     135GYRE_PISCES 
     136----------- 
     137 
     138| Idealized configuration representing double gyres in the North hemisphere, Beta-plane with 
     139  a regular grid spacing at 1° horizontal resolution (and possible use as a benchmark by 
     140  easily inscreasing grid size), 101 vertical levels, forced with analytical heat, freshwater and 
     141  wind-stress fields. 
     142| This configuration is coupled to `PISCES biogeochemical model`_. 
     143 
     144Running GYRE as a benchmark 
     145--------------------------- 
     146 
     147This simple configuration can be used as a benchmark since it is easy to increase resolution 
     148(and in this case no physical meaning of outputs): 
     149 
     1501. Choose the grid size 
     151 
     152   In ``./cfgs/GYRE/EXP00``, edit your ``namelist_cfg`` file to change the ``jp_cfg``, ``jpi``, ``jpj``, 
     153   ``jpk`` variables in &namcfg: 
     154 
     155   +------------+---------+---------+---------+------------------+---------------+ 
     156   | ``jp_cfg`` | ``jpi`` | ``jpj`` | ``jpk`` | Number of points | Equivalent to | 
     157   +============+=========+=========+=========+==================+===============+ 
     158   | 1          | 30      | 20      | 101     | 60600            | GYRE 1°       | 
     159   +------------+---------+---------+---------+------------------+---------------+ 
     160   | 25         | 750     | 500     | 101     | 37875000         | ORCA 1/2°     | 
     161   +------------+---------+---------+---------+------------------+---------------+ 
     162   | 50         | 1500    | 1000    | 101     | 151500000        | ORCA 1/4°     | 
     163   +------------+---------+---------+---------+------------------+---------------+ 
     164   | 150        | 4500    | 3000    | 101     | 1363500000       | ORCA 1/12°    | 
     165   +------------+---------+---------+---------+------------------+---------------+ 
     166   | 200        | 6000    | 4000    | 101     | 2424000000       | ORCA 1/16°    | 
     167   +------------+---------+---------+---------+------------------+---------------+ 
     168 
     1692. 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 
     170 
     171.. code-block:: fortran 
     172    
     173   nn_bench    =    1     !  Bench mode (1/0): CAUTION use zero except for bench 
     174 
     1753. 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`) 
     176 
     177.. code-block:: fortran 
     178    
     179   rn_rdt      = 1200.     !  time step for the dynamics 
     180 
     1814. Optional, in order to increase the number of MPI communication for benchmark purposes: 
     182   you can change the number of sub-timesteps computed in the time-splitting scheme each iteration. 
     183   First change the list of active CPP keys for your experiment, 
     184   in `cfgs/"your configuration name"/cpp_"your configuration name".fcm`: 
     185   replace ``key_dynspg_flt by key_dynspg_ts`` and recompile/create your executable again 
     186    
     187   .. code-block:: fortran 
     188    
     189   makenemo [...] add_key 'key_dynspg_ts' del_key 'key_dynspg_flt' 
     190 
     191In your ``namelist_cfg`` file, edit the &namsplit namelist by adding the following line:  
     192 
     193.. code-block:: fortran 
     194    
     195   nn_baro       =    30               !  Number of iterations of barotropic mode/ 
     196 
     197``nn_baro = 30`` is a kind of minimum (we usually use 30 to 60). 
     198So than increasing the ``nn_baro`` value will increase the number of MPI communications. 
     199 
     200The GYRE CPP keys, namelists and scripts can be explored in the ``GYRE`` configuration directory 
     201(``./cfgs/GYRE`` and ``./cfgs/GYRE/EXP00``). 
     202 
     203Find `here <http://prodn.idris.fr/thredds/catalog/ipsl_public/reee451/NEMO_OUT/GYRE/catalog.html>`_ 
     204monthly mean outputs of 1 year run 
     205 
     206---------------- 
     207ORCA2_ICE_PISCES 
     208---------------- 
     209 
     210ORCA is the generic name given to global ocean configurations. 
     211Its specificity lies on the horizontal curvilinear mesh used to overcome the North Pole singularity found for 
     212geographical meshes. 
     213SI3 (Sea Ice Integrated Initiative) is a thermodynamic-dynamic sea ice model specifically designed for 
     214climate studies. 
     215A brief description of the model is given here. 
     216 
     217:underline:`Space-time domain` 
     218 
     219The horizontal resolution available through the standard configuration is ORCA2. 
     220It is based on a 2 degrees Mercator mesh, (i.e. variation of meridian scale factor as cosinus of the latitude). 
     221In the northern hemisphere the mesh has two poles so that the ratio of anisotropy is nearly one everywhere. 
     222The mean grid spacing is about 2/3 of the nominal value: for example it is 1.3 degrees for ORCA2. 
     223Other resolutions (ORCA4, ORCA05 and ORCA025) are running or under development within specific projects. 
     224In the coarse resolution version (i.e. ORCA2 and ORCA4) the meridional grid spacing is increased near 
     225the equator to improve the equatorial dynamics. 
     226Figures in pdf format of mesh and bathymetry can be found and downloaded here. 
     227The sea-ice model runs on the same grid. 
     228 
     229The vertical domain spreads from the surface to a depth of 5000m. 
     230There are 31 levels, with 10 levels in the top 100m. 
     231The vertical mesh is deduced from a mathematical function of z ([[AttachmentNum(1)]]). 
     232The ocean surface corresponds to the w-level k=1, and the ocean bottom to the w-level k=31. 
     233The last T-level (k=31) is thus always in the ground.The depths of the vertical levels and 
     234the associated scale factors can be viewed. 
     235Higher vertical resolution is used in ORCA025 and ORCA12 (see `DRAKKAR project <http://www.drakkar-ocean.eu>`_). 
     236 
     237The time step depends on the resolution. It is 1h36' for ORCA2 so that there is 15 time steps in one day. 
     238 
     239:underline:`Ocean Physics (for ORCA2)` 
     240 
     241- horizontal diffusion on momentum: the eddy viscosity coefficient depends on the geographical position. 
     242  It is taken as 40000 $m^2/s$, reduced in the equator regions (2000 $m^2/s$) excepted near the western boundaries. 
     243- isopycnal diffusion on tracers: the diffusion acts along the isopycnal surfaces (neutral surface) with 
     244  a eddy diffusivity coefficient of 2000 $m^2/s$. 
     245- Eddy induced velocity parametrization with a coefficient that depends on the growth rate of 
     246  baroclinic instabilities (it usually varies from 15 $m^2/s$ to 3000 $m^2/s$). 
     247- lateral boundary conditions : zero fluxes of heat and salt and no-slip conditions are applied through 
     248  lateral solid boundaries. 
     249- bottom boundary condition : zero fluxes of heat and salt are applied through the ocean bottom. 
     250  The Beckmann [19XX] simple bottom boundary layer parameterization is applied along continental slopes. 
     251  A linear friction is applied on momentum. 
     252- convection: the vertical eddy viscosity and diffusivity coefficients are increased to 1 $m^2/s$ in case of 
     253  static instability. 
     254- forcings: the ocean receives heat, freshwater, and momentum fluxes from the atmosphere and/or the sea-ice. 
     255  The solar radiation penetrates the top meters of the ocean. 
     256  The downward irradiance I(z) is formulated with two extinction coefficients [Paulson and Simpson, 1977], 
     257  whose values correspond to a Type I water in Jerlov's classification (i.e the most transparent water) 
     258 
     259ORCA2_ICE_PISCES is a reference configuration with the following characteristics: 
     260 
     261- global ocean configuration 
     262- based on a tri-polar ORCA grid, with a 2° horizontal resolution 
     263- 31 vertical levels 
     264- forced with climatological surface fields 
     265- coupled to the sea-ice model SI3. 
     266- coupled to TOP passive tracer transport module and `PISCES biogeochemical model`_. 
     267 
     268:underline:`AGRIF demonstrator` 
     269 
     270| From the ``ORCA2_ICE_PISCES`` configuration, a demonstrator using AGRIF nesting can be activated. 
     271  It includes the global ``ORCA2_ICE_PISCES`` configuration and a nested grid in the Agulhas region. 
     272| To set up this configuration, after extracting NEMO: 
     273 
     274- Build your AGRIF configuration directory from ORCA2_ICE_PISCES, with the key_agrif CPP key activated: 
     275 
     276.. code-block:: console 
     277                 
     278   $ ./makenemo -r 'ORCA2_ICE_PISCES' -n 'AGRIF' add_key 'key_agrif' 
     279 
     280- Using the ``ORCA2_ICE_PISCES`` input files and namelist, AGRIF test configuration is ready to run 
     281 
     282:underline:`On-The-Fly Interpolation` 
     283 
     284| NEMO allows to use the interpolation on the fly option allowing to interpolate input data during the run. 
     285  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  2 weights files `bil_weights` for scalar field (bilinear interpolation) and `bic_weights` for 
     289  vector field (bicubic interpolation). 
     290| The data files used are `COREII forcing <http://data1.gdfl.noaa.gov/nomads/forms/mom4/COREv2>`_ extrapolated on 
     291  continents, ready to be used for on the fly option: 
     292  `COREII`_ forcing files extrapolated on continents 
     293 
     294---------------- 
     295ORCA2_OFF_PISCES 
     296---------------- 
     297 
     298``ORCA2_OFF_PISCES`` uses the ORCA2 configuration in which the `PISCES biogeochemical model`_ has been activated in 
     299standalone using the dynamical fields that are pre calculated. 
     300 
     301See `ORCA2_ICE_PISCES`_ for general description of ORCA2. 
     302 
     303The input files for PISCES are needed, in addition the dynamical fields are used as input. 
     304They are coming from a 2000 years of an ORCA2_LIM climatological run using ERA40 atmospheric forcing. 
     305 
     306------------- 
     307ORCA2_OFF_TRC 
     308------------- 
     309 
     310``ORCA2_OFF_TRC`` uses the ORCA2_LIM configuration in which the tracer passive transport module TOP has been 
     311activated in standalone using the dynamical fields that are pre calculated. 
     312 
     313See `ORCA2_ICE_PISCES`_ for general description of ORCA2. 
     314 
     315In ``namelist_top_cfg``, different passive tracers can be activated ( cfc11, cfc12, sf6, c14, age ) or my-trc, 
     316a user-defined tracer. 
     317 
     318The dynamical fields are used as input, they are coming from a 2000 years of an ORCA2_LIM climatological run using 
     319ERA40 atmospheric forcing. 
     320 
     321------------- 
     322ORCA2_SAS_ICE 
     323------------- 
     324 
     325``ORCA2_SAS_ICE`` is a demonstrator of the SAS ( Stand-alone Surface module ) based on ORCA2_LIM configuration. 
     326 
     327The standalone surface module allows surface elements such as sea-ice, iceberg drift and surface fluxes to 
     328be run using prescribed model state fields. 
     329For example, it can be used to inter-compare different bulk formulae or adjust the parameters of 
     330a given bulk formula 
     331 
     332See `ORCA2_ICE_PISCES`_ for general description of ORCA2. 
     333 
     334Same input files as `ORCA2_ICE_PISCES`_ are needed plus fields from a previous ORCA2_LIM run. 
     335 
     336More informations on input and configuration files in `NEMO Reference manual`_. 
     337 
     338------- 
     339SPITZ12 
     340------- 
     341 
     342``SPITZ12`` 
     343 
     344Unsupported configurations 
     345========================== 
     346 
     347Other configurations are developed and used by some projects with "NEMO inside", 
     348these projects are welcome to publicize it here: http://www.nemo-ocean.eu/projects/add-project 
     349 
     350:underline:`Obviously these "projects configurations" are not under the NEMO System Team's responsibility`. 
     351 
     352.. _regional model:               http://www.tandfonline.com/doi/pdf/10.1080/1755876X.2012.11020128 
     353.. _AMM12_v4.0.tar:               http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AMM12_v4.0.tar 
     354.. _PISCES biogeochemical model:  http://www.geosci-model-dev.net/8/2465/2015 
     355.. _INPUTS_PISCES_v4.0.tar:       http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_PISCES_v4.0.tar 
     356.. _ORCA2_OFF_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_OFF_v4.0.tar 
     357.. _ORCA2_ICE_v4.0.tar:           http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/ORCA2_ICE_v4.0.tar 
     358.. _INPUTS_SAS_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_SAS_v4.0.tar 
     359.. _NEMO Reference manual:        http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html?doc=NEMO 
     360.. _INPUTS_C1D_PAPA_v4.0.tar:     http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/INPUTS_C1D_PAPA_v4.0.tar 
     361.. _Reffray 2015:                 http://www.geosci-model-dev.net/8/69/2015 
     362.. _COREII:                       http://prodn.idris.fr/thredds/catalog/ipsl_public/reee512/ORCA2_ONTHEFLY/FILLED_FILES/catalog.html 
     363.. _SPITZ12_v4.0.tar:             http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/SPITZ12_v4.0.tar 
     364.. _AGRIF_DEMO_v4.0.tar:          http://prodn.idris.fr/thredds/fileServer/ipsl_public/romr005/Online_forcing_archives/AGRIF_DEMO_v4.0.tar 
Note: See TracChangeset for help on using the changeset viewer.