xtalmet.distance module

This module offers a range of distance functions for crystals.

xtalmet.distance.distance(distance: str, xtal_1: Structure | Crystal | tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str, xtal_2: Structure | Crystal | tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str, normalize: bool = True, verbose: bool = False, **kwargs) → float | tuple[float, tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str, tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str]View on GitHub

Compute the distance between two crystals.

Parameters:

  • distance (str) – The distance metric to use. Currently supported metrics are listed in SUPPORTED_DISTANCES in constants.py. For more detailed information about each distance metric, please refer to the tutorial notebook.

  • xtal_1 (Structure | Crystal | TYPE_EMB_ALL) – pymatgen Structure or Crystal or an embedding.

  • xtal_2 (Structure | Crystal | TYPE_EMB_ALL) – pymatgen Structure or Crystal or an embedding.

  • normalize (bool) – Whether to normalize the distance d to [0, 1] by using d’ = d / (1 + d). This argument is only considered when d is a continuous distance that is not normalized to [0, 1]. Such distances are listed in CONTINUOUS_UNNORMALIZED_DISTANCES in constants.py. Default is True.

  • verbose (bool) – Whether to return intermediate embeddings. Default is False.

  • **kwargs – Additional keyword arguments for specific distance metrics. It can contain two keys: “args_emb” and “args_dist”. The value of “args_emb” is a dict of arguments for the calculation of embeddings, and the value of “args_dist” is a dict of arguments for the calculation of distance between the embeddings. If embeddings are pre-computed and provided as inputs, the “args_emb” will be ignored.

Returns:

Distance between crystals. If verbose is True, also returns the embeddings and the computing time.

Return type:

float | tuple[np.ndarray, TYPE_EMB_ALL, TYPE_EMB_ALL, dict[str, float]]

Raises:

ValueError – If an unsupported distance metric is provided.

xtalmet.distance.TYPE_D_MTX_RETURN = numpy.ndarray | tuple[numpy.ndarray, list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | numpy.ndarray[numpy.float32 | numpy.float64] | str], dict[str, float]] | tuple[numpy.ndarray, list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | numpy.ndarray[numpy.float32 | numpy.float64] | str], list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | numpy.ndarray[numpy.float32 | numpy.float64] | str], dict[str, float]]

Return type for distance_matrix function.

xtalmet.distance.distance_matrix(distance: str, xtals_1: list[Structure | Crystal | tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str], xtals_2: list[Structure | Crystal | tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str] | None = None, normalize: bool = True, multiprocessing: bool = False, n_processes: int | None = None, verbose: bool = False, **kwargs) → ndarray | tuple[ndarray, list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str], dict[str, float]] | tuple[ndarray, list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str], list[tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str], dict[str, float]]View on GitHub

Compute the distance matrix between two sets of crystals.

If xtals_2 is None, compute the distance matrix within xtals_1.

Parameters:

  • distance (str) – The distance metric to use. Currently supported metrics are listed in SUPPORTED_DISTANCES in constants.py. For more detailed information about each distance metric, please refer to the tutorial notebook.

  • xtals_1 (list[Structure | Crystal | TYPE_EMB_ALL]) – A list of pymatgen Structures or Crystals or embeddings.

  • xtals_2 (list[Structure | Crystal | TYPE_EMB_ALL] | None) – A list of pymatgen Structures or Crystals or embeddings, or None. Default is None.

  • normalize (bool) – Whether to normalize the distances d to [0, 1] by using d’ = d / (1 + d). This argument is only considered when d is a continuous distance that is not normalized to [0, 1]. Such distances are listed in CONTINUOUS_UNNORMALIZED_DISTANCES in constants.py. Default is True.

  • multiprocessing (bool) – Whether to use multiprocessing. Default is False.

  • n_processes (int | None) – Maximum number of processes for multiprocessing. If multiprocessing is False, this argument will be ignored. Default is None.

  • verbose (bool) – Whether to return embeddings and the computing time. Default is False.

  • **kwargs – Additional keyword arguments for specific distance metrics. It can contain two keys: “args_emb” and “args_dist”. The value of “args_emb” is a dict of arguments for the calculation of embeddings, and the value of “args_dist” is a dict of arguments for the calculation of distance matrix using the embeddings.

Returns:

Distance matrix, the embeddings of xtals_1 (and xtals_2 if xtals_2 is not None) and the computing time.

Return type:

TYPE_D_MTX_RETURN

Raises:

ValueError – If an unsupported distance metric is provided.