You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[Command Line Interface](#command-line-interface-)
34
+
*[Running Simulations](#running-simulations-)
35
+
*[Outputs](#outputs-)
36
+
*[Replotting Utility](#replotting-utility-)
33
37
*[Examples](#examples-)
34
38
*[Limitations](#limitations-)
35
39
*[Citation](#citation-)
@@ -42,7 +46,7 @@ The code runs on pure python with the following dependencies:
42
46
-`autograd`
43
47
-`matplotlib`
44
48
-`pandas`
45
-
-`scipy`
49
+
-`scikit-learn`
46
50
-`h5py`
47
51
-`fire`
48
52
-`navicat_volcanic`
@@ -61,64 +65,113 @@ or
61
65
python setup.py install
62
66
```
63
67
64
-
## Usages [↑](#usages)
65
-
66
-
The code requires two essential inputs for the analysis: energy data and reaction network (along with initial concentrations to be incorporated in the reaction network). All these files must be in the working directory or in the directory targeted with the `-d` option..
67
-
68
-
- energy data: reaction_data (in csv or xlsx format)
69
-
- reaction network: rxn_network (in csv or xlsx format)
70
-
- (optional) kinetic data: kinetic_data (in csv or xlsx format)
71
-
72
-
73
-
The energy data must be named "reaction_data" and share similar format as in `navicat_volcanic` found [here](https://raw.githubusercontent.com/lcmd-epfl/volcanic). In cases involving multiple reaction pathways, the final column of each pathway (including those pathways leading to the resting state) should contain "Prod" (case-insensitive).
74
-
75
-
The reaction network must be provided as a pandas-compatible csv or xlsx file named "rxn_network". Each row in the network represents an elementary step, while the columns represent the chemical species involved in the mechanism, excluding transition states. When filling in the reaction network, it is crucial to ensure that the species names match those in the energy data.
76
-
77
-
For each step (denoted as *i*) in the reaction network, assign a value of *-n* to the species on the left side of the elementary step equation and *+n* (or simply *n*) to the species on the right side, where *n* represents the stoichiometric coefficient. If a chemical species is not involved in step i, leave the corresponding cell empty or fill it with 0.
78
-
79
-
The initial concentrations should be specified in the last row of the reaction network file. This row can be named "c0", "initial_conc," or "initial conc."
80
-
81
-
82
-
The code offers three modes of operation:
83
-
84
-
-**mkm**: This mode is for a single MKM run. If there are multiple profiles in the reaction data file, the top-most row is read.
85
-
-**cond**: Use this mode for screening over reaction time and/or temperature.
86
-
-**vp**: This mode is for screening over all energy profiles in the reaction data file. Note that it's only applicable when the reaction data contains more than one energy profile.
87
-
88
-
Once all input files are ready and `mikimo` is installed, several run options are available:
89
-
90
-
1. Call just microkinetic solver:
68
+
## Input Preparation [↑](#input-preparation)
69
+
70
+
The code requires two essential inputs for the analysis: energy/kinetic data and reaction network (along with initial concentrations). All files must be in the working directory or in the directory targeted with the `-d` option.
71
+
72
+
### 1. Reaction Data (Energy Profile)
73
+
***Filename:**`reaction_data.csv` or `reaction_data.xlsx`
74
+
***Format:** Matches the `navicat_volcanic` format found [here](https://raw.githubusercontent.com/lcmd-epfl/volcanic).
75
+
***Details:**
76
+
* In cases involving multiple reaction pathways, the final column of each pathway (including those leading to the resting state) should contain "Prod" (case-insensitive).
77
+
* Used by default.
78
+
79
+
### 2. Kinetic Data (Rate Constants)
80
+
***Filename:**`kinetic_data.csv` or `kinetic_data.xlsx`
81
+
***Format:** Similar structure to reaction data but values are rate constants.
82
+
***Details:**
83
+
* Used when the `-k` or `--kinetic` flag is active.
84
+
* Allows inputting direct rate constants, bypassing Eyring equation calculations.
85
+
***Note:** Screening over temperature ranges is not supported in this mode.
86
+
87
+
### 3. Reaction Network
88
+
***Filename:**`rxn_network.csv` or `rxn_network.xlsx`
89
+
***Format:** Pandas-compatible CSV/XLSX.
90
+
***Structure:**
91
+
***Rows:** Elementary steps.
92
+
***Columns:** Chemical species involved (excluding transition states).
93
+
***Values:** Stoichiometric coefficients.
94
+
* Left side (Reactants): `-n`
95
+
* Right side (Products): `+n`
96
+
* Not involved: `0` or empty.
97
+
***Matching:** Species names must match those in the `reaction_data`/`kinetic_data`.
98
+
***Initial Concentrations:** Specified in the last row, labeled "c0", "initial_conc", or "initial conc".
99
+
100
+
## Command Line Interface [↑](#command-line-interface)
101
+
102
+
The main tool is `navicat_mikimo`. Below are the available flags:
|`-is`|`--imputer_strat`| Strategy to fill missing data (`knn`, `iterative`, `simple`). |`knn`|
120
+
|`-tt`|`--map`| Construct a Time-Temperature activity map. |`False`|
121
+
122
+
## Running Simulations [↑](#running-simulations)
123
+
124
+
The code offers three main modes of operation:
125
+
126
+
### 1. Single MKM Run (`mkm`)
127
+
Performs a single microkinetic modeling run. If multiple profiles exist, the top-most row (or specified via `-e`) is used.
91
128
```python
92
129
python -m navicat_mikimo mkm -d [DIR]
93
130
```
94
-
2. Microkinetic modeling for all reaction profiles:
95
-
```python
96
-
python -m navicat_mikimo vp -d [DIR] -nd 0
97
-
```
98
131
99
-
3. To construct microkinetic volcano plot:
132
+
### 2. Screening / Volcano Plots (`vp`)
133
+
Screens over all profiles in the reaction data file.
134
+
***Run MKM for all profiles (no plot):**`-nd 0`
135
+
***Volcano Plot:**`-nd 1`
136
+
***Activity/Selectivity Map:**`-nd 2`
137
+
100
138
```python
101
139
python -m navicat_mikimo vp -d [DIR] -nd 1
102
140
```
103
141
104
-
4. To construct microkinetic activity/selectivity map with a descriptor variable representing catalyst and temperature (or reaction time) (T1 and T2 are the lower and upper bounds of the temperature range, respectively):
142
+
### 3. Conditions Screening (`cond`)
143
+
Screens over reaction time and/or temperature ranges.
105
144
```python
106
-
python -m navicat_mikimo vp-d [DIR]-nd 1-t T1 T2
145
+
python -m navicat_mikimo cond-d [DIR]
107
146
```
108
147
109
-
5. To construct microkinetic activity/selectivity map:
110
-
```python
111
-
python -m navicat_mikimo vp -d [DIR] -nd 2
112
-
```
148
+
## Outputs [↑](#outputs)
149
+
150
+
***Single Run (`mkm`):**
151
+
*`mkm_output.json`: Time-course data.
152
+
*`mkm_[name].png`: Concentration evolution plot.
153
+
***Volcano/Screening (`vp`, `cond`):**
154
+
***HDF5 Files:**`mkm_vp.h5`, `mkm_descr_phys.h5`, `mkm_vp_3d.h5`. Contain raw data for replotting.
155
+
***Plots:** Combo plots, profile plots, and activity/selectivity maps (PNG).
156
+
157
+
## Replotting Utility [↑](#replotting-utility)
158
+
159
+
A standalone script `replot.py` is provided to smooth or adjust plots using generated HDF5 files.
6. Constructing microkinetic activity and selectivity maps with reaction time [2-24 hr] and temperature [273.15-423.15 K] as descriptors for the catalytic hydrosilylation of carbon dioxide with the Co pincer complex:
You can find examples demonstrating how to read h5 files and regenerate plots in the "examples" folder.
164
220
165
-
If the kinetic profile is detected in the directory, the code will prompt the user with an option to choose between using the kinetic profile instead of the energy profile. However, it's important to note that selecting the kinetic profile will restrict the user from screening over a range of temperatures or utilizing different temperature settings. Additionally, using the kinetic profile will limit the information about species names (for ax labelling purposes) and may worsen the quality of the linear scaling relationships in volcano plot generation.
166
-
167
221
## Limitations [↑](#limitations)
168
222
169
-
1. Overlapping states of different pathways before the reference state (starting point).
223
+
1.**Overlapping states** of different pathways before the reference state (starting point).
224
+
2.**Bridging states** between otherwise separate pathways.
225
+
3.**Different TSs** connecting the same 2 intermediates: just choose the lowest one or compute an effective TS energy that corresponds to the sum of the two rate constants.
170
226
171
-
2. Bridging states between otherwise separate pathways.
172
-
173
-
3. Different TSs connecting the same 2 intermediates: just choose the lowest one or compute an effective TS energy that corresponds to the sum of the two rate constants.
174
-
175
-
To overcome these limitations and offer more flexibility, users have the option to input a kinetic profile named "kinetic_profile" in either csv or xlsx format, replacing the conventional energy profile. However, this choice comes with the trade-off of disabling the ability to screen over a range of temperatures or use different temperature settings.
227
+
To overcome these limitations and offer more flexibility, users have the option to input a kinetic profile named "kinetic_data" in either csv or xlsx format, replacing the conventional energy profile. However, this choice comes with the trade-off of disabling the ability to screen over a range of temperatures or use different temperature settings.
176
228
177
229
## Citation [↑](#citation)
178
230
@@ -181,5 +233,4 @@ If you use navicat_mikimo in your work, please cite our work and the publication
181
233
```
182
234
Worakul, T., Laplaza, R., Das, S., Wodrich, M.D., Corminboeuf, C., Microkinetic Molecular Volcano Plots for Enhanced Catalyst Selectivity and Activity Predictions. ACS Catalysis 2024 14 (13), 9829-9839.
0 commit comments