event_base

This module defines the Event class, which encapsulates the information required to represent a migration event in a lattice-based simulation, such as those used in kinetic Monte Carlo (kMC) studies.

The Event class focuses purely on defining which sites are involved in the hop and providing the local environment indices. All energy calculations are now handled by the model classes.

class kmcpy.event.base.Event(mobile_ion_indices, local_env_indices)

Represents a migration event in a lattice-based simulation.

The Event class focuses purely on defining which sites are involved in the hop and providing the local environment indices. All calculations are now handled by the model classes.

mobile_ion_indices

Compact active-site indices of the mobile ions involved in the event

Type:

tuple

local_env_indices

Compact active-site indices of the neighboring sites in the supercell

Type:

tuple

classmethod from_dict(event_dict)

Create Event from dictionary.

show_info()

Display information about the event.

class kmcpy.event.base.EventLib

A library of events, which can be used to store and manage multiple Event objects.

events

List of Event objects

Type:

list

event_dependencies

2D list where event_dependencies[i] contains indices of events that depend on event i (need to be updated when event i is executed). Dependencies are determined based on shared active-site indices.

Type:

list

site_to_events

Mapping from active-site index to list of event indices that involve that site

Type:

dict

Note: All indices (mobile_ion_indices and local_env_indices) are active-site indices, despite the misleading name of local_env_indices.

add_event(event)

Add an event to the library and update site mappings.

as_dict()

Convert EventLib to dictionary for serialization.

clear_event_dependencies()

Clear the event dependency matrix cache. Call this if events are modified.

classmethod from_dict(data)

Create EventLib from dictionary.

classmethod from_file(filename)

Load EventLib from a serialized event file.

generate_event_dependencies()

Generate the event dependency matrix and store it in the class.

For each event, find all other events that share active sites and thus have dependencies. When an event is executed, all dependent events need to be updated. The dependency matrix is stored as self.event_dependencies.

Note: All indices (mobile_ion_indices and local_env_indices) are active-site indices.

Returns:

2D list where event_dependencies[i] contains indices of events that

depend on event i (need to be updated when event i is executed).

Return type:

list

get_dependency_statistics()

Get statistics about the event dependency matrix for analysis.

Returns:

Dictionary containing dependency matrix statistics.

Return type:

dict

get_dependent_events(event_index)

Get all event indices that depend on the given event (need to be updated when it’s executed).

Parameters:

event_index (int) – Index of the event that was executed.

Returns:

List of event indices that depend on the given event.

Return type:

list

get_event_dependencies_info()

Get information about the stored event dependency matrix.

get_events_involving_site(site_index)

Get all events that involve a specific site.

Parameters:

site_index (int) – The site index to search for.

Returns:

List of event indices that involve the given site.

Return type:

list

has_event_dependencies()

Check if event dependency matrix is generated and stored.

set_index_metadata(active_site_order)

Attach active-site order metadata to this event library.

to(filename)

Write EventLib to a serialized event file.

validate_index_metadata(active_site_order)

Validate that event indices use the provided active-site index space.