local_site_order

Ordering rules for local-environment occupation vectors.

LocalSiteOrder defines only how already selected local sites are ordered and whether a real center site is included in the occupation vector. The center position itself is chosen by LocalLatticeStructure or the local-environment enumeration helpers.

class kmcpy.structure.local_site_order.LocalSiteOrder(name, sort_keys=('species_string',), exclude_center_site=False, center_match_tolerance=0.001)

Rules that define a local occupation-vector sequence.

This object is deliberately narrow: it does not choose the local-environment center and it does not decide whether the center is a real atom or an abstract coordinate. It only controls:

• sort keys for sites returned by the local cutoff search;

• whether a site matching the supplied center is removed from the vector.

If the center is an active-site index, exclude_center_site=True removes that exact site. If the center is a fractional coordinate, it removes a real site only when one lies within center_match_tolerance of that coordinate.

as_dict()

Serialize the local site order.

Return type:

dict[str, Any]

classmethod from_dict(data)

Create a local site order from serialized metadata.

Return type:

LocalSiteOrder

classmethod from_name(name)

Create a built-in local site order by name.

Return type:

LocalSiteOrder

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

classmethod resolve(order)

Normalize user input into a local site order.

Return type:

LocalSiteOrder

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.

sort_local_env_sites(local_env_sites)

Sort get_sites_in_sphere results according to this order.

Return type:

list[Any]

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

with_exclude_center_site(exclude_center_site)

Return a copy with an explicit center-site exclusion policy.

Return type:

LocalSiteOrder

kmcpy.structure.local_site_order.ordered_site_hash(signature)

Hash an ordered local-site signature for consistency checks.

Return type:

str

kmcpy.structure.local_site_order.ordered_site_signature(sites, *, decimals=8)

Return an order-sensitive, JSON-safe signature for local sites.

Return type:

list[dict[str, Any]]