Input: Difference between revisions

From icon-art guide
Jump to navigation Jump to search
Tag: Manual revert
 
(15 intermediate revisions by the same user not shown)
Line 1,230: Line 1,230:
* In any case, double check if all emission tags have been assigned to the correct tracer
* In any case, double check if all emission tags have been assigned to the correct tracer


= Online emission module (OEM) =
== Running a Limited Area Meteorology (LAM) Simulation ==
=== Introduction ===

The online emission module (OEM) is an extension to ICON-ART for the application of temporal and vertical emission profiles online during a simulation. Its concept and functionality is described in [Jähn et al. (2020)](https://doi.org/10.5194/gmd-13-2379-2020). More recently, it was extended with the capability of generating an ensemble of perturbed emissions and boundary conditions and corresponding tracers online, which enables efficient coupling with the inversion systems CTDAS and CIF. Finally, it was extended with the Vegetation Photosynthesis and Respiration Model (VPRM) of [Mahadevan et al. (2008)](https://doi.org/10.1029/2006GB002735) for the online computation of atmosphere - biosphere exchange of CO2, which is a critical feature for simulations of atmospheric CO2.

The Online Emission Module (OEM) computes emissions "online", i.e. during run time, based on one single gridded emissions file in addition to temporal and vertical scaling profiles. The temporal profiles to be provided are hour-of-day, day-of-week and month-of-year. Those three profiles can be replaced by the profile hour-of-year.

The use of OEM for a tracer in ART is enabled by adding additional xml-tags to the xml metadata of the corresponding tracer. In addition, the input files for OEM are controlled with the namelist `oemctrl_nml`. The following 3 types of "OEM-tracers" are possible: "emis" (enables the update of the tracer with emissions from OEM), "ens" (defines this tracer as a member of an ensemble of perturbed emissions) and "vprm" (used for the tracers representing biospheric fluxes in VPRM).

----

=== OEM tracer with emissions ===

This feature is available with the [icon-kit-dev](https://gitlab.dkrz.de/icon/icon-kit) and [master](https://gitlab.dkrz.de/art/art/-/tree/master/) branch of the icon-kit and art repository, respectively. An example for a standard **OEM tracer with emissions** is given in [Tutorial examples](https://gitlab.empa.ch/abt503/user-guides/-/wikis/ICON-ART-documentation-and-user-guide#tutorial-examples).

Using this feature requires the following settings:

'''XML-tags for OEM tracers (example):'''

<syntaxhighlight lang="xml">
<oem_type type="char">emis</oem_type>
<oem_cat type="char">CH4_A,CH4_B</oem_cat>
<oem_vp type="char">GNFR_A,GNFR_B</oem_vp>
<oem_tp type="char">GNFR_A,GNFR_B</oem_tp>
<oem_tscale type="int">1</oem_tscale>
</syntaxhighlight>

* The main xml-tag to enable OEM is `oem_type`. By setting it to `emis`, the corresponding tracer is updated with emissions by OEM. This type of tracer requires the following 4 additional xml-tags.
* The xml-tag `oem_cat` defines the categories contributing to the emissions of this tracer. The category names (in this example "CH4_A" and "CH4_B") must match the names of the variables in the gridded emission file.
* The xml-tag `oem_vp` defines the vertical profiles for the emission categories. The number of vertical profile categories must match the number of emission categories (`oem_cat`). The category names (in this example "GNFR_A" and "GNF_B") must match the names of the variables in the vertical profile file.
* The xml-tag `oem_tp` defines the temporal profiles for the emission categories. The number of temporal profile categories must match the number of emission categories (`oem_cat`). The category names (in this example "GNFR_A" and "GNF_B") must match the names of the variables in the temporal profile files.
* The xml-tag `oem_tscale` defines the type of temporal profiles used for this tracer. It can either be set to 1 (to use the profiles hour-of-day, day-of-week, and month-of-year) or to 2 (to use the profile hour-of-year).

'''Namelist-parameters in `oemctrl_nml` (for `oem_tscale`=1):'''

<syntaxhighlight lang="bash">
gridded_emissions_nc = 'emission_file.nc'
vertical_profile_nc = 'vertical_profiles.nc'
hour_of_day_nc = 'hourofday.nc'
day_of_week_nc = 'dayofweek.nc'
month_of_year_nc = 'monthofyear.nc'
</syntaxhighlight>

'''Namelist-parameters in `oemctrl_nml` (for `oem_tscale`=2):'''

<syntaxhighlight lang="bash">
gridded_emissions_nc = 'emission_file.nc'
vertical_profile_nc = 'vertical_profiles.nc'
hour_of_year_nc = 'hourofyear.nc'
</syntaxhighlight>

* The file `emission_file.nc` contains the emissions of all categories with the names specified in the xml-tag `oem_cat` on the (2D) dynamical ICON grid. Besides the emissions of the categories, the file must contain the variable "country_ids" with the EMEP country codes for every cell.
* The file `vertical_profiles.nc` contains the vertical profiles of all categories with the names specified in the xml-tag `oem_vp`. The levels of these profiles are specified with the variables "layer_bot", "layer_mid", and "layer_top" on the number of levels specified with the "level" dimension. The interpolation to the ICON levels in the simulation is done by OEM.
* The files `hourofday.nc`, `dayofweek.nc`, `monthofyear.nc`, and `hourofyear.nc` contain the temporal profiles of all categories with the names specified in the xml-tag `oem_tp`. The dimensions for the profile variables in these files are `(hourofday=24,country)`, `(dayofweek=7,country)`, `(monthofyear=12,country)`, and `(hourofyear=8784,country)`, respectively, where "country" corresponds to the number of countries within the domain of the dynamical grid. Note that the 8784 hours of a year correspond to a leap year, which must be considered in the pre-processing of the profiles. In the case of a common year, the last 24 indices of the variable are not used.

== Online Generation of a Flux Ensemble ==

This feature is available with the [https://gitlab.dkrz.de/icon/icon-kit icon-kit-dev] and [https://gitlab.dkrz.de/art/art/-/tree/master/ master] branch of the icon-kit and art repository, respectively. An example for an **ensemble of flux fields** is provided in the [https://gitlab.empa.ch/abt503/user-guides/-/wikis/ICON-ART-documentation-and-user-guide#tutorial-examples Tutorial examples].

It requires the following settings:

=== XML-Tags (Example): ===

**Undisturbed reference tracer** ([https://gitlab.empa.ch/abt503/user-guides/-/wikis/OEM_User_Guide#oem-tracer-with-emissions standard OEM emission tracer]), from which the ensemble is generated:

<syntaxhighlight lang="xml">
<chemtracer id="CH4_A">
<oem_type type="char">emis</oem_type>
<oem_cat type="char">CH4_A,CH4_B</oem_cat>
<oem_vp type="char">GNFR_A,GNFR_B</oem_vp>
<oem_tp type="char">GNFR_A,GNFR_B</oem_tp>
<oem_tscale type="int">1</oem_tscale>
...
</chemtracer>
</syntaxhighlight>

**Each ensemble member:**

<syntaxhighlight lang="xml">
<chemtracer id="CH4_A-001">
<oem_type type="char">ens</oem_type>
...
</chemtracer>
</syntaxhighlight>

* Each ensemble member requires its own entry in the XML file.
* The name format for the ensemble members must be strictly followed. The tracer name of the undisturbed reference tracer (in this example, "CH4_A") is followed by a "-" and a three-digit number indicating the ensemble member number (e.g., "001", "002", "003", etc.). **The tracer name of the undisturbed reference tracer must not contain any "-"**.
* For the ensemble members, no additional XML tags are required. The settings defined by the XML tags (such as `oem_vp` or `oem_tscale`) are inherited from the undisturbed reference tracer.

=== Namelist Parameters in `oemctrl_nml` ===
(In addition to the [https://gitlab.empa.ch/abt503/user-guides/-/wikis/OEM_User_Guide#oem-tracer-with-emissions namelist parameters for the standard OEM emission tracer]):

<syntaxhighlight lang="bash">
ens_reg_nc = 'region_mask.nc'
ens_lambda_nc = 'lambda_file.nc'
</syntaxhighlight>

* The file `region_mask.nc` contains the region mask, linking the individual grid cells to the scaling regions. The file has 1 variable and 1 dimension:
* `int64 REG(cell)` with the `cell` dimension having the same size as the number of grid cells of the dynamical grid. The value in `REG` indicates the scaling region for each grid cell.
* The file `lambda_file.nc` contains the scaling factor for the generation of the flux ensemble. The file has 1 variable and 4 dimensions:
* `float lambda(ens, reg, cat, tracer)`
* `ens`: number of ensemble members (i.e., number of tracers with the `oem_type` set to `ens`)
* `reg`: number of scaling regions
* `cat`: number of categories (i.e., number of categories in `oem_cat` of the undisturbed reference tracer)
* `tracer`: number of tracers from which an ensemble is generated (usually 1)

---

== Perturbation of Tracer Boundary Conditions ==

This feature is available with the [https://gitlab.dkrz.de/icon/icon-kit/-/tree/icon-kit/icon-kit-oem?ref_type=heads icon-kit/icon-kit-oem] and [https://gitlab.dkrz.de/art/art/-/tree/oem?ref_type=heads oem] branch of the icon-kit and art repository, respectively. An example for a setup with **perturbed tracer boundary conditions** is provided in the [https://gitlab.empa.ch/abt503/user-guides/-/wikis/ICON-ART-documentation-and-user-guide#tutorial-examples Tutorial examples].

It requires the following settings:

=== XML-Tags for Ensemble Members: ===

<syntaxhighlight lang="xml">
<chemtracer id="CH4_A-001">
<oem_type type="char">ens</oem_type>
<oem_bg_ens type="char">CH4_BG</oem_bg_ens>
...
</chemtracer>
</syntaxhighlight>

* This setting requires the existence of the following two tracers:
1. An undisturbed reference emission tracer (e.g., "CH4_A").
2. A background tracer updated at the lateral boundaries (e.g., "CH4_BG").
* The "background tracer" is initialized at the beginning of the simulation and updated at the lateral boundaries using the following XML tags:

<syntaxhighlight lang="xml">
<init_mode type="int">1</init_mode>
<latbc type="char">file</latbc>
</syntaxhighlight>

* By adding the `oem_bg_ens` XML tag to the ensemble member, the tracer field of the tracer specified in this tag is copied to the ensemble member and perturbed at the lateral boundaries based on additional region masks and scaling factors.

=== Namelist Parameters in `oemctrl_nml` ===
(In addition to the [https://gitlab.empa.ch/abt503/user-guides/-/wikis/OEM_User_Guide#oem-tracer-with-emissions namelist parameters for the standard OEM emission tracer] and the [https://gitlab.empa.ch/abt503/user-guides/-/wikis/OEM_User_Guide#online-generation-of-a-flux-ensemble namelist parameters for online flux ensemble generation]):

<syntaxhighlight lang="bash">
boundary_regions_nc = 'boundary_mask.nc'
boundary_lambda_nc = 'background_lambdas.nc'
</syntaxhighlight>

* The file `boundary_mask.nc` contains the region mask, linking individual grid cells of the lateral boundary grid to the scaling regions. The file has 2 variables and 2 dimensions:
* `int64 boundaryregion(cell, reg)`
* `int64 global_cell_idx(cell)`
* `cell`: has the same size as the number of grid cells of the lateral boundary grid.
* `reg`: size of the number of scaling regions.
* The values in `boundaryregion` are either 1 or 0. For each scaling region, the grid cells are indicated with 1, while all others are set to 0. `global_cell_idx` indicates the global cell index of each boundary grid cell in the ICON dynamical grid.
* The file `background_lambdas.nc` contains the scaling factor for perturbation of the tracer boundary conditions. The file has 1 variable and 2 dimensions:
* `float lambda(ens, reg)`
* `ens`: number of ensemble members (i.e., number of tracers with the `oem_type` set to `ens`)
* `reg`: number of scaling regions (same as in `boundary_mask.nc`)

== Online VPRM Tracer (for CO2 Respiration and Photosynthesis) ==

The output includes a respiration tracer (RA; CO2 emissions) and a gross photosynthetic production tracer (GPP; CO2 uptake). The net effect should be the difference between the respiration and GPP tracers.

=== Required Settings ===

==== XML Tags for the Two Tracers ====
<syntaxhighlight lang="xml">
<chemtracer id="CO2_RA">
<oem_type type="char">vprm</oem_type>
<oem_ftype type="char">resp</oem_ftype>
...
</chemtracer>
</syntaxhighlight>

<syntaxhighlight lang="xml">
<chemtracer id="CO2_GPP">
<oem_type type="char">vprm</oem_type>
<oem_ftype type="char">gpp</oem_ftype>
...
</chemtracer>
</syntaxhighlight>

==== Namelist Parameters in `oemctrl_nml` ====
<syntaxhighlight lang="bash">
vegetation_indices_nc = 'VPRM_indices_ICON.nc'
</syntaxhighlight>

The file `VPRM_indices_ICON.nc` needs to be produced using [https://github.com/C2SM/modis2grid modis2grid], which remaps MODIS satellite data onto the ICON grid.

== Technical Implementation of OEM ==

=== Reading of the `oemctrl_nml` Namelist ===
To read the `oemctrl_nml` namelist, two new files were added: `src/namelists/mo_oem_nml.f90` and `src/configure_model/mo_oem_config.f90`. The call to read the `oemctrl_nml` is included in `src/namelists/mo_read_namelists.f90`.

---

=== Initialization ===
OEM initialization occurs during ART initialization. All routines are located in `art/emissions/mo_art_oem_init.f90`. Key routines include:

<syntaxhighlight lang="fortran">
PUBLIC :: art_oem_init, &
& art_oem_init_and_read_gridded_emissions, &
& art_oem_init_vertical_profile_fields, &
& art_oem_init_temporal_profile_fields, &
& art_oem_read_temporal_profile_from_file, &
& art_oem_interpolate_vertical_profiles, &
& art_oem_read_vertical_profile_from_file, &
& art_oem_cleanup_vertical_profile_fields
</syntaxhighlight>

The subroutine `art_oem_init` is called from `art_init` in `mo_art_init.f90`. It loops over all tracers, reads their XML tags, and checks for OEM-specific tags. It then initializes variables and calls routines to read emission fields, scaling profiles, and perform required interpolations. If an ensemble tracer is detected, `art_oem_ens_init` from `mo_art_oem_ensemble` (in `art/emissions/mo_art_oem_ensemble.f90`) is called to initialize ensemble members.

---

=== Computation of Emissions ===
Emissions are computed during runtime using `mo_art_oem_emission` in `art/emissions/mo_art_oem_emission.f90`. Key routines include:

<syntaxhighlight lang="fortran">
PUBLIC :: art_oem_compute_emissions, &
& art_oem_extract_time_information
</syntaxhighlight>

`art_oem_compute_emissions` is called at every time step from `art_emission_interface` in `mo_art_emission_interface`. It loops over emission tracers, reads scaling profiles, emission fields, and updates tracer concentrations. Temporal scaling distinguishes three types:
* 0: Constant emissions
* 1: Emissions scaled by hour-of-day, day-of-week, and month-of-year profiles
* 2: Emissions scaled by hour-of-year profile

For temporal scaling type 1, total flux at grid cell ''i'' (in country ''c'') is:

<math> F_i = \sum_{c=1}^{n} F_{i,cat}^{gridded} \times \lambda_{cat,c}^{hour-of-day} \times \lambda_{cat,c}^{day-of-week} \times \lambda_{cat,c}^{month-of-year} \times \lambda_{i,c}^{vertical} </math>

== Generation of a Flux Ensemble ==

The flux ensemble is computed online within the routine art_oem_compute_emissions, which also handles the "regular" online emissions. For each OEM emission tracer, the routine checks if an ensemble with perturbed fluxes is to be generated. If so, it loops through all ensemble members associated with the tracer and applies an additional scaling factor to compute the tracer's emissions at each grid cell:

<math> F_i = \sum_{c=1}^{n} F_{i,cat}^{gridded} \times \lambda_{cat,c}^{hour-of-day} \times \lambda_{cat,c}^{day-of-week} \times \lambda_{cat,c}^{month-of-year} \times \lambda_{i,cat}^{vertical} \times \color{red} \lambda_{i,cat}^{perturbation} </math>

== Perturbation of the Lateral Boundary Tracer Conditions ==

As described in the section Perturbation of Tracer Boundary Conditions, adding the XML tag oem_bg_ens of type string to an ensemble member and setting it to the name of the background tracer (e.g., <oem_bg_ens type="char">CH4_BG</oem_bg_ens>) includes the background tracer field in the ensemble member. The background is scaled using the scaling factors provided in boundary_lambda_nc = 'background_lambdas.nc' based on the region mask defined in boundary_regions_nc = 'boundary_mask.nc'.

Technically, the background field is added to the ensemble member in the routine art_oem_add_bg_ens (from the module mo_art_oem_ensemble). The background tracer concentrations are scaled with the corresponding perturbation scaling factors. During the simulation, only the tendencies of the background field at the boundary grid cells are scaled. For the first lateral boundary timestep, this occurs synchronously in the subroutine art_oem_emissions (on the variable p_nh_state%diag%grf_tend_tracer()), while for subsequent timesteps, it happens asynchronously in the subroutine compute_boundary_tendencies (from the module mo_async_latbc_utils()).

= Running a Limited Area Mode (LAM) Simulation =


=== General ===
=== General ===
Line 1,252: Line 1,491:


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.
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 ==
== Creating A Nested ICON-Grid ==
Line 1,330: Line 1,566:
If you want to generate a finer grid (e.g. R2B10) you might have to increase the allocated memory (-m 64000).
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 ==
= Initial and boundary conditions from CAM-Chem output =
=== XML data are art/runctrl_examples/xml_ctrl ===

===CAM-Chem data===

The Community Atmosphere Model with Chemistry (CAM-Chem) is a component of the Community Earth System Model (CESM) used for simulations of global tropospheric and stratospheric atmospheric composition. The chemistry in CAM-Chem is based on the Model for Ozone and Related Chemical Tracers (MOZART) mechanism. The latest release is CESM2, using the MOZART-T1 mechanism detailed in [Emmons, 2020].

Output from a simulation of CAM-Chem in CESM2 is available online, with the goal of providing initial and time-varying boundary conditions for regional models:

[https://www.acom.ucar.edu/cam-chem/cam-chem.shtml CAM-Chem Download]

The data is provided in NetCDF format with a 0.9x1.25 horizontal resolution and with 56 vertical levels. Currently, data coverage is January 1, 2001 to December 31, 2020. An overview of the chemical species, meteorological fields and aerosols available in the CAM-Chem output is given in the table below. For more details consult the CAM-Chem wiki page:

[https://wiki.ucar.edu/display/camchem/CESM2.1%3ACAM-chem+as+Boundary+Conditions CESM2.1:CAM-Chem as Boundary Conditions]

''Remark:''
''Gas phase chemistry in ICON-ART uses the atmospheric chemistry module MECCA (Module Efficiently Calculating the Chemistry of the Atmosphere). In the current version (MECCA 4.0) only an older version (MOZART-4 [Emmons, 2010]) of the MOZART chemical mechanism is implemented, while its latest expansion, MOZART-T1, is not. However, one can simply add the MOZART-T1 chemical mechanism to the base version of MECCA by specifying new chemical species, reactions and rate coefficients. This allows the use of CAM-Chem output data as described above.''

<summary>Table with species available in CAM-Chem output</summary>

{| class="wikitable"
|+ Species available in CAM-Chem output
! Species !! Description
|-
| PS || Surface pressure [Pa]
|-
| Z3 || Geopotential height (above sea level) [m]
|-
| T || Temperature [K]
|-
| Q || Specific humidity [kg/kg]
|-
| U || Zonal wind [m/s]
|-
| V || Meridional wind [m/s]
|-
| ALKNIT || Standard alkyl nitrate from BIGALK+OH chemistry
|-
| BCARY || Beta-caryophyllene and other sesquiterpenes
|-
| BENZENE || Benzene
|-
| BIGALD || Lumped aldehyde from terpene ozonolysis
|-
| BIGALD1 || Butenedial, a product of aromatic oxidation
|-
| BIGALD2 || 4-oxo-2-pentenal, a product of aromatic oxidation
|-
| BIGALD3 || 2-methyl butenedial, a product of aromatic oxidation
|-
| BIGALD4 || 2-methyl-4-oxo-2-pentenal, a product of aromatic oxidation
|-
| BIGALK || Lumped alkanes C>3
|-
| BIGENE || Lumped alkenes C>3
|-
| C2H2 || Ethyne
|-
| C2H4 || Ethene
|-
| C2H5OH || Ethanol
|-
| C2H6 || Ethane
|-
| C3H6 || Propene
|-
| C3H8 || Propane
|-
| CH2O || Formaldehyde
|-
| CH3CHO || Acetaldehyde
|-
| CH3COCH3 || Acetone
|-
| CH3COCHO || Methyl glyoxal
|-
| CH3COOH || Acetic acid
|-
| CH3OH || Methanol
|-
| CH3OOH || Methyl hydroperoxide
|-
| CH4 || Methane
|-
| CO || Carbon monoxide
|-
| CRESOL || Lumped cresols
|-
| DMS || Dimethyl sulfide
|-
| GLYOXAL || Glyoxal
|-
| H2O2 || Hydrogen peroxide
|-
| HCOOH || Formic acid
|-
| HNO3 || Nitric acid
|-
| H2O || Water
|-
| HO2 || Hydroperoxyl radical
|-
| HO2NO2 || Pernitric acid
|-
| HONITR || Lumped hydroxynitrates from various compounds
|-
| HYAC || Hydroxyacetone
|-
| ISOP || Isoprene
|-
| ISOPNITA || 1,2-hydroxynitrate from OH+isoprene chemistry
|-
| ISOPNITB || 1,4-hydroxynitrate from OH+isoprene chemistry
|-
| MEK || Methyl ethyl ketone
|-
| MACR || Methacrolein
|-
| MPAN || Methacryloyl peroxynitrate
|-
| MTERP || Lumped monoterpenes
|-
| MVK || Methyl vinyl ketone
|-
| N2O || Nitrous oxide
|-
| N2O5 || Dinitrogen pentoxide
|-
| NH3 || Ammonia
|-
| NH4 || Ammonium aerosol
|-
| NO || Nitric oxide
|-
| NO2 || Nitrogen dioxide
|-
| NO3 || Nitrate radical
|-
| PM25 || Particulate matter
|-
| NOA || Nitrooxyacetone, largely from NO3+propene chemistry
|-
| O3 || Ozone
|-
| OH || Hydroxyl radical
|-
| ONITR || Lumped hydroxynitrates
|-
| PAN || Peroxy acetyl nitrate
|-
| PBZNIT || Peroxy benzoyl nitrate
|-
| PHENOL || Phenol
|-
| SO2 || Sulfur dioxide
|-
| TERPNIT || Mostly hydroxynitrates from OH+terpene chemistry
|-
| TOLUENE || Toluene
|-
| XYLENES || Lumped xylenes
|}
</details>

=== Pre-processing ===

Throughout we assume that the chemistry data is provided by CAM-Chem output (MOZART chemistry). We will lay out the pre-processing steps needed to merge the chemical with the meteorological fields, as required when using the Online Emission Module (OEM) in ICON-ART. The chemistry data is given on 56 vertical levels, while the meteorological fields are defined on 137 levels. Thus, vertical interpolation of the chemical fields has to be performed. Moreover, the chemistry data is contained in one single file with a time step of 6 hours. One has to separate the file into multiple files containing one single time step each and subsequently interpolate the data to obtain the same time resolution as for the meteorological variables.

The vertical interpolation and splitting of the data for each time step is done using the Python script
[https://gitlab.empa.ch/abt503/users/keco/icon-art-user-guide-mozart-chemistry/-/blob/main/Scripts/mozart_vertintpl.py mozar_vertintpl.py].

''Remark:''
_The script extracts each time slice from the input file into a separate file and converts a float counting days since 0000-01-01 00:00:00 to a datetime object. Therefore, one might have to adjust the 'time' variable in the chemistry input file to match this convention._

= All input data required for ART standard configurations =
=== XML files are [https://gitlab.dkrz.de/icon/icon-model/-/tree/release-2024.10-public/externals/art/runctrl%20examples/xml%20ctrl?ref%20type=heads here] ===

=== Runscripts are part of the code [https://gitlab.dkrz.de/icon/icon-model/-/tree/release-2024.10-public/externals/art/runctrl_examples/run_scripts?ref_type=heads here] ===
=== Runscripts are part of the code [https://gitlab.dkrz.de/icon/icon-model/-/tree/release-2024.10-public/externals/art/runctrl_examples/run_scripts?ref_type=heads here] ===


Latest revision as of 01:16, 24 January 2025


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

Online emission module (OEM)

Introduction

The online emission module (OEM) is an extension to ICON-ART for the application of temporal and vertical emission profiles online during a simulation. Its concept and functionality is described in [Jähn et al. (2020)](https://doi.org/10.5194/gmd-13-2379-2020). More recently, it was extended with the capability of generating an ensemble of perturbed emissions and boundary conditions and corresponding tracers online, which enables efficient coupling with the inversion systems CTDAS and CIF. Finally, it was extended with the Vegetation Photosynthesis and Respiration Model (VPRM) of [Mahadevan et al. (2008)](https://doi.org/10.1029/2006GB002735) for the online computation of atmosphere - biosphere exchange of CO2, which is a critical feature for simulations of atmospheric CO2.

The Online Emission Module (OEM) computes emissions "online", i.e. during run time, based on one single gridded emissions file in addition to temporal and vertical scaling profiles. The temporal profiles to be provided are hour-of-day, day-of-week and month-of-year. Those three profiles can be replaced by the profile hour-of-year.

The use of OEM for a tracer in ART is enabled by adding additional xml-tags to the xml metadata of the corresponding tracer. In addition, the input files for OEM are controlled with the namelist `oemctrl_nml`. The following 3 types of "OEM-tracers" are possible: "emis" (enables the update of the tracer with emissions from OEM), "ens" (defines this tracer as a member of an ensemble of perturbed emissions) and "vprm" (used for the tracers representing biospheric fluxes in VPRM).

OEM tracer with emissions

This feature is available with the [icon-kit-dev](https://gitlab.dkrz.de/icon/icon-kit) and [master](https://gitlab.dkrz.de/art/art/-/tree/master/) branch of the icon-kit and art repository, respectively. An example for a standard **OEM tracer with emissions** is given in [Tutorial examples](https://gitlab.empa.ch/abt503/user-guides/-/wikis/ICON-ART-documentation-and-user-guide#tutorial-examples).

Using this feature requires the following settings:

XML-tags for OEM tracers (example): 

<oem_type type="char">emis</oem_type>
<oem_cat type="char">CH4_A,CH4_B</oem_cat>
<oem_vp type="char">GNFR_A,GNFR_B</oem_vp>
<oem_tp type="char">GNFR_A,GNFR_B</oem_tp>
<oem_tscale type="int">1</oem_tscale>
  • The main xml-tag to enable OEM is `oem_type`. By setting it to `emis`, the corresponding tracer is updated with emissions by OEM. This type of tracer requires the following 4 additional xml-tags.
  • The xml-tag `oem_cat` defines the categories contributing to the emissions of this tracer. The category names (in this example "CH4_A" and "CH4_B") must match the names of the variables in the gridded emission file.
  • The xml-tag `oem_vp` defines the vertical profiles for the emission categories. The number of vertical profile categories must match the number of emission categories (`oem_cat`). The category names (in this example "GNFR_A" and "GNF_B") must match the names of the variables in the vertical profile file.
  • The xml-tag `oem_tp` defines the temporal profiles for the emission categories. The number of temporal profile categories must match the number of emission categories (`oem_cat`). The category names (in this example "GNFR_A" and "GNF_B") must match the names of the variables in the temporal profile files.
  • The xml-tag `oem_tscale` defines the type of temporal profiles used for this tracer. It can either be set to 1 (to use the profiles hour-of-day, day-of-week, and month-of-year) or to 2 (to use the profile hour-of-year).

Namelist-parameters in `oemctrl_nml` (for `oem_tscale`=1): 

gridded_emissions_nc = 'emission_file.nc'
vertical_profile_nc  = 'vertical_profiles.nc'
hour_of_day_nc       = 'hourofday.nc'
day_of_week_nc       = 'dayofweek.nc'
month_of_year_nc     = 'monthofyear.nc'

Namelist-parameters in `oemctrl_nml` (for `oem_tscale`=2): 

gridded_emissions_nc = 'emission_file.nc'
vertical_profile_nc  = 'vertical_profiles.nc'
hour_of_year_nc      = 'hourofyear.nc'
  • The file `emission_file.nc` contains the emissions of all categories with the names specified in the xml-tag `oem_cat` on the (2D) dynamical ICON grid. Besides the emissions of the categories, the file must contain the variable "country_ids" with the EMEP country codes for every cell.
  • The file `vertical_profiles.nc` contains the vertical profiles of all categories with the names specified in the xml-tag `oem_vp`. The levels of these profiles are specified with the variables "layer_bot", "layer_mid", and "layer_top" on the number of levels specified with the "level" dimension. The interpolation to the ICON levels in the simulation is done by OEM.
  • The files `hourofday.nc`, `dayofweek.nc`, `monthofyear.nc`, and `hourofyear.nc` contain the temporal profiles of all categories with the names specified in the xml-tag `oem_tp`. The dimensions for the profile variables in these files are `(hourofday=24,country)`, `(dayofweek=7,country)`, `(monthofyear=12,country)`, and `(hourofyear=8784,country)`, respectively, where "country" corresponds to the number of countries within the domain of the dynamical grid. Note that the 8784 hours of a year correspond to a leap year, which must be considered in the pre-processing of the profiles. In the case of a common year, the last 24 indices of the variable are not used.

Online Generation of a Flux Ensemble

This feature is available with the icon-kit-dev and master branch of the icon-kit and art repository, respectively. An example for an **ensemble of flux fields** is provided in the Tutorial examples.

It requires the following settings:

XML-Tags (Example):

<chemtracer id="CH4_A">
   <oem_type type="char">emis</oem_type>
   <oem_cat type="char">CH4_A,CH4_B</oem_cat>
   <oem_vp type="char">GNFR_A,GNFR_B</oem_vp>
   <oem_tp type="char">GNFR_A,GNFR_B</oem_tp>
   <oem_tscale type="int">1</oem_tscale>
   ...
</chemtracer>
    • Each ensemble member:**
<chemtracer id="CH4_A-001">
   <oem_type type="char">ens</oem_type>
   ...
</chemtracer>
  • Each ensemble member requires its own entry in the XML file.
  • The name format for the ensemble members must be strictly followed. The tracer name of the undisturbed reference tracer (in this example, "CH4_A") is followed by a "-" and a three-digit number indicating the ensemble member number (e.g., "001", "002", "003", etc.). **The tracer name of the undisturbed reference tracer must not contain any "-"**.
  • For the ensemble members, no additional XML tags are required. The settings defined by the XML tags (such as `oem_vp` or `oem_tscale`) are inherited from the undisturbed reference tracer.

Namelist Parameters in `oemctrl_nml`

(In addition to the namelist parameters for the standard OEM emission tracer): 

ens_reg_nc    =   'region_mask.nc'
ens_lambda_nc =   'lambda_file.nc'
  • The file `region_mask.nc` contains the region mask, linking the individual grid cells to the scaling regions. The file has 1 variable and 1 dimension:
 * `int64 REG(cell)` with the `cell` dimension having the same size as the number of grid cells of the dynamical grid. The value in `REG` indicates the scaling region for each grid cell.
  • The file `lambda_file.nc` contains the scaling factor for the generation of the flux ensemble. The file has 1 variable and 4 dimensions:
 * `float lambda(ens, reg, cat, tracer)`
   * `ens`: number of ensemble members (i.e., number of tracers with the `oem_type` set to `ens`)
   * `reg`: number of scaling regions
   * `cat`: number of categories (i.e., number of categories in `oem_cat` of the undisturbed reference tracer)
   * `tracer`: number of tracers from which an ensemble is generated (usually 1)

---

Perturbation of Tracer Boundary Conditions

This feature is available with the icon-kit/icon-kit-oem and oem branch of the icon-kit and art repository, respectively. An example for a setup with **perturbed tracer boundary conditions** is provided in the Tutorial examples.

It requires the following settings:

XML-Tags for Ensemble Members:

<chemtracer id="CH4_A-001">
  <oem_type type="char">ens</oem_type>
  <oem_bg_ens type="char">CH4_BG</oem_bg_ens>
  ...
</chemtracer>
  • This setting requires the existence of the following two tracers:
 1. An undisturbed reference emission tracer (e.g., "CH4_A").
 2. A background tracer updated at the lateral boundaries (e.g., "CH4_BG").
  • The "background tracer" is initialized at the beginning of the simulation and updated at the lateral boundaries using the following XML tags:
<init_mode type="int">1</init_mode>
<latbc type="char">file</latbc>
  • By adding the `oem_bg_ens` XML tag to the ensemble member, the tracer field of the tracer specified in this tag is copied to the ensemble member and perturbed at the lateral boundaries based on additional region masks and scaling factors.

Namelist Parameters in `oemctrl_nml`

(In addition to the namelist parameters for the standard OEM emission tracer and the namelist parameters for online flux ensemble generation): 

boundary_regions_nc =   'boundary_mask.nc'
boundary_lambda_nc  =   'background_lambdas.nc'
  • The file `boundary_mask.nc` contains the region mask, linking individual grid cells of the lateral boundary grid to the scaling regions. The file has 2 variables and 2 dimensions:
 * `int64 boundaryregion(cell, reg)`
 * `int64 global_cell_idx(cell)`
   * `cell`: has the same size as the number of grid cells of the lateral boundary grid.
   * `reg`: size of the number of scaling regions.
   * The values in `boundaryregion` are either 1 or 0. For each scaling region, the grid cells are indicated with 1, while all others are set to 0. `global_cell_idx` indicates the global cell index of each boundary grid cell in the ICON dynamical grid.
  • The file `background_lambdas.nc` contains the scaling factor for perturbation of the tracer boundary conditions. The file has 1 variable and 2 dimensions:
 * `float lambda(ens, reg)`
   * `ens`: number of ensemble members (i.e., number of tracers with the `oem_type` set to `ens`)
   * `reg`: number of scaling regions (same as in `boundary_mask.nc`)

Online VPRM Tracer (for CO2 Respiration and Photosynthesis)

The output includes a respiration tracer (RA; CO2 emissions) and a gross photosynthetic production tracer (GPP; CO2 uptake). The net effect should be the difference between the respiration and GPP tracers.

Required Settings

XML Tags for the Two Tracers

<chemtracer id="CO2_RA">
  <oem_type type="char">vprm</oem_type>
  <oem_ftype type="char">resp</oem_ftype>
  ...
</chemtracer>

<chemtracer id="CO2_GPP">
  <oem_type type="char">vprm</oem_type>
  <oem_ftype type="char">gpp</oem_ftype>
  ...
</chemtracer>

Namelist Parameters in `oemctrl_nml`

vegetation_indices_nc = 'VPRM_indices_ICON.nc'

The file `VPRM_indices_ICON.nc` needs to be produced using modis2grid, which remaps MODIS satellite data onto the ICON grid.

Technical Implementation of OEM

Reading of the `oemctrl_nml` Namelist

To read the `oemctrl_nml` namelist, two new files were added: `src/namelists/mo_oem_nml.f90` and `src/configure_model/mo_oem_config.f90`. The call to read the `oemctrl_nml` is included in `src/namelists/mo_read_namelists.f90`.

---

Initialization

OEM initialization occurs during ART initialization. All routines are located in `art/emissions/mo_art_oem_init.f90`. Key routines include: 

PUBLIC :: art_oem_init, &
  &       art_oem_init_and_read_gridded_emissions, &
  &       art_oem_init_vertical_profile_fields, &
  &       art_oem_init_temporal_profile_fields, &
  &       art_oem_read_temporal_profile_from_file, &
  &       art_oem_interpolate_vertical_profiles, &
  &       art_oem_read_vertical_profile_from_file, &
  &       art_oem_cleanup_vertical_profile_fields

The subroutine `art_oem_init` is called from `art_init` in `mo_art_init.f90`. It loops over all tracers, reads their XML tags, and checks for OEM-specific tags. It then initializes variables and calls routines to read emission fields, scaling profiles, and perform required interpolations. If an ensemble tracer is detected, `art_oem_ens_init` from `mo_art_oem_ensemble` (in `art/emissions/mo_art_oem_ensemble.f90`) is called to initialize ensemble members.

---

Computation of Emissions

Emissions are computed during runtime using `mo_art_oem_emission` in `art/emissions/mo_art_oem_emission.f90`. Key routines include: 

PUBLIC :: art_oem_compute_emissions, &
  &       art_oem_extract_time_information

`art_oem_compute_emissions` is called at every time step from `art_emission_interface` in `mo_art_emission_interface`. It loops over emission tracers, reads scaling profiles, emission fields, and updates tracer concentrations. Temporal scaling distinguishes three types:

  • 0: Constant emissions
  • 1: Emissions scaled by hour-of-day, day-of-week, and month-of-year profiles
  • 2: Emissions scaled by hour-of-year profile

For temporal scaling type 1, total flux at grid cell i (in country c) is:

Generation of a Flux Ensemble

The flux ensemble is computed online within the routine art_oem_compute_emissions, which also handles the "regular" online emissions. For each OEM emission tracer, the routine checks if an ensemble with perturbed fluxes is to be generated. If so, it loops through all ensemble members associated with the tracer and applies an additional scaling factor to compute the tracer's emissions at each grid cell:

Perturbation of the Lateral Boundary Tracer Conditions

As described in the section Perturbation of Tracer Boundary Conditions, adding the XML tag oem_bg_ens of type string to an ensemble member and setting it to the name of the background tracer (e.g., <oem_bg_ens type="char">CH4_BG</oem_bg_ens>) includes the background tracer field in the ensemble member. The background is scaled using the scaling factors provided in boundary_lambda_nc = 'background_lambdas.nc' based on the region mask defined in boundary_regions_nc = 'boundary_mask.nc'.

Technically, the background field is added to the ensemble member in the routine art_oem_add_bg_ens (from the module mo_art_oem_ensemble). The background tracer concentrations are scaled with the corresponding perturbation scaling factors. During the simulation, only the tendencies of the background field at the boundary grid cells are scaled. For the first lateral boundary timestep, this occurs synchronously in the subroutine art_oem_emissions (on the variable p_nh_state%diag%grf_tend_tracer()), while for subsequent timesteps, it happens asynchronously in the subroutine compute_boundary_tendencies (from the module mo_async_latbc_utils()).

Running a Limited Area Mode (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.

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


Initial and boundary conditions from CAM-Chem output

CAM-Chem data

The Community Atmosphere Model with Chemistry (CAM-Chem) is a component of the Community Earth System Model (CESM) used for simulations of global tropospheric and stratospheric atmospheric composition. The chemistry in CAM-Chem is based on the Model for Ozone and Related Chemical Tracers (MOZART) mechanism. The latest release is CESM2, using the MOZART-T1 mechanism detailed in [Emmons, 2020].

Output from a simulation of CAM-Chem in CESM2 is available online, with the goal of providing initial and time-varying boundary conditions for regional models:

CAM-Chem Download

The data is provided in NetCDF format with a 0.9x1.25 horizontal resolution and with 56 vertical levels. Currently, data coverage is January 1, 2001 to December 31, 2020. An overview of the chemical species, meteorological fields and aerosols available in the CAM-Chem output is given in the table below. For more details consult the CAM-Chem wiki page:

CESM2.1:CAM-Chem as Boundary Conditions

Remark: Gas phase chemistry in ICON-ART uses the atmospheric chemistry module MECCA (Module Efficiently Calculating the Chemistry of the Atmosphere). In the current version (MECCA 4.0) only an older version (MOZART-4 [Emmons, 2010]) of the MOZART chemical mechanism is implemented, while its latest expansion, MOZART-T1, is not. However, one can simply add the MOZART-T1 chemical mechanism to the base version of MECCA by specifying new chemical species, reactions and rate coefficients. This allows the use of CAM-Chem output data as described above.

<summary>Table with species available in CAM-Chem output</summary>

Species available in CAM-Chem output
Species Description
PS Surface pressure [Pa]
Z3 Geopotential height (above sea level) [m]
T Temperature [K]
Q Specific humidity [kg/kg]
U Zonal wind [m/s]
V Meridional wind [m/s]
ALKNIT Standard alkyl nitrate from BIGALK+OH chemistry
BCARY Beta-caryophyllene and other sesquiterpenes
BENZENE Benzene
BIGALD Lumped aldehyde from terpene ozonolysis
BIGALD1 Butenedial, a product of aromatic oxidation
BIGALD2 4-oxo-2-pentenal, a product of aromatic oxidation
BIGALD3 2-methyl butenedial, a product of aromatic oxidation
BIGALD4 2-methyl-4-oxo-2-pentenal, a product of aromatic oxidation
BIGALK Lumped alkanes C>3
BIGENE Lumped alkenes C>3
C2H2 Ethyne
C2H4 Ethene
C2H5OH Ethanol
C2H6 Ethane
C3H6 Propene
C3H8 Propane
CH2O Formaldehyde
CH3CHO Acetaldehyde
CH3COCH3 Acetone
CH3COCHO Methyl glyoxal
CH3COOH Acetic acid
CH3OH Methanol
CH3OOH Methyl hydroperoxide
CH4 Methane
CO Carbon monoxide
CRESOL Lumped cresols
DMS Dimethyl sulfide
GLYOXAL Glyoxal
H2O2 Hydrogen peroxide
HCOOH Formic acid
HNO3 Nitric acid
H2O Water
HO2 Hydroperoxyl radical
HO2NO2 Pernitric acid
HONITR Lumped hydroxynitrates from various compounds
HYAC Hydroxyacetone
ISOP Isoprene
ISOPNITA 1,2-hydroxynitrate from OH+isoprene chemistry
ISOPNITB 1,4-hydroxynitrate from OH+isoprene chemistry
MEK Methyl ethyl ketone
MACR Methacrolein
MPAN Methacryloyl peroxynitrate
MTERP Lumped monoterpenes
MVK Methyl vinyl ketone
N2O Nitrous oxide
N2O5 Dinitrogen pentoxide
NH3 Ammonia
NH4 Ammonium aerosol
NO Nitric oxide
NO2 Nitrogen dioxide
NO3 Nitrate radical
PM25 Particulate matter
NOA Nitrooxyacetone, largely from NO3+propene chemistry
O3 Ozone
OH Hydroxyl radical
ONITR Lumped hydroxynitrates
PAN Peroxy acetyl nitrate
PBZNIT Peroxy benzoyl nitrate
PHENOL Phenol
SO2 Sulfur dioxide
TERPNIT Mostly hydroxynitrates from OH+terpene chemistry
TOLUENE Toluene
XYLENES Lumped xylenes

</details>

Pre-processing

Throughout we assume that the chemistry data is provided by CAM-Chem output (MOZART chemistry). We will lay out the pre-processing steps needed to merge the chemical with the meteorological fields, as required when using the Online Emission Module (OEM) in ICON-ART. The chemistry data is given on 56 vertical levels, while the meteorological fields are defined on 137 levels. Thus, vertical interpolation of the chemical fields has to be performed. Moreover, the chemistry data is contained in one single file with a time step of 6 hours. One has to separate the file into multiple files containing one single time step each and subsequently interpolate the data to obtain the same time resolution as for the meteorological variables.

The vertical interpolation and splitting of the data for each time step is done using the Python script mozar_vertintpl.py.

Remark: _The script extracts each time slice from the input file into a separate file and converts a float counting days since 0000-01-01 00:00:00 to a datetime object. Therefore, one might have to adjust the 'time' variable in the chemistry input file to match this convention._

All input data required for ART standard configurations

XML files are here

Runscripts are part of the code here

All grid, IC, BC and emission data are here

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