kmc

This module provides the KMC class and associated functions for performing Kinetic Monte Carlo (kMC) simulations, particularly for modeling processes in materials such as ion diffusion. The KMC class manages the initialization, event handling, probability calculations, and simulation loop for kMC workflows. It supports loading input data from various sources, updating system states, and tracking simulation results.

class kmcpy.simulator.kmc.KMC(structure, model, event_lib, config, simulation_state=None, hop_state_lookup=None, active_site_order=None, **kwargs)

Kinetic Monte Carlo Simulation Class.

This class implements a Kinetic Monte Carlo (kMC) simulation for modeling stochastic processes in materials, such as ion diffusion. It provides methods for initializing the simulation from various input sources, managing events, updating system states, and running the simulation loop.

attach(func, interval=None, time_interval=None, name=None, store=True, max_records=None, on_error=None, enabled=True)

Attach a custom property callback to the KMC run.

Parameters:

• func (Callable[[State, int, float], Any]) – Callback with signature (state, step, time).

• interval (Optional[int]) – Event-step interval override for this callback.

• time_interval (Optional[float]) – Simulation-time interval override for this callback.

• name (Optional[str]) – Optional callback name; defaults to function __name__.

• store (bool) – Whether callback return values should be stored.

• max_records (Optional[int]) – Optional cap on stored record count for this callback.

• on_error (Optional[Callable[[Exception, State, int, float], bool]]) – Optional error handler. Return True to continue.

Returns:

The callback name used for registration.

Return type:

str

clear_attachments()

Remove all attached custom property callbacks.

Return type:

None

detach(name)

Detach a previously attached custom property callback.

Return type:

None

classmethod from_config(config)

Create a KMC instance from a Configuration.

Return type:

KMC

list_attachments()

Return names of currently attached custom property callbacks.

Return type:

list[str]

list_property_calculations()

Return enabled/disabled built-ins and currently attached callbacks.

Return type:

dict[str, list[str]]

propose(events)

Propose a new event to be updated by update().

Parameters:

events (list) – List of events.

Returns:

The chosen event, the time for this event to occur, and the event index.

Return type:

tuple[Event, float, int]

run(label=None)

Run KMC simulation using this instance’s Configuration object.

This is the main method for running KMC simulations using the modern Configuration format.

Parameters:

label (str, optional) – Label for the simulation run. Defaults to None. If None, will use self.config.name.

Returns:

Tracker object containing simulation results.

Return type:

kmcpy.tracker.Tracker

Example:

# Using Configuration
config = Configuration(name="Test", temperature=400.0, ...)
tracker = kmc.run()

# Alternative usage patterns:
# 1. Create KMC and run in one step
kmc = KMC.from_config(config)
tracker = kmc.run()

set_property_enabled(name, enabled)

Enable or disable a built-in summary field or attached callback.

Return type:

None

set_property_frequency(interval=None, time_interval=None)

Set global sampling frequency for built-in and attached properties.

Parameters:

• interval (Optional[int]) – Global event-step interval.

• time_interval (Optional[float]) – Global simulation-time interval.

Return type:

None

show_project_info()

Log current probability vectors for quick diagnostics.

update(event, dt=0.0)

Updates the system state and event probabilities after an event occurs.

This method delegates state management to State, following clean architecture principles with single responsibility and separation of concerns.

This method performs the following steps: 1. Delegates occupation updates to State.apply_event() 2. Automatically finds the event index in the event library 3. Identifies all events that need probability updates using EventLib 4. Recalculates probabilities for affected events 5. Updates the cumulative probability list for event selection

Parameters:

• event (Event) – The event object that has just occurred.

• dt (float, optional) – Time increment for this event. Used for state tracking.

Return type:

None

Side Effects:

Modifies occupation state and probability lists via State delegation.