From 2d08ee6d3c1a71a9aeb72b820ca326bd8a211031 Mon Sep 17 00:00:00 2001 From: Max Hoffmann Date: Sat, 27 Dec 2025 16:52:08 -0300 Subject: [PATCH 1/2] Update README --- README.md | 70 ++++++++++++++++++++ README.rst | 189 ----------------------------------------------------- 2 files changed, 70 insertions(+), 189 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 00000000..69fd4163 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +# kmos + +[![CI](https://github.com/mhoffman/kmos/actions/workflows/ci.yml/badge.svg)](https://github.com/mhoffman/kmos/actions/workflows/ci.yml) + +**kMC modeling on steroids** + +kmos is a tool for kinetic Monte Carlo (kMC) modeling focused on lattice models for surface science applications. + +## 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) + +## Installation + +```bash +pip install kmos +``` + +## Development + +```bash +# Clone the repository +git clone https://github.com/mhoffman/kmos.git +cd kmos + +# Install dependencies with uv +uv sync + +# Run tests +PYTHONPATH=. uv run pytest tests/ +``` + +## 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: + +```bash +# 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: +```bash +pip install kmos +# or +uv add kmos +``` + +## License + +GPL-3.0-or-later \ No newline at end of file diff --git a/README.rst b/README.rst deleted file mode 100644 index c6e6e599..00000000 --- a/README.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. image:: https://travis-ci.org/mhoffman/kmos.png?branch=master - :target: https://travis-ci.org/mhoffman/kmos -.. image:: https://img.shields.io/badge/license-GPLv3-brightgreen.svg?style=flat-square) - :target COPYING -.. image:: https://readthedocs.org/projects/kmos/badge/?version=latest - :target: http://kmos.readthedocs.org/en/latest/?badge=latest - :alt: Documentation Status -.. image:: https://badges.gitter.im/mhoffman/kmos.svg - :alt: Join the chat at https://gitter.im/mhoffman/kmos - :target: https://gitter.im/mhoffman/kmos?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge - -kmos: kMC modelling on steroids -===================================== -*a vigorous attempt to make lattice kinetic Monte Carlo modelling more accessible.* - -Copyright (C) 2009-13 Max J. Hoffmann - -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. - -This program is distributed in the hope that it will be useful, but WITHOUT -ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS -FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this program; if not, see `http://www.gnu.org/licenses/ `_. - -QUICKSTART -########## - -Prepare a minimal input file with the following content and save it as ``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} - -In the same directory run ``kmos export mini_101.ini``. You should now have a folder ``mini_101_local_smart`` -in the same directory. ``cd`` into it and run ``kmos benchmark``. If everything went well you should see something -like :: - - Using the [local_smart] backend. - 1000000 steps took 1.51 seconds - Or 6.62e+05 steps/s - -In the same directory try running ``kmos view`` to watch the model run or fire up ``kmos shell`` -to interact with the model interactively. Explore more commands with ``kmos help`` and please -refer to the documentation how to build complex model and evaluate them systematically. To test all bells and whistles try ``kmos edit mini_101.ini`` and inspect the model visually. - -DOCUMENTATION -############## - -Please refer to - -* https://www.th4.ch.tum.de/index.php?id=1321 -* http://mhoffman.github.io/kmos/ -* http://kmos.readthedocs.org/ -* https://github.com/jmlorenzi/intro2kmos - -or links therein for tutorials, user guide, reference, and troubleshooting hints. - -BUGS, ISSUES, TROUBLE -##################### - -This code is research code for scientists by scientists. If you -believe you have hit a bug, have a feature request get in touch -with us either via the `mailing list `_, `Gitter `_, or open an `issue `_ . - -THANKS -###### - -This project draws on several other great Python modules, which are in turn -each free software and I would like to thank each of these projects for -making their code freely avalaible, namely: - -* `Python `_ -* `ASE `_ -* Numpy -* `f2py `_ -* `kiwi `_, gazpacho -* lxml and in particular `ElementTree `_ - -FILES -##### -| ├── COPYING # Copy of GPLv3 -| ├── INSTALL.rst # installation instructions -| ├── README.rst # This document -| ├── TODO.rst # Ideas for improvement and new features -| ├── requirements.txt # Dependencies which can be installed via pip -| ├── setup.py # setuptools using setup script -| ├── index.html # landing website -| ├── kmos/ # the core kmos python modules -| │   ├── cli.py # the command line interface -| │   ├── config.py # configuration of some project wide paths -| │   ├── fortran_src/ # static Fortran 90 source files -| │   │   ├── assert.ppc # assertion macro -| │   │   ├── base.f90 # the default kMC solver -| │   │   ├── base_lat_int.f90 # slightly modified kMC solver for lat_int backend -| │   │   ├── kind_values.f90 # definition of project wide kind values -| │   │   └── main.f90 # source template for standalone Fortran 90 clients -| │   ├── gui/ # kmos.gui module -| │   │   ├── forms.py # view definitions (MVC) of editor GUI -| │   │   └── __init__.py # controller definitions (MVC) of editor GUI -| │   ├── __init__.py # root import module -| │   ├── io.py # conversion between format: contains main Code Generator -| │   ├── kmc_editor.glade # Glade XML definiton for form interfaces -| │   ├── kmc_project_v0.1.dtd # Document Type Definition file of kMC project v0.1 -| │   ├── kmc_project_v0.2.dtd # Document Type Definition file of kMC project v0.2 -| │   ├── run.py # High-level API for compiled models -| │   ├── species.py # Convenient interface for some reaction intermediates -| │   ├── types.py # The basic classes for building kMC models -| │   ├── units.py # Definition of conversion factor (CODATA 2010) -| │   ├── utils/ # Utility function that didn't fit elsewhere -| │   │   ├── __init__.py -| │   │   ├── ordered_dict.py -| │   │   ├── progressbar.py -| │   │   └── terminal.py -| │   └── view.py # The runtime GUI for compiled models -| ├── doc/ # user guide, documentation, and reference -| │   └── source/ # documentation source file for compilation with Sphinx -| ├── examples/ # demoing non-standard features and useful idioms -| │   ├── AB_model.py # small demo file -| │   ├── benchmark_compilers_and_backends.sh # demo file -| │   ├── crowded.xml # demo file -| │   ├── dreiD.xml # demo file for 3d model -| │   ├── dummy.xml # mininal model -| │   ├── model_Pt111_surface.py # demo file for non-rectangular lattice -| │   ├── multidentate.py # basic example for multidentate adsorption -| │   ├── render_bigcell.py # demo containing many sites -| │   ├── render_co_oxidation_ruo2.py # demoing th CO Oxidation at RuO2(110) model -| │   ├── render_diffusion_model.py # idioms for describing lateral interaction -| │   ├── render_einsD.py # simple 1-dimensional model -| │   ├── render_multispecies.py # render many species -| │   ├── render_pairwise_interaction.py # idioms for describing lateral interaction -| │   ├── render_Pt_111.py # another non-rectangular lattice -| │   ├── render_sand_model.py # a neat diffusion model for non-trivial boundary conditions -| │   ├── run_in_multi_process.py # an example for parallelization over processes -| │   ├── run.py # a high-level run script using the ModelRunner metaclass -| │   ├── ruptured_Pd.xml # a fcc(100) like surface with some sites missing -| │   └── small.xml # demo file -| ├── tests/ # Unit tests and test data -| └── tools # Entry points for command line interface -| ├── kmos -| ├── kmos.bat -| ├── kmos-build-standalone -| └── kmos-install-dependencies-ubuntu From 2f0a2336f72e3ac2a913121ab0f4076ca3f188d6 Mon Sep 17 00:00:00 2001 From: Max Hoffmann Date: Sat, 27 Dec 2025 17:22:45 -0300 Subject: [PATCH 2/2] Merged README.rst into README.md --- MANIFEST.in | 2 - README.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++- pyproject.toml | 3 +- 3 files changed, 107 insertions(+), 5 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index 83082789..2d4e5321 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,6 +2,4 @@ include kmos/*.dtd include kmos/fortran_src/*f90 include kmos/kmc_editor.glade include kmos/fortran_src/assert.ppc -include README.rst -include INSTALL.rst include COPYING diff --git a/README.md b/README.md index 69fd4163..3fd96e24 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,25 @@ **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 + +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 @@ -19,6 +30,74 @@ kmos is a tool for kinetic Monte Carlo (kMC) modeling focused on lattice models pip install kmos ``` +## Quickstart + +Create a minimal input file `mini_101.ini`: + +```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: +```bash +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 ```bash @@ -30,7 +109,7 @@ cd kmos uv sync # Run tests -PYTHONPATH=. uv run pytest tests/ +uv run pytest tests/ ``` ## Requirements @@ -65,6 +144,32 @@ pip install kmos uv add kmos ``` +## Documentation + +For tutorials, user guides, API reference, and troubleshooting: + +- [GitHub Pages](http://mhoffman.github.io/kmos/) +- [ReadTheDocs](http://kmos.readthedocs.org/) +- [TU Munich Documentation](https://www.th4.ch.tum.de/index.php?id=1321) +- [Introduction to kMOS](https://github.com/jmlorenzi/intro2kmos) + +## Bugs, Issues, Questions + +This is research software for scientists by scientists. If you encounter bugs, have feature requests, or need help: + +- Open an [issue](https://github.com/mhoffman/kmos/issues/new) +- Join the [mailing list](https://groups.google.com/forum/#!forum/kmos-users) + +## Acknowledgments + +This project builds upon several excellent open-source Python projects: + +- [Python](http://www.python.org) +- [ASE (Atomic Simulation Environment)](https://wiki.fysik.dtu.dk/ase/) +- [NumPy](https://numpy.org/) +- [f2py](http://cens.ioc.ee/projects/f2py2e/) +- [lxml](https://lxml.de/) + ## License GPL-3.0-or-later \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 021ca146..664882dd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ version = "0.4.2" # Managed by bump-my-version description = "kMC modeling on steroids" readme = "README.md" requires-python = ">=3.9" -license = {text = "GPL-3.0-or-later"} +license = "GPL-3.0-or-later" authors = [ {name = "Max J. Hoffmann", email = "mjhoffmann@gmail.com"} ] @@ -21,7 +21,6 @@ classifiers = [ "Environment :: Console", "Intended Audience :: Science/Research", "Intended Audience :: Developers", - "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)", "Natural Language :: English", "Operating System :: POSIX :: Linux", "Operating System :: Microsoft :: Windows",