cluster¶

Finite clusters of sites and deterministic cluster matching.

class kmcpy.structure.cluster.Cluster(site_indices=None, sites=None, *, species=None, coords=None, roles=None, metadata=None, distance_matrix=None, sym=None, analyze_symmetry=False)[source]¶

A finite labeled cluster of sites.

The cluster stores species, site indices, optional per-site metadata, and a distance matrix. It is used both by local cluster expansion terms and by event local-environment matching.

as_dict()[source]¶: Serialize the cluster.

property fingerprint: str¶: Stable cluster fingerprint with rounded distances.

classmethod from_dict(data)[source]¶

Create a cluster from a Monty-style payload.

Return type:: Cluster

classmethod from_neighbor_info(neighbor_info, roles=None, analyze_symmetry=False)[source]¶

Build a cluster from pymatgen near-neighbor dictionaries.

Return type:: Cluster

classmethod from_sites(sites, site_indices=None, roles=None, metadata=None, analyze_symmetry=False)[source]¶

Build a cluster from pymatgen sites or coordinate-like objects.

Return type:: Cluster

get_bond_distances()[source]¶: Return max, min, and sorted pair distances.

get_cluster_function(occupation)[source]¶: Return the occupation product for this cluster.

property labels: tuple[tuple[str, str], ...]¶: Species and role labels used as node colors during matching.

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

property point_group_symbol: str¶: Return the cluster point-group symbol, computed on demand.

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.

property signature: tuple[tuple[tuple[str, str], int], ...]¶: Order-independent label-count signature.

to_json()¶

Returns a json string representation of the MSONable object.

Return type:: str

to_xyz(fname)[source]¶: Write the cluster structure as XYZ.

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

class kmcpy.structure.cluster.ClusterMatch(reference_to_candidate, candidate_to_reference, ordered_candidate_indices, fingerprint, is_unique, score=0.0)[source]¶: Permutation returned by matching a candidate cluster to a reference.

class kmcpy.structure.cluster.ClusterMatcher(reference, rtol=0.001, atol=0.001)[source]¶

Match candidate clusters to a reference cluster order.

match(candidate, *, require_unique=False, find_nearest_if_fail=False)[source]¶

Return the permutation that orders candidate sites like the reference.

Return type:: ClusterMatch

ordered_candidate_indices(candidate, *, require_unique=False, find_nearest_if_fail=False)[source]¶

Return candidate site indices ordered in the reference convention.

Return type:: tuple[int, ...]

class kmcpy.structure.cluster.Orbit[source]¶

A group of equivalent clusters.

as_dict()[source]¶: A JSON serializable dict representation of an object.

property cluster_site_indices¶: Cluster site-index sets included in this orbit.

property fingerprint¶: Stable identity for the orbit term associated with one ECI.