Changes between Version 24 and Version 25 of Users/Setup New Configuration


Ignore:
Timestamp:
2017-05-14T23:26:43+02:00 (3 years ago)
Author:
acc
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Users/Setup New Configuration

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