# Namelists Namelists for the ICON-ART model runs can be created and included either from a [Fortran namelist](#fortran-namelist-as-template) or from a [yaml file](#yaml-file-as-template). The namelist files will be processed and written to the output directory, from where ICON reads them. The init script will create the appropriate [files and symliks](Configuration-files.md#symlinks-created-by-the-init-script) for the namelist to be modified. The master namelist is always fully provided by _auto-icon_. For the atmosphere (and ocean) namelist(s), _auto-icon_ will 1. read in the respective file, 2. substitute [Autosubmit placeholders](#autosubmit-placeholders), 3. add all parameters that were not explicitly provided by the user (see [Generally added parameters](#generally-added-parameters)), 4. overwrite modified parameters (e.g. [member modifications](#changing-the-namelist-for-each-member) or reinit parameters) and 4. write the full namelist file. ## Modifications ### Autosubmit placeholders Every Autosubmit placeholder (enclosed by `%...%`) is replaced with the respective entry from the configuration files. If an entry is not present, the placeholder is replaced with an empty string. Placeholders can be grouped into yaml sections as in the experiment definitions file: ```yaml EXPERIMENT: TIMESTEP: ``` To refer to the time step, the placeholder `%EXPERIMENT.TIMESTEP%` needs to be used. The most important placeholders for the namelist are defined in the experiment configuration file. :::{seealso} [Autosubmit Variables reference](https://autosubmit.readthedocs.io/en/master/userguide/variables.html) ::: ### Generally added parameters Several parameters are added to the namelist if they are missing: * Grid and radiation grid information * File type of input/output files * The time step is set to the value of `EXPERIMENT.TIMESTEP` (python expressions allowed) * Slow physics time steps are replaced (see below) * For all `output_nml` groups, the following will be inserted: * Filetype * output start and end are set to the simulation boundaries * `output_interval` with the corresponding value from the `EXPERIMENT` section * `file_interval` and `steps_per_file` (mutually exclusive) with the respective values of the `EXPERIMENT` section. * If reinitialization is done, additional output files are added to write the final state for those variables that shall be continued to the next run. A summary of all added entries is presented here: ``` &grid_nml dynamics_grid_filename = ... radiation_grid_filename = ... lredgrid_phys = ... &run_nml dtime = ... ! depending on EXPERIMENT.TIMESTEP modelTimeStep = ... ! depending on EXPERIMENT.TIMESTEP &nwp_phy_nml dt_rad = ... dt_conv = ... dt_ccov = ... dt_sso = ... dt_gwd = ... &initicon_nml filetype = ... &io_nml restart_file_type = ... &output_nml filetype = ... output_start = output_end = file_interval = ... ! alternatively 'steps_per_file' steps_per_file = ... ! alternatively 'file_interval' ``` :::{tip} If you want to have a mix of `file_interval` and `steps_per_file` for different output namelists, you need to explicitly specify the default for one type. For all other groups where you need to specify both, one with an empty value. E.g. you specify `file_interval` as default, and then specify `file_interval: ""` and `steps_per_file: 6` in the other groups. ::: :::{tip} These keys are only added if missing, i.e. you can overwrite this mechanism by specifying their value in the namelist. ::: #### Time steps The time step can be specified either in the namelist directly or with the `EXPERIMENT.TIMESTEP` key. The latter will be set for `dtime` if it is an integer or for `modelTimeStep` if it is a ISO period string. Further, a python expression that evaluates to seconds (i.e. an integer) can be supplied also. For convenience, the slow physics time steps (for RAD, CONV, CCOV, SSO, GWD) can be also set in two ways in the `EXPERIMENT` section: 1. `EXPERIMENT.TIMESTEP_FACTORS.DT_` is multiplied by `dtime` and will be set accordingly. 2. `EXPERIMENT.TIMESTEP_PHY.` is set directly. Lastly, `TIMESTEP_OCEAN` and `TIMESTEP_COUPLING` can be used to explicitly set the time steps for ocean and coupling between atmosphere and ocean. :::{note} The timestep factors are included to ease transition of the model resolution. The other settings are mostly for convenience to have all the timing information contained in the `EXPERIMENT` section. ::: ### Parameter substitution In the same way as some [parameters are added](#generally-added-parameters) some parameters are substituted, i.e. overwriting provided values. These are the member parameters (see [below](#changing-the-namelist-for-each-member)) and parameters that shall be substituted for all chunks except the first (listed in `EXPERIMENT.NML_SUB_NOT_FIRST` and `REINITIALIZATION.REINIT_SUBSTITUTES`, see [here](/Userguide/Important-configuration.md#substituting-namelist-parameters) for details) ## Fortran namelist as template Fortran namelist do not support changing the configuration with Members (see [below](#changing-the-namelist-for-each-member)). ## Yaml file as template The atmosphere namelist requires a yaml section `NAMELIST`, with a set of yaml sections each representing a namelist group: ```yaml NAMELIST: parallel_nml: nproma: 8 num_io_procs: 1 iorder_sendrecv: 3 run_nml: num_lev: 90 ltransport: True iforcing: 3 output: "nml" transport_nml: itype_vlimit: [1,1,1,1,1] ``` The types need to be correct yaml types in order to be parsed correctly, i.e. boolean values need to be `True` or `False` and just like floats or integers not be encapsulated within quotes. Further, lists need to be embraced within square brackets (or written in the yaml list representation with dashes). :::{important} Yaml keys need to be unique. If you require multiple output sets, provide a suffix to each of them, e.g. `output_nml-1`, `output_nml-2`, ... They will be processed correctly to yield multiple `output_nml` groups. ::: ### Changing the namelist for each member The namelist can be adjusted for each member to manage multiple similar runs at once, e.g. for different types of parametrizations. To do so, a new section `MEMBERS` with a subsection for each member (that needs namelist modifications) has to be added to the yaml namelist file: ```yaml MEMBERS: member-1: namelist_a_nml: ivar: 1 member-2: namelist_a_nml: ivar: 3 rvar: 1.2 namelist_b_nml: cvar: value ``` :::{important} Member sections have to be named exaclty as the members (case-sensitive!). ::: :::{important} Namelist section names will be matched against each namelist group from the beginning, i.e. for a configuration ```yaml MEMBERS: member-1: output_nml: ... output_nml-2: ... ``` the `output_nml` will match __all__ ouptut sections, `output_nml-2` will match e.g. sections `output_nml-2` and `output_nml-21` but not `my-output_nml-2` or `output_nml-12`. :::