New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
setup.rst in NEMO/trunk/doc/rst/source – NEMO

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

Last change on this file since 10279 was 10279, checked in by nicolasmartin, 6 years ago

Various improvments for quick start guide

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