# mikimo: microkinetic modeling and microkinetic volcano plots for homogeneous catalytic reactions
<details>
<summary style="cursor: pointer;">
☄️ Why use microkinetic modeling? ☄️
</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: diagrams that show the activity (or selectivity) of catalysts plotted against a descriptor variable that identifies a specific catalyst. Based on linear free energy scaling relationships. </li>
<li>Microkinetic volcano plot: volcano plots in which the activity/selectivity is expressed as the final product concentration, or a ratio of concentrations, after a given time.
</p>
</details>
## Contents
* [Dependencies](#dependencies-)
* [Install](#install-)
* [Usages](#usages-)
* [Examples](#examples-)
* [Limitations](#limitations-)
* [Citation](#citation-)
## Dependencies [↑](#dependencies)
The code runs on pure python with the following dependencies:
- `numpy`
- `scipy`
- `autograd`
- `matplotlib`
- `pandas`
- `scipy`
- `h5py`
- `fire`
- `navicat_volcanic`
- `openpyxl`
- `tqdm`
## Install [↑](#install)
```python
pip install .
```
or
```python
python setup.py install
```
## Usages [↑](#usages)
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..
- 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` 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).
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.
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.
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."
The code offers three modes of operation:
- **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.
- **cond**: Use this mode for screening over reaction time and/or temperature.
- **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.
Once all input files are ready and `mikimo` is installed, several run options are available:
1. Call just microkinetic solver:
```python
python -m navicat_mikimo mkm -d [DIR]
```
2. Microkinetic modeling 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
```
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):
```python
python -m navicat_mikimo vp -d [DIR] -nd 1 -t T1 T2
```
5. To construct microkinetic activity/selectivity map:
```python
python -m navicat_mikimo vp -d [DIR] -nd 2
```
6. To screen over reaction time and temperature:
```python
python -m navicat_mikimo cond -d [DIR]
```
7. To smooth the volcano plots generated:
```python
python replot.py [i]
```
## Examples [↑](#examples)
1. Microkinetic modeling for Pd-catalyzed carbocyclization-borylation of enallene in the presence of chiral phosphoric acid (298.15 K, 1 min):
```python
python -m navicat_mikimo mkm -d test_cases/pd_carbocylic_borylation/ -t 298.15 -Tf 60
```
2. Microkinetic modeling for all profiles of the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):
```python
python -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 0
```
3. Constructing microkinetic volcano plot for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):
```python
python -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 1 -ncore 24
```
4. Constructing microkinetic activity and selectivity maps for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):
```python
python -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 2 -ncore 24
```
5. Constructing microkinetic activity and selectivity maps with a descriptor variable representing catalyst and temperature [273.15-423.15 K] for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (2h):
```python
python -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 273.15 423.15 -Tf 7200 -nd 1 -ncore 24
```
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:
```python
python -m navicat_mikimo cond -d test_cases/pincer_CO2_jacs/ -tt -Tf 7200 86400 -t 273.15 423.15 -ncore 24
```
7. Using filtering to smooth the plot:
```python
python -m navicat_mikimo replot examples/data/vp/data_a.h5 -p 3 3 3 -w 20 20 20
```
You can find examples demonstrating how to read h5 files and regenerate 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. 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.
## Limitations [↑](#limitations)
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 or compute an effective TS energy that corresponds to the sum of the two rate constants.
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": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "computational chemistry utility",
"author": "pregabalin_hoshiyomi",
"author_email": "pregabalin_Hoshiyomi <thanapat.worakul@epfl.ch>",
"download_url": "https://files.pythonhosted.org/packages/40/6f/b941d7ef65b92843ddc7e555487d27b2d2c178fb04fa1a3b252d5b456b55/navicat_mikimo-1.0.1.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 modeling? \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: diagrams that show the activity (or selectivity) of catalysts plotted against a descriptor variable that identifies a specific catalyst. Based on linear free energy scaling relationships. </li>\n <li>Microkinetic volcano plot: volcano plots in which the activity/selectivity is expressed as the final product concentration, or a 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* [Limitations](#limitations-)\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- `openpyxl`\n- `tqdm` \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 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..\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` 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).\n\nThe 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.\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 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.\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\nThe code offers three modes of operation:\n\n- **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. \n- **cond**: Use this mode for screening over reaction time and/or temperature.\n- **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.\n\nOnce all input files are ready and `mikimo` is installed, several run options are available:\n\n1. Call just microkinetic solver:\n```python\npython -m navicat_mikimo mkm -d [DIR]\n```\n2. Microkinetic modeling 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\n4. 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):\n```python\npython -m navicat_mikimo vp -d [DIR] -nd 1 -t T1 T2\n```\n\n5. To construct microkinetic activity/selectivity map:\n```python\npython -m navicat_mikimo vp -d [DIR] -nd 2\n```\n\n6. To screen over reaction time and temperature:\n```python\npython -m navicat_mikimo cond -d [DIR] \n```\n\n7. To smooth the volcano plots generated: \n```python\npython replot.py [i]\n```\n\n## Examples [\u2191](#examples)\n\n1. Microkinetic modeling for Pd-catalyzed carbocyclization-borylation of enallene in the presence of chiral phosphoric acid (298.15 K, 1 min): \n```python\npython -m navicat_mikimo mkm -d test_cases/pd_carbocylic_borylation/ -t 298.15 -Tf 60\n```\n\n2. Microkinetic modeling for all profiles of the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):\n```python\npython -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 0\n```\n\n3. Constructing microkinetic volcano plot for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):\n```python\npython -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 1 -ncore 24\n```\n\n4. Constructing microkinetic activity and selectivity maps for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (323.15 K, 2 h):\n```python\npython -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 323.15 -Tf 7200 -nd 2 -ncore 24\n```\n\n5. Constructing microkinetic activity and selectivity maps with a descriptor variable representing catalyst and temperature [273.15-423.15 K] for the catalytic hydrosilylation of carbon dioxide with metal pincer complexes (2h):\n```python\npython -m navicat_mikimo vp -d test_cases/pincer_CO2/ -t 273.15 423.15 -Tf 7200 -nd 1 -ncore 24\n```\n\n6. 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:\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\n7. Using filtering to smooth the plot:\n\n```python\npython -m navicat_mikimo replot examples/data/vp/data_a.h5 -p 3 3 3 -w 20 20 20\n```\n\nYou can find examples demonstrating how to read h5 files and regenerate 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. 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.\n\n## Limitations [\u2191](#limitations)\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 or compute an effective TS energy that corresponds to the sum of the two rate constants.\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": null,
"summary": "microkinetic modeling code for homogeneous catalytic reactions",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/lcmd-epfl/mikimo"
},
"split_keywords": [
"computational",
"chemistry",
"utility"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5f25762d0f388124e5bc09dd4f75d15ef0d12b0ddb7d13690f59162d3451198",
"md5": "7df48c52fbf4a09e315e5ec665201fcd",
"sha256": "f16bdd277cfd9317692ade9cdd72f087772bc46fe6083de4a2e49271740cceb3"
},
"downloads": -1,
"filename": "navicat_mikimo-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7df48c52fbf4a09e315e5ec665201fcd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 48026,
"upload_time": "2024-07-12T09:18:55",
"upload_time_iso_8601": "2024-07-12T09:18:55.974173Z",
"url": "https://files.pythonhosted.org/packages/c5/f2/5762d0f388124e5bc09dd4f75d15ef0d12b0ddb7d13690f59162d3451198/navicat_mikimo-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "406fb941d7ef65b92843ddc7e555487d27b2d2c178fb04fa1a3b252d5b456b55",
"md5": "23a2c9507943e5f31e3521320ba62e9a",
"sha256": "648322fc937a9e8c5413224a78f293842ee3220f0fa6e38bfa557129db0221b6"
},
"downloads": -1,
"filename": "navicat_mikimo-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "23a2c9507943e5f31e3521320ba62e9a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 46683,
"upload_time": "2024-07-12T09:18:57",
"upload_time_iso_8601": "2024-07-12T09:18:57.498970Z",
"url": "https://files.pythonhosted.org/packages/40/6f/b941d7ef65b92843ddc7e555487d27b2d2c178fb04fa1a3b252d5b456b55/navicat_mikimo-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-12 09:18:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lcmd-epfl",
"github_project": "mikimo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "navicat-mikimo"
}
JSON
