kmos

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.

Features

• 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

Installation

pip install kmos

Quickstart

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

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

Development

Quick Start for Contributors

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

Available Make Commands

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

Code Quality Tools

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

Running Tests

# Quick test run
make test

# Verbose output
make test-verbose

# With coverage report
make test-coverage

Manual Commands (if not using Make)

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

Requirements

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

Publishing

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 kmos

Documentation

For tutorials, user guides, API reference, and troubleshooting:

• GitHub Pages
• ReadTheDocs
• TU Munich Documentation
• Introduction to kMOS

Bugs, Issues, Questions

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

Acknowledgments

This project builds upon several excellent open-source Python projects:

• Python
• ASE (Atomic Simulation Environment)
• NumPy
• f2py
• lxml

License

GPL-3.0-or-later