Kinetic Monte Carlo Simulation with Python (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, resulting in significant speed improvements.

[!warning] kMCpy is under active development kMCpy is still under active development. While we strive to maintain backward compatibility, some changes may occur that could affect existing workflows. We recommend users to check the release notes and documentation for any updates or changes that might impact their usage.

Installation

Method 1: Install using pip (recommended)

You can quickly install the latest version of kMCpy through PyPI to your environment.

pip install kmcpy

[!note] Virtual Environment It is highly recommended to install kMCpy in a virtual environment to avoid dependency conflicts with other packages. You can use uv or venv or conda to create a virtual environment. For example, using venv:

python -m venv kmcpy-env
source kmcpy-env/bin/activate  # On Windows use `kmcpy-env\Scripts\activate.bat`

Then you can install kMCpy in the virtual environment using pip install kmcpy. To deactivate the virtual environment, you can use the command deactivate. For conda, you should also use pip install kmcpy to install kMCpy after activating the conda environment. For uv, you can use uv pip install kmcpy to install kMCpy after creating and activating the virtual environment.

Method 2: Install from source

You can install kMCpy from source using either pip or UV. First, clone the repository and navigate to its root directory.

Using pip

To install normally:

pip install .

For development (editable mode):

pip install -e ".[dev]"

To install GUI dependencies:

pip install -e ".[gui]"

Using UV (recommended)

To install all dependencies:

uv sync

For development (editable mode):

uv sync --extra dev
uv pip install -e .

To install GUI dependencies:

uv sync --extra gui

[!note] GUI kMCpy provides a graphical user interface (GUI) to facilitate the setup and execution of kMC simulations. However, the current GUI is deprecated. Users are encouraged to use the command line interface (CLI) or API for running simulations. The GUI is based on wxpython. You may need to install GTK for wxpython to work properly.

[!warning] Windows users Windows users (not applicable to WSL) need to install Microsoft C++ build tools for pymatgen.

Build documentation

You can access the documentation at https://kmcpy.readthedocs.io/. However, if you want to build the documentation locally, you can do so by following these steps:

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.

run_kmc input.json

To print out all arguments, you can run:

run_kmc --help

GUI usage

You can start the GUI from command line. The basic usage is as follows:

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:

@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 Gautam, Gopalakrishnan Sai and Canepa, Pieremanuele},
          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},
          }