matador.plugins.voronoi_interface package


matador.plugins.voronoi_interface.voronoi_interface module

This file implements a thin wrapper to the Voronoi code written by Can Kocer, for use with matador queries and docs.

Requires Can’s code to be on your PYTHONPATH.


Run Can’s Voronoi analysis on a matador doc.

matador.plugins.voronoi_interface.voronoi_interface.get_voronoi_points(doc, debug=False)[source]

Run Can’s Voronoi analysis on a matador doc and return nodes, face midpoints and edge midpoints.

matador.plugins.voronoi_interface.voronoi_similarity module

This file implements lattice-site level measures of similarity, using Voronoi decompositions.

Sketch of methodology:

  • For a list of structures, take each in turn, compute the Voronoi substructure

and create normalised padded arrays so that they can be compared.

  • For each structure, find the unique sites, to some definition of unique, initially

just a simple np.isclose() on the site arrays.

  • Now do an all-to-all comparison of the unique sites in each structure, yielding

an overall list of unique substructures. This step should have a dial that can be turned such that all sites fold onto each other, or all sites become distinct, i.e. sensitivity vs specificity.

  • [OPTIONAL] The remaining unique sites across the whole list can now be clustered, if desired,

using e.g. hierarchical clustering.

  • Every site in every structure can now be assigned to one of the unique sites above, or

one of the unique clusters.

  • Finally, the structures themselves can be clustered by the sites that are present, if desired.

matador.plugins.voronoi_interface.voronoi_similarity.are_sites_the_same(site_A, site_B, rtol=0.01, atol=0.01)[source]

Simple check for uniqueness of sites based on their Voronoi substructure.


site_A : dict, with elements as keys, containing numpy arrays of normalised solid angles.
site_B : dict, as A.
  • rtol (|) – relative tolerance in solid angle for np.allclose,

  • atol (|) – absolute tolerance in solid angle for np.allclose.


True if sites have approximately the same values for each species, else False.


Collect unique substrucs from each structure into a single dict.


cursor: list(dict), list of structures with pre-computed unique sites.

dict(list), dict with element symbol keys containing

a list of each unique substructure.

Return type



For a given set of elemental environments, find the greatest number of each element in a site.


single_elem_environments: list(dict), list of voronoi substructures,

dict(int), greatest number of each element in a substruc.

Return type


matador.plugins.voronoi_interface.voronoi_similarity.create_site_array(unique_environments, max_num_elems=None, elems=None, normalise=False)[source]

Create padded numpy arrays based on unique environments provided.


unique_environments: dict(list), dict with element keys full of local substructures.
  • max_num_elems (|) – dict(dict(int)), dict with element keys, containing sub-dict with element keys that contain the largest number of each type of element contributing to a site. If None, this will be calculated based on the input environments. The site array is padded to this size.

  • elems (|) – list(str), custom list of elements to loop over.

  • normalise (|) – bool, whether to normalise site array to 1.


dict(np.ndarray), dict with element keys full of

normalised site arrays.

max_num_elems : dict(dict(int)), dict with element keys containing the highest number of atoms of an element contributing to a particular site, e.g. {‘P’: {‘K’: 10}}.

Return type



Compute voronoi substructure and collect into dict. Sets the ‘voronoi_substruc’ and ‘substruc_dict’ entries in the doc.


doc: dict, structure to compute substructure of.
matador.plugins.voronoi_interface.voronoi_similarity.set_site_array(doc, normalise=False)[source]

Set the ‘site_array’ entry in the chosen document. Creates a dict of numpy arrays of normalised solid angles with element keys from the import calculated substructure.


doc: dict, matador doc containing substruc_dict.

normalise (|) – bool, whether to normalise site_arrays to total angle.

matador.plugins.voronoi_interface.voronoi_similarity.get_unique_sites(doc, atol=0.01, rtol=0.01)[source]
matador.plugins.voronoi_interface.voronoi_similarity.compare_docs(docA, docB, elems)[source]
matador.plugins.voronoi_interface.voronoi_similarity.cluster(X, hull, max_of_elems, elems=None, method='KMeans', elem='P', quantile=None, n_clusters=None, cmap='tab10')[source]
matador.plugins.voronoi_interface.voronoi_similarity.plot_class_hull(hull, n_clusters, plot_class=None)[source]
matador.plugins.voronoi_interface.voronoi_similarity.find_site_index(doc, elem, elem_ind)[source]
matador.plugins.voronoi_interface.voronoi_similarity.viz_site(doc, targ_substruc, elem, rmax=6)[source]