Ignore:
Timestamp:
2018-10-09T18:46:38+02:00 (2 years ago)
Author:
nicolasmartin
Message:

Preliminary implementation of a NEMO Quick Start Guide via RST files and Sphinx installation

Location:
NEMO/trunk/doc/rst/source
Files:
1 added
1 moved

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/doc/rst/source/setup_configuration.rst

    r10182 r10186  
     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 
     12--------------------------------------------- 
     13Option 1: Duplicate an existing configuration 
     14--------------------------------------------- 
     15 
     16The NEMO so-called Reference Configurations cover a number of major features for NEMO setup 
     17(global, regional, 1D, using embeded zoom with AGRIF...) 
     18 
     19One can create a new configuration by duplicating one of the reference configurations 
     20(``ORCA2_LIM3_PISCES`` in the following example) 
     21 
     22.. code-block:: sh 
     23 
     24   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' 
     25 
     26------------------------------------ 
     27Option 2: Duplicate with differences 
     28------------------------------------ 
     29 
     30Create and compile a new configuration based on a reference configuration 
     31(``ORCA2_LIM3_PISCES`` in the following example) but with different pre-processor options. 
     32For this either add ``add_key`` or ``del_key`` keys as required; e.g. 
     33 
     34.. code-block:: sh 
     35 
     36   makenemo –n 'ORCA2_LIM3_PISCES_MINE' -r 'ORCA2_LIM3_PISCES' del_key 'key_iomput' add_key 'key_xios' 
     37 
     38--------------------------------------------------------- 
     39Option 3: Use the SIREN tools to subset an existing model 
     40--------------------------------------------------------- 
     41 
     42Define a regional configuration which is a sub- or super-set of an existing configuration. 
     43 
     44This last option employs the SIREN software tools that are included in the standard distribution. 
     45The software is written in Fortran 95 and available in the ``./tools/SIREN`` directory. 
     46SIREN allows you to create your own regional configuration embedded in a wider one. 
     47 
     48SIREN is a set of programs to create all the input files you need to run a NEMO regional configuration. 
     49As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid), 
     50as well as examples of namelists are available `here`_. 
     51 
     52`SIREN documentation`_ 
     53 
     54Any questions or comments regarding the use of SIREN should be posted in `the corresponding forum`_. 
     55 
     56Creating a completely new configuration 
     57======================================= 
     58 
     59From NEMO version 4.0 there are two ways to build configurations from scratch. 
     60The appropriate method to use depends largely on the target configuration. 
     61Method 1 is for more complex/realistic global or regional configurations and 
     62method 2 is intended for simpler, idealised configurations whose 
     63domains and characteristics can be described in simple geometries and formulae. 
     64 
     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_LIM3_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_LIM3_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 
     129----------------------------------------------------------------------------- 
     130Option 2: Adapt the usr_def configuration module of NEMO for you own purposes 
     131----------------------------------------------------------------------------- 
     132 
     133This method is intended for configuring easily simple/idealised configurations which 
     134are often used as demonstrators or for process evaluation and comparison. 
     135This method can be used whenever the domain geometry has a simple mathematical description and 
     136the ocean initial state and boundary forcing is described analytically.  
     137As a start, consider the case of starting a completely new ocean-only test case based on 
     138the ``LOCK_EXCHANGE`` example. 
     139[Note: we probably need an even more basic example than this with only one namelist and 
     140minimal changes to the usrdef modules] 
     141 
     142Firstly, construct the directory structure, starting in the ``cfgs`` directory: 
     143 
     144.. code-block:: sh 
     145 
     146   ./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE' 
     147 
     148where the ``-t`` option has been used to locate the new configuration in the ``tests`` subdirectory 
     149(it is recommended practice to keep full configurations and idealised cases clearly distinguishable). 
     150This command will have created (amongst others) the following files and directories:: 
     151 
     152   ./tests/MY_NEW_TEST: 
     153   BLD     MY_SRC cpp_MY_NEW_TEST.fcm 
     154   EXP00   WORK 
     155   # 
     156   ./tests/MY_NEW_TEST/EXP00: 
     157   context_nemo.xml       domain_def_nemo.xml 
     158   field_def_nemo-opa.xml file_def_nemo-opa.xml 
     159   iodef.xml 
     160   namelist_cfg 
     161   namelist_ref 
     162   # 
     163   ./tests/MY_NEW_TEST/MY_SRC: 
     164   usrdef_hgr.F90    usrdef_nam.F90 usrdef_zgr.F90 
     165   usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90 
     166 
     167The key to setting up an idealised configuration lies in adapting a small set of short Fortran 90 modules which 
     168should be dropped into the ``MY_SRC`` directory. 
     169Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in 
     170the ``src/OCE/USR`` directory is:: 
     171 
     172   ./src/OCE/USR: 
     173   usrdef_closea.F90 usrdef_istate.F90 usrdef_zgr.F90 
     174   usrdef_fmask.F90  usrdef_nam.F90 
     175   usrdef_hgr.F90    usrdef_sbc.F90 
     176 
     177Before discussing these in more detail it is worth noting the various namelist controls that 
     178engage the different user-defined aspects. 
     179These controls are set using two new logical switches or are implied by the settings of existing ones. 
     180For example, the mandatory requirement for an idealised configuration is to provide routines which 
     181define the horizontal and vertical domains. 
     182Templates for these are provided in the ``usrdef_hgr.F90`` and ``usrdef_zgr.F90`` modules. 
     183The application of these modules is activated whenever: 
     184 
     185.. code-block:: fortran 
     186 
     187   ln_read_cfg = .false. 
     188 
     189in any configuration's ``namelist_cfg`` file. 
     190This setting also activates the reading of an optional ``nam_usrdef`` namelist which can be used to 
     191supply configuration specific settings. 
     192These need to be declared and read in the ``usrdef_nam.F90`` module. 
     193 
     194Another explicit control is available in the ``namsbc`` namelist which activates the use of analytical forcing. 
     195With 
     196 
     197.. code-block:: fortran 
     198 
     199   ln_usr = .true. 
     200 
     201Other usrdef modules are activated by less explicit means. 
     202For example, code in ``usrdef_istate.F90`` is used to define initial temperature and salinity fields if 
     203 
     204.. code-block:: fortran 
     205 
     206   ln_tsd_init   = .false. 
     207 
     208in the ``namtsd`` namelist. 
     209The remaining modules, namely:: 
     210 
     211   usrdef_closea.F90 usrdef_fmask.F90 
     212 
     213are specific to ORCA configurations and set local variations of some specific fields for 
     214the various resolutions of the global models. 
     215They do not need to be considered here in the context of idealised cases but it is worth noting that all 
     216configuration specific code has now been isolated in the usrdef modules. 
     217In the case of these last two modules, they are activated only if an ORCA configuration is detected. 
     218Currently this requires a specific integer variable named ``ORCA`` to be set in a ``domain_cfg.nc`` file. 
     219[Note: this would be less confusing if the cn_cfg string is read directly as a character attribue from 
     220the ``domain_cfg.nc`` ] 
     221 
     222So, in most cases, the set up of idealised model configurations can be completed by 
     223copying the template routines from ``./src/OCE/USR`` into 
     224your new ``./cfgs/MY_NEW_TEST/MY_SRC`` directory and editing the appropriate modules as needed. 
     225The default set are those used for the GYRE reference configuration. 
     226The contents of ``MY_SRC`` directories from other idealised configurations may provide more convenient templates if 
     227they share common characteristics with your target application. 
     228 
     229Whatever the starting point it should not require too many changes or additional lines of code to 
     230produce routines in ``./src/OCE/USR`` that define analytically the domain, 
     231the initial state and the surface boundary conditions for your new configuration. 
     232 
     233To summarize, the base set of modules is: 
     234 
     235- ``usrdef_hgr.F90``   : define horizontal grid 
     236- ``usrdef_zgr.F90``   : define vertical grid 
     237- ``usrdef_sbc.F90``   : provides at each time-step the surface boundary condition, i.e. the momentum, heat and freshwater fluxes 
     238- ``usrdef_istate.F90``: defines initialization of the dynamics and tracers 
     239- ``usrdef_nam.F90``   : configuration-specific namelist processing to set any associated run-time parameters 
     240 
     241with two specialised ORCA modules 
     242(not related to idealised configurations but used to isolate configuration specific code that is used in 
     243ORCA2 reference configurations and established global configurations using the ORCA tripolar grid): 
     244 
     245- ``usrdef_fmask.F90`` : only used in ORCA CONFIGURATIONS for alteration of f-point land/ocean mask in some straits 
     246- ``usrdef_closea.F90``: only used in ORCA CONFIGURATIONS for specific treatments associated with closed seas 
     247 
     248From version 4.0, the NEMO release includes a ``tests`` subdirectory containing available and 
     249up to date test cases build by the community. 
     250These will not be fully supported as is NEMO reference but should provide a source of raw material. 
     251 
     252.. _here:                     http://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html?dataset=DatasetScanipsl_public/rron463/INPUT_SIREN.tar 
     253.. _the corresponding forum:  http://forge.ipsl.jussieu.fr/nemo/discussion/forum/2 
     254.. _SIREN documentation:      http://forge.ipsl.jussieu.fr/nemo/doxygen/index.html 
Note: See TracChangeset for help on using the changeset viewer.