site_energy

Site-energy-difference models for composite KMC simulations.

class kmcpy.models.site_energy.MappedOccupationChange(kmcpy_site, external_site, old_state, new_state, old_value, new_value)

One local occupation change in both kMCpy and external coordinates.

as_flip()

Return (external_site, new_value) for smol-style APIs.

Return type:

tuple[int, Any]

as_system_change_tuple()

Return (external_site, old_value, new_value).

Return type:

tuple[int, Any, Any]

class kmcpy.models.site_energy.SiteEnergyModel(compute_fn=None, compute_ref=None, compute_kwargs=None, apply_fn=None, apply_ref=None, apply_kwargs=None, runtime=None, runtime_ref=None, runtime_kwargs=None, site_mapping=None, state_mapping=None, state_mapping_by_site=None, initial_occupation=None, external_size=None, external_fill_value=0, external_dtype=None, active_site_order=None, active_site_order_hash=None, units='eV', name='SiteEnergyModel')

Site-energy-difference model with optional external-site mapping.

The model returns E_after_hop - E_before_hop for a proposed event. If site_mapping and state mappings are omitted, the callable receives kMCpy active-site indices and occupation labels. If an external code has a different site order or state encoding, provide mappings once before KMC starts; per-event evaluation then touches only the two event endpoints.

initialize_state validates the mapping once, builds the external occupation once, and caches site/state mapping dictionaries as lookup arrays. compute passes only the two endpoint changes for the proposed event to compute_fn. apply_event updates only accepted endpoints and optionally calls apply_fn to keep a live external evaluator synchronized.

compute_fn is called as:

compute_fn(
    runtime=runtime,
    external_occupation=external_occupation,
    changes=changes,
    event=event,
    simulation_state=simulation_state,
    **compute_kwargs,
)

where changes is a list of MappedOccupationChange objects. Simple callables may also accept only the subset they need, such as event and simulation_state. It must return E_after_hop - E_before_hop in units.

apply_fn is optional and is called before the cached external occupation is updated in place.

apply_event(*, event, simulation_state)

Commit one accepted event to the external runtime and cache.

Return type:

None

as_dict()

Convert the model object to a dictionary representation.

Return type:

dict[str, Any]

build(*args, **kwargs)

Build model data from scientific inputs, when supported.

compute(event, simulation_state)

Return E_after_hop - E_before_hop in meV.

Return type:

float

compute_probability(*args, **kwargs)

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

property external_site_order_hash: str

Order-sensitive hash of the active-site to external-site mapping.

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.

classmethod from_dict(data)

Create a model object from a dictionary representation.

Return type:

SiteEnergyModel

classmethod from_file(filename)

Create a model object from a serialized file.

Return type:

SiteEnergyModel

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)

Build and validate external occupation caches once.

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)

Save the model object to a JSON file.

Return type:

None

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

property unit_factor_to_mev: float

Conversion factor from configured units to meV.

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.site_energy.constant_site_energy_difference(event=None, simulation_state=None, value=0.0, **kwargs)

Small helper used by examples/tests to return a constant difference.

Return type:

float

kmcpy.models.site_energy.resolve_callable_reference(callable_ref)

Resolve module:function or module.function references.