Metadata-Version: 2.4
Name: kmcpy
Version: 0.2.5
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: MIT License
        
        Copyright (c) 2021 Caneparesearch and DENG Group
        
        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.
        
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: License :: OSI Approved :: MIT License
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: 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: pymatgen>=2025.10.7
Requires-Dist: pyyaml>=6.0.3
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.
>
> 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](https://pypi.org/project/kmcpy/) to your environment.

```shell
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](https://docs.astral.sh/uv/getting-started/installation/) or [venv](https://docs.python.org/3/library/venv.html) or [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) to create a virtual environment.
> For example, using `venv`:
> ```shell
> 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](https://docs.astral.sh/uv/getting-started/installation/). First, clone the repository and navigate to its root directory.

#### Using pip

To install normally:
```shell
pip install .
```

For development (editable mode):
```shell
pip install -e ".[dev]"
```

#### Using UV (recommended)

To install all dependencies:
```shell
uv sync
```

For development (editable mode):
```shell
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_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:

```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(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:
```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 tabulated model files (sparse data)
For sparse datasets, you can use `TabulatedModel` with direct event+occupation lookup.

Build a model bundle via API:
```python
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:
```shell
kmcpy pack-tabulated-model --entries-file tabulated_entries.json --output model.json
```

Use it in simulation config:
```yaml
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:

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