[docu] Difference between namelist_changes and add_namelist_changes needs documentation

[christian-stepanek]

There is a critical difference in the results derived when adjusting namelists in the YAML with "namelist_changes" vs. employing "add_namelist_changes".

So far I find only a tiny statement, that can be easily overlooked, in the esm_tools documentation (section 6.2.3, page 20):
"However, ECHAM’s version 6.3.05p2-concurrent_radiation needs of further namelist changes written down in the same file inside a choose_block and for that we need to use the add_ functionality".

From that is not fully clear (at least to me) what is the general difference between both ways of defining namelist settings. In particular, is one safe if always add_namelist_changes is employed rather than namelist_changes per general rule? Furthermore, the statement in the documentation does not reveal that the difference is also of relevance for other models than echam with concurrent radiation.

Example FESOM2:

Using namelist_changes:
YAML (excerpt):

fesom:
    namelist_changes:
        namelist.oce:
            oce_tra:
                 surf_relax_s: 0.0

resulting namelist.oce (excerpt):

&oce_tra
   [...]
    surf_relax_s = 1.929e-06
    [...]
/

Using add_namelist_changes:
YAML (excerpt):

fesom:
    add_namelist_changes:
        namelist.oce:
            oce_tra:
                 surf_relax_s: 0.0

resulting namelist.oce (excerpt):

&oce_tra
   [...]
    surf_relax_s = 0
    [...]
/

I do not know where to best document this. But I believe this information should be highlighted somewhere prominent to avoid people getting confused on differences between their YAML-defined namelist changes and the namelist settings that are finally seen by the model (if they notice that problem at all).

[denizural]

Hi @christian-stepanek, thank you very much for pointing out the issue. Yes, I also encountered the same issue before. We will develop a unified solution to that. Thanks again.