Creating your First Own Simulation - Introduction to Cases, Resources, and DETCHEM stagnation
In this first tutorial, we will learn how to create all necessary files to run your first own simulation with CaRMeN. This tutorial is therefore aimed for those wanting to quickly simulate an experimental data set, given a certain chemical model and set of conditions.
For this we will take an existing experimental data set and write all necessary files, a so called case, in the most simple way as to obtain a plot in CaRMeN containing both the experimental points and the simulation result.
Steps
1. Preliminary Considerations
Before we get started, there are a few things to consider.
i. System Requirements
In order to write the content of your own files for CaRMeN you will need a professional text editor. Word, Pages, Text Edit or WordPad will not work, since they do not provide the necessary control over the raw text as professional text editors do.
There are a number of suitable text editors available, either paid or for free. Here are two recommendations:
ii. Chemical Information
In this tutorial we will we need a set of chemical information about the species we are working with. This includes molar mass, kinetic theory parameters, enthalpy, entropy and heat capacity, as well as the reaction mechanism. We will use the molar and thermodynamic data, and the mechanism developed by Deutschmann et al. 1 for the catalytic conversion of CH4 over Rh. The mechanism file is written in CHEMKIN format. The original files are available for download as a .zip-file from DETCHEM's homepage. After opening this link click on Example, provide your email address, and click on Send and proceed. The download will begin automatically. After extracting the contents of the file you will see the folder PCCP 2018 10.1039_c7cp07777g, which contains the subfolders experiments and mechanisms. You may move this folder to any location of your choice.
iii. Data Structure
All pertinent files must be consolidated in a common folder, the so called Project Directory. The internal structure of the folder is irrelevant, as long as file paths are correctly accounted for. The simplest of all Project Directories requires, apart from the above mentioned files and a file containing the experimental data, a package.json file (and optionally a carmen.yml file).
The package.json file marks the enclosing directory as a package and is CaRMeN's starting point when loading files. Strictly speaking, a single package.json file suffices to define all required parameters for any number of experimental data sets, models, etc. However, working with only a single file quickly becomes cumbersome to work with as more data and models are added to the project. We will nevertheless restrict ourselves to only a single package.json file for simplicity in this first tutorial. We will restructure the project in the course of the remaining tutorials.
iv. Description of the Example Setup
In this tutorial we will use experimental data collected by Karakaya et al. 2 for the catalytic conversion of CH4 over Rh at 873 K in a stagnation flow reactor. The measured data consists of the concentration profile of CH4, CO, CO2, H2, O2, and H2O with respect to the distance to the catalytic plate. Stagnation flow reactors offer a simple configuration for the investigation of reactions on catalytic surfaces 3. Temperature and concentration profiles within the boundary layer are radially constant and vary only with the distance to the plate surface. Further details on the experimental setup can be found in Karakaya and coworkers publication 2. The original experimental data is also available for download as a .zip-file from DETCHEM's homepage.
The following table summarizes the experimental conditions. All values are given in SI-units.
| name | value | unit |
|---|---|---|
| Gas temperature at inlet | 313.15 | K |
| Gas velocity at inlet | 0.5088 | m/s |
| Gas mole fraction of CH4 | 0.053 | |
| Gas mole fraction of O2 | 0.0257 | |
| Gas mole fraction of Ar | 0.9213 | |
| Distance inlet to disc | 0.039 | m |
| Reactor pressure | 49994 | Pa |
| Surface temperature | 873.15 | K |
2. Creating the Case
Now that we have all the necessary information, including experimental measurements and conditions, as well as the chemical data and mechanism, we can proceed to creating the case for our first simulation.
i. Consolidating Files into the Project Directory
Create a folder with a name of your choice. This directory will be the Project Directory. For this example we will name it first_simulation. Now copy the molar-data file moldata, the thermodynamic-data file thermdata.ckt, and the mechanism file surface.ckr from Deutschmann and coworkers 1 into the Project Directory. The files are part of the examples that can be downloaded from the DETCHEM website. They are located under the path PCCP 2018 10.1039_c7cp07777g/mechanisms/Deutschmann 2001 10.1016_S0167-2991(01)80312-8.
Now copy the file containing the experimental data into the Project Directory. In this example the data is written in the CSV format (comma-separated values) using commas , as delimiters. CSV files can be directly read by CaRMeN. We will take the original data file called CH4-873K-tau_son_processed.csv and rename it to CPOX_stag_873.csv. The original file from Karakaya and coworkers 2 is in the folder downloaded from DETCHEM's homepage under the path /PCCP 2018 10.1039_c7cp07777g/experiments/unpublished data/Stagnation.
Here is a preview of the experimental data when opened with either Pages or Excel:
Note: For CSV files that do not use commas (
,) as delimiters, for example semicolons (;), a resource has to be defined. For more information about resources see the chapters Concepts under the manual section of this documentation and Resource Loaders under the reference section. Later in this tutorial we will introduce you to writing resources.
ii. Writing the package.json File
Now create a new file with the name package.json in the Project Directory. Make sure the file has the extension .json and no additional one. The required format for package.json files is JSON. Here we need to define only one object with three keys: name, version, and carmen. We begin defining an object in JSON by writing a left brace { and hitting enter. On the line below the left brace we insert one level of indentation by writing two blank spaces followed by the first key. The names of keys are given as strings and are therefore surrounded by double quotes ". The name of each key is followed by a colon : and the value of the key. A blank space can be inserted after the colon for better readability. The following is an example of a valid package.json file:
{
"name": "carmen-first-tutorial",
"version": "0.0.0",
"carmen": "carmen.yml"
}
The field name can be given any value as a string. It does not show up in CaRMeN's user interface but rather only serves the program to differentiate between multiple package.json files. Here we give it the name carmen-first-tutorial.
The field version indicates the version of the package. This field is currently ignored, but will be important in future versions of CaRMeN. Here we give "0.0.0" as a value.
The field carmen contains all configurations related to CaRMeN. We can either specify all configuration options here within the package.json file in JSON format, or we can specify a path to an external file. In this tutorial, we will write the configuration in an external file (called carmen.yml) because this allows us to write it in the YAML-Format. YAML is easier to read and write than JSON, and also allows comments to be written in the file. If you are not familiar with the JSON- and YAML-formats, we suggest you read the chapter Data Structures in the manual.
iii. Writing the carmen.yml File
Create now a new file with the name carmen.yml in the Project Directory. Make sure the file has the extension .yml and no additional one. The required format for carmen.yml files is YAML.
NOTE:
carmen.ymlfiles can actually be given any name, as long as it contains the extension.ymland the name of the file matches the value given in thepackage.jsonfile. In this and further tutorials however we will consequently stick to the file namecarmen.ymlfor the sake of clarity.
We begin defining a case in YAML by writing cases: and hitting enter. Cases are then given as an array, each one starting with one level of indentation (i.e. two blank spaces) followed by a hyphen - and enter.
cases:
-
#...
In this and following examples, the comment #... denotes only that the shown code is either an unfinished file or an excerpt from one. Each case requires a title key, a data key, and a configuration key. The first key is written by convention on the line below the hyphen with one additional level of indentation (i.e. two additional blank spaces) with respect to the hyphen. The name of each key is followed by a colon :, a blank space, and the value of the key. Here we write:
cases:
-
title: My first simulation - CPOX 873 Rh
data: ./CPOX_stag_873.csv
configuration:
#...
The title field defines the name of the case shown in CaRMeN's user interface. It is therefore important to give it a name which allows you to quickly and unequivocally identify it. In this example we give it the name My first simulation - CPOX 873 Rh.
The data field is given as a string referencing the file containing the experimental data, starting always with a point followed by a slash ./ and the path to the file. In this example the data file is contained in the same folder as the carmen.yml file so we write ./CPOX_stag_873.csv.
OPTIONAL: The additional key
viewcan be added to the case definition in order to modify visual aspects of the plot shown by CaRMeN. In this case we would want to plot mole fraction of species against the distance to the disk x in meters. For this we could define the labels of the plot axes by writing:cases: - #... view: label: x: distance from disc (x/m) y: mole fractions #...In this an following examples we will give optional fields as comments starting with a number symbol
#followed by a blank space.
The configuration field is an embedded object containing the configuration parameters that are bound to the experimental data. The configuration object requires a driver, an output, and a parameters key. Because these three fields belong to configuration object, we must increase the level of indentation by one (i.e. two additional blank spaces) for them as shown below:
cases:
-
#...
configuration:
driver: detchem_stagnation
output: ./mole_fractions
parameters:
#...
The driver field defines the driver used by CaRMeN for simulating, in other words, it defines the code which will be used by CaRMeN's remote server to perform the calculations. For more information on drivers see the chapter Drivers under the manual and the reference section of this documentation. In this example we choose the DETCHEM stagnation driver by writing detchem_stagnation.
The output field defines the output of the driver by writing a point . followed by a slash / and the name of the desired output format. The available output formats depends on the driver used. Here we define the output to be given as mole fractions of species by writing output: ./mole_fractions.
The parameters field again contains the simulation parameters of the driver for the simulation. Which parameters are allowed depends on the driver used. Amongst others, the DETCHEM stagnation driver requires the fields inlet, surface, f_cat_geo, distance_inlet_disk, and pressure to be defined. Refer to the driver reference for a detailed description of all the available parameters and examples. Because parameters is again an embedded object, the indentation level of the individual parameters must be increased.
cases:
-
#...
parameters:
inlet:
#...
surface:
temperature: 873.15
f_cat_geo: 1
distance_inlet_disk: 0.039
pressure: 49994
#...
The f_cat_geo field defines the ratio of the catalytic to the geometrical area of the catalyst plate. For the sake of simplicity we will assume the catalytic plate to be just a perfectly flat Rh foil, for which we write 1.
The distance_inlet_disk field defines the perpendicular distance of the gas inlet to the catalytic plate given in meters (m), which depends on the particular experimental setup. Here, we use the value 0.039. Note that no units have to be provided, since values are assumed to be in SI-units.
The pressure field defines the reactor pressure in pascals (Pa), for which we use the pressure from the experiment (49994).
The surface field defines the conditions of the catalytic surface. In this case we only define the temperature of the catalytic surface in kelvin (K) to be constant by writing temperature: 873.15 with one additional level of indentation below the surface field. The temperature field is defined within the surface object to indicate the temperature refers to the surface.
The inlet field defines the conditions of the gas flow entering the reactor. It requires a temperature, a gas_velocity, and a mole_fractions key.
cases:
-
#...
inlet:
temperature: 313.15
gas_velocity: 0.5088
mole_fractions:
CH4: 0.053
O2: 0.0257
Ar: "*"
#...
The temperature field defines the temperature of the gas entering the reactor in kelvin (K). We write the measured temperature of the gas flow 313.15.
The gas_velocity field defines the velocity of the gas entering the reactor in meters per second (m/s). We write the measured gas velocity 0.5088.
The mole_fractions field defines the mole fraction of all species in the gas entering the reactor. We write the set mole fractions of CH4 and O2 by writing CH4: 0.053 and O2: 0.0257 as objects, each with one additional level of indentation below the mole_fractions field. As convenience, we define the mole fraction of Ar to be "*", which represents the remaining gas fraction. Please note that an asterisk * has to always be enclosed by double quotes ", even when working in YAML-format.
Your carmen.yml file should now look as follows:
cases:
-
title: My first simulation - CPOX 873 Rh
data: ./CPOX_stag_873.csv
# view:
# label:
# x: distance from disc (x/m)
# y: mole fractions
configuration:
driver: detchem_stagnation
output: ./mole_fractions
parameters:
inlet:
temperature: 313.15
gas_velocity: 0.5088
mole_fractions:
CH4: 0.053
O2: 0.0257
Ar: "*"
surface:
temperature: 873.15
f_cat_geo: 1
distance_inlet_disk: 0.039
pressure: 49994
We have now defined all parameters regarding the experimental data. However, in order for CaRMeN to be able to perform a simulation, we need to define the reaction mechanism as well as the chemical and thermodynamic data to be used. For that we need to add a chemical_model key to the parameters field.
#...
parameters:
#...
chemical_model:
#...
#...
The chemical_model: field defines the chemical mechanism, the chemical data, and thermodynamic data to be used. All of this information is loaded into CaRMeN by using a so called resource. Resources are an important concept in CaRMeN since they allow to import, interpret, and transform external data without requiring the user to modify the original file (i.e. preprocessing). Within the parameters object, resources are imported using the $resource macro. Add a chemical_model field to the existing parameters as shown in the following example:
#...
parameters:
#...
chemical_model:
$resource: model
#...
Macros are objects with a single field that starts with a $ symbol followed by the name of the macro, in case of resources the name of the macro is resource. The $resource field contains the name of the resource to be used, which in this case we still need to define. Here, we chose the name model, so we write $resource: model. Our next task is now to define the model resource, so that CaRMeN can import it and place its contents into the chemical_model field.
There are several kinds of resources available in CaRMeN. Resources are grouped into two categories. The first is that of the so called one-to-one resources, which receive and interpret single files (e.g. the .csv file containing the experimental data). The second category is that of the so called transforming resources, which receive and interpret data from one or more files (e.g. the chemical-model resource which we are currently defining). Transforming resources are always introduced as an object accompanied by a resource definition. For more information on the resources available in CaRMeN see the chapters Resources and Resource Loaders under the manual and the reference section of this documentation.
In order to configure how our chemical model resource will import the chemical data, a resource definition must be specified. Resources are defined in the main carmen configuration file (in our case the carmen.yml file) within the resources field. Multiple resources can be defined, and each definition is an item in the resources list. In YAML, a list (or array) is defined by writing a hyphen with one additional level of indentation (i.e. two blank spaces) as follows:
resources:
-
#...
Now we have to define the resource with the name model. Transforming resources allow three keys in their definition: name, loader, and options. The first key is written by convention on the line below the hyphen with one additional level of indentation (i.e. two additional blank spaces) with respect to the hyphen.
#...
resources:
-
name: model
loader: chemical-model
options:
#...
The name field defines the name of the resource by which it can be referred to within the file. In this case we write model, because we referred to it under that name using the $resource macro in the case definition above.
The loader field specifies which resource loader should be used. Loaders are routines (code) that serve to translate input data from one format into another, generally into a format that CaRMeN can interpret. In this example we need the loader chemical-model which agglomerates species data and reaction data into a single object, the so called chemical model, that is compatible with the DETCHEM stagnation driver.
The options field defines various parameters of the loader and allows for customization. The allowed parameters depend on the loader used. For the chemical-model loader the options field is obligatory and requires a species_database key and a reactions key. See the chemical-model loader entry in the reference for all available options.
#...
resources:
-
name: model
loader: chemical-model
options:
species_database:
- ./moldata
- ./thermo.ckt
reactions:
surface: ./surface.ckr
The species_database: field defines the chemical and thermodynamic data to be used which is contained in the external files moldata and thermo.ckt. The files are referenced by including them as items in the specie_database array. In this case we write ./moldata and ./thermo.ckt.
The reactions field defines the reaction mechanism to be used. The reactions field allows a gas key for gas phase reactions, and a surface key for surface reactions. Since we are only dealing with reactions on the Rh surface (i.e. gas phase reactions are neglected) we need only a surface key under the reactions field.
The surface field refers to the file containing the reaction mechanism starting with a point followed by a slash and the path to the file. In this case the mechanism is contained in the file surface.ckr so we write ./surface.ckr.
Your carmen.yml file should look by now as follows:
cases:
-
title: My first simulation - CPOX 873 Rh
data: ./CPOX_stag_873.csv
# view:
# label:
# x: distance from disc (x/m)
# y: mole fractions
configuration:
driver: detchem_stagnation
output: ./mole_fractions
parameters:
inlet:
temperature: 313.15
gas_velocity: 0.5088
mole_fractions:
CH4: 0.053
O2: 0.0257
Ar: "*"
surface:
temperature: 873.15
f_cat_geo: 1
distance_inlet_disk: 0.039
pressure: 49994
chemical_model:
$resource: model
resources:
-
name: model
loader: chemical-model
options:
species_database:
- ./moldata
- ./thermo.ckt
reactions:
surface: ./surface.ckr
At this point, we have finally defined all parameters for the simulation to run. You may now proceed to load the Project Directory into CaRMeN and run the simulation as shown in the tutorial Quick Start. If you have followed all steps correctly you should see the following result in CaRMeN's Combiner View.
IMPORTANT:__ By following this tutorial you will have created two files, apart from the experimental-data file and the chemical model files, which define a case and contain all the required information to allow CaRMeN to perform a simulation and produce a plot containing both the experimental data and the simulation result. This means that you do not have to select a _mixin (as it was shown in the Tutorial Quick Start) in addition to the case in order to run the simulation.
3. Concluding Remarks
You should now be able to create all necessary files to run your own simulations with CaRMeN, including consolidating the chemical and experimental data and defining cases and resources.
In the next tutorial Modifying your First Own Simulation we will show how to add (or override) certain parameters of the case you just created by using so called mixins. Using mixins will then allow you to quickly vary a number of aspects about your simulation like fitting variables, catalyst structure, or reaction mechanisms by just clicking on them in CaRMeN's user interface.
1. [O. Deutschmann, R. Schwiedemoch, L. I. Maier and D. Chatterjee, Stud. Surf. Sci. Catal., 2001, 251–258, DOI: 10.1016/S0167-2991(01)80312-8] ↩
2. C. Karakaya, L. Maier and O. Deutschmann, Int. J. Chem. Kinet., 2016, 48, 144–160. DOI: 10.1002/kin.20980 ↩
3. H. Gossler, L. Maier, S. Angeli, S. Tischerb and O. Deutschmann, Phys. Chem. Chem. Phys., 2018, Advance Article, DOI: 10.1039/C7CP07777G ↩