Merge branch 'master' into pgh-ruff-rules

Author: DanielYang59

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

requirements-optional.txt

@@ -9,7 +9,7 @@ h5py==3.11.0
 # hiphive>=0.6
 icet>=2.2
 jarvis-tools>=2022.9.16
-matgl==1.1.1
+matgl==1.1.2
 netCDF4>=1.5.8
 phonopy==2.23.1
 seekpath>=2.0.1

requirements.txt

@@ -1,9 +1,9 @@
 numpy==1.26.4
 sympy==1.12
-requests==2.32.0
+requests==2.32.3
 monty==2024.5.24
 ruamel.yaml==0.18.6
-scipy==1.11.3
+scipy==1.13.1
 tabulate==0.9.0
 matplotlib==3.8.0
 palettable==3.3.3
@@ -12,7 +12,7 @@ pandas==2.1.1
 networkx==3.3
 plotly==5.17.0
 uncertainties==3.1.7
-Cython==3.0.2
+Cython==3.0.10
 pybtex==0.24.0
 tqdm==4.66.4
 joblib==1.3.2

tests/core/test_structure.py

@@ -924,6 +924,13 @@ def setUp(self):
         self.disordered = Structure.from_spacegroup("Im-3m", Lattice.cubic(3), [Composition("Fe0.5Mn0.5")], [[0, 0, 0]])
         self.labeled_structure = Structure(lattice, ["Si", "Si"], coords, labels=["Si1", "Si2"])
 
+    def test_from_id(self):
+        s = Structure.from_id("mp-1143")
+        assert isinstance(s, Structure)
+        assert s.reduced_formula == "Al2O3"
+        s = Structure.from_id("1101077", source="COD")
+        assert s.reduced_formula == "LiV2O4"
+
     def test_mutable_sequence_methods(self):
         struct = self.struct
         struct[0] = "Fe"