Namelists#

Namelists for the ICON-ART model runs can be created and included either from a Fortran namelist or from a yaml file. 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 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,

  3. add all parameters that were not explicitly provided by the user (see Generally added parameters),

  4. overwrite modified parameters (e.g. member modifications or reinit parameters) and

  5. 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:

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.

See also

Autosubmit Variables reference

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 = <simulation start>
  output_end = <simulation 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_<type> is multiplied by dtime and will be set accordingly.

  2. EXPERIMENT.TIMESTEP_PHY.<type> 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 some parameters are substituted, i.e. overwriting provided values. These are the member parameters (see below) 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 for details)

Fortran namelist as template#

Fortran namelist do not support changing the configuration with Members (see below).

Yaml file as template#

The atmosphere namelist requires a yaml section NAMELIST, with a set of yaml sections each representing a namelist group:

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:

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

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.