kMC modeling on steroids
A vigorous attempt to make lattice kinetic Monte Carlo modeling more accessible.
kmos is a tool for kinetic Monte Carlo (kMC) modeling focused on lattice models for surface science applications.
Copyright (C) 2009-2025 Max J. Hoffmann mjhoffmann@gmail.com
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
- Lattice-based kinetic Monte Carlo simulations
- Support for complex surface chemistry models
- Written in Python with Fortran backend for performance
- Integration with ASE (Atomic Simulation Environment)
- Interactive GUI for model editing and visualization
- High-performance kMC solver with multiple backends
pip install kmosCreate a minimal input file mini_101.ini:
[Meta]
author = Your Name
email = you@server.com
model_dimension = 2
model_name = fcc_100
[Species empty]
color = #FFFFFF
[Species CO]
representation = Atoms("CO", [[0, 0, 0], [0, 0, 1.17]])
color = #FF0000
[Lattice]
cell_size = 3.5 3.5 10.0
[Layer simple_cubic]
site hollow = (0.5, 0.5, 0.5)
color = #FFFFFF
[Parameter k_CO_ads]
value = 100
adjustable = True
min = 1
max = 1e13
scale = log
[Parameter k_CO_des]
value = 100
adjustable = True
min = 1
max = 1e13
scale = log
[Process CO_ads]
rate_constant = k_CO_ads
conditions = empty@hollow
actions = CO@hollow
tof_count = {'adsorption':1}
[Process CO_des]
rate_constant = k_CO_des
conditions = CO@hollow
actions = empty@hollow
tof_count = {'desorption':1}Then run:
kmos export mini_101.ini
cd mini_101_local_smart
kmos benchmarkYou should see output like:
Using the [local_smart] backend.
1000000 steps took 1.51 seconds
Or 6.62e+05 steps/s
Try running kmos view to watch the model run, or kmos shell to interact with it interactively. Explore more commands with kmos help.
# Clone the repository
git clone https://github.com/mhoffman/kmos.git
cd kmos
# Install dev dependencies
uv sync --all-extras
# Install pre-commit hooks (automatic code formatting & linting)
uv run pre-commit install
# Run tests
make testThe project includes a Makefile for common development tasks:
make help # Show all available commands
make test # Run tests
make test-coverage # Run tests with coverage report
make lint # Lint code with ruff
make format # Format code with ruff
make clean # Clean build artifacts and caches
make docs # Build documentation
make all # Run full CI pipeline locallyThis project uses modern Python tooling:
- ruff - Fast linting and formatting (replaces black, isort, flake8)
- mypy - Type checking
- pre-commit - Automatic checks before commits
- pytest - Testing framework
- coverage - Test coverage reporting
After installing pre-commit hooks with uv run pre-commit install, your code will automatically be formatted and linted before each commit.
# Quick test run
make test
# Verbose output
make test-verbose
# With coverage report
make test-coverage# Run tests
PYTHONPATH=. uv run pytest tests/
# Lint code
uv run ruff check kmos/ tests/
# Format code
uv run ruff format kmos/ tests/
# Type check
uv run mypy kmos/- Python >= 3.9
- Tested on Python 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14
- Fortran compiler (gfortran recommended)
- Meson build system (automatically installed with Python >= 3.12)
To publish a new version to PyPI:
# 1. Bump version
uv run bump-my-version bump patch # or minor, or major
# 2. Build the package
uv build
# 3. Upload to PyPI (requires PyPI credentials)
uv publish
# Or upload to Test PyPI first
uv publish --publish-url https://test.pypi.org/legacy/After publishing, users can install with:
pip install kmos
# or
uv add kmosFor tutorials, user guides, API reference, and troubleshooting:
This is research software for scientists by scientists. If you encounter bugs, have feature requests, or need help:
- Open an issue
- Join the mailing list
This project builds upon several excellent open-source Python projects:
GPL-3.0-or-later