New URL for NEMO forge!

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.
user/gm/Namelist_framework – NEMO

Version 9 (modified by nicolasmartin, 6 years ago) (diff)


Namelist framework proposition

This page is an attempt to provide a proposed general philosophy behind the namelist_ref structure and what should appear in namelist_cfg. It also suggests some improvements to the current namelist.

From a NEMO System Team perspective, the main objectif is to reduce drastically the duplication of sub-namelist in the namelist_cfg file for the standard configurations and test cases, and therefore facilitate namelist changes.

From a user perspective, the main objective is to have a configuration namelist where : (1) all key choices appear, and (2) on which choices they willingly rely on the default reference namelist. Note that users that want all the namelist choices available in the namelist_cfg can still just copy the reference namelist and modify it.

If adopted, such a description should probably appear in the DOC as well as in the system team and user wiki pages.

Reference namelist :

The ocean namelist contains 10 sections :

!! NEMO/OPA  :  1 - Domain & run manager (namrun, namcfg, namdom, namtsd, namcrs, namc1d, namc1d_uvd)
!! namelists    2 - Surface boundary (namsbc, namsbc_flx, namsbc_blk, namsbc_cpl,
!!                                    namsbc_sas, namtra_qsr, namsbc_rnf,
!!                                    namsbc_isf, namsbc_iscpl, namsbc_apr, 
!!                                    namsbc_ssr, namsbc_wave, namberg)
!!              3 - lateral boundary (namlbc, namagrif, nambdy, nambdy_tide)
!!              4 - top/bot boundary (namdrg, namdrg_top, namdrg_bot, nambbc, nambbl)
!!              5 - Tracer           (nameos, namtra_adv, namtra_ldf, namtra_eiv, namtra_dmp)
!!              6 - dynamics         (namdyn_adv, namdyn_vor, namdyn_hpg, namdyn_spg, namdyn_ldf)
!!              7 - Vertical physics (namzdf, namzdf_ric, namzdf_tke, namzdf_gls, namzdf_iwm)
!!              8 - diagnostics      (namnc4, namtrd, namspr, namflo, namhsb)
!!              9 - Obs & Assim      (namobs, nam_asminc)
!!             10 - miscellaneous    (nammpp, namctl, namsto)

There is three type of namelist : (1) "manager" ; (2) "associate manager" ; and (3) "specific" (may be called "self-contained" or autonomous" namelist ?).

(1) "manager" namelist : it is required in all user configuration. It defines key parameters and activate through a logical the reading of the "associate manager" namelists. By default, all choices are deactivated, while choices is required (the model will stop at the initialization phase if no choice is made) . Such a namelist is characterized by a " (default: NO selection) " comment at the end of their opening line :

&namXXX     !   sort description                                        (default: NO selection)

(2) "associate manager" namelist : It is read only if its associated flag (ln_xxxyyy) appearing in its father "manager" namelist is set to true. It contains reasonable default value that user may overwrite in namelist_cfg. Such a namelist is characterized by a " (ln_xxxyyy =T) " comment at the end of their opening line :

&namXXX     !   sort description                                        (ln_xxxyyy =T)

(3) "specific" namelist : they are associated with a pure optional feature (ocean parametrization such as namtra_eiv, naltra_mle, etc.) or option that does not change the the model trajectory (diagnostics, print control, etc.). They contains their own control switch (the first variable given in the namelist) and its default value is always FALSE. Such a type of namelist is characterized by a " (default: NO) " comment at the end of their opening line :

&namXXX     !   sort description                                        (default: OFF)

Note that two other settings of these 3 types of namelist may be adopted to add a better visual identification :

!! manager namelist
&namXXX        !   short description                                    (default: NO selection)

!! assistant manager
&namXXX        !   short description                                    (ln_xxxyyy =T)

!! specific namelist 
&namXXX        !   short description                                    (default: OFF)


!-== == == == == == == == == == == == == == == == == == == == == == == =
&namXXX        !   short description                                    (default: NO selection)
!-== == == == == == == == == == == == == == == == == == == == == == == =

!! assistant manager
!--= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
&namXXX        !   short description                                    (ln_xxxyyy =T)
!--= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

!! specific namelist 
&namXXX        !   short description                                    (default: OFF)

Note also that the I'm not very found of the tag for manager namelist :

"default: NO selection"

For example, they can be be :

"default: REQUIRE selection" or "selection REQUIRED" or just "REQUIRED" ?

or any other clever suggestion.

configuration namelist :

This namelist aims to overwrite the reference namelist values. The way it is set in all configurations and test cases (NEMOGCM/CONFIG directory) is the following : It have to contain :

(0) all the header of 10 sections of the ocean namelist, listing all the section namelist that are relevant for the configuration (e.g. C1D namelist description line will only appears in the C1D_PAPA configuration).

(1) In addition to namdom and namrun, ALL the "manager" namelist. Indeed, by definition all the "manager" namelists require to switch at least on namelist logical from FALSE to TRUE.

(2) only the "associate manager" namelist for which the two conditions are satisfied: -1- its manager namelist logical equal TRUE ; and -2- the default reference values that has been modified.

(3) only "specific" namelist for which the user have chosen to set to TRUE its control switch.

In ALL three types of namelist present in the namlist_cfg, only the namelist option that has been changed compare to the reference will appear.

Key changes compare to v3.6

  • No more ORCA2 specific choices in namelist_ref. Major changes:

namdta_tsd: ln_tsd_dmp = F ; ln_tsd_init = F

namsbc: nn_ice = 0 (no sea-ice) ; ln_blk = F ; ln_traqsr = F ; ln_rnf = F ; nn_fwb = 0

namrun: nn_no becomes the assimilation stage as it is now the only use of this parameter.

namtra_dmp: ln_tradmp = F

namsbc_ssr: nn_sssr =0

namlbc: rn_shlat = -9999. (a choice is therefore required)

namdyn_adv: ln_dynadv_vec = F

namzdf: ln_zdfevd = F

namzdf_ric: ln_mldw = F

NB: Not done but should be done: nn_fsbc = 1

  • generalize the notion of "manager", "associate manager" and "specific" namelists
  • add the possibility of having (in the solved Primitive Equation) NO trend in tracer or momentum advection and/or lateral mixing, Coriolis, …
  • set to false all option in "manager" namelists, switch off all switches that , except in so called "associated manager" namelists .
  • change to a dummy name all name and/or weight fields that need to be read in a NetCDF file.

things to be improved & questions :

  • move in namsbc_wave namelist all the wave related variable that are in namsbc except ln_wave switch, that is:
       ln_cdgw     = .false.   !  Neutral drag coefficient read from wave model (T => ln_wave=.true. & fill namsbc_wave)
       ln_sdw      = .false.   !  Read 2D Surf Stokes Drift & Computation of 3D stokes drift (T => ln_wave=.true. & fill namsbc_wave) 
       nn_sdrift   =  0        !  Parameterization for the calculation of 3D-Stokes drift from the surface Stokes drift
          !                    !   = 0 Breivik 2015 parameterization: v_z=v_0*[exp(2*k*z)/(1-8*k*z)]
          !                    !   = 1 Phillips:                      v_z=v_o*[exp(2*k*z)-beta*sqrt(-2*k*pi*z)*erfc(sqrt(-2*k*z))]
          !                    !   = 2 Phillips as (1) but using the wave frequency from a wave model
       ln_tauwoc   = .false.   !  Activate ocean stress modified by external wave induced stress (T => ln_wave=.true. & fill namsbc_wave)
       ln_tauw     = .false.   !  Activate ocean stress components from wave model
       ln_stcor    = .false.   !  Activate Stokes Coriolis term (T => ln_wave=.true. & ln_sdw=.true. & fill namsbc_wave)
       nn_lsm      = 0         !  =0 land/sea mask for input fields is not applied (keep empty land/sea mask filename field) ,
                               !  =1:n number of iterations of land/sea mask application for input fields (fill land/sea mask filename field)
  • create namisf, a "master" namelist for under-ice-shelf cavities. This namelist will regroup all ISF related control instead of the current spread of ISF control parameter throughout many namelists.
  • rename namtra_adv_mle ==>> namtra_mle to be consistent with eve name: namtra_eiv which are both associated with an extra advection for tracers. ==>>> DONE in rev @9532.
  • namlbc : the current default is no slip, should it be a required choice (set by default a negative value: -9999 or, a probably better case, set it by default to free slip ? ==>>>required choice DONE in revision @9527
  • namdyn_vor : add a ln_dynvor_noCOR option (used in some TEST_CASES (overflow and lock exchange)
  • move ln_icebergs from namberg to namsbc namelist (affect the surface ocean boundary condition, should be a "associate manager" namelist
  • nam_tide should it be an "associate manager" namelist ??
  • C1D: CPP key removed, C1D_PAPA moved in TEST_CASES, and ALL the three C1D namelist should be regrouped in ONE single namelist read in namusr_def namelist.
  • remove namelist control for output that are also controlled via the xIOS xml file

All suggestions for improvements are welcome '''

Dear all, The changes at change set 9490 have introduced a lot of name list changes that have 
undone all the work I did at change set 9356 to align all the reference and configuration name lists; I.e.:

r9356 | acc | 2018-02-23 17:32:30 +0000 (Fri, 23 Feb 2018) | 1 line

Branch: 2017/dev_merge_2017. Cosmetic (hopefully) changes to namelist files to enforce more 
consistency between reference and configuration name lists. 

See new file: NEMOGCM/CONFIG/SHARED/README.namelists for the conventions used.
For a brief period it was possible to do a simple side by side comparison of the reference 
and configuration name lists and have all the blocks line up. If no one else thinks this is useful 
then I'll give up the idea because it is too tedious to keep repeating that process if changes to 
namelists are not made incrementally with reference to the current head. 
Something to discuss at the next VC perhaps. 


Needs quite probably some discussion very soon.


gurvan: Yes indeed, didn't saw that such an action was ongoing. I have contacted Andrew.

From discussion with Andrew:

  • In logical namelist use "_OFF" instead of "_NONE" (e.g. ln_traldf_NONE ==> ln_traldf_OFF) DONE in @9526
  • "specific" namelist should be called self-contained or autonomous namelist

From Nicolas:
IMHO the best way to distinguish the different types of namelist should be from the name of the namelist itself. It would mean defining a naming convention like the ones we already have for files, modules and variables.
More or less it is what have been done so far with the naming of namxxx for manager namelist and namxxx_xxxx for related namelists, we should find a new naming convention to split related namelists between associate and specific namelists