Quickstart

This page runs one small kMC simulation after kMCpy is installed. For installation options, see Install.

Run The Bundled Example From Source

uv run python example/minimal_example.py

The example loads:

  • a structure file,

  • an event file,

  • a model file,

  • an optional initial-state file,

  • runtime settings such as temperature, number of passes, and random seed.

It writes results under:

example/output/minimal/

Use this command when you have a source checkout, because the example data files live in the repository.

Run From Python

Use Configuration.from_file(...) when you already have a YAML or JSON input file:

from kmcpy import Configuration, run

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

tracker contains the final state and sampled transport/property records.

Run From The Command Line

Create a template input file:

uv run kmcpy init --output input_template.yaml

Edit the file paths and runtime fields, then run:

uv run run_kmc --input input_template.yaml

The generated template uses the modern Configuration format. Legacy InputSet style inputs are no longer supported.

What The Input Must Provide

A kMC run needs:

  • a structure containing all possible mobile-ion sites,

  • a site_mapping that says which sites are mutable and which species or vacancy states are allowed,

  • an event library,

  • a model file that can assign rates to those events,

  • initial occupations,

  • runtime settings such as temperature, attempt frequency, and number of passes.

The workflow tutorial explains how to prepare each part.

Inspect Configuration Fields

If you are unsure which fields belong in the input file, ask kMCpy:

uv run python -c "from kmcpy.simulator.config import Configuration; Configuration.help_fields()"

The output separates physical system inputs from runtime controls.

Common Problems

Unknown Field Error

If you see Unknown configuration fields: [...], the input file contains a misspelled or legacy field. Compare it against:

from kmcpy.simulator.config import Configuration

Configuration.help_fields()

Missing File Error

Relative file paths are resolved from the current working directory. Run from the repository root or use absolute paths when debugging.

No Results Written

Check that the run actually reached production steps and that the output directory is writable. Attached custom properties are written separately from built-in transport properties.