xtalmet.distance module

This module offers a range of distance functions for crystals.

xtalmet.distance.d_smat(xtal_1: Structure | Crystal, xtal_2: Structure | Crystal, **kwargs) → floatView on GitHub 

Compute the binary distance based on pymatgen’s StructureMatcher.

Parameters:

xtal_1 (Structure | Crystal) – pymatgen Structure or Crystal.
xtal_2 (Structure | Crystal) – pymatgen Structure or Crystal.
**kwargs – Additional arguments for StructureMatcher, e.g., ltol, stol, angle_tol.

Returns:

StructureMatcher-based distance (0.0 or 1.0).

Return type:

float

Note

d_smat does not allow pre-computation of embeddings.

xtalmet.distance.d_comp(xtal_1: Structure | Crystal | tuple[tuple[str, int]], xtal_2: Structure | Crystal | tuple[tuple[str, int]]) → floatView on GitHub 

Compute the binary distance based on the match of compositions.

Parameters:

xtal_1 (Structure | Crystal | tuple[tuple[str, int]]) – pymatgen Structure or Crystal or its embedding.
xtal_2 (Structure | Crystal | tuple[tuple[str, int]]) – pymatgen Structure or Crystal or its embedding.

Returns:

Composition distance (0.0 or 1.0).

Return type:

float

Compute the binary distance based on the match of Wyckoff representations.

Parameters:

xtal_1 (Structure | Crystal | tuple[int, tuple[str]]) – pymatgen Structure or Crystal or its embedding.
xtal_2 (Structure | Crystal | tuple[int, tuple[str]]) – pymatgen Structure or Crystal or its embedding.

Returns:

Wyckoff distance (0.0 or 1.0).

Return type:

float

xtalmet.distance.d_magpie(xtal_1: Structure | Crystal | list[float], xtal_2: Structure | Crystal | list[float]) → floatView on GitHub 

Compute the continuous distance using compositional Magpie fingerprints.

Parameters:

xtal_1 (Structure | Crystal | list[float]) – pymatgen Structure or Crystal or its
embedding.
xtal_2 (Structure | Crystal | list[float]) – pymatgen Structure or Crystal or its embedding.

Returns:

Magpie distance.

Return type:

float

References

Ward et al., (2016). A general-purpose machine learning framework for
predicting properties of inorganic materials. npj Computational Materials, 2(1), 1-7. https://doi.org/10.1038/npjcompumats.2016.28

Compute the continuous distance using the pointwise distance distribution (PDD).

Parameters:

xtal_1 (Structure | Crystal | np.ndarray[np.float32 | np.float64]) – pymatgen Structure or Crystal or its embedding.
xtal_2 (Structure | Crystal | np.ndarray[np.float32 | np.float64]) – pymatgen Structure or Crystal or its embedding.
**kwargs – Additional arguments for amd.PDD and amd.PDD_cdist. It can contain two keys: “emb” and “dist”. The value of “emb” is a dict of arguments for amd.PDD, and the value of “dist” is a dict of arguments for amd.PDD_cdist.

Returns:

PDD distance.

Return type:

float

Examples

>>> kwargs = {
...     "emb": {"k": 100},
...     "dist": {
...         "metric": "chebyshev",
...         "backend": "multiprocessing",
...         "n_jobs": 2,
...         "verbose": False,
...     },
... }
>>> d_pdd(xtal_1, xtal_2, **kwargs)
0.123456789

References

Widdowson et al., (2022). Resolving the data ambiguity for periodic
crystals. Advances in Neural Information Processing Systems, 35, 24625–24638. https://openreview.net/forum?id=4wrB7Mo9_OQ

Compute the continuous distance using the average minimum distance (AMD).

Parameters:

xtal_1 (Structure | Crystal | np.ndarray[np.float32 | np.float64]) – pymatgen Structure or Crystal or its embedding.
xtal_2 (Structure | Crystal | np.ndarray[np.float32 | np.float64]) – pymatgen Structure or Crystal or its embedding.
**kwargs – Additional arguments for amd.AMD and amd.AMD_cdist. It should contain two keys: “emb” and “dist”. The value of “emb” is a dict of arguments for amd.AMD, and the value of “dist” is a dict of arguments for amd.AMD_cdist.

Returns:

AMD distance.

Return type:

float

Examples

>>> kwargs = {
...     "emb": {"k": 100},
...     "dist": {"metric": "chebyshev", "low_memory": False},
... }
>>> d_amd(xtal_1, xtal_2, **kwargs)
0.123456789

References

Widdson et al., (2022). Average Minimum Distances of periodic point sets -
foundational invariants for mapping periodic crystals. MATCH Communications in Mathematical and in Computer Chemistry, 87(3), 529-559, https://doi.org/10.46793/match.87-3.529W