MECCA-based (full) Chemistry

- work in progress -

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

This article teaches you...

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

Introductioin

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

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

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

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

Preparing the MECCA-xml-file

Step 0: Download and open the caaba3.0-supplement

Once you have downloaded the caaba3.0-supplement, you can open it in your preferred directory browser or terminal.

Step 1: Setting up the chemical mechanism

If you browse the mecca directory you can check out the gas.eqn file. Just use the text editor if you use the directory browser or use the command

vi gas.eqn

in the terminal. Once you have opened it, you can see all available reactions implemented in MECCA with their respective reaction codes which represents the full MECCA mechanism. In this configuration case we will implement a MECCA chemistry with all available reactions. That's why the gas.eqn can be left as it is.

What to do if not all reactions are wanted

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

What to do if you want to edit existing reactions of the gas.eqn or add new reactions to your mechanism

If a reaction of the gas.eqn is only similar to that one that you want to implement or a specific reaction is not implemented in the gas.eqn, you can make use of replacement-files. Inside the mecca directory, select the rpl directory in which you can copy and rename the example.rpl first of all. If you open it (again with the text editor or with the vi-command you can edit and add your reactions, depending on your scientific goal. If you want to edit a reaction, use the #REPLACE command as well as the number of the respective reaction (e.g. <G4110>) in the first line, then write <a> (<b>, <c>,...) for your first (second, third,...) reaction which belongs to the same reaction number. Below some examples are shown.

• Editing one reaction: Reaction G4110 originally looks like this inside the gas.eqn:

<G4110>  CO + OH = H + CO2           : {%StTrG} (1.57E-13+cair*3.54E-33){§1.15}; {&1628}

Inside the replacement file you can change it for example like this:

 #REPLACE <G4110>
 <a> CO + OH = HO2 + CO2 : {%StTrG} 1.57E-13 + cair*3.54E-33 {&1628}
 #ENDREPLACE

• Split one reaction into two (or more): If you want to split a reaction into several subreactions (e.g. reaction G4101). Originally G4110 looks like this inside the gas.eqn:

<G4101>  CH4 + OH {+O2}= CH3O2 + H2O      : {%StTrG}  1.85E-20{§1.2}*EXP(2.82*log(temp)-987./temp); {&1627}

The splitting can then be written as:

#REPLACE <G4101>
<a> CH4 + OH = CH3 + H2O : {%StTrG} 1.85E-20*EXP(2.82*log(temp)-987./temp); {&&1627}
<b> CH3 + O2 = CH3O2 : {%StTrG} 1E-999; {&&}
#ENDREPLACE

• Adding new reaction: If you want to add a new reaction, define a not yet existing reaction number and write your new reaction:

#REPLACE <>
<G9876JD> XYZ + OH = RO2 + H2O : {%StG} 1.57E-13; {&&}
#ENDREPLACE

Note:

• The added reaction only works for your specific project, it is not implemented in MECCA then and it can't be applied from the gas.eqn afterwards.
• if you try to edit a reaction with a not existing reaction number, an error message will be given

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

Step 2: Setting up the batch file

Inside the mecca directory of the supplement, check out the example.bat file in the batch directory. The batch file is some kind of runscript of the respective MECCA-mechanism to create the belonging Fortran Code and the ICON-Code afterwards. Copy and rename it according to your project. After opening it afterwards you will see the following code lines:

Example batch file (example.bat)

# -*- Shell-script -*-

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

 set apn          = 2                 # number of aerosol phases [0...99, default=0]
 set gaseqnfile   = gas.eqn
 set rplfile      =                   # no replacements
 set wanted       = "Tr && (G || (Aa && Mbl)) && \!I && \!Hg"
 set mcfct        = n                 # Monte-Carlo factor?
 set diagtracfile =                   # diagnostic tracers?
 set rxnrates     = n                 # calculate accumulated reaction rates?
 set tagdbl       = n                 # tagging, doubling, both, none ??
 set kppoption    = k                 # k=kpp, 4=kp4, q=quit
 set integr       = rosenbrock_posdef # integrator
 set vlen         = 256               # only for kp4 and integr=rosenbrock_vec
 set decomp       = n                 # remove indirect indexing
                                      # kp4: 0/1/2/3/q; kpp: y/n/q
 set deltmpkp4    = y                 # delete temporary kp4 files
 set latex        = n                 # latex list of reactions
 set graphviz     = n                 # graphviz plots?
 set deltmp       = n                 # delete temporary xmecca files?

The most parameters can be left as they are. Important is to rename the gas-equation-file and the replacement-file (if you have created one?). Here is a list added with a short explanation of each parameter:

• apn:
• gaseqnfile:
• rplfile:
• wanted:
• mcfct:
• diagtracfile:
• rxnrates:
• tagdbl:
• kppoption:
• integr:
• vlen:
• decomp:
• deltmpkp4:
• latex:
• graphviz:
• deltmp:

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

Step 3: Execute the Mecca script

The first most important preparations are done now. Let's execute the xmecca script by typing

./xmecca

inside the mecca directory and follow the steps. Select your previously created batch file and run it. Now the Fortran files of the selected mechanism are created.

Step4: Transfer MECCA mechanism to ICON

Since the created Fortran code is only located inside Mecca and not in ICON-ART so far, a transfer has to be carried out. A script that performs this transfer can be obtained via

git clone https://gitlab.dkrz.de/art/mecca_preproc.git

Now a new directory Mecca_preproc has been generated where the script create_icon_code4.sh can be found. By executing

./create_icon_code4.sh -h

the following view will be provided:

usage: ./create_icon_code4.sh [-m <mecca_home>] [-i <icon_home>] [-o <file_name>] [-h]
-m <mecca_home> : path to Mecca home directory, e.g. '~/caaba_3.0/mecca'
-i <icon_home>  : path to icon home directory, e.g. '~/icon-kit/src/ICON-ART'
-o <file_name>  : name of the XML file for ICON-ART, e.g. 'tracers_full.xml'
-h              : display help

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

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

Involving Mecca chemistry in a ICON-ART simulation

Now, in the respective runscript the namelist parameter lart_mecca has be set to .TRUE and for cart_mecca_xml the path to the Mecca file can be provided. Important before executing the simulation: As a final step, the ICON code has to be recompiled with the command

./config/dkrz/levante.intel --enable-art --enable-ecrad

and executed afterwards with the command

./make -j8

Afterwards the respective simulation can be executed, e.g. as explained in Lifetime Tracer Simulation. Double check all filled in paths and namelist - especially the ART-namelists. If every namelist parameter in the runscript is filled in correctly, the runscript has to be saved. Afterwards by typing

./exp.testsuite.meccasim_test.run

a job can be submitted to the respective HPC-System. Type the terminal command

squeue

to view a list of your submitted and currently running and jobs. By changing in the output directory you can check the slurm file for possible errors and run times after your job has been run through. In the output directory you can also find all output data for postprocessing in netCDF format.