Mat Kinetic Monte Carlo

Kinetic Monte Carlo (KMC)

Goal

Run kinetic Monte Carlo simulations to evolve a system on experimental (long) timescales using a continuous-time Markov jump process defined by elementary events and their rates.

This skill focuses on best-practice, physics-grounded KMC:

• correct rejection-free time advancement (no time-step error),
• good event/rate bookkeeping,
• detailed balance / microreversibility checks when appropriate,
• practical handling of "flickers" / superbasins,
• and robust postprocessing (event stats, MSD -> diffusivity, Arrhenius).

This skill is designed to compose with:

• chem-neb-barrier — compute migration barriers via NEB with MLIPs.
• mat-phonon — compute vibrational frequencies for hTST prefactors (Vineyard formula).
• mat-diffusion-analysis — MSD fitting, Arrhenius analysis, and D → σ via Nernst-Einstein.

MCP Server Integration

Barrier computations and phonon calculations require MLIP models (MACE, MatGL, FairChem). These run through the corresponding MCP servers or directly via wrapper scripts:

• MACE: src/mcp_server/mace_server.py — provides relax_structure, predict_structure tools. Used by neb-barrier and phonon scripts via src/utils/mlips/mace/mace_wrapper.py.
• MatGL: src/mcp_server/matgl_server.py — same interface, CHGNet/M3GNet/TensorNet models.
• FairChem: src/mcp_server/fairchem_server.py — UMA/ESEN models.

KMC scripts themselves do not call MLIPs — they consume barrier/prefactor values computed upstream by the NEB and phonon skills.

When to Use KMC (and When Not)

Use KMC when:

• Dynamics are rare-event dominated (activated hops/reactions separated by long waiting times).
• You can define a set of states + elementary transitions between states with rate constants.
• You need time/length scales unreachable by MD.

Do NOT use KMC when:

• Motion is not rare-event-like (barriers ~ few kBT or less) and recrossings dominate.
• You cannot define a reasonably complete event set (or the event set changes too rapidly without on-the-fly discovery).
• The system is strongly non-Markovian at the state resolution you chose.

Background

Core Theory

KMC simulates a Poisson process over discrete events with rates {k_m}.

At a given state:

1. Compute total rate: R = sum_m k_m
2. Choose the next event m with probability k_m / R
3. Advance time by: dt = -ln(u) / R where u ~ Uniform(0,1)

This is equivalent to the Gillespie direct method / residence-time algorithm and the classic rejection-free "n-fold way" formulation.

Key property: No time-step bias; time is advanced by the correct exponential waiting-time distribution.

Model-Building Choices

A) Lattice KMC (recommended if you can map to a lattice)

Best for:

• diffusion on a known sublattice (vacancy-mediated, intercalation on a site network),
• surface catalysis on discrete adsorption sites,
• ordering kinetics with local events.

Requires:

• a site network (graph: sites + neighbor relations),
• local occupancy/state variables,
• an event catalog (local patterns -> transitions).

B) Off-lattice / On-the-fly KMC (use for complex/disordered systems)

Best for:

• amorphous materials,
• heavily strained crystals,
• defect clusters, complex mechanisms,
• when you cannot predefine the event table.

Typical approaches:

• AKMC (saddle searches near current minimum + hTST rates),
• k-ART (topology-based self-learning off-lattice KMC),
• SLKMC (self-learning event discovery; often surfaces).

This skill provides guidance + validation criteria, but the included scripts implement lattice KMC (event table provided).

Instructions

0. Define the Scientific Question and Minimal State Representation

Examples:

• Ion diffusion: state = occupancy of diffusion sites (carriers/vacancies).
• Surface microkinetics: state = coverage on adsorption sites.
• Defect aggregation: state = positions/connectivity of defects.

Best practice: choose the coarsest state that still makes the dynamics approximately Markovian.

1. Build the Site Network (Graph)

For lattice KMC you need:

• site coordinates (fractional/cartesian),
• periodic cell,
• neighbor list (including periodic image shifts).

Validation:

• neighbor graph is symmetric (if i neighbors j, ensure j neighbors i with opposite shift).
• hop distances are physically reasonable (cutoffs/NN shells).

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/build_lattice_from_structure.py \
    --structure relaxed.cif \
    --site_element Li \
    --cutoff 3.2 \
    --out lattice.json

2. Define Elementary Events (Event Catalog)

An "elementary event" must specify:

• precondition: local pattern (occupied -> empty neighbor, reactant adjacency, etc.)
• action: update the state (swap occupancy, change species, etc.)
• rate constant k(T)

Best practice:

• Always include reverse events (or verify they exist).
• Avoid hidden multi-step processes masquerading as "one event" unless properly coarse-grained.
• Track degeneracy explicitly (many symmetry-equivalent realizations).

3. Assign Rates in a Thermodynamically Consistent Way

Most atomistic KMC models use Arrhenius / transition-state theory:

k = nu(T) * exp(-dG_barrier(T) / kBT)

Common approximations:

• Use a constant attempt frequency nu ~ 1e12-1e13 s^-1 (document it).
• Use 0 K NEB barriers dE_barrier as dG_barrier (document missing entropic contribution).
• For high rigor: compute nu(T) via harmonic TST (Vineyard-type prefactor) and include free-energy corrections.

Critical: detailed balance / microreversibility

If your simulation is intended to reproduce equilibrium thermodynamics, rates must satisfy:

k_ij / k_ji = exp(-(F_j - F_i) / kBT)

At minimum (energy-only model):

k_ij / k_ji ~ exp(-(E_j - E_i) / kBT)

4. Validate the Event Table (Completeness + Correctness)

Correctness checks:

• reverse transitions exist
• detailed balance holds (if applicable)
• rates have correct units and magnitudes

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/validate_detailed_balance.py \
    --config kmc_config.json

Completeness checks (modern best practice):

• Identify dominant events via sensitivity analysis (remove/perturb event types).
• Use on-the-fly discovery if needed.

If you see "stuck" behavior or unrealistically slow kinetics, the event catalog is likely incomplete.

5. Handle Flickers / Superbasins (Do NOT Ignore)

A common failure mode: the system executes extremely frequent small-barrier back-and-forth transitions ("flickers"), wasting steps without making physical progress.

Best-practice solutions include:

• superbasin / mean-rate / absorbing Markov chain acceleration methods,
• local superbasin methods,
• bac-MRM-style approaches (common in off-lattice/on-the-fly KMC).

At minimum:

• detect flickers (rapid repeated transitions among a small state set),
• report them in logs (so users know the model needs superbasin handling).