Changes between Version 33 and Version 34 of Users/Setup New Configuration


Ignore:
Timestamp:
2018-07-13T19:10:09+02:00 (3 months ago)
Author:
clevy
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Users/Setup New Configuration

    v33 v34  
    1 {{{#!rst 
    2  
    3 ============================== 
    4 Setting up a new configuration 
    5 ============================== 
    6  
    7 Last edition: :code-block:`Wikinfo:changed_ts` by :code-block:`Wikinfo:changed_by` 
    8  
    9 .. contents:: Table of contents 
    10  
    11 ----------------------------- 
    12 Starting from an existing one 
    13 ----------------------------- 
    14  
    15 There are three options for creating new configurations based on an existing one: 
    16  
    17 Option 1: Duplicate an existing configuration 
    18 ============================================= 
    19  
    20 Create and compile a new configuration duplicating a reference configuration (ORCA_LIM3 
    21 in the following example) 
    22  
    23 .. code-block:: bash 
    24  
    25    makenemo –n 'ORCA_LIM3_MYCONFIG' -r ORCA_LIM3 
    26  
    27 Option 2: Duplicate with differences 
    28 ==================================== 
    29  
    30 Create and compile a new configuration based on a reference configuration (ORCA_LIM3 in 
     1= Setting up a new configuration 
     2 
     3[[PageOutline]] 
     4[[BR]] 
     5[[BR]] 
     6[[BR]] 
     7[[BR]] 
     8[[BR]] 
     9[[BR]] 
     10[[BR]] 
     11[[BR]] 
     12[[BR]] 
     13[[BR]] 
     14[[BR]] 
     15Last edition on '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]''' 
     16 
     17 
     18== Starting from an existing configuration 
     19 
     20 
     21There are three options to build a new configuration from an existing one: 
     22 
     23=== Option 1: Duplicate an existing configuration 
     24 
     25The NEMO so-called Reference Configurations [wiki:Users/ReferenceConfigurations list available here] cover a number of major features for NEMO setup (global, regional, 1D, using embeded zoom with AGRIF...) 
     26 
     27One can create a new configuration by duplicating one of the  reference configurations (ORCA2_LIM3_PISCES in the following example) 
     28 
     29 
     30{{{ 
     31   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r ORCA2_LIM3_PISCES 
     32}}} 
     33 
     34 
     35=== Option 2: Duplicate with differences 
     36 
     37Create and compile a new configuration based on a reference configuration (ORCA2_LIM3_PISCES in 
    3138the following example) but with different pre-processor options. For this either add 
    3239(add_key) or remove (del_key) keys as required; e.g. 
    3340 
    34 .. code-block:: bash 
    35  
    36    makenemo –n 'ORCA2_LIM3_MYCONFIG' -r ORCA2_LIM3 del_key 'key_iomput' add_key 'key_xios' 
    37  
    38 Option 3: Use the SIREN tools to subset an existing model 
    39 ========================================================= 
     41 
     42{{{ 
     43   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r ORCA2_LIM3_PISCES del_key 'key_iomput' add_key 'key_xios' 
     44}}} 
     45 
     46=== Option 3: Use the SIREN tools to subset an existing model 
     47 
    4048 
    4149Define a regional configuration which is a sub- or super-set of an existing 
     
    5058configuration. As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the 
    5159ORCA025 grid), as well as examples of namelists are available 
    52 :trac:`[http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar here]`. 
    53  
    54 :trac:`[/doxygen/index.html SIREN documentation]` 
    55  
    56 Any questions or comments regarding the use of SIREN should be posted in the corresponding 
    57 :trac:`forum:2 forum`. 
    58  
    59 --------------------------------------- 
    60 Creating a completely new configuration 
    61 --------------------------------------- 
     60[http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar here]`. 
     61 
     62[/doxygen/index.html SIREN documentation] 
     63 
     64Any questions or comments regarding the use of SIREN should be   
     65[forum:2 posted in the corresponding forum]. 
     66 
     67 
     68== Creating a completely new configuration 
     69 
    6270 
    6371From NEMO version 4.0 there are two ways to build configurations from scratch. The 
     
    6775simple geometries and formulae. 
    6876 
    69 Option 1: Create and use a domain configuration file 
    70 ==================================================== 
    71  
    72 **1** Even when starting from scratch it is advisable to create the directory structure to 
     77=== Option 1: Create and use a domain configuration file 
     78 
     79This method is used by each of the reference configurations, so that [wiki:Users/ReferenceConfigurations downloading their input files linked to their description can help] 
     80Although starting from scratch it is advisable to create the directory structure to 
    7381house your new configuration by duplicating the closest reference configuration to your 
    74 target application.  For example, If your application requires both ocean and ice 
    75 components then run 
    76  
    77 .. code-block:: bash 
    78  
    79    makenemo –n 'MY_NEW_CONFIG' -r ORCA_LIM3 
     82target application.  For example, If your application requires both ocean ice and passive tracers, then use the ORCA2_LIM3_PISCES as template, and execute following command to build your MY_NEW_CONFIG configuration: 
     83 
     84{{{ 
     85makenemo –n 'MY_NEW_CONFIG' -r ORCA2_LIM3_PISCES 
     86}}} 
    8087 
    8188where ``'MY_NEW_CONFIG'`` can be substituted with a suitably descriptive name for your new 
    82 configuration.  The purpose of this step is simply to create and populate the appropriate WORK,  
     89configuration.   
     90 
     91The purpose of this step is simply to create and populate the appropriate WORK,  
    8392MY_SRC and EXP00 subdirectories for your new configuration. Other choices for the base reference 
    8493configuration might be 
     
    8695  * GYRE  - If your target application is ocean-only 
    8796  * AMM12 - If your target application is regional with open boundaries 
    88   * ORCA2_LIM_PISCES - If your target application requires ocean, sea-ice and passive tracers 
    89  
    90 **2** All the domain information for your new configuration will be contained within a netcdf 
     97 
     98All the domain information for your new configuration will be contained within a netcdf 
    9199file called ``domain_cfg.nc`` which you will need to create and place in the 
    92100 
    93 .. code-block:: bash 
    94  
     101{{{ 
    95102   NEMOGCM/CONFIG/'MY_NEW_CONFIG'/EXP00 
    96  
     103}}} 
    97104sub-directory. Firstly though, ensure that your configuration is set to use such a file by 
    98 confirming that 
    99  
    100 .. code-block:: fortran 
    101  
     105checking that 
     106 
     107 
     108{{{ 
    102109   ln_read_cfg = .true. 
    103  
     110}}} 
    104111in 
    105  
    106 .. code-block:: bash 
    107  
     112{{{ 
    108113   NEMOGCM/CONFIG/'MY_NEW_CONFIG'/EXP00/namelist_cfg 
    109  
    110 **3** Create the domain_cfg.nc file which must contain the following fields 
    111  
    112 .. code-block:: cpp 
    113  
     114}}} 
     115==== Create the domain_cfg.nc file which must contain the following fields 
     116 
     117 
     118{{{ 
    114119   int    ORCA, ORCA_index                  /* configuration name, configuration resolution                             */ 
    115120   int    jpiglo, jpjglo, jpkglo            /* global domain sizes                                                      */ 
     
    128133   int    bottom_level, top_level           /* last wet T-points, 1st wet T-points (for ice shelf cavities)             */ 
    129134 
    130  
     135}}} 
    131136There are two options for creating a domain_cfg.nc file: 
    132137 
     
    139144   for details. 
    140145 
    141 Option 2: Copy and modify user-defined configuration modules 
    142 ============================================================ 
    143  
    144 This method is intended for configuring easily defined idealised configurations which are 
     146=== Option 2: Adapt the usr_def configuration module of NEMO for you own purposes  
     147 
     148This method is intended for configuring easily simple/idealised configurations which are 
    145149often used as demonstrators or for process evaluation and comparison. This method can be 
    146150used whenever the domain geometry has a simple mathematical description and the ocean 
    147 initial state and boundary forcing is described analytically. From version 4.0, the NEMO 
    148 release includes a ``TEST_CASES`` subdirectory of the reference ``CONFIG`` directory which 
    149 includes several examples and will, over time, include further user-contributed examples. 
    150 These will not necessarily be fully supported but should provide a source of raw material 
    151 and ideas for constructing your own examples. 
    152  
    153 For now, consider the case of starting a completely new ocean-only test case based on the 
     151initial state and boundary forcing is described analytically.  
     152As a start, consider the case of starting a completely new ocean-only test case based on the 
    154153LOCK_EXCHANGE example. [Note: we probably need an even more basic example than this with 
    155154only one namelist and minimal changes to the usrdef modules] 
     
    157156Firstly, construct the directory structure, starting in the ``CONFIG`` directory: 
    158157 
    159 .. code-block:: bash 
    160  
     158 
     159{{{ 
    161160   ./makenemo -a TEST_CASES -n 'MY_NEW_TEST' -r LOCK_EXCHANGE 
    162  
     161}}} 
    163162where the ``-a`` option has been used to locate the new configuration in the 
    164163``TEST_CASES`` subdirectory (it is recommended practice to keep full configurations and 
     
    166165the following files and directories: 
    167166 
    168 .. code-block:: bash 
    169  
     167 
     168{{{ 
    170169   TEST_CASES/'MY_NEW_TEST': 
    171170   BLD     MY_SRC     cpp_MY_NEW_TEST.fcm 
     
    182181   usrdef_hgr.F90       usrdef_nam.F90    usrdef_zgr.F90 
    183182   usrdef_istate.F90    usrdef_sbc.F90    zdfini.F90 
    184  
     183}}} 
    185184The key to setting up an idealised configuration lies in adapting a small set of short fortran90 
    186185modules which should be dropped into the MY_SRC directory. Here the LOCK_EXCHANGE example is using 
    1871865 such routines but the full set that is availablein the ``NEMO/OPA_SRC/USR`` directory is: 
    188187 
    189 .. code-block:: bash 
    190  
     188 
     189{{{ 
    191190   ../NEMO/OPA_SRC/USR: 
    192191   usrdef_closea.F90   usrdef_istate.F90   usrdef_zgr.F90 
    193192   usrdef_fmask.F90    usrdef_nam.F90 
    194193   usrdef_hgr.F90      usrdef_sbc.F90 
     194}}} 
    195195 
    196196Before discussing these in more detail it is worth noting the various namelist controls 
     
    202202activated whenever: 
    203203 
    204 .. code-block:: fortran 
    205  
     204 
     205{{{ 
    206206   ln_read_cfg = .false. 
    207  
     207}}} 
    208208in any configuration's ``namelist_cfg`` file. This setting also activates the reading of 
    209209an optional ``nam_usrdef`` namelist which can be used to supply configuration specific 
     
    212212Another explicit control is available in the ``namsbc`` namelist which activates the 
    213213use of analytical forcing. With 
    214  
    215 .. code-block:: fortran 
    216  
     214{{{ 
    217215   ln_usr = .true. 
    218  
     216}}} 
    219217Other usrdef modules are activated by less explicit means. For example, code in 
    220218``usrdef_istate.F90`` is used to define initial temperature and salinity fields if 
    221  
    222 .. code-block:: fortran 
    223  
     219{{{ 
    224220   ln_tsd_init   = .false. 
    225  
     221}}} 
    226222in the ``namtsd`` namelist. The remaining modules, namely 
    227  
    228 .. code-block:: bash 
    229  
     223{{{ 
    230224   usrdef_closea.F90   usrdef_fmask.F90 
    231  
     225}}} 
    232226are specific to ORCA configurations and set local variations of some specific 
    233227fields for the various resolutions of the global models. They do not need to be 
     
    251245the initial state and the surface boundary conditions for your new configuration. 
    252246 
    253 In summary, the base set of modules is: 
     247To summarize, the base set of modules is: 
    254248 
    255249    * usrdef_hgr.F90    : define horizontal grid 
     
    265259    * usrdef_fmask.F90  : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits 
    266260    * usrdef_closea.F90 : only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas 
    267 }}} 
     261 
     262From version 4.0, the NEMO 
     263release includes a ``test`` subdirectory  
     264containing available and up to date test cases build by the community . 
     265These will not be fully supported as is NEMO reference but should provide a source of raw material.