local_cluster_expansion

This module provides classes and functions to build a Local Cluster Expansion (LCE) model for kinetic Monte Carlo (KMC) simulations, particularly for ionic conductors such as NaSICON materials. The main class, LocalClusterExpansion, reads a crystal structure file (e.g., CIF format), processes the structure to define a local migration unit, and generates clusters (points, pairs, triplets, quadruplets) within a specified cutoff. The clusters are grouped into orbits based on symmetry, and the resulting model can be serialized to JSON for use in KMC simulations.

class kmcpy.models.local_cluster_expansion.LocalClusterExpansion

LocalClusterExpansion will be initialized with a template structure where all the sites are occupied cutoff_cluster is the cutoff for pairs and triplet cutoff_region is the cutoff for generating local cluster region

apply_event(*, event, simulation_state)

Commit an accepted event to optional model-side state.

Stateless models can ignore this hook. Stateful external adapters should update only the changed sites here so their internal state stays aligned with kMCpy’s State.

Return type:

None

as_dict()

Return a dictionary representation of the LocalClusterExpansion.

build(local_lattice_structure, cutoff_cluster=[6, 6, 6], **kwargs)

Build the LocalClusterExpansion model from a Structure object.

The local-environment center is already defined by local_lattice_structure. If that center was a structure site, it may be included or excluded according to the local site order. If the center was a fractional-coordinate point, it is only a geometric origin and is not itself an occupation-vector site.

Parameters:

• local_lattice_structure (LocalLatticeStructure) – Local environment object containing the structure and center site.

• cutoff_cluster (list, optional) – Cutoff distances for clusters [pair, triplet, quadruplet]. Defaults to [6, 6, 6].

Return type:

None

Notes

If the next-step KMC is not based on the same LCE object generated in this step, be careful with two things: 1) The Ekra generated in this step can be transferred to the KMC, provided the orbits are arranged in the same way as here. 2) The cluster_site_indices must correspond exactly to the input structure used in the KMC step, which may require reconstruction of an LCE object using the same KMC-input structure.

build_orbits(clusters)

return a list of Orbit

For each orbit, loop over clusters

for each cluster, check if this cluster exists in this orbit

if not, attach the cluster to orbit else,

compute(simulation_state, event)

Compute the fitted scalar value for this event/local environment.

LocalClusterExpansion does not distinguish barrier and site-energy-difference roles internally. A model passed as the kra_model in CompositeLCEModel returns E_KRA. A model passed as the site_model returns the site-energy-difference contribution expected by that composite model.

Parameters:

• simulation_state (State) – State object containing occupation vector (preferred)

• event (Event) – Event object containing mobile ion indices (required for local environment)

Returns:

The fitted scalar value

Return type:

float

compute_probability(*args, **kwargs)

Compute an event rate/probability for KMC, when supported.

fit(*args, **kwargs)

Fit parameters and include this model’s local-environment metadata.

classmethod from_config(config)

Load the configured model.

Called on BaseModel, this dispatches to the concrete model class declared by the model file or config.model_type. Called on a concrete subclass, it loads that subclass directly from config.model_file.

classmethod from_dict(data)

Load a LocalClusterExpansion object from a dictionary payload.

Parameters:

data (dict) – Dictionary containing serialized LocalClusterExpansion data.

Returns:

The loaded LocalClusterExpansion object

Return type:

LocalClusterExpansion

classmethod from_file(filename)

Load a LocalClusterExpansion object from a serialized file.

Parameters:

filename (str) – Path to the JSON file containing the LocalClusterExpansion data

Returns:

The loaded LocalClusterExpansion object

Return type:

LocalClusterExpansion

get_corr_from_structure(structure, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5)

get_corr_from_structure() returns a correlation numpy array.

classmethod get_fitter_class()

Return fitter implementation for this model class.

get_occ_corr_from_structure(structure, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5)

Compute occupation and correlation vectors from a structure.

Parameters:

• structure (Structure) – Structure to featurize.

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to map structure sites into the model’s local site order. If omitted, the model must carry local_lattice_structure from build.

• exclude_species (Optional[Sequence[str]]) – Removed argument; use site_mapping fixed sites.

• tol – Structure matching tolerance.

• angle_tol – Structure matching angle tolerance.

Returns:

(occupation, correlation).

Return type:

tuple

get_orbit_fingerprints()

Return orbit fingerprints in the same order as the correlation vector.

Return type:

list[str]

initialize_state(*, simulation_state, event_lib=None, structure=None, config=None, active_site_order=None)

Initialize optional stateful model caches from the KMC state.

Stateless models can ignore this hook. Stateful adapters can use it to build their own occupancy representation once, instead of rebuilding it during every event-rate evaluation.

Return type:

None

classmethod load(file_path)

Loads a class from a provided json file.

Parameters:

file_path (os.PathLike) – The json file to load from.

Returns:

An instance of the class being reloaded.

Return type:

MSONable

load_parameters_from_file(filename)

Load fitted parameters from a JSON file.

Parameters:

filename (str) – Path to the JSON file containing LCE parameters

save(json_path, mkdir=True, json_kwargs=None, pickle_kwargs=None, strict=True)

Utility that uses the standard tools of MSONable to convert the class to json format, but also save it to disk. In addition, this method intelligently uses pickle to individually pickle class objects that are not serializable, saving them separately. This maximizes the readability of the saved class information while allowing _any_ class to be at least partially serializable to disk.

For a fully MSONable class, only a class.json file will be saved to the location {save_dir}/class.json. For a partially MSONable class, additional information will be saved to the save directory at {save_dir}. This includes a pickled object for each attribute that e serialized.

Parameters:

• file_path (os.PathLike) – The file to which to save the json object. A pickled object of the same name but different extension might also be saved if the class is not entirely MSONable.

• mkdir (bool) – If True, makes the provided directory, including all parent directories.

• json_kwargs (dict) – Keyword arguments to pass to the serializer.

• pickle_kwargs (dict) – Keyword arguments to pass to pickle.dump.

• strict (bool) – If True, will not allow you to overwrite existing files.

set_parameters(parameters)

Set fitted parameters for this LocalClusterExpansion model.

Parameters:

parameters – LCEModelParameters object or dict containing keci and empty_cluster

to(fname)

Save the model object to a JSON file.

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

unsafe_hash()

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x

validate_reference_lattice_structure(reference_local_lattice_structure)

Validate that a reference local lattice has the same site order as the model.

Parameters:

reference_local_lattice_structure (LocalLatticeStructure) – Reference used to map structures into occupation vectors.

Raises:

ValueError – If the reference order is incompatible with this model.

Return type:

None

write_representative_clusters(filename='representative_clusters.txt')

Write representative clusters to a text file.

Parameters:

filename – Name of the output file