xtalmet.stability module

This module offers functions to compute the stability of crystal structures.

class xtalmet.stability.StabilityCalculator(diagram: Literal['mp_250618', 'mp'] | PatchedPhaseDiagram | str = 'mp_250618', mace_model: str = 'mace-mh-1', binary=True, threshold: float = 0.1, intercept: float = 1.215)View on GitHub

Bases: object

Class to calculate stability scores of crystal structures.

Initialize StabilityCalculator.

Parameters:

  • diagram (Literal["mp_250618", "mp"] | PatchedPhaseDiagram | str) – A phased diagram to use. If “mp_250618” is specified, the diagram constructed using this class from the MP entries on June 18, 2025, will be used. If “mp” is specified, the diagram will be constructed on the spot. You can also pass your own diagram or a path to it.

  • mace_model (str) – The MACE model to use for energy prediction. Default is “mace-mh-1”.

  • binary (bool) – If True, compute binary stability scores (1 for stable, 0 for unstable). If False, compute continuous stability scores between 0 and 1. Default is True.

  • threshold (float) – Energy above hull threshold for stability in eV/atom. Only used if binary is True. Default is 0.1 eV/atom.

  • intercept (float) – Intercept for linear scaling of stability scores in eV/atom. Only used if binary is False. Default is 1.215 eV/atom, which is the 99th percentile of the energy above hull values for the MP data with theoretical=False.

compute_stability_scores(xtals: list[Crystal], e_above_hulls_precomputed: ndarray[float] | None = None) → tuple[ndarray[float], ndarray[float], float]View on GitHub

Compute stability scores for a list of crystals.

Parameters:

  • xtals (list[Crystal]) – List of crystals to compute stability scores for.

  • e_above_hulls_precomputed (np.ndarray[float] | None) – Precomputed energy above hull values. If None, they will be computed internally.

Returns:

A tuple of stability scores, raw energy above hull values, and computation time in seconds.

Return type:

tuple[np.ndarray[float], np.ndarray[float], float]