Input

Requirements for a Simulation

To run a Simulation with ICON-ART there are three main points to consider: Setting the namelist parameters, preparing the xmls, and optionally prepare additional Input data.

Namelist Inputs

To run a simulation with ICON-ART installed the first thing to prepare is the runfile. It is usually best to start with an existing and working runfile and adapt parts as needed. The runfile contains the majority of parameters to run a simulation, like the length, timesteps and grids used, as well as a variety of options for methods and parametrisations used in the model. The runfile contents are then split up in several namelists that the model reads at the beginning of a simulation. An overview of the Namelist Parameters can be found in Namelist.

To enable ART in an ICON simulation, the switch lart = .TRUE. has to be set in the section &run_nml. This is the global on/off switch for ICON-ART. This is how this could look like in the context of a runfile:

! run_nml: general switches ----------
&run_nml
 ltestcase = .FALSE.
 num_lev = 50
 ltransport = .TRUE.
.............

 \textcolor{red}{lart = .TRUE.}

Generally the first letters of a namelist switch refer to its type, the "l" in "lart" stands for logical, meaning it has to be either True or False. Here are some examples.

Some namelist switches and their data types.

namelist switch	type
lart	logical
cart_aerosol_xml	character
iart_init_aero	integer

The namelist &art_nml is used for general options of the ART simulation. To run a certain kind of simulation the according switch has to be set to .TRUE.. For Example to include a point source the switch cart_aerosol_xml has to be set to .TRUE..

XML Inputs

This enables the inclusion of a .xml file containing additional information like location and strength of the point source. The table below contains the most important &art_nml namelist parameters and additional namelist parameters required if they are set to .TRUE..

XML files and their namelist dependencies

XML File	Description	Namelist parameter dependency	Default
cart_chemtracer_xml	Switch for simple OH chemistry	lart_chemtracer	.FALSE.
cart_mecca_xml	Switch for kpp chemistry	lart_mecca	.FALSE.
cart_pntSrc_xml	Enables addition of point sources	lart_pntSrc	.FALSE.
cart_aerosol_xml	Main switch for the treatment of atmospheric aerosols	lart_aerosol	.FALSE.
cart_modes_xml	Main switch for the treatment of atmospheric aerosols	lart_aerosol	.FALSE.
cart_diagnostics_xml	Enables diagnostic output fields	lart_diag_out	.FALSE.
cart_pntSrc_xml	Enables creation of point sources emitting given Aerosols at a given rate	lart_pntSrc	.FALSE.
cart_emiss_xml_file	XML File for emission metadata	-	-
cart_ext_data_xml	XML File for metadata of datasets prescribing tracers	-	-
cart_coag_xml	XML File containing additional information about coagulation

The reason for the use of those additional .xml files is that the ART variables they contain (sea salt, mineral dust etc.) might be different for every run which differs from the Icon Variables (Temperature, Pressure, etc.) which usually don’t change between runs. .xml files are readable for both humans and machines, which makes them easy to tweak and integrate. An Example for the contents of an .xml file adding ash particles can be seen below.

<modes>
  <aerosol id="asha">
    <kind type="char">2mom</kind>
    <d_gn type="real">1.190E-6</d_gn>
    <sigma_g type="real">1.410E+0</sigma_g>
    <rho type="real">2.600E+3</rho>
  </aerosol>
</modes>

Here is an example for a more complex .xml using AERODYN: This is an example for the number and mass concentration of dust in a tracer .xml.

<tracers>  
    <aerosol id="nmb">    
      <moment type="int">0</moment>    
      <mode type="char">insol_acc,insol_coa</mode>    
      <unit type="char">kg-1</unit>    
      <transport type="char">hadv52aero</transport>  
    </aerosol>  
    <aerosol id="dust">    
      <moment type="int">3</moment>    
      <mode type="char">insol_acc,insol_coa</mode>    
      <sol type="real">1.0</sol>    
      <mol_weight type="real">50.00E-3</mol_weight>    
      <rho type="real">2.650E3</rho>    
      <unit type="char">mug kg-1</unit>    
      <transport type="char">hadv52aero</transport>  
    </aerosol>
</tracers>

Further .xml examples can be fount in /your_ART_Directory/runctrl_examples/xml_ctrl.

Input Data

Depending on the type of simulation there might be additional input files required. These are essential files that are not contained in classical ICON initialisation data. For example for the emission of mineral dust there has to be information about the soil types supplied to the model. The additional input files should be renamed to a netcdf file and follow the naming convention shown in fig 1.1. Please note that the XXX has to be replaced by one of the indices mentionend in Table input-init and input-emissions.

Additional input files for the initialisation

Species	Namelist switch	Options	XXX
Gas	iart_init_gas	0 (cold start), 5 (from file)	IGX
Aerosol	iart_init_aero	0 (cold start), 5 (from file)	IAE

Additional input files for the emissions

Type	Data	XXX
Point souces	XML-file	-
Sea salt	no extra data necessary	-
Mineral Dust	Soil Type Data	ART_STY
Biogenic VOCs	Emissions or Vegetatiom	ART_STY
Athropogenic emissions	Emission data sets	ART_BIO ART_ANT
Biomass burning	Satellite data	ART_BCF

Obtaining Input Data

The 2 ways of obtaining input data are to generate it yourself or download it.

How to generate input data

How to download input data

Running a Limited Area Meteorology (LAM) Simulation

General

Here are some notes on setting up an ICON-ART LAM simulation. Theses settings are important if you use initial data and boundary data from different sources. It is preferable to use data from the same source to be consistent. However, in certain situations this is not possible due to limitations of the model (e.g. initialization routines).

Required data for LAM domain

Grid of LAM domain external parameters of LAM domain external parameters containing soil parameters (only necessary for dust simulations) initial data (ICON-ART or IFS)

Required data for LAM boundaries

Auxiliary grid (grid containing boundary area of the LAM domain, generated during remapping process with ICONtools) forcing data for the boundaries

Initialization

There are two different possible methods to read in the dust during initialization. You can either pass a file containing meteorological variables and a second file containing dust data. The vertical levels may differ between these two files and the dust must be delivered as ART_IAE file. The corresponding namelist setting in &art_nml is iart_init_aero=5

The other possibility is to pass all variables required for the initialization in a single file. The vertical levels must all be consistent and the corresponding namelist setting in &art_nml is iart_init_aero=0 . Furthermore you have to add file in the tracer xml file.

Boundary Data:

The boundary data can only be passed to the model as one single file per time step. The vertical levels for all time steps must be the same. Otherwise an error occurs. If you use data from a different source than the one used for initialization, it is crucial to decouple the reading of the boundary data from the reading of initial data. During the start of the simulation it is possible to read the first boundary data from the initial data when using ICON-ART data. To prevent this and to read the boundary data from a separate file during initialization, set init_latbc_from_fg = .FALSE. in &limarea_nml . Additionally you have to add file in the tracer xml file.