Skip to Content

Create chemistry scheme

Last modified by pecl@helsinki_fi on 2024/01/26 07:24

CCSteps.png

KPP

You will need the Kinetic PreProcessor (KPP) installed on your computer to be able to create the final chemistry source code. KPP is provided in ARCAs install/ directory, and we recommend using it, because we have added some small tweaks which enable the use of longer variable names and larger equation sets. However, you can use ARCAs Create chemistry scheme tool even without KPP, you will get the definition file for KPP, but you will not be able to take the final step of putting the new scheme to use in ARCA.

Reactions and reaction rates

Acquiring the reactions and reaction rates is your next job, and the backbone of your scheme would most likely come from the Master Chemical Mechanism (MCM). In addition, there might be other reactions you want to study. The chemistry scheme can be used in many creative ways, for example to study reactivities etc, which are out of the scope of this manual. Just know that the functionality does not end with calculating concentrations.

Below we explain what you need from MCM to get the necessary file.

  1. Browse the mechanism, pick the precursor compounds you are going to feed in the model. Make sure they are also added to the Mark List, shown here with 1b. Also note that the contents of the mark list in this figure is just an example, yours will be different.
  2. When your compounds are in the Mark List, click Extract and you will land on the page in the figure below.
  3. Choose option "KPP, experimental KPP format"
  4. Don't forget to include both these options.
  5. Exctract
  6. You will get the file which is needed by the Create chemistry scheme tool.
  7. Hold on to this file

For possible future use, also save the molecular weights and SMILES codes, by selecting the button shown in green ellipse!

mcm.png

Applying Create chemistry scheme

You can access this tool from the toolbar menu Tools::Create chemistry scheme or from the tab Chemistry→Chemistry tools by pressing Create chemistry scheme:

The purpose of ARCAs Create chemistry scheme tool is to create the definition file for KPP: "second.def". In addition, the tool copies the parsing options for  KPP: "second.kpp" settings and the interface template (in KPP lingo called the "driver"). The script also saves a log file "second.log". With the three first files you can run KPP and parse the Fortran files - which then can be used as a chemistry scheme in ARCA. Here we explain what the options in the Create chemistry scheme dialog mean.

NewCC.png

Output directory

This is the path to the directory where the output of this script are stored. It doesn't really matter where they are initially stored, but keep in mind that to add the final scheme to ARCA, the files need to be in their own directory inside src/chemistry.

Main source file

This is the file you got from MCM (by default "mcm_subset.kpp" or similar)

Include PRAM_v21

This option includes the Peroxy Autoxidation Mechanism (PRAM) to the chemistry. PRAM simulates the formation of Highly Oxygenated Molecules (HOM) from monoterpenes (C10H16). The effect of this option is same as including the PRAM file in the "Other included files".

Other included files

This option lets you add other mechanisms, if they conform to the same format than is used by the mcm file. You can add as many files you need.

Create KPP settings

Pressing this will start the tool. It will combine the input files, remove any reactions that are exact duplicates and issue warning if there are files missing or similar reactions with different rates. It will also add some necessary ingredients which do not come from mcm, such as complex reaction rates, and apply other small tweaks to accomodate ARCAs needs. The main product of the script is the "second.def" file (the name of the file goes long way back to history, and legend says that there once was a file called "first.def").

Possible problems
  • The script might find duplicate equations that have the same reactants and products but differing rates. Since it cannot know which one is correct, it will include both. You should remove one of them from the output "second.def". You should always read the "second.log" to make sure that there are no other issues.
  • when running KPP, you might get other warnings. you can solve them in the second.def file, but it might be good to think if they should already be fixed earlier in the process chain.

Applying KPP

If you have KPP installed and properly configured (KPP.zip has all the necessary instructions for this), you should be able to run KPP from the directory you saved the files from the previous step. Then you just type the command:

kpp second.kpp

If KPP runs succesfully, then this step is done. If not, read the error messages. For example, there might undefined variables, make sure they are defined in the second.def file.

Switching to the new chemistry scheme

After KPP has done it's job, and the produced second_*.f90 (about a dozen of them) files are in their own folder inside src/chemistry, you can switch to that chemistry. Go to tab Chemistry, select the Switch chemistry scheme option and pick the new chemistry scheme from the Available schemes popup menu (1). Then click Recompile (2). Note that for the first time the compilation of the chemistry scheme could take a long time, and that means a looong time, like hours. However, once this is done, switching to this scheme is much faster since the compiled objects are store in build/[Your_chemistry_name] directory, and are not recompiled unless the actual source code is changed.

SwitchChem.png


If for some reason you want to remove also the previous compiled objects, check the box "Clean everything before compilation..." and recompile.








.