models_base

Base model classes used across kMCpy.

class kmcpy.models.base.BaseModel(*args, **kwargs)

Base class for models in kmcpy.

This base class provides common serialization and loading conventions for model objects. Scientific operations such as compute, build, and compute_probability are optional because different model classes have different roles in a KMC workflow.

Constructor convention (pymatgen-style): - as_dict and from_dict handle structured data. - to and from_file handle file I/O.

name

Name of the model instance.

Type:

str, optional

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

abstractmethod as_dict()

Convert the model object to a dictionary representation.

build(*args, **kwargs)

Build model data from scientific inputs, when supported.

compute(*args, **kwargs)

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

compute_probability(*args, **kwargs)

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

fit(*args, **kwargs)

Fit model parameters using the model-specific fitter implementation.

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.

abstractmethod classmethod from_dict(d)

Create a model object from a dictionary representation.

classmethod from_file(fname)

Create a model object from a serialized file.

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)

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

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(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

kmcpy.models.base.require_model_file_payload(payload)

Validate and return a serialized model envelope dictionary.

kmcpy.models.base.require_model_type(payload, model_type)

Validate that a serialized model envelope declares the expected type.