source: NEMO/trunk/cfgs/README.rst @ 10201

Last change on this file since 10201 was 10201, checked in by nicolasmartin, 3 years ago

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