| Name | kmcpy JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Kinetic Monte Carlo Simulation using Python (kMCpy) |
| upload_time | 2025-07-10 18:13:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2021 Caneparesearch
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
kinetic monte carlo
kmc
simulation
materials science
condensed matter physics
chemistry
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/caneparesearch/kMCpy/master/docs/source/_static/kmcpy_logo_dark.svg">
<img alt="Logo" src="https://raw.githubusercontent.com/caneparesearch/kMCpy/master/docs/source/_static/kmcpy_logo.svg" height="120">
</picture>
</h1>
[](https://GitHub.com/caneparesearch/kmcpy/releases/)
[](https://kmcpy.readthedocs.io/en/latest/)
[](https://github.com/caneparesearch/kmcpy/actions/workflows/test-ubuntu.yml)
[](https://pypi.org/project/kmcpy)
[](https://python.org/downloads)
[](https://doi.org/10.1016/j.commatsci.2023.112394)
kMCpy is an open-source Python package for studying ion diffusion using the kinetic Monte Carlo (kMC) technique. It offers a comprehensive Python-based approach to compute kinetic properties, suitable for research, development, and prediction of new functional materials.
Key features include a local cluster expansion model toolkit, a rejection-free kinetic Monte Carlo (rf-kMC) solver, and tools to extract ion transport properties like diffusivities and conductivities. The local cluster expansion model toolkit facilitates model fitting from ab initio or empirical barrier calculations. Post-training, the local cluster expansion model can compute migration barriers in crystalline materials within the transition state theory.
Advantages of using kMCpy:
1. Written entirely in Python with a modular design, promoting developer-centricity and easy feature addition.
2. Cross-platform compatibility, supporting Windows, macOS, and Linux.
3. Performance-optimized kMC routines using [Numba](https://numba.pydata.org/), resulting in significant speed improvements.
This code was recently employed to investigate the transport properties of Na-ion in [NaSiCON solid electrolyte](https://www.nature.com/articles/s41467-022-32190-7). In this study, rf-kMC was used to model Na-ion conductivity in NaSiCON, leading to the discovery that maximum conductivity is achieved at Na = 3.4.
## Installation
### Method 1: Install using `pip`
You can quickly install the latest version of kMCpy through [PyPI](https://pypi.org/project/kmcpy/) to your environment.
```shell
pip install kmcpy
```
### Method 2: Install from source using `pip`
You can install from the source code using `pip`. Assuming you have cloned the repository, navigate to the root directory of the kMCpy repository and run:
```shell
pip install .
```
For development, you can clone the repository and install it in editable mode using
```shell
pip install -e ".[dev]"
```
This allows you to modify the source code and see changes immediately without reinstalling.
kMCpy also has a basic graphical user interface (GUI). It is based on`wxpython`. You might need to install [GTK](https://www.gtk.org/) for `wxpython`. You can install other additional dependencies for the GUI by running:
```shell
pip install -e ".[gui]"
```
### Method 3: Install from source using [UV](https://docs.astral.sh/uv/getting-started/installation/)
It is highly recommended to install kMCpy from source using [UV](https://docs.astral.sh/uv/getting-started/installation/) and use it with virtual environment.
```shell
uv sync
```
For development, you can install it in editable mode using:
```shell
uv sync --extra dev
uv pip install -e . # this makes the installation using the editable mode
```
For GUI, you can install the additional dependencies by running:
```shell
uv sync --extra gui
```
> **⚠️ Warning for Windows users:**
> You need to install [Microsoft C++ build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile `pymatgen`.
## Build documentation
You can access the documentation at [https://kmcpy.readthedocs.io/](https://kmcpy.readthedocs.io/). However, if you want to build the documentation locally, you can do so by following these steps:
```shell
uv sync --extra doc
python scripts/build_doc.py
```
## Run kMCpy
### API usage
You can run kMC through API. You can find more details in the `examples` directory. You can see the examples in the `examples` directory for how to use kMCpy in your own scripts. The examples cover various aspects of kMCpy, including how to build a model and use it for simulations.
### Command line usage
A wrapper is provided if you want to run kMCpy through command line only. There is a wrapper script `run_kmc` that allows you to run kMCpy from the command line. You can use it to run a kMCpy simulation with a JSON/YAML input file. The input file should contain the necessary parameters for the simulation. It should be noted that you need to have all the input files that needed to run kMC.
```shell
run_kmc input.json
```
To print out all arguments, you can run:
```shell
run_kmc --help
```
### GUI usage
You can start the GUI from command line. The basic usage is as follows:
```shell
start_kmcpy_gui
```
Then a window will pop up, allowing you to select the input file and run the simulation.
## Citation
If you use kMCpy in your research, please cite it as follows:
```bibtex
@article{deng2022fundamental,
title={Fundamental investigations on the sodium-ion transport properties of mixed polyanion solid-state battery electrolytes},
author={Deng, Zeyu and Mishra, Tara P and Mahayoni, Eunike and Ma, Qianli and Tieu, Aaron Jue Kang and Guillon, Olivier and Chotard, Jean-No{\"e}l and Seznec, Vincent and Cheetham, Anthony K and Masquelier, Christian and others},
journal={Nature communications},
volume={13},
number={1},
pages={1--14},
year={2022},
publisher={Nature Publishing Group}
}
@article{deng2023kmcpy,
title = {kMCpy: A python package to simulate transport properties in solids with kinetic Monte Carlo},
journal = {Computational Materials Science},
volume = {229},
pages = {112394},
year = {2023},
issn = {0927-0256},
doi = {https://doi.org/10.1016/j.commatsci.2023.112394},
author = {Zeyu Deng and Tara P. Mishra and Weihang Xie and Daanyal Ahmed Saeed and Gopalakrishnan Sai Gautam and Pieremanuele Canepa},
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "kmcpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Zeyu Deng <dengzeyu@gmail.com>, Weihang Xie <david.xie1998@gmail.com>, Pieremanuele Canepa <pieremanuele.canepa@gmail.com>",
"keywords": "kinetic monte carlo, kmc, simulation, materials science, condensed matter physics, chemistry",
"author": null,
"author_email": "kMCpy Development Team <dengzeyu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/15/40/6af14783a1a1ada815def27f8f49dd1854535f1a08776c194192d4d8888d/kmcpy-0.2.1.tar.gz",
"platform": null,
"description": "\n<h1 align=\"center\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/caneparesearch/kMCpy/master/docs/source/_static/kmcpy_logo_dark.svg\">\n <img alt=\"Logo\" src=\"https://raw.githubusercontent.com/caneparesearch/kMCpy/master/docs/source/_static/kmcpy_logo.svg\" height=\"120\">\n </picture>\n</h1>\n\n[](https://GitHub.com/caneparesearch/kmcpy/releases/)\n[](https://kmcpy.readthedocs.io/en/latest/)\n[](https://github.com/caneparesearch/kmcpy/actions/workflows/test-ubuntu.yml)\n[](https://pypi.org/project/kmcpy)\n[](https://python.org/downloads)\n[](https://doi.org/10.1016/j.commatsci.2023.112394)\n\nkMCpy is an open-source Python package for studying ion diffusion using the kinetic Monte Carlo (kMC) technique. It offers a comprehensive Python-based approach to compute kinetic properties, suitable for research, development, and prediction of new functional materials.\n\nKey features include a local cluster expansion model toolkit, a rejection-free kinetic Monte Carlo (rf-kMC) solver, and tools to extract ion transport properties like diffusivities and conductivities. The local cluster expansion model toolkit facilitates model fitting from ab initio or empirical barrier calculations. Post-training, the local cluster expansion model can compute migration barriers in crystalline materials within the transition state theory.\n\nAdvantages of using kMCpy:\n\n1. Written entirely in Python with a modular design, promoting developer-centricity and easy feature addition.\n2. Cross-platform compatibility, supporting Windows, macOS, and Linux.\n3. Performance-optimized kMC routines using [Numba](https://numba.pydata.org/), resulting in significant speed improvements.\n\nThis code was recently employed to investigate the transport properties of Na-ion in [NaSiCON solid electrolyte](https://www.nature.com/articles/s41467-022-32190-7). In this study, rf-kMC was used to model Na-ion conductivity in NaSiCON, leading to the discovery that maximum conductivity is achieved at Na = 3.4.\n\n## Installation\n\n### Method 1: Install using `pip`\nYou can quickly install the latest version of kMCpy through [PyPI](https://pypi.org/project/kmcpy/) to your environment.\n\n```shell\npip install kmcpy\n```\n\n### Method 2: Install from source using `pip`\n\nYou can install from the source code using `pip`. Assuming you have cloned the repository, navigate to the root directory of the kMCpy repository and run:\n```shell\npip install .\n```\nFor development, you can clone the repository and install it in editable mode using \n\n```shell\npip install -e \".[dev]\"\n```\nThis allows you to modify the source code and see changes immediately without reinstalling.\n\nkMCpy also has a basic graphical user interface (GUI). It is based on`wxpython`. You might need to install [GTK](https://www.gtk.org/) for `wxpython`. You can install other additional dependencies for the GUI by running:\n```shell\npip install -e \".[gui]\"\n```\n\n### Method 3: Install from source using [UV](https://docs.astral.sh/uv/getting-started/installation/)\nIt is highly recommended to install kMCpy from source using [UV](https://docs.astral.sh/uv/getting-started/installation/) and use it with virtual environment.\n```shell\nuv sync\n```\nFor development, you can install it in editable mode using:\n```shell\nuv sync --extra dev\nuv pip install -e . # this makes the installation using the editable mode\n```\nFor GUI, you can install the additional dependencies by running:\n```shell\nuv sync --extra gui\n```\n\n> **\u26a0\ufe0f Warning for Windows users:** \n> You need to install [Microsoft C++ build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) to compile `pymatgen`.\n\n\n## Build documentation\nYou can access the documentation at [https://kmcpy.readthedocs.io/](https://kmcpy.readthedocs.io/). However, if you want to build the documentation locally, you can do so by following these steps:\n```shell\nuv sync --extra doc\npython scripts/build_doc.py\n```\n\n## Run kMCpy\n### API usage\nYou can run kMC through API. You can find more details in the `examples` directory. You can see the examples in the `examples` directory for how to use kMCpy in your own scripts. The examples cover various aspects of kMCpy, including how to build a model and use it for simulations.\n\n### Command line usage\nA wrapper is provided if you want to run kMCpy through command line only. There is a wrapper script `run_kmc` that allows you to run kMCpy from the command line. You can use it to run a kMCpy simulation with a JSON/YAML input file. The input file should contain the necessary parameters for the simulation. It should be noted that you need to have all the input files that needed to run kMC.\n```shell\nrun_kmc input.json\n```\n\nTo print out all arguments, you can run:\n```shell\nrun_kmc --help\n```\n\n### GUI usage\nYou can start the GUI from command line. The basic usage is as follows:\n```shell\nstart_kmcpy_gui\n```\nThen a window will pop up, allowing you to select the input file and run the simulation.\n\n## Citation\nIf you use kMCpy in your research, please cite it as follows:\n\n```bibtex\n@article{deng2022fundamental,\n title={Fundamental investigations on the sodium-ion transport properties of mixed polyanion solid-state battery electrolytes},\n author={Deng, Zeyu and Mishra, Tara P and Mahayoni, Eunike and Ma, Qianli and Tieu, Aaron Jue Kang and Guillon, Olivier and Chotard, Jean-No{\\\"e}l and Seznec, Vincent and Cheetham, Anthony K and Masquelier, Christian and others},\n journal={Nature communications},\n volume={13},\n number={1},\n pages={1--14},\n year={2022},\n publisher={Nature Publishing Group}\n }\n@article{deng2023kmcpy,\n title = {kMCpy: A python package to simulate transport properties in solids with kinetic Monte Carlo},\n journal = {Computational Materials Science},\n volume = {229},\n pages = {112394},\n year = {2023},\n issn = {0927-0256},\n doi = {https://doi.org/10.1016/j.commatsci.2023.112394},\n author = {Zeyu Deng and Tara P. Mishra and Weihang Xie and Daanyal Ahmed Saeed and Gopalakrishnan Sai Gautam and Pieremanuele Canepa},\n }\n```\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2021 Caneparesearch\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Kinetic Monte Carlo Simulation using Python (kMCpy)",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://kmcpy.readthedocs.io/",
"Homepage": "https://github.com/caneparesearch/kmcpy",
"Issues": "https://github.com/caneparesearch/kmcpy/issues",
"Repository": "https://github.com/caneparesearch/kmcpy"
},
"split_keywords": [
"kinetic monte carlo",
" kmc",
" simulation",
" materials science",
" condensed matter physics",
" chemistry"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a491d66445bb5e0eb72ec1e95ee53a81c25400221fa842c8f6e31e9c3dc3de4",
"md5": "f7612c14eb07af3580c0465a77cded91",
"sha256": "05c7115b920aaf96eb7c5ad3b5e49a9497e5ead6e5d7ead4394796afe7d1c82a"
},
"downloads": -1,
"filename": "kmcpy-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f7612c14eb07af3580c0465a77cded91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 82499,
"upload_time": "2025-07-10T18:13:28",
"upload_time_iso_8601": "2025-07-10T18:13:28.028961Z",
"url": "https://files.pythonhosted.org/packages/5a/49/1d66445bb5e0eb72ec1e95ee53a81c25400221fa842c8f6e31e9c3dc3de4/kmcpy-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15406af14783a1a1ada815def27f8f49dd1854535f1a08776c194192d4d8888d",
"md5": "e39c1e4e78a3cb55d5964d1e7f453cab",
"sha256": "88bf81ef144a81f18ddb026f41e4e87d480f378508a5f344b66f7e2ebba638c3"
},
"downloads": -1,
"filename": "kmcpy-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e39c1e4e78a3cb55d5964d1e7f453cab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 91364,
"upload_time": "2025-07-10T18:13:29",
"upload_time_iso_8601": "2025-07-10T18:13:29.315417Z",
"url": "https://files.pythonhosted.org/packages/15/40/6af14783a1a1ada815def27f8f49dd1854535f1a08776c194192d4d8888d/kmcpy-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 18:13:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caneparesearch",
"github_project": "kmcpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kmcpy"
}
