Metadata-Version: 2.4
Name: kmcpy
Version: 0.3.0
Summary: Kinetic Monte Carlo Simulation using Python (kMCpy)
Author-email: kMCpy Development Team <dengzeyu@gmail.com>
Maintainer-email: Zeyu Deng <dengzeyu@gmail.com>, Weihang Xie <david.xie1998@gmail.com>, Pieremanuele Canepa <pieremanuele.canepa@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/caneparesearch/kmcpy
Project-URL: Repository, https://github.com/caneparesearch/kmcpy
Project-URL: Issues, https://github.com/caneparesearch/kmcpy/issues
Project-URL: Documentation, https://kmcpy.readthedocs.io/
Keywords: kinetic monte carlo,kmc,simulation,materials science,condensed matter physics,chemistry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: glob2>=0.7
Requires-Dist: joblib>=1.5.3
Requires-Dist: monty>=2025.3.3
Requires-Dist: numba<0.63,>=0.62; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: numba>=0.63.1; sys_platform != "darwin" or platform_machine != "x86_64"
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: pymatgen>=2025.10.7
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: scipy>=1.13
Requires-Dist: scikit-learn>=1.8.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx>=7.0; extra == "doc"
Requires-Dist: furo; extra == "doc"
Requires-Dist: nbsphinx; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
Requires-Dist: myst-parser; extra == "doc"
Requires-Dist: tqdm; extra == "doc"
Requires-Dist: psutil; extra == "doc"
Provides-Extra: gui
Requires-Dist: gooey; extra == "gui"
Dynamic: license-file


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

[![GitHub release](https://img.shields.io/github/release/caneparesearch/kmcpy.svg)](https://GitHub.com/caneparesearch/kmcpy/releases/)
[![Documentation Status](https://readthedocs.org/projects/kmcpy/badge/?version=latest)](https://kmcpy.readthedocs.io/en/latest/?badge=latest)
[![CI Status](https://github.com/caneparesearch/kmcpy/actions/workflows/test-ubuntu.yml/badge.svg)](https://github.com/caneparesearch/kmcpy/actions/workflows/test-ubuntu.yml)
[![PyPI Version](https://img.shields.io/pypi/v/kmcpy?logo=pypi&logoColor=white&color=blue&label=PyPI)](https://pypi.org/project/kmcpy)
[![Requires Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
[![Paper](https://img.shields.io/badge/Comp.Mater.Sci.-2023.112394-blue?logo=elsevier&logoColor=white)](https://doi.org/10.1016/j.commatsci.2023.112394)

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](https://numba.pydata.org/), 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](https://github.com/caneparesearch/kmcpy/blob/master/CHANGELOG.md).

## Installation

### Install with `pip`

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

```shell
pip install kmcpy
```

Using a virtual environment is recommended:

```shell
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](https://docs.astral.sh/uv/), use
the same PyPI package:

```shell
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:

```shell
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`:

```shell
pip install .
```

For development with `pip`:

```shell
pip install -e ".[dev]"
```

For development with `uv`:

```shell
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](https://visualstudio.microsoft.com/visual-cpp-build-tools/) for `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
```

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

```shell
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:

```python
from kmcpy import Configuration, run

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

You can also attach custom property callbacks during a run:

```python
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:
```shell
kmcpy init --output input_template.yaml
```

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

3. Run the simulation:
```shell
run_kmc --input input_template.yaml
```

To print out all arguments, you can run:
```shell
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:
```python
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":
```python
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:
```python
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:
```yaml
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:

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