structuretoolkit 0.0.41__tar.gz → 0.0.42__tar.gz

{structuretoolkit-0.0.41 → structuretoolkit-0.0.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structuretoolkit
-Version: 0.0.41
+Version: 0.0.42
 Summary: build, analyse and visualise atomistic structures for materials science
 Project-URL: Homepage, https://github.com/pyiron/structuretoolkit
 Project-URL: Documentation, https://github.com/pyiron/structuretoolkit
@@ -49,7 +49,7 @@ Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: <3.15,>=3.10
 Requires-Dist: ase<=3.28.0,>=3.20.1
 Requires-Dist: numpy<=2.4.3,>=1.23.5
-Requires-Dist: scipy<=1.17.0,>=1.15.0
+Requires-Dist: scipy<=1.17.1,>=1.15.0
 Provides-Extra: clusters
 Requires-Dist: scikit-learn==1.8.0; extra == 'clusters'
 Provides-Extra: dscribe
@@ -59,10 +59,13 @@ Requires-Dist: aimsgb<=1.1.1,>=1.0.2; extra == 'grainboundary'
 Requires-Dist: pymatgen<=2026.3.23,>=2022.2.1; extra == 'grainboundary'
 Provides-Extra: matplotlib
 Requires-Dist: matplotlib==3.10.8; extra == 'matplotlib'
+Provides-Extra: mp-api
+Requires-Dist: mp-api==0.45.15; extra == 'mp-api'
+Requires-Dist: pymatgen<=2026.3.23,>=2022.2.1; extra == 'mp-api'
 Provides-Extra: nglview
 Requires-Dist: nglview<=4.0.1,>=2.7.7; extra == 'nglview'
 Provides-Extra: phonopy
-Requires-Dist: phonopy<=3.2.1,>=2.16.2; extra == 'phonopy'
+Requires-Dist: phonopy<=3.5.0,>=2.16.2; extra == 'phonopy'
 Requires-Dist: spglib==2.7.0; extra == 'phonopy'
 Provides-Extra: plotly
 Requires-Dist: plotly<=6.6.0,>=4.14.3; extra == 'plotly'

{structuretoolkit-0.0.41 → structuretoolkit-0.0.42}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
 dependencies = [
     "ase>=3.20.1,<=3.28.0",
     "numpy>=1.23.5,<=2.4.3",
-    "scipy>=1.15.0,<=1.17.0",
+    "scipy>=1.15.0,<=1.17.1",
 ]
 dynamic = ["version"]
 
@@ -52,9 +52,13 @@ surface = [
     "pymatgen>=2022.2.1,<=2026.3.23",
 ]
 phonopy = [
-    "phonopy>=2.16.2,<=3.2.1",
+    "phonopy>=2.16.2,<=3.5.0",
     "spglib==2.7.0",
 ]
+mp-api = [
+    "mp-api==0.45.15",
+    "pymatgen>=2022.2.1,<=2026.3.23",
+]
 
 [tool.ruff]
 exclude = [".ci_support", "tests", "setup.py", "_version.py"]

{structuretoolkit-0.0.41 → structuretoolkit-0.0.42}/src/structuretoolkit/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.41'
-__version_tuple__ = version_tuple = (0, 0, 41)
+__version__ = version = '0.0.42'
+__version_tuple__ = version_tuple = (0, 0, 42)
 
 __commit_id__ = commit_id = None

{structuretoolkit-0.0.41 → structuretoolkit-0.0.42}/src/structuretoolkit/build/__init__.py

@@ -2,6 +2,10 @@ from structuretoolkit.build.aimsgb import get_grainboundary_info, grainboundary
 from structuretoolkit.build.compound import B2, C14, C15, C36, D03
 from structuretoolkit.build.mesh import create_mesh
 from structuretoolkit.build.sqs import sqs_structures
+from structuretoolkit.build.materialsproject import (
+    search as materialsproject_search,
+    by_id as materialsproject_by_id,
+)
 from structuretoolkit.build.surface import (
     get_high_index_surface_info,
     high_index_surface,
@@ -19,4 +23,6 @@ __all__ = [
     "sqs_structures",
     "get_high_index_surface_info",
     "high_index_surface",
+    "materialsproject_search",
+    "materialsproject_by_id",
 ]

structuretoolkit-0.0.42/src/structuretoolkit/build/materialsproject.py

@@ -0,0 +1,138 @@
+from typing import Any, Iterable
+from collections.abc import Generator
+from ase.atoms import Atoms
+from structuretoolkit.common.pymatgen import pymatgen_to_ase
+
+
+def search(
+    chemsys: str | list[str], fields: Iterable[str] = (), api_key=None, **kwargs
+) -> Generator[dict[str, Any], None, None]:
+    """
+    Search the database for all structures matching the given query.
+
+    Note that `chemsys` takes distinct values for unaries, binaries and so!  A query with `chemsys=["Fe", "O"]` will
+    return iron and oxygen structures but not iron oxide.  Similarly `chemsys=["Fe-O"]` will
+    not return unary structures.
+
+    All keyword arguments for filtering from the original API are supported.  See the
+    `original docs <https://docs.materialsproject.org/downloading-data/using-the-api>`_ for them.
+
+    Search for all iron structures:
+
+    >>> irons = structuretoolkit.build.materialsproject.search("Fe")
+    >>> len(list(irons))
+    10
+
+    Search for all structures with Al, Li that are on the T=0 convex hull:
+
+    >>> alli = structuretoolkit.build.materialsproject.search(['Al', 'Li', 'Al-Li'], is_stable=True)
+    >>> len(list(alli))
+    6
+
+    Usage is only possible with an API key obtained from the Materials Project.  To do this, create an account with
+    them, login and access `this webpage <https://next-gen.materialsproject.org/api#api-key>`.
+
+    Once you have a key, either pass it as the `api_key` parameter or export an
+    environment variable, called `MP_API_KEY`, in your shell setup.
+
+    Args:
+        chemsys (str, list of str): confine search to given elements; either an element symbol or multiple element
+            symbols separated by dashes; if a list of strings is given return structures matching either of them
+        fields (iterable of str): pass as `fields` to :meth:`mp_api.MPRester.summary.search` to request additional
+            database entries beyond the structure
+        api_key (str, optional): if your API key is not exported in the environment flag MP_API_KEY, pass it here
+        **kwargs: passed verbatim to :meth:`mp_api.MPRester.summary.search` to further filter the results
+
+    Returns:
+        list of dict: one dictionary for each search results with at least keys
+            'material_id': database key of the hit
+            'structure': ASE atoms object
+            plus any requested via `fields`.
+    """
+    from mp_api.client import MPRester
+
+    rest_kwargs = {
+        "use_document_model": False,  # returns results as dictionaries
+        "include_user_agent": True,  # send some additional software version info to MP
+    }
+    if api_key is not None:
+        rest_kwargs["api_key"] = api_key
+    with MPRester(**rest_kwargs) as mpr:
+        results = mpr.summary.search(
+            chemsys=chemsys,
+            **kwargs,
+            fields=list(fields) + ["structure", "material_id"],
+        )
+    for r in results:
+        if "structure" in r:
+            r["structure"] = pymatgen_to_ase(r["structure"])
+        yield r
+
+
+def by_id(
+    material_id: str | int,
+    final: bool = True,
+    conventional_unit_cell: bool = False,
+    api_key=None,
+) -> Atoms | list[Atoms]:
+    """
+    Retrieve a structure by material id.
+
+    This is how you would ask for the iron ground state:
+
+    >>> structuretoolkit.build.materialsproject.by_id('mp-13')
+    Fe: [0. 0. 0.]
+    tags:
+        spin: [(0: 2.214)]
+    pbc: [ True  True  True]
+    cell:
+    Cell([[2.318956, 0.000185, -0.819712], [-1.159251, 2.008215, -0.819524], [2.5e-05, 0.000273, 2.459206]])
+
+    Usage is only possible with an API key obtained from the Materials Project.  To do this, create an account with
+    them, login and access `this webpage <https://next-gen.materialsproject.org/api#api-key>`.
+
+    Once you have a key, either pass it as the `api_key` parameter or export an
+    environment variable, called `MP_API_KEY`, in your shell setup.
+
+    Args:
+        material_id (str): the id assigned to a structure by the materials project
+        api_key (str, optional): if your API key is not exported in the environment flag MP_API_KEY, pass it here
+        final (bool, optional): if set to False, returns the list of initial structures,
+        else returns the final structure. (Default is True)
+        conventional_unit_cell (bool, optional): if set to True, returns the standard conventional unit cell.
+        (Default is False)
+
+    Returns:
+        :class:`~.Atoms`: requested final structure if final is True
+        list of :class:~.Atoms`:  a list of initial (pre-relaxation) structures if final is False
+
+    Raises:
+        ValueError: material id does not exist
+    """
+    from mp_api.client import MPRester
+
+    rest_kwargs = {
+        "include_user_agent": True,  # send some additional software version info to MP
+    }
+    if api_key is not None:
+        rest_kwargs["api_key"] = api_key
+    with MPRester(**rest_kwargs) as mpr:
+        if final:
+            return pymatgen_to_ase(
+                mpr.get_structure_by_material_id(
+                    material_id=material_id,
+                    final=final,
+                    conventional_unit_cell=conventional_unit_cell,
+                )
+            )
+        else:
+            return [
+                pymatgen_to_ase(mpr_structure)
+                for mpr_structure in (
+                    mpr.get_structure_by_material_id(
+                        material_id=material_id,
+                        final=final,
+                        conventional_unit_cell=conventional_unit_cell,
+                    )
+                )
+            ]