kmcpy 0.2.5

Kinetic Monte Carlo Simulation using Python (kMCpy)

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]"

Using UV (recommended)

To install all dependencies:

uv sync

For development (editable mode):

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_parameters()"
uv run python example/minimal_example.py

Configuration routes arguments into two groups:

1. system parameters define what you simulate (structure, events, model files).
2. runtime parameters define how you simulate (temperature, passes, random seed).

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

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(config)

# 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 tabulated model files (sparse data)

For sparse datasets, you can use TabulatedModel with direct event+occupation lookup.

Build a model bundle via API:

from kmcpy.io.config_io import ConfigIO

bundle = ConfigIO.build_tabulated_model_bundle_from_file(
    entries_file="tabulated_entries.json"
)
ConfigIO.save_model_bundle(bundle, "model.json")

Build via CLI:

kmcpy pack-tabulated-model --entries-file tabulated_entries.json --output model.json

Use it in simulation config:

model_type: "tabulated"
model_file: "model.json"

TabulatedModel performs exact lookup only. Unseen configurations raise an error (no extrapolation fallback).

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