allow linelabels, bulk_stability

pymatgen/analysis/defects/plotting/phases.py

@@ -8,10 +8,20 @@
 from matplotlib.axes import Axes
 from matplotlib.patches import Polygon
 from pymatgen.core import Element
+from pymatgen.util.string import latexify
 from scipy.spatial import ConvexHull
 
 from pymatgen.analysis.defects.thermo import FormationEnergyDiagram
 
+# check if labellines is installed
+try:
+    from labellines import labelLines
+except ImportError:
+
+    def labelLines(*args, **kwargs):
+        pass
+
+
 __author__ = "Jimmy Shen"
 __copyright__ = "Copyright 2022, The Materials Project"
 __maintainer__ = "Jimmy Shen @jmmshn"
@@ -26,6 +36,9 @@ def plot_chempot_2d(
     y_element: Element,
     ax: Axes | None = None,
     min_mu: float = -5.0,
+    label_lines: bool = False,
+    x_vals: list[float] | None = None,
+    label_fontsize: int = 12,
 ):
     """Plot the chemical potential diagram for two elements.
 
@@ -40,6 +53,10 @@ def plot_chempot_2d(
             The matplotlib axes to plot on. If None, a new figure will be created.
         min_mu:
             The minimum chemical potential to plot.
+        label_lines:
+            Whether to label the lines with the competing phases. Requires Labellines to be installed.
+        x_vals:
+            The x position of the line labels. If None, defaults will be used.
     """
     PLOT_PADDING = 0.1
     ax = ax or plt.gca()
@@ -53,7 +70,7 @@ def plot_chempot_2d(
     y_min = float("inf")
     clip_path = []
     for p1, p2, phase in hull2d:
-        p_txt = ", ".join(phase.keys())
+        p_txt = ", ".join(map(latexify, phase.keys()))
         ax.axline(p1, p2, label=p_txt, color="k")
         ax.scatter(p1[0], p1[1], color="k")
         x_m_ = p1[0] if p1[0] > min_mu else float("inf")
@@ -72,6 +89,8 @@ def plot_chempot_2d(
     ax.set_ylabel(f"$\Delta\mu_{{{y_element}}}$ (eV)")
     ax.set_xlim(x_min - PLOT_PADDING, 0 + PLOT_PADDING)
     ax.set_ylim(y_min - PLOT_PADDING, 0 + PLOT_PADDING)
+    if label_lines:
+        labelLines(ax.get_lines(), align=False, xvals=x_vals, fontsize=label_fontsize)
 
 
 def _convex_hull_2d(

pymatgen/analysis/defects/thermo.py

@@ -213,7 +213,9 @@ class FormationEnergyDiagram(MSONable):
             A artificial value is needed to help the half-space intersection algorithm.
             This can be justified since these tend to be the substitutional elements
             which should not have very negative chemical potential.
-
+        bulk_stability:
+            If the bulk energy is above the convex hull, lower it to this value below
+            the convex hull.
     """
 
     defect_entries: List[DefectEntry]
@@ -222,6 +224,7 @@ class FormationEnergyDiagram(MSONable):
     band_gap: Optional[float] = None
     bulk_entry: Optional[ComputedStructureEntry] = None
     inc_inf_values: bool = False
+    bulk_stability: float = 0.001
 
     def __post_init__(self):
         """Post-initialization.
@@ -248,7 +251,7 @@ def __post_init__(self):
         pd_ = PhaseDiagram(self.pd_entries)
         entries = pd_.stable_entries | {bulk_entry}
         pd_ = PhaseDiagram(entries)
-        self.phase_diagram = ensure_stable_bulk(pd_, bulk_entry)
+        self.phase_diagram = ensure_stable_bulk(pd_, bulk_entry, self.bulk_stability)
         entries = []
         for entry in self.phase_diagram.stable_entries:
             d_ = dict(
@@ -259,8 +262,12 @@ def __post_init__(self):
             )
             entries.append(ComputedEntry.from_dict(d_))
             entries.append(ComputedEntry.from_dict(d_))
-
         self.chempot_diagram = ChemicalPotentialDiagram(entries)
+        if bulk_entry.composition.reduced_formula not in self.chempot_diagram.domains:
+            raise ValueError(
+                "Bulk entry is not stable in the chemical potential diagram."
+                "Consider increasing the `bulk_stability` to make it more stable."
+            )
         chempot_limits = self.chempot_diagram.domains[
             bulk_entry.composition.reduced_formula
         ]
@@ -819,6 +826,7 @@ def _get_name(fed):
 def ensure_stable_bulk(
     pd: PhaseDiagram,
     entry: ComputedEntry,
+    threshold: float = 0.001,
 ) -> PhaseDiagram:
     """Added entry to phase diagram and ensure that it is stable.
 
@@ -834,14 +842,16 @@ def ensure_stable_bulk(
             Phase diagram.
         entry:
             entry to be added
+        threshold:
+            If the bulk energy is above the convex hull, lower it to this value below
+            the convex hull.
 
     Returns:
         PhaseDiagram:
             Modified Phase diagram.
     """
-    SMALL_NUM = 1e-8
     stable_entry = ComputedEntry(
-        entry.composition, pd.get_hull_energy(entry.composition) - SMALL_NUM
+        entry.composition, pd.get_hull_energy(entry.composition) - threshold
     )
     pd = PhaseDiagram(pd.all_entries + [stable_entry])
     return pd

pyproject.toml

@@ -6,9 +6,9 @@ requires = ["setuptools >= 42", "versioningit ~= 1.0", "wheel"]
 authors = [{ name = "Jimmy-Xuan Shen", email = "[email protected]" }]
 classifiers = [
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Science/Research",
   "Operating System :: OS Independent",
@@ -26,7 +26,7 @@ keywords = ["high-throughput", "automated", "dft", "defects"]
 license = { text = "modified BSD" }
 name = "pymatgen-analysis-defects"
 readme = "README.rst"
-requires-python = '>=3.8'
+requires-python = '>=3.9'
 
 [project.optional-dependencies]
 finder = ["dscribe>=2.0.0"]
@@ -74,7 +74,7 @@ line-length = 88
 extend-ignore = "E203, W503, E501, F401, RST21"
 max-line-length = 120
 max-doc-length = 120
-min-python-version = "3.8.0"
+min-python-version = "3.9.0"
 rst-roles = "class, func, ref, obj"
 select = "C, E, F, W, B, B950"