Quick Start - Introduction to CaRMeN's Workflow
This chapter aims to serve as a quick guide for installing and setting up CaRMeN, along with a series of experimental data sets and chemical models, and to introduce you to CaRMeN's workflow.
Steps
1. Downloading and Installing CaRMeN
CaRMeN is available for download for both Mac and Windows from the DETCHEM website. Select the version that matches your operating system, provide your email address, and click on Send and proceed. CaRMeN will be downloaded automatically. A collection of experimental data sets and reaction mechanisms for trying CaRMeN are also available as a .zip-file.
The Mac version is provided as an application. It can be run immediately by just double clicking the CaRMeN.app file, either directly on the download folder or after copying into the application folder of your system.
The Windows version can be installed by executing the CaRMeN.exe file.
2. Loading Files
NOTE FOR WINDOWS USERS: CaRMeN can take about a minute to start up. During this time you may not see any changes happening or windows opening.
After extracting the contents of the downloaded examples .zip-file, you will see a folder named PCCP 2018 10.1039_c7cp07777g. This folder contains two subfolders: experiments and mechanisms. You may move this folder into any location of your choice.
To load the example files in CaRMeN, you must first open CaRMeN and then click on the folder icon located furthest left in the top blue icon bar. A Finder window (or explorer window for Windows) will open. Locate the folder PCCP 2018 10.1039_c7cp07777g. This will be the so-called Project Directory. Select it and click open. A detailed description of CaRMeN's user interface is provided in the chapter Description of CaRMeN's User Interface under the manual section of this documentation.
NOTE: Do not try to load the
experimentsor themechanismsfolder, nor any file contained in these folders individually. CaRMeN will recursively search all folders contained in the Project Directory and load all available files.
You can see the loaded experimental data sets as so called cases in the Cases view and the loaded chemical models as so called mixins in the Mixins view. To switch between these views click on the second (beaker) or third icon (suitcase with molecule) of the right side in the top blue icon bar. CaRMeN automatically checks every loaded case and mixin for compatibility. Any errors will be reported in the Event Log view, which is accessible by clicking on the warning icon. The Project Directory can be loaded anew by clicking on the refresh-folder icon located second from the left in the top blue icon bar.
3. Running Simulations
NOTE: A stable working internet connection is necessary for running simulations with CaRMeN. This is because simulations are run on CaRMeN's remote server.
After loading the Project Directory containing the downloaded example files go to the Combiner View by clicking on the icon located furthest right in the top blue icon bar. You will now see all loaded cases on the left column of the window and all mixins in the right. In order to run a simulation with this downloaded set of example files you must first select the experimental data and the chemical model you wish to investigate.
For this example select the first experimental data set (case) from Pery-Warnatz 2002 named "CO OX stagnation Pery-Warnatz CO/O2=0.5 T=300-750K" on the left. A graph will appear showing the experimental data points, axis labels and a legend of the depicted species. In this example the coverage fraction of the Rhodium surface by carbon monoxide is plotted against the temperature in Kelvin (K). The colour used for the experimental points in the graph corresponds to the colour given to CO-Rh in the legend below the graph. Above the graph the title of the case is shown.
To the left of the case's title a warning icon in form of a yellow triangle with an exclamation mark will be shown. To obtain further information move the cursor over the warning icon. A blue popup will appear, indicating an validation error: "Configuration should have required property 'chemical_model' (missingProperty: chemical_model)". This validation error occurs because the selected case contains no information about the chemical model (defined here as a mixin), but a chemical model is required to run the simulation.
In order to get the validation to pass, select the last mechanism (mixin) in the right sidebar named "CO H2 O2 Rankovic-DaCosta 2011". The warning icon is replaced by a circular progress icon. Move the cursor over the progress icon to receive a explanatory notification. In this case, the text "Status: validating" appears. This indicates that CaRMeN is validating the selected case-mixin combination on CaRMeN's remote server. After a few seconds, the icon will be replaced by a play icon, indicating that the selected case-mixin combination is valid, and that the simulation can now be run. The status of is now "valid". Upon selecting a mixin, the title of the mixin is shown below the legend of the graph. To the left of the mixin's title a tilted solid line is shown which corresponds to the line that will be used to display the result of the simulation after it has been run.
NOTE: If no connection to CaRMeN's remote server can be stablished, a red-X icon will appear to the right of the mixin's title in the Detailed Comparison view. A report will also be shown in the Event Log window.
Please check your internet connection before continuing. After reestablishing your internet connection right-click on the red-X icon and select the action retry.
If there is an incompatibility between the selected case and mixin a warning icon will appear. Placing the mouse pointer over the warning icon will provide further information about the problem.
By clicking on either of the two play icons the simulation will be initiated on CaRMeN's remote server. The play icons will be replaced again by progress icons. Placing the mouse pointer over one of the progress icons will show the notification "Status: running", which indicates that the simulation is running. A status of "pending" indicates that the simulation is queued due to other requests.
NOTE: Some simulations, especially end-of-pipe simulations (EOP), may take several minutes to be completed. Previously run simulations are saved both locally on your computer, under the folder
cachein the Project Directory, and on CaRMeN's remote server. Results for such simulations can therefore be retrieved and shown faster.
After the simulation has been successfully completed the result will be plotted in the Detailed Comparison view together with the experimental data points. Progress icons will be replaced by green-check icons. Placing the mouse pointer over one of the green-check icons will show the notification "Status: success", which indicates that the simulation was successfully completed. You can now visually compare the result of the simulation with the experimental data.
You may also want to compare the experimental data with the simulation result by using the Parity Plot view. Parity plots can be exported as .csv-files by using the option Export in the Parity Plot view. You can zoom in and out of any plot by scrolling over the plot, either with your mouse's scrolling wheel or with your trackpad.
NOTE: Failed simulations receive a red-X icon. Further information can be obtained by placing the mouse pointer over the red-X icon.
CaRMeN's remote server parallelizes simulations. You can take advantage of this by selecting two or more cases and/or two or more mixins you may want to test. To run simulations on a selected experimental data set (case) with all selected mechanisms (defined here as mixins) you can click on the play icon next the case's title above the graph in the Detailed Comparison view. You may alternatively run each simulation individually by clicking on the play icon next to title of the mixin you want to test in the Detailed Comparison view.
4. Concluding Remarks
At this point, you should now be able to install and set up a copy of CaRMeN and to load experimental data sets and chemical models to run simulations.
More information about how to use CaRMeN is provided as a tutorial series under the Tutorials section of this documentation. This tutorial series aims to introduce you step by step to CaRMeN's workflow and to help you unleash it's full potential.
ADVANCED: The raw data generated by CaRMeN during a simulation is saved in the Project Directory under the folder
cache. If you wish to view the raw data corresponding to a specific simulation, you may do so by right-clicking on the green-check (or red-X) icon next to the case's title after running the simulation and choosing the action Show Directory from the pop-up-menu. A Finder window (or explorer window for Windows) will open showing the desired cache files. Choosing the action Show Details from the pop-up-menu opens the Status Details window containing the configuration parameters of each calculation of the simulation. The Status Details window can be closed by clicking on the X icon on the top right corner of the window.