icon-art guide - User contributions [en]

Getting Started

2024-04-12T12:08:37Z

Admin 1: /* Installation */ added hint to GPL conditions

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

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

MECCA-based (full) Chemistry

2024-04-12T12:01:48Z

Admin 1: /* Step4: Transfer MECCA mechanism to ICON */ fixed broken link

- work in progress -

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

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

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

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

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

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

== Preparing the MECCA-xml-file ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Getting Started

2024-03-25T09:48:13Z

Admin 1: /* Installation */

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

== 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 has to be included using the tag <code> --enable-art —enable-art-gpl </code>.

<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-02-14T17:06:06Z

Admin 1: /* Installation */

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

== 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 has to be included using the tag <code> --enable-art —enable-art-gpl </code>.

<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</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-02-06T09:32:16Z

Admin 1: /* Getting the source code */

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

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

<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</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-02-06T09:30:36Z

Admin 1: /* Getting the source code */

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

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

<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</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-02-06T09:29:15Z

Admin 1: /* Getting the source code */

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

== 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 including all submodules (including ART) use :

<code>
git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git
</code>
<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.

<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</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-02-06T09:28:13Z

Admin 1: /* Getting the source code */

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

== 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 including all submodules (including ART) use :

<code>
git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git
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.

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

Input

2024-01-30T13:27:48Z

Admin 1:

== 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:
<syntaxhighlight lang=bash line>
! run_nml: general switches ----------
&run_nml
ltestcase = .FALSE.
num_lev = 50
ltransport = .TRUE.
.............
lart = .TRUE.
</syntaxhighlight>
Generally the first letters of a namelist switch refer to its type, the "l" in "lart" stands for logical, meaning it has to be either True or False. Here are some examples.

<div id="tab:vartypes">

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

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

== XML Inputs ==

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

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

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

</div>

{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Tracers">Aerosol Tracers</span>
|-
! tag
! type
! options
! description
|-
| htop_proc
| real
| in m
| top height for processes
|-
| initc
| character
| file
| initialize from Input file
|-
| inucl
| integer
| 0 (off), 1 (on)
| H2SO4 nucleation for so4 tracer (default=1); 1 for so4_sol_ait, 0 for other so4 tracer)
|-
| label
| character
| e.g., dusta
| allows to name tracers individually
|-
| latbc
| character
| file
| read data for LBC
|-
| lfeedback
| integer
| 0 (off), 1 (on)
| child -> parent feedback in nested simulations (default=0)
|-
| '''mode'''
| character
| insol_acc, mixed_acc,..
| indicates in which modes the tracer occurs
|-
| '''mol_weight'''
| real
| in kg/mol
| value for molar weight
|-
| '''moment'''
| integer
| 0, 3
| zeroth (number) or third (mass) moment
|-
| '''rho'''
| real
| in g/m3
| density of tracer, not needed for zeroth moment
|-
| '''sol'''
| integer
| 0 (no), 1 (yes)
| indicates whether the tracer is soluble or not
|-
| '''transport'''
| character
| stdaero, stdchem, ..., off
| choice of transport template
|-
| '''unit'''
| character
| e.g., mug kg-1, kg-1
| unit of tracer
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Modes">Aerosol Modes</span>
|-
! tag
! type
! options
! description
|-
| condensation
| integer
| 0 (off), 1 (on)
| condensation of H2SO4 on this mode?
|-
| '''d_gn'''
| real
| in m
| value for the initial median diameter of the number distribution
|-
| dissfac_mean
| real
|
| dissociation factor (needed with ikoehler=1)
|-
| '''icoag'''
| integer
| 0 (off), 1 (on)
| mode involved in coagulation? If 1 for any mode, then provide coagulate.xml
|-
| ikoehler
| integer
| 0 (off), 1 (on)
| Activation via Köhler theory (warm clouds), needs dissfac_mean tag
|-
| '''kind'''
| character
| 1mom or 2mom
| 1-moment or 2-moment description of distribution
|-
| '''sigma_g'''
| real
|
| standard deviation of the distribution
|-
| shift2larger
| character
| e.g., sol_acc
| Name of larger mode to be shifted to, when diameter threshold (shift_diam) exceeded
|-
| shift2mixed
| character
| e.g., mixed_acc
| Name of mixed mode to be shifted to, when soluble mass threshold of 5% exceeded
|-
| shift_diam
| real
| in m
| diameter threshold for shift2larger
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Emission">Aerosol Emission</span>
|-
! tag
! type
! options
! description
|-
| '''nmodes'''
| integer
|
| number of emission modes
|-
| '''d_g0_*'''
| real
|
| median diameter of number distribution of mode * (e.g., d_g0_1, d_g0_2, d_g0_3)
|-
| '''d_g3_*'''
| real
|
| median diameter of mass distribution of mode * (e.g., d_g3_1, d_g3_2, d_g3_3)
|-
| '''rho'''
| real
| in kg/m3
| particle density (same for all modes)
|-
| '''sigma_g_*'''
| real
|
| standard deviation of mode *
|-
| substance
| character
| ash, dust, na, cl, soot
| emitted substance
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br \> routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Point Source">Point Source</span>
|-
! tag
! type
! options
! description
|-
| dg3_emiss
| real
| in m
| median diameter of aerosol mass distribution
|-
| emiss_profile
| character
|
| anti-derivative of emission profile
|-
| endTime
| character
|
| end time of emission (default=9999-12-31T00:00:00)
|-
| '''height'''
| real
| in m
| emission height
|-
| height_bot
| real
| in m
| bottom height
|-
| '''lat'''
| real
| in degree
| latitude
|-
| '''lon'''
| real
| in degree
| longitude
|-
| sigma_emiss
| real
|
| standard deviation of aerosol distribution
|-
| startTime
| character
|
| start time of emission (default=1582-10-15T00:00:00)
|-
| '''source_strength'''
| real
|
| emission source strength
|-
| '''substance'''
| character
| e.g., TRSO2
| substance nme from tracer xml
|-
| '''unit'''
| character
| e.g., kg s-1
| unit of source strength
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Chemistry Tracers">Chemistry Tracers</span>
|-
! tag
! type
! options
! description
|-
| '''c_solve'''
| character
| param, lt, cold, OH, linoz, simnoy, passive
| solving mechanism/strategy
|-
| emissions
|
| anthropogenic, biogenic, biomassBurning
| usage see in tracers_chemtracer_amip.xml (*)
|-
| htop_proc
| real
| in m
| top height for processes
|-
| iconv
| integer
| 0 (off), 1 (on)
| transport by convection (default=1)
|-
| initc
| character
| file
| initialize from Input file
|-
| init_mode
| integer
| 0 (off), 1 (on)
| initialize tracer
|-
| init_name
| character
|
| name of tracer in initialization file
|-
| iturb
| integer
| 0 (off), 1 (on)
| transport by turbulence (default=1)
|-
| latbc
| character
| file
| read data for LBC
|-
| lfeedback
| integer
| 0 (off), 1 (on)
| child -> parent feedback in nested simulations (default=0)
|-
| lifetime
| real
| in s
| value for lifetime
|-
| '''mol_weight'''
| real
| in kg/mol
| value for molar weight
|-
| products
| character
| name of tracer
| name of resulting tracer after depletion
|-
| tag001,...
| character
|
| name of tag to be added to tracer name
|-
| '''transport'''
| character
| stdaero, stdchem, ..., off
| choice of transport template
|-
| '''unit'''
| character
| e.g., mol mol-1
| unit of tracer
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br\> (*) in icon-kit/externals/art/runctrl_examples/xml_ctrl/
|}

The reason for the use of those additional .xml files is that the ART variables they contain (sea salt, mineral dust etc.) might be different for every run which differs from the Icon Variables (Temperature, Pressure, etc.) which usually don’t change between runs. .xml files are readable for both humans and machines, which makes them easy to tweak and integrate. An Example for the contents of an .xml file adding ash particles can be seen below.
<syntaxhighlight lang=xml line>
<modes>
<aerosol id="asha">
<kind type="char">2mom</kind>
<d_gn type="real">1.190E-6</d_gn>
<sigma_g type="real">1.410E+0</sigma_g>
<rho type="real">2.600E+3</rho>
</aerosol>
</modes>
</syntaxhighlight>

Here is an example for a more complex .xml using [[AERODYN]]:
This is an example for the number and mass concentration of dust in a tracer .xml.
<syntaxhighlight lang=xml line>
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa</mode>
<unit type="char">kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="dust">
<moment type="int">3</moment>
<mode type="char">insol_acc,insol_coa</mode>
<sol type="real">1.0</sol>
<mol_weight type="real">50.00E-3</mol_weight>
<rho type="real">2.650E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
</tracers>
</syntaxhighlight>

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

== Input Data ==

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

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

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

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

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

=== Obtaining Input Data ===

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

[[How to generate input data]]

[[How to download input data]]

=== Emission Data ===
In every ICON-ART, there is the possibility to add additional input data like emission data that correspond with different sources. A quick overview about them can be found below.
{| class="wikitable" style="text-align:left;"
|+ Additional input files for the emissions
! Type
! Data
! XXX
|-
| Point souces
| XML-file
| -
|-
| Sea salt
| no extra data necessary
| -
|-
| Mineral Dust
| Soil Type Data
| ART_STY
|-
| Biogenic VOCs
| Emissions or Vegetatiom
| ART_STY
|-
| Athropogenic emissions
| Emission data sets
| ART_BIO ART_ANT
|-
| Biomass burning
| Satellite data
| ART_BCF
|}

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

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

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

=== General ===

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

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

=== Required data for LAM boundaries ===

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

===Initialization ===

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

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

=== Boundary Data ===

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

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

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

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

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

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

== All input data required for standard configurations ==
=== XML data are art/runctrl_examples/xml_ctrl ===
=== Runscripts are art/runctrl_examples/run_scripts ===
=== All grid, IC, BC and emission data are [https://bwsyncandshare.kit.edu/s/YdaqfMDgJPfo8QF here] ===

Input

2024-01-24T14:44:35Z

Admin 1:

== 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:
<syntaxhighlight lang=bash line>
! run_nml: general switches ----------
&run_nml
ltestcase = .FALSE.
num_lev = 50
ltransport = .TRUE.
.............
lart = .TRUE.
</syntaxhighlight>
Generally the first letters of a namelist switch refer to its type, the "l" in "lart" stands for logical, meaning it has to be either True or False. Here are some examples.

<div id="tab:vartypes">

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

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

== XML Inputs ==

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

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

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

</div>

{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Tracers">Aerosol Tracers</span>
|-
! tag
! type
! options
! description
|-
| htop_proc
| real
| in m
| top height for processes
|-
| initc
| character
| file
| initialize from Input file
|-
| inucl
| integer
| 0 (off), 1 (on)
| H2SO4 nucleation for so4 tracer (default=1); 1 for so4_sol_ait, 0 for other so4 tracer)
|-
| label
| character
| e.g., dusta
| allows to name tracers individually
|-
| latbc
| character
| file
| read data for LBC
|-
| lfeedback
| integer
| 0 (off), 1 (on)
| child -> parent feedback in nested simulations (default=0)
|-
| '''mode'''
| character
| insol_acc, mixed_acc,..
| indicates in which modes the tracer occurs
|-
| '''mol_weight'''
| real
| in kg/mol
| value for molar weight
|-
| '''moment'''
| integer
| 0, 3
| zeroth (number) or third (mass) moment
|-
| '''rho'''
| real
| in g/m3
| density of tracer, not needed for zeroth moment
|-
| '''sol'''
| integer
| 0 (no), 1 (yes)
| indicates whether the tracer is soluble or not
|-
| '''transport'''
| character
| stdaero, stdchem, ..., off
| choice of transport template
|-
| '''unit'''
| character
| e.g., mug kg-1, kg-1
| unit of tracer
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Modes">Aerosol Modes</span>
|-
! tag
! type
! options
! description
|-
| condensation
| integer
| 0 (off), 1 (on)
| condensation of H2SO4 on this mode?
|-
| '''d_gn'''
| real
| in m
| value for the initial median diameter of the number distribution
|-
| dissfac_mean
| real
|
| dissociation factor (needed with ikoehler=1)
|-
| '''icoag'''
| integer
| 0 (off), 1 (on)
| mode involved in coagulation? If 1 for any mode, then provide coagulate.xml
|-
| ikoehler
| integer
| 0 (off), 1 (on)
| Activation via Köhler theory (warm clouds), needs dissfac_mean tag
|-
| '''kind'''
| character
| 1mom or 2mom
| 1-moment or 2-moment description of distribution
|-
| '''sigma_g'''
| real
|
| standard deviation of the distribution
|-
| shift2larger
| character
| e.g., sol_acc
| Name of larger mode to be shifted to, when diameter threshold (shift_diam) exceeded
|-
| shift2mixed
| character
| e.g., mixed_acc
| Name of mixed mode to be shifted to, when soluble mass threshold of 5% exceeded
|-
| shift_diam
| real
| in m
| diameter threshold for shift2larger
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Aerosol Emission">Aerosol Emission</span>
|-
! tag
! type
! options
! description
|-
| '''nmodes'''
| integer
|
| number of emission modes
|-
| '''d_g0_*'''
| real
|
| median diameter of number distribution of mode * (e.g., d_g0_1, d_g0_2, d_g0_3)
|-
| '''d_g3_*'''
| real
|
| median diameter of mass distribution of mode * (e.g., d_g3_1, d_g3_2, d_g3_3)
|-
| '''rho'''
| real
| in kg/m3
| particle density (same for all modes)
|-
| '''sigma_g_*'''
| real
|
| standard deviation of mode *
|-
| substance
| character
| ash, dust, na, cl, soot
| emitted substance
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br \> routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Point Source">Point Source</span>
|-
! tag
! type
! options
! description
|-
| dg3_emiss
| real
| in m
| median diameter of aerosol mass distribution
|-
| emiss_profile
| character
|
| anti-derivative of emission profile
|-
| endTime
| character
|
| end time of emission (default=9999-12-31T00:00:00)
|-
| '''height'''
| real
| in m
| emission height
|-
| height_bot
| real
| in m
| bottom height
|-
| '''lat'''
| real
| in degree
| latitude
|-
| '''lon'''
| real
| in degree
| longitude
|-
| sigma_emiss
| real
|
| standard deviation of aerosol distribution
|-
| startTime
| character
|
| start time of emission (default=1582-10-15T00:00:00)
|-
| '''source_strength'''
| real
|
| emission source strength
|-
| '''substance'''
| character
| e.g., TRSO2
| substance nme from tracer xml
|-
| '''unit'''
| character
| e.g., kg s-1
| unit of source strength
|-
| colspan="4"| '''bold''' letters indicate which tags are always required.
|}
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
|+ style=white-space:nowrap | <span id="Chemistry Tracers">Chemistry Tracers</span>
|-
! tag
! type
! options
! description
|-
| '''c_solve'''
| character
| param, lt, cold, OH, linoz, simnoy, passive
| solving mechanism/strategy
|-
| emissions
|
| anthropogenic, biogenic, biomassBurning
| usage see in tracers_chemtracer_amip.xml (*)
|-
| htop_proc
| real
| in m
| top height for processes
|-
| iconv
| integer
| 0 (off), 1 (on)
| transport by convection (default=1)
|-
| initc
| character
| file
| initialize from Input file
|-
| init_mode
| integer
| 0 (off), 1 (on)
| initialize tracer
|-
| init_name
| character
|
| name of tracer in initialization file
|-
| iturb
| integer
| 0 (off), 1 (on)
| transport by turbulence (default=1)
|-
| latbc
| character
| file
| read data for LBC
|-
| lfeedback
| integer
| 0 (off), 1 (on)
| child -> parent feedback in nested simulations (default=0)
|-
| lifetime
| real
| in s
| value for lifetime
|-
| '''mol_weight'''
| real
| in kg/mol
| value for molar weight
|-
| products
| character
| name of tracer
| name of resulting tracer after depletion
|-
| tag001,...
| character
|
| name of tag to be added to tracer name
|-
| '''transport'''
| character
| stdaero, stdchem, ..., off
| choice of transport template
|-
| '''unit'''
| character
| e.g., mol mol-1
| unit of tracer
|-
| colspan="4"| '''bold''' letters indicate which tags are always required. <br\> (*) in icon-kit/externals/art/runctrl_examples/xml_ctrl/
|}

The reason for the use of those additional .xml files is that the ART variables they contain (sea salt, mineral dust etc.) might be different for every run which differs from the Icon Variables (Temperature, Pressure, etc.) which usually don’t change between runs. .xml files are readable for both humans and machines, which makes them easy to tweak and integrate. An Example for the contents of an .xml file adding ash particles can be seen below.
<syntaxhighlight lang=xml line>
<modes>
<aerosol id="asha">
<kind type="char">2mom</kind>
<d_gn type="real">1.190E-6</d_gn>
<sigma_g type="real">1.410E+0</sigma_g>
<rho type="real">2.600E+3</rho>
</aerosol>
</modes>
</syntaxhighlight>

Here is an example for a more complex .xml using [[AERODYN]]:
This is an example for the number and mass concentration of dust in a tracer .xml.
<syntaxhighlight lang=xml line>
<tracers>
<aerosol id="nmb">
<moment type="int">0</moment>
<mode type="char">insol_acc,insol_coa</mode>
<unit type="char">kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
<aerosol id="dust">
<moment type="int">3</moment>
<mode type="char">insol_acc,insol_coa</mode>
<sol type="real">1.0</sol>
<mol_weight type="real">50.00E-3</mol_weight>
<rho type="real">2.650E3</rho>
<unit type="char">mug kg-1</unit>
<transport type="char">hadv52aero</transport>
</aerosol>
</tracers>
</syntaxhighlight>

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

== Input Data ==

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

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

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

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

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

=== Obtaining Input Data ===

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

[[How to generate input data]]

[[How to download input data]]

=== Emission Data ===
In every ICON-ART, there is the possibility to add additional input data like emission data that correspond with different sources. A quick overview about them can be found below.
{| class="wikitable" style="text-align:left;"
|+ Additional input files for the emissions
! Type
! Data
! XXX
|-
| Point souces
| XML-file
| -
|-
| Sea salt
| no extra data necessary
| -
|-
| Mineral Dust
| Soil Type Data
| ART_STY
|-
| Biogenic VOCs
| Emissions or Vegetatiom
| ART_STY
|-
| Athropogenic emissions
| Emission data sets
| ART_BIO ART_ANT
|-
| Biomass burning
| Satellite data
| ART_BCF
|}

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

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

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

=== General ===

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

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

=== Required data for LAM boundaries ===

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

===Initialization ===

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

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

=== Boundary Data ===

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

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

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

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

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

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

== All input data required for standard configurations ==
=== XML data are art/runctrl_examples/xml_ctrl ===
=== Runscripts are art/runctrl_examples/run_scripts ===
=== All grid, IC, BC and emission data are in the following link ===
https://bwsyncandshare.kit.edu/s/YdaqfMDgJPfo8QF

Input

2024-01-24T14:35:36Z

Admin 1:

Getting Started

2023-10-13T12:06:50Z

Admin 1: /* Installation */

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

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

Afterwards you also should get access to the DKRZ gitlab. If you have access you can clone ICON.

Example for cloning the ICON-KIT repository including all submodules (including ART):

<code>
git clone --recursive git@gitlab.dkrz.de:icon/icon-kit.git
</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.

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

2023-10-13T10:50:01Z

Admin 1: /* Creating a Runfile */ typo

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

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

Afterwards you also should get access to the DKRZ gitlab. If you have access you can clone ICON.

Example for cloning the ICON-KIT repository including all submodules (including ART):

<code>
git clone --recursive git@gitlab.dkrz.de:icon/icon-kit.git
</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.

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

2023-10-12T13:54:53Z

Admin 1: /* Creating a Runfile */ added more information

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

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

Afterwards you also should get access to the DKRZ gitlab. If you have access you can clone ICON.

Example for cloning the ICON-KIT repository including all submodules (including ART):

<code>
git clone --recursive git@gitlab.dkrz.de:icon/icon-kit.git
</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.

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

2023-10-12T05:29:19Z

Admin 1: /* Creating a Runfile */ added info for the info file

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

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

Afterwards you also should get access to the DKRZ gitlab. If you have access you can clone ICON.

Example for cloning the ICON-KIT repository including all submodules (including ART):

<code>
git clone --recursive git@gitlab.dkrz.de:icon/icon-kit.git
</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.

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

* 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

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

2023-10-12T05:01:15Z

Admin 1: /* Installation */ included step-by-step guide

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

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

Afterwards you also should get access to the DKRZ gitlab. If you have access you can clone ICON.

Example for cloning the ICON-KIT repository including all submodules (including ART):

<code>
git clone --recursive git@gitlab.dkrz.de:icon/icon-kit.git
</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.

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

Getting Started

2023-10-12T04:49:38Z

Admin 1: /* Getting the source code */

Input

2023-09-28T12:44:57Z

Admin 1: /* Input Data */

Getting Started

2022-09-18T21:17:22Z

Admin 1: /* Running a Job */

= Getting Started =

== 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 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 figure [[#ART-capabilities|1.1]]).

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

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 figure [[#ART-seamless|1.2]]. It also enables its use as a prediction tool for the production of renewable energy.

[[File:ART-seamless.png|thumb|none|alt=ICON-ART’s cpabilities for seamless prediction.|ICON-ART’s cpabilities for seamless prediction.]]

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

In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:

http://icon-art.imk-tro.kit.edu

After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.

== Installation ==

In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br />
$ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.

If you have compiled ICON as recommended first without ART, you have to do clean up first:

<div class="small">

<pre> make distclean</pre>

</div>
In order to compile ICON-ART, an additional flag has to be set at the configuration command:

<div class="small">

<pre> ./config/dkrz/mistral.intel --enable-art

</div>
By setting –with-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:

<div class="small">

<pre> make -j8

</div>
== 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

* Configure the code with the additional flag –enable-art as described above

* Prepare the input data (see section [[https://www.icon-art.kit.edu/userguide/index.php?title=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 .

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

* Add an output namelist as described in for the species you are interested in.

* Submit the job analogous to an ICON job.

Getting Started

2022-09-18T21:15:19Z

Admin 1:

= Getting Started =

== 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 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 figure [[#ART-capabilities|1.1]]).

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

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 figure [[#ART-seamless|1.2]]. It also enables its use as a prediction tool for the production of renewable energy.

[[File:ART-seamless.png|thumb|none|alt=ICON-ART’s cpabilities for seamless prediction.|ICON-ART’s cpabilities for seamless prediction.]]

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

In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:

http://icon-art.imk-tro.kit.edu

After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.

== Installation ==

In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br />
$ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.

If you have compiled ICON as recommended first without ART, you have to do clean up first:

<div class="small">

<pre> make distclean</pre>

</div>
In order to compile ICON-ART, an additional flag has to be set at the configuration command:

<div class="small">

<pre> ./config/dkrz/mistral.intel --enable-art

</div>
By setting –with-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:

<div class="small">

<pre> make -j8

</div>
== 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

* Configure the code with the additional flag –enable-art as described above

* Prepare the input data (see section [[Inputs]]

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

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

* Add an output namelist as described in for the species you are interested in.

* Submit the job analogous to an ICON job.

Main Page

2022-09-18T21:10:44Z

Admin 1:

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

* [https://www.icon-art.kit.edu/userguide/index.php?title=Getting_Started Getting Started]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Input Input]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Namelist Namelist]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Output Output]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Programming_ART Programming ART]
* [https://www.icon-art.kit.edu/userguide/index.php?title=tutorial_Examples Tutorial Examples]

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

== Getting started ==
* [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]

Namelist

2022-09-15T09:27:33Z

Admin 1:

= 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="margin:auto"
|+ Recommended ICON namelist settings for ART tracers.
!
!
!
! '''Description'''
|-
| dtime
| -
| run_nml
| If facing stability problems, it is recommended to use a shorter time step as recommended by operational setups (e.g. <math display="inline">\frac{3}{5}\cdot</math>dtime<math display="inline">_{oper}</math>).
|-
| ndyn_substeps
| -
| run_nml
| There is no need to call the dynamics more often than in operational setup. Adjust it according to your dtime choice.
|-
| inwp_gscp
|
| '''•''' nwp_phy_nml
| In order to enable aerosol-cloud-interactions within ICON-ART, you have to specify this. Note, that you will still need to set iart_aci_warm and iart_aci_cold from .
|-
| irad_aero
|
| radiation_nml
| aerosol optical properties are taken from climatology
|-
|
|
|
| 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 id="tab:art_nml_gen">

{| class="wikitable" style="margin:auto"
|+ General namelist parameters to control the ART routines. For naming conventions, see . These switches are - with the exception of lart- located inside art_nml.
!
!
! '''Description'''
|-
| lart
| .FALSE.
| Main switch which enables the ART modules. Located in the namelist run_nml .
|-
| iart_init_aero
|
| Initialization of aerosol species. Possible values: : Initialization with 0. : Initialization with Climatology1 (not yet implemented) : Initialization from files (see )
|-
| iart_init_gas
|
| Initialization of gaseous species. Possible values: : Initialization with 0. : Initialization with Climatology1 (not yet implemented) : Initialization in modus, given by the .xml file input declaration <code>init_mode</code>(see ) : Initialization from files (see )
|-
| lart_chem
| .FALSE.
| Enables chemistry. The chemical mechanism and the according species are set via <code>lart_chemtracer</code> and <code>lart_mecca</code>.
|-
| lart_pntSrc
| .FALSE.
| Enables addition of point sources for passive tracer. The sources are controled via <code>cart_pntSrc_xml</code>.
|-
| lart_aerosol
| .FALSE.
| Main switch for the treatment of atmospheric aerosol.
|-
| lart_diag_out
| .FALSE.
| If this switch is set to <code>.TRUE.</code>, diagnostic output fields are available. Set it to <code>.FALSE.</code> when facing memory problems.
|}

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

{| class="wikitable" style="margin:auto"
|+ Namelist parameters to control ART input. These switches are located inside art_nml.
! cart_io_suffix(ndom)
! ’grid-number’
! Specifies the grid specification in ART input file name convention (see section [[#sec:name_concept|[sec:name_concept]]]). 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.
|-
| cart_input_folder
| ”
| Absolute path where input files, like initialization files are located.
|-
| cart_emiss_xml_file
| ”
| Path and file name to the XML file for specifying emission metadata.
|-
| cart_chemtracer_xml
| ”
| Path and file name to the XML file for specifying chemical and passive tracer.
|-
| cart_mecca_xml
| ”
| Path and file name to the XML file for specifying tracers of the MECCA chemical mechanism.
|-
| cart_aerosol_xml
| ”
| Path and file name to the XML file for specifying aerosol tracer.
|-
| cart_modes_xml
| ”
| Path and file name to the XML file for specifying aerosol modes.
|-
| cart_pntSrc_xml
| ”
| Path and file name to the XML file for specifying point source emissions.
|-
| cart_diagnostics_xml
| ”
| Path and file name to the XML file for specifying (mainly GRIB2) metadata for diagnostic output variables. Not needed for NetCDF output at the moment.
|-
| cart_ext_data_xml
| ”
| Path and file name to the XML file for specifying metadata of external datasets for prescribing tracers.
|}

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

{| class="wikitable" style="margin:auto"
|+ Namelist parameters related to atmospheric chemistry. For naming conventions, see . These switches art located inside art_nml.
!
!
! '''Description'''
|-
| lart_chemtracer
| .FALSE.
| Enables the computation of simplified chemistry and passive tracers.
|-
| lart_mecca
| .FALSE.
| Enables the computation of full chemistry via the MECCA package.
|-
| cart_vortex_init_date
| ’ ’
| Date of vortex initialization
|-
| cart_cheminit_file
| ’ ’
| Path to chemical initialization file
|-
| cart_cheminit_coord
| ’ ’
| Path to chemical initialization coordinate file
|-
| cart_cheminit_type
| ’ ’
| Type of chemical initialization coordinate file
|-
| lart_psc
| .FALSE.
| Switch if polar stratospheric clouds should be calculated
|}

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

{| class="wikitable" style="margin:auto"
|+ Namelist parameters related to aerosol physics. For naming conventions, see . These switches are located in art_nml .
!
!
! '''Description'''
|-
| iart_seasalt
|
| Treatment of sea salt aerosol. Possible values: : No treatment. : As specified in . Add 6 to iart_ntracer .
|-
| iart_dust
|
| Treatment of mineral dust aerosol. Possible values: : No treatment. : As specified in . : Simplified version of .
|-
| iart_volcano
|
| Treatment of volcanic ash particles. Possible values: : No treatment. : 1-moment treatment. As described in . Add 6 to iart_ntracer . : 2-moment treatment. Add 6 to iart_ntracer .
|-
| cart_volcano_file
| ”
| Path and filename of the input file for the geographical position and the type of volcanoes.
|-
| iart_radioact
|
| Treatment of radioactive nuclei. Possible values: : No treatment. : As described in the ICON-ART technical documentation. An input file has to be specified via cart_radioact_file. Add 9 to iart_ntracer .
|-
| cart_radioact_file
| ”
| Path and filename of the input file for the dispersion of radioactive nuclei.
|-
| iart_pollen
|
| Treatment of pollen. Possible values: : No treatment. :
|}

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

{| class="wikitable" style="margin:auto"
|+ Namelist parameters related to feedback processes between aerosols and meteorological variables. For naming conventions, see .
!
!
! '''Description'''
|-
| iart_aci_warm
|
| Treatment of warm-phase activation. Note, that inwp_gscp = 6 is a prerequisite for aerosol-cloud-interactions. Possible values: : Constant <math display="inline">qni = 200\,\mathrm{cm}^{-3}</math> as for inwp_gscp = 4. : with extensions .
|-
| iart_aci_cold
|
| Treatment of cold-phase nucleation. Note, that inwp_gscp = 6 is a prerequisite for aerosol-cloud-interactions. Possible values: : scheme with constant IN properties as for inwp_gscp = 4. : scheme with scheme for het. nucleation. : scheme with scheme for het. nucleation. : scheme with scheme for het. nucleation. : scheme with scheme for het. nucleation. : scheme with Ullrich et al. scheme for het. nucleation. : scheme with scheme for het. nucleation and budget variable for activated dust IN. : scheme with prognostic mineral dust IN and budget variable for activated dust IN.
|-
| iart_ari
|
| Direct interaction of simulated aerosol with radiation (here default: irad_aero = 6 ).: no interaction : with interaction. Set irad_aero = 9 in radiation_nml
|}

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

{| class="wikitable" style="margin:auto"|+ Namelist parameters related to physics parameterizations in ICON. For naming conventions, see . These switches art located inside art_nml .
!
!
! '''Description'''
|-
| lart_conv
| .TRUE.
| Consider tendencies due to the convection parameterization.
|-
| lart_turb
| .TRUE.
| Consider tendencies due to the turbulent diffusion parameterization.
|}

</div>

Getting Started

2022-09-15T09:18:54Z

Admin 1:

= Getting Started =

== 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 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 figure [[#ART-capabilities|1.1]]).

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

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 figure [[#ART-seamless|1.2]]. It also enables its use as a prediction tool for the production of renewable energy.

[[File:ART-seamless.png|thumb|none|alt=ICON-ART’s cpabilities for seamless prediction.|ICON-ART’s cpabilities for seamless prediction.]]

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

In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:

http://icon-art.imk-tro.kit.edu

After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.

== Installation ==

In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br />
$ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.

If you have compiled ICON as recommended first without ART, you have to do clean up first:

<div class="small">

<pre> make distclean</pre>

</div>
In order to compile ICON-ART, an additional flag has to be set at the configuration command:

<div class="small">

<pre> ./config/dkrz/mistral.intel --enable-art

</div>
By setting –with-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:

<div class="small">

<pre> make -j8

</div>
== 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:

* Configure the code with the additional flag –enable-art as described in .
* Prepare the input data
* 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 .
* 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 .
* Add an output namelist as described in for the species you are interested in.
* Submit the job analogous to an ICON job.

Getting Started

2022-09-08T09:19:17Z

Admin 1:

= Getting Started =

== 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 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 figure [[#ART-capabilities|1.1]]).

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

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 figure [[#ART-seamless|1.2]]. It also enables its use as a prediction tool for the production of renewable energy.

[[File:ART-seamless.png|thumb|none|alt=ICON-ART’s cpabilities for seamless prediction.|ICON-ART’s cpabilities for seamless prediction.]]

== Getting the source code ==

''Last Update: 2014/06/18 Daniel Rieger''

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

In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:

http://icon-art.imk-tro.kit.edu

After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.

== Installation ==

''Last Update: 2016/05/25 Jonas Straub''

In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br />
$ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.

If you have compiled ICON as recommended first without ART, you have to do clean up first:

<div class="small">

<pre> make distclean</pre>

</div>
In order to compile ICON-ART, an additional flag has to be set at the configuration command:

<div class="small">

<pre> ./config/dkrz/mistral.intel --enable-art

</div>
By setting –with-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:

<div class="small">

<pre> make -j8

</div>
== Running a Job ==

''Last Update: 2016/05/25 Jonas Straub''

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:

* Configure the code with the additional flag –enable-art as described in .
* Prepare the input data
* 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 .
* 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 .
* Add an output namelist as described in for the species you are interested in.
* Submit the job analogous to an ICON job.

Getting Started

2022-09-08T09:18:28Z

Admin 1:

= Getting Started =

== 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 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 figure [[#ART-capabilities|1.1]]).

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

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 figure [[#ART-seamless|1.2]]. It also enables its use as a prediction tool for the production of renewable energy.

[[File:ART-seamless.png|thumb|none|alt=ICON-ART’s cpabilities for seamless prediction.|ICON-ART’s cpabilities for seamless prediction.]]

== Getting the source code ==

''Last Update: 2014/06/18 Daniel Rieger''

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

In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:

http://icon-art.imk-tro.kit.edu

After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.

== Installation ==

''Last Update: 2016/05/25 Jonas Straub''

In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br />
$ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.

If you have compiled ICON as recommended first without ART, you have to do clean up first:

<div class="small">

<pre> make distclean</pre>

</div>
In order to compile ICON-ART, an additional flag has to be set at the configuration command:

<div class="small">

<pre> ./config/dkrz/mistral.intel --enable-art

</div>
By setting –with-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:

<div class="small">

<pre> ./build_command</pre>

</div>
== Running a Job ==

''Last Update: 2016/05/25 Jonas Straub''

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:

* Configure the code with the additional flag –enable-art as described in .
* Prepare the input data
* 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 .
* 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 .
* Add an output namelist as described in for the species you are interested in.
* Submit the job analogous to an ICON job.

Main Page

2022-09-08T09:10:01Z

Admin 1:

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

* [https://www.icon-art.kit.edu/userguide/index.php?title=Getting_Started Getting Started]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Input Input]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Namelist Namelist]
* [https://www.icon-art.kit.edu/userguide/index.php?title=Output Output]

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

== Getting started ==
* [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]

Getting Started

2022-09-02T11:01:29Z

Admin 1:

<h1 id="chap:gettingstarted">Getting Started</h1> <h2 id="overview">Overview</h2> <p>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 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 figure <a href="#ART-capabilities" data-reference-type="ref" data-reference="ART-capabilities">1.1</a>).</p> <figure> <img src="figures/ART-capabilities.png" id="ART-capabilities" alt="Capabilities of ICON-ART and how they relate to each other." /> <figcaption aria-hidden="true">Capabilities of ICON-ART and how they relate to each other.</figcaption> </figure> <p>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 figure <a href="#ART-seamless" data-reference-type="ref" data-reference="ART-seamless">1.2</a>. It also enables its use as a prediction tool for the production of renewable energy.</p> <figure> <img src="figures/ART-seamless.png" id="ART-seamless" alt="ICON-ARTÔÇÖs cpabilities for seamless prediction." /> <figcaption aria-hidden="true">ICON-ARTÔÇÖs cpabilities for seamless prediction.</figcaption> </figure> <h2 id="sec:general_remarks">Getting the source code</h2> <p>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:</p> <p><a href="https://code.mpimet.mpg.de/projects/iconpublic">https://code.mpimet.mpg.de/projects/iconpublic</a></p> <p>In order to obtain the ART code, the institution that wants to use ICON-ART has to sign an additional license agreement with Karlsruhe Institute of Technology (KIT). Further information can be found on the following website:</p> <p><a href="http://icon-art.imk-tro.kit.edu">http://icon-art.imk-tro.kit.edu</a></p> <p>After you have signed the license agreement, you will be provided with a compressed file with the recent source code of ART which is called ART-v<X>.<YY>.tar.gz. <X> and <YY> indicate the version numbers.</p> <h2 id="sec:installation">Installation</h2> <p>In this section, a brief description of how to compile ICON-ART is given. The user has to do the same steps as compiling ICON with a few additions. The reader is referred to <span class="citation" data-cites="icon:user_guide"></span> in order to compile ICON successfully. First, the ART-v<X>.<YY>.tar.gz file has to uncompressed. You will obtain a directory, which should be copied inside the ICON source directory $ICON-DIR/src/. In the following, we refer to this directory<br /> $ICON-DIR/src/ART-v<X>.<YY> as $ARTDIR.</p> <p>If you have compiled ICON as recommended first without ART, you have to do clean up first:</p> <div class="small"> <pre><code> make distclean</code></pre> </div> <p>In order to compile ICON-ART, an additional flag has to be set at the configuration command:</p> <div class="small"> <pre><code> ./configure --with-fortran=cray --with-art</code></pre> </div> <p>By setting ÔÇôwith-art a compiler flag -D__ICON_ART is set. This flag tells the preprocessor to compile the code inside the ART interfaces and hence connect the ICON code with the ART code. As soon as the configuration is finished, you can start to compile the ICON-ART code:</p> <div class="small"> <pre><code> ./build_command</code></pre> </div> <h2 id="running-a-job">Running a Job</h2> <p>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 <span class="citation" data-cites="icon:user_guide"></span>.</p> <p>In order to run ICON-ART, one has to do the following steps:</p> <ul> <li><p>Configure the code with the additional flag ÔÇôenable-art as described in <a href="#sec:installation" data-reference-type="autoref" data-reference="sec:installation">[sec:installation]</a>.</p></li> <li><p>Prepare the input data</p></li> <li><p>Inside the runscript in the namelist run_nml, set the main switch for ICON-ART to true: lart = .true.</p></li> <li><p>Add a namelist art_nml and choose the namelist parameters for the ART setup as described in <a href="#chap:namelist" data-reference-type="autoref" data-reference="chap:namelist">[chap:namelist]</a>.</p></li> <li><p>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 <a href="#chap:output" data-reference-type="autoref" data-reference="chap:output">[chap:output]</a>.</p></li> <li><p>Add an output namelist as described in <a href="#chap:output" data-reference-type="autoref" data-reference="chap:output">[chap:output]</a> for the species you are interested in.</p></li> <li><p>Submit the job analogous to an ICON job.</p></li> </ul>