Merge branch 'master' into ml-evs/optimade-adapter

pymatgen/core/composition.py

@@ -767,11 +767,12 @@ def oxi_state_guesses(
                 element's common oxidation states, e.g. {"V": [2,3,4,5]}
             target_charge (int): the desired total charge on the structure.
                 Default is 0 signifying charge balance.
-            all_oxi_states (bool): if True, an element defaults to
-                all oxidation states in pymatgen Element.icsd_oxidation_states.
-                Otherwise, default is Element.common_oxidation_states. Note
-                that the full oxidation state list is *very* inclusive and
-                can produce nonsensical results.
+            all_oxi_states (bool): if True, all oxidation states of an element, even rare ones, are used in the search
+                for guesses. However, the full oxidation state list is *very* inclusive and can produce nonsensical
+                results. If False, the icsd_oxidation_states list is used when present, or the common_oxidation_states
+                is used when icsd_oxidation_states is not present. These oxidation states lists comprise more
+                commonly occurring oxidation states and results in more reliable guesses, albeit at the cost of
+                missing some uncommon situations. The default is False.
             max_sites (int): if possible, will reduce Compositions to at most
                 this many sites to speed up oxidation state guesses. If the
                 composition cannot be reduced to this many sites a ValueError
@@ -859,11 +860,12 @@ def add_charges_from_oxi_state_guesses(
                 element's common oxidation states, e.g. {"V": [2, 3, 4, 5]}
             target_charge (float): the desired total charge on the structure.
                 Default is 0 signifying charge balance.
-            all_oxi_states (bool): If True, an element defaults to
-                all oxidation states in pymatgen Element.icsd_oxidation_states.
-                Otherwise, default is Element.common_oxidation_states. Note
-                that the full oxidation state list is *very* inclusive and
-                can produce nonsensical results.
+            all_oxi_states (bool): if True, all oxidation states of an element, even rare ones, are used in the search
+                for guesses. However, the full oxidation state list is *very* inclusive and can produce nonsensical
+                results. If False, the icsd_oxidation_states list is used when present, or the common_oxidation_states
+                is used when icsd_oxidation_states is not present. These oxidation states lists comprise more
+                commonly occurring oxidation states and results in more reliable guesses, albeit at the cost of
+                missing some uncommon situations. The default is False.
             max_sites (int): If possible, will reduce Compositions to at most
                 this many sites to speed up oxidation state guesses. If the
                 composition cannot be reduced to this many sites a ValueError
@@ -916,15 +918,15 @@ def _get_oxi_state_guesses(
         calculation of the most likely oxidation states
 
         Args:
-            oxi_states_override (dict): dict of str->list to override an
-                element's common oxidation states, e.g. {"V": [2,3,4,5]}
-            target_charge (float): the desired total charge on the structure.
-                Default is 0 signifying charge balance.
-            all_oxi_states (bool): if True, an element defaults to
-                all oxidation states in pymatgen Element.icsd_oxidation_states.
-                Otherwise, default is Element.common_oxidation_states. Note
-                that the full oxidation state list is *very* inclusive and
-                can produce nonsensical results.
+            oxi_states_override (dict): dict of str->list to override an element's common oxidation states, e.g.
+                {"V": [2,3,4,5]}.
+            target_charge (float): the desired total charge on the structure. Default is 0 signifying charge balance.
+            all_oxi_states (bool): if True, all oxidation states of an element, even rare ones, are used in the search
+                for guesses. However, the full oxidation state list is *very* inclusive and can produce nonsensical
+                results. If False, the icsd_oxidation_states list is used when present, or the common_oxidation_states
+                is used when icsd_oxidation_states is not present. These oxidation states lists comprise more
+                commonly occurring oxidation states and results in more reliable guesses, albeit at the cost of
+                missing some uncommon situations. The default is False.
             max_sites (int): if possible, will reduce Compositions to at most
                 this many sites to speed up oxidation state guesses. If the
                 composition cannot be reduced to this many sites a ValueError
@@ -980,7 +982,7 @@ def _get_oxi_state_guesses(
             elif all_oxi_states:
                 oxids = Element(el).oxidation_states
             else:
-                oxids = Element(el).icsd_oxidation_states or Element(el).oxidation_states
+                oxids = Element(el).icsd_oxidation_states or Element(el).common_oxidation_states
 
             # Get all possible combinations of oxidation states
             # and sum each combination

pymatgen/core/structure.py

@@ -64,6 +64,7 @@
     from pymatgen.util.typing import CompositionLike, MillerIndex, PathLike, PbcLike, SpeciesLike
 
 FileFormats = Literal["cif", "poscar", "cssr", "json", "yaml", "yml", "xsf", "mcsqs", "res", "pwmat", ""]
+StructureSources = Literal["Materials Project", "COD"]
 
 
 class Neighbor(Site):
@@ -2937,6 +2938,28 @@ def to(self, filename: PathLike = "", fmt: FileFormats = "", **kwargs) -> str:
             writer.write_file(filename)
         return str(writer)
 
+    @classmethod
+    def from_id(cls, id: str, source: StructureSources = "Materials Project", **kwargs) -> Structure:
+        """
+        Load a structure file based on an id, usually from an online source.
+
+        Args:
+            id: The id. E.g., the materials project id.
+            source: Source of the data. Defaults to "Materials Project".
+            **kwargs: Pass-through to any API calls.
+        """
+        if source == "Materials Project":
+            from pymatgen.ext.matproj import MPRester
+
+            mpr = MPRester(**kwargs)
+            return mpr.get_structure_by_material_id(id)  # type: ignore
+        if source == "COD":
+            from pymatgen.ext.cod import COD
+
+            cod = COD()
+            return cod.get_structure_by_id(int(id))
+        raise ValueError(f"Invalid source: {source}")
+
     @classmethod
     def from_str(  # type: ignore[override]
         cls,

pymatgen/ext/matproj.py

@@ -229,7 +229,7 @@ def get_structure_by_material_id(self, material_id: str, conventional_unit_cell:
             Structure object.
         """
         prop = "structure"
-        response = self.request(f"materials/summary/{material_id}/?_fields={prop}")
+        response = self.request(f"materials/summary?material_ids={material_id}&_fields={prop}")
         structure = response[0][prop]
         if conventional_unit_cell:
             return SpacegroupAnalyzer(structure).get_conventional_standard_structure()

pymatgen/util/testing/__init__.py

@@ -1,8 +1,8 @@
-"""Common test support for pymatgen test scripts.
+"""This module implements testing utilities for materials science codes.
 
-This single module should provide all the common functionality for pymatgen
-tests in a single location, so that test scripts can just import it and work
-right away.
+While the primary use is within pymatgen, the functionality is meant to be useful for external materials science
+codes as well. For instance, obtaining example crystal structures to perform tests, specialized assert methods for
+materials science, etc.
 """
 
 from __future__ import annotations