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.

APIs and serialized file formats may change before a stable release. Check the release notes and current documentation when updating existing workflows.

Release notes are maintained in the changelog.

Installation

Install with pip

You can install the latest PyPI release directly into a Python environment:

pip install kmcpy

Using a virtual environment is recommended:

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

Install with uv pip

If you manage Python environments with uv, use the same PyPI package:

uv venv kmcpy-env
source kmcpy-env/bin/activate
uv pip install kmcpy

Install with Conda

Use Conda to create the Python environment, then install the PyPI package inside that environment:

conda create -n kmcpy python=3.11 pip
conda activate kmcpy
python -m pip install kmcpy

Install from source

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

To install normally with pip:

pip install .

For development with pip:

pip install -e ".[dev]"

For development with uv:

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

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

Quickstart

Run a minimal end-to-end simulation with bundled example files:

uv sync
uv run python -c "from kmcpy.simulator.config import Configuration; Configuration.help_fields()"
uv run python example/minimal_example.py

Configuration routes arguments into two groups:

1. system fields define what you simulate after loader inputs have been read.
2. runtime fields define how you simulate (temperature, passes, random seed).

If you pass an unknown keyword, kMCpy raises a clear error and points to Configuration.help_fields().

Unit conventions are explicit in code via kmcpy.units, Configuration.field_units(), and tracker.result_units. Common units are: barriers in meV, rates/probabilities in Hz, time in s, distance in Angstrom, diffusivity in cm^2/s, and conductivity in mS/cm.

Run kMCpy

API usage

You can run kMC through API. See the example directory for scripts and notebook workflows covering setup, event generation, and simulations.

For a one-call simulation:

from kmcpy import Configuration, run

config = Configuration.from_file("input.yaml")
tracker = run(config)

You can also attach custom property callbacks during a run:

from kmcpy.simulator.kmc import KMC

kmc = KMC.from_config(config)

def custom_property(state, step, sim_time):
    occupied = sum(1 for occ in state.occupations if occ < 0)
    return occupied / len(state.occupations)

kmc.attach(custom_property, interval=100, name="occupied_fraction")
kmc.set_property_enabled("conductivity", False)  # Optional: disable selected built-in fields
tracker = kmc.run()

# Stored custom callback records
records = tracker.get_property_records("occupied_fraction")

Command line usage

A wrapper is provided if you want to run kMCpy from the command line.

1. Generate a commented template input file:

kmcpy init --output input_template.yaml

2. Edit the required file paths and simulation settings in input_template.yaml.

3. Run the simulation:

run_kmc --input input_template.yaml

To print out all arguments, you can run:

run_kmc --help

Build local barrier models

For direct barrier logic, use LocalBarrierModel. It supports constant barriers, count rules, species-count rules, wildcard patterns, and exact catalog-style matches. Barrier values are in meV.

Constant barrier:

from kmcpy.models import LocalBarrierModel

model = LocalBarrierModel.constant_barrier(300.0)
model.to("model.json")

Species-count rule, for example "more than 3 Si in the local environment":

model = LocalBarrierModel(
    default_barrier=300.0,
    site_species={
        1: {-1: "P", 1: "Si"},
        2: {-1: "Si", 1: "P"},
        3: {-1: "Si", 1: "P"},
        4: {-1: "Al", 1: "Si"},
    },
)
model.add_species_count_rule(
    name="si_rich",
    sites="local_env",
    species="Si",
    min_count=4,
    barrier=420.0,
)
model.to("model.json")

Exact catalog-style match:

model = LocalBarrierModel.from_exact_entries([
    {
        "mobile_ion_indices": [0, 1],
        "local_env_indices": [1, 2, 3],
        "occupations": [1, -1, 1, -1],
        "properties": {"barrier": 250.0},
    }
])

Use the generated model file in simulation config by pointing to it:

model_file: "model.json"

Exact catalog-style data should be represented as LocalBarrierModel exact rules rather than a separate catalog model.

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},
          }