source: NEMO/trunk/doc/rst/source/setup.rst @ 11734

Last change on this file since 11734 was 11734, checked in by nicolasmartin, 12 months ago

Review README for reference confgiurations

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