icon-art guide - User contributions [en]

Getting Started

2024-11-22T08:10:18Z

Editor 2: /* Getting the source code */ removed the git init submodules since it is no longer needed ~LR

== Requirements to run ICON-ART ==

As for most atmospheric models, it is strongly recommended to run ICON-ART on a High Performance Computing system such as Levante from the [https://www.dkrz.de/en DKRZ] or [https://www.scc.kit.edu/en/services/horeka.php HoreKA] from KIT. This usually requires an account which has to be obtained through the respective HPC Systems procedures.

== The auto-icon tool for automating runs ==
''auto-icon'' is a flexible tool for automating ICON(-ART) runs, starting from the retrieval of input data to post-processing and visualization. After an initial set-up, a great simplification in running various examples can be achieved. ''auto-icon'' takes care of obtaining the model code and installing it on the desired HPC system, retrieving parts of the input data (more to come) and running the model. Custom post-processing and visualization tasks can be added to the pipeline to get them executed automatically. The automation engine behind ''auto-icon'', called [https://autosubmit.readthedocs.io/en/master/ Autosubmit], is a powerful and flexible tool, providing multi-platform support, fault tolerance and an experiment database. The latter stores metadata for all conducted experiments and allows simple finding and reproduction of existing workflows, thus promoting the [http://www.go-fair.org/fair-principles/ FAIR] principles.

Especially if you are new to the ICON-ART model, ''auto-icon'' can help you set up a first run as it builds the model for you and has a bunch of example cases built in, running out of the box. These [https://www.icon-art.kit.edu/ ICON-ART standard cases] are included as templates along with a few other cases. There is a separate [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/home Wiki] for ''auto-icon'' with a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Shortest-guide-to-success shortest guide to success] and a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Step-by-step-guide more detailed guide].

The remainder of this Wiki serves as valuable source of information on how the ART module itself works, while the ''auto-icon'' Wiki only deals with technical aspects of ''auto-icon''.
Further, ''auto-icon'' does not use runscripts to conduct the runs but instead loads a configuration and a namelist describing the whole model workflow. The correspondence of runscript entries with the configuration is demonstrated in [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Transform-a-runscript-into-an-auto-icon-configuration this guide].

For starting your ICON model run with ''auto-icon'', you go to one of the linked guides and skip the remainder of this page.

== Getting the source code ==

The source code for ART is available in the open-source ICON repository under [http://www.icon-model.org www.icon-model.org]

To clone the ICON repository use:

<code>
git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git
</code>

This will get the ICON repository and additionally, because of the --recursive flag, also the submodules (including ART).

== Installation ==

ICON-ART is already included in the most recent ICON version. For Instructions on how to install ICON, please refer to the first chapter of the [https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html:official ICON Model Tutorial].
The only caveat is that during the configuration step the tag <code> --enable-art </code> has to be included. In addition, to set up and use chemical mechanisms using the MECCA/KPP the related interfaces have to be included using the tag <code> --enable-art —enable-art-gpl </code> (Be aware that you accept the GPL conditions for MECCA and KPP when you use this option).

<b>General step-by-step guide:</b>

* Navigate to your ICON main folder.
* Within this directory, you will find the 'config' folder.
* Inside the 'config' directory, there are several subfolders corresponding to different institutions.
* In each institutional folder, you will find configuration scripts tailored for various computers and compilers.

<b>Example for HoreKa at KIT:</b>
# Access your ICON main folder.
# Run the following command: <code>config/kit/hk.intel-2022-openmpi-4.0 --enable-art --enable-ecrad</code>
# Execute <code>make -j4</code>
# You should now have a functional binary with ART integration. For other HPC systems, substitute the config script with the one relevant to your HPC system.

== Creating a Runfile ==

* Go to <code>icon-kit/run/checksuite.icon-kit</code>

* Run bash-script <code>run_testsuite</code> via <code>./run_testsuite</code>

* The script creates the folder runscripts, which contains exemplary runfiles which are adapted to your HPC-System (if available in the config files). For the description of the runscripts see the table below.

* in <code>icon-kit/run/checksuites.icon-kit/Test-<current_date>.info</code> you will find a few informations to the ICON-ART Testsuite you just created, including your output directory when you perform the model runs in the next step

* To run your chosen runscript just execute from the console, e.g. by typing <code>runscripts/NWP_LIFETIME.run</code>

{| class="wikitable"
|-
! runscript !! description
|-
| NWP_OH_CHEMISTRY.run || Short example for simplified oh chemistry
|-
| NWP_GASPHASE.run || Example for MECCA chemistry based on https://gmd.copernicus.org/articles/11/4043/2018/
|-
| NWP_LIFETIME.run || Example for parameterized chemtracer chemistry including lifetime, simnoy, linoz and passive tracers, as well as regional tracers and PSCs
|-
| NWP_EXT_DATA.run || tbd
|-
| NWP_LIFETIME_lart.run || tbd
|-
| NATAERO_NORAD.run || tbd
|-
| VOLAERO_RAD.run || tbd
|}

== Running a Job ==

For a user who succeeded in running the ICON model, there are only a few steps to run the ART extension along with the ICON model. A description how to run the ICON model can be found in .

In order to run ICON-ART, one has to do the following steps:

* Make sure you have everything required for an ICON run

* Prepare the input data (see section [[:Input]] )

* Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.

* Add a namelist art_nml and choose the namelist parameters for the ART setup as described in [[:Input]].

* Adapt the XML files for tracers, emi. The number of tracers related to a specific setup is equal to the number of possible prognostic output fields as described in [[:Input]].

* Add an output namelist as described in for the species you are interested in [[:Input]].

* Submit the job analogous to an ICON job.

Getting Started

2024-10-09T13:13:23Z

Editor 2: /* The auto-icon tool for automating runs */

== Requirements to run ICON-ART ==

As for most atmospheric models, it is strongly recommended to run ICON-ART on a High Performance Computing system such as Levante from the [https://www.dkrz.de/en DKRZ] or [https://www.scc.kit.edu/en/services/horeka.php HoreKA] from KIT. This usually requires an account which has to be obtained through the respective HPC Systems procedures.

== The auto-icon tool for automating runs ==
''auto-icon'' is a flexible tool for automating ICON(-ART) runs, starting from the retrieval of input data to post-processing and visualization. After an initial set-up, a great simplification in running various examples can be achieved. ''auto-icon'' takes care of obtaining the model code and installing it on the desired HPC system, retrieving parts of the input data (more to come) and running the model. Custom post-processing and visualization tasks can be added to the pipeline to get them executed automatically. The automation engine behind ''auto-icon'', called [https://autosubmit.readthedocs.io/en/master/ Autosubmit], is a powerful and flexible tool, providing multi-platform support, fault tolerance and an experiment database. The latter stores metadata for all conducted experiments and allows simple finding and reproduction of existing workflows, thus promoting the [http://www.go-fair.org/fair-principles/ FAIR] principles.

Especially if you are new to the ICON-ART model, ''auto-icon'' can help you set up a first run as it builds the model for you and has a bunch of example cases built in, running out of the box. These [https://www.icon-art.kit.edu/ ICON-ART standard cases] are included as templates along with a few other cases. There is a separate [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/home Wiki] for ''auto-icon'' with a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Shortest-guide-to-success shortest guide to success] and a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Step-by-step-guide more detailed guide].

The remainder of this Wiki serves as valuable source of information on how the ART module itself works, while the ''auto-icon'' Wiki only deals with technical aspects of ''auto-icon''.
Further, ''auto-icon'' does not use runscripts to conduct the runs but instead loads a configuration and a namelist describing the whole model workflow. The correspondence of runscript entries with the configuration is demonstrated in [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Transform-a-runscript-into-an-auto-icon-configuration this guide].

For starting your ICON model run with ''auto-icon'', you go to one of the linked guides and skip the remainder of this page.

== Getting the source code ==

The source code for ART is available in the open-source ICON repository under [http://www.icon-model.org www.icon-model.org]

To clone the ICON repository use :

<code>
git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git
</code>

This will get the ICON reository. To get the all submodules (including ART):

<code>
git submodule update --init
</code>

== Installation ==

ICON-ART is already included in the most recent ICON version. For Instructions on how to install ICON, please refer to the first chapter of the [https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html:official ICON Model Tutorial].
The only caveat is that during the configuration step the tag <code> --enable-art </code> has to be included. In addition, to set up and use chemical mechanisms using the MECCA/KPP the related interfaces have to be included using the tag <code> --enable-art —enable-art-gpl </code> (Be aware that you accept the GPL conditions for MECCA and KPP when you use this option).

<b>General step-by-step guide:</b>

* Navigate to your ICON main folder.
* Within this directory, you will find the 'config' folder.
* Inside the 'config' directory, there are several subfolders corresponding to different institutions.
* In each institutional folder, you will find configuration scripts tailored for various computers and compilers.

<b>Example for HoreKa at KIT:</b>
# Access your ICON main folder.
# Run the following command: <code>config/kit/hk.intel-2022-openmpi-4.0 --enable-art --enable-ecrad</code>
# Execute <code>make -j4</code>
# You should now have a functional binary with ART integration. For other HPC systems, substitute the config script with the one relevant to your HPC system.

== Creating a Runfile ==

* Go to <code>icon-kit/run/checksuite.icon-kit</code>

* Run bash-script <code>run_testsuite</code> via <code>./run_testsuite</code>

* The script creates the folder runscripts, which contains exemplary runfiles which are adapted to your HPC-System (if available in the config files). For the description of the runscripts see the table below.

* in <code>icon-kit/run/checksuites.icon-kit/Test-<current_date>.info</code> you will find a few informations to the ICON-ART Testsuite you just created, including your output directory when you perform the model runs in the next step

* To run your chosen runscript just execute from the console, e.g. by typing <code>runscripts/NWP_LIFETIME.run</code>

{| class="wikitable"
|-
! runscript !! description
|-
| NWP_OH_CHEMISTRY.run || Short example for simplified oh chemistry
|-
| NWP_GASPHASE.run || Example for MECCA chemistry based on https://gmd.copernicus.org/articles/11/4043/2018/
|-
| NWP_LIFETIME.run || Example for parameterized chemtracer chemistry including lifetime, simnoy, linoz and passive tracers, as well as regional tracers and PSCs
|-
| NWP_EXT_DATA.run || tbd
|-
| NWP_LIFETIME_lart.run || tbd
|-
| NATAERO_NORAD.run || tbd
|-
| VOLAERO_RAD.run || tbd
|}

== Running a Job ==

For a user who succeeded in running the ICON model, there are only a few steps to run the ART extension along with the ICON model. A description how to run the ICON model can be found in .

In order to run ICON-ART, one has to do the following steps:

* Make sure you have everything required for an ICON run

* Prepare the input data (see section [[:Input]] )

* Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.

* Add a namelist art_nml and choose the namelist parameters for the ART setup as described in [[:Input]].

* Adapt the XML files for tracers, emi. The number of tracers related to a specific setup is equal to the number of possible prognostic output fields as described in [[:Input]].

* Add an output namelist as described in for the species you are interested in [[:Input]].

* Submit the job analogous to an ICON job.

Getting Started

2024-06-17T11:00:57Z

Editor 2:

== Requirements to run ICON-ART ==

As for most atmospheric models, it is strongly recommended to run ICON-ART on a High Performance Computing system such as Levante from the [https://www.dkrz.de/en DKRZ] or [https://www.scc.kit.edu/en/services/horeka.php HoreKA] from KIT. This usually requires an account which has to be obtained through the respective HPC Systems procedures.

== The auto-icon tool for automating runs ==
auto-icon is a flexible tool for automating ICON(-ART) runs, starting from the retrieval of input data to post-processing and visualization. After an initial set-up, a great simplification in running various examples can be achieved. auto-icon takes care of obtaining the model code and installing it on the desired HPC system, retrieving parts of the input data (more to come) and running the model. Custom post-processing and visualization tasks can be added to the pipeline to get them executed automatically. The automation engine behind auto-icon, called [https://autosubmit.readthedocs.io/en/master/ Autosubmit], is a powerful and flexible tool, providing multi-platform support, fault tolerance and an experiment database. The latter stores metadata for all conducted experiments and allows simple finding and reproduction of existing workflows, thus promoting the [http://www.go-fair.org/fair-principles/ FAIR] principles.

The configurations for the ICON-ART standard cases (see below and [https://www.icon-art.kit.edu/userguide/index.php?title=Tutorial_Examples Tutorial examples]) are included as templates along with a few other cases. These run out of the box in just a few steps. There is a separate [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/home Wiki] for auto-icon with a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Shortest-guide-to-success shortest guide to success] and a [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Step-by-step-guide more detailed guide].

The remainder of this Wiki serves as valuable source of information on how ART works, while the auto-icon Wiki only deals with technical aspects of auto-icon.
Further, auto-icon does not use runscripts to conduct the runs but instead loads a configuration and a namelist describing the whole model workflow. The correspondence of runscript entries with the configuration is demonstrated in [https://gitlab.dkrz.de/auto-icon/auto-icon/-/wikis/Usage/Transform-a-runscript-into-an-auto-icon-configuration this guide].

You can choose between using auto-icon for your runs or the runscript approach. For the former, consult the linked pages, for the latter go on with the remainder of this page to get started.

== Getting the source code ==

The source code for ART is available in the open-source ICON repository under [http://www.icon-model.org www.icon-model.org]

To clone the ICON repository use :

<code>
git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git
</code>

This will get the ICON reository. To get the all submodules (including ART):

<code>
git submodule update --init
</code>

== Installation ==

ICON-ART is already included in the most recent ICON version. For Instructions on how to install ICON, please refer to the first chapter of the [https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html:official ICON Model Tutorial].
The only caveat is that during the configuration step the tag <code> --enable-art </code> has to be included. In addition, to set up and use chemical mechanisms using the MECCA/KPP the related interfaces have to be included using the tag <code> --enable-art —enable-art-gpl </code> (Be aware that you accept the GPL conditions for MECCA and KPP when you use this option).

<b>General step-by-step guide:</b>

* Navigate to your ICON main folder.
* Within this directory, you will find the 'config' folder.
* Inside the 'config' directory, there are several subfolders corresponding to different institutions.
* In each institutional folder, you will find configuration scripts tailored for various computers and compilers.

<b>Example for HoreKa at KIT:</b>
# Access your ICON main folder.
# Run the following command: <code>config/kit/hk.intel-2022-openmpi-4.0 --enable-art --enable-ecrad</code>
# Execute <code>make -j4</code>
# You should now have a functional binary with ART integration. For other HPC systems, substitute the config script with the one relevant to your HPC system.

== Creating a Runfile ==

* Go to <code>icon-kit/run/checksuite.icon-kit</code>

* Run bash-script <code>run_testsuite</code> via <code>./run_testsuite</code>

* The script creates the folder runscripts, which contains exemplary runfiles which are adapted to your HPC-System (if available in the config files). For the description of the runscripts see the table below.

* in <code>icon-kit/run/checksuites.icon-kit/Test-<current_date>.info</code> you will find a few informations to the ICON-ART Testsuite you just created, including your output directory when you perform the model runs in the next step

* To run your chosen runscript just execute from the console, e.g. by typing <code>runscripts/NWP_LIFETIME.run</code>

{| class="wikitable"
|-
! runscript !! description
|-
| NWP_OH_CHEMISTRY.run || Short example for simplified oh chemistry
|-
| NWP_GASPHASE.run || Example for MECCA chemistry based on https://gmd.copernicus.org/articles/11/4043/2018/
|-
| NWP_LIFETIME.run || Example for parameterized chemtracer chemistry including lifetime, simnoy, linoz and passive tracers, as well as regional tracers and PSCs
|-
| NWP_EXT_DATA.run || tbd
|-
| NWP_LIFETIME_lart.run || tbd
|-
| NATAERO_NORAD.run || tbd
|-
| VOLAERO_RAD.run || tbd
|}

== Running a Job ==

For a user who succeeded in running the ICON model, there are only a few steps to run the ART extension along with the ICON model. A description how to run the ICON model can be found in .

In order to run ICON-ART, one has to do the following steps:

* Make sure you have everything required for an ICON run

* Prepare the input data (see section [[:Input]] )

* Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.

* Add a namelist art_nml and choose the namelist parameters for the ART setup as described in [[:Input]].

* Adapt the XML files for tracers, emi. The number of tracers related to a specific setup is equal to the number of possible prognostic output fields as described in [[:Input]].

* Add an output namelist as described in for the species you are interested in [[:Input]].

* Submit the job analogous to an ICON job.

Postprocessing

2024-01-08T16:12:03Z

Editor 2: repaired Icontools link

== Output Checks with SAMOA ==

SAMOA performs a sanity check on all model outputs that can be read by CDO. It checks if a variable lies in-between a predefined range and if the minimum and maximum value of each variable are the same. For this purpose CDO version 1.6.2rc3 is required currently (see https://code.zmaw.de/projects/cdo).

For more information about the usage please refer to the README-file within the SAMOA package. You can get a copy of the SAMOA script by writing an e-mail to the contact person of the ART code (see http://icon-art.imk-tro.kit.edu). SAMOA is licensed under the GNU GENERAL PUBLIC LICENSE Version 3.

As SAMOA is primarily developed for the usage with COSMO-ART and COSMO-CLM, you have to do a minor change before using it. The latest version of SAMOA has a list for the usage of SAMOA with ICON-ART output included but not loaded automatically. This list is called samoa_list_icon-art. You have to replace the default (COSMO) list that is used by SAMOA by editing samoa.sh:

Search for the following lines:

<syntaxhighlight lang=bash># Path to the list with variables (is overwritten when -l specified)
# Assumed to be on the same path as script

path_list=$SCRIPTPATH/list </syntaxhighlight>
Change the name of the list to:

<syntaxhighlight lang=bash>path_list=$SCRIPTPATH/samoa_list_icon-art </syntaxhighlight>
Now you may use SAMOA with the ICON-ART output file out.nc with the following command:

<syntaxhighlight lang=bash>./samoa.sh out.nc</syntaxhighlight>
For all options see:

<syntaxhighlight lang=bash>./samoa.sh --help</syntaxhighlight>

== Data Processing ==
Some ways to handle and modify the outputs of ICON-ART are described here.

=== CDO ===
[https://code.mpimet.mpg.de/projects/cdo CDO] is a command line tool to interact with netCDF files, enabling to list the variables and do calculations efficiently.
Different examples for its usage can be found in the [https://code.mpimet.mpg.de/projects/cdo/wiki/FAQ CDO FAQ]
=== ICONTOOLS ===
[https://c2sm.github.io/tools/icontools.html ICONTOOLS] is a command line tool used to produce the required external parameters data of a simulation and is especially good at remapping data from one grid to another.

== Visualisation ==
There are many ways to visualize data produced by ICON-ART. In general, there are two possibilities: The output may exist on the ICON grid or it may exist on an interpolated longitude/latitude grid. This can be chosen by adaptions of the output namelist. Although it comes along with a loss in information, sometimes it is only possible to use interpolated output. By this, the visualization is much easier to handle.

In the following sections some tools are introduced which can be used to visualize ICON output. Note, that '''only NETCDF''' is supported by ICON-ART so far. With the tool Ncview it is very easy to have a quick look into the interpolated model output. With ParaView and Met3D a nice-looking three-dimensional visualization can be created. Python in the recent years has become the standard tool for 2D visualisation and its capabilities far exceed those of Ncview.

=== Ncview ===

"Ncview is a visual browser for netCDF format files. Typically you would use ncview to get a quick and easy, push-button look at your netCDF files. You can view simple movies of the data, view along various dimensions, take a look at the actual data values, change color maps, invert the data, etc." (http://meteora.ucsd.edu/~pierce/ncview_home_page.html)

Please note that Ncview does only work for latitude-longitude grid data and cannot be used for RXXBXX-style ICON grids without remapping.

=== Met3d ===

Met3D is a visualization software that can be used on a HPC system to visualize ICON as well as ICON-ART data in 3D. An online documentation can be found [https://met3d.wavestoweather.de/met-3d.html here]. Met3D needs remapped ICON fields to Latitude-Longitude . Furthermore, it is important to have the pressure (pres - variable) as model output, as Met3D transforms model levels in pressure levels for plotting.

=== ParaView ===

"ParaView is an open-source, multi-platform data analysis and visualization application. ParaView users can quickly build visualizations to analyze their data using qualitative and quantitative techniques. The data exploration can be done interactively in 3D or programmatically using ParaView’s batch processing capabilities.

ParaView was developed to analyze extremely large datasets using distributed memory computing resources. It can be run on supercomputers to analyze datasets of exascale size as well as on laptops for smaller data." (http://www.paraview.org/)

Paraview can be used for both Latitude-Longitude grids as well as RXXBXX-style ICON grids.

=== Python ===

On the [https://www.python.org/about/ official Website] Python describes itself as

<pre>Python is powerful... and fast;
plays well with others;
runs everywhere;
is friendly & easy to learn;
is Open.</pre>
Using Python is a simple but effective way to display ICON-ART model output data. There is a large number of Packages available to help with Visualisation, the most useful Packages for visualising ICON-ART data are given in this [[#tab:pythonpackages|Table]]

<div id="tab:pythonpackages">

{| class="wikitable" style="text-align:left;"
|+ Helpful Python Packages and their primary usage for Visualisation
|align="center"| numpy
|align="center"| predefined Mathematical functions
|-
|align="center"| matplotlib
|align="center"| Plotting framework
|-
|align="center"| xarray
|align="center"| reading in and processing netcdf datasets
|-
|align="center"| cartopy
|align="center"| Include country borders in plots
|-
|align="center"| ...
|align="center"|
|}

Python can be used for both Latitude-Longitude grids as well as RXXBXX-style ICON grids.
</div>

Simplified Chemistry

2023-10-26T11:15:48Z

Editor 2: fixed math display

- 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:
<chem>
[OH] =\frac{ 2 [O(^1D)] k_{H2O} [H2O] } { k_{CH4} [CH4] + k_{CO,1} [CO] + k_{CO,2} [CO]},
</chem>

with
<math>
[O(^1D)] = \frac{ J_{O3} [O3]}{k_{O2}[O2]+k_{N2}[N2]+k_{H2O}[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)
<syntaxhighlight line lang=bash 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}
#
#-----------------------------------------------------------------------------
</syntaxhighlight>
</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)
<syntaxhighlight line lang=bash 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"
</syntaxhighlight>
</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)
<syntaxhighlight line lang=bash 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.
/
</syntaxhighlight>
</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)
<syntaxhighlight line lang=bash 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
</syntaxhighlight>
</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)
<syntaxhighlight line lang=bash 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
</syntaxhighlight>
</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
<syntaxhighlight line lang=bash 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
</syntaxhighlight>
</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)
<syntaxhighlight line lang=xml 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>
</syntaxhighlight>
</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-10-26T10:45:43Z

Editor 2: fixed math display

- 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} \overline{\rho} \hat{\Psi}_{l})- \nabla \cdot (\overline{\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\overline{(\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)
<syntaxhighlight lang=bash line 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}
#
#-----------------------------------------------------------------------------
</syntaxhighlight>
</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)
<syntaxhighlight lang=bash line 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"
</syntaxhihlight>
</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)
<syntaxhighlight lang=bash line 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.
/
</syntaxhighlight>
</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)
<syntaxhighlight lang=bash line 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
</syntaxhighlight>
</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)
<syntaxhighlight lang=bash line 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
</syntaxhighlight>
</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
<syntaxhighlight lang=bash line 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
</syntaxhighlight>
</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
<syntaxhighlight lang=xml line 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>
</syntaxhighlight>
</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)
<syntaxhighlight lang=xml line 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>
</syntaxhighlight>
</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.

Atmospheric Chemistry

2023-10-26T08:51:22Z

Editor 2: fixed math display

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{dc_i}{dt} = P_i - \frac{c_i}{\tau_i}</math>

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

Simulating a Point Source

2023-10-26T08:18:38Z

Editor 2: Some minor changes

In this tutorial, the steps to simulate a volcanic eruption via a point source are given.

[[File:Pointsource.gif]]
== Setting up ICON-ART ==

The first thing to do is having a working installation of ICON-ART. To check if your icon version has been built correctly, you can check if
your_icon_folder/bin/icon.exe
exists.

== Setting up Directories ==

Now a directory structure has to be set up. Usually the following directories are used:
* '''Working Directory''': Here the files that are needed for an individual run are saved. This usually includes the runscript and the relevant .xml files.
* '''Icon Code directory''': This is where the Icon code is stored.
* '''External Data directory''': Here external files which are needed for a run are stored. For example, to parametrize the optical properties of clouds a files like ECHAM6_CldOptProps.nc is used. These files of course can be switched out for others, however in most applications the same ones are used. A list of the used files is given in the runscript, which then creates a link of these files in the output directory.
* '''Output directory''': This is where the new simulation data will be stored. Since most of the time large amounts of data are produced, this is stored in the work or scratch partitions on most HPC systems. The namelists produced by the runfile are also stored here.

== Setting up the Runscript ==

The function of the runscript is to set up the directory structure, link the relevant files and create the namelists, which are grouped into several namelist files.

== Setting up the .xml's ==
Here the .xml
pntSRC.xml
is set up. It contains all the necessary information to describe the emission of the here defined aerosols into the atmosphere.
The following information is contained:
* where is the Pointsource
* when is it emitting
* what substances are emitted
* how much of each substance is emitted
* what size are the emitted substances (median and standard deviation)

This can be adapted as needed.

In this example the Raikoke eruption on 21 of June 2019 is simulated, as can be seen in the following .xml:

<syntaxhighlight line lang=xml class="mw-collapsible-content">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "sources_selTrnsp.dtd">

<sources>
<pntSrc id="Raikoke-SO2">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">TRSO2</substance>
<source_strength type="real">46300.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashacc">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_acc</substance>
<dg3_emiss type="real">0.8E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashcoa">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_coa</substance>
<dg3_emiss type="real">2.98E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashgiant">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_giant</substance>
<dg3_emiss type="real">11.35E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
</sources>
</syntaxhighlight>

== Running the Simulation ==
The setup of the model for the simulation happens with a runscript. It contains all the different control parameters, such as time control of the simulation, what equations are going to be used, whether ART is active, and a lot more.
The runscript itself is just a text file, which is run via bash to start the simulation. Usually a template file is used and adapted to the specific needs of the user running the simulation.
Here we will go through the runscript for our pointsource simulation.

The first step is to set the relevant directories, so that the XML data we provide as well as the path to the ICON model can be found and accessed easily.
In this simulation, external data such as a grid containing external parameter data is required. The directory containing the data is set as DATADIR.
The output directory is where the model will write the output NetCDF files into, as well as linking a lot of relevant files used in the simulation.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
# working directory
export XMLDIR=/your/path/to/Training2023/Volcano

# datadir2 --> do not change
export DATADIR=/your/path/to/DATA_Volcano

# output directory
export OUTDIR=/your/path/to/Volcano_externally

# Code directory
export ICONDIR=/your/path/to/icon-kit
export ARTDIR=${ICONDIR}/externals/art

</syntaxhighlight>

In the next step, the previously defined output directory is created, if not already there, and the icon executable is linked into it for easier access and overview.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

# copy icon binary to OUTDIR
cp ${ICONDIR}/bin/icon icon.exe
</syntaxhighlight>

Now, the external parameters and chemistry files are linked into the output directory, so that ICON and the user can find it in the output directory
<syntaxhighlight line lang=bash class="mw-collapsible-content">
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G.nc ${OUTDIR}/iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G-grfinfo.nc ${OUTDIR}/iconR2B06-DOM01-grfinfo.nc
ln -sf ${DATADIR}/icon_extpar_0024_R02B06_G_20200917_tiles.nc ${OUTDIR}/extpar_iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_init_0024_R02B06_2019062112.nc ${OUTDIR}/igfff00000000

ln -sf ${ICONDIR}/data/rrtmg_lw.nc ${OUTDIR}/rrtmg_lw.nc
ln -sf ${ICONDIR}/data/ECHAM6_CldOptProps.nc ${OUTDIR}/ECHAM6_CldOptProps.nc

# Dictionary for the mapping: DWD GRIB2 names <-> ICON internal names
ln -sf ${ICONDIR}/run/ana_varnames_map_file.txt ${OUTDIR}/map_file.ana

## chemistry
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat

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

</syntaxhighlight>

In the next step, namelist files are created. They contain the individual namelists which control the settings of the different modules of icon. They are written into the output directory and read by icon during a run.
First the master namelist is created, which most importantly contains the start and stop date, as well as the possibility to restart a run.
The next namelist file created is called "NAMELIST_Raikoke-June-2019". Here a lot of the model setup is taking place. It is subdivided into different namelists, which all do their part to set up a different part of the model.
Some important namelists for this simulation are:
* grid_nml (line 35): Here the grid on which the simulation is taking place is given
* run_nml (line 49): Contains the switch to turn on ICON-ART, as well as set model height levels and timestep length.
* output_nml (line 225): Defines which variables at which intervals are written in the output directory
* art_nml (line 238): Contains the switches relevant for ICON-ART, see [[Namelist]] for more details. Most importantly, the xml file for the point source emission is linked here

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cd $OUTDIR
cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "2019-06-21T12:00:00"
forecastLeadTime = "P1D"
checkpointTimeIntval = "P10D"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="NAMELIST_Raikoke-June-2019"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
&time_nml
ini_datetime_string = "2019-06-21T12:00:00"
dt_restart = 864000 ! 10 days
/
EOF

cat > NAMELIST_Raikoke-June-2019 << 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 = 1 ! 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 = 'iconR2B06-DOM01.nc'
dynamics_parent_grid_id = 0
lredgrid_phys = .false.
/
&initicon_nml
init_mode = 7 ! 2: IFS; 7: Initialized DWD Analysis
lread_ana = .FALSE. ! no analysis data will be read
dwdfg_filename = "igfff00000000" ! initial data filename
filetype = 4
ana_varnames_map_file = "map_file.ana" ! dictionary mapping internal names onto GRIB2 shortNames
ltile_coldstart = .TRUE. ! coldstart for surface tiles
ltile_init = .FALSE. ! set it to .TRUE. if FG data originate from run without tiles
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
!nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
dtime = 180 ! timestep in seconds
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 = 15 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = .true.
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 4
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 = 3600 ! 7200.
itype_z0 = 2
icpl_aero_conv = 0 ! check meaning -> default 0 - off
icpl_aero_gscp = 0 ! check meaning -> default 0 - off
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
mu_rain = 0.5
rain_n0_factor = 0.1
lshallowconv_only = .true.
lgrayzone_deepconv = .false.
/
&nwp_tuning_nml
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
tune_gkdrag = 0.09
tune_gkwake = 1.8
tune_gfrcrit = 0.333
tune_dust_abs = 1.
tune_zvz0i = 1.1
tune_box_liq_asy = 4.0
tune_gust_factor = 7.0
tune_rcucov = 0.075
tune_rhebc_land = 0.825
tune_zvz0i = 0.85
icpl_turb_clc = 2
max_calibfac_clcl = 2.0
tune_box_liq = 0.04
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! "
pat_len = 750. ! 750 in exp.nh_oper
c_diff = 0.2
rat_sea = 0.8 ! ** new value since for v2.0.15; previously 8.0 ** ! ** 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:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
alpha1 = 0.125
icldm_turb = 1 ! found in exp.nh_oper ** new recommendation for v2.0.15 in conjunction with evaporation fix for grid-scale rain **
rlam_heat = 10.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .false. !!! .false. for assimilation cycle and forecast
itype_heatcond = 3
idiag_snowfrac = 20
lsnowtile = .true. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .true.
lprog_albsi = .true.
itype_lndtbl = 4 ! minimizes moist/cold bias in lower tropical troposphere
itype_evsl = 4
itype_root = 2
itype_trvg = 3
cwimax_ml = 5.e-4
c_soil = 1.25
c_soil_urb = 0.5
sstice_mode = 2
/
&radiation_nml
irad_o3 = 7
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
direct_albedo_water = 3
albedo_whitecap = 1
ecrad_data_path = "${ICONDIR}/externals/ecrad/data"
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 44000.
rayleigh_coeff = 1
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, must be at least as large as htop_moist_proc
htop_aero_proc = 25000. !height limit for aerosol tracer processes
/
&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
ivadv_tracer = 3,3,3,3,3,3,3,3,3,3,3
itype_hlimit = 3,4,4,4,4,3,3,3,3,3,3
ihadv_tracer = 52,2,2,2,2,22,22,22,22,22,22
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.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
hgtdiff_max_smooth_topo = 750., ! found in exp.nh_oper ** should be changed to 750.,750 with next Extpar update! **
itype_lwemiss = 2
/
&io_nml
itype_pres_msl = 5 ! 5: new DWD method; 4: IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
mode = 1 ! 1 = forecast mode with TAXIS_RELATIVE, works only with output in multiples of 1h; 2 = climate mode, default, TAXIS_ABSOLUTE
output_bounds = 0., 691200., 600. ! start, end, increment
steps_per_file = 1
include_last = .TRUE.
output_filename = 'Raikoke-June-2019-forecast_mode-remap' ! file name base
ml_varlist = 'TRSO2_chemtr','TRH2SO4_chemtr','group:ART_AEROSOL','rho','pres','temp', 'z_mc','z_ifc'
remap = 1
reg_lon_def = 120.,0.1,280.
reg_lat_def = 85.,-0.1, 30.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .TRUE.
lart_pntSrc = .TRUE.
lart_chem = .TRUE.
lart_chemtracer = .TRUE.
iart_ari = 0

cart_aerosol_xml = '${XMLDIR}/Ex01_aerotracer.xml'
cart_modes_xml = '${XMLDIR}/Ex01_modes.xml'
cart_pntSrc_xml = '${XMLDIR}/Ex01_pntSrc.xml'
cart_chemtracer_xml = '${XMLDIR}/Ex01_chemtracer.xml'
/
EOF
</syntaxhighlight>

With the namelists set, we can now prepare the simulation for running. Since a lot of setup is required for running, this is also prepared within the runscript and then later executed. The following part is highly dependant on the HPC system configuration. The following setup works on the DKRZ Levante HPC system (July 2023):

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cat > ${OUTDIR}/job_ICON << ENDFILE
#!/bin/bash
#SBATCH --job-name=EXP01_ART # Specify job name
#SBATCH --partition=compute # Specify partition name
#SBATCH --nodes=4 # Specify number of nodes
#SBATCH --ntasks-per-node=128 # Specify number of (MPI) tasks on each node
#SBATCH --time=01:00:00 # Set a limit on the total run time
#SBATCH --mail-type=FAIL # Notify user by email in case of job failure
#SBATCH --mail-user=example@mail.com # Set your e-mail address
#SBATCH --account=your_project_account # Charge resources on this project account

module load gcc
module load intel-oneapi-compilers/2022.0.1-gcc-11.2.0
module load intel-oneapi-mkl/2022.0.1-gcc-11.2.0
module load openmpi/4.1.2-intel-2021.5.0
module load netcdf-c/4.8.1-openmpi-4.1.2-intel-2021.5.0
module load netcdf-fortran/4.5.3-openmpi-4.1.2-intel-2021.5.0
module load parallel-netcdf/1.12.2-openmpi-4.1.2-intel-2021.5.0
module load hdf5/1.12.1-openmpi-4.1.2-intel-2021.5.0
module load eccodes/2.21.0-intel-2021.5.0

unset SLURM_EXPORT_ENV
unset SLURM_MEM_PER_NODE
unset SBATCH_EXPORT

export LD_LIBRARY_PATH="/usr/lib:/usr/lib64:/sw/spack-levante/netcdf-c-4.8.1-2k3cmu/lib:/sw/spack-levante/netcdf-fortran-4.5.3-k6xq5g/lib:/sw/spack-levante/hdf5-1.12.1-tvymb5/lib:/sw/spack-levante/eccodes-2.21.0-3ehkbb/lib64:/sw/spack-levante/intel-oneapi-mkl-2022.0.1-ttdktf/mkl/2022.0.1/lib/intel64/"

export OMPI_MCA_pml="ucx"
export OMPI_MCA_btl=self
export OMPI_MCA_osc="pt2pt"
export UCX_IB_ADDR_TYPE=ib_global

export OMPI_MCA_coll="^ml,hcoll"
export OMPI_MCA_coll_hcoll_enable="0"
export HCOLL_ENABLE_MCAST_ALL="0"
export HCOLL_MAIN_IB=mlx5_0:1
export UCX_NET_DEVICES=mlx5_0:1
export UCX_TLS=mm,knem,cma,dc_mlx5,dc_x,self
export UCX_UNIFIED_MODE=y
export HDF5_USE_FILE_LOCKING=FALSE
export OMPI_MCA_io="romio321"
export UCX_HANDLE_ERRORS=bt

ulimit -s 102400
ulimit -c 0

srun -l --cpu_bind=cores --distribution=block:cyclic --propagate=STACK,CORE ./icon.exe

ENDFILE
</syntaxhighlight>
This concludes the runfile.
The Job_ICON-file that has been produced in the last step can then be executed. For that, the runfile hast to be run using bash:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ chmod +x myrunfile
$ ./myrunfile
</syntaxhighlight>
This will then create all the Namelist files and the runscript job_ICON. To submit the icon run, go to the output directory, make the runscript executable, and run it:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cd /path/to/your/output
$ chmod +x job_ICON
$ sbatch job_ICON
</syntaxhighlight>
Now the Job should be submitted. The submission status can be seen with
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ squeue --user your_username
</syntaxhighlight>

If everything went well, in the output directory there will be output files generated with names like Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
== Inspecting the Output ==
In this example, the output is created in the form of several NetCDF4 (.nc) files. To avoid having one giant file, it is subdivided into several files containing a fixed amount of timesteps. The quickest way to inspect a NetCDF file is with [https://code.mpimet.mpg.de/projects/cdo CDO]:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cdo sinfo Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
</syntaxhighlight>
This way it is possible to obtain information about the variables, grid parameters and timesteps of the simulation. To actually see the values of a specific variable, tools like ncdump can be used, however in many cases this is not practical, since the amount of single values is way too large to look at individual data points.

== Making a Plot of the Simulation Data ==
In order to gain insight into the simulation, as well as an overview, the most common way is to create some plots of different variables of interest. In our case, we want to know what happens to the ash emitted from the Raikoke eruption.
A quick and easy way to create plots is using python and a reference script to produce a plot similar to the Pointsource animation is given here:
<syntaxhighlight line lang=python class="mw-collapsible-content">
# first we import the following packages:
import numpy as np # general utility for trigonomic functions and arrays
import matplotlib.pyplot as plt # Library to produce Plots
import xarray as xr # reading in of netCDF data, optimized for large datasets
from glob import glob
import cartopy.crs as ccrs # plotting things on a map

#Next step: read in the Netcdf Files

#datadir_externally = 'path/to/your/output/Training2023/Volcano_externally/'
files_externally = glob(datadir_externally+'Raikoke-June-2019-forecast_mode-remap_DOM01_ML*')
files_externally.sort()

#Next step: Calculate relevant data to be displayed
# get model level height
def get_dz(ds):
dz = -1 * ds.z_ifc.diff('height_2')
dz = dz.rename({'height_2':'height'})
dz = dz.assign_coords(height=(dz.height - 1))
return dz

# Calculate column integrated tracer mass (tracer load)
def tracer_load(tr,rho,dz):
m_tr = tr * rho * dz
m_tr = m_tr.sum('height')
m_tr = m_tr.squeeze()
return m_tr

#
MM_SO2 = 64/28.96 # molar weight of SO2 / dry air

# set the timestep you want to plot
# in this simulation there are 144 timesteps and 144 files each containing one timestep
# To produce a plot for each timestep, you can also loop the rest of this file over i
i = 30

#load the NetCDF file containing the timestep
ds = xr.open_dataset(files_externally[i],autoclose=True)

#calculate Heightlevels
dz = get_dz(ds)

# Read in SO2 Column
SO2 = tracer_load(ds.TRSO2_chemtr.values*MM_SO2,ds.rho,dz)

# set colorbar levels
color_so2 = np.linspace(1e-5, 0.02, 11,endpoint=True)

# Plot SO2 column
# set the size of the figure and the background color to white
fig = plt.figure(figsize=(8,6),facecolor='w')

# Set the axes using the specified map projection
ax=plt.axes(projection=ccrs.NearsidePerspective(central_longitude=180, central_latitude=49.29,satellite_height=35785831/5, globe=None))
ax.stock_img() #add a stock image as background
ax.coastlines() # add coastlines
ax.set_title(str(ds.time.values)[2:12]+" "+str(ds.time.values)[13:18]) #set title to the current time displayed
ax.gridlines(draw_labels=False, dms=False, x_inline=True, y_inline=True) #add lat lon gridlines

# Make a filled contour plot
plot1=ax.contourf(ds.lon, ds.lat, SO2, levels=color_so2, cmap='plasma',
transform = ccrs.PlateCarree())
kwargs = {'format': '%.3f'}
cbar = plt.colorbar(plot1,location='right',ticks=color_so2,**kwargs)
cbar.set_label('SO2 Column Mass (kg m-2)')

#save the plot at a path of your choice

#plt.savefig("path/to/your/Plots/folder/SO2_{:03d}.png".format(i))
plt.close(fig)

</syntaxhighlight>
To run the script, you need a working python version and the packages listed in the beginning of the script. Dont forget to make the file executable in order to run it using <code> chmod +x plotscript </code>.
The resulting Plot will look something like this: [[File:Example SO2 130.png]]

Simulating a Point Source

2023-10-18T08:13:03Z

Editor 2: fixed some typos and wording, added plot for pythonscripts and instructions how to run it

In this tutorial, the steps to simulate a volcanic eruption via a point source are given.
<gallery mode="slideshow">
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019.
</gallery>
== Setting up ICON-ART ==

The first thing to do is having a working installation of ICON-ART. To check if your icon version has been built correctly, you can check if
your_icon_folder/bin/icon.exe
exists.

== Setting up Directories ==

Now a directory structure has to be set up. Usually the following directories are used:
* '''Working Directory''': Here the files that are needed for an individual run are saved. This usually includes the runscript and the relevant .xml files.
* '''Icon Code directory''': This is where the Icon code is stored.
* '''External Data directory''': Here external files which are needed for a run are stored. For example, to parametrize the optical properties of clouds a files like ECHAM6_CldOptProps.nc is used. These files of course can be switched out for others, however in most applications the same ones are used. A list of the used files is given in the runscript, which then creates a link of these files in the output directory.
* '''Output directory''': This is where the new simulation data will be stored. Since most of the time large amounts of data are produced, this is stored in the work or scratch partitions on most HPC systems. The namelists produced by the runfile are also stored here.

== Setting up the Runscript ==

The function of the runscript is to set up the directory structure,link the relevant files and create the namelists.

== Setting up the .xml's ==
Here the .xml
pntSRC.xml
is set up. It contains all the necessary information to describe the emission of the here defined aerosols into the atmosphere.
The following information is contained:
* where is the Pointsource
* when is it emitting
* what substances are emitted
* how much of each substance is emitted
* what size are the emitted substances (median and standard deviation)

This can be adapted as needed.

In this example the Raikoke eruption on 21 of June 2019 is simulated, as can be seen in the following .xml:

<syntaxhighlight line lang=xml class="mw-collapsible-content">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "sources_selTrnsp.dtd">

<sources>
<pntSrc id="Raikoke-SO2">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">TRSO2</substance>
<source_strength type="real">46300.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashacc">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_acc</substance>
<dg3_emiss type="real">0.8E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashcoa">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_coa</substance>
<dg3_emiss type="real">2.98E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashgiant">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_giant</substance>
<dg3_emiss type="real">11.35E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
</sources>
</syntaxhighlight>

== Running the Simulation ==
The setup of the model for the simulation happens with a runscript. It contains all the different control parameters, such as time control of the simulation, what equations are going to be used, whether ART is active, and a lot more.
The runscript itself is just a text file, which is run via bash to start the simulation. Usually a template file is used and adapted to the specific needs of the user running the simulation.
Here we will go through the runscript for our pointsource simulation.

The first step is to set the relevant directories, so that the XML data we provide as well as the path to the ICON model can be found and accessed easily.
In this simulation, external data such as a grid containing external parameter data is required. The directory containing the data is set as DATADIR.
The output directory is where the model will write the output NetCDF files into, as well as linking a lot of relevant files used in the simulation.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
# working directory
export XMLDIR=/your/path/to/Training2023/Volcano

# datadir2 --> do not change
export DATADIR=/your/path/to/DATA_Volcano

# output directory
export OUTDIR=/your/path/to/Volcano_externally

# Code directory
export ICONDIR=/your/path/to/icon-kit
export ARTDIR=${ICONDIR}/externals/art

</syntaxhighlight>

In the next step, the previously defined output directory is created, if not already there, and the icon executable is linked into it for easier access and overview.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

# copy icon binary to OUTDIR
cp ${ICONDIR}/bin/icon icon.exe
</syntaxhighlight>

Now, the external parameters and chemistry files are linked into the output directory, so that after running the simulation it can be identified which run specific settings have been used.
<syntaxhighlight line lang=bash class="mw-collapsible-content">
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G.nc ${OUTDIR}/iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G-grfinfo.nc ${OUTDIR}/iconR2B06-DOM01-grfinfo.nc
ln -sf ${DATADIR}/icon_extpar_0024_R02B06_G_20200917_tiles.nc ${OUTDIR}/extpar_iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_init_0024_R02B06_2019062112.nc ${OUTDIR}/igfff00000000

ln -sf ${ICONDIR}/data/rrtmg_lw.nc ${OUTDIR}/rrtmg_lw.nc
ln -sf ${ICONDIR}/data/ECHAM6_CldOptProps.nc ${OUTDIR}/ECHAM6_CldOptProps.nc

# Dictionary for the mapping: DWD GRIB2 names <-> ICON internal names
ln -sf ${ICONDIR}/run/ana_varnames_map_file.txt ${OUTDIR}/map_file.ana

## chemistry
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat

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

</syntaxhighlight>

In the next step, namelist files are created. They contain the individual namelists which control the settings of the different modules of icon. They are written into the output directory and read by icon during a run.
First the master namelist is created, which most importantly contains the start and stop date, as well as the possibility to restart a run.
The next namelist created is called "NAMELIST_Raikoke-June-2019". Here a lot of the model setup is taking place. It is subdivided into different smaller namelist parts, which all do their part to set up a different part of the model.
Some important namelists for this simulation are:
* grid_nml (line 35): Here the grid on which the simulation is taking place is given
* run_nml (line 49): Contains the switch to turn on ICON-ART, as well as set model height levels and timestep length.
* output_nml (line 225): Defines which variables at which intervals are written in the output directory
* art_nml (line 238): Contains the switches relevant for ICON-ART, see [[Namelist]] for more details. Most importantly, the xml file for the point source emission is linked here

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cd $OUTDIR
cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "2019-06-21T12:00:00"
forecastLeadTime = "P1D"
checkpointTimeIntval = "P10D"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="NAMELIST_Raikoke-June-2019"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
&time_nml
ini_datetime_string = "2019-06-21T12:00:00"
dt_restart = 864000 ! 10 days
/
EOF

cat > NAMELIST_Raikoke-June-2019 << 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 = 1 ! 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 = 'iconR2B06-DOM01.nc'
dynamics_parent_grid_id = 0
lredgrid_phys = .false.
/
&initicon_nml
init_mode = 7 ! 2: IFS; 7: Initialized DWD Analysis
lread_ana = .FALSE. ! no analysis data will be read
dwdfg_filename = "igfff00000000" ! initial data filename
filetype = 4
ana_varnames_map_file = "map_file.ana" ! dictionary mapping internal names onto GRIB2 shortNames
ltile_coldstart = .TRUE. ! coldstart for surface tiles
ltile_init = .FALSE. ! set it to .TRUE. if FG data originate from run without tiles
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
!nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
dtime = 180 ! timestep in seconds
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 = 15 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = .true.
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 4
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 = 3600 ! 7200.
itype_z0 = 2
icpl_aero_conv = 0 ! check meaning -> default 0 - off
icpl_aero_gscp = 0 ! check meaning -> default 0 - off
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
mu_rain = 0.5
rain_n0_factor = 0.1
lshallowconv_only = .true.
lgrayzone_deepconv = .false.
/
&nwp_tuning_nml
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
tune_gkdrag = 0.09
tune_gkwake = 1.8
tune_gfrcrit = 0.333
tune_dust_abs = 1.
tune_zvz0i = 1.1
tune_box_liq_asy = 4.0
tune_gust_factor = 7.0
tune_rcucov = 0.075
tune_rhebc_land = 0.825
tune_zvz0i = 0.85
icpl_turb_clc = 2
max_calibfac_clcl = 2.0
tune_box_liq = 0.04
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! "
pat_len = 750. ! 750 in exp.nh_oper
c_diff = 0.2
rat_sea = 0.8 ! ** new value since for v2.0.15; previously 8.0 ** ! ** 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:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
alpha1 = 0.125
icldm_turb = 1 ! found in exp.nh_oper ** new recommendation for v2.0.15 in conjunction with evaporation fix for grid-scale rain **
rlam_heat = 10.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .false. !!! .false. for assimilation cycle and forecast
itype_heatcond = 3
idiag_snowfrac = 20
lsnowtile = .true. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .true.
lprog_albsi = .true.
itype_lndtbl = 4 ! minimizes moist/cold bias in lower tropical troposphere
itype_evsl = 4
itype_root = 2
itype_trvg = 3
cwimax_ml = 5.e-4
c_soil = 1.25
c_soil_urb = 0.5
sstice_mode = 2
/
&radiation_nml
irad_o3 = 7
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
direct_albedo_water = 3
albedo_whitecap = 1
ecrad_data_path = "${ICONDIR}/externals/ecrad/data"
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 44000.
rayleigh_coeff = 1
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, must be at least as large as htop_moist_proc
htop_aero_proc = 25000. !height limit for aerosol tracer processes
/
&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
ivadv_tracer = 3,3,3,3,3,3,3,3,3,3,3
itype_hlimit = 3,4,4,4,4,3,3,3,3,3,3
ihadv_tracer = 52,2,2,2,2,22,22,22,22,22,22
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.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
hgtdiff_max_smooth_topo = 750., ! found in exp.nh_oper ** should be changed to 750.,750 with next Extpar update! **
itype_lwemiss = 2
/
&io_nml
itype_pres_msl = 5 ! 5: new DWD method; 4: IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
mode = 1 ! 1 = forecast mode with TAXIS_RELATIVE, works only with output in multiples of 1h; 2 = climate mode, default, TAXIS_ABSOLUTE
output_bounds = 0., 691200., 600. ! start, end, increment
steps_per_file = 1
include_last = .TRUE.
output_filename = 'Raikoke-June-2019-forecast_mode-remap' ! file name base
ml_varlist = 'TRSO2_chemtr','TRH2SO4_chemtr','group:ART_AEROSOL','rho','pres','temp', 'z_mc','z_ifc'
remap = 1
reg_lon_def = 120.,0.1,280.
reg_lat_def = 85.,-0.1, 30.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .TRUE.
lart_pntSrc = .TRUE.
lart_chem = .TRUE.
lart_chemtracer = .TRUE.
iart_ari = 0

cart_aerosol_xml = '${XMLDIR}/Ex01_aerotracer.xml'
cart_modes_xml = '${XMLDIR}/Ex01_modes.xml'
cart_pntSrc_xml = '${XMLDIR}/Ex01_pntSrc.xml'
cart_chemtracer_xml = '${XMLDIR}/Ex01_chemtracer.xml'
/
EOF
</syntaxhighlight>

With the namelists set, we can now prepare the simulation for running. Since a lot of setup is required for running, this is also prepared within the runscript and then later executed. The following part is highly dependant on the HPC system configuration. The following setup works on the DKRZ Levante HPC system:

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cat > ${OUTDIR}/job_ICON << ENDFILE
#!/bin/bash
#SBATCH --job-name=EXP01_ART # Specify job name
#SBATCH --partition=compute # Specify partition name
#SBATCH --nodes=4 # Specify number of nodes
#SBATCH --ntasks-per-node=128 # Specify number of (MPI) tasks on each node
#SBATCH --time=01:00:00 # Set a limit on the total run time
#SBATCH --mail-type=FAIL # Notify user by email in case of job failure
#SBATCH --mail-user=example@mail.com # Set your e-mail address
#SBATCH --account=your_project_account # Charge resources on this project account

module load gcc
module load intel-oneapi-compilers/2022.0.1-gcc-11.2.0
module load intel-oneapi-mkl/2022.0.1-gcc-11.2.0
module load openmpi/4.1.2-intel-2021.5.0
module load netcdf-c/4.8.1-openmpi-4.1.2-intel-2021.5.0
module load netcdf-fortran/4.5.3-openmpi-4.1.2-intel-2021.5.0
module load parallel-netcdf/1.12.2-openmpi-4.1.2-intel-2021.5.0
module load hdf5/1.12.1-openmpi-4.1.2-intel-2021.5.0
module load eccodes/2.21.0-intel-2021.5.0

unset SLURM_EXPORT_ENV
unset SLURM_MEM_PER_NODE
unset SBATCH_EXPORT

export LD_LIBRARY_PATH="/usr/lib:/usr/lib64:/sw/spack-levante/netcdf-c-4.8.1-2k3cmu/lib:/sw/spack-levante/netcdf-fortran-4.5.3-k6xq5g/lib:/sw/spack-levante/hdf5-1.12.1-tvymb5/lib:/sw/spack-levante/eccodes-2.21.0-3ehkbb/lib64:/sw/spack-levante/intel-oneapi-mkl-2022.0.1-ttdktf/mkl/2022.0.1/lib/intel64/"

export OMPI_MCA_pml="ucx"
export OMPI_MCA_btl=self
export OMPI_MCA_osc="pt2pt"
export UCX_IB_ADDR_TYPE=ib_global

export OMPI_MCA_coll="^ml,hcoll"
export OMPI_MCA_coll_hcoll_enable="0"
export HCOLL_ENABLE_MCAST_ALL="0"
export HCOLL_MAIN_IB=mlx5_0:1
export UCX_NET_DEVICES=mlx5_0:1
export UCX_TLS=mm,knem,cma,dc_mlx5,dc_x,self
export UCX_UNIFIED_MODE=y
export HDF5_USE_FILE_LOCKING=FALSE
export OMPI_MCA_io="romio321"
export UCX_HANDLE_ERRORS=bt

ulimit -s 102400
ulimit -c 0

srun -l --cpu_bind=cores --distribution=block:cyclic --propagate=STACK,CORE ./icon.exe

ENDFILE
</syntaxhighlight>
This concludes the runfile.
The Job_ICON-file that has been produced in the last step can then be executed. For that, the runfile hast to be run using bash:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ chmod +x myrunfile
$ ./myrunfile
</syntaxhighlight>
This will then create all the Namelists and the runscript job_ICON. To submit the icon run, go to the output directory, make the runscript executable, and run it:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cd /path/to/your/output
$ chmod +x job_ICON
$ sbatch job_ICON
</syntaxhighlight>
Now the Job should be submitted. The submission status can be seen with
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ squeue --user your_username
</syntaxhighlight>

If everything went well, in the output directory there will be output files generated with names like Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
== Inspecting the Output ==
In this example, the output is created in the form of several NetCDF4 (.nc) files. To avoid having one giant file, it is subdivided into several files containing a fixed amount of timesteps. The quickest way to inspect a NetCDF file is with [https://code.mpimet.mpg.de/projects/cdo CDO]:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cdo sinfo Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
</syntaxhighlight>
This way it is possible to obtain information about the variables, grid parameters and timesteps of the simulation. To actually see the values of a specific variable, tools like ncdump can be used, however in many cases this is not practical, since the amount of single values is way too large to look at individual data points.

== Making a Plot of the Simulation Data ==
In order to gain insight into the simulation, as well as an overview, the most common way is to create some plots of different variables of interest. In our case, we want to know what happens to the ash emitted from the Raikoke eruption.
A quick and easy way to create plots is using python and a reference script to produce a plot similar to the Pointsource animation is given here:
<syntaxhighlight line lang=python class="mw-collapsible-content">
# first we import the following packages:
import numpy as np # general utility for trigonomic functions and arrays
import matplotlib.pyplot as plt # Library to produce Plots
import xarray as xr # reading in of netCDF data, optimized for large datasets
from glob import glob
import cartopy.crs as ccrs # plotting things on a map

#Next step: read in the Netcdf Files

#datadir_externally = 'path/to/your/output/Training2023/Volcano_externally/'
files_externally = glob(datadir_externally+'Raikoke-June-2019-forecast_mode-remap_DOM01_ML*')
files_externally.sort()

#Next step: Calculate relevant data to be displayed
# get model level height
def get_dz(ds):
dz = -1 * ds.z_ifc.diff('height_2')
dz = dz.rename({'height_2':'height'})
dz = dz.assign_coords(height=(dz.height - 1))
return dz

# Calculate column integrated tracer mass (tracer load)
def tracer_load(tr,rho,dz):
m_tr = tr * rho * dz
m_tr = m_tr.sum('height')
m_tr = m_tr.squeeze()
return m_tr

#
MM_SO2 = 64/28.96 # molar weight of SO2 / dry air

# set the timestep you want to plot
# in this simulation there are 144 timesteps and 144 files each containing one timestep
# To produce a plot for each timestep, you can also loop the rest of this file over i
i = 30

#load the NetCDF file containing the timestep
ds = xr.open_dataset(files_externally[i],autoclose=True)

#calculate Heightlevels
dz = get_dz(ds)

# Read in SO2 Column
SO2 = tracer_load(ds.TRSO2_chemtr.values*MM_SO2,ds.rho,dz)

# set colorbar levels
color_so2 = np.linspace(1e-5, 0.02, 11,endpoint=True)

# Plot SO2 column
# set the size of the figure and the background color to white
fig = plt.figure(figsize=(8,6),facecolor='w')

# Set the axes using the specified map projection
ax=plt.axes(projection=ccrs.NearsidePerspective(central_longitude=180, central_latitude=49.29,satellite_height=35785831/5, globe=None))
ax.stock_img() #add a stock image as background
ax.coastlines() # add coastlines
ax.set_title(str(ds.time.values)[2:12]+" "+str(ds.time.values)[13:18]) #set title to the current time displayed
ax.gridlines(draw_labels=False, dms=False, x_inline=True, y_inline=True) #add lat lon gridlines

# Make a filled contour plot
plot1=ax.contourf(ds.lon, ds.lat, SO2, levels=color_so2, cmap='plasma',
transform = ccrs.PlateCarree())
kwargs = {'format': '%.3f'}
cbar = plt.colorbar(plot1,location='right',ticks=color_so2,**kwargs)
cbar.set_label('SO2 Column Mass (kg m-2)')

#save the plot at a path of your choice

#plt.savefig("path/to/your/Plots/folder/SO2_{:03d}.png".format(i))
plt.close(fig)

</syntaxhighlight>
To run the script, you need a working python version and the packages listed in the beginning of the script. Dont forget to make the file executable in order to run it using <code> chmod +x plotscript </code>.
The resulting Plot will look something like this: [[File:Example SO2 130.png]]

File:Example SO2 130.png

2023-10-18T08:04:46Z

Editor 2: Examplatory visualisation of a single timestep during a pointsource simulation.

== Summary ==
Examplatory visualisation of a single timestep during a pointsource simulation.

Simulating a Point Source

2023-10-12T09:04:34Z

Editor 2: updated draft

___ Work in Progress ___

In this Tutorial, the steps to simulate a Volcanic Eruption via a point source are given.
<gallery mode="slideshow">
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019.
</gallery>
== Setting up ICON-ART ==

The first thing to do is having a working installation of ICON-art. To check if your icon version has been built correctly, you can check if
your_icon_folder/bin/icon.exe
exists.

== Setting up Directories ==

Now a directory structure has to be set up. Usually the following directories are used:
* '''Working Directory''': Here the files that are needed for an individual run are saved. This usually includes the runscript and the relevant .xml files.
* '''Icon Code directory''': This is where the Icon code is stored.
* '''External Data directory''': Here external files which are needed for a run are stored. For example, to parametrize the optical properties of clouds a files like ECHAM6_CldOptProps.nc is used. These files of course can be switched out for others, however in most applications the same ones are used. A list of the used files is given in the Runscript, which then creates a link of these files in the Output directory.
* '''Output directory''': This is where the new Simulation data will be stored. Since most of the time large amounts of data are produced, this is stored in the work or scratch partitions on most HPC Systems. The Namelists produced by the runfile are also stored here.

== Setting up the Runscript ==

The function of the runscript is to set up the directory structure,link the relevant files and create the namelists.

== Setting up the .xml's ==
Here the .xml
pntSRC.xml
is set up. It contains all the necessary information to describe the emission of the here defined aerosols into the atmosphere.
The following information is contained:
* where is the Pointsource
* when is it emitting
* what substances are emitted
* how much of each substance is emitted
* what size are the emitted substances (median and standard deviation)

This can be adapted as needed.

In this example, the Raikoke eruption on 21. of June 2019 is Simulated, as can be seen in the following .xml:

<syntaxhighlight line lang=xml class="mw-collapsible-content">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "sources_selTrnsp.dtd">

<sources>
<pntSrc id="Raikoke-SO2">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">TRSO2</substance>
<source_strength type="real">46300.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashacc">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_acc</substance>
<dg3_emiss type="real">0.8E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashcoa">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_coa</substance>
<dg3_emiss type="real">2.98E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashgiant">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_giant</substance>
<dg3_emiss type="real">11.35E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
</sources>
</syntaxhighlight>

== Running the Simulation ==
The setup of the model for the Simulation happens with a runscript. It contains all the different control parameters, such as time Control of the Simulation, what equations are going to be used, whether ART is active, and a lot more.
The Runscript itself is just a text file, which is run via bash to start the simulation. Usually a template file is used and adapted to the specific needs of the User running the Simulation.
Here we will go through the runscript for our Pointsource Simulation.

The first step is to set the relevant directories, so that the XML data we provide as well as the path to the ICON model can be found and accessed easily.
In this simulation, external data such as a grid containing external parameter data is required. The directory containing the data is set as DATADIR.
The output directory is where the model will write the output into, as well as linking a lot of relevant files used in the simulation.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
# working directory
export XMLDIR=/your/path/to/Training2023/Volcano

# datadir2 --> do not change
export DATADIR=/your/path/to/DATA_Volcano

# output directory
export OUTDIR=/your/path/to/Volcano_externally

# Code directory
export ICONDIR=/your/path/to/icon-kit
export ARTDIR=${ICONDIR}/externals/art

</syntaxhighlight>

In the next step, the previously defined Output directory is created, if not already there, and the icon executable is linked into it for easier acces and overview.

<syntaxhighlight line lang=bash class="mw-collapsible-content">
if [ ! -d $OUTDIR ]; then
mkdir -p $OUTDIR
fi

cd $OUTDIR

# copy icon binary to OUTDIR
cp ${ICONDIR}/bin/icon icon.exe
</syntaxhighlight>

Now, the external Parameters and chemistry files are linked into the Output directory, so that after running the simulation it can be identified which have been used.
<syntaxhighlight line lang=bash class="mw-collapsible-content">
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G.nc ${OUTDIR}/iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_grid_0024_R02B06_G-grfinfo.nc ${OUTDIR}/iconR2B06-DOM01-grfinfo.nc
ln -sf ${DATADIR}/icon_extpar_0024_R02B06_G_20200917_tiles.nc ${OUTDIR}/extpar_iconR2B06-DOM01.nc
ln -sf ${DATADIR}/icon_init_0024_R02B06_2019062112.nc ${OUTDIR}/igfff00000000

ln -sf ${ICONDIR}/data/rrtmg_lw.nc ${OUTDIR}/rrtmg_lw.nc
ln -sf ${ICONDIR}/data/ECHAM6_CldOptProps.nc ${OUTDIR}/ECHAM6_CldOptProps.nc

# Dictionary for the mapping: DWD GRIB2 names <-> ICON internal names
ln -sf ${ICONDIR}/run/ana_varnames_map_file.txt ${OUTDIR}/map_file.ana

## chemistry
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Simnoy2002.dat ${OUTDIR}/Simnoy2002.dat
ln -sf ${ARTDIR}/runctrl_examples/init_ctrl/Linoz2004Br.dat ${OUTDIR}/Linoz2004Br.dat

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

</syntaxhighlight>

In the next step, we create the Namelists. They are written into the Output directory.
First the Master Namelist is created, which most importantly contains the start and stop date, as well as the possibility to restart a run.
The next namelist created is called "NAMELIST_Raikoke-June-2019". Here a lot of the model setup is taking place. It is subdivided into different smaller namelist parts, which all do their part to set up a different part of the model.
Some important namelists for this simulation are:
* grid_nml (line 35): Here the grid on which the Simulation is taking place is given
* run_nml (line 3): Contains the switch to turn on ICON-ART, as well as set model height levels and timestep length.
* output_nml (line 225): Defines which variables at which intervals are written in the Output directory
* art_nml (line 238): Contains the switches relevant for icon--art, see [[Namelist]] for more details. Most importantly, the xml file for the point source emission is linked here

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cd $OUTDIR
cat > icon_master.namelist << EOF
&master_nml
lRestart = .false.
/
&master_time_control_nml
experimentStartDate = "2019-06-21T12:00:00"
forecastLeadTime = "P1D"
checkpointTimeIntval = "P10D"
/
&master_model_nml
model_type=1
model_name="ATMO"
model_namelist_filename="NAMELIST_Raikoke-June-2019"
model_min_rank=1
model_max_rank=65536
model_inc_rank=1
/
&time_nml
ini_datetime_string = "2019-06-21T12:00:00"
dt_restart = 864000 ! 10 days
/
EOF

cat > NAMELIST_Raikoke-June-2019 << 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 = 1 ! 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 = 'iconR2B06-DOM01.nc'
dynamics_parent_grid_id = 0
lredgrid_phys = .false.
/
&initicon_nml
init_mode = 7 ! 2: IFS; 7: Initialized DWD Analysis
lread_ana = .FALSE. ! no analysis data will be read
dwdfg_filename = "igfff00000000" ! initial data filename
filetype = 4
ana_varnames_map_file = "map_file.ana" ! dictionary mapping internal names onto GRIB2 shortNames
ltile_coldstart = .TRUE. ! coldstart for surface tiles
ltile_init = .FALSE. ! set it to .TRUE. if FG data originate from run without tiles
/
&run_nml
num_lev = 90
lvert_nest = .true. ! use vertical nesting if a nest is active
!nsteps = ${nsteps} ! 50 ! 1200 ! 7200 !
dtime = 180 ! timestep in seconds
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 = 15 ! can be increased up to 10 for detailed timer output
output = "nml"
lart = .true.
/
&nwp_phy_nml
inwp_gscp = 1
inwp_convection = 1
inwp_radiation = 4
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 = 3600 ! 7200.
itype_z0 = 2
icpl_aero_conv = 0 ! check meaning -> default 0 - off
icpl_aero_gscp = 0 ! check meaning -> default 0 - off
! resolution-dependent settings - please choose the appropriate one
dt_rad = 2160.
dt_conv = 720.
dt_sso = 1440.
dt_gwd = 1440.
mu_rain = 0.5
rain_n0_factor = 0.1
lshallowconv_only = .true.
lgrayzone_deepconv = .false.
/
&nwp_tuning_nml
itune_albedo = 1 ! somewhat reduced albedo (w.r.t. MODIS data) over Sahara in order to reduce cold bias
tune_gkdrag = 0.09
tune_gkwake = 1.8
tune_gfrcrit = 0.333
tune_dust_abs = 1.
tune_zvz0i = 1.1
tune_box_liq_asy = 4.0
tune_gust_factor = 7.0
tune_rcucov = 0.075
tune_rhebc_land = 0.825
tune_zvz0i = 0.85
icpl_turb_clc = 2
max_calibfac_clcl = 2.0
tune_box_liq = 0.04
/
&turbdiff_nml
tkhmin = 0.75 ! new default since rev. 16527
tkmmin = 0.75 ! "
pat_len = 750. ! 750 in exp.nh_oper
c_diff = 0.2
rat_sea = 0.8 ! ** new value since for v2.0.15; previously 8.0 ** ! ** 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:
itype_sher = 3
ltkeshs = .true.
a_hshr = 2.0
alpha1 = 0.125
icldm_turb = 1 ! found in exp.nh_oper ** new recommendation for v2.0.15 in conjunction with evaporation fix for grid-scale rain **
rlam_heat = 10.0
/
&lnd_nml
ntiles = 3 !!! 1 for assimilation cycle and forecast
nlev_snow = 3 !!! 1 for assimilation cycle and forecast
lmulti_snow = .false. !!! .false. for assimilation cycle and forecast
itype_heatcond = 3
idiag_snowfrac = 20
lsnowtile = .true. !! later on .true. if GRIB encoding issues are solved
lseaice = .true.
llake = .true.
lprog_albsi = .true.
itype_lndtbl = 4 ! minimizes moist/cold bias in lower tropical troposphere
itype_evsl = 4
itype_root = 2
itype_trvg = 3
cwimax_ml = 5.e-4
c_soil = 1.25
c_soil_urb = 0.5
sstice_mode = 2
/
&radiation_nml
irad_o3 = 7
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
direct_albedo_water = 3
albedo_whitecap = 1
ecrad_data_path = "${ICONDIR}/externals/ecrad/data"
/
&nonhydrostatic_nml
iadv_rhotheta = 2
ivctype = 2
itime_scheme = 4
exner_expol = 0.333
vwind_offctr = 0.2
damp_height = 44000.
rayleigh_coeff = 1
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, must be at least as large as htop_moist_proc
htop_aero_proc = 25000. !height limit for aerosol tracer processes
/
&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
ivadv_tracer = 3,3,3,3,3,3,3,3,3,3,3
itype_hlimit = 3,4,4,4,4,3,3,3,3,3,3
ihadv_tracer = 52,2,2,2,2,22,22,22,22,22,22
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.
/
&extpar_nml
itopo = 1
n_iter_smooth_topo = 1
heightdiff_threshold = 3000.
hgtdiff_max_smooth_topo = 750., ! found in exp.nh_oper ** should be changed to 750.,750 with next Extpar update! **
itype_lwemiss = 2
/
&io_nml
itype_pres_msl = 5 ! 5: new DWD method; 4: IFS method with bug fix for self-consistency between SLP and geopotential
itype_rh = 1 ! RH w.r.t. water
/
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = -1 ! write all domains
mode = 1 ! 1 = forecast mode with TAXIS_RELATIVE, works only with output in multiples of 1h; 2 = climate mode, default, TAXIS_ABSOLUTE
output_bounds = 0., 691200., 600. ! start, end, increment
steps_per_file = 1
include_last = .TRUE.
output_filename = 'Raikoke-June-2019-forecast_mode-remap' ! file name base
ml_varlist = 'TRSO2_chemtr','TRH2SO4_chemtr','group:ART_AEROSOL','rho','pres','temp', 'z_mc','z_ifc'
remap = 1
reg_lon_def = 120.,0.1,280.
reg_lat_def = 85.,-0.1, 30.
/
&art_nml
lart_diag_out = .TRUE.
lart_aerosol = .TRUE.
lart_pntSrc = .TRUE.
lart_chem = .TRUE.
lart_chemtracer = .TRUE.
iart_ari = 0

cart_aerosol_xml = '${XMLDIR}/Ex01_aerotracer.xml'
cart_modes_xml = '${XMLDIR}/Ex01_modes.xml'
cart_pntSrc_xml = '${XMLDIR}/Ex01_pntSrc.xml'
cart_chemtracer_xml = '${XMLDIR}/Ex01_chemtracer.xml'
/
EOF
</syntaxhighlight>

With the namelists set, we can now prepare the Simulation for running. Since a lot of setup is required for running, this is also prepared within the runscript and then later executed. The following part is highly dependant on the HPC system configuration. The following setup works on the DKRZ Levante HPC system:

<syntaxhighlight line lang=bash class="mw-collapsible-content">
cat > ${OUTDIR}/job_ICON << ENDFILE
#!/bin/bash
#SBATCH --job-name=EXP01_ART # Specify job name
#SBATCH --partition=compute # Specify partition name
#SBATCH --nodes=4 # Specify number of nodes
#SBATCH --ntasks-per-node=128 # Specify number of (MPI) tasks on each node
#SBATCH --time=01:00:00 # Set a limit on the total run time
#SBATCH --mail-type=FAIL # Notify user by email in case of job failure
#SBATCH --mail-user=example@mail.com # Set your e-mail address
#SBATCH --account=your_project_account # Charge resources on this project account

module load gcc
module load intel-oneapi-compilers/2022.0.1-gcc-11.2.0
module load intel-oneapi-mkl/2022.0.1-gcc-11.2.0
module load openmpi/4.1.2-intel-2021.5.0
module load netcdf-c/4.8.1-openmpi-4.1.2-intel-2021.5.0
module load netcdf-fortran/4.5.3-openmpi-4.1.2-intel-2021.5.0
module load parallel-netcdf/1.12.2-openmpi-4.1.2-intel-2021.5.0
module load hdf5/1.12.1-openmpi-4.1.2-intel-2021.5.0
module load eccodes/2.21.0-intel-2021.5.0

unset SLURM_EXPORT_ENV
unset SLURM_MEM_PER_NODE
unset SBATCH_EXPORT

export LD_LIBRARY_PATH="/usr/lib:/usr/lib64:/sw/spack-levante/netcdf-c-4.8.1-2k3cmu/lib:/sw/spack-levante/netcdf-fortran-4.5.3-k6xq5g/lib:/sw/spack-levante/hdf5-1.12.1-tvymb5/lib:/sw/spack-levante/eccodes-2.21.0-3ehkbb/lib64:/sw/spack-levante/intel-oneapi-mkl-2022.0.1-ttdktf/mkl/2022.0.1/lib/intel64/"

export OMPI_MCA_pml="ucx"
export OMPI_MCA_btl=self
export OMPI_MCA_osc="pt2pt"
export UCX_IB_ADDR_TYPE=ib_global

export OMPI_MCA_coll="^ml,hcoll"
export OMPI_MCA_coll_hcoll_enable="0"
export HCOLL_ENABLE_MCAST_ALL="0"
export HCOLL_MAIN_IB=mlx5_0:1
export UCX_NET_DEVICES=mlx5_0:1
export UCX_TLS=mm,knem,cma,dc_mlx5,dc_x,self
export UCX_UNIFIED_MODE=y
export HDF5_USE_FILE_LOCKING=FALSE
export OMPI_MCA_io="romio321"
export UCX_HANDLE_ERRORS=bt

ulimit -s 102400
ulimit -c 0

srun -l --cpu_bind=cores --distribution=block:cyclic --propagate=STACK,CORE ./icon.exe

ENDFILE
</syntaxhighlight>
This concludes the runfile.
The Job_ICON-file that has been produced in the last step can then be executed. For that, firstly the runfile hast to be run using bash:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ chmod +x myrunfile
$ ./myrunfile
</syntaxhighlight>
This will then create all the Namelists and the runscript job_ICON. To then submit the icon run, go to the output directory, make the runscript executable, and run it:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cd /path/to/your/output
$ chmod +x job_ICON
$ sbatch job_ICON
</syntaxhighlight>
with that, the Job should be submitted. The submission status can be seen with
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ squeue --user your_username
</syntaxhighlight>

If everything went well, in the Output directory there will be output files generated with names like Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
== Inspecting the Output ==
In this example, the output is created in the form of several NetCDF4 (.nc) files. To avoid having one giant file, it is subdivided into several files containing a fixed amount of timesteps. The quickest way to inspect a NetCDF file is with [https://code.mpimet.mpg.de/projects/cdo CDO]:
<syntaxhighlight lang=bash class="mw-collapsible-content">
$ cdo sinfo Raikoke-June-2019-forecast_mode-remap_DOM01_ML_0001.nc
</syntaxhighlight>
This way it is possible to obtain information about the variables, grid parameters and timesteps of the simulation. To actually see the values of a specific variable, tools like ncdump can be used, however in many cases this is not practical, since the amount of single values is way too large to look at individual data points.

== Making a Plot of the Simulation Data ==
In order to gain insight into the Simulation, as well as an overview, the most common way is to create some plots of different variables of interest. In our case, we want to know what happens to the ash emitted from the Raikoke eruption.
A quick and easy way to create Plots is using python and a reference script to produce a plot similar to the Pointsource animation is given here:
<syntaxhighlight line lang=python class="mw-collapsible-content">
# first we import the following packages:
import numpy as np # general utility for trigonomic functions and arrays
import matplotlib.pyplot as plt # Library to produce Plots
import xarray as xr # reading in of netCDF data, optimized for large datasets
import cartopy.crs as ccrs # plotting things on a map

#Next step: read in the Netcdf Files

#datadir_externally = 'path/to/your/output/Training2023/Volcano_externally/'
files_externally = glob(datadir_externally+'Raikoke-June-2019-forecast_mode-remap_DOM01_ML*')
files_externally.sort()

#Next step: Calculate relevant data to be displayed
# get model level height
def get_dz(ds):
dz = -1 * ds.z_ifc.diff('height_2')
dz = dz.rename({'height_2':'height'})
dz = dz.assign_coords(height=(dz.height - 1))
return dz

# Calculate column integrated tracer mass (tracer load)
def tracer_load(tr,rho,dz):
m_tr = tr * rho * dz
m_tr = m_tr.sum('height')
m_tr = m_tr.squeeze()
return m_tr

#
MM_SO2 = 64/28.96 # molar weight of SO2 / dry air

# set the timestep you want to plot
# in this simulation there are 144 timesteps and 144 files each containing one timestep
# To produce a plot for each timestep, you can also loop the rest of this file over i
i = 1

#load the NetCDF file containing the timestep
ds = xr.open_dataset(files_externally[i],autoclose=True)

#calculate Heightlevels
dz = get_dz(ds)

# Read in SO2 Column
SO2 = tracer_load(ds.TRSO2_chemtr.values*MM_SO2,ds.rho,dz)

# set colorbar levels
color_so2 = np.linspace(1e-5, 0.02, 11,endpoint=True)

# Plot SO2 column
# set the size of the figure and the background color to white
fig = plt.figure(figsize=(8,6),facecolor='w')

# Set the axes using the specified map projection
ax=plt.axes(projection=ccrs.NearsidePerspective(central_longitude=180, central_latitude=49.29,satellite_height=35785831/5, globe=None))
ax.stock_img() #add a stock image as background
ax.coastlines() # add coastlines
ax.set_title(str(ds.time.values)[2:12]+" "+str(ds.time.values)[13:18]) #set title to the current time displayed
ax.gridlines(draw_labels=False, dms=False, x_inline=True, y_inline=True) #add lat lon gridlines

# Make a filled contour plot
plot1=ax.contourf(ds.lon, ds.lat, SO2, levels=color_so2, cmap='plasma',
transform = ccrs.PlateCarree())
kwargs = {'format': '%.3f'}
cbar = plt.colorbar(plot1,location='right',ticks=color_so2,**kwargs)
cbar.set_label('SO2 Column Mass (kg m-2)')

#save the plot at a path of your choice

#plt.savefig("path/to/your/Plots/folder/SO2_{:03d}.png".format(i))
plt.close(fig)

</syntaxhighlight>

Main Page

2023-07-06T08:02:30Z

Editor 2: width of table aut-adjusts

{|border="1" width="100%" bordercolor="#000000" cellspacing="0" cellpadding="5" align="center"

|-valign="middle" height="75" bgcolor="##169088;" align="center"
|<p><font color="#FFFFFF" size="+2">'''ICON-ART User guide'''</font></p>

|}
<strong>Welcome to the ICON-ART Wiki!</strong>
ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery mode="packed-hover" align="left" widths=600px heights=400px >

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

File:ART-seamless.png|none|alt=ICON-ART’s capabilities for seamless prediction.|ICON-ART’s capabilities for seamless prediction.
</gallery>
Being a seamless model makes it possible to use ART to simulate processes overarching multiple scales, like the emission of greenhouse gases, aerosol-cloud interactions and atmospheric chemistry as indicated in [[#ART-seamless|seamless prediction with ICON-ART]]. It also enables its use as a prediction tool for the production of renewable energy.

<strong>ICON-ART Wiki is under construction!</strong>

ICON-ART (Aerosol and Reactive Trace gases interactions) is a sub-module of the ICON Model and can be used to simulate emissions, transport, gas phase chemistry, and aerosol dynamics in the troposphere and stratosphere. Before using ICON-ART you need some experience using the ICON model, and to make best use of the articles on this wiki some fluency with using ICON is required. Further information about the usage of ICON can be found in the [https://www.dwd.de/EN/ourservices/nwv_icon_tutorial/pdf_volume/icon_tutorial2020_en.html:official ICON Model Tutorial].

{|border="1" width="100%" bordercolor="#000000" cellspacing="0" cellpadding="5" align="center"
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|style="width: 30%"| <p><font color="#FFFFFF" size="+1">'''[[:Getting Started]]'''</font></p>
|style="width: 70%"| Contains all the necessary information to get started using ICON-ART.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Input]]'''</font></p>
|An overview about which Variables to set and files to prepare to run an ICON-ART simulation.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Namelist]]'''</font></p>
|An overview about the ART Namelist Variables which can be set in the runfile to control the parameters of the ICON-ART run.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Output]]'''</font></p>
|Summarizes how to create model output files containing the desired variables for further analysis.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Atmospheric Chemistry]]'''</font></p>
|Explanations and Examples on Simulations with atmospheric chemistry.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Postprocessing]]'''</font></p>
|A brief overview on how to further analyze and visualise the output data.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1"> '''[[:Programming ART]]'''</font></p>
|A short introduction to modifying ICON_ART, for example create a new diagnostic.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Tutorial Examples]]'''</font></p>
|An assortment of Tutorial slides with some examples and a general overview of ICON-ART.
|}

== ICON-ART Application Examples ==
<gallery mode="slideshow" align="left" >
File:Bluemarble.gif|The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. |alt=alt language
File:Raikoke_SO2.gif|SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. |alt=alt language
File: Soot.gif |Soot from Californian wildfires|alt=alt language
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019. See [[Simulating a Point Source]] for instructions how to run this Simulation
</gallery>

----

If you want to contribute to the ICON-ART User guide, here are some links to get started using MediaWiki:

* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

Main Page

2023-07-06T07:58:00Z

Editor 2: made table centered to align with other page elements

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5" align="center"

|-valign="middle" height="75" bgcolor="##169088;" align="center"
|<p><font color="#FFFFFF" size="+2">'''ICON-ART User guide'''</font></p>

|}
<strong>Welcome to the ICON-ART Wiki!</strong>
ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery mode="packed-hover" align="left" widths=600px heights=400px >

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

File:ART-seamless.png|none|alt=ICON-ART’s capabilities for seamless prediction.|ICON-ART’s capabilities for seamless prediction.
</gallery>
Being a seamless model makes it possible to use ART to simulate processes overarching multiple scales, like the emission of greenhouse gases, aerosol-cloud interactions and atmospheric chemistry as indicated in [[#ART-seamless|seamless prediction with ICON-ART]]. It also enables its use as a prediction tool for the production of renewable energy.

<strong>ICON-ART Wiki is under construction!</strong>

ICON-ART (Aerosol and Reactive Trace gases interactions) is a sub-module of the ICON Model and can be used to simulate emissions, transport, gas phase chemistry, and aerosol dynamics in the troposphere and stratosphere. Before using ICON-ART you need some experience using the ICON model, and to make best use of the articles on this wiki some fluency with using ICON is required. Further information about the usage of ICON can be found in the [https://www.dwd.de/EN/ourservices/nwv_icon_tutorial/pdf_volume/icon_tutorial2020_en.html:official ICON Model Tutorial].

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5" align="center"
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|style="width: 30%"| <p><font color="#FFFFFF" size="+1">'''[[:Getting Started]]'''</font></p>
|style="width: 70%"| Contains all the necessary information to get started using ICON-ART.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Input]]'''</font></p>
|An overview about which Variables to set and files to prepare to run an ICON-ART simulation.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Namelist]]'''</font></p>
|An overview about the ART Namelist Variables which can be set in the runfile to control the parameters of the ICON-ART run.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Output]]'''</font></p>
|Summarizes how to create model output files containing the desired variables for further analysis.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Atmospheric Chemistry]]'''</font></p>
|Explanations and Examples on Simulations with atmospheric chemistry.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Postprocessing]]'''</font></p>
|A brief overview on how to further analyze and visualise the output data.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1"> '''[[:Programming ART]]'''</font></p>
|A short introduction to modifying ICON_ART, for example create a new diagnostic.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Tutorial Examples]]'''</font></p>
|An assortment of Tutorial slides with some examples and a general overview of ICON-ART.
|}

== ICON-ART Application Examples ==
<gallery mode="slideshow" align="left" >
File:Bluemarble.gif|The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. |alt=alt language
File:Raikoke_SO2.gif|SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. |alt=alt language
File: Soot.gif |Soot from Californian wildfires|alt=alt language
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019. See [[Simulating a Point Source]] for instructions how to run this Simulation
</gallery>

----

If you want to contribute to the ICON-ART User guide, here are some links to get started using MediaWiki:

* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

Simulating a Point Source

2023-06-30T10:07:41Z

Editor 2: added work in Progress disclaimer for now

Main Page

2023-06-30T10:06:59Z

Editor 2: /* ICON-ART Application Examples */ added Pointsource Raikoke eruption matplotlib visualisation

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"

|-valign="middle" height="75" bgcolor="##169088;" align="center"
|<p><font color="#FFFFFF" size="+2">'''ICON-ART User guide'''</font></p>

|}
<strong>Welcome to the ICON-ART Wiki!</strong>
ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery mode="packed-hover" align="left" widths=600px heights=400px >

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

File:ART-seamless.png|none|alt=ICON-ART’s capabilities for seamless prediction.|ICON-ART’s capabilities for seamless prediction.
</gallery>
Being a seamless model makes it possible to use ART to simulate processes overarching multiple scales, like the emission of greenhouse gases, aerosol-cloud interactions and atmospheric chemistry as indicated in [[#ART-seamless|seamless prediction with ICON-ART]]. It also enables its use as a prediction tool for the production of renewable energy.

<strong>ICON-ART Wiki is under construction!</strong>

ICON-ART (Aerosol and Reactive Trace gases interactions) is a sub-module of the ICON Model and can be used to simulate emissions, transport, gas phase chemistry, and aerosol dynamics in the troposphere and stratosphere. Before using ICON-ART you need some experience using the ICON model, and to make best use of the articles on this wiki some fluency with using ICON is required. Further information about the usage of ICON can be found in the [https://www.dwd.de/EN/ourservices/nwv_icon_tutorial/pdf_volume/icon_tutorial2020_en.html:official ICON Model Tutorial].

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|style="width: 30%"| <p><font color="#FFFFFF" size="+1">'''[[:Getting Started]]'''</font></p>
|style="width: 70%"| Contains all the necessary information to get started using ICON-ART.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Input]]'''</font></p>
|An overview about which Variables to set and files to prepare to run an ICON-ART simulation.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Namelist]]'''</font></p>
|An overview about the ART Namelist Variables which can be set in the runfile to control the parameters of the ICON-ART run.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Output]]'''</font></p>
|Summarizes how to create model output files containing the desired variables for further analysis.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Atmospheric Chemistry]]'''</font></p>
|Explanations and Examples on Simulations with atmospheric chemistry.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Postprocessing]]'''</font></p>
|A brief overview on how to further analyze and visualise the output data.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1"> '''[[:Programming ART]]'''</font></p>
|A short introduction to modifying ICON_ART, for example create a new diagnostic.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Tutorial Examples]]'''</font></p>
|An assortment of Tutorial slides with some examples and a general overview of ICON-ART.
|}

== ICON-ART Application Examples ==
<gallery mode="slideshow" align="left" >
File:Bluemarble.gif|The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. |alt=alt language
File:Raikoke_SO2.gif|SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. |alt=alt language
File: Soot.gif |Soot from Californian wildfires|alt=alt language
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019. See [[Simulating a Point Source]] for instructions how to run this Simulation
</gallery>

----

If you want to contribute to the ICON-ART User guide, here are some links to get started using MediaWiki:

* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

Simulating a Point Source

2023-06-30T10:03:54Z

Editor 2: added Raikoke.gif

In this Tutorial, the steps to simulate a Volcanic Eruption via a point source are given.
<gallery mode="slideshow">
File:Pointsource.gif | Pointsource simulation of the Raikoke eruption in June 2019.
</gallery>
== Setting up ICON-ART ==

The first thing to do is having a working installation of ICON-art. To check if your icon version has been built correctly, you can check if
your_icon_folder/bin/icon.exe
exists.

== Setting up Directories ==

Now a directory structure has to be set up. Usually the following directories are used:
* '''Working Directory''': Here the files that are needed for an individual run are saved. This usually includes the runscript and the relevant .xml files.
* '''Icon Code directory''': This is where the Icon code is stored.
* '''External Data directory''': Here external files which are needed for a run are stored. For example, to parametrize the optical properties of clouds a files like ECHAM6_CldOptProps.nc is used. These files of course can be switched out for others, however in most applications the same ones are used. A list of the used files is given in the Runscript, which then creates a link of these files in the Output directory.
* '''Output directory''': This is where the new Simulation data will be stored. Since most of the time large amounts of data are produced, this is stored in the work or scratch partitions on most HPC Systems. The Namelists produced by the runfile are also stored here.

== Setting up the Runscript ==

The function of the runscript is to set up the directory structure,link the relevant files and create the namelists.

== Setting up the .xml's ==
Here the .xml
pntSRC.xml
is set up. It contains all the necessary information to describe the emission of the here defined aerosols into the atmosphere.
The following information is contained:
* where is the Pointsource
* when is it emitting
* what substances are emitted
* how much of each substance is emitted
* what size are the emitted substances (median and standard deviation)

This can be adapted as needed.

In this example, the Raikoke eruption on 21. of June 2019 is Simulated, as can be seen in the following .xml:

<pre class="mw-collapsible-content">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "sources_selTrnsp.dtd">

<sources>
<pntSrc id="Raikoke-SO2">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">TRSO2</substance>
<source_strength type="real">46300.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashacc">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_acc</substance>
<dg3_emiss type="real">0.8E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashcoa">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_coa</substance>
<dg3_emiss type="real">2.98E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashgiant">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_giant</substance>
<dg3_emiss type="real">11.35E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
</sources>
</pre>

== Running the Simulation ==

== Inspecting the Output ==

== Making a Plot of the Simulation Data ==

File:Pointsource.gif

2023-06-30T09:59:34Z

Editor 2: Results of a Pointsource Simulation of the Raikoke Eruption in June 2019

== Summary ==
Results of a Pointsource Simulation of the Raikoke Eruption in June 2019

Simulating a Point Source

2023-06-28T13:13:02Z

Editor 2: /* Setting up the .xml's */ added raikoke .xml

In this Tutorial, the steps to simulate a Volcanic Eruption via a point source are given.

== Setting up ICON-ART ==

The first thing to do is having a working installation of ICON-art. To check if your icon version has been built correctly, you can check if
your_icon_folder/bin/icon.exe
exists.

== Setting up Directories ==

Now a directory structure has to be set up. Usually the following directories are used:
* '''Working Directory''': Here the files that are needed for an individual run are saved. This usually includes the runscript and the relevant .xml files.
* '''Icon Code directory''': This is where the Icon code is stored.
* '''External Data directory''': Here external files which are needed for a run are stored. For example, to parametrize the optical properties of clouds a files like ECHAM6_CldOptProps.nc is used. These files of course can be switched out for others, however in most applications the same ones are used. A list of the used files is given in the Runscript, which then creates a link of these files in the Output directory.
* '''Output directory''': This is where the new Simulation data will be stored. Since most of the time large amounts of data are produced, this is stored in the work or scratch partitions on most HPC Systems. The Namelists produced by the runfile are also stored here.

== Setting up the Runscript ==

The function of the runscript is to set up the directory structure,link the relevant files and create the namelists.

== Setting up the .xml's ==
Here the .xml
pntSRC.xml
is set up. It contains all the necessary information to describe the emission of the here defined aerosols into the atmosphere.
The following information is contained:
* where is the Pointsource
* when is it emitting
* what substances are emitted
* how much of each substance is emitted
* what size are the emitted substances (median and standard deviation)

This can be adapted as needed.

In this example, the Raikoke eruption on 21. of June 2019 is Simulated, as can be seen in the following .xml:

<pre class="mw-collapsible-content">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tracers SYSTEM "sources_selTrnsp.dtd">

<sources>
<pntSrc id="Raikoke-SO2">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">TRSO2</substance>
<source_strength type="real">46300.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashacc">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_acc</substance>
<dg3_emiss type="real">0.8E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashcoa">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_insol_coa</substance>
<dg3_emiss type="real">2.98E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
<pntSrc id="Raikoke-ashgiant">
<lon type="real">153.24</lon>
<lat type="real">49.29</lat>
<substance type="char">ash_giant</substance>
<dg3_emiss type="real">11.35E-6</dg3_emiss>
<sigma_emiss type="real">1.4</sigma_emiss>
<source_strength type="real">19700.0</source_strength>
<height type="real">14000</height>
<height_bot type="real">600</height_bot>
<unit type="char">kg s-1</unit>
<startTime type="char">2019-06-21T13:00:00</startTime>
<endTime type="char">2019-06-21T22:00:00</endTime>
</pntSrc>
</sources>
</pre>

== Running the Simulation ==

== Inspecting the Output ==

== Making a Plot of the Simulation Data ==

Simulating a Point Source

2023-06-28T11:18:38Z

Editor 2:

Simulating a Point Source

2023-06-28T10:41:33Z

Editor 2: Created Structure /first draft

Postprocessing

2023-06-20T10:18:28Z

Editor 2: added Data Processing chapter containing ICONTOOLS and CDO

== Output Checks with SAMOA ==

SAMOA performs a sanity check on all model outputs that can be read by CDO. It checks if a variable lies in-between a predefined range and if the minimum and maximum value of each variable are the same. For this purpose CDO version 1.6.2rc3 is required currently (see https://code.zmaw.de/projects/cdo).

For more information about the usage please refer to the README-file within the SAMOA package. You can get a copy of the SAMOA script by writing an e-mail to the contact person of the ART code (see http://icon-art.imk-tro.kit.edu). SAMOA is licensed under the GNU GENERAL PUBLIC LICENSE Version 3.

As SAMOA is primarily developed for the usage with COSMO-ART and COSMO-CLM, you have to do a minor change before using it. The latest version of SAMOA has a list for the usage of SAMOA with ICON-ART output included but not loaded automatically. This list is called samoa_list_icon-art. You have to replace the default (COSMO) list that is used by SAMOA by editing samoa.sh:

Search for the following lines:

<pre># Path to the list with variables (is overwritten when -l specified)
# Assumed to be on the same path as script

path_list=$SCRIPTPATH/list </pre>
Change the name of the list to:

<pre>path_list=$SCRIPTPATH/samoa_list_icon-art </pre>
Now you may use SAMOA with the ICON-ART output file out.nc with the following command:

<pre>./samoa.sh out.nc</pre>
For all options see:

<pre>./samoa.sh --help</pre>

== Data Processing ==
Some ways to handle and modify the outputs of ICON-ART are described here.

=== CDO ===
[https://code.mpimet.mpg.de/projects/cdo CDO] is a command line tool to interact with netCDF files, enabling to list the variables and do calculations efficiently.
Different examples for its usage can be found in the [https://code.mpimet.mpg.de/projects/cdo/wiki/FAQ CDO FAQ]
=== ICONTOOLS ===
[https://wiki.c2sm.ethz.ch/pub/MODELS/ICONDwdIconTools/doc_icontools.pdf ICONTOOLS] is a command line tool used to produce the required external parameters data of a simulation and is especially good at remapping data from one grid to another.

== Visualisation ==
There are many ways to visualize data produced by ICON-ART. In general, there are two possibilities: The output may exist on the ICON grid or it may exist on an interpolated longitude/latitude grid. This can be chosen by adaptions of the output namelist. Although it comes along with a loss in information, sometimes it is only possible to use interpolated output. By this, the visualization is much easier to handle.

In the following sections some tools are introduced which can be used to visualize ICON output. Note, that '''only NETCDF''' is supported by ICON-ART so far. With the tool Ncview it is very easy to have a quick look into the interpolated model output. With ParaView and Met3D a nice-looking three-dimensional visualization can be created. Python in the recent years has become the standard tool for 2D visualisation and its capabilities far exceed those of Ncview.

=== Ncview ===

"Ncview is a visual browser for netCDF format files. Typically you would use ncview to get a quick and easy, push-button look at your netCDF files. You can view simple movies of the data, view along various dimensions, take a look at the actual data values, change color maps, invert the data, etc." (http://meteora.ucsd.edu/~pierce/ncview_home_page.html)

Please note that Ncview does only work for latitude-longitude grid data and cannot be used for RXXBXX-style ICON grids without remapping.

=== Met3d ===

Met3D is a visualization software that can be used on a HPC system to visualize ICON as well as ICON-ART data in 3D. An online documentation can be found [https://met3d.wavestoweather.de/met-3d.html here]. Met3D needs remapped ICON fields to Latitude-Longitude . Furthermore, it is important to have the pressure (pres - variable) as model output, as Met3D transforms model levels in pressure levels for plotting.

=== ParaView ===

"ParaView is an open-source, multi-platform data analysis and visualization application. ParaView users can quickly build visualizations to analyze their data using qualitative and quantitative techniques. The data exploration can be done interactively in 3D or programmatically using ParaView’s batch processing capabilities.

ParaView was developed to analyze extremely large datasets using distributed memory computing resources. It can be run on supercomputers to analyze datasets of exascale size as well as on laptops for smaller data." (http://www.paraview.org/)

Paraview can be used for both Latitude-Longitude grids as well as RXXBXX-style ICON grids.

=== Python ===

On the [https://www.python.org/about/ official Website] Python describes itself as

<pre>Python is powerful... and fast;
plays well with others;
runs everywhere;
is friendly & easy to learn;
is Open.</pre>
Using Python is a simple but effective way to display ICON-ART model output data. There is a large number of Packages available to help with Visualisation, the most useful Packages for visualising ICON-ART data are given in this [[#tab:pythonpackages|Table]]

<div id="tab:pythonpackages">

{| class="wikitable" style="text-align:left;"
|+ Helpful Python Packages and their primary usage for Visualisation
|align="center"| numpy
|align="center"| predefined Mathematical functions
|-
|align="center"| matplotlib
|align="center"| Plotting framework
|-
|align="center"| xarray
|align="center"| reading in and processing netcdf datasets
|-
|align="center"| cartopy
|align="center"| Include country borders in plots
|-
|align="center"| ...
|align="center"|
|}

Python can be used for both Latitude-Longitude grids as well as RXXBXX-style ICON grids.
</div>

Getting Started

2023-06-20T09:34:13Z

Editor 2: typo

Getting Started

2023-06-20T09:32:57Z

Editor 2: Mentioned that it is recommended to run Icon-art on a HPC system

Main Page

2023-06-20T09:18:42Z

Editor 2: added the seamless prediction Image, since it is no longer in the Overview Chapter

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"

|-valign="middle" height="75" bgcolor="##169088;" align="center"
|<p><font color="#FFFFFF" size="+2">'''ICON-ART User guide'''</font></p>

|}
<strong>Welcome to the ICON-ART Wiki!</strong>
ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery mode="packed-hover" align="left" widths=600px heights=400px >

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

File:ART-seamless.png|none|alt=ICON-ART’s capabilities for seamless prediction.|ICON-ART’s capabilities for seamless prediction.
</gallery>
Being a seamless model makes it possible to use ART to simulate processes overarching multiple scales, like the emission of greenhouse gases, aerosol-cloud interactions and atmospheric chemistry as indicated in [[#ART-seamless|seamless prediction with ICON-ART]]. It also enables its use as a prediction tool for the production of renewable energy.

<strong>ICON-ART Wiki is under construction!</strong>

ICON-ART (Aerosol and Reactive Trace gases interactions) is a sub-module of the ICON Model and can be used to simulate emissions, transport, gas phase chemistry, and aerosol dynamics in the troposphere and stratosphere. Before using ICON-ART you need some experience using the ICON model, and to make best use of the articles on this wiki some fluency with using ICON is required. Further information about the usage of ICON can be found in the [https://www.dwd.de/EN/ourservices/nwv_icon_tutorial/pdf_volume/icon_tutorial2020_en.html:official ICON Model Tutorial].

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|style="width: 30%"| <p><font color="#FFFFFF" size="+1">'''[[:Getting Started]]'''</font></p>
|style="width: 70%"| Contains all the necessary information to get started using ICON-ART.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Input]]'''</font></p>
|An overview about which Variables to set and files to prepare to run an ICON-ART simulation.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Namelist]]'''</font></p>
|An overview about the ART Namelist Variables which can be set in the runfile to control the parameters of the ICON-ART run.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Output]]'''</font></p>
|Summarizes how to create model output files containing the desired variables for further analysis.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Postprocessing]]'''</font></p>
|A brief overview on how to further analyze and visualise the output data.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1"> '''[[:Programming ART]]'''</font></p>
|A short introduction to modifying ICON_ART, for example create a new diagnostic.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Tutorial Examples]]'''</font></p>
|An assortment of Tutorial slides with some examples and a general overview of ICON-ART.
|}

== ICON-ART Application Examples ==
<gallery mode="slideshow" align="left" >
File:Bluemarble.gif|The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. |alt=alt language
File:Raikoke_SO2.gif|SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. |alt=alt language
File: Soot.gif |Soot from Californian wildfires|alt=alt language

</gallery>

----

If you want to contribute to the ICON-ART User guide, here are some links to get started using MediaWiki:

* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

Getting Started

2023-06-20T09:09:42Z

Editor 2: removed the Overview part, as its already on the Main page

== Getting the source code ==

A user who wants to work with ICON-ART has to sign the ICON license agreement with the German Weatherservice (DWD) and Max-Planck-Institute for Meteorology (MPI-M) first. Further information can be found on the following website:

https://code.mpimet.mpg.de/projects/iconpublic

== Installation ==

ICON-ART is already included in the most recent ICON version. For Instructions on how to install ICON, please refer to the first chapter of the [https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html:official ICON Model Tutorial].
The only caveat is that during the configuration step the tag <code> --enable-art </code> has to be included.

== Creating a Runfile ==

* Go to <code>icon-kit/run/checksuites.icon-kit</code>

* Run bash-script <code>run_testsuite</code> via <code>./run_testsuite</code>

* The script creates the folder runscripts, which contains exemplary runfiles which are adapted to some common HPC-Systems you might be using.

== Running a Job ==

For a user who succeeded in running the ICON model, there are only a few steps to run the ART extension along with the ICON model. A description how to run the ICON model can be found in .

In order to run ICON-ART, one has to do the following steps:

* Make sure you have everything required for an ICON run

* Prepare the input data (see section [[:Input]] )

* Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.

* Add a namelist art_nml and choose the namelist parameters for the ART setup as described in [[:Input]].

* Adapt the XML files for tracers, emi. The number of tracers related to a specific setup is equal to the number of possible prognostic output fields as described in [[:Input]].

* Add an output namelist as described in for the species you are interested in [[:Input]].

* Submit the job analogous to an ICON job.

How to download input data

2023-06-15T08:15:07Z

Editor 2: Created first draft of Page

A quick way to obtain Gridfiles and their respective external parameter files is via the the [http://icon-downloads.mpimet.mpg.de/dwd_grids.xml Max Planck Institute for Meteorology's Icon Grid File Register].

To generate an individual grid file the german weather service has an [https://webservice.dwd.de/cgi-bin/spp1167/webservice.cgi Online Grid Generating Tool], which however is password protected. To obtain login data please refer to icon@dwd.de.

Input

2023-06-07T09:19:40Z

Editor 2: /* Running a Limmited Area Meteorology (LAM) Simulation */ fixed typo

== 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
|---
| <code>cart_chemtracer_xml</code>
| Switch for simple OH chemistry
| <code>lart_chemtracer</code>
| .FALSE.
|-
| <code>cart_mecca_xml</code>
| Switch for kpp chemistry
| <code>lart_mecca</code>
| .FALSE.
|-
| <code>cart_pntSrc_xml</code>
| Enables addition of point sources
| <code>lart_pntSrc</code>
| .FALSE.
|-
| <code>cart_aerosol_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|-
| <code>cart_modes_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|-
| <code>cart_diagnostics_xml</code>
| Enables diagnostic output fields
| <code>lart_diag_out</code>
| .FALSE.
|-
| <code>cart_pntSrc_xml</code>
| Enables creation of point sources emitting given Aerosols at a given rate
| <code>lart_pntSrc </code>
| .FALSE.
|-
| <code>cart_emiss_xml_file</code>
| XML File for emission metadata
| -
| -
|-
| <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>

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.

<pre><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></pre>

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.
<pre>
<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>
</pre>

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">

{| 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
|}

=== Obtaining Input Data ===

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

[[How to generate input data]]

[[How to download input data]]

== Running a Limited Area Meteorology (LAM) Simulation ==

=== General ===

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

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

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

There are two different possible methods to read in the dust during initialization. You can either pass a file containing meteorological variables and a second file containing dust data. The vertical levels may differ between these two files and the dust must be delivered as ART_IAE file. The corresponding namelist setting in<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.

AERODYN

2023-06-07T08:08:00Z

Editor 2: made the expanding xml examples more intuitive

AERODYN (AEROsol DYNamics) is a new aerosol dynamics module used in ICON-ART. With AERODYN, secondary aerosol formations (e.g. the accumulation of SO2 on a volcanic ash particle) can be accounted for.
Aerosol dynamic processes are the processes which change an aerosols properties after it has been released into the atmosphere. This change of properties (omitting chemical reactions) occurs either via condensation or coagulation.
Since it is not feasible to account for every individual aerosol to calculate their movement, coagulation and condensation, AERODYN uses a total of 12 categories for aerosol modes.

== Aerosol Modes in AERODYN ==

Traditionally, There are three categories to account for the aerosol sizes [https://www.sciencedirect.com/science/article/abs/pii/0004698178901968 Whitby et. Al. (1978)] : Aitken mode, accumulation mode and coarse mode. In AERODYN there is also a fourth mode, called giant mode, which accounts for especially large Aerosols, e.g. some species of pollen.

Since condensation can occur on a solid aerosol particle, as well as for a number of other reasons, it is possible to obtain aerosol modes which are a mixture of solid and liquid modes. To account for this, AERODYN combines 4 modes of aerosol size with the 3 modes soluble, insoluble and mixed.
A Visual Representation is given here:

[[File:AERODYNModes.png]]

when also adding the giant mode, the following configurations are possible:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

== Condensation, Nucleation and Accumulation Processes ==
Here is a quick reminder of the different aerosol processes:

* Condensation is the process of a gas turning into a liquid. In practice, some sort of surface, or condensation nucleus is needed to enable the phase change.
* Nucleation is the process of an aerosol particle forming from a gaseous phase by random collisions of the gas molecules. The produced aerosol sizes are in the Aitken mode.
* Accumulation in the Process of the initial nucleus growing in size through collision and deposition Processes.

A schematic overview of the different microphysical aerosol processes can be found in the following Figure from [https://doi.org/10.1016/S1352-2310(00)00239-9 Raes et. Al(2000)]:

[[File:Raes2000.jpg| Overview of Aerosol Processes.]]

In AERODYN, some modes are treated differently with respect to the dynamic processes: Nucleation is only considered for the Aitken mode, and the Giant mode is not affected by condensation. This is done to save computing power while still retaining realism, and since Nucleation of larger Particles without first having Aitken mode Aerosols is highly unlikely, this is a good approximation. Also, as condensation highly prefers smaller modes to the giant mode, this also is a reasonable way to save computing power. For details how the processes are calculated, see [https://doi.org/10.1029/2018RG000615 Riemer et Al. (2003)] and [https://doi.org/10.5194/acp-9-8661-2009 Vogel et. Al. (2009)].

== Defining Aerosols with AERODYN ==

AERODYN is meant to be as flexible as possible, allowing the user to quickly define their own aerosols and then use ICON-ART to simulate their dynamics.
Aerosols are defined in .xml files, which can then be included in the run by specifying their path in the runfile (see [[Input]] for more details)

There are several Types of .xml files for different applications. The most important/most used .xml files are compiled in the following paragraphs.

=== Defining Tracers ===

Below is the tracers.xml, where the aerosols as well as their properties are defined. The properties to be defined are listed in the following table.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ tracers.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! moment
| int || specifies which momentum scheme is used (???) || 3
|-
! mode
| char || mode name from AERODYN mode configurations (multiple modes can be given, seperated by a comma) || insol_giant,sol_aitken
|-

! mol_weight
| real || specify the molar mass || 30E-3
|-
! rho
| real || specify the density in terms of <code> unit </code> || 2e3

|-
! unit
| char || specify what unit the aerosol will have || kg-1
|-
! transport
| char || specify transport scheme to be used || hadv52aero
|-
|}

<div class="toccolours mw-collapsible mw-collapsed">
==== Example File of tracers.xml: ====
<pre class="mw-collapsible-content">
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa,sol_acc,sol_coa,mixed_acc,mixed_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,mixed_acc,mixed_coa</mode>
<sol type="real">0.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>
<aerosol id="na">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">22.9898E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="cl">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">35.453E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="h2o">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">18.01528E-3</mol_weight>
<rho type="real">1.E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">off</transport>
</aerosol>
</tracers>
</pre>
</div>

=== Defining Modes ===

In the modes.xml the modes which are going to be used in the simulation can be defined. The following .xml contains the same information as Figure 3.1, but in a way the computer can interpret it.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ modes.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! kind
| char || specifies which properties are to be calculated in the model (eg 2mom -> mass mixing ratio and number concentration) || 2mom
|-
! d_gn
| real || median diameter of the lognormal aerosol distribution || 2.0E-6
|-
! sigma_g
| real || standard deviation of the lognormal aerosol distribution || 2.2
|-
! condensation
| int || switch to control if condensation can occur || 0
|-
! icoag
| int || switch to control if coagulation can occur || 0
|-
! shift2larger
| char || prevents mode from getting to large, then shifts size to given mode (mostly used for Aitken mode) || insol_acc
|-
! shift_diam
| real || defines the diameter where the aerosol is shifted to the given mode || 0.08E-6
|-
! shift2mixed
| char || shift to given mode when 5% of mass is liquid || mixed_coa
|-
|}

Sometimes it is necessary for the type of an aerosol to change its given mode if its diameter gets too large or a large amount of condensation occurs. The mass can then be transferred to defined modes, as seen in the table above.

<div class="toccolours mw-collapsible mw-collapsed">
==== Example File of modes.xml: ====
<pre class="mw-collapsible-content">
<modes>
<aerosol id="sol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">0.2E-6</d_gn>
<sigma_g type="real">2.0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_acc</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="sol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_coa</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
</modes>
</pre>
</div>

=== Defining Coagulation ===

Here the behaviour of collision and subsequent merging (coagulation) between aerosols can be defined. If for example a solid (insol) aerosol merges with a liquid (sol) aerosol, the result should logically be a mixed aerosol, and so on. This can further be defined for all sizes of aerosols as seen in the example .xml for accumulation and coarse modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ coagulate.xml Parameters
! Parameter || type || description || example
|-
!smallmode id
| char || The aerosol_mode which is gonig to coagulate || insol_acc
|-
!nmodes
| int || Defines the number of modes for which the coagulation preocesses are defined || 5
|-
!bigmode id
| char || Inside angle brackets : coagulation partner of the given aerosol mode. Outside angle brackets: the new mode of the cagulated aerosols. || <bigmode id="sol_acc" type="char">mixed_acc</bigmode>
|-
|}

<div class="toccolours mw-collapsible mw-collapsed">
==== Example File of coag.xml: ====
<pre class="mw-collapsible-content">
<coagulate>
<smallmode id="sol_acc">
<nmodes type="int">6</nmodes>
<bigmode id="sol_acc" type="char">sol_acc</bigmode>
<bigmode id="insol_acc" type="char">mixed_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_acc">
<nmodes type="int">5</nmodes>
<bigmode id="insol_acc" type="char">insol_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_acc">
<nmodes type="int">4</nmodes>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="sol_coa">
<nmodes type="int">3</nmodes>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_coa">
<nmodes type="int">2</nmodes>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_coa">
<nmodes type="int">1</nmodes>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
</coagulate>
</pre>
</div>
=== Defining the Model Output ===
In the diagnostics.xml the diagnostic variables that can be written out are defined. Below are some examples, however this is a heavily shortened version of the diagnostics.xml used in ICON-ART.

<div class="toccolours mw-collapsible mw-collapsed">
==== Example File of diagnostics.xml: ====
<pre class="mw-collapsible-content">
<diagnostics>
<aerosol id="diam_insol_acc">
<productDefinitionTemplate type="int">40</productDefinitionTemplate>
<discipline type="int">0</discipline>
<parameterCategory type="int">254</parameterCategory>
<parameterNumber type="int">201</parameterNumber>
<constituentType type="int">62001</constituentType>
</aerosol>
<aerosol id="acc_drydepo">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">6,6,6,6,6,6,192,192,192,192</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
<aerosol id="acc_emiss">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">3,3,3,3,3,3,3,3,3,3</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
</diagnostics>
</pre>
</div>
=== Defining the Aerosol Emissions ===

Aerosol emissions can be defined via the aero_emiss.xml. Here you do not define the modes themselves but the distribution of the aerosols. ICON-ART then maps the given distribution on to the best fitting modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ aero_emiss.xml Parameters
! Parameter || type || description || example
|-
! routine id
| char || define the name of the emission routine || dust
|-
! nmodes
| int || number of aerosol modes to be emitted. The "X" in the following is to replaced by the numbers 1 to nmodes. || 3
|-
! d_g0_X
| real|| median diameter weighted by number concentration. Has to be defined for every mode given by nmodes. ||6.445E-7
|-
! d_g3_X
| real || median diameter weighted by mass concentration. Has to be defined for every mode given by nmodes. || 1.500E-6
|-
! rho
| real || Density of the emitted aerosol || 2.2E3
|-
! substances
| char || name of the tracers about to be emitted|| na,cl
|-
|}

<div class="toccolours mw-collapsible mw-collapsed">
==== Example File of aero_emiss.xml: ====
<pre class="mw-collapsible-content">
<emiss>
<routine id="dust">
<nmodes type="int">3</nmodes>
<d_g0_1 type="real">6.445E-7</d_g0_1>
<d_g3_1 type="real">1.500E-6</d_g3_1>
<sigma_g_1 type="real">1.700E+0</sigma_g_1>
<d_g0_2 type="real">3.454E-6</d_g0_2>
<d_g3_2 type="real">6.700E-6</d_g3_2>
<sigma_g_2 type="real">1.600E+0</sigma_g_2>
<d_g0_3 type="real">8.672E-6</d_g0_3>
<d_g3_3 type="real">1.420E-5</d_g3_3>
<sigma_g_3 type="real">1.500E+0</sigma_g_3>
<rho type="real">2.650E3</rho>
<substances type="char">dust</substances>
</routine>
<routine id="seas_mode1">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">0.100E-6</d_g0_1>
<d_g3_1 type="real">0.433E-6</d_g3_1>
<sigma_g_1 type="real">1.900E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
<routine id="seas_mode2">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">3.000E-6</d_g0_1>
<d_g3_1 type="real">1.268E-5</d_g3_1>
<sigma_g_1 type="real">2.000E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
</emiss>
</pre>
</div>

Getting Started

2023-06-06T07:41:45Z

Editor 2: rephrasing of installation instructions

== Overview ==

ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery widths=600px heights=400px>

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

File:ART-seamless.png|none|alt=ICON-ART’s capabilities for seamless prediction.|ICON-ART’s capabilities for seamless prediction.
</gallery>
Being a seamless model makes it possible to use ART to simulate processes overarching multiple scales, like the emission of greenhouse gases, aerosol-cloud interactions and atmospheric chemistry as indicated in [[#ART-seamless|seamless prediction with ICON-ART]]. It also enables its use as a prediction tool for the production of renewable energy.

== Getting the source code ==

A user who wants to work with ICON-ART has to sign the ICON license agreement with the German Weatherservice (DWD) and Max-Planck-Institute for Meteorology (MPI-M) first. Further information can be found on the following website:

https://code.mpimet.mpg.de/projects/iconpublic

== Installation ==

ICON-ART is already included in the most recent ICON version. For Instructions on how to install ICON, please refer to the first chapter of the [https://www.dwd.de/DE/leistungen/nwv_icon_tutorial/nwv_icon_tutorial.html:official ICON Model Tutorial].
The only caveat is that during the configuration step the tag <code> --enable-art </code> has to be included.

== Creating a Runfile ==

* Go to <code>icon-kit/run/checksuites.icon-kit</code>

* Run bash-script <code>run_testsuite</code> via <code>./run_testsuite</code>

* The script creates the folder runscripts, which contains exemplary runfiles which are adapted to some common HPC-Systems you might be using.

== Running a Job ==

For a user who succeeded in running the ICON model, there are only a few steps to run the ART extension along with the ICON model. A description how to run the ICON model can be found in .

In order to run ICON-ART, one has to do the following steps:

* Make sure you have everything required for an ICON run

* Prepare the input data (see section [[:Input]] )

* Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.

* Add a namelist art_nml and choose the namelist parameters for the ART setup as described in [[:Input]].

* Adapt the XML files for tracers, emi. The number of tracers related to a specific setup is equal to the number of possible prognostic output fields as described in [[:Input]].

* Add an output namelist as described in for the species you are interested in [[:Input]].

* Submit the job analogous to an ICON job.

ISORROPIA

2023-05-25T15:25:06Z

Editor 2: First draft/placeholder of page

ISORROPIA is a Model used to calculate the distribution of Aerosols between solid and gas phase in thermal equilibrium. It can be used for the Aerosols K ,Ca Mg NH4 Na So4,NO3 , CL, H2O.

The Integration into ICON-ART has ben done by Muser et al. (2020)

== References==

- Fountoukis, C. and Nenes, A.: ISORROPIA II: a computationally efficient thermodynamic equilibrium model for K+–Ca2+–Mg2+–NH4+–Na+–SO42−–NO3−–Cl−–H2O aerosols, Atmos. Chem. Phys., 7, 4639–4659, https://doi.org/10.5194/acp-7-4639-2007, 2007.

- Muser, L. O., Hoshyaripour, G. A., Bruckert, J., Horváth, Á., Malinina, E., Wallis, S., Prata, F. J., Rozanov, A., von Savigny, C., Vogel, H., and Vogel, B.: Particle aging and aerosol–radiation interaction affect volcanic plume dispersion: evidence from the Raikoke 2019 eruption, Atmos. Chem. Phys., 20, 15015–15036, https://doi.org/10.5194/acp-20-15015-2020, 2020.

AERODYN

2023-05-25T07:00:37Z

Editor 2: Made .xml code samples collapsible as well as collapsed in their basic state

AERODYN (AEROsol DYNamics) is a new aerosol dynamics module used in ICON-ART. With AERODYN, secondary aerosol formations (e.g. the accumulation of SO2 on a volcanic ash particle) can be accounted for.
Aerosol dynamic processes are the processes which change an aerosols properties after it has been released into the atmosphere. This change of properties (omitting chemical reactions) occurs either via condensation or coagulation.
Since it is not feasible to account for every individual aerosol to calculate their movement, coagulation and condensation, AERODYN uses a total of 12 categories for aerosol modes.

== Aerosol Modes in AERODYN ==

Traditionally, There are three categories to account for the aerosol sizes [https://www.sciencedirect.com/science/article/abs/pii/0004698178901968 Whitby et. Al. (1978)] : Aitken mode, accumulation mode and coarse mode. In AERODYN there is also a fourth mode, called giant mode, which accounts for especially large Aerosols, e.g. some species of pollen.

Since condensation can occur on a solid aerosol particle, as well as for a number of other reasons, it is possible to obtain aerosol modes which are a mixture of solid and liquid modes. To account for this, AERODYN combines 4 modes of aerosol size with the 3 modes soluble, insoluble and mixed.
A Visual Representation is given here:

[[File:AERODYNModes.png]]

when also adding the giant mode, the following configurations are possible:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

== Condensation, Nucleation and Accumulation Processes ==
Here is a quick reminder of the different aerosol processes:

* Condensation is the process of a gas turning into a liquid. In practice, some sort of surface, or condensation nucleus is needed to enable the phase change.
* Nucleation is the process of an aerosol particle forming from a gaseous phase by random collisions of the gas molecules. The produced aerosol sizes are in the Aitken mode.
* Accumulation in the Process of the initial nucleus growing in size through collision and deposition Processes.

A schematic overview of the different microphysical aerosol processes can be found in the following Figure from [https://doi.org/10.1016/S1352-2310(00)00239-9 Raes et. Al(2000)]:

[[File:Raes2000.jpg| Overview of Aerosol Processes.]]

In AERODYN, some modes are treated differently with respect to the dynamic processes: Nucleation is only considered for the Aitken mode, and the Giant mode is not affected by condensation. This is done to save computing power while still retaining realism, and since Nucleation of larger Particles without first having Aitken mode Aerosols is highly unlikely, this is a good approximation. Also, as condensation highly prefers smaller modes to the giant mode, this also is a reasonable way to save computing power. For details how the processes are calculated, see [https://doi.org/10.1029/2018RG000615 Riemer et Al. (2003)] and [https://doi.org/10.5194/acp-9-8661-2009 Vogel et. Al. (2009)].

== Defining Aerosols with AERODYN ==

AERODYN is meant to be as flexible as possible, allowing the user to quickly define their own aerosols and then use ICON-ART to simulate their dynamics.
Aerosols are defined in .xml files, which can then be included in the run by specifying their path in the runfile (see [[Input]] for more details)

There are several Types of .xml files for different applications. The most important/most used .xml files are compiled in the following paragraphs.

=== Defining Tracers ===

Below is the tracers.xml, where the aerosols as well as their properties are defined. The properties to be defined are listed in the following table.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ tracers.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! moment
| int || specifies which momentum scheme is used (???) || 3
|-
! mode
| char || mode name from AERODYN mode configurations (multiple modes can be given, seperated by a comma) || insol_giant,sol_aitken
|-

! mol_weight
| real || specify the molar mass || 30E-3
|-
! rho
| real || specify the density in terms of <code> unit </code> || 2e3

|-
! unit
| char || specify what unit the aerosol will have || kg-1
|-
! transport
| char || specify transport scheme to be used || hadv52aero
|-
|}

==== tracers.xml ====
<pre class="mw-collapsible mw-collapsed">
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa,sol_acc,sol_coa,mixed_acc,mixed_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,mixed_acc,mixed_coa</mode>
<sol type="real">0.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>
<aerosol id="na">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">22.9898E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="cl">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">35.453E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="h2o">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">18.01528E-3</mol_weight>
<rho type="real">1.E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">off</transport>
</aerosol>
</tracers>
</pre>

=== Defining Modes ===

In the modes.xml the modes which are going to be used in the simulation can be defined. The following .xml contains the same information as Figure 3.1, but in a way the computer can interpret it.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ modes.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! kind
| char || specifies which properties are to be calculated in the model (eg 2mom -> mass mixing ratio and number concentration) || 2mom
|-
! d_gn
| real || median diameter of the lognormal aerosol distribution || 2.0E-6
|-
! sigma_g
| real || standard deviation of the lognormal aerosol distribution || 2.2
|-
! condensation
| int || switch to control if condensation can occur || 0
|-
! icoag
| int || switch to control if coagulation can occur || 0
|-
! shift2larger
| char || prevents mode from getting to large, then shifts size to given mode (mostly used for Aitken mode) || insol_acc
|-
! shift_diam
| real || defines the diameter where the aerosol is shifted to the given mode || 0.08E-6
|-
! shift2mixed
| char || shift to given mode when 5% of mass is liquid || mixed_coa
|-
|}

Sometimes it is necessary for the type of an aerosol to change its given mode if its diameter gets too large or a large amount of condensation occurs. The mass can then be transferred to defined modes, as seen in the table above.

==== modes.xml ====
<pre class="mw-collapsible mw-collapsed">
<modes>
<aerosol id="sol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">0.2E-6</d_gn>
<sigma_g type="real">2.0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_acc</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="sol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_coa</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
</modes>
</pre>

=== Defining Coagulation ===

Here the behaviour of collision and subsequent merging (coagulation) between aerosols can be defined. If for example a solid (insol) aerosol merges with a liquid (sol) aerosol, the result should logically be a mixed aerosol, and so on. This can further be defined for all sizes of aerosols as seen in the example .xml for accumulation and coarse modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ coagulate.xml Parameters
! Parameter || type || description || example
|-
!smallmode id
| char || The aerosol_mode which is gonig to coagulate || insol_acc
|-
!nmodes
| int || Defines the number of modes for which the coagulation preocesses are defined || 5
|-
!bigmode id
| char || Inside angle brackets : coagulation partner of the given aerosol mode. Outside angle brackets: the new mode of the cagulated aerosols. || <bigmode id="sol_acc" type="char">mixed_acc</bigmode>
|-
|}

==== coag.xml ====
<pre class="mw-collapsible mw-collapsed">
<coagulate>
<smallmode id="sol_acc">
<nmodes type="int">6</nmodes>
<bigmode id="sol_acc" type="char">sol_acc</bigmode>
<bigmode id="insol_acc" type="char">mixed_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_acc">
<nmodes type="int">5</nmodes>
<bigmode id="insol_acc" type="char">insol_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_acc">
<nmodes type="int">4</nmodes>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="sol_coa">
<nmodes type="int">3</nmodes>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_coa">
<nmodes type="int">2</nmodes>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_coa">
<nmodes type="int">1</nmodes>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
</coagulate>
</pre>

=== Defining the Model Output ===
In the diagnostics.xml the diagnostic variables that can be written out are defined. Below are some examples, however this is a heavily shortened version of the diagnostics.xml used in ICON-ART.

==== diagnostics.xml ====
<pre class="mw-collapsible mw-collapsed">
<diagnostics>
<aerosol id="diam_insol_acc">
<productDefinitionTemplate type="int">40</productDefinitionTemplate>
<discipline type="int">0</discipline>
<parameterCategory type="int">254</parameterCategory>
<parameterNumber type="int">201</parameterNumber>
<constituentType type="int">62001</constituentType>
</aerosol>
<aerosol id="acc_drydepo">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">6,6,6,6,6,6,192,192,192,192</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
<aerosol id="acc_emiss">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">3,3,3,3,3,3,3,3,3,3</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
</diagnostics>
</pre>

=== Defining the Aerosol Emissions ===

Aerosol emissions can be defined via the aero_emiss.xml. Here you do not define the modes themselves but the distribution of the aerosols. ICON-ART then maps the given distribution on to the best fitting modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ aero_emiss.xml Parameters
! Parameter || type || description || example
|-
! routine id
| char || define the name of the emission routine || dust
|-
! nmodes
| int || number of aerosol modes to be emitted. The "X" in the following is to replaced by the numbers 1 to nmodes. || 3
|-
! d_g0_X
| real|| median diameter weighted by number concentration. Has to be defined for every mode given by nmodes. ||6.445E-7
|-
! d_g3_X
| real || median diameter weighted by mass concentration. Has to be defined for every mode given by nmodes. || 1.500E-6
|-
! rho
| real || Density of the emitted aerosol || 2.2E3
|-
! substances
| char || name of the tracers about to be emitted|| na,cl
|-
|}

====aero_emiss.xml====
<pre class="mw-collapsible mw-collapsed">
<emiss>
<routine id="dust">
<nmodes type="int">3</nmodes>
<d_g0_1 type="real">6.445E-7</d_g0_1>
<d_g3_1 type="real">1.500E-6</d_g3_1>
<sigma_g_1 type="real">1.700E+0</sigma_g_1>
<d_g0_2 type="real">3.454E-6</d_g0_2>
<d_g3_2 type="real">6.700E-6</d_g3_2>
<sigma_g_2 type="real">1.600E+0</sigma_g_2>
<d_g0_3 type="real">8.672E-6</d_g0_3>
<d_g3_3 type="real">1.420E-5</d_g3_3>
<sigma_g_3 type="real">1.500E+0</sigma_g_3>
<rho type="real">2.650E3</rho>
<substances type="char">dust</substances>
</routine>
<routine id="seas_mode1">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">0.100E-6</d_g0_1>
<d_g3_1 type="real">0.433E-6</d_g3_1>
<sigma_g_1 type="real">1.900E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
<routine id="seas_mode2">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">3.000E-6</d_g0_1>
<d_g3_1 type="real">1.268E-5</d_g3_1>
<sigma_g_1 type="real">2.000E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
</emiss>
</pre>

AERODYN

2023-05-03T11:46:49Z

Editor 2: Added explainations and references for Condensation, Nucleation and coagulation

AERODYN (AEROsol DYNamics) is a new aerosol dynamics module used in ICON-ART. With AERODYN, secondary aerosol formations (e.g. the accumulation of SO2 on a volcanic ash particle) can be accounted for.
Aerosol dynamic processes are the processes which change an aerosols properties after it has been released into the atmosphere. This change of properties (omitting chemical reactions) occurs either via condensation or coagulation.
Since it is not feasible to account for every individual aerosol to calculate their movement, coagulation and condensation, AERODYN uses a total of 12 categories for aerosol modes.

== Aerosol Modes in AERODYN ==

Traditionally, There are three categories to account for the aerosol sizes [https://www.sciencedirect.com/science/article/abs/pii/0004698178901968 Whitby et. Al. (1978)] : Aitken mode, accumulation mode and coarse mode. In AERODYN there is also a fourth mode, called giant mode, which accounts for especially large Aerosols, e.g. some species of pollen.

Since condensation can occur on a solid aerosol particle, as well as for a number of other reasons, it is possible to obtain aerosol modes which are a mixture of solid and liquid modes. To account for this, AERODYN combines 4 modes of aerosol size with the 3 modes soluble, insoluble and mixed.
A Visual Representation is given here:

[[File:AERODYNModes.png]]

when also adding the giant mode, the following configurations are possible:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

== Condensation, Nucleation and Accumulation Processes ==
Here is a quick reminder of the different aerosol processes:

* Condensation is the process of a gas turning into a liquid. In practice, some sort of surface, or condensation nucleus is needed to enable the phase change.
* Nucleation is the process of an aerosol particle forming from a gaseous phase by random collisions of the gas molecules. The produced aerosol sizes are in the Aitken mode.
* Accumulation in the Process of the initial nucleus growing in size through collision and deposition Processes.

A schematic overview of the different microphysical aerosol processes can be found in the following Figure from [https://doi.org/10.1016/S1352-2310(00)00239-9 Raes et. Al(2000)]:

[[File:Raes2000.jpg| Overview of Aerosol Processes.]]

In AERODYN, some modes are treated differently with respect to the dynamic processes: Nucleation is only considered for the Aitken mode, and the Giant mode is not affected by condensation. This is done to save computing power while still retaining realism, and since Nucleation of larger Particles without first having Aitken mode Aerosols is highly unlikely, this is a good approximation. Also, as condensation highly prefers smaller modes to the giant mode, this also is a reasonable way to save computing power. For details how the processes are calculated, see [https://doi.org/10.1029/2018RG000615 Riemer et Al. (2003)] and [https://doi.org/10.5194/acp-9-8661-2009 Vogel et. Al. (2009)].

== Defining Aerosols with AERODYN ==

AERODYN is meant to be as flexible as possible, allowing the user to quickly define their own aerosols and then use ICON-ART to simulate their dynamics.
Aerosols are defined in .xml files, which can then be included in the run by specifying their path in the runfile (see [[Input]] for more details)

There are several Types of .xml files for different applications. The most important/most used .xml files are compiled in the following paragraphs.

=== Defining Tracers ===

Below is the tracers.xml, where the aerosols as well as their properties are defined. The properties to be defined are listed in the following table.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ tracers.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! moment
| int || specifies which momentum scheme is used (???) || 3
|-
! mode
| char || mode name from AERODYN mode configurations (multiple modes can be given, seperated by a comma) || insol_giant,sol_aitken
|-

! mol_weight
| real || specify the molar mass || 30E-3
|-
! rho
| real || specify the density in terms of <code> unit </code> || 2e3

|-
! unit
| char || specify what unit the aerosol will have || kg-1
|-
! transport
| char || specify transport scheme to be used || hadv52aero
|-
|}

<pre>
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa,sol_acc,sol_coa,mixed_acc,mixed_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,mixed_acc,mixed_coa</mode>
<sol type="real">0.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>
<aerosol id="na">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">22.9898E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="cl">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">35.453E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="h2o">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">18.01528E-3</mol_weight>
<rho type="real">1.E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">off</transport>
</aerosol>
</tracers>
</pre>

=== Defining Modes ===

In the modes.xml the modes which are going to be used in the simulation can be defined. The following .xml contains the same information as Figure 3.1, but in a way the computer can interpret it.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ modes.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! kind
| char || specifies which properties are to be calculated in the model (eg 2mom -> mass mixing ratio and number concentration) || 2mom
|-
! d_gn
| real || median diameter of the lognormal aerosol distribution || 2.0E-6
|-
! sigma_g
| real || standard deviation of the lognormal aerosol distribution || 2.2
|-
! condensation
| int || switch to control if condensation can occur || 0
|-
! icoag
| int || switch to control if coagulation can occur || 0
|-
! shift2larger
| char || prevents mode from getting to large, then shifts size to given mode (mostly used for Aitken mode) || insol_acc
|-
! shift_diam
| real || defines the diameter where the aerosol is shifted to the given mode || 0.08E-6
|-
! shift2mixed
| char || shift to given mode when 5% of mass is liquid || mixed_coa
|-
|}

Sometimes it is necessary for the type of an aerosol to change its given mode if its diameter gets too large or a large amount of condensation occurs. The mass can then be transferred to defined modes, as seen in the table above.

<pre>
<modes>
<aerosol id="sol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">0.2E-6</d_gn>
<sigma_g type="real">2.0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_acc</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="sol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_coa</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
</modes>
</pre>

=== Defining Coagulation ===

Here the behaviour of collision and subsequent merging (coagulation) between aerosols can be defined. If for example a solid (insol) aerosol merges with a liquid (sol) aerosol, the result should logically be a mixed aerosol, and so on. This can further be defined for all sizes of aerosols as seen in the example .xml for accumulation and coarse modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ coagulate.xml Parameters
! Parameter || type || description || example
|-
!smallmode id
| char || The aerosol_mode which is gonig to coagulate || insol_acc
|-
!nmodes
| int || Defines the number of modes for which the coagulation preocesses are defined || 5
|-
!bigmode id
| char || Inside angle brackets : coagulation partner of the given aerosol mode. Outside angle brackets: the new mode of the cagulated aerosols. || <bigmode id="sol_acc" type="char">mixed_acc</bigmode>
|-
|}

<pre>
<coagulate>
<smallmode id="sol_acc">
<nmodes type="int">6</nmodes>
<bigmode id="sol_acc" type="char">sol_acc</bigmode>
<bigmode id="insol_acc" type="char">mixed_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_acc">
<nmodes type="int">5</nmodes>
<bigmode id="insol_acc" type="char">insol_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_acc">
<nmodes type="int">4</nmodes>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="sol_coa">
<nmodes type="int">3</nmodes>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_coa">
<nmodes type="int">2</nmodes>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_coa">
<nmodes type="int">1</nmodes>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
</coagulate>
</pre>

=== Defining the Model Output ===
In the diagnostics.xml the diagnostic variables that can be written out are defined. Below are some examples, however this is a heavily shortened version of the diagnostics.xml used in ICON-ART.

<pre>
<diagnostics>
<aerosol id="diam_insol_acc">
<productDefinitionTemplate type="int">40</productDefinitionTemplate>
<discipline type="int">0</discipline>
<parameterCategory type="int">254</parameterCategory>
<parameterNumber type="int">201</parameterNumber>
<constituentType type="int">62001</constituentType>
</aerosol>
<aerosol id="acc_drydepo">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">6,6,6,6,6,6,192,192,192,192</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
<aerosol id="acc_emiss">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">3,3,3,3,3,3,3,3,3,3</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
</diagnostics>
</pre>

=== Defining the Aerosol Emissions ===

Aerosol emissions can be defined via the aero_emiss.xml. Here you do not define the modes themselves but the distribution of the aerosols. ICON-ART then maps the given distribution on to the best fitting modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ aero_emiss.xml Parameters
! Parameter || type || description || example
|-
! routine id
| char || define the name of the emission routine || dust
|-
! nmodes
| int || number of aerosol modes to be emitted. The "X" in the following is to replaced by the numbers 1 to nmodes. || 3
|-
! d_g0_X
| real|| median diameter weighted by number concentration. Has to be defined for every mode given by nmodes. ||6.445E-7
|-
! d_g3_X
| real || median diameter weighted by mass concentration. Has to be defined for every mode given by nmodes. || 1.500E-6
|-
! rho
| real || Density of the emitted aerosol || 2.2E3
|-
! substances
| char || name of the tracers about to be emitted|| na,cl
|-
|}

<pre>
<emiss>
<routine id="dust">
<nmodes type="int">3</nmodes>
<d_g0_1 type="real">6.445E-7</d_g0_1>
<d_g3_1 type="real">1.500E-6</d_g3_1>
<sigma_g_1 type="real">1.700E+0</sigma_g_1>
<d_g0_2 type="real">3.454E-6</d_g0_2>
<d_g3_2 type="real">6.700E-6</d_g3_2>
<sigma_g_2 type="real">1.600E+0</sigma_g_2>
<d_g0_3 type="real">8.672E-6</d_g0_3>
<d_g3_3 type="real">1.420E-5</d_g3_3>
<sigma_g_3 type="real">1.500E+0</sigma_g_3>
<rho type="real">2.650E3</rho>
<substances type="char">dust</substances>
</routine>
<routine id="seas_mode1">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">0.100E-6</d_g0_1>
<d_g3_1 type="real">0.433E-6</d_g3_1>
<sigma_g_1 type="real">1.900E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
<routine id="seas_mode2">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">3.000E-6</d_g0_1>
<d_g3_1 type="real">1.268E-5</d_g3_1>
<sigma_g_1 type="real">2.000E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
</emiss>
</pre>

File:Raes2000.jpg

2023-05-03T11:37:23Z

Editor 2: https://doi.org/10.1016/S1352-2310(00)00239-9 Figure 1 Scheme of the microphysical processes that influence the size distribution and chemical composition of the atmospheric aerosol. The scheme highlights the large range of sizes that are involved in t...

== Summary ==
https://doi.org/10.1016/S1352-2310(00)00239-9 Figure 1
Scheme of the microphysical processes that influence the size distribution and chemical composition of the atmospheric aerosol. The scheme highlights the large range of sizes that are involved in the formation and evolution of aerosol particles, and how aerosols participate in atmospheric chemical processes through homogeneous, heterogeneous and in-cloud reactions.

AERODYN

2023-04-18T11:41:58Z

Editor 2: fixed some typos

AERODYN (AEROsol DYNamics) is a new aerosol dynamics module used in ICON-ART. With AERODYN, secondary aerosol formations (e.g. the accumulation of SO2 on a volcanic ash particle) can be accounted for.
Aerosol dynamic processes are the processes which change an aerosols properties after it has been released into the atmosphere. This change of properties (omitting chemical reactions) occurs either via condensation or coagulation.
Since it is not feasible to account for every individual aerosol to calculate their movement, coagulation and condensation, AERODYN uses a total of 12 categories for aerosol modes.

== Aerosol Modes in AERODYN ==

Traditionally, There are three categories to account for the aerosol sizes [https://www.sciencedirect.com/science/article/abs/pii/0004698178901968 Whitby et. Al. (1978)] : Aitken mode, accumulation mode and coarse mode. In AERODYN there is also a fourth mode, called giant mode, which accounts for especially large Aerosols, e.g. some species of pollen.

Since condensation can occur on a solid aerosol particle, as well as for a number of other reasons, it is possible to obtain aerosol modes which are a mixture of solid and liquid modes. To account for this, AERODYN combines 4 modes of aerosol size with the 3 modes soluble, insoluble and mixed.
A Visual Representation is given here:
[[File:AERODYNModes.png]]

when also adding the giant mode, the following configurations are possible:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

== Defining Aerosols with AERODYN ==

AERODYN is meant to be as flexible as possible, allowing the user to quickly define their own aerosols and then use ICON-ART to simulate their dynamics.
Aerosols are defined in .xml files, which can then be included in the run by specifying their path in the runfile (see [[Input]] for more details)

There are several Types of .xml files for different applications. The most important/most used .xml files are compiled in the following paragraphs.

=== Defining Tracers ===

Below is the tracers.xml, where the aerosols as well as their properties are defined. The properties to be defined are listed in the following table.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ tracers.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! moment
| int || specifies which momentum scheme is used (???) || 3
|-
! mode
| char || mode name from AERODYN mode configurations (multiple modes can be given, seperated by a comma) || insol_giant,sol_aitken
|-

! mol_weight
| real || specify the molar mass || 30E-3
|-
! rho
| real || specify the density in terms of <code> unit </code> || 2e3

|-
! unit
| char || specify what unit the aerosol will have || kg-1
|-
! transport
| char || specify transport scheme to be used || hadv52aero
|-
|}

<pre>
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa,sol_acc,sol_coa,mixed_acc,mixed_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,mixed_acc,mixed_coa</mode>
<sol type="real">0.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>
<aerosol id="na">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">22.9898E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="cl">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">35.453E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="h2o">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">18.01528E-3</mol_weight>
<rho type="real">1.E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">off</transport>
</aerosol>
</tracers>
</pre>

=== Defining Modes ===

In the modes.xml the modes which are going to be used in the simulation can be defined. The following .xml contains the same information as Figure 3.1, but in a way the computer can interpret it.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ modes.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! kind
| char || specifies which properties are to be calculated in the model (eg 2mom -> mass mixing ratio and number concentration) || 2mom
|-
! d_gn
| real || median diameter of the lognormal aerosol distribution || 2.0E-6
|-
! sigma_g
| real || standard deviation of the lognormal aerosol distribution || 2.2
|-
! condensation
| int || switch to control if condensation can occur || 0
|-
! icoag
| int || switch to control if coagulation can occur || 0
|-
! shift2larger
| char || prevents mode from getting to large, then shifts size to given mode (mostly used for Aitken mode) || insol_acc
|-
! shift_diam
| real || defines the diameter where the aerosol is shifted to the given mode || 0.08E-6
|-
! shift2mixed
| char || shift to given mode when 5% of mass is liquid || mixed_coa
|-
|}

Sometimes it is necessary for the type of an aerosol to change its given mode if its diameter gets too large or a large amount of condensation occurs. The mass can then be transferred to defined modes, as seen in the table above.

<pre>
<modes>
<aerosol id="sol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">0.2E-6</d_gn>
<sigma_g type="real">2.0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_acc</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="sol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_coa</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
</modes>
</pre>

=== Defining Coagulation ===

Here the behaviour of collision and subsequent merging (coagulation) between aerosols can be defined. If for example a solid (insol) aerosol merges with a liquid (sol) aerosol, the result should logically be a mixed aerosol, and so on. This can further be defined for all sizes of aerosols as seen in the example .xml for accumulation and coarse modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ coagulate.xml Parameters
! Parameter || type || description || example
|-
!smallmode id
| char || The aerosol_mode which is gonig to coagulate || insol_acc
|-
!nmodes
| int || Defines the number of modes for which the coagulation preocesses are defined || 5
|-
!bigmode id
| char || Inside angle brackets : coagulation partner of the given aerosol mode. Outside angle brackets: the new mode of the cagulated aerosols. || <bigmode id="sol_acc" type="char">mixed_acc</bigmode>
|-
|}

<pre>
<coagulate>
<smallmode id="sol_acc">
<nmodes type="int">6</nmodes>
<bigmode id="sol_acc" type="char">sol_acc</bigmode>
<bigmode id="insol_acc" type="char">mixed_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_acc">
<nmodes type="int">5</nmodes>
<bigmode id="insol_acc" type="char">insol_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_acc">
<nmodes type="int">4</nmodes>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="sol_coa">
<nmodes type="int">3</nmodes>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_coa">
<nmodes type="int">2</nmodes>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_coa">
<nmodes type="int">1</nmodes>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
</coagulate>
</pre>

=== Defining the Model Output ===
In the diagnostics.xml the diagnostic variables that can be written out are defined. Below are some examples, however this is a heavily shortened version of the diagnostics.xml used in ICON-ART.

<pre>
<diagnostics>
<aerosol id="diam_insol_acc">
<productDefinitionTemplate type="int">40</productDefinitionTemplate>
<discipline type="int">0</discipline>
<parameterCategory type="int">254</parameterCategory>
<parameterNumber type="int">201</parameterNumber>
<constituentType type="int">62001</constituentType>
</aerosol>
<aerosol id="acc_drydepo">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">6,6,6,6,6,6,192,192,192,192</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
<aerosol id="acc_emiss">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">3,3,3,3,3,3,3,3,3,3</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
</diagnostics>
</pre>

=== Defining the Aerosol Emissions ===

Aerosol emissions can be defined via the aero_emiss.xml. Here you do not define the modes themselves but the distribution of the aerosols. ICON-ART then maps the given distribution on to the best fitting modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ aero_emiss.xml Parameters
! Parameter || type || description || example
|-
! routine id
| char || define the name of the emission routine || dust
|-
! nmodes
| int || number of aerosol modes to be emitted. The "X" in the following is to replaced by the numbers 1 to nmodes. || 3
|-
! d_g0_X
| real|| median diameter weighted by number concentration. Has to be defined for every mode given by nmodes. ||6.445E-7
|-
! d_g3_X
| real || median diameter weighted by mass concentration. Has to be defined for every mode given by nmodes. || 1.500E-6
|-
! rho
| real || Density of the emitted aerosol || 2.2E3
|-
! substances
| char || name of the tracers about to be emitted|| na,cl
|-
|}

<pre>
<emiss>
<routine id="dust">
<nmodes type="int">3</nmodes>
<d_g0_1 type="real">6.445E-7</d_g0_1>
<d_g3_1 type="real">1.500E-6</d_g3_1>
<sigma_g_1 type="real">1.700E+0</sigma_g_1>
<d_g0_2 type="real">3.454E-6</d_g0_2>
<d_g3_2 type="real">6.700E-6</d_g3_2>
<sigma_g_2 type="real">1.600E+0</sigma_g_2>
<d_g0_3 type="real">8.672E-6</d_g0_3>
<d_g3_3 type="real">1.420E-5</d_g3_3>
<sigma_g_3 type="real">1.500E+0</sigma_g_3>
<rho type="real">2.650E3</rho>
<substances type="char">dust</substances>
</routine>
<routine id="seas_mode1">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">0.100E-6</d_g0_1>
<d_g3_1 type="real">0.433E-6</d_g3_1>
<sigma_g_1 type="real">1.900E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
<routine id="seas_mode2">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">3.000E-6</d_g0_1>
<d_g3_1 type="real">1.268E-5</d_g3_1>
<sigma_g_1 type="real">2.000E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
</emiss>
</pre>

Output

2023-04-17T12:02:58Z

Editor 2: added link to AERODYN article

__TOC__

== General Remarks ==

In principle, output of ICON-ART variables works the same way as for ICON variables. As described in , the following five quantities of the output have to be specified:

* The time interval between two model outputs.
* The name of the output file.
* The name of the variable(s) and/or variable group(s).
* The type of vertical output grid.
* The type of horizontal output grid.

For the best results it is recommended to use NETCDF output on the icosahedral grid which ICON-ART is using. However in some applications remapping the grid to a latitude-longitude grid may be required, which can be set via the <code>remap</code> option. A corresponding output namelist for sea salt on model levels can be seen here:

<pre>NAMELIST EXAMPLE
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = 1 ! write output for domain 1
output_start = "JJJJ-MM-DDTHH:MM:SSZ" !put date in
output_end = "JJJJ-MM-DDTHH:MM:SSZ" !put date in
output_interval = "PT1H" ! \href{ISO8601}{https://en.wikipedia.org/wiki/ISO_8601}
steps_per_file = 1 ! max. num. of time steps within one file
mode = 1 ! 1: forecast mode (relative t-axis)
include_last = .TRUE. ! include the last time step
output_filename = '<INSERTFILENAME>' ! file name base
ml_varlist = 'seasa','seasb','seasc',
'seasa0','seasb0','seasc0'
remap = 1 ! output is transferred to lat long grid
reg_lon_def = -180.,0.5,179.5 !start, incr., end, in deg.
reg_lat_def = 90.,-0.5, -90. !start, incr., end, in deg.</pre>

There is an option to obtain all diagnostic Variables of a certain Group without having to specifying all of them. For example, you may use the group ART_DIAGNOSTICS.

To include a group of Variables in the output file change the namelist variable ml_varlist from the example above to the following:

<pre>ml_varlist = 'group:ART_AEROSOL'</pre>
The output variables that are associated to this group will be written to the output file. You can check the groups of output variables in this [[#OutputTable | Table]] .

== Aerosol Naming Conventions ==
The following table contains an overview of the possible output variables.

There are several ways to choose the Naming of the output variables, depending on your application

* '''Externally mixed Aerosols:''' : The Tracers for Dust, Seasalt, Ash and Soot are combined with the three Possible modes a, b and c, which correspond to the different size bins of the particles <div id="OutputTable"></div>

::{| class="wikitable" style="text-align:left;"
|+ Externally mixed Tracer modes
!|| dust||seasalt ||ash ||soot
|-
!a
| dusta ||seasa ||asha ||soota
|-
!b
| dustb ||seasb ||ashb ||-
|-
!c
| dustc||seasc ||ashc ||-
|-
|}

* '''Internally mixed Aerosols ([[AERODYN]]):''' Here a tracer is defined in a different way, with the goal being to have a more flexible framework for various applications. In this framework modes are created in a different way, as illustrated int the table below:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

The modes are then combined with The Tracername to obtain the name of the Variable using <code>varname = 'Tracer' + '_' + 'mode from Table'</code>.
Example : <code> dust_insol_acc </code>

* '''Monodisperse Aerosols'''

== Available Output Variables ==
The following Table contains an overview over the diagnostic Icon-ART Variables. Expressions in Brackets are Placeholders which can be used to construct the name of the actual variables:

[aeronet wavelength] => [340, 380, 440, 500, 550, 675, 870, 1020, 1064]

[ceilo_wavelength] => [355,532,1064]

[pollen] => [ALNU,BETU,...] to be defined in diagnostics.xml

{| class="wikitable"
|+ Output Overview
|-
!
! varname
! groups
! unit
! descripition
! namelist switch
! required xml
|-
!rowspan="19" style="vertical-align:top;" | Aerosols
| diam_[mode]
| ART_DIAGNOSTICS
| m
| with AERODYN : aerosol diameter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| diam_[aerosol][mode]
| ART_DIAGNOSTICS
| m
| WITHOUT AERODYN: aerosol diameter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| aod_[aerosol]_[aeronet wavelength]nm
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| Layer-1
| [AEROSOL] optical depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| bsc_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS
| m-1 sr-1
| [AEROSOL] backscatter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ceil_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| m-1 sr-1
| [AEROSOL] Attenuated Backscatter Ceilometer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| sat_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS
| m-1 sr-1
| [AEROSOL] Attenuated Backscatter Satellite
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_so4_sol
| ART_DIAGNOSTICS
| layer-1
| SO4 sol Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_insol
| ART_DIAGNOSTICS
| layer-1
| Ash insol Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_mixed
| ART_DIAGNOSTICS
| layer-1
| Ash mixed Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_giant
| ART_DIAGNOSTICS
| layer-1
| Ash giant Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ustar_thres
| ART_ROUTINE_DIAG
| m s-1
| threshold friction velocity for dust emission'
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ustar
| ART_ROUTINE_DIAG
| m s-1
| Friction velocity
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_drydepo_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated dry deposition of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_sedim_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated sedimentation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_gscp_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition by grid scale precipitation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_con_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition by convective precipitation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_rrsfc_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition of tracer if precipitation reaches surface
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| emiss_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2 s-1
| emission of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_emiss_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated emission of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
!rowspan="9" style="vertical-align:top;"| Pollen
| [pollen]rprec
| ART_ROUTINE_DIAG
| m-2
| precipitation reservoir of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]reso
| ART_ROUTINE_DIAG
| m-2
| Pollen reservoir (previous timestep) of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]ress
| ART_ROUTINE_DIAG
| m-2
| Pollen reservoir (daily sum) of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]sdes
| ART_ROUTINE_DIAG
| -
| State of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]ctsum
| ART_ROUTINE_DIAG
| K
| Cumulated weighted 2m temperature sum of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisn
| ART_ROUTINE_DIAG
| days
| Number of days since start of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisl
| ART_ROUTINE_DIAG
| days
| length of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisa
| ART_ROUTINE_DIAG
| days
| Number of days since the start of pollen season of [pollen]. if present day is out of the season: length of current season
| REQUIRES diagnostics.xml
|
|-
| [pollen]fe
| ART_ROUTINE_DIAG
| m-2 s-1
| Emission flux of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
!rowspan="18" style="vertical-align:top;" | Chemistry
| reac_rates
| ART_DIAGNOSTICS
| s-1
| MECCA reaction rates
| lart_mecca=True, lart_diag_out=True
|
|-
| art_o3
| kg/kg
| Ozone mass mixing ratio
| lart_chem =True, lart_diag_out=True
|
|
|-
| OH_Nconc
| # / cm3
| OH number concentration
| lart_chem =TRUE
|
|
|-
| photo
| -
| s-1
| photolysis rates
| lart_chem=TRUE, lart_mecca=TRUE
|
|-
| art_full_chemistry_o3_col
| -
| DU
| Ozone column
| lart_chem=TRUE, lart_mecca=TRUE
|
|-
| sts_liqsur
| ART_DIAGNOSTICS
| cm2 cm-3
| liquid area density of STS
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| cgaml
| ART_DIAGNOSTICS
| -
| STS uptake coefficient of the reaction
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| dens_ice
| ART_DIAGNOSTICS
| m-3
| number density of ice particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_ice
| ART_DIAGNOSTICS
| m
| radius of ice particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_STS
| ART_DIAGNOSTICS
| m
| radius of STS particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| dens_NAT
| ART_DIAGNOSTICS
| m-3
| number density of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_NAT
| ART_DIAGNOSTICS
| m
| radius of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| HNO3_Nconc_s
| ART_DIAGNOSTICS
| cm-3
| number concentration of HNO3 in NAT
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| HNO3_Nconc_l
| ART_DIAGNOSTICS
| cm-3
| number concentration of HNO3 in STS
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| ice_vmr_Marti
| ART_DIAGNOSTICS
| mol mol-1
| volume mixing ratio of solid water by Marti and Mauersberger
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| NAT_sedi_rel_difference
| ART_DIAGNOSTICS
| -
| relative difference of NAT mass bef and aft sedi (aft - bef) * 2 / (aft + bef)
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| NAT_sedi_vel
| ART_DIAGNOSTICS
| m s-1
| sedimentation velocity of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| art_so2_col
| ART_DIAGNOSTICS
| DU
| SO2 column
| lat_chem=TRUE , lart_chemtracer=TRUE
|
|-
!rowspan="3" style="vertical-align:top;"| Radioactive Tracer Diagnostics
| wet deposition of xml defined tracer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-2
| wet deposition of xml defined tracer
| lart_aerosol=True and iart_radioact=1
|
|-
| dry deposition of xml defined tracer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-2
| dry deposition of xml defined tracer
| lart_aerosol=True and iart_radioact=1
|
|-
| Averaged air concentration of xml defined traer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-3
| Averaged air concentration of xml defined traer
| lart_aerosol=True and iart_radioact=1
|
|-
!rowspan="4" style="vertical-align:top;"| FPLUME Output
| plume_height
| ART_FPLUME
| m
| plume height
| iart_fplume/=0
|
|-
| plume_MFR
| ART_FPLUME
| kg s-1
| plume MFR
| iart_fplume/=0
|
|-
| MER_transport
| ART_FPLUME
| kg s-1
| Amount of very fine ash for transport
| iart_fplume/=0
|
|-
| solution_with
| ART_FPLUME
| -
| FPlume off, Mastin, or FPlume
| iart_fplume/=0
|
|}

Input

2023-04-17T12:01:33Z

Editor 2: added link to AERODYN article

== 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
|---
| <code>cart_chemtracer_xml</code>
| Switch for simple OH chemistry
| <code>lart_chemtracer</code>
| .FALSE.
|-
| <code>cart_mecca_xml</code>
| Switch for kpp chemistry
| <code>lart_mecca</code>
| .FALSE.
|-
| <code>cart_pntSrc_xml</code>
| Enables addition of point sources
| <code>lart_pntSrc</code>
| .FALSE.
|-
| <code>cart_aerosol_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|-
| <code>cart_modes_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| .FALSE.
|-
| <code>cart_diagnostics_xml</code>
| Enables diagnostic output fields
| <code>lart_diag_out</code>
| .FALSE.
|-
| <code>cart_pntSrc_xml</code>
| Enables creation of point sources emitting given Aerosols at a given rate
| <code>lart_pntSrc </code>
| .FALSE.
|-
| <code>cart_emiss_xml_file</code>
| XML File for emission metadata
| -
| -
|-
| <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>

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.

<pre><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></pre>

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.
<pre>
<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>
</pre>

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">

{| 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
|}

=== Obtaining Input Data ===

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

[[How to generate input data]]

[[How to download input data]]

== Running a Limmited 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.

AERODYN

2023-04-17T11:55:49Z

Editor 2: /* Defining Aerosols with AERODYN */ added a lot of detailabout the individual AERODYN .xml's

AERODYN (AEROsol DYNamics) is a new aerosol dynamics module used in ICON-ART. With AERODYN, secondary aerosol formations (e.g. the accumulation of SO2 on a volcanic ash particle) can be accounted for.
Aerosol dynamic processes are the processes which change an aerosols properties after it has been released into the atmosphere. This change of properties (omitting chemical reactions) occurs either via condensation or coagulation.
Since it is not feasible to account for every individual aerosol to calculate their movement, AERODYN uses a total of 12 categories for aerosol modes.

== Aerosol Modes in AERODYN ==

Traditionally, There are three categories to account for the aerosol sizes [https://www.sciencedirect.com/science/article/abs/pii/0004698178901968 Whitby et. Al. (1978)] : Aitken mode, accumulation mode and coarse mode. In AERODYN there is also a fourth mode, called giant mode, which accounts for especially large Aerosols, e.g. some species of pollen.

Since condensation can occur on a solid aerosol particle, as well as for a number of other reasons, it is possible to obtain aerosol modes which are a mixture of solid and liquid modes. To account for this, AERODYN combines 4 modes of aerosol size with the 3 modes soluble, insoluble and mixed.
A Visual Representation is given here:
[[File:AERODYNModes.png]]

when also adding the giant mode, the following configurations are possible:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

== Defining Aerosols with AERODYN ==

AERODYN is meant to be as flexible as possible, allowing the user to quickly define their own aerosols and then use ICON-ART to simulate their dynamics.
Aerosols are defined in .xml files, which can then be included in the run by specifying their path in the runfile (see [[Input]] for more details)

There are several Types of .xml files for different applications. The most important/most used .xml files are compiled in the following paragraphs.

=== Defining Tracers ===

Below is ther tracers.xml, where the aerosols as well as their properties are defined. The properties to be defined are listed in the following table.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ tracers.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! moment
| int || specifies which momentum scheme is used (???) || 3
|-
! mode
| char || mode name from AERODYN mode configurations (multiple modes can be given, seperated by a comma) || insol_giant,sol_aitken
|-

! mol_weight
| real || specify the molar mass || 30E-3
|-
! rho
| real || specify the density in terms of <code> unit </code> || 2e3

|-
! unit
| char || specify what unit the aerosol will have || kg-1
|-
! transport
| char || specify transport scheme to be used || hadv52aero
|-
|}

<pre>
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa,sol_acc,sol_coa,mixed_acc,mixed_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,mixed_acc,mixed_coa</mode>
<sol type="real">0.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>
<aerosol id="na">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">22.9898E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="cl">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa,mixed_acc,mixed_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">35.453E-3</mol_weight>
<rho type="real">2.2E+3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="h2o">
<moment type="int">3</moment>
<mode type="char">sol_acc,sol_coa</mode>
<sol type="real">1.</sol>
<mol_weight type="real">18.01528E-3</mol_weight>
<rho type="real">1.E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">off</transport>
</aerosol>
</tracers>
</pre>

=== Defining Modes ===

In the modes.xml the modes whiche are going to be used in the simulation can be defined. The following .xml contains the same information as Figure 3.1, but in a way the computer can interpret it.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ modes.xml Parameters
! Parameter || type || description || example
|-
! aerosol id
| char ||specifies name of the aerosol || "my_first_aerosol"
|-
! kind
| char || specifies which properties are to be calculated in the model (eg 2mom -> mass mixing ratio and number concentration) || 2mom
|-
! d_gn
| real || median diameter of the lognormal aerosol distribution || 2.0E-6
|-
! sigma_g
| real || standard deviation of the lognormal aerosol distribution || 2.2
|-
! condensation
| int || switch to control if condensation can occur || 0
|-
! icoag
| int || switch to control if coagulation can occur || 0
|-
! shift2larger
| char || prevents mode from getting to large, then shifts size to given mode (mostly used for Aitken mode) || insol_acc
|-
! shift_diam
| real || defines the diameter where the aerosol is shifted to the given mode || 0.08E-6
|-
! shift2mixed
| char || shift to given mode when 5% of mass is liquid || mixed_coa
|-
|}

Sometimes it is necessary for the type of an aerosol to change its given mode if its diameter gets too large ore a large amount of condensation occurs. The mass can then be trensferred to defined modes, as seen in the table above.

<pre>
<modes>
<aerosol id="sol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">0.2E-6</d_gn>
<sigma_g type="real">2.0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_acc</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_acc">
<kind type="char">2mom</kind>
<d_gn type="real">6.445E-7</d_gn>
<sigma_g type="real">1.700E+0</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="sol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="insol_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<shift2mixed type="char">mixed_coa</shift2mixed>
<icoag type="int">1</icoag>
</aerosol>
<aerosol id="mixed_coa">
<kind type="char">2mom</kind>
<d_gn type="real">2.0E-6</d_gn>
<sigma_g type="real">2.2</sigma_g>
<condensation type="int">0</condensation>
<icoag type="int">1</icoag>
</aerosol>
</modes>
</pre>

=== Defining Coagulation ===

Here the behaviour of collision and subsequent merging (coagulation) between aerosols can be defined. If for example a solid (insol) aerosol merges with a liquid (sol) aerosol, the result should logically be a mixed aerosol, and so on. This can further be defined for all sizes of aerosols as seen in the example .xml for accumulation and coarse modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ coagulate.xml Parameters
! Parameter || type || description || example
|-
!smallmode id
| char || The aerosol_mode which is gonig to coagulate || insol_acc
|-
!nmodes
| int || Defines the number of modes for which the coagulation preocesses are defined || 5
|-
!bigmode id
| char || Inside angle brackets : coagulation partner of the given aerosol mode. Outside angle brackets: the new mode of the cagulated aerosols. || <bigmode id="sol_acc" type="char">mixed_acc</bigmode>
|-
|}

<pre>
<coagulate>
<smallmode id="sol_acc">
<nmodes type="int">6</nmodes>
<bigmode id="sol_acc" type="char">sol_acc</bigmode>
<bigmode id="insol_acc" type="char">mixed_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_acc">
<nmodes type="int">5</nmodes>
<bigmode id="insol_acc" type="char">insol_acc</bigmode>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_acc">
<nmodes type="int">4</nmodes>
<bigmode id="mixed_acc" type="char">mixed_acc</bigmode>
<bigmode id="sol_coa" type="char">mixed_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="sol_coa">
<nmodes type="int">3</nmodes>
<bigmode id="sol_coa" type="char">sol_coa</bigmode>
<bigmode id="insol_coa" type="char">mixed_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="insol_coa">
<nmodes type="int">2</nmodes>
<bigmode id="insol_coa" type="char">insol_coa</bigmode>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
<smallmode id="mixed_coa">
<nmodes type="int">1</nmodes>
<bigmode id="mixed_coa" type="char">mixed_coa</bigmode>
</smallmode>
</coagulate>
</pre>

=== Defining the Model Output ===
In the diagnostics.xml the diagnostic variables that can be written out are defined. Below are some examples, however this is a heavily shortened version of the diagnostics.xml used in ICON-ART.

<pre>
<diagnostics>
<aerosol id="diam_insol_acc">
<productDefinitionTemplate type="int">40</productDefinitionTemplate>
<discipline type="int">0</discipline>
<parameterCategory type="int">254</parameterCategory>
<parameterNumber type="int">201</parameterNumber>
<constituentType type="int">62001</constituentType>
</aerosol>
<aerosol id="acc_drydepo">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">6,6,6,6,6,6,192,192,192,192</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
<aerosol id="acc_emiss">
<tracername_list type="char">dust_insol_acc,dust_insol_coa,na_sol_acc,na_sol_coa,cl_sol_acc,cl_sol_coa,nmb_sol_acc,nmb_sol_coa,nmb_insol_acc,nmb_insol_coa</tracername_list>
<parameterNumber_list type="char">3,3,3,3,3,3,3,3,3,3</parameterNumber_list>
<productDefinitionTemplate_list type="char">67,67,67,67,67,67,67,67,67,67</productDefinitionTemplate_list>
<typeOfStatisticalProcessing type="int">1</typeOfStatisticalProcessing>
<bitsPerValue type="int">32</bitsPerValue>
<typeOfDistributionFunction type="int">8</typeOfDistributionFunction>
<numberOfModeOfDistribution type="int">3</numberOfModeOfDistribution>
<numberOfDistributionFunctionParameters type="int">2</numberOfDistributionFunctionParameters>
</aerosol>
</diagnostics>
</pre>

=== Defining the Aerosol Emissions ===

Aerosol emissions can be defined via the aero_emiss.xml. Here you do not define the modes themselves but the distribution of the aerosols. ICON-ART then maps the given distribution on to the best fitting modes.

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ aero_emiss.xml Parameters
! Parameter || type || description || example
|-
! routine id
| char || define the name of the emission routine || dust
|-
! nmodes
| int || number of aerosol modes to be emitted. The "X" in the following is to replaced by the numbers 1 to nmodes. || 3
|-
! d_g0_X
| real|| median diameter weighted by number concentration. Has to be defined for every mode given by nmodes. ||6.445E-7
|-
! d_g3_X
| real || median diameter weighted by mass concentration. Has to be defined for every mode given by nmodes. || 1.500E-6
|-
! rho
| real || Density of the emitted aerosol || 2.2E3
|-
! substances
| char || name of the tracers about to be emitted|| na,cl
|-
|}

<pre>
<emiss>
<routine id="dust">
<nmodes type="int">3</nmodes>
<d_g0_1 type="real">6.445E-7</d_g0_1>
<d_g3_1 type="real">1.500E-6</d_g3_1>
<sigma_g_1 type="real">1.700E+0</sigma_g_1>
<d_g0_2 type="real">3.454E-6</d_g0_2>
<d_g3_2 type="real">6.700E-6</d_g3_2>
<sigma_g_2 type="real">1.600E+0</sigma_g_2>
<d_g0_3 type="real">8.672E-6</d_g0_3>
<d_g3_3 type="real">1.420E-5</d_g3_3>
<sigma_g_3 type="real">1.500E+0</sigma_g_3>
<rho type="real">2.650E3</rho>
<substances type="char">dust</substances>
</routine>
<routine id="seas_mode1">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">0.100E-6</d_g0_1>
<d_g3_1 type="real">0.433E-6</d_g3_1>
<sigma_g_1 type="real">1.900E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
<routine id="seas_mode2">
<nmodes type="int">1</nmodes>
<d_g0_1 type="real">3.000E-6</d_g0_1>
<d_g3_1 type="real">1.268E-5</d_g3_1>
<sigma_g_1 type="real">2.000E+0</sigma_g_1>
<rho type="real">2.2E3</rho>
<substances type="char">na,cl</substances>
</routine>
</emiss>
</pre>

AERODYN

2023-04-04T10:57:28Z

Editor 2: Created first draft of Page

File:AERODYNModes.png

2023-04-04T09:40:45Z

Editor 2: Figure describing the combination of size modes and their composition from Muser et al. (2020)

== Summary ==
Figure describing the combination of size modes and their composition from Muser et al. (2020)

File:Soot.gif

2023-03-23T08:57:20Z

Editor 2: Editor 2 uploaded a new version of File:Soot.gif

== Summary ==
Icon-art example of global fire soot movement

Die Animation zeigt eine die vertikal integrierte Rußsäule von Vegetationsbränden global simuliert mit ICON-ART. Die Simulation startet am 8. September 2020 und dauert 7 Tage. Zu diesem Zeitpunkt gab es gravierende Vegetationsbrände in Kalifornien, aber auch in Zentralafrika und Südamerika hat es starke Brände gegeben.

File:Raikoke SO2.gif

2023-03-23T08:53:29Z

Editor 2: Editor 2 uploaded a new version of File:Raikoke SO2.gif

== Summary ==
SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. The isosurface of a constant gas concentration of 100 µg per kg air is displayed in the animation.

File:Bluemarble.gif

2023-03-23T08:50:56Z

Editor 2: Editor 2 uploaded a new version of File:Bluemarble.gif

== Summary ==
The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. The Aerosol Optical Thickness is a measure of the opacity of the atmosphere. Simulation performed by the German Weather Service.

Main Page

2023-03-09T10:13:12Z

Editor 2: /* ICON-ART Application Examples */ removed link to article list

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"

|-valign="middle" height="75" bgcolor="##169088;" align="center"
|<p><font color="#FFFFFF" size="+2">'''ICON-ART User guide'''</font></p>

|}
<strong>Welcome to the ICON-ART Wiki!</strong>
ICON-ART is a state-of-the-science seamless model system for the whole atmosphere (physics and composition) that comprises the key components of the next generation Earth system model in Germany. ICON is a global weather and climate model that solves the full three-dimensional non-hydrostatic and compressible Navier-Stokes equations on an icosahedral grid and allows seamless predictions from local to global scales. Aerosol and Reactive Trace gases (ART), as a submodule of ICON, supplements the model by including emissions, transport, gas phase chemistry and aerosol dynamics in the troposphere and stratosphere (as seen in [[#ART-capabilitie|Capabilities of ICON-ARTs]]).
<gallery widths=600px heights=400px>

File:ART-capabilities.png|none|alt=Capabilities of ICON-ART and how they relate to each other.|Capabilities of ICON-ART and how they relate to each other.

</gallery>

<strong>ICON-ART Wiki is under construction!</strong>

ICON-ART (Aerosol and Reactive Trace gases interactions) is a sub-module of the ICON Model and can be used to simulate emissions, transport, gas phase chemistry, and aerosol dynamics in the troposphere and stratosphere. Before using ICON-ART you need some experience using the ICON model, and to make best use of the articles on this wiki some fluency with using ICON is required. Further information about the usage of ICON can be found in the [https://www.dwd.de/EN/ourservices/nwv_icon_tutorial/pdf_volume/icon_tutorial2020_en.html:official ICON Model Tutorial].

{|border="1" width="925px" bordercolor="#000000" cellspacing="0" cellpadding="5"
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|style="width: 30%"| <p><font color="#FFFFFF" size="+1">'''[[:Getting Started]]'''</font></p>
|style="width: 70%"| Contains all the necessary information to get started using ICON-ART.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Input]]'''</font></p>
|An overview about which Variables to set and files to prepare to run an ICON-ART simulation.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Namelist]]'''</font></p>
|An overview about the ART Namelist Variables which can be set in the runfile to control the parameters of the ICON-ART run.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Output]]'''</font></p>
|Summarizes how to create model output files containing the desired variables for further analysis.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Postprocessing]]'''</font></p>
|A brief overview on how to further analyze and visualise the output data.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1"> '''[[:Programming ART]]'''</font></p>
|A short introduction to modifying ICON_ART, for example create a new diagnostic.
|-valign="middle" height="60" bgcolor="##169088;" align="left"
|<p><font color="#FFFFFF" size="+1">'''[[:Tutorial Examples]]'''</font></p>
|An assortment of Tutorial slides with some examples and a general overview of ICON-ART.
|}

== ICON-ART Application Examples ==
<gallery mode="slideshow" align="left" >
File:Bluemarble.gif|The Aerosol Optical Thickness due to mineral dust during a Saharan dust event in Europe from 14-03-22 to 19-03-22. |alt=alt language
File:Raikoke_SO2.gif|SO2 cloud of the Raikoke eruption in June 2019, simulated with ICON-ART. |alt=alt language
File: Soot.gif |Soot from Californian wildfires|alt=alt language

</gallery>

----

If you want to contribute to the ICON-ART User guide, here are some links to get started using MediaWiki:

* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

Namelist

2023-03-02T10:17:19Z

Editor 2: removed lart , moved cart_input_folder

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependencies
|-
!rowspan="8" style="vertical-align:top;" | General Variables
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="9" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
| cart_coag_xml
| -
| Path to XML file for coagulation processes
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Namelist

2023-03-02T10:14:16Z

Editor 2: removed iart_gscp and irad_aero

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependencies
|-
!rowspan="9" style="vertical-align:top;" | General Variables
| lart
| .FALSE.
| Main switch which enables the treatment of atmospheric aerosol and trace gases (the ART modules)
| Located in the namelist run_nml
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="9" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
| cart_coag_xml
| -
| Path to XML file for coagulation processes
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Namelist

2023-03-02T09:59:18Z

Editor 2: renamed table coloumn to "Dependencies" from "dependent xml"

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependencies
|-
!rowspan="11" style="vertical-align:top;" | General Variables
| lart
| .FALSE.
| Main switch which enables the treatment of atmospheric aerosol and trace gases (the ART modules)
| Located in the namelist run_nml
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
| inwp_gscp
| 1
| Cloud microphysics and precipitation.
|
1 : one_moment bulk microphysics by Doms and Schaettler(2004) and Seifert and Beheng(2006)
2 : one-moment graupel scheme
3 : two-moment cloud ice scheme of Koehler (2013)
4 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number
5 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number and some aerosol, CCN and IN tracers
6 : two-moment bulk microphysics by Seifert and Beheng (2006) incorporating prognostic aerosol as CCN and IN from the ART extension. Note, that you will still need to set iart_aci_warm and iart_aci_cold
9 : a simple Kessler-type warm rain scheme
|
|-
| irad_aero
| 2
| Aerosols
|
0: No aerosol
1: prognostic variable
2: global constant
3: externally specified
5: Tanre aerosol climatology for iforcing = 3 (NWP)
6: Tegen aerosol climatology for iforcing = 3 (NWP) .AND. itopo =1
9: ART online aerosol radiation interaction, uses Tegen for aerosols not chosen to be represented in ART for iforcing = 3 (NWP) .AND. itopo =1 .AND. lart=TRUE .AND. iart_ari=1
12: Perpetual background Kinne aerosols
13: Tropospheric aerosol optical properties after S. Kinne
14: Stratospheric aerosol optical properties 15: Tropospheric aerosols after S. Kinne and stratospheric aerosol optical properties
18: Tropospheric background aerosols (Kinne) and stratospheric aerosols (CMIP6) + simple plumes
19: Tropospheric background aerosols (Kinne), no stratospheric aerosols + simple plumes
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="9" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
| cart_coag_xml
| -
| Path to XML file for coagulation processes
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Namelist

2023-03-02T09:20:26Z

Editor 2: fixed broken formatting in table after adding a row

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependent xml
|-
!rowspan="11" style="vertical-align:top;" | General Variables
| lart
| .FALSE.
| Main switch which enables the treatment of atmospheric aerosol and trace gases (the ART modules)
| Located in the namelist run_nml
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
| inwp_gscp
| 1
| Cloud microphysics and precipitation.
|
1 : one_moment bulk microphysics by Doms and Schaettler(2004) and Seifert and Beheng(2006)
2 : one-moment graupel scheme
3 : two-moment cloud ice scheme of Koehler (2013)
4 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number
5 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number and some aerosol, CCN and IN tracers
6 : two-moment bulk microphysics by Seifert and Beheng (2006) incorporating prognostic aerosol as CCN and IN from the ART extension. Note, that you will still need to set iart_aci_warm and iart_aci_cold
9 : a simple Kessler-type warm rain scheme
|
|-
| irad_aero
| 2
| Aerosols
|
0: No aerosol
1: prognostic variable
2: global constant
3: externally specified
5: Tanre aerosol climatology for iforcing = 3 (NWP)
6: Tegen aerosol climatology for iforcing = 3 (NWP) .AND. itopo =1
9: ART online aerosol radiation interaction, uses Tegen for aerosols not chosen to be represented in ART for iforcing = 3 (NWP) .AND. itopo =1 .AND. lart=TRUE .AND. iart_ari=1
12: Perpetual background Kinne aerosols
13: Tropospheric aerosol optical properties after S. Kinne
14: Stratospheric aerosol optical properties 15: Tropospheric aerosols after S. Kinne and stratospheric aerosol optical properties
18: Tropospheric background aerosols (Kinne) and stratospheric aerosols (CMIP6) + simple plumes
19: Tropospheric background aerosols (Kinne), no stratospheric aerosols + simple plumes
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="9" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
| cart_coag_xml
| -
| Path to XML file for coagulation processes
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Namelist

2023-03-02T09:19:30Z

Editor 2: added cart_coag_xml to the large table

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependent xml
|-
!rowspan="11" style="vertical-align:top;" | General Variables
| lart
| .FALSE.
| Main switch which enables the treatment of atmospheric aerosol and trace gases (the ART modules)
| Located in the namelist run_nml
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
| inwp_gscp
| 1
| Cloud microphysics and precipitation.
|
1 : one_moment bulk microphysics by Doms and Schaettler(2004) and Seifert and Beheng(2006)
2 : one-moment graupel scheme
3 : two-moment cloud ice scheme of Koehler (2013)
4 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number
5 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number and some aerosol, CCN and IN tracers
6 : two-moment bulk microphysics by Seifert and Beheng (2006) incorporating prognostic aerosol as CCN and IN from the ART extension. Note, that you will still need to set iart_aci_warm and iart_aci_cold
9 : a simple Kessler-type warm rain scheme
|
|-
| irad_aero
| 2
| Aerosols
|
0: No aerosol
1: prognostic variable
2: global constant
3: externally specified
5: Tanre aerosol climatology for iforcing = 3 (NWP)
6: Tegen aerosol climatology for iforcing = 3 (NWP) .AND. itopo =1
9: ART online aerosol radiation interaction, uses Tegen for aerosols not chosen to be represented in ART for iforcing = 3 (NWP) .AND. itopo =1 .AND. lart=TRUE .AND. iart_ari=1
12: Perpetual background Kinne aerosols
13: Tropospheric aerosol optical properties after S. Kinne
14: Stratospheric aerosol optical properties 15: Tropospheric aerosols after S. Kinne and stratospheric aerosol optical properties
18: Tropospheric background aerosols (Kinne) and stratospheric aerosols (CMIP6) + simple plumes
19: Tropospheric background aerosols (Kinne), no stratospheric aerosols + simple plumes
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="8" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
| cart_coag_xml
| -
| Path to XML file for coagulation processes
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Namelist

2023-03-02T09:01:11Z

Editor 2: Added and formatted the more comprehensive namelist Tabe from the google doc

__TOC__
== Recommended ICON Namelist Settings ==

It is necessary for the user to choose the ICON settings carefully. Part of the values listed in are recommended to obtain a stable ICON-ART simulation with scientifically reasonable results. Another part is necessary to enable ART features like aerosol-cloud-interactions.

<div id="tab:icon_tracer_nml">

{| class="wikitable" style="text-align:left;"
|+ Recommended ICON namelist settings for ART tracers.
! '''Parameter'''
! ''' Value'''
! ''' Namelist'''
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. 0.5*dtime).
|-
| inwp_gscp
| 4
| nwp_phy_nml
| Standard value is 1. Set this to 4 for aerosol-cloud-interactions within ICON-ART. Note, that you will still need to set iart_aci_warm and iart_aci_cold < 0 .
|-
| irad_aero
| 6
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
| 9
|
| optical properties depend on aerosol concentrations (set iart_ari = 1 in art_nml )
|}

</div>

== ART Namelists ==

ICON-ART has an own namelist to modify the setup of ART simulations at runtime. The main switch for ART, lart, is located inside run_nml. The namelist for the other ART switches is called art_nml.

A naming convention is used in order to show the type of data. An INTEGER namelist parameter starts with iart_, a REAL namelist parameter starts with rart_, a LOGICAL namelist parameter starts with lart_, and a CHARACTER namelist parameter starts with cart_.

The ICON-ART namelist is located in the module src/namelists/mo_art_nml.f90. General namelist parameters are listed and explained within . Namelist parameters for ART input are listed within . Namelist parameters related to atmospheric chemistry are listed within . Namelist parameters related to aerosol physics are listed within . Namelist parameters related to feedback processes between aerosols and meteorological variables are listed in . Finally, namelist parameters related to physics parameterizations in ICON are listed in .

</div>
<div id="tab:namelist">

{| class="wikitable" style="text-align:left;"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
| '''General Variables'''
|
|-
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
| <code>lart_pntSrc</code>
| Enables point sources
|-
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
| <code>cart_input_folder</code>
| Absolute Path to ART Input Files
|-
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
| '''Atmospheric Chemistry'''
|
|-
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
| '''XML configuration'''
|
|-
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
| <code>cart_emiss_xml_file</code>
| Path to XML file for emission metadata
|-
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
| <code>cart_coag_xml</code>
| Path to XML file for coagulation processes
|-
| '''Atmospheric Aerosol'''
|
|-
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol interaction with radiation
|-
| <code>iart_dust </code>
| Treatment of mineral dust aerosol interaction with radiation
|-
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
| <code>iart_fire </code>
| Enables treatment of wildfire aerosol
|-
| <code>iart_volcano </code>
| Enables treatment of volcanic ash aerosol
|-
| <code> iart_isorropia</code>
| Treatment of aerosol gas partitioning
|-
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
| <code>iart_pollen </code>
| Treatment of pollen
|-
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
| '''Feedback Processes'''
|
|-
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
| <code>iart_ari </code>
| Direct interaction of aerosol with radiation
|}

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

----
{| class="wikitable"
|-
!
! Name
! Default Value
! Description
! Details
! Dependent xml
|-
!rowspan="11" style="vertical-align:top;" | General Variables
| lart
| .FALSE.
| Main switch which enables the treatment of atmospheric aerosol and trace gases (the ART modules)
| Located in the namelist run_nml
|
|-
| cart_input_folder
| -
| Absolute path where input folder of ART initialization and external files are located.
|
|
|-
| iart_init_aero
| 0
| Initialization of aerosol species.
|
0: Initialization with 0
1: At this point climatological aerosol profiles may be included as standard initialization
2: Initialization with fixed value different from 0.0_wp (e.g. using 10.0_wp)
5: Set aerosol tracer initial values from file
6: Read background climatology from aes-ham
|
|-
| iart_init_gas
| 0
| Initialization of gaseous species.
|
0: Nothing to do here, tracers are initialized with 0.0_wp automatically
1: At this point climatological gas profiles may be included as a standard initialization
4: Initializing chemical tracers using method given by .xml
5: Initializing from file
|
|-
| lart_diag_out
| .FALSE.
| Enable output of diagnostic fields.
| If this switch is set to .TRUE., diagnostic output fields are available. Set it to .FALSE. when facing memory problems.
| cart_diagnostics_xml
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer.
| The sources are controled via cart_pntSrc_xml.
| cart_pntSrc_xml
|-
| lart_emiss_turbdiff
| .FALSE.
| Switch if emissions should be included to the turbulence scheme as surface flux condition
|
|
|-
| cart_io_suffix
| 'grid-nr'
| Specifies the grid specification in ART input file name convention. With default grid-number it is replaced by the four character string due to ICON parameter number_of_grid_used . Any other string can be included for each domain.
|
|
|-
| iart_modeshift
| 1
| Doing mode shift (only temporary switch for debug)
|
0 = off
1 = on
|
|-
| inwp_gscp
| 1
| Cloud microphysics and precipitation.
|
1 : one_moment bulk microphysics by Doms and Schaettler(2004) and Seifert and Beheng(2006)
2 : one-moment graupel scheme
3 : two-moment cloud ice scheme of Koehler (2013)
4 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number
5 : two-moment bulk microphysics by Seifert and Beheng (2006) with prognostic cloud droplet number and some aerosol, CCN and IN tracers
6 : two-moment bulk microphysics by Seifert and Beheng (2006) incorporating prognostic aerosol as CCN and IN from the ART extension. Note, that you will still need to set iart_aci_warm and iart_aci_cold
9 : a simple Kessler-type warm rain scheme
|
|-
| irad_aero
| 2
| Aerosols
|
0: No aerosol
1: prognostic variable
2: global constant
3: externally specified
5: Tanre aerosol climatology for iforcing = 3 (NWP)
6: Tegen aerosol climatology for iforcing = 3 (NWP) .AND. itopo =1
9: ART online aerosol radiation interaction, uses Tegen for aerosols not chosen to be represented in ART for iforcing = 3 (NWP) .AND. itopo =1 .AND. lart=TRUE .AND. iart_ari=1
12: Perpetual background Kinne aerosols
13: Tropospheric aerosol optical properties after S. Kinne
14: Stratospheric aerosol optical properties 15: Tropospheric aerosols after S. Kinne and stratospheric aerosol optical properties
18: Tropospheric background aerosols (Kinne) and stratospheric aerosols (CMIP6) + simple plumes
19: Tropospheric background aerosols (Kinne), no stratospheric aerosols + simple plumes
|
|-
!rowspan="8" style="vertical-align:top;" | Atmospheric Chemistry
| lart_chem
| .FALSE.
| Main switch to enable chemistry
|
| lart_chemtracer = .TRUE. OR lart_mecca = .TRUE.
|-
| lart_chemtracer
| .FALSE.
| Switch for chemical tracer processes
|
| cart_chemtracer_xml
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|
| cart_mecca_xml
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|
|
|-
| cart_vortex_init_date
| -
| Date of vortex initialization
|
|
|-
| cart_cheminit_file(max_dom)
| -
| Path to chemical initialization file
|
|
|-
| cart_cheminit_coord
| -
| Path to chemical initialization coordinate file
|
|
|-
| cart_cheminit_type
| -
| Type of chemical initialization coordinate file
|
|
|-
!rowspan="8" style="vertical-align:top;" | XML configuration
| cart_chemtracer_xml
| -
| Path to XML file for parametrised chemtracers
|
|
|-
| cart_mecca_xml
| -
| Path to XML file for MECCA chemistry tracers
|
|
|-
| cart_aerosol_xml
| -
| Path to XML file for aerosol tracers
|
|
|-
| cart_modes_xml
| -
| Path to XML file for modes
|
|
|-
| cart_pntSrc_xml
| -
| Path to XML file for point sources
|
|
|-
| cart_diagnostics_xml
| -
| Path to XML file for aerosol diagnostics (GRIB2 meta data)
|
|
|-
| cart_emiss_xml_file
| -
| Path and file name of the xml files for emission metadata
|
|
|-
| cart_ext_data_xml
| -
| Path to XML file for metadata of datasets prescribing tracers
|
|
|-
!rowspan="9" style="vertical-align:top;" | Atmospheric Aerosol
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol
|
| cart_aerosol_xml
|-
| iart_seasalt
| 0
| Treatment of sea salt aerosol
|
0: No treatment.
1: Initialization of seasalt emission. Add 6 to iart_ntracer.
2: A second parameterization is used for the seasalt emission. Add 6 to iart_ntracer.
|
|-
| iart_dust
| 0
| Treatment of mineral dust aerosol
|
0: No treatment.
1: Initialization of mineral dust aerosol (Vogel et al. 2006).
2: Simplified version of emission fluxes of mineral dust aerosol (Vogel et al. 2006).
|
|-
| iart_anthro
| 0
| Treatment of anthropogenic aerosol
|
0: No treatment.
1: With the anthropogenic aerosol.
|
|-
| iart_fire
| 0
| Treatment of wildfire aerosol
|
0: Nothing to do, no biomass burning emissions
1: Initialization of biomass burning tracer data
|
|-
| iart_volcano
| 0
| Treatment of volcanic ash aerosol
|
0: No treatment.
1: 1-moment treatment. Add 6 to iart ntracer.
2: 2-moment treatment. Add 6 to iart_ntracer.
|
|-
| iart_nonsph
| 0
| Treatment of nonspherical particles
|
0: USE Mie values
1: Ellipsoid mixture
|
|-
| iart_pollen
| 0
| Treatment of pollen
|
0: No treatment
1: Initialization of pollen tracer data
|
|-
| iart_radioact
| 0
| Treatment of radioactive particles
|
0: No treatment.
1: As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer.
|
|-
!rowspan="3" style="vertical-align:top;" | Feedback Processes
| iart_aci_warm
| 0
| Nucleation of aerosol to cloud droplets
|
0: Constant cloud droplet number inwp_gscp=4
1: Nucleation Warm ART
|
|-
| iart_aci_cold
| 0
| Nucleation of aerosol to cloud ice
|
0: Nucleation originial 2-moment scheme (1,2,3,4,5): Nucleation Cold ART
6: With tracking of activated dust
7: With prognostic dust as input and relaxation of activated dust
|
|-
| iart_ari
| 0
| Direct interaction of aerosol with radiation
|
0: No radiation feedback with ART aerosols
1: Turn on radiation feedback with ART aerosols (ASH or DUST). Set irad_aero = 9 in radiation_nml
|
|-
!rowspan="3" style="vertical-align:top;" | Emissions
| cart_volcano_file
| -
| Absolute path + filename of input file for volcanoes
|
|
|-
| cart_radioact_file
| -
| Absolute path + filename of input for radioactive emissions
|
|
|-
| Online emission module
|
| See oem namelist
|
|
|}

Output

2023-02-24T10:56:09Z

Editor 2: /* Finding the correct Mode description */ added monodisperse

__TOC__

== General Remarks ==

In principle, output of ICON-ART variables works the same way as for ICON variables. As described in , the following five quantities of the output have to be specified:

* The time interval between two model outputs.
* The name of the output file.
* The name of the variable(s) and/or variable group(s).
* The type of vertical output grid.
* The type of horizontal output grid.

For the best results it is recommended to use NETCDF output on the icosahedral grid which ICON-ART is using. However in some applications remapping the grid to a latitude-longitude grid may be required, which can be set via the <code>remap</code> option. A corresponding output namelist for sea salt on model levels can be seen here:

<pre>NAMELIST EXAMPLE
&output_nml
filetype = 4 ! output format: 2=GRIB2, 4=NETCDFv2
dom = 1 ! write output for domain 1
output_start = "JJJJ-MM-DDTHH:MM:SSZ" !put date in
output_end = "JJJJ-MM-DDTHH:MM:SSZ" !put date in
output_interval = "PT1H" ! \href{ISO8601}{https://en.wikipedia.org/wiki/ISO_8601}
steps_per_file = 1 ! max. num. of time steps within one file
mode = 1 ! 1: forecast mode (relative t-axis)
include_last = .TRUE. ! include the last time step
output_filename = '<INSERTFILENAME>' ! file name base
ml_varlist = 'seasa','seasb','seasc',
'seasa0','seasb0','seasc0'
remap = 1 ! output is transferred to lat long grid
reg_lon_def = -180.,0.5,179.5 !start, incr., end, in deg.
reg_lat_def = 90.,-0.5, -90. !start, incr., end, in deg.</pre>

There is an option to obtain all diagnostic Variables of a certain Group without having to specifying all of them. For example, you may use the group ART_DIAGNOSTICS.

To include a group of Variables in the output file change the namelist variable ml_varlist from the example above to the following:

<pre>ml_varlist = 'group:ART_AEROSOL'</pre>
The output variables that are associated to this group will be written to the output file. You can check the groups of output variables in this [[#OutputTable | Table]] .

== Aerosol Naming Conventions ==
The following table contains an overview of the possible output variables.

There are several ways to choose the Naming of the output variables, depending on your application

* '''Externally mixed Aerosols:''' : The Tracers for Dust, Seasalt, Ash and Soot are combined with the three Possible modes a, b and c, which correspond to the different size bins of the particles <div id="OutputTable"></div>

::{| class="wikitable" style="text-align:left;"
|+ Externally mixed Tracer modes
!|| dust||seasalt ||ash ||soot
|-
!a
| dusta ||seasa ||asha ||soota
|-
!b
| dustb ||seasb ||ashb ||-
|-
!c
| dustc||seasc ||ashc ||-
|-
|}

* '''Internally mixed Aerosols (AERODYN):''' Here a tracer is defined in a different way, with the goal being to have a more flexible framework for various applications. In this framework modes are created in a different way, as illustrated int the table below:

<div id="OutputTable"></div>
::{| class="wikitable" style="text-align:left;"
|+ AERODYN mode configurations
! || aitken || accumulation || coarse || giant
|-
! soluble
| sol_aitken || sol_acc || sol_coarse || sol_giant
|-
! insoluble
|insol_aitken || insol_acc || insol_coarse || insol_giant
|-
! mixed
| mixed_aitken ||mixed_acc || mixed_coarse || mixed_giant
|-
|}

The modes are then combined with The Tracername to obtain the name of the Variable using <code>varname = 'Tracer' + '_' + 'mode from Table'</code>.
Example : <code> dust_insol_acc </code>

* '''Monodisperse Aerosols'''

== Available Output Variables ==
The following Table contains an overview over the diagnostic Icon-ART Variables. Expressions in Brackets are Placeholders which can be used to construct the name of the actual variables:

[aeronet wavelength] => [340, 380, 440, 500, 550, 675, 870, 1020, 1064]

[ceilo_wavelength] => [355,532,1064]

[pollen] => [ALNU,BETU,...] to be defined in diagnostics.xml

{| class="wikitable"
|+ Output Overview
|-
!
! varname
! groups
! unit
! descripition
! namelist switch
! required xml
|-
!rowspan="19" style="vertical-align:top;" | Aerosols
| diam_[mode]
| ART_DIAGNOSTICS
| m
| with AERODYN : aerosol diameter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| diam_[aerosol][mode]
| ART_DIAGNOSTICS
| m
| WITHOUT AERODYN: aerosol diameter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| aod_[aerosol]_[aeronet wavelength]nm
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| Layer-1
| [AEROSOL] optical depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| bsc_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS
| m-1 sr-1
| [AEROSOL] backscatter
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ceil_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| m-1 sr-1
| [AEROSOL] Attenuated Backscatter Ceilometer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| sat_[arosol]_[ceilo_wavelength]nm
| ART_DIAGNOSTICS
| m-1 sr-1
| [AEROSOL] Attenuated Backscatter Satellite
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_so4_sol
| ART_DIAGNOSTICS
| layer-1
| SO4 sol Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_insol
| ART_DIAGNOSTICS
| layer-1
| Ash insol Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_mixed
| ART_DIAGNOSTICS
| layer-1
| Ash mixed Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| AOD_550_ash_giant
| ART_DIAGNOSTICS
| layer-1
| Ash giant Optical Depth
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ustar_thres
| ART_ROUTINE_DIAG
| m s-1
| threshold friction velocity for dust emission'
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| ustar
| ART_ROUTINE_DIAG
| m s-1
| Friction velocity
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_drydepo_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated dry deposition of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_sedim_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated sedimentation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_gscp_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition by grid scale precipitation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_con_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition by convective precipitation of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_wetdepo_rrsfc_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated wet deposition of tracer if precipitation reaches surface
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| emiss_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2 s-1
| emission of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
| acc_emiss_[tracer]
| ART_DIAGNOSTICS , ART_ROUTINE_DIAG
| tracer-unit m-2
| accumulated emission of tracer
| lart_aerosol=True and lart_diag_out=True
| requires cart_diagnostics_xml file
|-
!rowspan="9" style="vertical-align:top;"| Pollen
| [pollen]rprec
| ART_ROUTINE_DIAG
| m-2
| precipitation reservoir of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]reso
| ART_ROUTINE_DIAG
| m-2
| Pollen reservoir (previous timestep) of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]ress
| ART_ROUTINE_DIAG
| m-2
| Pollen reservoir (daily sum) of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]sdes
| ART_ROUTINE_DIAG
| -
| State of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]ctsum
| ART_ROUTINE_DIAG
| K
| Cumulated weighted 2m temperature sum of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisn
| ART_ROUTINE_DIAG
| days
| Number of days since start of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisl
| ART_ROUTINE_DIAG
| days
| length of pollen season of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
| [pollen]saisa
| ART_ROUTINE_DIAG
| days
| Number of days since the start of pollen season of [pollen]. if present day is out of the season: length of current season
| REQUIRES diagnostics.xml
|
|-
| [pollen]fe
| ART_ROUTINE_DIAG
| m-2 s-1
| Emission flux of [pollen]
| iart_pollen>0
| REQUIRES diagnostics.xml
|-
!rowspan="18" style="vertical-align:top;" | Chemistry
| reac_rates
| ART_DIAGNOSTICS
| s-1
| MECCA reaction rates
| lart_mecca=True, lart_diag_out=True
|
|-
| art_o3
| kg/kg
| Ozone mass mixing ratio
| lart_chem =True, lart_diag_out=True
|
|
|-
| OH_Nconc
| # / cm3
| OH number concentration
| lart_chem =TRUE
|
|
|-
| photo
| -
| s-1
| photolysis rates
| lart_chem=TRUE, lart_mecca=TRUE
|
|-
| art_full_chemistry_o3_col
| -
| DU
| Ozone column
| lart_chem=TRUE, lart_mecca=TRUE
|
|-
| sts_liqsur
| ART_DIAGNOSTICS
| cm2 cm-3
| liquid area density of STS
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| cgaml
| ART_DIAGNOSTICS
| -
| STS uptake coefficient of the reaction
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| dens_ice
| ART_DIAGNOSTICS
| m-3
| number density of ice particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_ice
| ART_DIAGNOSTICS
| m
| radius of ice particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_STS
| ART_DIAGNOSTICS
| m
| radius of STS particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| dens_NAT
| ART_DIAGNOSTICS
| m-3
| number density of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| radius_NAT
| ART_DIAGNOSTICS
| m
| radius of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| HNO3_Nconc_s
| ART_DIAGNOSTICS
| cm-3
| number concentration of HNO3 in NAT
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| HNO3_Nconc_l
| ART_DIAGNOSTICS
| cm-3
| number concentration of HNO3 in STS
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| ice_vmr_Marti
| ART_DIAGNOSTICS
| mol mol-1
| volume mixing ratio of solid water by Marti and Mauersberger
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| NAT_sedi_rel_difference
| ART_DIAGNOSTICS
| -
| relative difference of NAT mass bef and aft sedi (aft - bef) * 2 / (aft + bef)
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| NAT_sedi_vel
| ART_DIAGNOSTICS
| m s-1
| sedimentation velocity of NAT particles
| lart_chem=TRUE , lart_psc=TRUE
|
|-
| art_so2_col
| ART_DIAGNOSTICS
| DU
| SO2 column
| lat_chem=TRUE , lart_chemtracer=TRUE
|
|-
!rowspan="3" style="vertical-align:top;"| Radioactive Tracer Diagnostics
| wet deposition of xml defined tracer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-2
| wet deposition of xml defined tracer
| lart_aerosol=True and iart_radioact=1
|
|-
| dry deposition of xml defined tracer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-2
| dry deposition of xml defined tracer
| lart_aerosol=True and iart_radioact=1
|
|-
| Averaged air concentration of xml defined traer
| ART_DIAGNOSTICS, ART_ROUTINE_DIAG
| Bq m-3
| Averaged air concentration of xml defined traer
| lart_aerosol=True and iart_radioact=1
|
|-
!rowspan="4" style="vertical-align:top;"| FPLUME Output
| plume_height
| ART_FPLUME
| m
| plume height
| iart_fplume/=0
|
|-
| plume_MFR
| ART_FPLUME
| kg s-1
| plume MFR
| iart_fplume/=0
|
|-
| MER_transport
| ART_FPLUME
| kg s-1
| Amount of very fine ash for transport
| iart_fplume/=0
|
|-
| solution_with
| ART_FPLUME
| -
| FPlume off, Mastin, or FPlume
| iart_fplume/=0
|
|}