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 | |
| 12 | Starting from an existing one |
| 13 | -------------------------------- |
| 14 | |
| 15 | There 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 |
| 18 | in 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 |
| 23 | the 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 |
| 29 | configuration. |
| 30 | |
| 31 | This last option employs the SIREN software tools that are included in the standard |
| 32 | distribution. The software is written in FORTRAN95 and available in the |
| 33 | ``NEMOGCM/TOOLS/SIREN`` directory of ``nemo_v3_6_STABLE`` (since revision 6468). SIREN |
| 34 | allows you to create your own regional configuration embedded in a wider one. |
| 35 | |
| 36 | SIREN is a set of programs to create all the input files you need to run a NEMO regional |
| 37 | configuration. As a basic demonstrator, a set of GLORYS files (GLObal ReanalYSis on the |
| 38 | ORCA025 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 | |
| 43 | Any 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 | |
| 47 | Creating a completely new configuration |
| 48 | ---------------------------------------------- |
| 49 | |
| 50 | From NEMO version 4.0 there are two ways to build configurations from scratch. The |
| 51 | appropriate method to use depends largely on the target configuration. Method 1 is for |
| 52 | more complex/realistic global or regional configurations and method 2 is intended for |
| 53 | simpler, idealised configurations whose domains and characteristics can be described in |
| 54 | simple geometries and formulae. |
| 55 | |
| 56 | Method 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 |
| 60 | house your new configuration by duplicating the closest reference configuration to your |
| 61 | target application. For example, If your application requires both ocean and ice |
| 62 | components then run:: |
| 63 | |
| 64 | makenemo –n MY_NEW_CONFIG -r ORCA_LIM3 |
| 65 | |
| 66 | where ``MY_NEW_CONFIG`` can be substituted with a suitably descriptive name for your new |
| 67 | configuration. The purpose of this step is simply to create and populate the appropriate WORK, |
| 68 | MY_SRC and EXP00 subdirectories for your new configuration. Other choices for the base reference |
| 69 | configuration 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 |
| 76 | file called ``domain_cfg.nc`` which you will need to create and place in the:: |
| 77 | |
| 78 | NEMOGCM/CONFIG/MY_NEW_CONFIG/EXP00 |
| 79 | |
| 80 | sub-directory. Firstly though, ensure that your configuration is set to use such a file by |
| 81 | confirming that:: |
| 82 | |
| 83 | ln_read_cfg = .true. |
| 84 | |
| 85 | in:: |
| 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 | |
| 108 | There 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 | |
| 119 | Method 2: Copy and modify user-defined configuration modules |
| 120 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 121 | |
| 122 | This method is intended for configuring easily defined idealised configurations which are |
| 123 | often used as demonstrators or for process evaluation and comparison. This method can be |
| 124 | used whenever the domain geometry has a simple mathematical description and the ocean |
| 125 | initial state and boundary forcing is described analytically. From version 4.0, the NEMO |
| 126 | release includes a ``TEST_CASES`` subdirectory of the reference ``CONFIG`` directory which |
| 127 | includes several examples and will, over time, include further user-contributed examples. |
| 128 | These will not necessarily be fully supported but should provide a source of raw material |
| 129 | and ideas for constructing your own examples. |
| 130 | |
| 131 | For now, consider the case of starting a completely new ocean-only test case based on the |
| 132 | LOCK_EXCHANGE example. [Note: we probably need an even more basic example than this with |
| 133 | only one namelist and minimal changes to the usrdef modules] |
| 134 | |
| 135 | Firstly, construct the directory structure, starting in the ``CONFIG`` directory:: |
| 136 | |
| 137 | ./makenemo -a TEST_CASES -n MY_NEW_TEST -r LOCK_EXCHANGE |
| 138 | |
| 139 | where 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 |
| 141 | idealised cases clearly distinguishable). This command will have created (amongst others) |
| 142 | the 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 | |
| 159 | The key to setting up an idealised configuration lies in adapting a small set of short fortran90 |
| 160 | modules which should be dropped into the MY_SRC directory. Here the LOCK_EXCHANGE example is using |
| 161 | 5 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 | |
| 168 | Before discussing these in more detail it is worth noting the various namelist controls |
| 169 | that engage the different user-defined aspects. These controls are set using two new |
| 170 | logical switches or are implied by the settings of existing ones. For example, the |
| 171 | mandatory requirement for an idealised configuration is to provide routines which define |
| 172 | the 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 |
| 174 | activated whenever:: |
| 175 | |
| 176 | ln_read_cfg = .false. |
| 177 | |
| 178 | in any configuration's ``namelist_cfg`` file. This setting also activates the reading of |
| 179 | an optional ``nam_usrdef`` namelist which can be used to supply configuration specific |
| 180 | settings. These need to be declared and read in the ``usrdef_nam.F90`` module. |
| 181 | |
| 182 | Another explicit control is available in the ``namsbc`` namelist which activates the |
| 183 | use of analytical forcing. With:: |
| 184 | |
| 185 | ln_usr = .true. |
| 186 | |
| 187 | Other 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 | |
| 192 | in the ``namtsd`` namelist. The remaining modules, namely:: |
| 193 | |
| 194 | usrdef_closea.F90 usrdef_fmask.F90 |
| 195 | |
| 196 | are specific to ORCA configurations and set local variations of some specific |
| 197 | fields for the various resolutions of the global models. They do not need to be |
| 198 | considered here in the context of idealised cases but it is worth noting that all |
| 199 | configuration specific code has now been isolated in the usrdef modules. In the |
| 200 | case of these last two modules, they are activated only if an ORCA configuration |
| 201 | is detected. Currently this requires a specific integer variable named ``ORCA`` |
| 202 | to be set in a domain_cfg.nc file. [Note: this would be less confusing if the |
| 203 | cn_cfg string is read directly as a character attribue from the domain_cfg.nc] |
| 204 | |
| 205 | So, in most cases, the set up of idealised model configurations can be completed by |
| 206 | copying 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 |
| 208 | needed. The default set are those used for the GYRE reference configuration. |
| 209 | The contents of ``MY_SRC`` directories from other idealised configurations |
| 210 | may provide more convenient templates if they share common characteristics with your |
| 211 | target application. |
| 212 | |
| 213 | Whatever the starting point it should not require too many changes or additional lines of |
| 214 | code to produce routines in NEMOGCM/NEMO/OPA_SRC/USR that define analytically the domain, |
| 215 | the initial state and the surface boundary conditions for your new configuration. |
| 216 | |
| 217 | In 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 | |
| 225 | with two specialised ORCA modules (not related to idealised configurations but used to isolate |
| 226 | configuration specific code that is used in ORCA2 reference configurations and established |
| 227 | global 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 |