# mikimo: microkinetic modeling and microkinetic volcano plots for homogeneous catalytic reactions
<details>
<summary style="cursor: pointer;">
☄️ Why use microkinetic modelling? ☄️
</summary>
<p>
<li>Elegant way to deal with complex reaction pathway thermodynamics and kinetics</li>
<li>Accounts for reaction conditions: temperature effects, concentration effects, reaction time, etc.
</p>
</details>
<details>
<summary style="cursor: pointer;">
☄️ What are microkinetic volcano plots? ☄️
</summary>
<p>
<li>Volcano plot: plots the activity (or selectivity) of catalysts against a descriptor variable that uniquely determines a catalyst. Based on linear free energy scaling relationships. </li>
<li>microkinetic volcano plot: the activity/selectivity is expressed the final product concentrations, or ratio of concentrations, after a given time.
</p>
</details>
## Contents
* [Dependencies](#dependencies-)
* [Install](#install-)
* [Usages](#usages-)
* [Examples](#examples-)
* [Known Limitation](#limitation-)
* [Citation](#citation-)
## Dependencies [↑](#dependencies)
The code runs on pure python with the following dependencies:
- `numpy`
- `scipy`
- `autograd`
- `matplotlib`
- `pandas`
- `scipy`
- `h5py`
- `fire`
- `navicat_volcanic`
## Install [↑](#install)
```python
pip install .
```
or
```python
python setup.py install
```
## Usages [↑](#usages)
The code requires two essential inputs for the analysis: energy data, reaction network (along with initial concentrations to be incorporated in the reaction network). All these files must be in the same directory.
- energy data: reaction_data (in csv or xlsx format)
- reaction network: rxn_network (in csv or xlsx format)
- (optional) kinetic data: kinetic_data (in csv or xlsx format)
The energy data must be named "reaction_data" and share similar format as in `navicat_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).
The reaction network must be provided as a 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.
For each step (denoted as *i*) in the reaction network, assign a value of *-n* to the species on the left side of the 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.
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."
Once all input files are ready and `mikimo` is installed, several run options are available:
1. Call just kinetic solver:
```python
python -m navicat_mikimo mkm -d [DIR]
```
2. Microkinetic modelling for all reaction profiles:
```python
python -m navicat_mikimo vp -d [DIR] -nd 0
```
3. To construct microkinetic volcano plot:
```python
python -m navicat_mikimo vp -d [DIR] -nd 1
```
3. To construct microkinetic activity/selectivity map:
```python
python -m navicat_mikimo vp -d [DIR] -nd 2
```
4. To screen over reaction time and temperature:
```python
python -m navicat_mikimo cond -d [DIR]
```
5. To smooth the volcano plots generated:
```python
python replot.py [i]
```
## Examples [↑](#examples)
1. Microkinetic modelling for Pd-catalyzed carbocyclization-borylation of enallene in the presence of chiral phosphoric acid at room temperature for 1 min of reaction time:
```python
python -m navicat_mikimo mkm -d test_cases/pd_carbocylic_borylation/ -t 298.15 -Tf 60
```
2. Microkinetic modelling for all profiles of the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):
```python
python -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 0
```
3. Constructing the microkinetic volcano plot for the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):
```python
python -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 1 -ncore 24
```
4. Constructiong the microkinetic activity/selectivity map for the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):
```python
python -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 2 -ncore 24
```
5. Constructing the activity/selectivity map with time [2-24 hr] and temperature [273.15-423.15 K] as descriptors:
```python
python -m navicat_mikimo cond -d test_cases/pincer_CO2_jacs/ -tt -Tf 7200 86400 -t 273.15 423.15 -ncore 24
```
6. Using filtering to smooth the plot:
```python
python replot.py examples/data/data.h5 -p 3 3 3 -w 20 20 20
```
You can find examples of reading h5 files and regenerating plots in the "examples" folder.
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.
## Known Limitations [↑](#limitation)
1. Overlapping states of different pathways before the reference state (starting point).
2. Bridging states between otherwise separate pathways.
3. Different TSs connecting the same 2 intermediates: just choose the lowest one.
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.
## Citation [↑](#citation)
If you use navicat_mikimo in your work, please cite our work and the forthcoming publication.
Raw data
{
"_id": null,
"home_page": "https://github.com/lcmd-epfl/mikimo",
"name": "navicat-mikimo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "computational chemistry utility",
"author": "pregabalin_hoshiyomi",
"author_email": "pregabalin_Hoshiyomi <thanapat.worakul@epfl.ch>",
"download_url": "https://files.pythonhosted.org/packages/52/e3/dab893ca71fbf659cc1427b89555562c137dc6eca88be6a8449932514752/navicat_mikimo-1.0.0.tar.gz",
"platform": null,
"description": "# mikimo: microkinetic modeling and microkinetic volcano plots for homogeneous catalytic reactions\n\n\n\n<details>\n <summary style=\"cursor: pointer;\">\n \u2604\ufe0f Why use microkinetic modelling? \u2604\ufe0f\n </summary>\n <p>\n <li>Elegant way to deal with complex reaction pathway thermodynamics and kinetics</li>\n <li>Accounts for reaction conditions: temperature effects, concentration effects, reaction time, etc.\n </p>\n</details>\n\n\n<details>\n <summary style=\"cursor: pointer;\">\n \u2604\ufe0f What are microkinetic volcano plots? \u2604\ufe0f\n </summary>\n <p>\n <li>Volcano plot: plots the activity (or selectivity) of catalysts against a descriptor variable that uniquely determines a catalyst. Based on linear free energy scaling relationships. </li>\n <li>microkinetic volcano plot: the activity/selectivity is expressed the final product concentrations, or ratio of concentrations, after a given time.\n </p>\n</details>\n\n## Contents \n* [Dependencies](#dependencies-)\n* [Install](#install-)\n* [Usages](#usages-)\n* [Examples](#examples-)\n* [Known Limitation](#limitation-)\n* [Citation](#citation-)\n\n\n## Dependencies [\u2191](#dependencies)\nThe code runs on pure python with the following dependencies: \n- `numpy`\n- `scipy`\n- `autograd`\n- `matplotlib`\n- `pandas`\n- `scipy`\n- `h5py`\n- `fire`\n- `navicat_volcanic`\n\n## Install [\u2191](#install)\n\n```python\npip install .\n```\n\nor \n\n```python\npython setup.py install\n```\n\n## Usages [\u2191](#usages)\n\nThe code requires two essential inputs for the analysis: energy data, reaction network (along with initial concentrations to be incorporated in the reaction network). All these files must be in the same directory.\n\n- energy data: reaction_data (in csv or xlsx format)\n- reaction network: rxn_network (in csv or xlsx format)\n- (optional) kinetic data: kinetic_data (in csv or xlsx format)\n\n\nThe energy data must be named \"reaction_data\" and share similar format as in `navicat_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).\n\nThe reaction network must be provided as a 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.\n\nFor each step (denoted as *i*) in the reaction network, assign a value of *-n* to the species on the left side of the 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.\n\nThe 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.\" \n\n\nOnce all input files are ready and `mikimo` is installed, several run options are available:\n\n1. Call just kinetic solver:\n```python\npython -m navicat_mikimo mkm -d [DIR]\n```\n2. Microkinetic modelling for all reaction profiles:\n```python\npython -m navicat_mikimo vp -d [DIR] -nd 0\n```\n\n3. To construct microkinetic volcano plot:\n```python\npython -m navicat_mikimo vp -d [DIR] -nd 1\n```\n\n3. To construct microkinetic activity/selectivity map:\n```python\npython -m navicat_mikimo vp -d [DIR] -nd 2\n```\n\n4. To screen over reaction time and temperature:\n```python\npython -m navicat_mikimo cond -d [DIR] \n```\n\n5. To smooth the volcano plots generated: \n```python\npython replot.py [i]\n```\n\n## Examples [\u2191](#examples)\n\n1. Microkinetic modelling for Pd-catalyzed carbocyclization-borylation of enallene in the presence of chiral phosphoric acid at room temperature for 1 min of reaction time: \n```python\npython -m navicat_mikimo mkm -d test_cases/pd_carbocylic_borylation/ -t 298.15 -Tf 60\n```\n\n2. Microkinetic modelling for all profiles of the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):\n```python\npython -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 0\n```\n\n3. Constructing the microkinetic volcano plot for the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):\n```python\npython -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 1 -ncore 24\n```\n\n4. Constructiong the microkinetic activity/selectivity map for the catalytic competing carboamination and cyclopropanation of N-enoxyphathanalimides with alkenes (353.15 K, 1 d):\n```python\npython -m navicat_mikimo vp -d volcanic_test/CA_CP_selectivity/ -t 353.15 -nd 2 -ncore 24\n```\n\n5. Constructing the activity/selectivity map with time [2-24 hr] and temperature [273.15-423.15 K] as descriptors:\n\n```python\npython -m navicat_mikimo cond -d test_cases/pincer_CO2_jacs/ -tt -Tf 7200 86400 -t 273.15 423.15 -ncore 24\n```\n\n6. Using filtering to smooth the plot:\n\n```python\npython replot.py examples/data/data.h5 -p 3 3 3 -w 20 20 20\n```\n\nYou can find examples of reading h5 files and regenerating plots in the \"examples\" folder.\n\nIf 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. \n\n## Known Limitations [\u2191](#limitation)\n\n1. Overlapping states of different pathways before the reference state (starting point).\n\n2. Bridging states between otherwise separate pathways.\n\n3. Different TSs connecting the same 2 intermediates: just choose the lowest one.\n\nTo 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.\n\n## Citation [\u2191](#citation)\n\nIf you use navicat_mikimo in your work, please cite our work and the forthcoming publication.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "microkinetic modeling code for homogeneous catalytic reactions",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/lcmd-epfl/mikimo"
},
"split_keywords": [
"computational",
"chemistry",
"utility"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c00edf0118afb35433e3370d86b609e0e43cf612755c9835be82aef56bf6368a",
"md5": "5f2851241920a5fb67c765f20226de8d",
"sha256": "044bdc5d21bd60a679e22886e84a3219aac9d4a985eba253a441c89b52fe14f1"
},
"downloads": -1,
"filename": "navicat_mikimo-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f2851241920a5fb67c765f20226de8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 47169,
"upload_time": "2023-09-27T07:56:51",
"upload_time_iso_8601": "2023-09-27T07:56:51.572099Z",
"url": "https://files.pythonhosted.org/packages/c0/0e/df0118afb35433e3370d86b609e0e43cf612755c9835be82aef56bf6368a/navicat_mikimo-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "52e3dab893ca71fbf659cc1427b89555562c137dc6eca88be6a8449932514752",
"md5": "17c8046557d47c7d627ce7f98f1b6d87",
"sha256": "89e3e110e07cb0eaf2c207405f7015af4d772a0b153995b6b3a801e7e0e58f93"
},
"downloads": -1,
"filename": "navicat_mikimo-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "17c8046557d47c7d627ce7f98f1b6d87",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 45113,
"upload_time": "2023-09-27T07:56:53",
"upload_time_iso_8601": "2023-09-27T07:56:53.389799Z",
"url": "https://files.pythonhosted.org/packages/52/e3/dab893ca71fbf659cc1427b89555562c137dc6eca88be6a8449932514752/navicat_mikimo-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-27 07:56:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lcmd-epfl",
"github_project": "mikimo",
"github_not_found": true,
"lcname": "navicat-mikimo"
}
JSON
