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.

---

bold letters indicate which tags are always required.

Chemistry Tracers

tag	type	options	description
c_solve	character	param, lt, cold, OH, linoz, simnoy, passive	solving mechanism/strategy
emissions		anthropogenic, biogenic, biomassBurning	usage see in tracers_chemtracer_amip.xml (*)
htop_proc	real	in m	top height for processes
iconv	integer	0 (off), 1 (on)	transport by convection (default=1)
initc	character	file	initialize from Input file
init_mode	integer	0 (off), 1 (on)	initialize tracer
init_name	character		name of tracer in initialization file
iturb	integer	0 (off), 1 (on)	transport by turbulence (default=1)
latbc	character	file	read data for LBC
lfeedback	integer	0 (off), 1 (on)	child -> parent feedback in nested simulations (default=0)
lifetime	real	in s	value for lifetime
mol_weight	real	in kg/mol	value for molar weight
products	character	name of tracer	name of resulting tracer after depletion
tag001,...	character		name of tag to be added to tracer name
transport	character	stdaero, stdchem, ..., off	choice of transport template
unit	character	e.g., mol mol-1	unit of tracer

(*) in icon-kit/externals/art/runctrl_examples/xml_ctrl/

Aerosol Tracers

tag	type	options	description
htop_proc	real	in m	top height for processes
initc	character	file	initialize from Input file
inucl	integer	0 (off), 1 (on)	H2SO4 nucleation for so4 tracer (default=1); 1 for so4_sol_ait, 0 for other so4 tracer)
label	character	e.g., dusta	allows to name tracers individually
latbc	character	file	read data for LBC
lfeedback	integer	0 (off), 1 (on)	child -> parent feedback in nested simulations (default=0)
mode	character	insol_acc, mixed_acc,..	indicates in which modes the tracer occurs
mol_weight	real	in kg/mol	value for molar weight
moment	integer	0, 3	zeroth (number) or third (mass) moment
rho	real	in g/m3	density of tracer, not needed for zeroth moment
sol	integer	0 (no), 1 (yes)	indicates whether the tracer is soluble or not
transport	character	stdaero, stdchem, ..., off	choice of transport template
unit	character	e.g., mug kg-1, kg-1	unit of tracer

Aerosol Modes

tag	type	options	description
condensation	integer	0 (off), 1 (on)	condensation of H2SO4 on this mode?
d_gn	real	in m	value for the initial median diameter of the number distribution
dissfac_mean	real		dissociation factor (needed with ikoehler=1)
icoag	integer	0 (off), 1 (on)	mode involved in coagulation? If 1 for any mode, then provide coagulate.xml
ikoehler	integer	0 (off), 1 (on)	Activation via Köhler theory (warm clouds), needs dissfac_mean tag
kind	character	1mom or 2mom	1-moment or 2-moment description of distribution
sigma_g	real		standard deviation of the distribution
shift2larger	character	e.g., sol_acc	Name of larger mode to be shifted to, when diameter threshold (shift_diam) exceeded
shift2mixed	character	e.g., mixed_acc	Name of mixed mode to be shifted to, when soluble mass threshold of 5% exceeded
shift_diam	real	in m	diameter threshold for shift2larger

Aerosol Emission

tag	type	options	description
nmodes	integer		number of emission modes
d_g0_*	real		median diameter of number distribution of mode * (e.g., d_g0_1, d_g0_2, d_g0_3)
d_g3_*	real		median diameter of mass distribution of mode * (e.g., d_g3_1, d_g3_2, d_g3_3)
rho	real	in kg/m3	particle density (same for all modes)
sigma_g_*	real		standard deviation of mode *
substance	character	ash, dust, na, cl, soot	emitted substance

routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3

Point Source

tag	type	options	description
dg3_emiss	real	in m	median diameter of aerosol mass distribution
emiss_profile	character		anti-derivative of emission profile
endTime	character		end time of emission (default=9999-12-31T00:00:00)
height	real	in m	emission height
height_bot	real	in m	bottom height
lat	real	in degree	latitude
lon	real	in degree	longitude
sigma_emiss	real		standard deviation of aerosol distribution
startTime	character		start time of emission (default=1582-10-15T00:00:00)
source_strength	real		emission source strength
substance	character	e.g., TRSO2	substance nme from tracer xml
unit	character	e.g., kg s-1	unit of source strength