generators

This module provides tools for generating and matching local atomic environments and events for kinetic Monte Carlo (kMC) simulations, particularly for ionic diffusion in crystalline solids. It includes utilities for neighbor environment matching, event generation, and supercell normalization, with support for structures parsed by pymatgen.

class kmcpy.event.generators.EventGenerator

Generate migration events by combining point+cutoff environment detection with primitive-template expansion into a supercell.

This keeps neighbor searches in the primitive cell only, then maps pre-ordered templates to each supercell image via dictionary lookups for performance.

generate_events(structure_file='210.cif', convert_to_primitive_cell=False, local_env_cutoff_dict=None, mobile_ion_identifiers=None, distance_matrix_rtol=0.01, distance_matrix_atol=0.01, find_nearest_if_fail=True, export_local_env_structure=False, supercell_shape=None, event_file='events.json', mobile_species=None, site_mapping=None, local_env_cutoff=None, rtol=None, atol=None)

Generate migration events and save as bundled event library.

Events are saved with embedded dependencies in a single JSON file. The dependency matrix is computed and stored as an attribute of EventLib.

Event generation always follows the performant primitive-template -> supercell expansion workflow.

site_mapping is the canonical active-site convention. When mobile_species is omitted, kMCpy infers it from mapping entries that include a vacancy state such as "X". Label identifiers are only needed when the hop endpoints must be restricted to specific crystallographic labels, for example ("Na1", "Na2").

Return type:

Dict

kmcpy.event.generators.find_atom_indices(structure, site_selection_kind='species', atom_identifier='Li+')

Return site indices matching a species or crystallographic label identifier.

Parameters:

• structure (Structure) – structure object to work on

• site_selection_kind (str, optional) – Select from [“species”, “label”]. Defaults to “species”.

• atom_identifier (str, optional) – identifier of atom. Defaults to “Li+”.

• input (typical)

• site_selection_kind=species

• atom_identifier="Li+"

• site_selection_kind=label

• atom_identifier="Li1"

Raises:

ValueError – site_selection_kind is not recognized.

Returns:

list of atom indices that satisfy the identifier

Return type:

list

kmcpy.event.generators.normalize_supercell_tuple(site_belongs_to_supercell=[5, 1, 7], image_of_site=(0, -1, 1), supercell_shape=[5, 6, 7], additional_input=False)

finding the equivalent position in periodic supercell considering the periodic boundary condition. i.e., normalize the supercell tuple to make sure that each component of supercell is greater than zero

for example,

# 5 1 7 with image 0 -1 1 -> 5 0 8 -> in periodic 567 supercell should change to 561, suppose supercell start with index1

input: site_belongs_to_supercell: site belongs to which supercell

Returns:

supercell tuple

Return type:

tuple