Choose And Build A Model¶

Every kMC event needs a rate. In kMCpy, rates come from a model. Choose the smallest model that represents the physics you need, then build that model before preparing the final simulation input.

Model	Use When	Data Needed
`LocalBarrierModel`	Barriers can be written as explicit local rules.	Constants, count rules, wildcard rules, or exact local environments.
`LocalClusterExpansion`	A local scalar should be fitted from local-environment data.	A reference local lattice, cluster cutoffs, and fitted coefficients from NEB or other target data.
`CompositeLCEModel`	You have one model for `E_KRA` and optionally another model for site-energy differences.	A fitted KRA model and optional site-energy-difference model.
`SiteEnergyModel`	A callable or external code supplies site-energy differences.	A runtime object or callable plus site/state mappings.

Local Barrier Branch¶

Use LocalBarrierModel when the barrier rule is direct and readable. A constant barrier is the smallest valid model:

from kmcpy.models import LocalBarrierModel

model = LocalBarrierModel.constant_barrier(300.0)  # meV
model.to("local_barrier_model.json")

constant_barrier(barrier) takes one required argument:

barrier: activation barrier in meV, used for every valid event.

Rules are evaluated in order. The first matching rule provides the barrier; if no rule matches, default_barrier is used. For species-count rules, provide site_species so kMCpy can translate each active-site occupation state into a chemical label:

from kmcpy.models import LocalBarrierModel

model = LocalBarrierModel(
    default_barrier=350.0,
    site_species={
        5: {0: "P", 1: "Si"},
        6: {0: "Si", 1: "P"},
        7: {0: "Al", 1: "Si"},
        8: {0: "Si", 1: "P"},
    },
)
model.add_species_count_rule(
    name="si_rich",
    sites="local_env",
    species="Si",
    min_count=3,
    barrier=420.0,
)
model.to("local_barrier_model.json")

The important arguments are:

default_barrier: fallback barrier in meV.
site_species: mapping {active_site_index: {state_index: species_label}} used by species-count rules.
sites: which sites the rule counts. "local_env" counts the event local environment. "canonical" counts the two mobile-ion endpoints followed by the local-environment sites with duplicates removed.
min_count, max_count, or count: the count condition.
barrier: barrier in meV returned when the rule matches.

For exact-match tables, wildcard patterns, and more rule examples, see Use advanced local barrier rules.

LCE Branch¶

Use LocalClusterExpansion when a local scalar should be fitted from local environment data. The scalar can be E_KRA, a site-energy-difference term, or another model quantity. The meaning comes from where the LCE is used later.

An LCE is built in two stages:

Build a LocalLatticeStructure. This defines the local environment and the local site order.
Build the LocalClusterExpansion. This enumerates point, pair, triplet, and quadruplet clusters inside the local environment.

from pymatgen.core import Structure

from kmcpy.models import LocalClusterExpansion
from kmcpy.structure import LocalLatticeStructure

structure = Structure.from_file("nasicon.cif")
site_mapping = {
    "Na": ["Na", "X"],
    "Zr": "Zr",
    "Si": ["Si", "P"],
    "O": "O",
}

local_lattice = LocalLatticeStructure(
    template_structure=structure,
    center=0,
    cutoff=4.0,
    site_mapping=site_mapping,
    basis_type="chebyshev",
    local_site_order="kmcpy_default",
)

kra_lce = LocalClusterExpansion()
kra_lce.build(
    local_lattice_structure=local_lattice,
    cutoff_cluster=[6.0, 6.0, 0.0],
)

The important LocalLatticeStructure arguments are:

template_structure: structure containing every possible mobile-ion site.
center: local-environment origin. It can be a structure site index or a fractional-coordinate point. If it is a real site, the local site order controls whether the center is included in the occupation vector.
cutoff: radius used to select local-environment sites.
site_mapping: allowed occupation states for active sites and fixed species for inactive sites.
basis_type: occupation encoding. Use "chebyshev" for multicomponent active sites.
local_site_order: deterministic order for the local occupation vector. See Control local site order.

The important LocalClusterExpansion.build(...) arguments are:

local_lattice_structure: the ordered local lattice just built.
cutoff_cluster: [pair, triplet, quadruplet] cutoffs in angstrom. The LCE always includes point clusters; the list controls higher-body clusters.

The fitted scalar is

\[ y(\sigma) = E_0 + \sum_j \alpha_j \Phi_j(\sigma) \]

where sigma is the ordered local occupation vector, Phi_j are decorated cluster-orbit features, and alpha_j are fitted coefficients.

At this point the LCE has the correct feature order, but it has no fitted coefficients. Continue to Local Environments And NEB Data and Fit A Local Cluster Expansion.

Composite LCE Models¶

For transition-state-theory rates, kMCpy can combine a KRA model and a site-energy-difference model:

from kmcpy.models import CompositeLCEModel

model = CompositeLCEModel(
    kra_model=kra_lce,
    site_model=site_lce,  # optional
)
model.to("model.json")

The effective barrier is

\[ E_{\mathrm{eff}} = E_{\mathrm{KRA}} + \frac{\Delta E_{\mathrm{site}}}{2} \]

where the site model provides the signed event energy change.

The same LocalClusterExpansion.compute(...) method is used for any fitted scalar:

as kra_model, it returns E_KRA;
as site_model, it returns the fitted site-energy-difference contribution for the canonical event orientation.

External Site-Energy Models¶

Use SiteEnergyModel when an external runtime, such as a cluster-expansion evaluator, supplies only the site-energy difference. kMCpy initializes the external occupation once, precomputes array-backed site/state mappings, and then passes only the changed endpoints to the callable for each proposed event.

See Use site-energy-difference models for the external-code workflow.