source: NEMO/branches/2019/dev_ASINTER-01-05_merged/src/OCE/USR/README.rst @ 12165

Last change on this file since 12165 was 12165, checked in by davestorkey, 10 months ago

2019/dev_ASINTER-01-05_merged: Update to r12072 of trunk.

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