icon-art guide - User contributions [en]

Input

2023-08-25T08:15:44Z

Tim R: Nested Grid Creation

== 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 <code>lart = .TRUE.</code> has to be set in the section <code>&run_nml</code>. This is the global on/off switch for ICON-ART. This is how this could look like in the context of a runfile:

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

\textcolor{red}{lart = .TRUE.}</pre>
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.

<div id="tab:vartypes">

{| class="wikitable" style="text-align:left;"
|+ Some namelist switches and their data types.
! namelist switch
! type
|-
| <code>lart</code>
| logical
|-
| <code>cart_aerosol_xml</code>
| character
|-
| <code>iart_init_aero </code>
| integer
|}

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

== XML Inputs ==

This enables the inclusion of a .xml file containing additional information like location and strength of the point source. The table [[#tab:art_nml-params|below]] contains the most important <code>&art_nml</code> namelist parameters and additional namelist parameters required if they are set to <code>.TRUE.</code>.

<div id="tab:art_nml-params">

{| class="wikitable" style="text-align:left;"
|+ XML files and their namelist dependencies
! XML File
! Description
! Namelist parameter dependency
! Default
! Further Information
|---
| <code>cart_chemtracer_xml</code>
| Switch for simple OH chemistry
| <code>lart_chemtracer</code>
| .FALSE.
|[[#Chemistry Tracers|Chemistry Tracers]]
|-
| <code>cart_mecca_xml</code>
| Switch for kpp chemistry
| <code>lart_mecca</code>
| .FALSE.
|[[Atmospheric Chemistry]]
|-
| <code>cart_pntSrc_xml</code>
| Enables creation of point sources emitting given Aerosols at a given rate
| <code>lart_pntSrc</code>
| .FALSE.
|[[#Point Source|Point Source]]
|-
| <code>cart_aerosol_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|[[#Aerosol Tracers|Aerosol Tracers]]
|-
| <code>cart_modes_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|[[#Aerosol Modes|Aerosol Modes]]
|-
| <code>cart_diagnostics_xml</code>
| Enables diagnostic output fields
| <code>lart_diag_out</code>
| .FALSE.
| -
|-
| <code>cart_emiss_xml_file</code>
| XML File for emission metadata
| -
| -
|[[#Aerosol Emission|Aerosol Emission]]
|-
| <code>cart_ext_data_xml</code>
| XML File for metadata of datasets prescribing tracers
| -
| -
| -
|-
| <code> cart_coag_xml </code>
| XML File containing additional information about coagulation
| -
| -
| -
|}

</div>

{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Tracers">Aerosol Tracers</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Modes">Aerosol Modes</span>
|-
! 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
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Emission">Aerosol Emission</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br \> routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Point Source">Point Source</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Chemistry Tracers">Chemistry Tracers</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br\> (*) in icon-kit/externals/art/runctrl_examples/xml_ctrl/
|}

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.
<syntaxhighlight lang=xml line>
<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>
</syntaxhighlight>

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.
<syntaxhighlight lang=xml line>
<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>
</syntaxhighlight>

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

== 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 [[#input-names|1.1]]. Please note that the XXX has to be replaced by one of the indices mentionend in Table [[#tab:input-init|input-init]] and [[#tab:input-emissions|input-emissions]].

[[File:input-names.png|800px|none|alt=ICON-ART input file naming convention.|ICON-ART input file naming convention.]]

<div id="tab:input-init">

{| class="wikitable" style="text-align:left;"
|+ Additional input files for the initialisation
! Species
! Namelist switch
! Options
! XXX
|-
| Gas
| <code>iart_init_gas</code>
| 0 (cold start), 5 (from file)
| IGX
|-
| Aerosol
| <code>iart_init_aero</code>
| 0 (cold start), 5 (from file)
| IAE
|}

</div>
<div id="tab:input-emissions">

=== 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]]

=== Emission Data ===
In every ICON-ART, there is the possibility to add additional input data like emission data that correspond with different sources. A quick overview about them can be found below.
{| class="wikitable" style="text-align:left;"
|+ 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
|}

==== Chemical Tracer ====
Emission data can be obtained from several sources. The following table should give an overview about which emission data are available for a corresponding tracer. To find out when to use which emission data type we recommend respective further reading.
{| class="wikitable"
! Tracer !! Emission Type !! Emission !! Resolution
|-
| C2H6 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || BBE || GFED || R2B04_ECHAM
|-
| || || GFED3 || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || BIO || MEGA || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| C3H8 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED || R2B04_ECHAM
|-
| || || GFED3 || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || BIO || MEGA || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B07_nest
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| C5H8 || BBE || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CFCl3 || ANT || GEIA || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3CN || BBE || GFED.1s_Akagi_daily || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Akagi_monthly || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Stockwell_daily || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Stockwell_monthly || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3COCH3 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || || R3B07_0026
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GICC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GUESS-ES || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || RETRO || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MEGANv2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3I || BIO || Bell || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ziska || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH4 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || || R3B08_0049
|-
| || || EDGARv4.2 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || || EDGARv4.3.1 || R2B04_0012
|-
| || || || R2B05_0014
|-
| CHBr3 || BIO || Liang || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ordonez || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ziska || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CO || ANT || EDGAR || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || EDGARv4.2 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GICC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GUESS-ES || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || RETRO || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MEGANv2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CO2 || ANT || EDGARv4.2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B06_0031_nest
|-
| || || || R2B07_0018
|-
| || || || R2B07_nest
|-
| || || || R3B07_0022
|-
| || || || B3B07_0026
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| DMS || BBE || GFED3 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| N2O || ANT || EDGARv4.2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| NH3 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MACCity_agriculture || R2B06_0016
|-
| || || MACCity_agric_waste || R2B06_0016
|-
| || || MACCity_energy || R2B06_0016
|-
| || || MACCity_industrial || R2B06_0016
|-
| || || MACCity_residential || R2B06_0016
|-
| || || MACCity_transport || R2B06_0016
|-
| SF6 || ANT || EDGARLevin || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| SO2 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_nest
|-
| || || || R3B07_0022
|-
| || || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|}

==== Remapping Emissions ====
A comprehensible manual can be found [https://gitlab.dkrz.de/art/kit-wiki/-/wikis/uploads/44c05db0bff5da516d7812292de3dff8/MECCA_Emissions01.pdf here]. The document was provided by M. Weimer (June 2019).
This document provides an overview of the workflow to be done in order to remap a set of emission data onto your own ICON grid. The raw emission data can be taken from emission inventories such as Edgar, MACCity, etc. (see above).
The desired files can be copied to an own directory where they serve as input for the remap procedure described in the manual.
Additional remarks:
* The mentioned workflow was initially designed for FH2. Should be tested on other machines as well
* The automatic addition of emission tags to the tracer.xml (add_emissions_to_tracer_xml.py) is very sensitive to tracer names and emission species. In doubt, add emission tags manually.
* In any case, double check if all emission tags have been assigned to the correct tracer

== 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<code> &art_nml </code> is <code> iart_init_aero=5 </code>

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 <code> &art_nml</code> is <code> iart_init_aero=0 </code>. 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 <code>init_latbc_from_fg = .FALSE. </code>in <code> &limarea_nml </code>. Additionally you have to add file in the tracer xml file.

------
[[#Aerosol Tracers]]

== Creating A Nested ICON-Grid ==
There are four steps to create a grid. The steps have to be run separately as they are dependent on each other.
=== Graph Generation ===
The first step is creating the graph. Ensure that you specify R and B for the finest nest! I.e. if you plan a global R2B6 grid with a R2B7 Nest, you have to set R=2 and B=7.
An example namelist in a runscript looks like this:
<pre>cat > NAMELIST_GRAPH << EOF
&graph_ini
nroot = ${R}
grid_levels = ${B}
/
EOF

echo global_graph_generator null > $commandFile
job_submit -c p -p 1 -t 60 -m 32000 ${run_commmand}</pre>
You might have to increase the allocated memory (-m 64000) if the process crashes (-p 1 is maximum because of lacking parallelization)
=== Grid generation ===
The second step is the generation of all (global) grids. I.e., if you choose R=2 and B=7, you get global grids for R2B1, R2B2, R2B3, R2B4, R2B5, R2B6 and R2B7. Even if you want R2B7 to be your nest, you have to do this step down to R2B7! This means, that the values of R and B for step 1 and 2 must not differ.
As far as I could figure out, the spring dynamics optimization is the one to choose. Therefore, you should choose @itype_optimize = 4@.
An example namelist looks like this:
<pre>cat > NAMELIST_GRID << EOF
&grid_ini
nroot = ${R}
grid_levels = ${B}
/
&grid_options
itype_optimize = 4
/
EOF

echo global_grid_generator null > $commandFile
job_submit -c p -p 1 -t 600 -m 32000 ${run_commmand}</pre>
If you want to generate a finer grid (e.g. R2B10) you might have to increase the allocated memory (-m 256000).
=== Modify the filenames ===
The spring-dynamics-optimized files carry this information within their filename. In order to continue, the names have to be changed to the standard names of grids. This can be done within a script as shown in the following. (@maxlev_optim@ is a parameter, that specifies the maximum level to which optimizations are applied. This is set in the previous step within the grid_options namelist. As the default is 100, there is usually no need to change this. You just have to set the variable @maxlev_optim@ within the script for the copying):
<pre>level=1;
while [[ $level -le $maxlev_optim ]] ; do
cp iconR${R}B0${level}-grid_spr0.90.nc iconR${R}B0${level}-grid.nc
((level=$level+1))
done</pre>
=== Nested grid creation ===
As a last step, you have to specify the nests. In the following example, three nests are added to a global R2B6 grid. Therefore, @start_lev = 6@ and @n_dom = 4@. As these nests are subsequent, the @parent_id@ of each nest is the one of the domain with one rank higher. I.e. R2B6 has the ID 1, therefore the @parent_id@ of R2B7 is 1. R2B8 has the ID of the R2B7 as @parent_id@ and therefore 2. The different domains are seperated by commas in the namelist. The global domain does of course not show up (you produced the global grid files in step 2).
In this example, the further namelist variables mean the following:
@l_circ@ gives the nests a circular instead of an rectangular shape.
@l_plot@ provides output which can be used to plot the grids with GMT scripts.
@radius, center_lon, center_lat@ define the location of the nests.
With @lsep_gridref_info = .true.@ the grid information is stored within an additional grid description file. This needs then to be specified within ICON!
<pre>cat > NAMELIST_GRIDREF << EOF
&gridref_ini
grid_root = 2
start_lev = 6
n_dom = 4
parent_id = 1,2,3
l_circ = .true.
l_plot = .true.
radius = 20.,12.,12.
center_lon = 10.,5.,5.
center_lat = 40.,47.5,47.5
bdy_indexing_depth = 14
lsep_gridref_info = .false.
/
EOF

echo global_grid_refine null > $commandFile
job_submit -c p -p 64 -t 60 -m 16000 ${run_commmand}</pre>
If you want to generate a finer grid (e.g. R2B10) you might have to increase the allocated memory (-m 64000).

Input

2023-08-25T08:04:35Z

Tim R: Remapping Emissions added

Input

2023-08-10T15:54:08Z

Tim R: /* Emission Data */

== 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 <code>lart = .TRUE.</code> has to be set in the section <code>&run_nml</code>. This is the global on/off switch for ICON-ART. This is how this could look like in the context of a runfile:

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

\textcolor{red}{lart = .TRUE.}</pre>
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.

<div id="tab:vartypes">

{| class="wikitable" style="text-align:left;"
|+ Some namelist switches and their data types.
! namelist switch
! type
|-
| <code>lart</code>
| logical
|-
| <code>cart_aerosol_xml</code>
| character
|-
| <code>iart_init_aero </code>
| integer
|}

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

== XML Inputs ==

This enables the inclusion of a .xml file containing additional information like location and strength of the point source. The table [[#tab:art_nml-params|below]] contains the most important <code>&art_nml</code> namelist parameters and additional namelist parameters required if they are set to <code>.TRUE.</code>.

<div id="tab:art_nml-params">

{| class="wikitable" style="text-align:left;"
|+ XML files and their namelist dependencies
! XML File
! Description
! Namelist parameter dependency
! Default
! Further Information
|---
| <code>cart_chemtracer_xml</code>
| Switch for simple OH chemistry
| <code>lart_chemtracer</code>
| .FALSE.
|[[#Chemistry Tracers|Chemistry Tracers]]
|-
| <code>cart_mecca_xml</code>
| Switch for kpp chemistry
| <code>lart_mecca</code>
| .FALSE.
|[[Atmospheric Chemistry]]
|-
| <code>cart_pntSrc_xml</code>
| Enables creation of point sources emitting given Aerosols at a given rate
| <code>lart_pntSrc</code>
| .FALSE.
|[[#Point Source|Point Source]]
|-
| <code>cart_aerosol_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|[[#Aerosol Tracers|Aerosol Tracers]]
|-
| <code>cart_modes_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|[[#Aerosol Modes|Aerosol Modes]]
|-
| <code>cart_diagnostics_xml</code>
| Enables diagnostic output fields
| <code>lart_diag_out</code>
| .FALSE.
| -
|-
| <code>cart_emiss_xml_file</code>
| XML File for emission metadata
| -
| -
|[[#Aerosol Emission|Aerosol Emission]]
|-
| <code>cart_ext_data_xml</code>
| XML File for metadata of datasets prescribing tracers
| -
| -
| -
|-
| <code> cart_coag_xml </code>
| XML File containing additional information about coagulation
| -
| -
| -
|}

</div>

{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Tracers">Aerosol Tracers</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Modes">Aerosol Modes</span>
|-
! 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
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Emission">Aerosol Emission</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br \> routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Point Source">Point Source</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Chemistry Tracers">Chemistry Tracers</span>
|-
! 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
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br\> (*) in icon-kit/externals/art/runctrl_examples/xml_ctrl/
|}

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.
<syntaxhighlight lang=xml line>
<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>
</syntaxhighlight>

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.
<syntaxhighlight lang=xml line>
<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>
</syntaxhighlight>

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

== 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 [[#input-names|1.1]]. Please note that the XXX has to be replaced by one of the indices mentionend in Table [[#tab:input-init|input-init]] and [[#tab:input-emissions|input-emissions]].

[[File:input-names.png|800px|none|alt=ICON-ART input file naming convention.|ICON-ART input file naming convention.]]

<div id="tab:input-init">

{| class="wikitable" style="text-align:left;"
|+ Additional input files for the initialisation
! Species
! Namelist switch
! Options
! XXX
|-
| Gas
| <code>iart_init_gas</code>
| 0 (cold start), 5 (from file)
| IGX
|-
| Aerosol
| <code>iart_init_aero</code>
| 0 (cold start), 5 (from file)
| IAE
|}

</div>
<div id="tab:input-emissions">

=== 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]]

=== Emission Data ===
In every ICON-ART, there is the possibility to add additional input data like emission data that correspond with different sources. A quick overview about them can be found below.
{| class="wikitable" style="text-align:left;"
|+ 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
|}

==== Chemical Tracer ====
Emission data can be obtained from several sources. The following table should give an overview about which emission data are available for a corresponding tracer. To find out when to use which emission data type we recommend respective further reading.
{| class="wikitable"
! Tracer !! Emission Type !! Emission !! Resolution
|-
| C2H6 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || BBE || GFED || R2B04_ECHAM
|-
| || || GFED3 || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || BIO || MEGA || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| C3H8 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED || R2B04_ECHAM
|-
| || || GFED3 || R2B06_0024
|-
| || || || R2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || BIO || MEGA || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B07_nest
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| C5H8 || BBE || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CFCl3 || ANT || GEIA || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3CN || BBE || GFED.1s_Akagi_daily || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Akagi_monthly || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Stockwell_daily || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || GFED.1s_Stockwell_monthly || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3COCH3 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || || R3B07_0026
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GICC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GUESS-ES || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || RETRO || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MEGANv2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH3I || BIO || Bell || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ziska || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CH4 || ANT || EDGA || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || || R3B08_0049
|-
| || || EDGARv4.2 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || || EDGARv4.3.1 || R2B04_0012
|-
| || || || R2B05_0014
|-
| CHBr3 || BIO || Liang || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ordonez || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || Ziska || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CO || ANT || EDGAR || R2B04_ECHAM
|-
| || || EDGAR+ || R2B05_0014
|-
| || || EDGAR432-monthly || R2B05_0014
|-
| || || || R2B06_0024
|-
| || || || B2B06_EU_nest
|-
| || || || R2B07_nest
|-
| || || || R2B07_NSR_D_nest
|-
| || || || R3B07_0026
|-
| || || EDGARv4.2 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || POET || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GICC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || GUESS-ES || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || RETRO || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || BIO || MEGAN || R2B04_ECHAM
|-
| || || MEGAN-MACC || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MEGANv2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| CO2 || ANT || EDGARv4.2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0024
|-
| || || || R2B06_0031_nest
|-
| || || || R2B07_0018
|-
| || || || R2B07_nest
|-
| || || || R3B07_0022
|-
| || || || B3B07_0026
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| DMS || BBE || GFED3 || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MACCity || R2B04_0012
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| N2O || ANT || EDGARv4.2 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| || BBE || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_polstrNest
|-
| || || || R3B07_0022
|-
| NH3 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| || || MACCity_agriculture || R2B06_0016
|-
| || || MACCity_agric_waste || R2B06_0016
|-
| || || MACCity_energy || R2B06_0016
|-
| || || MACCity_industrial || R2B06_0016
|-
| || || MACCity_residential || R2B06_0016
|-
| || || MACCity_transport || R2B06_0016
|-
| SF6 || ANT || EDGARLevin || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|-
| SO2 || ANT || MACCity || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R2B07_nest
|-
| || || || R3B07_0022
|-
| || || GFED3 || R2B04_0012
|-
| || || || R2B04_ECHAM
|-
| || || || R2B05_0014
|-
| || || || R2B06_0016
|-
| || || || R2B07_0018
|-
| || || || R3B07_0022
|}

== 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<code> &art_nml </code> is <code> iart_init_aero=5 </code>

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 <code> &art_nml</code> is <code> iart_init_aero=0 </code>. 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 <code>init_latbc_from_fg = .FALSE. </code>in <code> &limarea_nml </code>. Additionally you have to add file in the tracer xml file.

------
[[#Aerosol Tracers]]

Input

2023-08-10T13:57:15Z

Tim R: /* Input Data */

MECCA-based (full) Chemistry

2023-08-10T13:09:48Z

Tim R: /* Preparing the MECCA-xml-file */

- work in progress -

In this configuration example a simulation with (full) MECCA-based chemistry is performed. If we talk about MECCA-based chemistry we mean a full gas phase chemistry that can be applied additionally to the existing standard parametrized chemistry from ICON-ART (explained in the article [[Atmospheric Chemistry]], example: [[Simplified Chemistry|click here]]). MECCA uses the Kinetic PreProcessor (KPP) to convert the chemical equations into differential equations that can be used then e.g., in ICON-ART. MECCA already contains a comprehensive chemical mech-
anism, but it also allows to create an own mechanism by changing equations or only picking a subset of equations.
To perform this example, a complete reaction mechanism is created and transferred to ICON-ART.

This article teaches you...
*the implementation of (full) MECCA-based chemistry in ICON-ART
*the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
*the implementation of not yet in MECCA implemented reactions in your mechanism
*the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART

== Introductioin ==
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

In this case we are going to have a look at the implementation of the fully available chemistry, meaning all in default mode available reactions will be implemented. This could also be adjusted easily if necessary and will be showed later. If we talk about "adding" MECCA chemistry to ICON-ART, it means that it is additionally calculated to the in any way calculated parametrized simplified chemistry in ICON-ART.

(Note: Adding MECCA-chemistry to ICON-ART also means that some namelist parameters will be overwritten in the runscript which means that some extra options (e.g. LINOZ-chemistry) are only available by setting them manually in the ICON-ART code.)

[In this configuration case a regular simulation with a MECCA chemistry implementation that will be applied in most cases is explained. The implementation and link to ICON-ART works with an xml-file that has to created with help of the [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip caaba3.0-supplement]. The created xml-file has to be included in the runscript as well. To get a better overview about the upcoming steps you can also check out the MECCA chemistry part in the [[Atmospheric Chemistry]] article.

== Preparing the MECCA-xml-file ==

=== Step 0: Download and open the caaba3.0-supplement ===
Once you have downloaded the [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip caaba3.0-supplement], you can open it in your preferred directory browser or terminal.

=== Step 1: Setting up the chemical mechanism ===
If you browse the <code>mecca</code> directory you can check out the <code>gas.eqn</code> file. Just use the text editor if you use the directory browser or use the command
vi gas.eqn
in the terminal. Once you have opened it, you can see all available reactions implemented in MECCA with their respective reaction codes which represents the full MECCA mechanism. In this configuration case we will implement a MECCA chemistry with all available reactions. That's why the <code>gas.eqn</code> can be left as it is.

==== What to do if not all reactions are wanted ====
First, never edit the <code>gas.eqn</code> itself! Better copy and rename it for your respective chemical mechanism that you want to create, e.g. <code>gas_Mechanism1.eqn</code>. Afterwards you can open it and delete all reactions that are not wanted (for Terminal users: to activate writing inside vi, use command <code>:w</code>, for closing and saving: <code>:wq</code>).

==== What to do if you want to edit existing reactions of the gas.eqn or add new reactions to your mechanism ====
If a reaction of the <code>gas.eqn</code> is only similar to that one that you want to implement or a specific reaction is not implemented in the <code>gas.eqn</code>, you can make use of replacement-files. Inside the <code>mecca</code> directory, select the <code>rpl</code> directory in which you can copy and rename the <code>example.rpl</code> first of all. If you open it (again with the text editor or with the <code>vi</code>-command you can edit and add your reactions, depending on your scientific goal.
If you want to edit a reaction, use the <code>#REPLACE</code> command as well as the number of the respective reaction (e.g. <G4110>) in the first line, then write <code><a></code> (<code><nowiki><b></nowiki></code>, <code><c></code>,...) for your first (second, third,...) reaction which belongs to the same reaction number. Below some examples are shown.
* <u>Editing one reaction:</u> Reaction <code>G4110</code> originally looks like this inside the <code>gas.eqn</code>:
<pre>
<G4110> CO + OH = H + CO2 : {%StTrG} (1.57E-13+cair*3.54E-33){§1.15}; {&1628}
</pre>

Inside the replacement file you can change it for example like this:
<pre>
#REPLACE <G4110>
<a> CO + OH = HO2 + CO2 : {%StTrG} 1.57E-13 + cair*3.54E-33 {&1628}
#ENDREPLACE
</pre>
* <u>Split one reaction into two (or more):</u> If you want to split a reaction into several subreactions (e.g. reaction <code>G4101</code>). Originally <code>G4110</code> looks like this inside the <code>gas.eqn</code>:
<G4101> CH4 + OH {+O2}= CH3O2 + H2O : {%StTrG} 1.85E-20{§1.2}*EXP(2.82*log(temp)-987./temp); {&1627}
The splitting can then be written as:
#REPLACE <G4101>
<a> CH4 + OH = CH3 + H2O : {%StTrG} 1.85E-20*EXP(2.82*log(temp)-987./temp); {&&1627}
<nowiki><b></nowiki> CH3 + O2 = CH3O2 : {%StTrG} 1E-999; {&&}
#ENDREPLACE
* <u>Adding new reaction:</u> If you want to add a new reaction, define a not yet existing reaction number and write your new reaction:
#REPLACE <>
<G9876JD> XYZ + OH = RO2 + H2O : {%StG} 1.57E-13; {&&}
#ENDREPLACE
Note:
* The added reaction only works for your specific project, it is not implemented in MECCA then and it can't be applied from the <code>gas.eqn</code> afterwards.
* if you try to edit a reaction with a not existing reaction number, an error message will be given

If you're finished, don't forget to save everything (for Terminal users: to activate writing inside vi, use command <code>:w</code>, for closing and saving: <code>:wq</code>)!

=== Step 2: Setting up the batch file ===
Inside the <code>mecca</code> directory of the supplement, check out the <code>example.bat</code> file in the <code>batch</code> directory. The batch file is some kind of runscript of the respective MECCA-mechanism to create the belonging Fortran Code and the ICON-Code afterwards. Copy and rename it according to your project. After opening it afterwards you will see the following code lines:
<div class="toccolours mw-collapsible mw-collapsed">
Example batch file (<code>example.bat</code>)
<pre class="mw-collapsible-content">
# -*- Shell-script -*-

# The shell variables defined here will be used by xmecca
# when it is run in batch mode (i.e. not interactive).

set apn = 2 # number of aerosol phases [0...99, default=0]
set gaseqnfile = gas.eqn
set rplfile = # no replacements
set wanted = "Tr && (G || (Aa && Mbl)) && \!I && \!Hg"
set mcfct = n # Monte-Carlo factor?
set diagtracfile = # diagnostic tracers?
set rxnrates = n # calculate accumulated reaction rates?
set tagdbl = n # tagging, doubling, both, none ??
set kppoption = k # k=kpp, 4=kp4, q=quit
set integr = rosenbrock_posdef # integrator
set vlen = 256 # only for kp4 and integr=rosenbrock_vec
set decomp = n # remove indirect indexing
# kp4: 0/1/2/3/q; kpp: y/n/q
set deltmpkp4 = y # delete temporary kp4 files
set latex = n # latex list of reactions
set graphviz = n # graphviz plots?
set deltmp = n # delete temporary xmecca files?
</pre>
</div>
The most parameters can be left as they are. Important is to rename the gas-equation-file and the replacement-file (if you have created one?).
Here is a list added with a short explanation of each parameter:
* <b>apn:</b>
* <b>gaseqnfile:</b>
* <b>rplfile:</b>
* <b>wanted:</b>
* <b>mcfct:</b>
* <b>diagtracfile:</b>
* <b>rxnrates:</b>
* <b>tagdbl:</b>
* <b>kppoption:</b>
* <b>integr:</b>
* <b>vlen:</b>
* <b>decomp:</b>
* <b>deltmpkp4:</b>
* <b>latex:</b>
* <b>graphviz:</b>
* <b>deltmp:</b>

If you're finished, don't forget to save everything (for Terminal users: to activate writing inside vi, use command <code>:w</code>, for closing and saving: <code>:wq</code>)!

=== Step 3: Execute the Mecca script ===
The first most important preparations are done now. Let's execute the <code>xmecca</code> script by typing
./xmecca
inside the <code>mecca</code> directory and follow the steps. Select your previously created batch file and run it. Now the Fortran files of the selected mechanism are created.

=== Step4: Transfer MECCA mechanism to ICON ===
Since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via
git clone https://gitlab.dkrz.de/art/mecca preproc.git
Now a new directory <code>Mecca_preproc</code> has been generated where the script <code>create_icon_code4.sh</code> can be found. By executing
./create_icon_code4.sh -h
the following view will be provided:
usage: ./create_icon_code4.sh [-m <mecca_home>] [-i <icon_home>] [-o <file_name>] [-h]
-m <mecca_home> : path to Mecca home directory, e.g. '~/caaba_3.0/mecca'
-i <icon_home> : path to icon home directory, e.g. '~/icon-kit/src/ICON-ART'
-o <file_name> : name of the XML file for ICON-ART, e.g. 'tracers_full.xml'
-h : display help

Here all paths to the Mecca- and ICON home directories have to be provided (type <code>pwd</code> in terminal to find out the path of your current directory) as well as a name for the XML-file that is going to be linked in the runscript later.

Now the Mecca-XML-file is generated and can be found in ICON in the directory <code>/icon home>/runctrl examples/xml ctrl</code>.

== Involving Mecca chemistry in a ICON-ART simulation ==
Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important before executing the simulation:''' As a final step, the ICON code has to be recompiled with the command
./config/dkrz/levante.intel --enable-art --enable-ecrad
and executed afterwards with the command
./make -j8

Afterwards the respective simulation can be executed, e.g. as explained in [[Lifetime Tracer Simulation]].
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.meccasim_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory you can check the slurm file for possible errors and run times after your job has been run through. In the output directory you can also find all output data for postprocessing in netCDF format.

Atmospheric Chemistry

2023-08-10T12:39:14Z

Tim R: /* Including MECCA-based Chemistry in a ICON-ART Simulation */

In this article it is described how to perform different kinds of atmospheric chemistry simulations. This includes the description of simulations with a simplified chemistry and MECCA-based (full) chemistry, their nameless settings, possible modules to make use of and information about initialization data.
Further, there are given some examples of typical simulation you can do with ICON-ART including atmospheric chemistry.

== Simplified Chemistry ==
When we talk about simplified calculated chemistry in ICON-ART, we mean that the concentration of the gases we want to simulate is calculated with a parametrization. Here production and depletion rates are used to solve the differential equation

<math>\frac{\mathrm{dc_i}}/{\mathrm{dt}} = P_i - \frac{c_i}/{\tau _i}</math>

{{math|1=''E'' = ''mc''{{sup|2}}}}

numerically and two calculate the concentration distribution. Here, <math>c_i</math> describes the number concentration of a certain tracer, <math>c_i</math> describes the chemical production and <math>\tau_i</math>is the belonging life time of tracer <math>i</math>.
For the namelist settings you are able to use for atmospheric chemistry, check out the ART-namelist parameters (see [[Namelist|ART namelists]]). The procedure of creating an ICON-ART simulation in Atmospheric Chemistry always comes back to switching on a namelist parameter and providing the path of the respective XML-file. How to create these for several cases, please check the examples below in the [[Atmospheric Chemistry|Configurations]] part.

To learn more about technical details of simplified chemistry, see also [https://gmd.copernicus.org/articles/10/2471/2017/ Weimer et. al. (2017)].

Note: When enabling simplified chemistry with the switch <code>lart_chemtracer = .TRUE.</code>, you can improve your runtime but the simulated concentration values are less exact compared to MECCA-based chemistry.

== MECCA-based Chemistry ==

=== General Information ===
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

=== Including MECCA-based Chemistry in a ICON-ART Simulation ===
(Note: It is recommended to perform all the following steps in the shell environment.)

The above mentioned collection of the gase phase chemistry reactions can be found in the supplement in the <code>gas.eqn</code> (path: caaba3.0/Mecca/gas.eqn).
Additionally it is also possible to edit existing reactions as well as creating new reactions with the help of "Replacement-files" (see an example in the [[Atmospheric Chemistry|Configurations]] part). Inside the <code>gas.eqn</code> every reaction is marked with a certain code. To select the specific reactions for the machanism labels can be set to your belonging reactions or, more easily, a new Gas-Equation-file <code>gas_Mechanism1.eqn</code> can be created, containing only the wanted reactions. (Note: Never edit the original <code>gas.eqn</code>! Better copy it in the first place and then rename and edit it, depending on the respective scientific goal.)
After that the following steps have to be fulfilled to create the code of your specific mechanism and to be able to execute an ICON-ART simulation with MECCA-based chemistry:
* set up a batch file: all previously set information about the mechanism can be selected and stated here (an example can be found below or also inside the supplement in <code>/caaba3.0/mecca/batch/example.bat</code>).
* execute <code>./xmecca</code> inside the folder <code>/caaba3.0/mecca</code>. Here the previously created batch file has to be selected and the Fortran files with the mechanism are created.
* since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via <code>git clone https://gitlab.dkrz.de/art/mecca preproc.git</code>.
* in a new directory <code>Mecca_preproc</code> has been generated and the script <code>create_icon_code4.sh</code> can be found inside of it. By executing <code>./create_icon_code4.sh -h</code> paths to the Mecca- and ICON home directories can be provided as well as a name for the XML-file that is going to be linked in the unscript later.
* the Mecca-XML-file is now generated and can be found in ICON in <code>/icon home>/runctrl examples/xml ctrl</code>.

Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important:''' As a final step, the ICON code has to be recompiled with the command <code>./config/dkrz/levante.intel --enable-art --enable-ecrad</code> and executed afterwards with <code>make -j 8</code>.

MECCA-based (full) Chemistry

2023-08-10T12:10:31Z

Tim R: Replacement files

MECCA-based (full) Chemistry

2023-08-10T11:39:36Z

Tim R:

Atmospheric Chemistry

2023-08-10T10:36:05Z

Tim R: /* Including MECCA-based Chemistry in a ICON-ART Simulation */

MECCA-based (full) Chemistry

2023-08-10T10:34:15Z

Tim R: adding the introduction

Stratospheric Ozone Chemistry and Polar Stratospheric Clouds

2023-07-26T14:11:10Z

Tim R: Creating chapter for xml-file and running the simulation

- under construction! -

In this example a simulation with only stratospheric (simplified) ozone chemistry is performed, also polar stratospheric clouds are taken into account. The tutorial teaches you...
* the implementation of stratospheric specific chemistry (here on thee example of ozone)
* applying linearized ozone chemistry (LINOZ) in a simulation
* the implementation of polar stratospheric clouds (PSCs)
No emission data will be included in this simulation.

== Configuration case ==
=== Stratospheric ozone with linearized ozone chemistry (LINOZ) ===
On the one hand the depicted case is dealing with simulating stratospheric ozone which is calculated with a linearized ozone chemistry (LINOZ). Here a linearized version of the differential equation for production or depletion like <math>\frac{\mathrm{d}c_i}{\mathrm{d}t}=P_i-\frac{c_i}{\tau _i}</math> is used. After calculating the Taylor expansion of first order the computed ozone concentrations are then anomalies from temperature and ozone column climatologies. This LINOZ chemistry is applied in heights of 10km and higher. Below that height the lifetime of ozone is set to constant 28 days so a constant climatology is applied. Without including LINOZ at this point, a complete ozone chemistry must be included in the simulation what would result in higher computational effort.
=== Polar Stratospheric Clouds (PSCs) ===
Further, the simulation of polar stratospheric clouds (PSC), are also considered. Polar stratospheric clouds are forming under very cold conditions in the antarctic region during the south hemispheric winter. These cold conditions are reached due to the underlying orographic conditions in Antarctica and a resulting very strong and stable polar vortex. In May or June the temperature is normally low enough to form polar stratospheric clouds. Then the reaction

<chem>ClNO3 + HCl -> Cl2 + HNO3</chem>

is effektively producing high <chem>HNO3</chem> concentrations in the stratosphere resulting in a formation of <chem>HNO3*H20</chem> phases, identifying as polar stratospheric clouds. The educts are existing due to the regular <chem>ClOx</chem> family reactions (see e.g. [https://onlinelibrary.wiley.com/doi/10.1002/ciuz.200700418#pane-pcw-references Dameris et al., 2007]). Later ion the year, when more light reaches Antarctica, the <chem>Cl2</chem> product can then be photolysed and finally, due to the <chem>ClOx</chem> cycle, Ozone can be depleted:

<chem>Cl2 + hv -> 2Cl</chem>

<chem>Cl + O3 -> ClO + O2</chem>

That's also why the ozone hole has formed: The more chlorofluorocarbons are emitted, the more <chem>ClNO3</chem> as well as <chem>HCl</chem> are produced and the more ozone can be depleted.
In this simulation, PSCs are considered to calculate the stratospheric ozone concentration but not to simulate the clouds itself.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.strat_ozone_linoz_psc.run</code> but of course you can call it differently as well. The runscript can be stored under the following path in your icon directory: <code>/icon-kit/run</code>

If you've already walked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check in part 1 that all your paths to your directories are correct, probably they have to be adjusted. Note that "hp8526" is a name of a specific account here, make sure to double check especially these lines. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>.True.</code>.
<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-strat_ozone_linoz_psc
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we simulate one week (01 October 2012 until 07 October 2012). To really catch all day times and so the time dependent solar radiation, the output interval is set to 10 hours to calculate <chem>O3</chem> to every time of the day. Because of the Photolysis dependency of <chem>O3</chem> this is particularly important.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-08T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-08T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

Since we make use of LINOZ, in the radiation namelist section <code>&radiation_nml</code> the namelist parameter <code>irad_o3</code> has to be set to 10:

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> has to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation, which is only <chem>O3</chem> in this case. How to create this xml-file is explained in the next chapter. Since PSCs shall be considered, the <code>lart_psc</code> switch has to be set to <code>.TRUE.</code>. Please also note the extra information that have to be given for <chem>O3</chem> in the xml-file that PSCs are considered correctly (see next chapter).
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
lart_psc = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-strat_ozone_linoz_psc
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-08T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-08T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
lart_psc = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_ozone_psc.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties, that are relevant for the simulation, are listed here. Since we perform a simulation with simplified and linearized ozone chemistry, we need the matching chemtracer-xml-file where only <chem>O3</chem> is mentioned. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case only <chem>O3</chem> (in xml-file: <code>TRO3</code>) we copy the needed code lines into our new xml-file <code>chemtracer_ozone_psc.xml</code> needed for the simulation. Additionally we add the three namelist parameter <code>polarchem</code>, <code>Thet</code> and <code>lt_het</code> as noted below. Also double check that the <code>c_solve</code> parameter is set to <code>linoz</code> to really mark that this Ozone tracer has to be computed with LINOZ chemistry and that the <code>transport</code> parameter is not set to <code>stdaero</code> but to <code>hadv52aero</code> which improves the accuracy in several cases.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for stratospheric ozone simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">hadv52aero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
<polarchem type="char">on</polarchem>
<Thet type="real">195</Thet>
<lt_het type="real">864000</lt_het>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.strat_ozone_linoz_psc.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Stratospheric Ozone Chemistry and Polar Stratospheric Clouds

2023-07-26T13:38:24Z

Tim R: Creating chapter "Setting up the runscript"

Lifetime Tracer Simulation

2023-07-26T13:18:42Z

Tim R: /* Setting up the Runscript */

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the setup of the runscript
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables
No emission data will be included in this simulation.

== Configuration case ==
The depicted case is dealing with biogenic very short-lived species (VSLS) with a very short lifetime, more accurately Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>). Like of most VSLSs the major source of <chem>CHBr3</chem> and <chem>CH2Br2</chem> is the ocean which leads too a large gradient with increasing height in the concentration of these tracers. Bromoform is mainly depleted by photolysis in the Troposphere whereas Dibromomethanes main loss is due to Hydroxylradicals (OH). To assess the ability to simulate the transport of VSLS from the surface to the lower stratosphere, this case study uses an idealized chemical tracer approach.

The simulation is modeling the 01 October 2012 and is initialized with data from the ECMWF Integrated Forecast System (IFS) and includes boundary conditions and chemical lifetimes from the WMO Ozone assessment 2010. The boundary conditions and the chemical lifetimes are recalculated in a sort of rate at which the substances are depleted from the atmosphere with help of the implicit solution of the balance equation:
<math>\frac{\partial(\bar{\rho)\hat{\Psi_{l}}/{\partial t} = -\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})- \nabla\cdot\bar{(\rho v''\Psi_{g,l}''}+P_l-L_l+E_l</math>

Here <math>\rho</math> is the density of air, <math>\hat{\Psi_{l}}</math> the barycentric-averaged mass mixing ratio, <math>\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})</math> indicates the flux divergence that includes the horizontal and vertical advection of the gaseous compound l and <math>\nabla\cdot\bar{(\rho v''\Psi_{l}'')}</math> indicates the change due to turbulent fluxes. Further <math>P_l</math> describes the production rate due to chemical reactions, <math>L_l</math> the respective loss rate and emissions are noted with <math>E_l</math>. Everything is related to the respective compound l.

In this example no emission data is used.

== Setting up the Runscript ==

Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.lifetime_tracer_test.run</code> but of course you can call it differently as well. The runscript can be stored under the following path in your icon directory: <code>/icon-kit/run</code>

If you've already walked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check in part 1 that all your paths to your directories are correct, probably they have to be adjusted. Note that "hp8526" is a name of a specific account here, make sure to double check especially these lines. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>.True.</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate one day (01 October 2012). To calculate <chem>CHBr3</chem> and <chem>CH2Br2</chem> to every time of the day the output interval is set to 1 hour.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation in general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> has to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our case study we're done for the ART setting at this point.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.

<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry of lifetime dependent tracers we need the matching chemtracer-xml-file where only these tracers have to mentioned. Then, the concentrations will be calculated according to their lifetimes with no relation to other tracers. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case <chem>CHBr3</chem> (in xml-file: <code>TRCHBr3</code>) and <chem>CH2Br2</chem> (in xml-file: <code>TRCH2Br2</code>)) we copy the needed code lines into our new xml-file <code>chemtracer_lifetime_chbr3_ch2br2.xml</code> needed for the simulation.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for lifetime tracer simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.lifetime_tracer_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Lifetime Tracer Simulation

2023-07-26T13:10:40Z

Tim R: Small improvements in and corrections in several parts

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the setup of the runscript
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables
No emission data will be included in this simulation.

== Configuration case ==
The depicted case is dealing with biogenic very short-lived species (VSLS) with a very short lifetime, more accurately Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>). Like of most VSLSs the major source of <chem>CHBr3</chem> and <chem>CH2Br2</chem> is the ocean which leads too a large gradient with increasing height in the concentration of these tracers. Bromoform is mainly depleted by photolysis in the Troposphere whereas Dibromomethanes main loss is due to Hydroxylradicals (OH). To assess the ability to simulate the transport of VSLS from the surface to the lower stratosphere, this case study uses an idealized chemical tracer approach.

The simulation is modeling the 01 October 2012 and is initialized with data from the ECMWF Integrated Forecast System (IFS) and includes boundary conditions and chemical lifetimes from the WMO Ozone assessment 2010. The boundary conditions and the chemical lifetimes are recalculated in a sort of rate at which the substances are depleted from the atmosphere with help of the implicit solution of the balance equation:
<math>\frac{\partial(\bar{\rho)\hat{\Psi_{l}}/{\partial t} = -\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})- \nabla\cdot\bar{(\rho v''\Psi_{g,l}''}+P_l-L_l+E_l</math>

Here <math>\rho</math> is the density of air, <math>\hat{\Psi_{l}}</math> the barycentric-averaged mass mixing ratio, <math>\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})</math> indicates the flux divergence that includes the horizontal and vertical advection of the gaseous compound l and <math>\nabla\cdot\bar{(\rho v''\Psi_{l}'')}</math> indicates the change due to turbulent fluxes. Further <math>P_l</math> describes the production rate due to chemical reactions, <math>L_l</math> the respective loss rate and emissions are noted with <math>E_l</math>. Everything is related to the respective compound l.

In this example no emission data is used.

== Setting up the Runscript ==

Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.lifetime_tracer_test.run</code> but of course you can call it differently as well. The runscript can be stored under the following path in your icon directory: <code>/icon-kit/run</code>

If you've already walked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check in part 1 that all your paths to your directories are correct, probably they have to be adjusted. Note that "hp8526" is a name of a specific account here, make sure to double check especially these lines. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>.True.</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate one day (01 October 2012). To calculate <chem>CHBr3</chem> and <chem>CH2Br2</chem> to every time of the day the output interval is set to 1 hour.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation in general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our case study we're done for the ART setting at this point.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.

<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry of lifetime dependent tracers we need the matching chemtracer-xml-file where only these tracers have to mentioned. Then, the concentrations will be calculated according to their lifetimes with no relation to other tracers. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case <chem>CHBr3</chem> (in xml-file: <code>TRCHBr3</code>) and <chem>CH2Br2</chem> (in xml-file: <code>TRCH2Br2</code>)) we copy the needed code lines into our new xml-file <code>chemtracer_lifetime_chbr3_ch2br2.xml</code> needed for the simulation.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for lifetime tracer simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.lifetime_tracer_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Simplified Chemistry

2023-07-26T13:06:20Z

Tim R: Small improvements and corrections

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.ohsim_simple_icon.run</code> but of course you can call it differently as well. The runscript can be stored under the following path in your icon directory: <code>/icon-kit/run</code>

Inside of that, first check in part 1 that all your paths to your directories are correct, probably they have to be adjusted. Note that "hp8526" is a name of a specific account here, make sure to double check especially these lines. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>.True.</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

Since we make use of LINOZ, in the radiation namelist section <code>&radiation_nml</code> the namelist parameter <code>irad_o3</code> has to be set to 10:

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> hadv52aero </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> hadv52aero </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Simplified Chemistry

2023-07-26T12:39:32Z

Tim R: /* Setting up the Runscript */

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>.True.</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> hadv52aero </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> hadv52aero </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Stratospheric Ozone Chemistry and Polar Stratospheric Clouds

2023-07-26T12:24:10Z

Tim R: Adding explanation to the configuration case

Lifetime Tracer Simulation

2023-07-26T11:20:43Z

Tim R:

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the setup of the runscript
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables
No emission data will be included in this simulation.

== Configuration case ==
The depicted case is dealing with biogenic very short-lived species (VSLS) with a very short lifetime, more accurately Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>). Like of most VSLSs the major source of <chem>CHBr3</chem> and <chem>CH2Br2</chem> is the ocean which leads too a large gradient with increasing height in the concentration of these tracers. Bromoform is mainly depleted by photolysis in the Troposphere whereas Dibromomethanes main loss is due to Hydroxylradicals (OH). To assess the ability to simulate the transport of VSLS from the surface to the lower stratosphere, this case study uses an idealized chemical tracer approach.

The simulation is modeling the 01 October 2012 and is initialized with data from the ECMWF Integrated Forecast System (IFS) and includes boundary conditions and chemical lifetimes from the WMO Ozone assessment 2010. The boundary conditions and the chemical lifetimes are recalculated in a sort of rate at which the substances are depleted from the atmosphere with help of the implicit solution of the balance equation:
<math>\frac{\partial(\bar{\rho)\hat{\Psi_{l}}/{\partial t} = -\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})- \nabla\cdot\bar{(\rho v''\Psi_{g,l}''}+P_l-L_l+E_l</math>

Here <math>\rho</math> is the density of air, <math>\hat{\Psi_{l}}</math> the barycentric-averaged mass mixing ratio, <math>\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})</math> indicates the flux divergence that includes the horizontal and vertical advection of the gaseous compound l and <math>\nabla\cdot\bar{(\rho v''\Psi_{l}'')}</math> indicates the change due to turbulent fluxes. Further <math>P_l</math> describes the production rate due to chemical reactions, <math>L_l</math> the respective loss rate and emissions are noted with <math>E_l</math>. Everything is related to the respective compound l.

In this example no emission data is used.

== Setting up the Runscript ==

Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.lifetime_tracer_test.run</code> but of course you can call it differently as well.

If you've also worked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate one day (01 October 2012). To really catch all day times and so the time dependent solar radiation, the output interval is set to 1 hours to calculate <chem>CHBr3</chem> and <chem>CH2Br2</chem> to every time of the day. Because of the Photolysis dependency of <chem>CHBr3</chem> this is particularly important.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our case study we're done for the ART setting at this point.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.

<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry of lifetime dependent tracers we need the matching chemtracer-xml-file where only these tracers have to mentioned. Then, the concentrations will be calculated according to their lifetimes with no relation to other tracers. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case <chem>CHBr3</chem> (in xml-file: <code>TRCHBr3</code>) and <chem>CH2Br2</chem> (in xml-file: <code>TRCH2Br2</code>)) we copy the needed code lines into our new xml-file <code>chemtracer_lifetime_chbr3_ch2br2.xml</code> needed for the simulation.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for lifetime tracer simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.lifetime_tracer_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Lifetime Tracer Simulation

2023-07-26T11:20:01Z

Tim R:

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the setup of the runscript
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables

== Configuration case ==
The depicted case is dealing with biogenic very short-lived species (VSLS) with a very short lifetime, more accurately Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>). Like of most VSLSs the major source of <chem>CHBr3</chem> and <chem>CH2Br2</chem> is the ocean which leads too a large gradient with increasing height in the concentration of these tracers. Bromoform is mainly depleted by photolysis in the Troposphere whereas Dibromomethanes main loss is due to Hydroxylradicals (OH). To assess the ability to simulate the transport of VSLS from the surface to the lower stratosphere, this case study uses an idealized chemical tracer approach.

The simulation is modeling the 01 October 2012 and is initialized with data from the ECMWF Integrated Forecast System (IFS) and includes boundary conditions and chemical lifetimes from the WMO Ozone assessment 2010. The boundary conditions and the chemical lifetimes are recalculated in a sort of rate at which the substances are depleted from the atmosphere with help of the implicit solution of the balance equation:
<math>\frac{\partial(\bar{\rho)\hat{\Psi_{l}}/{\partial t} = -\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})- \nabla\cdot\bar{(\rho v''\Psi_{g,l}''}+P_l-L_l+E_l</math>

Here <math>\rho</math> is the density of air, <math>\hat{\Psi_{l}}</math> the barycentric-averaged mass mixing ratio, <math>\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})</math> indicates the flux divergence that includes the horizontal and vertical advection of the gaseous compound l and <math>\nabla\cdot\bar{(\rho v''\Psi_{l}'')}</math> indicates the change due to turbulent fluxes. Further <math>P_l</math> describes the production rate due to chemical reactions, <math>L_l</math> the respective loss rate and emissions are noted with <math>E_l</math>. Everything is related to the respective compound l.

In this example no emission data is used.

== Setting up the Runscript ==

Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.lifetime_tracer_test.run</code> but of course you can call it differently as well.

If you've also worked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate one day (01 October 2012). To really catch all day times and so the time dependent solar radiation, the output interval is set to 1 hours to calculate <chem>CHBr3</chem> and <chem>CH2Br2</chem> to every time of the day. Because of the Photolysis dependency of <chem>CHBr3</chem> this is particularly important.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our case study we're done for the ART setting at this point.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.

<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry of lifetime dependent tracers we need the matching chemtracer-xml-file where only these tracers have to mentioned. Then, the concentrations will be calculated according to their lifetimes with no relation to other tracers. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case <chem>CHBr3</chem> (in xml-file: <code>TRCHBr3</code>) and <chem>CH2Br2</chem> (in xml-file: <code>TRCH2Br2</code>)) we copy the needed code lines into our new xml-file <code>chemtracer_lifetime_chbr3_ch2br2.xml</code> needed for the simulation.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for lifetime tracer simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.lifetime_tracer_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Tutorial Examples

2023-07-20T14:54:39Z

Tim R: Restructuring: In the Tutorial Examples - Overview you can be forwarded to modeling examples AND post processing examples now

- under construction! -

In this article several examples from different topics and application areas in ICON-ART are presented, concerning the setup of a simulation as well as post processing and plotting. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of Simulation topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds]] ====
* here a simulation with only stratospheric (simplified) ozone chemistry is performed, also polar stratospheric clouds are taken into account
* this example teaches you...
** the implementation of stratospheric specific chemistry (here on thee example of ozone)
** applying linearized ozone chemistry (LINOZ) in a simulation
** the implementation of polar stratospheric clouds (PSCs)
* click [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds|here]] to see more details

==== [[Lifetime Tracer Simulation]] ====
* here it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. Here the very short-lived substances Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>) are simulated.
* this example teaches you...
** the correct setup of the xml-file for such tracers.
** the structure and correct usage of namelist parameter settings of lifetime tracers in xml-files
** editing output variables
* click [[Lifetime Tracer Simulation|here]] to see more details

---------

=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

== Overview of Post processing examples ==

=== Chemical tracer distributions ===

=== Aerosol Point Sources ===

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Atmospheric Chemistry

2023-07-20T14:44:25Z

Tim R: improvements on explaining simplifying chemistry

In this article it is described how to perform different kinds of atmospheric chemistry simulations. This includes the description of simulations with a simplified chemistry and MECCA-based (full) chemistry, their nameless settings, possible modules to make use of and information about initialization data.
Further, there are given some examples of typical simulation you can do with ICON-ART including atmospheric chemistry.

== Simplified Chemistry ==
When we talk about simplified calculated chemistry in ICON-ART, we mean that the concentration of the gases we want to simulate is calculated with a parametrization. Here production and depletion rates are used to solve the differential equation

<math>\frac{\mathrm{dc_i}}/{\mathrm{dt}} = P_i - \frac{c_i}/{\tau _i}</math>

{{math|1=''E'' = ''mc''{{sup|2}}}}

numerically and two calculate the concentration distribution. Here, <math>c_i</math> describes the number concentration of a certain tracer, <math>c_i</math> describes the chemical production and <math>\tau_i</math>is the belonging life time of tracer <math>i</math>.
For the namelist settings you are able to use for atmospheric chemistry, check out the ART-namelist parameters (see [[Namelist|ART namelists]]). The procedure of creating an ICON-ART simulation in Atmospheric Chemistry always comes back to switching on a namelist parameter and providing the path of the respective XML-file. How to create these for several cases, please check the examples below in the [[Atmospheric Chemistry|Configurations]] part.

To learn more about technical details of simplified chemistry, see also [https://gmd.copernicus.org/articles/10/2471/2017/ Weimer et. al. (2017)].

Note: When enabling simplified chemistry with the switch <code>lart_chemtracer = .TRUE.</code>, you can improve your runtime but the simulated concentration values are less exact compared to MECCA-based chemistry.

== MECCA-based Chemistry ==

=== General Information ===
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

=== Including MECCA-based Chemistry in a ICON-ART Simulation ===
(Note: It is recommended to perform all the following steps in the shell environment.)

The above mentioned collection of the gase phase chemistry reactions can be found in the supplement in the <code>gas.eqn</code> (path: caaba3.0/Mecca/gas.eqn).
Additionally it is also possible to edit existing reactions as well as creating new reactions with the help of "Replacement-files" (see an example in the [[Atmospheric Chemistry|Configurations]] part). Inside the <code>gas.eqn</code> every reaction is marked with a certain code. To select the specific reactions for the machanism labels can be set to your belonging reactions or, more easily, a new Gas-Equation-file <code>gas_Mechanism1.eqn</code> can be created, containing only the wanted reactions. (Note: Never edit the original <code>gas.eqn</code>! Better copy it in the first place and then rename and edit it, depending on the respective scientific goal.)
After that the following steps have to be fulfilled to create the code of your specific mechanism and to be able to execute an ICON-ART simulation with MECCA-based chemistry:
* set up a batch file: all previously set information about the mechanism can be selected and stated here (an example can be found below or also inside the supplement in <code>/caaba3.0/mecca/batch/example.bat</code>).
* execute <code>./mecca</code> inside the folder <code>/caaba3.0/mecca</code>. Here the previously created batch file has to be selected and the Fortran files with the mechanism are created.
* since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via <code>git clone https://gitlab.dkrz.de/art/mecca preproc.git</code>.
* in a new directory <code>Mecca_preproc</code> has been generated and the script <code>create_icon_code4.sh</code> can be found inside of it. By executing <code>./create_icon_code4.sh -h</code> paths to the Mecca- and ICON home directories can be provided as well as a name for the XML-file that is going to be linked in the unscript later.
* the Mecca-XML-file is now generated and can be found in ICON in <code>/icon home>/runctrl examples/xml ctrl</code>.

Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important:''' As a final step, the ICON code has to be recompiled with the command <code>./config/dkrz/levante.intel --enable-art --enable-ecrad</code> and after executed <code>make -j 8</code>.

Atmospheric Chemistry

2023-07-20T14:41:44Z

Tim R: /* Including MECCA-based Chemistry in a ICON-ART Simulation */

In this article it is described how to perform different kinds of atmospheric chemistry simulations. This includes the description of simulations with a simplified chemistry and MECCA-based (full) chemistry, their nameless settings, possible modules to make use of and information about initialization data.
Further, there are given some examples of typical simulation you can do with ICON-ART including atmospheric chemistry.

== Simplified Chemistry ==
When we talk about simplified calculated chemistry in ICON-ART, we mean that the concentration of the gases we want to simulate is calculated with a parametrization. Here production and depletion rates are calculated to solve the differential equation

<math>\frac{\mathrm{dc_i}}/{\mathrm{dt}} = P_i - \frac{c_i}/{\tau _i}</math>

{{math|1=''E'' = ''mc''{{sup|2}}}}

numerically. Here, <math>c_i</math> describes the number concentration of a certain tracer, <math>c_i</math> describes the chemical production and <math>\tau_i</math>is the belonging life time of tracer <math>i</math>.
For the namelist settings you are able to use for atmospheric chemistry, check out the ART-namelist parameters (see [[Namelist|ART namelists]]). The procedure of creating an ICON-ART simulation in Atmospheric Chemistry always comes back to switching on a namelist parameter and providing the path of the respective XML-file. How to create these for several cases, please check the examples below in the [[Atmospheric Chemistry|Configurations]] part.

To learn more about technical details of simplified chemistry, see also [https://gmd.copernicus.org/articles/10/2471/2017/ Weimer et. al. (2017)].

Note: When enabling simplified chemistry with the switch <code>lart_chemtracer = .TRUE.</code>, you can improve your runtime but the simulated concentration values are less exact compared to MECCA-based chemistry.

== MECCA-based Chemistry ==

=== General Information ===
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

=== Including MECCA-based Chemistry in a ICON-ART Simulation ===
(Note: It is recommended to perform all the following steps in the shell environment.)

The above mentioned collection of the gase phase chemistry reactions can be found in the supplement in the <code>gas.eqn</code> (path: caaba3.0/Mecca/gas.eqn).
Additionally it is also possible to edit existing reactions as well as creating new reactions with the help of "Replacement-files" (see an example in the [[Atmospheric Chemistry|Configurations]] part). Inside the <code>gas.eqn</code> every reaction is marked with a certain code. To select the specific reactions for the machanism labels can be set to your belonging reactions or, more easily, a new Gas-Equation-file <code>gas_Mechanism1.eqn</code> can be created, containing only the wanted reactions. (Note: Never edit the original <code>gas.eqn</code>! Better copy it in the first place and then rename and edit it, depending on the respective scientific goal.)
After that the following steps have to be fulfilled to create the code of your specific mechanism and to be able to execute an ICON-ART simulation with MECCA-based chemistry:
* set up a batch file: all previously set information about the mechanism can be selected and stated here (an example can be found below or also inside the supplement in <code>/caaba3.0/mecca/batch/example.bat</code>).
* execute <code>./mecca</code> inside the folder <code>/caaba3.0/mecca</code>. Here the previously created batch file has to be selected and the Fortran files with the mechanism are created.
* since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via <code>git clone https://gitlab.dkrz.de/art/mecca preproc.git</code>.
* in a new directory <code>Mecca_preproc</code> has been generated and the script <code>create_icon_code4.sh</code> can be found inside of it. By executing <code>./create_icon_code4.sh -h</code> paths to the Mecca- and ICON home directories can be provided as well as a name for the XML-file that is going to be linked in the unscript later.
* the Mecca-XML-file is now generated and can be found in ICON in <code>/icon home>/runctrl examples/xml ctrl</code>.

Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important:''' As a final step, the ICON code has to be recompiled with the command <code>./config/dkrz/levante.intel --enable-art --enable-ecrad</code> and after executed <code>make -j 8</code>.

Simplified Chemistry

2023-07-20T14:36:55Z

Tim R: Changing transport namelist from "stdchem" to "hadv52aero"

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> hadv52aero </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> hadv52aero </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> hadv52aero </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Lifetime Tracer Simulation

2023-07-20T14:20:15Z

Tim R: Chapter xml-files and running the simulation created

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the setup of the runscript
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables

== Configuration case ==
The depicted case is dealing with biogenic very short-lived species (VSLS) with a very short lifetime, more accurately Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>). Like of most VSLSs the major source of <chem>CHBr3</chem> and <chem>CH2Br2</chem> is the ocean which leads too a large gradient with increasing height in the concentration of these tracers. Bromoform is mainly depleted by photolysis in the Troposphere whereas Dibromomethanes main loss is due to Hydroxylradicals (OH). To assess the ability to simulate the transport of VSLS from the surface to the lower stratosphere, this case study uses an idealized chemical tracer approach.

The simulation is modeling the 01 October 2012 and is initialized with data from the ECMWF Integrated Forecast System (IFS) and includes boundary conditions and chemical lifetimes from the WMO Ozone assessment 2010. The boundary conditions and the chemical lifetimes are recalculated in a sort of rate at which the substances are depleted from the atmosphere with help of the implicit solution of the balance equation:
<math>\frac{\partial(\bar{\rho)\hat{\Psi_{l}}/{\partial t} = -\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})- \nabla\cdot\bar{(\rho v''\Psi_{g,l}''}+P_l-L_l+E_l</math>

Here <math>\rho</math> is the density of air, <math>\hat{\Psi_{l}}</math> the barycentric-averaged mass mixing ratio, <math>\nabla\cdot (\hat{v}\bar{\rho}\hat{\Psi_{l}})</math> indicates the flux divergence that includes the horizontal and vertical advection of the gaseous compound l and <math>\nabla\cdot\bar{(\rho v''\Psi_{l}'')}</math> indicates the change due to turbulent fluxes. Further <math>P_l</math> describes the production rate due to chemical reactions, <math>L_l</math> the respective loss rate and emissions are noted with <math>E_l</math>. Everything is related to the respective compound l.

In this example no emission data is used.

== Setting up the Runscript ==

Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.lifetime_tracer_test.run</code> but of course you can call it differently as well.

If you've also worked through the example of the [[Simplified Chemistry]], you can use nearly the same runscript. Note that you have to change the paths from Part 1, the timing settings from Part 2, the output variables from Part 3, the emission settings as well as the path of the chemtracer-xml-file in the ART-settings from Part 4 and finally the timing in the job settings from Part 5. Details can be found below.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate one day (01 October 2012). To really catch all day times and so the time dependent solar radiation, the output interval is set to 1 hours to calculate <chem>CHBr3</chem> and <chem>CH2Br2</chem> to every time of the day. Because of the Photolysis dependency of <chem>CHBr3</chem> this is particularly important.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently. For a detailed description, check out the ICON Documentation ([https://code.mpimet.mpg.de/attachments/download/19568/ICON_tutorial_2019.pdf Drill et. al. (2019)]).

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our case study we're done for the ART setting at this point.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.

<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=liftime_tracer_test
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2012-10-01T00:00:00Z"}
end_date=${end_date:="2012-10-02T00:00:00Z"}
output_start=${start_date:="2012-10-01T00:00:00Z"}
output_end=${end_date:="2012-10-02T00:00:00Z"}
output_interval="PT1H"
modelTimeStep="PT6M"
leadtime="P8H"
checkpoint_interval="P30D"

# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/

&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_lifetime_test.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=2
#SBATCH --time=06:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-file ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry of lifetime dependent tracers we need the matching chemtracer-xml-file where only these tracers have to mentioned. Then, the concentrations will be calculated according to their lifetimes with no relation to other tracers. Because of no specific other settings (e.g. emissions), this is the only xml-file needed here.

To prepare the xml-file we can select the matching species from the general previously generated xml-file <code>standard_chemtracer.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Standard Chemtracer-xml-file for simulations without emission data
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2014 ?>
<lifetime type="real">286977600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO;2.*TRH2O</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.736*TRCH3COCH3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRH2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.802E-2</mol_weight>
<?source_lifetime Just a placeholder (not used in the code) ?>
<lifetime type="real">2592000000</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">H2O</init_name>
</chemtracer>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRNO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NH3</init_name>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRHNO3</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">NO2</init_name>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">HNO3</init_name>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRH2SO4</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">SO2</init_name>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">TRSO2</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">OCS</init_name>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>

<c_solve type="char">lt</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">DMS</init_name>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<dataset01 type="char" cvar_name="H2SO4" rbottom_height="10000" rupper_height="40000">CCMI-ETH_MPIC1.1</dataset01>
</chemtracer>
<chemtracer id="TRHCL" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">3.60E-2</mol_weight>
<lifetime type="real">259200</lifetime>

<c_solve type="char">param</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TR_cold">
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<lifetime type="real">432000</lifetime>

<c_solve type="char">cold</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1576800</lifetime>

<c_solve type="char">linoz</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">O3</init_name>
</chemtracer>
<chemtracer id="TRN2O" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
<init_mode type="int">0</init_mode>
<init_name type="char">N2O</init_name>
</chemtracer>
<chemtracer id="TRNOy" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">6.301E-1</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">259200</lifetime>

<c_solve type="char">simnoy</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRAGE" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">none</unit>
<mol_weight type="real">1.000E+0</mol_weight>
<?source_lifetime Just a placeholder, not used in the code?>
<lifetime type="real">25920000</lifetime>

<c_solve type="char">passive</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

After identifying the needed chemtracers (in our case <chem>CHBr3</chem> (in xml-file: <code>TRCHBr3</code>) and <chem>CH2Br2</chem> (in xml-file: <code>TRCH2Br2</code>)) we copy the needed code lines into our new xml-file <code>chemtracer_lifetime_chbr3_ch2br2.xml</code> needed for the simulation.
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for lifetime tracer simulation (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCHBr3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">2.527E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">2073600</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
<chemtracer id="TRCH2Br2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<unit type="char">mol mol-1</unit>
<mol_weight type="real">1.738E-1</mol_weight>
<?source_lifetime Rieger et al., GMD, 2015 ?>
<lifetime type="real">10627200</lifetime>

<c_solve type="char">lt</c_solve>

<lfeedback type='int'>0</lfeedback>
<transport type="char">stdaero</transport>
</chemtracer>
</tracers>
</pre>
</div>

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.lifetime_tracer_test.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-liftime_tracer_test</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Simplified Chemistry

2023-07-20T14:17:14Z

Tim R:

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> stdchem </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> stdchem </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Simplified Chemistry

2023-07-20T14:16:05Z

Tim R: typos

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>exp.testsuite.ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> stdchem </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> stdchem </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
./exp.testsuite.ohsim_simple_icon.run.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Lifetime Tracer Simulation

2023-07-20T13:11:57Z

Tim R: Adding Description "Setting up the Runscript"

Simplified Chemistry

2023-07-20T12:47:44Z

Tim R: /* Chemtracer-xml-file */

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> stdchem </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> stdchem </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
/.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Atmospheric Chemistry

2023-07-20T12:38:36Z

Tim R: /* Simplified Chemistry */

In this article it is described how to perform different kinds of atmospheric chemistry simulations. This includes the description of simulations with a simplified chemistry and MECCA-based (full) chemistry, their nameless settings, possible modules to make use of and information about initialization data.
Further, there are given some examples of typical simulation you can do with ICON-ART including atmospheric chemistry.

== Simplified Chemistry ==
When we talk about simplified calculated chemistry in ICON-ART, we mean that the concentration of the gases we want to simulate is calculated with a parametrization. Here production and depletion rates are calculated to solve the differential equation

<math>\frac{\mathrm{dc_i}}/{\mathrm{dt}} = P_i - \frac{c_i}/{\tau _i}</math>

{{math|1=''E'' = ''mc''{{sup|2}}}}

numerically. Here, <math>c_i</math> describes the number concentration of a certain tracer, <math>c_i</math> describes the chemical production and <math>\tau_i</math>is the belonging life time of tracer <math>i</math>.
For the namelist settings you are able to use for atmospheric chemistry, check out the ART-namelist parameters (see [[Namelist|ART namelists]]). The procedure of creating an ICON-ART simulation in Atmospheric Chemistry always comes back to switching on a namelist parameter and providing the path of the respective XML-file. How to create these for several cases, please check the examples below in the [[Atmospheric Chemistry|Configurations]] part.

To learn more about technical details of simplified chemistry, see also [https://gmd.copernicus.org/articles/10/2471/2017/ Weimer et. al. (2017)].

Note: When enabling simplified chemistry with the switch <code>lart_chemtracer = .TRUE.</code>, you can improve your runtime but the simulated concentration values are less exact compared to MECCA-based chemistry.

== MECCA-based Chemistry ==

=== General Information ===
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

=== Including MECCA-based Chemistry in a ICON-ART Simulation ===
(Note: It is recommended to perform all the following steps in the shell environment.)

The above mentioned collection of the gase phase chemistry reactions can be found in the supplement in the <code>gas.eqn</code> (path: caaba3.0/Mecca/gas.eqn).
Additionally it is also possible to edit existing reactions as well as creating new reactions with the help of "Replacement-files" (see an example in the [[Atmospheric Chemistry|Configurations]] part). Inside the <code>gas.eqn</code> every reaction is marked with a certain code. To select the specific reactions for the machanism labels can be set to your belonging reactions or, more easily, a new Gas-Equation-file <code>gas_Mechanism1.eqn</code> can be created, containing only the wanted reactions. (Note: Never edit the original <code>gas.eqn</code>! Better copy it in the first place and then rename and edit it, depending on the respective scientific goal.)
After that the following steps have to be fulfilled to create the code of your specific mechanism and to be able to execute an ICON-ART simulation with MECCA-based chemistry:
* set up a batch file: all previously set information about the mechanism can be selected and stated here (an example can be found below or also inside the supplement in <code>/caaba3.0/mecca/batch/example.bat</code>).
* execute <code>./mecca</code> inside the folder <code>/caaba3.0/mecca</code>. Here the previously created batch file has to be selected and the Fortran files with the mechanism are created.
* since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via <code>git clone https://gitlab.dkrz.de/art/mecca preproc.git</code>.
* in a new directory <code>Mecca_preproc</code> has been generated and the script <code>create_icon_code4.sh</code> can be found inside of it. By executing <code>/.create_icon_code4.sh -h</code> paths to the Mecca- and ICON home directories can be provided as well as a name for the XML-file that is going to be linked in the unscript later.
* the Mecca-XML-file is now generated and can be found in ICON in <code>/icon home>/runctrl examples/xml ctrl</code>.

Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important:''' As a final step, the ICON code has to be recompiled with the command <code>./config/dkrz/levante.intel --enable-art --enable-ecrad</code> and after executed <code>make -j 8</code>.

Tutorial Examples

2023-07-20T11:32:43Z

Tim R: /* Lifetime Tracer Simulation */

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds]] ====
* here a simulation with only stratospheric (simplified) ozone chemistry is performed, also polar stratospheric clouds are taken into account
* this example teaches you...
** the implementation of stratospheric specific chemistry (here on thee example of ozone)
** applying linearized ozone chemistry (LINOZ) in a simulation
** the implementation of polar stratospheric clouds (PSCs)
* click [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds|here]] to see more details

==== [[Lifetime Tracer Simulation]] ====
* here it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. Here the very short-lived substances Bromoform (<chem>CHBr3</chem>) and Dibromomethane (<chem>CH2Br2</chem>) are simulated.
* this example teaches you...
** the correct setup of the xml-file for such tracers.
** the structure and correct usage of namelist parameter settings of lifetime tracers in xml-files
** editing output variables
* click [[Lifetime Tracer Simulation|here]] to see more details

---------

=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Tutorial Examples

2023-07-20T11:15:18Z

Tim R: specifying descriptions of examples (Atmospheric Chemistry)

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds]] ====
* here a simulation with only stratospheric (simplified) ozone chemistry is performed, also polar stratospheric clouds are taken into account
* this example teaches you...
** the implementation of stratospheric specific chemistry (here on thee example of ozone)
** applying linearized ozone chemistry (LINOZ) in a simulation
** the implementation of polar stratospheric clouds (PSCs)
* click [[Stratospheric Ozone Chemistry and Polar Stratospheric Clouds|here]] to see more details

==== [[Lifetime Tracer Simulation]] ====
* here it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. Here the very short-lived substances Bromoform (<chem>CHBr3</chem>) and dibromomethane (<chem>CH2Br2</chem>) are simulated.
* this example teaches you...
** the correct setup of the xml-file for such tracers.
** the structure and correct usage of namelist parameter settings of lifetime tracers in xml-files
** editing output variables
* click [[Lifetime Tracer Simulation|here]] to see more details

---------

=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Stratospheric Ozone Chemistry and Polar Stratospheric Clouds

2023-07-20T11:14:05Z

Tim R: Creating the article "Creating Stratospheric Ozone Chemistry and Polar Stratospheric Clouds"

Tutorial Examples

2023-07-20T11:01:50Z

Tim R: /* Overview of topics */

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== [[Lifetime Tracer Simulation]] ====
In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. Here the very short-lived substances Bromoform (<chem>CHBr3</chem>) and dibromomethane (<chem>CH2Br2</chem>) are simulated. This tutorial teaches you...
* the correct setup of the xml-file for such tracers.
* the structure and correct usage of namelist parameter settings of lifetime tracers in xml-files
* editing output variables

---------

=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Tutorial Examples

2023-07-20T11:00:50Z

Tim R: Specifying Lifetime tracer simulation

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== [[Lifetime Tracer Simulation]] ====
In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. Here the very short-lived substances Bromoform (<chem>CHBr3</chem>) and dibromomethane (<chem>CH2Br2</chem>) are simulated. This tutorial teaches you...
* the correct setup of the xml-file for such tracers.
* the structure and correct usage of namelist parameter settings of lifetime tracers in xml-files
* editing output variables

---------

=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Lifetime Tracer Simulation

2023-07-20T09:37:38Z

Tim R:

- under construction -

In this example it is shown how to simulate a lifetime driven tracer with simplified chemistry in ICON-ART. This tutorial teaches you...
* the correct setup of the xml-file for such tracers.
* the structure of lifetime tracers in xml-files
* editing output variables

Tutorial Examples

2023-07-20T09:04:47Z

Tim R: /* Overview of topics */

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== [[Lifetime Tracer Simulation]] ====
* Lifetime tracer Simulation

---------
=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">

== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Lifetime Tracer Simulation

2023-07-20T09:03:57Z

Tim R: Creation of Configuration example of "Lifetime tracer"

- under construction -

Atmospheric Chemistry

2023-07-20T08:59:40Z

Tim R: removed examples here, now in Chapter "Tutorial examples"

In this article it is described how to perform different kinds of atmospheric chemistry simulations. This includes the description of simulations with a simplified chemistry and MECCA-based (full) chemistry, their nameless settings, possible modules to make use of and information about initialization data.
Further, there are given some examples of typical simulation you can do with ICON-ART including atmospheric chemistry.

== Simplified Chemistry ==
When we talk about simplified calculated chemistry in ICON-ART, we mean that the concentration of the gases we want to simulate is calculated with a parametrization. Here production and depletion rates are calculated to solve the differential equation

<math>\frac{\mathrm{dc_i}}/{\mathrm{dt}} = P_i - \frac{c_i}/{\tau _i}</math>

{{math|1=''E'' = ''mc''{{sup|2}}}}

numerically. Here, <math>c_i</math> describes the number concentration of a certain tracer, <math>c_i</math> describes the chemical production and <math>\tau_i</math>is the belonging life time of tracer <math>i</math>.
For the namelist settings you are able to use for atmospheric chemistry, check out the ART-namelist parameters (see [[Namelist|ART namelists]]). The procedure of creating an ICON-ART simulation in Atmospheric Chemistry always comes back to switching on a namelist parameter and providing the path of the respective XML-file. How to create these for several cases, please check the examples below in the [[Atmospheric Chemistry|Configurations]] part.

To learn more about technical details of simplified chemistry, see also [https://gmd.copernicus.org/articles/10/2471/2017/ Weimer et. al. (2017)]

Note: When enabling simplified chemistry with the switch <code>lart_chemtracer = .TRUE.</code>, you can improve your runtime but the simulated concentration values are less exact compared to MECCA-based chemistry.

== MECCA-based Chemistry ==

=== General Information ===
The MECCA(=Module Efficiently Calculating the Chemistry of the Atmosphere) based chemistry describes a full gas phase chemistry that can be applied as an extension to the parametrized [[Atmospheric Chemistry|Simplified Chemistry]] (see above). MECCA based chemistry is generally more exact in the concentration values but the overall runtime is longer compared to purely simplified chemistry simulations. MECCA itself is originally a submodule of the CAABA box model where an air parcel is described as a box and outgoing from this model all exchange processes in- and outward of the box are calculated. As MECCA is part of this model, it contains a wide collection of the most important reactions, including Ozone-, Methane-, HOx-, NOx-, Carbonhydrogen-, Halogene- and Sulfur chemistry. MECCA is available in a [http://www.geosci-model-dev.net/4/373/2011/gmd-4-373-2011-supplement.zip supplement], available to download for free and containing all auxiliaries to perform MECCA-simulations.

=== Including MECCA-based Chemistry in a ICON-ART Simulation ===
(Note: It is recommended to perform all the following steps in the shell environment.)

The above mentioned collection of the gase phase chemistry reactions can be found in the supplement in the <code>gas.eqn</code> (path: caaba3.0/Mecca/gas.eqn).
Additionally it is also possible to edit existing reactions as well as creating new reactions with the help of "Replacement-files" (see an example in the [[Atmospheric Chemistry|Configurations]] part). Inside the <code>gas.eqn</code> every reaction is marked with a certain code. To select the specific reactions for the machanism labels can be set to your belonging reactions or, more easily, a new Gas-Equation-file <code>gas_Mechanism1.eqn</code> can be created, containing only the wanted reactions. (Note: Never edit the original <code>gas.eqn</code>! Better copy it in the first place and then rename and edit it, depending on the respective scientific goal.)
After that the following steps have to be fulfilled to create the code of your specific mechanism and to be able to execute an ICON-ART simulation with MECCA-based chemistry:
* set up a batch file: all previously set information about the mechanism can be selected and stated here (an example can be found below or also inside the supplement in <code>/caaba3.0/mecca/batch/example.bat</code>).
* execute <code>./mecca</code> inside the folder <code>/caaba3.0/mecca</code>. Here the previously created batch file has to be selected and the Fortran files with the mechanism are created.
* since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via <code>git clone https://gitlab.dkrz.de/art/mecca preproc.git</code>.
* in a new directory <code>Mecca_preproc</code> has been generated and the script <code>create_icon_code4.sh</code> can be found inside of it. By executing <code>/.create_icon_code4.sh -h</code> paths to the Mecca- and ICON home directories can be provided as well as a name for the XML-file that is going to be linked in the unscript later.
* the Mecca-XML-file is now generated and can be found in ICON in <code>/icon home>/runctrl examples/xml ctrl</code>.

Now, in the respective runscript the namelist parameter <code>lart_mecca</code> has be set to <code>.TRUE</code> and for <code>cart_mecca_xml</code> the path to the Mecca file can be provided.
'''Important:''' As a final step, the ICON code has to be recompiled with the command <code>./config/dkrz/levante.intel --enable-art --enable-ecrad</code> and after executed <code>make -j 8</code>.

MECCA-based (full) Chemistry

2023-07-14T13:22:22Z

Tim R:

MECCA-based (full) Chemistry

2023-07-14T13:22:04Z

Tim R:

MECCA-based (full) Chemistry

2023-07-14T12:59:46Z

Tim R:

Tutorial Examples

2023-07-14T12:58:27Z

Tim R: Linking the MECCA configuration example

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== [[MECCA-based (full) Chemistry]] ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click [[MECCA-based (full) Chemistry|here]] to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== Lifetime tracer Simulation ====
* Lifetime tracer Simulation

---------
=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">
== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

MECCA-based (full) Chemistry

2023-07-14T12:55:29Z

Tim R: Creating the article to MECCA-example

Tutorial Examples

2023-07-14T11:14:29Z

Tim R: Format editings

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click [[Simplified Chemistry|here]] to see more details

==== MECCA-based (full) Chemistry ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click here to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== Lifetime tracer Simulation ====
* Lifetime tracer Simulation

---------
=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">
== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>

Simplified Chemistry

2023-07-14T11:10:23Z

Tim R: Update on Runscript settings

- work in progress -

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B05-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

Depending on the used HPC-System, some parameter concerning the running job like maximum running time and used nodes can be set. For this case study the following settings can be copied. Note that this is valid for the HoreKa HPC system and that it can differ to other systems.
<div class="toccolours mw-collapsible mw-collapsed">
Part 5: Runscript job Settings (Example configuration)
<pre class="mw-collapsible-content">
cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

To conclude and to double check, in the following box the complete runscript is shown once again.
<div class="toccolours mw-collapsible mw-collapsed">
Complete example configuration of the runscript
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_mecca_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
# global timing
ndays_restart=366
dt_restart=`expr ${ndays_restart} \* 86400`
#
#-----------------------------------------------------------------------------
# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"

#
#-----------------------------------------------------------------------------
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'z_ifc','temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_chem = .TRUE.
lart_mecca = .TRUE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_mecca_xml = '${ARTFOLDER}/runctrl_examples/xml_ctrl/tracers_oh_reimus.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF

cp ${ICONFOLDER}/bin/icon ./icon.exe

cat > job_ICON << ENDFILE
#!/bin/bash -x
#SBATCH --nodes=4
#SBATCH --time=12:00:00
#SBATCH --ntasks-per-node=76
#SBATCH --partition=cpuonly
#SBATCH -A hk-project-iconart
###SBATCH --constraint=LSDF

module load compiler/intel/2022.0.2 mpi/openmpi/4.0 lib/netcdf/4.9_serial lib/hdf5/1.12_serial lib/netcdf-fortran/4.5_serial lib/eccodes/2.25.0 numlib/mkl/2022.0.2

mpirun --bind-to core --map-by core --report-bindings ./icon.exe

ENDFILE

chmod +x job_ICON
sbatch job_ICON
</pre>
</div>

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> stdchem </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> stdchem </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files for different resolutions.

== Running the simulation ==
Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing
/.ohsim_simple_icon.run
a job can be submitted to the respective HPC-System. Type the terminal command
squeue
to view a list of your submitted and currently running and jobs.
By changing in the output directory (which is according to our runscript <code>/hkfs/work/workspace/scratch/hp8526-ws_icon_oh/output/ohsim_icon_simple_atom1</code> you can check the slurm file for possible errors and run times after your job has been run through.

In the output directory you can also find all output data for postprocessing in netCDF format.

Simplified Chemistry

2023-07-14T10:42:41Z

Tim R: Xml-files and running the simulation and model output

Simplified Chemistry

2023-07-13T15:07:15Z

Tim R: /* Configuration case */

Simplified Chemistry

2023-07-13T15:05:56Z

Tim R:

Simplified Chemistry

2023-07-13T15:05:17Z

Tim R: adding explanations about xml-files

In this first example it is shown how to perform a simulation of with simplified chemistry in ICON-ART. This tutorial teaches you...
* the basics of setting up an ICON runscript with ICON-ART settings
* the use of the most simple ICON-ART namelist parameter
*the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
* the implementation of emission data in a simulation
Emission data will be applied on the simulation as well.

== Configuration case ==
The depicted case is about simulating the tropospheric hydroxyl radical (OH), one of the most important oxidants of the atmosphere. It's main source in the lower troposphere is the photolysis of ozone and its consequent reaction of an excited oxygen atom with the surrounding water vapor:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

Additionally the excited Oxygen atom reacts further with Nitrogen and Oxygen:

<chem>O3 + hv -> O2 + O(^1D)</chem>
<chem>O(^1D) + H2O -> 2OH</chem>

The main sink of OH in the Troposphere is methane and carbon monooxide:

<chem>OH + CH4 -> H2O + CH3 -> ... -> CO + HO2</chem>
<chem>OH + CO -> H + CO2</chem>
<chem>OH + CO -> HOCO</chem>

Now the OH concentrations are calculated with the respective kinetic and photolysis constants, based on chemical kinetic laws:
<math>[\ce{OH}]=\frac{\mathrm{2[\ce{O(^1D)}]}k_{\ce{H2O}}[\ce{H2O}]}{k_{\ce{CH4}}[\ce{CH4}]+(k_{\ce{CO,1}}+k_{\ce{CO,2}})[\ce{CO}]}</math>
with <math>[\ce{O(^1D)}]=\frac{J_{\ce{O3}}[\ce{O3}]}{k_{\ce{O2}}[\ce{O2}]+k_{\ce{N2}}[\ce{N2}]+k_{\ce{H2O}}[\ce{H2O}]}</math>.

Additionally emission data of the main sinks of OH are implemented. Since the simulation is performed on a R2B04-grid the following emission data are the most suitable ones for the respective trace gases:
*<chem>CH4</chem>: anthropogenic (EDGAR-432 monthly), biomass-burning (GFED3), biogenic (MEGAN-MACC)
*<chem>CO</chem>: anthropogenic (EDGAR-432 monthly)
For more information on recommended emission data see the abstract, dealing with [[Input|Emission Data]].
Since emission data are relatively large, they can also just be left out.

== Setting up the Runscript ==
Let's start with the runscript that has to be prepared. Please note that the in the following explained parts have to be printed in one runscript-file with the naming designation "xyz.run". Here it is named <code>ohsim_simple_icon.run</code> but of course you can call it differently as well.

Inside of that, first check that all your directories are correct, probably they have to be adjusted. Abbreviations used here are the following:
*CENTER: Your organization
*EXPNAME: name of your ICON-Simulation
*OUTDIR: Directory where the simulation output will be stored
*ARTFOLDER: Directory where the ICON-ART code is stored
*INDIR: Directory where the necessary Input data are stored
*EXP:
*lart: For ICON-ART Simulation that has to be switched to <code>Oheim_simple_icon.run</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Part 1: Runscript Directory Settings (Example configuration)
<pre class="mw-collapsible-content">
#!/bin/bash
CENTER=IMK
workspace=/hkfs/work/workspace/scratch/hp8526-ws_icon_oh
basedir=${workspace}/icon-kit-testsuite
icon_data_poolFolder=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT/AMIP/amip_input
EXPNAME=ohsim_icon_simple_atom1
OUTDIR=${workspace}/output/${EXPNAME}
ICONFOLDER=/home/hk-project-iconart/hp8526/icon-kit
ARTFOLDER=${ICONFOLDER}/externals/art
INDIR=/hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/INPUT
EXP=ECHAM_AMIP_LIFETIME
lart=.True.

FILETYPE=4
COMPILER=intel
restart=.False.
read_restart_namelists=.False.

# Remove folder from OUTDIR for postprocessing output
OUTDIR_PREFIX=${workspace}

# Create output directory and go to this directory

if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

#input for global domain
ln -sf ${INDIR}/../INPUT/GRID/icon_grid_0014_R02B05_G.nc iconR2B05_DOM01.nc
ln -sf ${INDIR}/../INPUT/EXTPAR/icon_extpar_0014_R02B05_G.nc extpar_iconR2B05_DOM01.nc
ln -sf /hkfs/work/workspace/scratch/fb4738-dwd_ozone/icon/output/0014_R02B05/uc1_ifs_t1279_grb2_remap_rev832_0014_R02B05_2018010100.nc ifs2icon_R2B05_DOM01.nc

ln -sf $ICONFOLDER/data/rrtmg_lw.nc rrtmg_lw.nc
ln -sf $ICONFOLDER/data/ECHAM6_CldOptProps.nc ECHAM6_CldOptProps.nc

ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/mozart_coord.nc ${OUTDIR}/mozart_coord.nc
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat
ln -sf ${ARTFOLDER}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-aer.dat ${OUTDIR}/FJX_scat-aer.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j.dat ${OUTDIR}/FJX_j2j.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-cld.dat ${OUTDIR}/FJX_scat-cld.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-ssa.dat ${OUTDIR}/FJX_scat-ssa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_scat-UMa.dat ${OUTDIR}/FJX_scat-UMa.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec.dat ${OUTDIR}/FJX_spec.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_std.dat ${OUTDIR}/atmos_std.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/atmos_h2och4.dat ${OUTDIR}/atmos_h2och4.dat

ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_j2j_extended.dat ${OUTDIR}/FJX_j2j_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended.dat ${OUTDIR}/FJX_spec_extended.dat
ln -sf ${ARTFOLDER}/runctrl_examples/photo_ctrl/FJX_spec_extended_lyman.dat ${OUTDIR}/FJX_spec_extended_lyman.dat

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# this if condition is necessary because otherwise
# a new link in ${INDIR}/${EXP}/emiss_minimal is generated
# linking to itself
if [ ! -L ${OUTDIR}/emissions ]; then
ln -sd /home/hk-project-iconart/hp8526/emissions ${OUTDIR}/emissions
fi

# the namelist filename
atmo_namelist=NAMELIST_${EXPNAME}
#
#-----------------------------------------------------------------------------
</pre>
</div>

Additionally in the next lines of code you set the timing. In this simulation we only simulate a few days. Because OH is dependent from the solar radiation, the output interval is set to 10 hours to calculate OH to every time of the day.
<div class="toccolours mw-collapsible mw-collapsed">
Part 2: Runscript Timing Settings (Example configuration)
<pre class="mw-collapsible-content">
! run_nml: general switches ----------
&# model timing

start_date=${start_date:="2016-07-29T00:00:00Z"}
end_date=${end_date:="2016-08-23T00:00:00Z"}
output_start=${start_date:="2016-07-29T00:00:00Z"}
output_end=${end_date:="2016-08-23T00:00:00Z"}
output_interval="PT10H"
modelTimeStep="PT6M"
leadtime="P10D"
checkpoint_interval="P30D"
</pre>
</div>

Further, all the namelist parameters (from the regular ICON model without ART-extension) have to be set. For a regular ICON-ART-Simulation the following settings are recommended - if not stated differently.

<div class="toccolours mw-collapsible mw-collapsed">
Part 3: Runscript ICON-Parameter and -Namelist Settings (Example configuration)
<pre class="mw-collapsible-content">
# model parameters
model_equations=3 # equation system
# 1=hydrost. atm. T
# 1=hydrost. atm. theta dp
# 3=non-hydrost. atm.,
# 0=shallow water model
# -1=hydrost. ocean
#-----------------------------------------------------------------------------
# the grid parameters
declare -a atmo_dyn_grids=("iconR2B04_DOM01.nc" "iconR2B05_DOM02.nc" "iconR2B06_DOM03.nc")
# "iconR2B08_DOM03.nc"
#atmo_dyn_grids="iconR2B07_DOM02.nc","iconR2B08_DOM03.nc"
#atmo_rad_grids="iconR2B06_DOM01.nc"
#-----------------------------------------------------------------------------

# create ICON master namelist
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf

no_of_models=1

cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "$start_date"
experimentStopDate = "$end_date"
forecastLeadTime = "$leadtime"
checkpointTimeIntval = "$checkpoint_interval"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="$atmo_namelist"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
EOF

#-----------------------------------------------------------------------------
#

#-----------------------------------------------------------------------------
#
# write ICON namelist parameters
# ------------------------
# For a complete list see Namelist_overview and Namelist_overview.pdf
#
# ------------------------
# reconstrcuct the grid parameters in namelist form
dynamics_grid_filename=""
for gridfile in ${atmo_dyn_grids}; do
dynamics_grid_filename="${dynamics_grid_filename} '${gridfile}',"
done
radiation_grid_filename=""
for gridfile in ${atmo_rad_grids}; do
radiation_grid_filename="${radiation_grid_filename} '${gridfile}',"
done

# ------------------------

cat > ${atmo_namelist} << EOF
&parallel_nml
nproma = 8 ! optimal setting 8 for CRAY; use 16 or 24 for IBM
p_test_run = .false.
l_test_openmp = .false.
l_log_checks = .false.
num_io_procs = 0 ! up to one PE per output stream is possible
itype_comm = 1
iorder_sendrecv = 3 ! best value for CRAY (slightly faster than option 1)
/
&grid_nml
dynamics_grid_filename = 'iconR2B05_DOM01.nc'
dynamics_parent_grid_id = 0
!radiation_grid_filename = ${radiation_grid_filename}
lredgrid_phys = .false.
lfeedback = .true.
ifeedback_type = 2
/
&initicon_nml
lconsistency_checks = .false.
init_mode = 2 ! operation mode 2: IFS
zpbl1 = 500.
zpbl2 = 1000.
! l_sst_in = .true.
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
! nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
! dtime = ${dtime} ! timestep in seconds
modelTimeStep = "${modelTimeStep}"
ldynamics = .TRUE. ! dynamics
ltransport = .true.
iforcing = 3 ! NWP forcing
ltestcase = .false. ! false: run with real data
msg_level = 7 ! print maximum wind speeds every 5 time steps
ltimer = .true. ! set .TRUE. for timer output
timers_level = 10 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = ${lart}
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 1
inwp_cldcover = 1
inwp_turb = 1
inwp_satad = 1
inwp_sso = 1
inwp_gwd = 1
inwp_surface = 1
icapdcycl = 3 ! apply CAPE modification to improve diurnalcycle over tropical land (optimizes NWP scores)
latm_above_top = .false., .true. ! the second entry refers to the nested domain (if present)
efdt_min_raylfric = 7200.
itype_z0 = 2
icpl_aero_conv = 1
icpl_aero_gscp = 1
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
/
&nwp_tuning_nml
tune_zceff_min = 0.075 ! ** default value to be used for R3B7; use 0.05 for R2B6 in order to get similar temperature biases in upper troposphere **
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! ""
pat_len = 100.
c_diff = 0.2
rat_sea = 8.5 ! ** new since r20191: 8.5 for R3B7, 8.0 for R2B6 in order to get similar temperature biases in the tropics **
ltkesso = .true.
frcsmot = 0.2 ! these 2 switches together apply vertical smoothing of the TKE source terms
imode_frcsmot = 2 ! in the tropics (only), which reduces the moist bias in the tropical lower troposphere
! use horizontal shear production terms with 1/SQRT(Ri) scaling to prevent unwanted side effects:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .true. !!! .false. for assimilation cycle and forecast
itype_heatcond = 2
idiag_snowfrac = 2
lsnowtile = .false. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .false.
itype_lndtbl = 3 ! minimizes moist/cold bias in lower tropical troposphere
itype_root = 2
/
&radiation_nml
irad_o3 = 10
irad_aero = 6
albedo_type = 2 ! Modis albedo
vmr_co2 = 390.e-06 ! values representative for 2012
vmr_ch4 = 1800.e-09
vmr_n2o = 322.0e-09
vmr_o2 = 0.20946
vmr_cfc11 = 240.e-12
vmr_cfc12 = 532.e-12
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 50000.
rayleigh_coeff = 0.10
lhdiff_rcf = .true.
divdamp_order = 24 ! for data assimilation runs, '2' provides extra-strong filtering of gravity waves
divdamp_type = 32 !!! optional: 2 for assimilation cycle if very strong gravity-wave filtering is desired
divdamp_fac = 0.004
l_open_ubc = .false.
igradp_method = 3
l_zdiffu_t = .true.
thslp_zdiffu = 0.02
thhgtd_zdiffu = 125.
htop_moist_proc= 22500.
hbot_qvsubstep = 22500. ! use 19000. with R3B7
/
&sleve_nml
min_lay_thckn = 20.
max_lay_thckn = 400. ! maximum layer thickness below htop_thcknlimit
htop_thcknlimit = 14000. ! this implies that the upcoming COSMO-EU nest will have 60 levels
top_height = 75000.
stretch_fac = 0.9
decay_scale_1 = 4000.
decay_scale_2 = 2500.
decay_exp = 1.2
flat_height = 16000.
/
&dynamics_nml
iequations = 3
idiv_method = 1
divavg_cntrwgt = 0.50
lcoriolis = .TRUE.
/
&transport_nml
! qv, qc, qi, qr, qs
itype_vlimit = 1,1,1,1,1
ivadv_tracer = 3, 3, 3, 3, 3
itype_hlimit = 3, 4, 4, 4 , 4
ihadv_tracer = 52, 2,2,2,2
iadv_tke = 0
/
&diffusion_nml
hdiff_order = 5
itype_vn_diffu = 1
itype_t_diffu = 2
hdiff_efdt_ratio = 24.0
hdiff_smag_fac = 0.025
lhdiff_vn = .TRUE.
lhdiff_temp = .TRUE.
/
&interpol_nml
nudge_zone_width = 8
lsq_high_ord = 3
l_intp_c2l = .true.
l_mono_c2l = .true.
support_baryctr_intp = .false.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
/
&io_nml
itype_pres_msl = 4 ! IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = ${FILETYPE} ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
output_start = "${output_start}"
output_end = "${output_end}"
output_interval = "${output_interval}"
steps_per_file = 1
include_last = .TRUE.
output_filename = 'icon-art-${EXPNAME}-chem' ! file name base
ml_varlist = 'temp','pres','group:ART_CHEMISTRY','u','v','OH_Nconc'
output_grid = .TRUE.
remap = 1
reg_lon_def = -180.,1,180.
reg_lat_def = -90.,1,90.
/
</pre>
</div>
Please note in the last namelist section "output_nml" that you can set all output variables that you need to postprocess your data later. All assigned variables here will be written in the output netCDF-files as well. To learn more about post processing your data, check out a later chapter of this article or the [[Postprocessing]] article.

Now, we're getting to the ICON-ART settings. To enable chemistry in an ICON-ART Simulation inn general, the switch <code>lart_chem</code> has to be set to <code>.TRUE.</code>. With <code>lart_diag_out</code> output of the diagnostic fields can be enabled. Due to setting <code>lart_chem=.TRUE.</code> either <code>lart_chemtracer</code> or <code>lart_mecca</code> have to be set to <code>.TRUE.</code>. Because we want to perform a simulation with simplified chemistry, we have to switch on <code>lart_chemtracer</code>. If this namelist parameter is set to <code>.TRUE.</code>, also <code>cart_chemtracer_xml</code> has to be fulfilled. Here you enter the path of your xml-file which describes the tracers occurring and their properties in the simulation. How to create this xml-file is explained in the next chapter. Because this xml-file will contain information about included emission data of certain chemical species, in <code>cart_emiss_xml_file</code> the path of a second emission-xml-file has to be set.
An example configuration for this part is shown in the following:
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Runscript ICON-ART Settings (Example configuration)
<pre class="mw-collapsible-content">
&art_nml
lart_chem = .TRUE.
lart_diag_out = .TRUE.
lart_aerosol = .FALSE.
lart_mecca = .FALSE.
lart_chemtracer = .TRUE.
cart_emiss_xml_file = '${ARTFOLDER}/runctrl_examples/emiss_ctrl/emissions_R2B05_0014_cs.xml'
cart_chemtracer_xml = '/home/hk-project-iconart/hp8526/icon-kit/externals/art/runctrl_examples/xml_ctrl/chemtracer_reimus.xml'
cart_input_folder = '${OUTDIR}'
cart_io_suffix = '0014'
iart_init_gas = 0
/
EOF
</pre>
</div>
Please note that there are also several other namelist parameter you can select from (see [[Namelist]] article) but to perform our we're done for this part.

== Setting up the xml-files ==
An xml-file describes the chemical components of the simulation which means that all trace gases or aerosols and their properties that are relevant for the simulation are listed here. Since we perform a simulation with simplified ICON-ART chemistry we need the matching chemtracer-xml-file. Additionally we need to create an emission-xml-file since emission data of certain chemical species is included in our simulation.

=== Chemtracer-xml-file ===
This file contains all the necessary information to describe the chemical mechanism with the respective important chemical species.
The following information are given per chemical species:
* properties like mol weight, units or lifetime of the tracer
* main sink
* main reaction product after reacting with the main sink after a given lifetime
* partly information about included emission data (ANT=anthropogenic emission, BIO=biogenic emission, BBE=biomass burning emission, more information about available emission data, see [[Emission Data]])
<div class="toccolours mw-collapsible mw-collapsed">
Part 4: Chemtracer-xml-file for OH chemistry (Example configuration)
<pre class="mw-collapsible-content">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "tracers.dtd">

<tracers>
<chemtracer id="TRCH4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.604E-2</mol_weight>
<?source_lifetime Hayman et al., ACP, 2017 ?>
<lifetime type="real">286977600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO</products>
<emiss_ANT type="char" inum_levs="1">CH4_ANT_EDGAR432-monthly</emiss_ANT>
<emiss_BBE type="char" inum_levs="1">CH4_BBE_GFED3</emiss_BBE>
<emiss_BIO type="char" inum_levs="1">CH4_BIO_MEGAN-MACC</emiss_BIO>
<init_mode type="int">0</init_mode>
<init_name type="char">CH4</init_name>
</chemtracer>
<chemtracer id="TRC2H6" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">3.006E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">5011200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<init_mode type="int">0</init_mode>
<init_name type="char">C2H6</init_name>
</chemtracer>
<chemtracer id="TRC3H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.40956E-2</mol_weight>
<?source_lifetime Hodnebrog et al, Atmos. Sci. Lett., 2018 ?>
<lifetime type="real">1123200</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">0.736*TRCH3COCH3</products>
<init_mode type="int">0</init_mode>
<init_name type="char">C3H8</init_name>
</chemtracer>
<chemtracer id="TRC5H8" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.812E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 16 ?>
<lifetime type="real">8640</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCH3COCH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">5.808E-2</mol_weight>
<?source_lifetime Weimer (2015), p. 9 ?>
<lifetime type="real">1728000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
</chemtracer>
<chemtracer id="TRCO" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">2.801E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">5184000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<c_solve type="char">OH</c_solve>
<products type="char">TRCO2</products>
<emiss_ANT type="char" inum_levs="1">CO_ANT_EDGAR432-monthly</emiss_ANT>
<init_mode type="int">0</init_mode>
<init_name type="char">CO</init_name>
</chemtracer>
<chemtracer id="TRCO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.401E-2</mol_weight>
<?source_lifetime Houghton et al., IPCC, Cambridge University Press, 2001 ?>
<lifetime type="real">3153600000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
<products type="char">TRCO</products>
</chemtracer>
<chemtracer id="TRNH3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">1.70E-2</mol_weight>
<?source_lifetime Pinder et al., GRL, 2008?>
<lifetime type="real">86400</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRNO2</products>
</chemtracer>
<chemtracer id="TRNO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.601E-2</mol_weight>
<?source_lifetime Wypych, 2017, Atlas of Material Damage?>
<lifetime type="real">4730400000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRHNO3</products>
</chemtracer>
<chemtracer id="TRSO2" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.40E-2</mol_weight>
<?source_lifetime Von Glasow, Chemical Geology, 2009 ?>
<lifetime type="real">1209600</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRH2SO4</products>
</chemtracer>
<chemtracer id="TROCS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.01E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">504576000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">TRSO2</products>
</chemtracer>
<chemtracer id="TRDMS" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.21E-2</mol_weight>
<?source_lifetime Ullwer (2017) ?>
<lifetime type="real">216000</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">OH</c_solve>
<products type="char">0.993*TRSO2;0.007*TROCS</products>
</chemtracer>
<chemtracer id="TRHNO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">6.30E-2</mol_weight>
<?source_lifetime Day et al., ACP, 2008?>
<lifetime type="real">21600</lifetime>
<transport type="char"> stdchem </transport>
<init_name type="char"> HNO3 </init_name>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRH2SO4" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">9.80E-2</mol_weight>
<?source_lifetime Fiedler et al., ACP, 2005?>
<lifetime type="real">1800</lifetime>
<transport type="char"> stdchem </transport>
<unit type="char">mol mol-1</unit>
<init_mode type="int">0</init_mode>
<c_solve type="char">lt</c_solve>
</chemtracer>
<chemtracer id="TRO3" full="FALSE" chemtr="TRUE">
<tag001 type="char">chemtr</tag001>
<mol_weight type="real">4.800E-2</mol_weight>
<?source_lifetime Ehhalt et al., IPCC, 2001, Chapter 4 ?>
<lifetime type="real">1555200</lifetime>
<transport type="char"> stdchem </transport>
<init_mode type="int"> 0 </init_mode>
<init_name type="char">O3</init_name>
<unit type="char">mol mol-1</unit>
<c_solve type="char">linoz</c_solve>
</chemtracer>
</tracers>
</pre>
</div>

=== Emission-xml-file ===
To link the information from the chemtracer-xml-file that we want to include emission data of a specific chemical species with the specific information about the respective emission, ICON-ART is working with, we need a second xml-file: The emission-xml-file. It is normally a standard grid-dependant xml-file you can use where nothing has to be changed. Since this Simulation is performed on a R2B05 grid, we use the <code>emissions_R2B05_0014_cs.xml</code>. Have a look at the article about [[Emission Data]] to check out all the available emission-xml-files.

Tutorial Examples

2023-07-13T13:42:10Z

Tim R: Linking the article "Simplified Chemistry"

- under construction! -

In this article several examples from different application areas in ICON-ART are presented. Just click on the highlighted text to get to the page of the respecting example. For every example a configuration is explained to try out typical cases in ICON-ART yourselves. Thereby, these pages can be viewed as a Tutorial in ICON-ART.

== Overview of topics ==

=== Atmospheric Chemistry Simulations ===
==== [[Simplified Chemistry]] ====
* here a simulation of the Hydroxylradical (OH) is performed with simplified chemistry
* this example teaches you...
** the basics of setting up an ICON runscript with ICON-ART settings
** the use of the most simple ICON-ART namelist parameter
** the implementation of the desired chemical species in a simulation by setting up a chemtracer xml-data for simplified chemistry simulations
** the implementation of emission data in a simulation
* click here to see more details

==== MECCA-based (full) Chemistry ====
* here a simulation with (full) MECCA-based chemistry is performed, for that a complete reaction mechanism is created and transferred to ICON-ART
* this example teaches you...
** the implementation of (full) MECCA-based chemistry in ICON-ART
** the creation of a chemical mechanism and the selection of the respective desired chemical species and their reactions in MECCA
** the implementation of not yet in MECCA implemented reactions in your mechanism
** the creation of the to your mechanism belonging Mecca-xml data to link MECCA calculations with ICON-ART
* click here to see more details

==== Stratospheric Ozone chemistry (with linearized Ozone, LINOZ) ====
* Stratospheric Ozone chemistry (with linearized Ozone, LINOZ)

==== Lifetime tracer Simulation ====
* Lifetime tracer Simulation

---------
=== Aerosol Simulations ===
==== [[Simulating a Point Source]] ====
* In this example a Point Source is installed at the location of the volcano Raikoke and a constant emission of SO2 and Ash is emitted into the atmosphere.
* this example teaches you...
** How to setup and run your first Simulation
** The setup of the directory structure when doing an ICON-ART Simulation
** How to modify a runscript to suit your needs
** How to modify .xml data to set up a Simulation
** A possible approach to visualise the output data

------
<div class="toccolours mw-collapsible mw-collapsed">
== Slides ICON-Training ==
<div class="mw-collapsible-content">

[[File:TD_slides_A.png|left]]
[[File:TD_slides_B.png|left]]

</div>
</div>