Input: Difference between revisions

From icon-art guide
Jump to navigation Jump to search
(used the pandoc -> mediawiki markdown converted text instead of pandoc -> html and added some formatting to the tables)
No edit summary
 
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:

= Input =


== Requirements for a Simulation ==
== 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.
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 chapter [[#chap:namelist|[chap:namelist]]].


== Namelist Inputs ==
To enable ART in an ICON simulation, the switch <code>lart = .TRUE.</code> has to be set in the section <code>&amp;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:


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]].
<pre>! run_nml: general switches ----------

To enable ART in an ICON simulation, the switch <code>lart = .TRUE.</code> has to be set in the section <code>&amp;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 ----------
&amp;run_nml
&amp;run_nml
ltestcase = .FALSE.
ltestcase = .FALSE.
Line 13: Line 17:
ltransport = .TRUE.
ltransport = .TRUE.
.............
.............
lart = .TRUE.

</syntaxhighlight>
\textcolor{red}{lart = .TRUE.}</pre>
Generally the first letters of a namelist switch refer to its type, the &quot;l&quot; in &quot;lart&quot; stands for logical, meaning it has to be either True or False. Table [[#tab:vartypes|1.1]] lists some examples.
Generally the first letters of a namelist switch refer to its type, the &quot;l&quot; in &quot;lart&quot; stands for logical, meaning it has to be either True or False. Here are some examples.


<div id="tab:vartypes">
<div id="tab:vartypes">


{| class="wikitable" style="margin:auto"
{| class="wikitable" style="text-align:left;"
|+ Some namelist switches and their data types.
|+ Some namelist switches and their data types.
! namelist switch
! namelist switch
Line 36: Line 40:


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



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


{| class="wikitable" style="margin:auto"
{| class="wikitable" style="text-align:left;"
|+ XML files and their namelist dependencies
|+ General art_nml namelist switches and respective parameters.
! XML File
! Namelist parameter
! Default
! Description
! Description
! Namelist parameter dependency
! If .TRUE. then needs
! Default
! Further Information
|---
|---
| <code>lart_chem</code>
| <code>cart_chemtracer_xml</code>
| Switch for simple OH chemistry
| .FALSE.
| Enables chemistry.
| <code>lart_chemtracer = .TRUE.</code>OR <code>lart_mecca = .TRUE.</code>
|-
| <code>lart_chemtracer</code>
| <code>lart_chemtracer</code>
| .FALSE.
| .FALSE.
|[[#Chemistry Tracers|Chemistry Tracers]]
| Switch for simple OH chemistry
| <code>cart_chemtracer_xml</code>
|-
|-
| <code>cart_mecca_xml</code>
| Switch for kpp chemistry
| <code>lart_mecca</code>
| <code>lart_mecca</code>
| .FALSE.
| .FALSE.
|[[Atmospheric Chemistry]]
| Switch for kpp chemistry
| <code>cart_mecca_xml</code>
|-
|-
| <code>cart_pntSrc_xml</code>
| Enables creation of point sources emitting given Aerosols at a given rate
| <code>lart_pntSrc</code>
| <code>lart_pntSrc</code>
| .FALSE.
| .FALSE.
|[[#Point Source|Point Source]]
| Enables addition of point sources
| <code>cart_pntSrc_xml</code>
|-
|-
| <code>cart_aerosol_xml</code>
| Main switch for the treatment of atmospheric aerosols
| <code>lart_aerosol</code>
| <code>lart_aerosol</code>
| .FALSE.
| .FALSE.
|[[#Aerosol Tracers|Aerosol Tracers]]
| Main switch for the treatment of
| <code>cart_aerosol_xml</code>
|-
|-
| <code>cart_modes_xml</code>
|
| Main switch for the treatment of atmospheric aerosols
|
| <code>lart_aerosol</code>
| atmospheric aerosol.
| .FALSE.
| and <code>cart_modes_xml</code>
|[[#Aerosol Modes|Aerosol Modes]]
|-
|-
| <code>cart_diagnostics_xml</code>
| Enables diagnostic output fields
| <code>lart_diag_out</code>
| <code>lart_diag_out</code>
| .FALSE.
| .FALSE.
| -
| Enables diagnostic output fields
|-
| <code>cart_diagnostics_xml</code>
| <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>
</div>
The reason for the use of those additional .xml files is that the ART variables (sea salt, mineral dust etc.) they contain 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.


{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
<pre>&lt;modes&gt;
|+ style=white-space:nowrap | <span id="Aerosol Tracers">Aerosol Tracers</span>
&lt;aerosol id=&quot;asha&quot;&gt;
|-
&lt;kind type=&quot;char&quot;&gt;2mom&lt;/kind&gt;
! tag
&lt;d_gn type=&quot;real&quot;&gt;1.190E-6&lt;/d_gn&gt;
! type
&lt;sigma_g type=&quot;real&quot;&gt;1.410E+0&lt;/sigma_g&gt;
! options
&lt;rho type=&quot;real&quot;&gt;2.600E+3&lt;/rho&gt;
! description
&lt;/aerosol&gt;
|-
&lt;/modes&gt;</pre>
| 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>
Further .xml examples can be fount in <code>/your_ART_Directory/runctrl_examples/xml_ctrl. </code>


==== Additional Input Data ====
== 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|1.3]] and [[#tab:input-emissions|1.4]].
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:figures/input-names.png|thumb|none|alt=ICON-ART input file naming convention.|ICON-ART input file naming convention.]]
[[File:input-names.png|800px|none|alt=ICON-ART input file naming convention.|ICON-ART input file naming convention.]]


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


{| class="wikitable" style="margin:auto"
{| class="wikitable" style="text-align:left;"
|+ Additional input files for the initialisation
|+ Additional input files for the initialisation
! Species
! Species
Line 115: Line 508:
| <code>iart_init_gas</code>
| <code>iart_init_gas</code>
| 0 (cold start), 5 (from file)
| 0 (cold start), 5 (from file)
| IGX
| ICE
|-
|-
| Aerosol
| Aerosol
Line 127: Line 520:
<div id="tab:input-emissions">
<div id="tab:input-emissions">



{| class="wikitable" style="margin:auto"
=== 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
|+ Additional input files for the emissions
! Type
! Type
Line 158: Line 563:
|}
|}


==== 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.
</div>
{| class="mw-collapsible mw-collapsed wikitable" style="text-align:left;"
<div id="tab:namelist">
|+ style=white-space:nowrap | <span id="Emission Data Sources">Emission Data Sources</span>

{| class="wikitable" style="margin:auto"
|+ Art namelist parameters
! '''Name'''
! '''function'''
|-
|-
! Tracer !! Emission Type !! Emission !! Resolution
| '''General Variables'''
|
|-
|-
| C2H6 || ANT || EDGA || R2B04_ECHAM
| <code>cart_input_folder</code>
| Absolute Path to ART source code
|-
|-
| || || EDGAR+ || R2B05_0014
| <code>iart_init_aero</code>
| Initialization of aerosol species
|-
|-
| || || EDGAR-monthly || R2B05_0014
| <code>iart_init_gas</code>
| Initialization of gaseous species
|-
|-
| || || || R2B06_0024
| <code>lart_diag_out</code>
| Enable output of diagnostic fields
|-
|-
| || || || B2B06_EU_nest
| <code>lart_pntSrc</code>
| Enables point sources
|-
|-
| || || || R2B07_nest
| <code>lart_emiss_turbdiff</code>
| Switch if emissions should be included as surface flux condition
|-
|-
| || || || R2B07_NSR_D_nest
| <code>cart_io_suffix</code>
| user given suffix instead of automatically generated grid number
|-
|-
| || || || R3B07_0026
| '''Atmospheric Chemistry'''
|
|-
|-
| || || MACCity || R2B04_0012
| <code>lart_chem</code>
| Main switch to enable chemistry
|-
|-
| || || || R2B05_0014
| <code>lart_chemtracer</code>
| Switch for parametrised chemtracers
|-
|-
| || || || R2B06_0016
| <code>lart_mecca</code>
| Switch for MECCA chemistry
|-
|-
| || || || R2B07_0018
| <code>lart_psc</code>
| Switch for computation of PSCs
|-
|-
| || || || R2B07_polstrNest
| <code>cart_vortex_init_date</code>
| Date of vortex initialization
|-
|-
| || || || R3B07_0022
| <code>cheminit_file(max_dom)</code>
| Path to chemical initialization file
|-
|-
| || BBE || GFED || R2B04_ECHAM
| <code>cart_cheminit_coord</code>
| Path to chemical initialization coordinate file
|-
|-
| || || GFED3 || R2B06_0024
| <code>cart_cheminit_type</code>
| Type of chemical initialization coordinate file
|-
|-
| || || || R2B06_EU_nest
| '''XML configuration'''
|
|-
|-
| || || || R2B07_nest
| <code>cart_chemtracer_xml</code>
| Path to XML file for parametrised chemtracers
|-
|-
| || || || R2B07_NSR_D_nest
| <code>cart_mecca_xml</code>
| Path to XML file for MECCA tracers
|-
|-
| || BIO || MEGA || R2B04_ECHAM
| <code>cart_aerosol_xml</code>
| Path to XML file for aerosol tracers
|-
|-
| || || MEGAN-MACC || R2B04_0012
| <code>cart_modes_xml</code>
| Path to XML file for modes
|-
|-
| || || || R2B05_0014
| <code>cart_pntSrc_xml</code>
| Path to XML file for point sources
|-
|-
| || || || R2B06_0016
| <code>cart_diagnostics_xml</code>
| Path to XML file for aerosol diagnostics
|-
|-
| || || || R2B06_0024
| <code>cart_emiss_xml_file</code>
| Path and file name of the xml files for emission metadata
|-
|-
| || || || R2B06_EU_nest
| <code>cart_ext_data_xml</code>
| Path to XML file for metadata of datasets prescribing tracers
|-
|-
| || || || R2B07_nest
| '''Atmospheric Aerosol'''
|
|-
|-
| || || || R2B07_NSR_D_nest
| <code>lart_aerosol </code>
| Main switch for the treatment of atmospheric aerosol
|-
|-
| || || || R2B07_0018
| <code>iart_seasalt </code>
| Treatment of sea salt aerosol
|-
|-
| || || || R2B07_polstrNest
| <code>iart_dust </code>
| Treatment of mineral dust aerosol
|-
|-
| || || || R3B07_0022
| <code>iart_anthro</code>
| Treatment of anthropogenic aerosol
|-
|-
| C3H8 || ANT || EDGA || R2B04_ECHAM
| <code>iart_fire </code>
| Treatment of wildfire aerosol
|-
|-
| || || EDGAR+ || R2B05_0014
| <code>iart_volcano </code>
| Treatment of volcanic ash aerosol
|-
|-
| || || EDGAR432-monthly || R2B05_0014
| <code>iart_nonsph</code>
| Treatment of nonspherical particles
|-
|-
| || || || R2B06_0024
| <code>iart_pollen </code>
| Treatment of pollen
|-
|-
| || || || B2B06_EU_nest
| <code>iart_radioact</code>
| Treatment of radioactive particles
|-
|-
| || || || R2B07_nest
| <code>cart_volcano_file </code>
| Absolute path + filename of input file for volcanoes
|-
|-
| || || || R2B07_NSR_D_nest
| <code>cart_radioact_file</code>
| Absolute path + filename of input for radioactive emissions
|-
|-
| || || || R3B07_0026
| '''Feedback Processes'''
|
|-
|-
| || || MACCity || R2B04_0012
| <code>iart_aci_warm </code>
| Nucleation of aerosol to cloud droplets
|-
|-
| || || || R2B05_0014
| <code>iart_aci_cold </code>
| Nucleation of aerosol to cloud ice
|-
|-
| || || || R2B06_0016
| <code>iart_ari </code>
|-
| Direct interaction of aerosol with radiation
| || || || 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 ==
</div>
<div id="tab:art_nml-params">


=== General ===
{| class="wikitable" style="margin:auto"
|+ General art_nml namelist switches and respective parameters.
! Namelist parameter
! Default
! Description
! If .TRUE. then needs
|-
| <code>iart_modeshift</code>
| 1
|
|
|}


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

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

Latest revision as of 14:27, 30 January 2024


Requirements for a Simulation

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

Namelist Inputs

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

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

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

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

Some namelist switches and their data types.
namelist switch type
lart logical
cart_aerosol_xml character
iart_init_aero integer


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

XML Inputs

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


XML files and their namelist dependencies
XML File Description Namelist parameter dependency Default Further Information
cart_chemtracer_xml Switch for simple OH chemistry lart_chemtracer .FALSE. Chemistry Tracers
cart_mecca_xml Switch for kpp chemistry lart_mecca .FALSE. Atmospheric Chemistry
cart_pntSrc_xml Enables creation of point sources emitting given Aerosols at a given rate lart_pntSrc .FALSE. Point Source
cart_aerosol_xml Main switch for the treatment of atmospheric aerosols lart_aerosol .FALSE. Aerosol Tracers
cart_modes_xml Main switch for the treatment of atmospheric aerosols lart_aerosol .FALSE. Aerosol Modes
cart_diagnostics_xml Enables diagnostic output fields lart_diag_out .FALSE. -
cart_emiss_xml_file XML File for emission metadata - - Aerosol Emission
cart_ext_data_xml XML File for metadata of datasets prescribing tracers - - -
cart_coag_xml XML File containing additional information about coagulation - - -
Aerosol Tracers
tag type options description
htop_proc real in m top height for processes
initc character file initialize from Input file
inucl integer 0 (off), 1 (on) H2SO4 nucleation for so4 tracer (default=1); 1 for so4_sol_ait, 0 for other so4 tracer)
label character e.g., dusta allows to name tracers individually
latbc character file read data for LBC
lfeedback integer 0 (off), 1 (on) child -> parent feedback in nested simulations (default=0)
mode character insol_acc, mixed_acc,.. indicates in which modes the tracer occurs
mol_weight real in kg/mol value for molar weight
moment integer 0, 3 zeroth (number) or third (mass) moment
rho real in g/m3 density of tracer, not needed for zeroth moment
sol integer 0 (no), 1 (yes) indicates whether the tracer is soluble or not
transport character stdaero, stdchem, ..., off choice of transport template
unit character e.g., mug kg-1, kg-1 unit of tracer
bold letters indicate which tags are always required.
Aerosol Modes
tag type options description
condensation integer 0 (off), 1 (on) condensation of H2SO4 on this mode?
d_gn real in m value for the initial median diameter of the number distribution
dissfac_mean real dissociation factor (needed with ikoehler=1)
icoag integer 0 (off), 1 (on) mode involved in coagulation? If 1 for any mode, then provide coagulate.xml
ikoehler integer 0 (off), 1 (on) Activation via Köhler theory (warm clouds), needs dissfac_mean tag
kind character 1mom or 2mom 1-moment or 2-moment description of distribution
sigma_g real standard deviation of the distribution
shift2larger character e.g., sol_acc Name of larger mode to be shifted to, when diameter threshold (shift_diam) exceeded
shift2mixed character e.g., mixed_acc Name of mixed mode to be shifted to, when soluble mass threshold of 5% exceeded
shift_diam real in m diameter threshold for shift2larger
Aerosol Emission
tag type options description
nmodes integer number of emission modes
d_g0_* real median diameter of number distribution of mode * (e.g., d_g0_1, d_g0_2, d_g0_3)
d_g3_* real median diameter of mass distribution of mode * (e.g., d_g3_1, d_g3_2, d_g3_3)
rho real in kg/m3 particle density (same for all modes)
sigma_g_* real standard deviation of mode *
substance character ash, dust, na, cl, soot emitted substance
bold letters indicate which tags are always required.
routine options: volc, volc fplume, dust, biomass burn, seas smith, seas monahan, seas martensson, seas mode1, seas mode2, seas mode3
Point Source
tag type options description
dg3_emiss real in m median diameter of aerosol mass distribution
emiss_profile character anti-derivative of emission profile
endTime character end time of emission (default=9999-12-31T00:00:00)
height real in m emission height
height_bot real in m bottom height
lat real in degree latitude
lon real in degree longitude
sigma_emiss real standard deviation of aerosol distribution
startTime character start time of emission (default=1582-10-15T00:00:00)
source_strength real emission source strength
substance character e.g., TRSO2 substance nme from tracer xml
unit character e.g., kg s-1 unit of source strength
bold letters indicate which tags are always required.
Chemistry Tracers
tag type options description
c_solve character param, lt, cold, OH, linoz, simnoy, passive solving mechanism/strategy
emissions anthropogenic, biogenic, biomassBurning usage see in tracers_chemtracer_amip.xml (*)
htop_proc real in m top height for processes
iconv integer 0 (off), 1 (on) transport by convection (default=1)
initc character file initialize from Input file
init_mode integer 0 (off), 1 (on) initialize tracer
init_name character name of tracer in initialization file
iturb integer 0 (off), 1 (on) transport by turbulence (default=1)
latbc character file read data for LBC
lfeedback integer 0 (off), 1 (on) child -> parent feedback in nested simulations (default=0)
lifetime real in s value for lifetime
mol_weight real in kg/mol value for molar weight
products character name of tracer name of resulting tracer after depletion
tag001,... character name of tag to be added to tracer name
transport character stdaero, stdchem, ..., off choice of transport template
unit character e.g., mol mol-1 unit of tracer
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. 

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

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

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



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

Input Data

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

ICON-ART input file naming convention.
Additional input files for the initialisation
Species Namelist switch Options XXX
Gas iart_init_gas 0 (cold start), 5 (from file) ICE
Aerosol iart_init_aero 0 (cold start), 5 (from file) IAE



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.

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.

Emission Data Sources
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 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 &art_nml is iart_init_aero=5

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

Boundary Data

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

#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: 

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}

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: 

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}

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): 

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

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! 

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}

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 here

Retrieved from "https://www.icon-art.kit.edu/userguide/index.php?title=Input&oldid=325"