source: NEMO/trunk/doc/rst/source/reference_configurations.rst @ 10186

Last change on this file since 10186 was 10186, checked in by nicolasmartin, 2 years ago

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

File size: 18.5 KB
Line 
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 TracBrowser for help on using the repository browser.