composite_lce_model

Composite Local Cluster Expansion Model

This module combines a KRA model with an optional site-energy-difference model for transition-rate calculations.

Author: Zeyu Deng

class kmcpy.models.composite_lce_model.CompositeLCEModel(site_model=None, kra_model=None, kra_fit_metadata=None, site_fit_metadata=None, *args, **kwargs)[source]

A composite model that combines a KRA LCE with a site-energy-difference model.

This class combines one LocalClusterExpansion for E_KRA with a site-energy-difference contribution. A LocalClusterExpansion always uses compute(simulation_state=..., event=...); its meaning comes from the role it is passed into. As kra_model it returns E_KRA. As site_model it returns the site-energy-difference contribution for the canonical event orientation. SiteEnergyModel exposes the same compute(event=..., simulation_state=...) interface and returns the signed event energy change, E_after_hop - E_before_hop, in meV.

The composite model provides:

  • compute_probability(): compute transition probability from an event

Example:

# Create individual models with parameters
site_model = LocalClusterExpansion(...)
site_model.load_parameters_from_file("site_parameters.json")

kra_model = LocalClusterExpansion(...)
kra_model.load_parameters_from_file("kra_parameters.json")

# Combine them
composite = CompositeLCEModel(site_model, kra_model)

# Use the composite model with State (preferred)
probability = composite.compute_probability(
    event=event,
    runtime_config=runtime_config,
    simulation_state=simulation_state
)
apply_event(*, event, simulation_state)[source]

Commit an accepted event to optional stateful submodels.

Return type:

None

as_dict()[source]

Serialize this composite model to the standard model-file payload.

build(*args, **kwargs)[source]

Composite models are assembled from separately built LCE models.

compute(*args, **kwargs)

Compute this model’s native quantity, when the model defines one.

compute_probability(event, runtime_config, simulation_state)[source]

Compute the transition probability/rate in Hz for a given event using the composite LCE model.

This method calculates the transition probability for a migration event by:

  • Computing the site-energy difference (delta_e_site, meV) using the site model.

  • Computing the barrier energy (e_kra, meV) using the barrier LocalClusterExpansion model and its stored parameters.

  • Determining the direction of the event from the occupation vector in the State.

  • Calculating the effective barrier as: e_barrier = e_kra + delta_e_site / 2

  • Using the Arrhenius equation to compute the probability: probability = hop_available * v * np.exp(-e_barrier / (k * temperature))

Parameters:

  • event (Event) – The migration event, containing mobile ion indices and local environment info.

  • runtime_config (RuntimeConfig) – Contains attempt frequency (v) and temperature (T).

  • simulation_state (State) – Contains the current occupation vector.

Returns:

The computed transition probability/rate in Hz.

Return type:

float

fit(*args, **kwargs)[source]

Composite models are assembled from separately fitted LCE models.

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)[source]

Create a CompositeLCEModel from a serialized payload.

Return type:

CompositeLCEModel

classmethod from_file(model_file)[source]

Create a CompositeLCEModel from a serialized model file.

Return type:

CompositeLCEModel

classmethod get_fitter_class()

Return fitter implementation for this model class.

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

Initialize optional stateful submodel caches.

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

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.

to(filename, indent=2)[source]

Write this composite model to a serialized model file.

Return type:

None

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