source: NEMO/trunk/src/OCE/USR/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: 12.4 KB
Line 
1==============================
2Setting up a new configuration
3==============================
4
5.. include:: .global.rst
6
7.. contents::
8
9Starting from an existing configuration
10=======================================
11
12There are three options to build a new configuration from an existing one:
13
14---------------------------------------------
15Option 1: Duplicate an existing configuration
16---------------------------------------------
17
18The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
19(global, regional, 1D, using embeded zoom with AGRIF...)
20
21One can create a new configuration by duplicating one of the reference configurations
22(``ORCA2_LIM3_PISCES`` in the following example)
23
24.. code-block:: sh
25
26   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES'
27
28------------------------------------
29Option 2: Duplicate with differences
30------------------------------------
31
32Create and compile a new configuration based on a reference configuration
33(``ORCA2_LIM3_PISCES`` in the following example) but with different pre-processor options.
34For this either add ``add_key`` or ``del_key`` keys as required; e.g.
35
36.. code-block:: sh
37
38   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' del_key 'key_iomput' add_key 'key_xios'
39
40---------------------------------------------------------
41Option 3: Use the SIREN tools to subset an existing model
42---------------------------------------------------------
43
44Define a regional configuration which is a sub- or super-set of an existing configuration.
45
46This last option employs the SIREN software tools that are included in the standard distribution.
47The software is written in Fortran 95 and available in the ``./tools/SIREN`` directory.
48SIREN allows you to create your own regional configuration embedded in a wider one.
49
50SIREN is a set of programs to create all the input files you need to run a NEMO regional configuration.
51As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
52as well as examples of namelists are available `here`_.
53
54`SIREN documentation`_
55
56Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_.
57
58Creating a completely new configuration
59=======================================
60
61From NEMO version 4.0 there are two ways to build configurations from scratch.
62The appropriate method to use depends largely on the target configuration.
63Method 1 is for more complex/realistic global or regional configurations and
64method 2 is intended for simpler, idealised configurations whose
65domains and characteristics can be described in simple geometries and formulae.
66
67----------------------------------------------------
68Option 1: Create and use a domain configuration file
69----------------------------------------------------
70
71This method is used by each of the reference configurations,
72so that downloading their input files linked to their description can help.
73Although starting from scratch it is advisable to create the directory structure to house your new configuration by
74duplicating the closest reference configuration to your target application.
75For example, if your application requires both ocean ice and passive tracers,
76then use the ``ORCA2_LIM3_PISCES`` as template,
77and execute following command to build your ``MY_NEW_CONFIG`` configuration:
78
79.. code-block:: sh
80
81   makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_LIM3_PISCES'
82
83where ``MY_NEW_CONFIG`` can be substituted with a suitably descriptive name for your new configuration. 
84
85The purpose of this step is simply to create and populate the appropriate ``WORK``, ``MY_SRC`` and
86``EXP00`` subdirectories for your new configuration.
87Other choices for the base reference configuration might be
88
89- ``GYRE``  - If your target application is ocean-only
90- ``AMM12`` - If your target application is regional with open boundaries
91
92All the domain information for your new configuration will be contained within
93a netcdf file called ``domain_cfg.nc`` which you will need to create and
94place in the ``./cfgs/MY_NEW_CONFIG/EXP00`` sub-directory.
95Firstly though, ensure that your configuration is set to use such a file by checking that
96
97.. code-block:: fortran
98
99   ln_read_cfg = .true.
100
101in ``./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg``
102
103Create the domain_cfg.nc file which must contain the following fields
104
105.. code-block:: c++
106
107   int    ORCA, ORCA_index                  /* configuration name, configuration resolution                 */
108   int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                          */
109   int    jperio                            /* lateral global domain b.c.                                   */
110   int    ln_zco, ln_zps, ln_sco            /* flags for z-coord, z-coord with partial steps and s-coord    */
111   int    ln_isfcav                         /* flag  for ice shelf cavities                                 */
112   double glamt, glamu, glamv, glamf        /* geographic position                                          */
113   double gphit, gphiu, gphiv, gphif        /* geographic position                                          */
114   double iff, ff_f, ff_t                   /* Coriolis parameter (if not on the sphere)                    */
115   double e1t, e1u, e1v, e1f                /* horizontal scale factors                                     */
116   double e2t, e2u, e2v, e2f                /* horizontal scale factors                                     */
117   double ie1e2u_v, e1e2u, e1e2v            /* U and V surfaces (if grid size reduction in some straits)    */
118   double e3t_1d, e3w_1d                    /* reference vertical scale factors at T and W points           */
119   double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0 /* vertical scale factors 3D coordinate at T,U,V,F and W points */
120   double e3uw_0, e3vw_0                    /* vertical scale factors 3D coordinate at UW and VW points     */
121   int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
122
123There are two options for creating a domain_cfg.nc file:
124
125- Users can use tools of their own choice to build a ``domain_cfg.nc`` with all mandatory fields.
126- Users can adapt and apply the supplied tool available in ``./tools/DOMAINcfg``.
127  This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
128  the horizontal and vertical grids that were available internally to that version.
129  See ``./tools/DOMAINcfg/README`` for details.
130
131-----------------------------------------------------------------------------
132Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
133-----------------------------------------------------------------------------
134
135This method is intended for configuring easily simple/idealised configurations which
136are often used as demonstrators or for process evaluation and comparison.
137This method can be used whenever the domain geometry has a simple mathematical description and
138the ocean initial state and boundary forcing is described analytically.
139As a start, consider the case of starting a completely new ocean-only test case based on
140the ``LOCK_EXCHANGE`` example.
141[Note: we probably need an even more basic example than this with only one namelist and
142minimal changes to the usrdef modules]
143
144Firstly, construct the directory structure, starting in the ``cfgs`` directory:
145
146.. code-block:: sh
147
148   ./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE'
149
150where the ``-t`` option has been used to locate the new configuration in the ``tests`` subdirectory
151(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
152This command will have created (amongst others) the following files and directories::
153
154   ./tests/MY_NEW_TEST:
155   BLD     MY_SRC cpp_MY_NEW_TEST.fcm
156   EXP00   WORK
157   #
158   ./tests/MY_NEW_TEST/EXP00:
159   context_nemo.xml       domain_def_nemo.xml
160   field_def_nemo-opa.xml file_def_nemo-opa.xml
161   iodef.xml
162   namelist_cfg
163   namelist_ref
164   #
165   ./tests/MY_NEW_TEST/MY_SRC:
166   usrdef_hgr.F90    usrdef_nam.F90 usrdef_zgr.F90
167   usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
168
169The key to setting up an idealised configuration lies in adapting a small set of short Fortran 90 modules which
170should be dropped into the ``MY_SRC`` directory.
171Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
172the ``src/OCE/USR`` directory is::
173
174   ./src/OCE/USR:
175   usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90
176   usrdef_fmask.F90  usrdef_nam.F90
177   usrdef_hgr.F90    usrdef_sbc.F90
178
179Before discussing these in more detail it is worth noting the various namelist controls that
180engage the different user-defined aspects.
181These controls are set using two new logical switches or are implied by the settings of existing ones.
182For example, the mandatory requirement for an idealised configuration is to provide routines which
183define the horizontal and vertical domains.
184Templates for these are provided in the ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules.
185The application of these modules is activated whenever:
186
187.. code-block:: fortran
188
189   ln_read_cfg = .false.
190
191in any configuration's ``namelist_cfg`` file.
192This setting also activates the reading of an optional ``nam_usrdef`` namelist which can be used to
193supply configuration specific settings.
194These need to be declared and read in the ``usrdef_nam.F90`` module.
195
196Another explicit control is available in the ``namsbc`` namelist which activates the use of analytical forcing.
197With
198
199.. code-block:: fortran
200
201   ln_usr = .true.
202
203Other usrdef modules are activated by less explicit means.
204For example, code in ``usrdef_istate.F90`` is used to define initial temperature and salinity fields if
205
206.. code-block:: fortran
207
208   ln_tsd_init   = .false.
209
210in the ``namtsd`` namelist.
211The remaining modules, namely::
212
213   usrdef_closea.F90 usrdef_fmask.F90
214
215are specific to ORCA configurations and set local variations of some specific fields for
216the various resolutions of the global models.
217They do not need to be considered here in the context of idealised cases but it is worth noting that all
218configuration specific code has now been isolated in the usrdef modules.
219In the case of these last two modules, they are activated only if an ORCA configuration is detected.
220Currently this requires a specific integer variable named ``ORCA`` to be set in a ``domain_cfg.nc`` file.
221[Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from
222the ``domain_cfg.nc`` ]
223
224So, in most cases, the set up of idealised model configurations can be completed by
225copying the template routines from ``./src/OCE/USR`` into
226your new ``./cfgs/MY_NEW_TEST/MY_SRC`` directory and editing the appropriate modules as needed.
227The default set are those used for the GYRE reference configuration.
228The contents of ``MY_SRC`` directories from other idealised configurations may provide more convenient templates if
229they share common characteristics with your target application.
230
231Whatever the starting point it should not require too many changes or additional lines of code to
232produce routines in ``./src/OCE/USR`` that define analytically the domain,
233the initial state and the surface boundary conditions for your new configuration.
234
235To summarize, the base set of modules is:
236
237- ``usrdef_hgr.F90``   : define horizontal grid
238- ``usrdef_zgr.F90``   : define vertical grid
239- ``usrdef_sbc.F90``   : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes
240- ``usrdef_istate.F90``: defines initialization of the dynamics and tracers
241- ``usrdef_nam.F90``   : configuration-specific namelist processing to set any associated run-time parameters
242
243with two specialised ORCA modules
244(not related to idealised configurations but used to isolate configuration specific code that is used in
245ORCA2 reference configurations and established global configurations using the ORCA tripolar grid):
246
247- ``usrdef_fmask.F90`` : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits
248- ``usrdef_closea.F90``: only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas
249
250From version 4.0, the NEMO release includes a ``tests`` subdirectory containing available and
251up to date test cases build by the community.
252These will not be fully supported as is NEMO reference but should provide a source of raw material.
253
254.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar
255.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2
256.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html
Note: See TracBrowser for help on using the repository browser.