View source for 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: [[Simplified Chemistry|click here]]). MECCA uses the Kinetic PreProcessor (KPP) to convert the chemical equations into differential equations that can be used then e.g., in ICON-ART. MECCA already contains a comprehensive chemical mech-
anism, but it also allows to create an own mechanism by changing equations or only picking a subset of equations.
To perform this example, a complete reaction mechanism is created and transferred to ICON-ART. 

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

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

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

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

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

== Preparing the MECCA-xml-file ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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