get_entries_in_chemsys added to MPRester (#353)

src/mp_api/matproj.py

@@ -2,6 +2,7 @@
 import warnings
 from typing import Optional, Tuple, List
 from enum import Enum, unique
+import itertools
 
 from pymatgen.core import Structure
 from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
@@ -361,6 +362,37 @@ def get_entry_by_material_id(self, material_id):
             ).entries.values()
         )
 
+    def get_entries_in_chemsys(
+        self, elements,
+    ):
+        """
+        Helper method to get a list of ComputedEntries in a chemical system.
+        For example, elements = ["Li", "Fe", "O"] will return a list of all
+        entries in the Li-Fe-O chemical system, i.e., all LixOy,
+        FexOy, LixFey, LixFeyOz, Li, Fe and O phases. Extremely useful for
+        creating phase diagrams of entire chemical systems.
+        Args:
+            elements (str or [str]): Chemical system string comprising element
+                symbols separated by dashes, e.g., "Li-Fe-O" or List of element
+                symbols, e.g., ["Li", "Fe", "O"].
+        Returns:
+            List of ComputedEntries.
+        """
+        if isinstance(elements, str):
+            elements = elements.split("-")
+
+        all_chemsyses = []
+        for i in range(len(elements)):
+            for els in itertools.combinations(elements, i + 1):
+                all_chemsyses.append("-".join(sorted(els)))
+
+        entries = []
+
+        for chemsys in all_chemsyses:
+            entries.extend(self.get_entries(chemsys_formula=chemsys))
+
+        return entries
+
     def get_bandstructure_by_material_id(
         self,
         material_id: str,

tests/test_mprester.py

@@ -111,6 +111,20 @@ def test_get_entries(self, mpr):
 
         assert sorted_entries != entries
 
+    def test_get_entries_in_chemsys(self, mpr):
+        syms = ["Li", "Fe", "O"]
+        syms2 = "Li-Fe-O"
+        entries = mpr.get_entries_in_chemsys(syms)
+        entries2 = mpr.get_entries_in_chemsys(syms2)
+        elements = set([Element(sym) for sym in syms])
+        for e in entries:
+            assert isinstance(e, ComputedEntry)
+            assert set(e.composition.elements).issubset(elements)
+
+        e1 = set([i.entry_id for i in entries])
+        e2 = set([i.entry_id for i in entries2])
+        assert e1 == e2
+
     def test_get_phonon_data_by_material_id(self, mpr):
         bs = mpr.get_phonon_bandstructure_by_material_id("mp-11659")
         assert isinstance(bs, PhononBandStructureSymmLine)