diff --git a/mp_api/client/core/_display.py b/mp_api/client/core/_display.py index af23f321..285c2244 100644 --- a/mp_api/client/core/_display.py +++ b/mp_api/client/core/_display.py @@ -89,6 +89,10 @@ unreachable, data missing, a local dataset reused): `logger.warning/info`. - Diagnostics: `logger.debug`. - Transient progress: `progress_bar` / `status`, interactive output only. + Bars and summary lines report work the caller asked for: lookups the client + makes on its own behalf (resolving IDs, then fetching the data) run inside a + `status()`, which describes the whole operation and keeps the bars inside it + from drawing or printing anything. - Output the user explicitly asked for (`notify_db_version`): `print_notice`. So WARNING-level log records always mean something went wrong, and @@ -119,6 +123,7 @@ from __future__ import annotations +import contextvars import io import logging import threading @@ -446,6 +451,13 @@ def update(self, advance: float = 1) -> None: self._progress.advance(self._task_id, advance) +# Whether a `status()` block is running in this context. Contextvars are copied +# into worker threads by `_external.in_current_context`, so those inherit it. +_IN_OPERATION: contextvars.ContextVar[bool] = contextvars.ContextVar( + "mp_api_client_in_operation", default=False +) + + def _as_int(value: float | None) -> float | None: """Show (near) whole-number counts as ints, without a trailing `.0`.""" if isinstance(value, float) and abs(value - round(value)) < 1e-6: @@ -469,7 +481,9 @@ def progress_bar( Args: description (str) : label shown next to the bar total (float or None) : expected number of units, None if unknown - enabled (bool) : if False, nothing is shown (a no-op handle is yielded) + enabled (bool) : if False, nothing is shown (a no-op handle is yielded). + Nothing is shown either inside a `status()` block, which describes + the whole operation itself. delay (float) : seconds before the bar is shown, so quick operations stay silent. Checked on each update. unit (str) : unit name for the rate column @@ -487,7 +501,7 @@ def progress_bar( ProgressHandle """ console = get_console() - if not enabled or is_quiet(): + if not enabled or is_quiet() or _IN_OPERATION.get(): yield ProgressHandle(total, summary=summary) return if not _is_interactive(console): @@ -705,25 +719,41 @@ def status(message: str, *, enabled: bool = True) -> Iterator[None]: of WARNING-level logs). If disabled (muted progress bars) or in quiet mode, nothing is shown or logged. + The status describes the whole operation the caller asked for, so + everything inside it stays quiet: + + - `progress_bar`s inside the block draw nothing, print no summary line and + log nothing (e.g. the lookup of a material's IDs the client makes on + its own behalf); + - a `status` nested in another one shows and logs nothing. + + Work with countable progress that the caller should watch (a multi-page + download) needs a `progress_bar` instead of a `status`. + Args: message (str) : what is happening, e.g. "Counting documents..." enabled (bool) : if False, show nothing """ console = get_console() - if not enabled or is_quiet(): - yield - return - if not (_is_interactive(console) and _can_draw_live(console)): - logging.getLogger(LOGGER_NAME).info(message) + if not enabled or is_quiet() or _IN_OPERATION.get(): yield return - progress = _STATE.acquire(console) - task_id = progress.add_task(message, total=None, status=True) + token = _IN_OPERATION.set(True) try: - yield + if not (_is_interactive(console) and _can_draw_live(console)): + logging.getLogger(LOGGER_NAME).info(message) + yield + return + + progress = _STATE.acquire(console) + task_id = progress.add_task(message, total=None, status=True) + try: + yield + finally: + _STATE.release(task_id) finally: - _STATE.release(task_id) + _IN_OPERATION.reset(token) def _app_handlers(logger: logging.Logger) -> list[logging.Handler]: diff --git a/mp_api/client/core/_external.py b/mp_api/client/core/_external.py index f949d56a..4ee33ad4 100644 --- a/mp_api/client/core/_external.py +++ b/mp_api/client/core/_external.py @@ -154,6 +154,8 @@ def _tracked(fn: Callable[..., Any]) -> Callable[..., Any]: @functools.wraps(fn) def wrapper(*args: Any, **kwargs: Any) -> Any: + # keep this frame out of tracebacks in IPython, Jupyter and pytest + __tracebackhide__ = True with capturing(): return fn(*args, **kwargs) diff --git a/mp_api/client/mprester.py b/mp_api/client/mprester.py index 9b02a4f3..70a8c2e8 100644 --- a/mp_api/client/mprester.py +++ b/mp_api/client/mprester.py @@ -74,6 +74,7 @@ from typing import Any, Literal import numpy as np + from emmet.core.phonon import PhononBS, PhononDOS from emmet.core.tasks import CoreTaskDoc from packaging.version import Version from pymatgen.analysis.phase_diagram import PDEntry @@ -1514,31 +1515,52 @@ def get_dos_by_material_id( load_projections=load_projections, ) - def get_phonon_dos_by_material_id(self, material_id: str): + def get_phonon_dos_by_material_id( + self, + material_id: str, + phonon_method: Literal["pheasy", "dfpt"] | None = None, + ) -> PhononDOS | dict[str, Any]: """Get phonon density of states data corresponding to a material_id. Args: material_id (str): Materials Project material_id. + phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default, + the method is chosen from the material's data: pheasy if it has it, + otherwise dfpt. If the pheasy calculation has no DOS, the dfpt one + is used (with a warning). A method passed explicitly is never replaced. Returns: - CompletePhononDos: A phonon DOS object. - + dos (PhononDOS): PhononDOS object """ return self.materials.phonon.get_dos_from_material_id( - material_id=material_id, phonon_method="dfpt" + material_id=material_id, phonon_method=phonon_method ) - def get_phonon_bandstructure_by_material_id(self, material_id: str): + def get_phonon_bandstructure_by_material_id( + self, + material_id: str, + phonon_method: Literal["pheasy", "dfpt"] | None = None, + path_type: str | BSPathType = BSPathType.setyawan_curtarolo, + ) -> PhononBS | dict[str, Any]: """Get phonon dispersion data corresponding to a material_id. Args: material_id (str): Materials Project material_id. + phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default, + the method is chosen from the material's data: pheasy if it has it, + otherwise dfpt. If the pheasy calculation has no band structure, + the dfpt one is used (with a warning). A method passed explicitly + is never replaced. + path_type (BSPathType or str): k-path selection convention for the band structure. + pheasy has all conventions; dfpt only has setyawan_curtarolo. Returns: - PhononBandStructureSymmLine: phonon band structure. + bandstructure (PhononBS): PhononBS object """ return self.materials.phonon.get_bandstructure_from_material_id( - material_id=material_id, phonon_method="dfpt" + material_id=material_id, + phonon_method=phonon_method, + path_type=path_type, ) def get_wulff_shape(self, material_id: str): @@ -1796,8 +1818,7 @@ def get_cohesive_energy( # Prevent user error if isinstance(material_ids, str | MPID): raise MPRestError( - "Input material IDs (even a single ID) as a list: " - f"`[{material_ids}]`" + f"Input material IDs (even a single ID) as a list: `[{material_ids}]`" ) entry_preference = { diff --git a/mp_api/client/routes/materials/electronic_structure.py b/mp_api/client/routes/materials/electronic_structure.py index dc12eb96..36093f8d 100644 --- a/mp_api/client/routes/materials/electronic_structure.py +++ b/mp_api/client/routes/materials/electronic_structure.py @@ -16,7 +16,7 @@ from pymatgen.electronic_structure.core import OrbitalType, Spin from mp_api.client.core import BaseRester, MPRestError -from mp_api.client.core._display import mp_deprecation +from mp_api.client.core._display import mp_deprecation, status from mp_api.client.core.utils import validate_ids if TYPE_CHECKING: @@ -284,48 +284,57 @@ def get_bandstructure_from_task_id( Returns: bandstructure (BandStructure): BandStructure or BandStructureSymmLine object """ - bs_lbl, _ = self._get_delta_table( - "materialsproject-parsed", - "core/electronic-structure/bandstructures/", - label="bandstructure", - ) - - query = f""" - SELECT * - FROM {bs_lbl} - WHERE identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}' - """ + with status( + f"Fetching the band structure for {task_id}...", + enabled=not self.mute_progress_bars, + ): + bs_lbl, _ = self._get_delta_table( + "materialsproject-parsed", + "core/electronic-structure/bandstructures/", + label="bandstructure", + ) - if run_type: - rt = RunType(run_type) if isinstance(run_type, str) else run_type - query += f"\nAND run_type='{rt.value}'" - if path_type: - query += f"\nAND path_convention='{path_type}'" - - table = self._query_delta_single(query, label=bs_lbl) - if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0: - if load_projections: - proj_bs_label, _ = self._get_delta_table( - "materialsproject-parsed", - "core/electronic-structure/projected-bandstructures/", - label="bandstructure_projections", - ) - proj_table = self._query_delta_single( - query.replace(bs_lbl, proj_bs_label), label=proj_bs_label + query = f""" + SELECT * + FROM {bs_lbl} + WHERE identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}' + """ + + if run_type: + rt = RunType(run_type) if isinstance(run_type, str) else run_type + query += f"\nAND run_type='{rt.value}'" + if path_type: + query += f"\nAND path_convention='{path_type}'" + + table = self._query_delta_single(query, label=bs_lbl) + if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0: + if load_projections: + proj_bs_label, _ = self._get_delta_table( + "materialsproject-parsed", + "core/electronic-structure/projected-bandstructures/", + label="bandstructure_projections", + ) + proj_table = self._query_delta_single( + query.replace(bs_lbl, proj_bs_label), label=proj_bs_label + ) + if ( + len( + deser_proj := proj_table.to_pylist(maps_as_pydicts="strict") + ) + > 0 + ): + deser[0]["projections"] = deser_proj[0] + emmet_bs = ElectronicBS(**deser[0]) + return emmet_bs.to_pmg( + pmg_cls=( + BandStructureSymmLine if emmet_bs.labels_dict else BandStructure + ) ) - if ( - len(deser_proj := proj_table.to_pylist(maps_as_pydicts="strict")) - > 0 - ): - deser[0]["projections"] = deser_proj[0] - emmet_bs = ElectronicBS(**deser[0]) - return emmet_bs.to_pmg( - pmg_cls=BandStructureSymmLine if emmet_bs.labels_dict else BandStructure + raise MPRestError( + f"No bandstructure data found for {task_id=}" + + (f" and run_type={rt.value}" if run_type else "") + + (f" and path_type={path_type}" if path_type else "") ) - raise MPRestError( - f"No bandstructure data found for {task_id=}" - + (f"run_type={rt}" if run_type else "") - ) def get_bandstructure_from_material_id( self, @@ -349,62 +358,73 @@ def get_bandstructure_from_material_id( pt: BSPathType = ( BSPathType(path_type) if isinstance(path_type, str) else path_type ) - if line_mode: - bs_doc = self.es_rester.search( - material_ids=material_id, fields=["bandstructure"] - ) - if not bs_doc: - raise MPRestError( - f"No electronic structure data found for material ID {material_id}." + kind = f"{pt.value} band structure" if line_mode else "uniform band structure" + with status( + f"Fetching the {kind} for {material_id}...", + enabled=not self.mute_progress_bars, + ): + if line_mode: + bs_doc = self.es_rester.search( + material_ids=material_id, fields=["bandstructure"] ) - - if (_bs_data := bs_doc[0]["bandstructure"]) is None: - raise MPRestError( - f"No {pt.value} band structure data found for {material_id}" + if not bs_doc: + raise MPRestError( + f"No electronic structure data found for material ID {material_id}." + ) + + if (_bs_data := bs_doc[0]["bandstructure"]) is None: + raise MPRestError( + f"No {pt.value} band structure data found for {material_id}" + ) + + bs_data = ( + _bs_data.model_dump() if self.use_document_model else _bs_data # type: ignore ) - bs_data = ( - _bs_data.model_dump() if self.use_document_model else _bs_data # type: ignore + if bs_data.get(pt.value, None) is None: + available = sorted(k for k, v in bs_data.items() if v is not None) + raise MPRestError( + f"No {pt.value} band structure data found for {material_id}" + + ( + f" (available: {', '.join(available)})." + if available + else "." + ) + ) + bs_task_id = bs_data[pt.value]["task_id"] + + else: + if not ( + bs_doc := self.es_rester.search( + material_ids=material_id, fields=["dos"] + ) + ): + raise MPRestError( + f"No electronic structure data found for material ID {material_id}." + ) + + if (_bs_data := bs_doc[0]["dos"]) is None: + raise MPRestError( + f"No uniform band structure data found for {material_id}" + ) + + bs_data = _bs_data.model_dump() if self.use_document_model else _bs_data + + if bs_data.get("total", None) is None: + raise MPRestError( + f"No uniform band structure data found for {material_id}" + ) + bs_task_id = bs_data["task_id"] + + bs_obj = self.get_bandstructure_from_task_id( + bs_task_id, + path_type=pt if line_mode else BSPathType.unknown, + load_projections=load_projections, ) - if bs_data.get(pt.value, None) is None: - raise MPRestError( - f"No {pt.value} band structure data found for {material_id}" - ) - bs_task_id = bs_data[pt.value]["task_id"] - - else: - if not ( - bs_doc := self.es_rester.search( - material_ids=material_id, fields=["dos"] - ) - ): - raise MPRestError( - f"No electronic structure data found for material ID {material_id}." - ) - - if (_bs_data := bs_doc[0]["dos"]) is None: - raise MPRestError( - f"No uniform band structure data found for {material_id}" - ) - - bs_data = _bs_data.model_dump() if self.use_document_model else _bs_data - - if bs_data.get("total", None) is None: - raise MPRestError( - f"No uniform band structure data found for {material_id}" - ) - bs_task_id = bs_data["task_id"] - - bs_obj = self.get_bandstructure_from_task_id( - bs_task_id, - path_type=pt if line_mode else BSPathType.unknown, - load_projections=load_projections, - ) - - if bs_obj: - return bs_obj - raise MPRestError("No band structure object found.") + if bs_obj: + return bs_obj + raise MPRestError("No band structure object found.") class DosRester(BaseESPropertyRester): @@ -540,42 +560,49 @@ def get_dos_from_task_id( Returns: pymatgen Dos """ - dos_lbl, _ = self._get_delta_table( - "materialsproject-parsed", - "core/electronic-structure/total-dos/", - label="total_dos", - ) - - query = f""" - SELECT * - FROM {dos_lbl} - WHERE identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}' - """ + with status( + f"Fetching the density of states for {task_id}...", + enabled=not self.mute_progress_bars, + ): + dos_lbl, _ = self._get_delta_table( + "materialsproject-parsed", + "core/electronic-structure/total-dos/", + label="total_dos", + ) - if run_type: - rt = RunType(run_type) if isinstance(run_type, str) else run_type - query += f"\nAND run_type='{rt.value}'" - - table = self._query_delta_single(query, label=dos_lbl) - if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0: - if load_projections: - proj_dos_label, _ = self._get_delta_table( - "materialsproject-parsed", - "core/electronic-structure/projected-dos/", - label="dos_projections", - ) - proj_table = self._query_delta_single( - query.replace(dos_lbl, proj_dos_label), label=proj_dos_label - ) - if ( - len(deser_proj := proj_table.to_pylist(maps_as_pydicts="strict")) - > 0 - ): - deser[0]["projected_densities"] = deser_proj[0] - return ElectronicDos(**deser[0]).to_pmg() - raise MPRestError( - f"No DOS data found for {task_id=}" + (f"run_type={rt}" if run_type else "") - ) + query = f""" + SELECT * + FROM {dos_lbl} + WHERE identifier='{str(AlphaID(task_id.split("-")[-1],padlen=8))}' + """ + + if run_type: + rt = RunType(run_type) if isinstance(run_type, str) else run_type + query += f"\nAND run_type='{rt.value}'" + + table = self._query_delta_single(query, label=dos_lbl) + if len(deser := table.to_pylist(maps_as_pydicts="strict")) > 0: + if load_projections: + proj_dos_label, _ = self._get_delta_table( + "materialsproject-parsed", + "core/electronic-structure/projected-dos/", + label="dos_projections", + ) + proj_table = self._query_delta_single( + query.replace(dos_lbl, proj_dos_label), label=proj_dos_label + ) + if ( + len( + deser_proj := proj_table.to_pylist(maps_as_pydicts="strict") + ) + > 0 + ): + deser[0]["projected_densities"] = deser_proj[0] + return ElectronicDos(**deser[0]).to_pmg() + raise MPRestError( + f"No DOS data found for {task_id=}" + + (f" and run_type={rt.value}" if run_type else "") + ) def get_dos_from_material_id( self, material_id: str, load_projections: bool = False @@ -590,17 +617,25 @@ def get_dos_from_material_id( Returns: pymatgen Dos """ - if not ( - dos_doc := self.es_rester.search(material_ids=material_id, fields=["dos"]) + with status( + f"Fetching the density of states for {material_id}...", + enabled=not self.mute_progress_bars, ): - raise MPRestError( - f"No electronic structure data found for material ID {material_id}." - ) + if not ( + dos_doc := self.es_rester.search( + material_ids=material_id, fields=["dos"] + ) + ): + raise MPRestError( + f"No electronic structure data found for material ID {material_id}." + ) - if not (dos_data := dos_doc[0].get("dos")): - raise MPRestError(f"No density of states data found for {material_id}") + if not (dos_data := dos_doc[0].get("dos")): + raise MPRestError(f"No density of states data found for {material_id}") - dos_task_id = (dos_data.model_dump() if self.use_document_model else dos_data)[ - "task_id" - ] - return self.get_dos_from_task_id(dos_task_id, load_projections=load_projections) + dos_task_id = ( + dos_data.model_dump() if self.use_document_model else dos_data + )["task_id"] + return self.get_dos_from_task_id( + dos_task_id, load_projections=load_projections + ) diff --git a/mp_api/client/routes/materials/phonon.py b/mp_api/client/routes/materials/phonon.py index 13240c8b..211100c2 100644 --- a/mp_api/client/routes/materials/phonon.py +++ b/mp_api/client/routes/materials/phonon.py @@ -1,5 +1,6 @@ from __future__ import annotations +import logging from collections import defaultdict from typing import TYPE_CHECKING @@ -8,14 +9,21 @@ from emmet.core.phonon import PhononBS, PhononBSDOSDoc, PhononBSDOSTask, PhononDOS from mp_api.client.core import BaseRester, MPRestError +from mp_api.client.core._display import status from mp_api.client.core.utils import validate_ids from mp_api.client.routes.materials.summary import SummaryRester if TYPE_CHECKING: - from typing import Any + from collections.abc import Callable + from typing import Any, Literal from emmet.core.math import Matrix3D +logger = logging.getLogger(__name__) + +# Order in which phonon methods are tried when the caller doesn't pick one +_METHOD_PREFERENCE = ("pheasy", "dfpt") + class PhononRester(BaseRester): _summary_rester: SummaryRester | None = None @@ -144,22 +152,147 @@ def search( **query_params, ) - def get_bandstructure_from_phonon_id( + def _unsupported( self, - identifier: str, phonon_method: str, - path_type: str | BSPathType = BSPathType.setyawan_curtarolo, - ) -> PhononBS | dict[str, Any]: - """Get the phonon band structure pymatgen object associated with a given phonon ID and phonon method. + what: str, + path_type: BSPathType | None = None, + ) -> str | None: + """Why `phonon_method` can't have this kind of data, or None if it can. + + Known from how the data is produced, so no query is needed: + dfpt band structures only exist for the Setyawan-Curtarolo path, and + only pheasy produces force constants. + + Args: + phonon_method (str) : phonon method + what (str) : kind of data: "band structure", "DOS" or "force constants" + path_type (BSPathType or None) : k-path of a band structure + """ + if ( + what == "band structure" + and phonon_method == "dfpt" + and path_type not in (None, BSPathType.setyawan_curtarolo) + ): + return ( + "dfpt phonon band structures are only available with " + f'path_type="{BSPathType.setyawan_curtarolo.value}".' + ) + if what == "force constants" and phonon_method != "pheasy": + return ( + f"{phonon_method} phonon calculations have no force constants; " + 'use phonon_method="pheasy".' + ) + return None - Arguments: - identifier (str): Phonon ID for the phonon band structure calculation - phonon_method (str): phonon method, i.e. pheasy or dfpt - path_type (BSPathType or str): k-path selection convention for the band structure. + def _phonon_candidates( + self, + material_id: str, + what: str, + phonon_method: str | None = None, + path_type: BSPathType | None = None, + ) -> list[tuple[str, str]]: + """The phonon calculations of a material to take `what` from, in order. + + With `phonon_method` unset, every method the material has data for that + can provide `what`, pheasy first, then dfpt. With it set, only that one: + an explicitly requested method is never replaced by another. + + Args: + material_id (str) : Materials Project ID + what (str) : kind of data: "band structure", "DOS" or "force constants" + phonon_method (str or None) : phonon method, None to choose + path_type (BSPathType or None) : k-path of a band structure Returns: - bandstructure (PhononBS): PhononBS object + list of (phonon method, phonon ID) + + Raises: + MPRestError: if the material has no suitable phonon data. """ + if phonon_method and ( + reason := self._unsupported(phonon_method, what, path_type) + ): + raise MPRestError(reason) + + summary_doc = self.summary_rester.search( + material_ids=material_id, fields=["phonon_IDs"] + ) + phonon_ids = (summary_doc[0].get("phonon_IDs") if summary_doc else None) or {} # type: ignore[union-attr] + available = {method: ids for method, ids in phonon_ids.items() if ids} + if not available: + raise MPRestError(f"No phonon data found for material ID {material_id}.") + + if phonon_method: + if phonon_method not in available: + raise MPRestError( + f"No {phonon_method} phonon data for {material_id} " + f"(available: {', '.join(sorted(available))}). Pass " + f'phonon_method="{sorted(available)[0]}", or leave it unset ' + "to choose automatically." + ) + methods = [phonon_method] + else: + methods = [m for m in _METHOD_PREFERENCE if m in available] + sorted( + m for m in available if m not in _METHOD_PREFERENCE + ) + reasons = {m: self._unsupported(m, what, path_type) for m in methods} + if not (usable := [m for m in methods if not reasons[m]]): + raise MPRestError( + f"No phonon {what} available for {material_id}: " + + " ".join(r for r in reasons.values() if r) + ) + methods = usable + + logger.debug( + f"Using {methods[0]} phonon data for {material_id} " + f"(available: {', '.join(sorted(available))})" + ) + return [(method, available[method][0]) for method in methods] + + @staticmethod + def _first_available( + candidates: list[tuple[str, str]], + fetch: Callable[[str, str], Any], + what: str, + material_id: str, + ) -> tuple[str, str, Any]: + """Fetch `what` from the first candidate that has it. + + Falls through to the next candidate when a calculation has no such + data, and says so, since the data then comes from another method + than usual. + + Args: + candidates (list of tuple) : (phonon method, phonon ID), see `_phonon_candidates` + fetch (callable) : `fetch(phonon_id, phonon_method)`, None if there's no data + what (str) : kind of data, for messages + material_id (str) : Materials Project ID, for messages + + Returns: + tuple of the phonon method, the phonon ID and the data + + Raises: + MPRestError: if no candidate has the data. + """ + for method, phonon_id in candidates: + if (data := fetch(phonon_id, method)) is not None: + if (first := candidates[0])[0] != method: + logger.warning( + f"No {first[0]} phonon {what} for {material_id} ({first[1]}), " + f"using {method} ({phonon_id}) instead." + ) + return method, phonon_id, data + tried = ", ".join(f"{m} {i}" for m, i in candidates) + raise MPRestError(f"No phonon {what} found for {material_id} (tried {tried}).") + + def _fetch_bandstructure( + self, + identifier: str, + phonon_method: str, + path_type: str | BSPathType | None, + ) -> PhononBS | dict[str, Any] | None: + """The band structure, or None if there is none for this calculation.""" ph_bs_lbl, _ = self._get_delta_table( "materialsproject-parsed", "phonon/electronic-structure/bandstructures/", @@ -169,7 +302,7 @@ def get_bandstructure_from_phonon_id( query = f""" SELECT * FROM {ph_bs_lbl} - WHERE identifier='{str(AlphaID(identifier.split("-")[-1],padlen=8))}' + WHERE identifier='{str(AlphaID(identifier.split("-")[-1], padlen=8))}' AND phonon_method='{phonon_method}' """ @@ -181,62 +314,82 @@ def get_bandstructure_from_phonon_id( if deser and deser[0].get("bandstructure") is not None: bs = deser[0]["bandstructure"] return PhononBS(**bs) if self.use_document_model else bs + return None - raise MPRestError( - f"No phonon bandstructure data found for {identifier=} and {phonon_method=}" - + (f" and run_type={path_type}" if path_type else "") - ) - - def get_bandstructure_from_material_id( + def get_bandstructure_from_phonon_id( self, - material_id: str, + identifier: str, phonon_method: str, path_type: str | BSPathType = BSPathType.setyawan_curtarolo, ) -> PhononBS | dict[str, Any]: - """Get the phonon band structure pymatgen object associated with a given material ID and phonon method. + """Get the phonon band structure pymatgen object associated with a given phonon ID and phonon method. Arguments: - material_id (str): Materials Project ID for a material + identifier (str): Phonon ID for the phonon band structure calculation phonon_method (str): phonon method, i.e. pheasy or dfpt path_type (BSPathType or str): k-path selection convention for the band structure. + dfpt band structures only exist for setyawan_curtarolo. Returns: bandstructure (PhononBS): PhononBS object """ - pt: BSPathType = ( - BSPathType(path_type) if isinstance(path_type, str) else path_type - ) - - if not ( - summary_doc := self.summary_rester.search( - material_ids=material_id, fields=["phonon_IDs"] - ) + with status( + f"Fetching the {phonon_method} phonon band structure for {identifier}...", + enabled=not self.mute_progress_bars, ): + bs = self._fetch_bandstructure(identifier, phonon_method, path_type) + if bs is None: raise MPRestError( - f"No phonon bandstructure data found for material ID {material_id}." + f"No phonon bandstructure data found for {identifier=} and {phonon_method=}" + + (f" and path_type={path_type}" if path_type else "") ) + return bs - if phonon_method not in summary_doc[0]["phonon_IDs"]: # type: ignore[arg-type, index] - raise MPRestError( - f"No phonon bandstructure data found for material ID: {material_id} and phonon method: {phonon_method}." - ) - - return self.get_bandstructure_from_phonon_id( - summary_doc[0]["phonon_IDs"][phonon_method][0], phonon_method, pt # type: ignore[arg-type, index] - ) - - def get_dos_from_phonon_id( - self, identifier: str, phonon_method: str - ) -> PhononDOS | dict[str, Any]: - """Get the phonon dos pymatgen object associated with a given phonon ID and phonon method. + def get_bandstructure_from_material_id( + self, + material_id: str, + phonon_method: Literal["pheasy", "dfpt"] | None = None, + path_type: str | BSPathType = BSPathType.setyawan_curtarolo, + ) -> PhononBS | dict[str, Any]: + """Get the phonon band structure pymatgen object associated with a given material ID. Arguments: - identifier (str): Phonon ID for the phonon dos calculation - phonon_method (str): phonon method, i.e. pheasy or dfpt + material_id (str): Materials Project ID for a material + phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default, + the method is chosen from the material's data: pheasy if it has it, + otherwise dfpt. If the pheasy calculation has no band structure, + the dfpt one is used (with a warning). A method passed explicitly + is never replaced. + path_type (BSPathType or str): k-path selection convention for the band structure. + pheasy has all conventions; dfpt only has setyawan_curtarolo. Returns: - dos (PhononDOS): PhononDOS object + bandstructure (PhononBS): PhononBS object + + Raises: + MPRestError: if there's no suitable data. The message names the + methods the material does have data for. """ + pt = BSPathType(path_type) if isinstance(path_type, str) else path_type + with status( + f"Fetching the phonon band structure for {material_id}...", + enabled=not self.mute_progress_bars, + ): + candidates = self._phonon_candidates( + material_id, "band structure", phonon_method, pt + ) + _, _, bs = self._first_available( + candidates, + lambda pid, method: self._fetch_bandstructure(pid, method, pt), + "band structure", + material_id, + ) + return bs + + def _fetch_dos( + self, identifier: str, phonon_method: str + ) -> PhononDOS | dict[str, Any] | None: + """The DOS, or None if there is none for this calculation.""" ph_dos_lbl, _ = self._get_delta_table( "materialsproject-parsed", "phonon/electronic-structure/dos/", @@ -246,7 +399,7 @@ def get_dos_from_phonon_id( query = f""" SELECT * FROM {ph_dos_lbl} - WHERE identifier='{str(AlphaID(identifier.split("-")[-1],padlen=8))}' + WHERE identifier='{str(AlphaID(identifier.split("-")[-1], padlen=8))}' AND phonon_method='{phonon_method}' """ @@ -255,53 +408,66 @@ def get_dos_from_phonon_id( if deser and deser[0].get("dos") is not None: dos = deser[0]["dos"] return PhononDOS(**dos) if self.use_document_model else dos + return None - raise MPRestError( - f"No phonon dos data found for {identifier=} and {phonon_method=}" - ) - - def get_dos_from_material_id( - self, material_id: str, phonon_method: str + def get_dos_from_phonon_id( + self, identifier: str, phonon_method: str ) -> PhononDOS | dict[str, Any]: - """Get the phonon dos pymatgen object associated with a given material ID and phonon method. + """Get the phonon dos pymatgen object associated with a given phonon ID and phonon method. Arguments: - material_id (str): Materials Project ID for a material + identifier (str): Phonon ID for the phonon dos calculation phonon_method (str): phonon method, i.e. pheasy or dfpt Returns: dos (PhononDOS): PhononDOS object """ - if not ( - summary_doc := self.summary_rester.search( - material_ids=material_id, fields=["phonon_IDs"] - ) + with status( + f"Fetching the {phonon_method} phonon DOS for {identifier}...", + enabled=not self.mute_progress_bars, ): + dos = self._fetch_dos(identifier, phonon_method) + if dos is None: raise MPRestError( - f"No phonon dos data found for material ID {material_id}." + f"No phonon dos data found for {identifier=} and {phonon_method=}" ) + return dos - if phonon_method not in summary_doc[0]["phonon_IDs"]: # type: ignore[arg-type, index] - raise MPRestError( - f"No phonon dos data found for material ID: {material_id} and phonon method: {phonon_method}." - ) - - return self.get_dos_from_phonon_id( - summary_doc[0]["phonon_IDs"][phonon_method][0], phonon_method # type: ignore[arg-type, index] - ) - - def get_forceconstants_from_phonon_id( - self, identifier: str, phonon_method: str - ) -> list[list[Matrix3D]]: - """Get the force constants associated with a given phonon ID and phonon method. + def get_dos_from_material_id( + self, + material_id: str, + phonon_method: Literal["pheasy", "dfpt"] | None = None, + ) -> PhononDOS | dict[str, Any]: + """Get the phonon dos pymatgen object associated with a given material ID. Arguments: - identifier (str): Phonon ID for the force constants calculation - phonon_method (str): phonon method, i.e. pheasy or dfpt + material_id (str): Materials Project ID for a material + phonon_method (str or None): phonon method, i.e. pheasy or dfpt. By default, + the method is chosen from the material's data: pheasy if it has it, + otherwise dfpt. If the pheasy calculation has no DOS, the dfpt one + is used (with a warning). A method passed explicitly is never replaced. Returns: - force constants (list[list[Matrix3D]]): force constants + dos (PhononDOS): PhononDOS object + + Raises: + MPRestError: if there's no suitable data. The message names the + methods the material does have data for. """ + with status( + f"Fetching the phonon DOS for {material_id}...", + enabled=not self.mute_progress_bars, + ): + candidates = self._phonon_candidates(material_id, "DOS", phonon_method) + _, _, dos = self._first_available( + candidates, self._fetch_dos, "DOS", material_id + ) + return dos + + def _fetch_forceconstants( + self, identifier: str, phonon_method: str + ) -> list[list[Matrix3D]] | None: + """The force constants, or None if there are none for this calculation.""" ph_fc_lbl, _ = self._get_delta_table( "materialsproject-parsed", "phonon/force-constants/", @@ -311,7 +477,7 @@ def get_forceconstants_from_phonon_id( query = f""" SELECT * FROM {ph_fc_lbl} - WHERE identifier='{str(AlphaID(identifier.split("-")[-1],padlen=8))}' + WHERE identifier='{str(AlphaID(identifier.split("-")[-1], padlen=8))}' AND phonon_method='{phonon_method}' """ @@ -319,10 +485,30 @@ def get_forceconstants_from_phonon_id( deser = table.to_pylist(maps_as_pydicts="strict") if deser and deser[0].get("force_constants") is not None: return deser[0]["force_constants"] + return None - raise MPRestError( - f"No phonon force constants data found for {identifier=} and {phonon_method=}" - ) + def get_forceconstants_from_phonon_id( + self, identifier: str, phonon_method: str + ) -> list[list[Matrix3D]]: + """Get the force constants associated with a given phonon ID and phonon method. + + Arguments: + identifier (str): Phonon ID for the force constants calculation + phonon_method (str): phonon method. Only pheasy calculations have force constants. + + Returns: + force constants (list[list[Matrix3D]]): force constants + """ + with status( + f"Fetching the {phonon_method} force constants for {identifier}...", + enabled=not self.mute_progress_bars, + ): + fcs = self._fetch_forceconstants(identifier, phonon_method) + if fcs is None: + raise MPRestError( + f"No phonon force constants data found for {identifier=} and {phonon_method=}" + ) + return fcs def get_forceconstants_from_material_id( self, material_id: str, phonon_method: str @@ -331,33 +517,32 @@ def get_forceconstants_from_material_id( Arguments: material_id (str): Materials Project ID for a material - phonon_method (str): phonon method, i.e. pheasy or dfpt + phonon_method (str): phonon method. Only pheasy calculations have + force constants; passing dfpt raises an error. Returns: force constants (list[list[Matrix3D]]): force constants + + Raises: + MPRestError: if the method can't have force constants, or the + material has none. """ - if not ( - summary_doc := self.summary_rester.search( - material_ids=material_id, fields=["phonon_IDs"] - ) + with status( + f"Fetching the {phonon_method} force constants for {material_id}...", + enabled=not self.mute_progress_bars, ): - raise MPRestError( - f"No phonon force constants data found for material ID {material_id}." + candidates = self._phonon_candidates( + material_id, "force constants", phonon_method ) - - if phonon_method not in summary_doc[0]["phonon_IDs"]: # type: ignore[arg-type, index] - raise MPRestError( - f"No phonon force constants data found for material ID: {material_id} and phonon method: {phonon_method}." + _, _, fcs = self._first_available( + candidates, self._fetch_forceconstants, "force constants", material_id ) - - return self.get_forceconstants_from_phonon_id( - summary_doc[0]["phonon_IDs"][phonon_method][0], phonon_method # type: ignore[arg-type, index] - ) + return fcs def compute_thermo_quantities( self, material_id: str | None = None, - phonon_method: str | None = None, + phonon_method: Literal["pheasy", "dfpt"] | None = None, identifier: str | None = None, ): """Compute thermodynamical quantities for a given phonon ID or material ID and phonon_method. @@ -365,11 +550,11 @@ def compute_thermo_quantities( Exactly one of `identifier` or `material_id` must be supplied. Arguments: - identifier (str): Phonon ID to calculate quantities for - material_id (str): Materials Project ID to calculate quantities for; the first - phonon ID associated with the requested `phonon_method` for the material - will be used. - phonon_method (str): phonon method, i.e. pheasy or dfpt + identifier (str): Phonon ID to calculate quantities for. Requires `phonon_method`. + material_id (str): Materials Project ID to calculate quantities for. + phonon_method (str): phonon method, i.e. pheasy or dfpt. With `material_id`, + the method is chosen from the material's data (pheasy, then dfpt) + unless given; the first phonon ID of the method is used. Returns: quantities (dict): thermodynamical quantities @@ -384,39 +569,33 @@ def compute_thermo_quantities( use_document_model = self.use_document_model self.use_document_model = False try: - if material_id: - if not ( - summary_doc := self.summary_rester.search( - material_ids=material_id, fields=["phonon_IDs"] - ) - ): - raise MPRestError( - f"No phonon data found for material ID {material_id}." + with status( + f"Computing thermodynamic quantities for {material_id or identifier}...", + enabled=not self.mute_progress_bars, + ): + if material_id: + candidates = self._phonon_candidates( + material_id, "DOS", phonon_method ) - if phonon_method not in summary_doc[0]["phonon_IDs"]: # type: ignore[arg-type, index] - raise MPRestError( - f"No phonon data found for material ID: {material_id} and " - f"phonon method: {phonon_method}." + phonon_method_used, identifier, ph_dos = self._first_available( + candidates, self._fetch_dos, "DOS", material_id ) - identifier = summary_doc[0]["phonon_IDs"][phonon_method][0] # type: ignore[arg-type, index] - - if identifier is None or phonon_method is None: - suffix = ( - f" for {material_id=}" if material_id else f" for {identifier=}" - ) - raise MPRestError( - f"Could not resolve a phonon identifier or method{suffix} " - f"({phonon_method=})." - ) - - ph_dos = self.get_dos_from_phonon_id(identifier, phonon_method) - docs = self.search(identifiers=identifier, phonon_method=phonon_method) - if not docs or not docs[0]: - raise MPRestError("No phonon document found") - - self.use_document_model = True - docs[0]["phonon_dos"] = ph_dos # type: ignore[index] - doc = PhononBSDOSDoc(**docs[0]) # type: ignore[arg-type, index] + phonon_method = phonon_method_used # type: ignore[assignment] + else: + if identifier is None or phonon_method is None: + raise MPRestError( + f"Could not resolve a phonon identifier or method " + f"for {identifier=} ({phonon_method=})." + ) + ph_dos = self.get_dos_from_phonon_id(identifier, phonon_method) + + docs = self.search(identifiers=identifier, phonon_method=phonon_method) + if not docs or not docs[0]: + raise MPRestError("No phonon document found") + + self.use_document_model = True + docs[0]["phonon_dos"] = ph_dos # type: ignore[index] + doc = PhononBSDOSDoc(**docs[0]) # type: ignore[arg-type, index] finally: self.use_document_model = use_document_model # below: same as numpy.linspace(0,800,100) but written out for mypy diff --git a/tests/client/core/test_external.py b/tests/client/core/test_external.py index 97b6e780..f8844823 100644 --- a/tests/client/core/test_external.py +++ b/tests/client/core/test_external.py @@ -673,3 +673,29 @@ def test_quiet_silences_dataset_warnings(tmp_path): warnings.simplefilter("always") dataset[0], dataset[0:2], list(dataset) assert caught == [] + + +# -------------------------------------------------------------------------- +# Tracebacks +# -------------------------------------------------------------------------- + + +def test_call_wrappers_are_hidden_from_tracebacks(): + """IPython, Jupyter and pytest skip frames that set `__tracebackhide__`.""" + + @track_calls + class Thing: + def fail(self): + raise ValueError("boom") + + with pytest.raises(ValueError) as excinfo: + Thing().fail() + + frames = [] + tb = excinfo.value.__traceback__ + while tb is not None: + frames.append(tb.tb_frame) + tb = tb.tb_next + wrappers = [f for f in frames if f.f_code.co_name == "wrapper"] + assert wrappers + assert all(f.f_locals.get("__tracebackhide__") is True for f in wrappers) diff --git a/tests/client/core/test_quiet.py b/tests/client/core/test_quiet.py index 40aeab98..95f188e8 100644 --- a/tests/client/core/test_quiet.py +++ b/tests/client/core/test_quiet.py @@ -9,8 +9,10 @@ import pytest from rich.console import Console +import mp_api.client.contribs._logger # noqa: F401 - import (and its warnings) up front import mp_api.client.core._display as display from mp_api.client import enable_logging, is_quiet, quiet +from mp_api.client.contribs._logger import MPCC_LOGGER from mp_api.client.core._display import mp_warning, print_notice, progress_bar, status from mp_api.client.core.exceptions import MPRestWarning @@ -50,8 +52,6 @@ def emit_everything(): """One of each kind of client output.""" logging.getLogger("mp_api.client.core.client").warning("core warning") logging.getLogger("mp_api.client.core.client").error("core error") - from mp_api.client.contribs._logger import MPCC_LOGGER - MPCC_LOGGER.warning("contribs warning") print_notice("a notice") with progress_bar("a bar", total=2, summary="Did {completed}") as bar: @@ -351,3 +351,127 @@ def test_database_versions_notebook_and_ipython(): assert data["text/html"].startswith("
")
assert "summary" in data["text/html"]
assert "color: #48c78e" in data["text/html"] # current version, green
+
+
+# --------------------------------------------------------------------------
+# status() describes the whole operation
+# --------------------------------------------------------------------------
+
+
+def _summary_shown(buf: io.StringIO) -> bool:
+ return "Did 2" in buf.getvalue()
+
+
+def test_bar_summary_is_printed_outside_a_status(term):
+ with progress_bar("a bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ assert _summary_shown(term)
+
+
+def test_bar_is_not_drawn_inside_a_status(term):
+ """A lookup the client makes for its own purposes shows no bar and no summary."""
+ with status("Fetching the thing..."):
+ with progress_bar("an inner bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ output = term.getvalue()
+ assert "an inner bar" not in output
+ assert not _summary_shown(term)
+ assert "Fetching the thing" in output # the status itself is still shown
+
+
+def test_bar_inside_a_status_still_counts_for_the_caller(term):
+ with status("Fetching the thing..."):
+ with progress_bar("an inner bar", total=3) as bar:
+ bar.update(2)
+ bar.update(1)
+ assert bar.completed == 3
+
+
+def test_bar_inside_a_status_logs_nothing_in_a_pipe(app_handler):
+ display.set_console(Console(file=io.StringIO(), force_terminal=False))
+ try:
+ with status("outer"):
+ with progress_bar("inner", total=1, log="inner message"):
+ pass
+ finally:
+ display.set_console(None)
+ assert [r.getMessage() for r in app_handler] == ["outer"]
+
+
+def test_bar_outside_a_status_logs_in_a_pipe(app_handler):
+ display.set_console(Console(file=io.StringIO(), force_terminal=False))
+ try:
+ with progress_bar("a bar", total=1, log="bar message"):
+ pass
+ finally:
+ display.set_console(None)
+ assert [r.getMessage() for r in app_handler] == ["bar message"]
+
+
+def test_summary_is_back_after_the_status_ends(term):
+ with status("Fetching the thing..."):
+ pass
+ with progress_bar("a bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ assert _summary_shown(term)
+
+
+def test_status_resets_even_if_the_block_raises(term):
+ with pytest.raises(RuntimeError):
+ with status("Fetching the thing..."):
+ raise RuntimeError("boom")
+ with progress_bar("a bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ assert _summary_shown(term)
+
+
+def test_nested_status_logs_nothing_in_a_pipe(app_handler):
+ display.set_console(Console(file=io.StringIO(), force_terminal=False))
+ try:
+ with status("outer"):
+ with status("inner"):
+ pass
+ finally:
+ display.set_console(None)
+ assert [r.getMessage() for r in app_handler] == ["outer"]
+
+
+def test_nested_status_draws_no_second_line(term):
+ with status("outer line"):
+ with status("inner line"):
+ pass
+ assert "inner line" not in term.getvalue()
+
+
+def test_status_in_worker_thread_inherits_the_operation(term):
+ """Threads started through `in_current_context` run inside the operation."""
+ from concurrent.futures import ThreadPoolExecutor
+
+ from mp_api.client.core._external import in_current_context
+
+ def work():
+ with progress_bar("a worker bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+
+ with status("outer"):
+ with ThreadPoolExecutor(1) as pool:
+ pool.submit(in_current_context(work)).result()
+ assert "a worker bar" not in term.getvalue()
+ assert not _summary_shown(term)
+
+
+def test_disabled_status_does_not_define_an_operation(term):
+ with status("muted", enabled=False):
+ with progress_bar("a bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ assert _summary_shown(term)
+
+
+def test_quiet_status_does_not_define_an_operation(term):
+ """In quiet mode nothing is shown anyway, and nothing is left set after it."""
+ with quiet():
+ with status("muted"):
+ pass
+ with progress_bar("a bar", total=2, summary="Did {completed}") as bar:
+ bar.update(2)
+ assert _summary_shown(term)
diff --git a/tests/client/materials/test_electronic_structure_messages.py b/tests/client/materials/test_electronic_structure_messages.py
new file mode 100644
index 00000000..6edc4e1e
--- /dev/null
+++ b/tests/client/materials/test_electronic_structure_messages.py
@@ -0,0 +1,208 @@
+"""Messages and status lines of the electronic structure shortcuts. No network access."""
+
+import io
+import logging
+
+import pytest
+from emmet.core.band_theory import BSPathType
+from rich.console import Console
+
+import mp_api.client.core._display as display
+from mp_api.client.core.exceptions import MPRestError
+from mp_api.client.routes.materials.electronic_structure import (
+ BandStructureRester,
+ DosRester,
+ ElectronicStructureRester,
+)
+
+
+def _summary(bandstructure=None, dos=None):
+ return [{"material_id": "mp-x", "bandstructure": bandstructure, "dos": dos}]
+
+
+@pytest.fixture
+def make(monkeypatch):
+ """A rester whose electronic structure lookup returns `docs`."""
+
+ def build(cls, docs):
+ class FakeES:
+ @staticmethod
+ def search(material_ids, fields):
+ return docs
+
+ rester = cls(api_key="a" * 32, use_document_model=False)
+ monkeypatch.setattr(cls, "es_rester", FakeES())
+ monkeypatch.setattr(
+ rester,
+ "get_bandstructure_from_task_id",
+ lambda *a, **k: "bs",
+ raising=False,
+ )
+ monkeypatch.setattr(
+ rester, "get_dos_from_task_id", lambda *a, **k: "dos", raising=False
+ )
+ return rester
+
+ return build
+
+
+# --- the path types a material has ----------------------------------------------
+
+
+def test_missing_path_type_lists_the_available_ones(make):
+ rester = make(
+ BandStructureRester,
+ _summary(
+ bandstructure={
+ "setyawan_curtarolo": {"task_id": "mp-1"},
+ "hinuma": None,
+ "latimer_munro": {"task_id": "mp-2"},
+ }
+ ),
+ )
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_bandstructure_from_material_id("mp-x", path_type="hinuma")
+ message = str(excinfo.value)
+ assert "No hinuma band structure data found for mp-x" in message
+ assert "available: latimer_munro, setyawan_curtarolo" in message
+
+
+def test_missing_path_type_without_alternatives(make):
+ rester = make(
+ BandStructureRester, _summary(bandstructure={"setyawan_curtarolo": None})
+ )
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_bandstructure_from_material_id("mp-x")
+ assert str(excinfo.value) == (
+ "No setyawan_curtarolo band structure data found for mp-x."
+ )
+
+
+def test_available_path_type_is_fetched(make):
+ rester = make(
+ BandStructureRester,
+ _summary(bandstructure={"hinuma": {"task_id": "mp-1"}}),
+ )
+ assert (
+ rester.get_bandstructure_from_material_id("mp-x", path_type=BSPathType.hinuma)
+ == "bs"
+ )
+
+
+# --- task ID messages ------------------------------------------------------------
+
+
+def _empty_table(monkeypatch, cls):
+ class Empty:
+ @staticmethod
+ def to_pylist(**kwargs):
+ return []
+
+ rester = cls(api_key="a" * 32)
+ monkeypatch.setattr(rester, "_get_delta_table", lambda *a, **k: ("lbl", None))
+ monkeypatch.setattr(rester, "_query_delta_single", lambda *a, **k: Empty())
+ return rester
+
+
+def test_bandstructure_task_id_message_has_separators(monkeypatch):
+ rester = _empty_table(monkeypatch, BandStructureRester)
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_bandstructure_from_task_id(
+ "mp-1", run_type="GGA", path_type="hinuma"
+ )
+ assert str(excinfo.value) == (
+ "No bandstructure data found for task_id='mp-1' and run_type=GGA "
+ "and path_type=hinuma"
+ )
+
+
+def test_bandstructure_task_id_message_without_options(monkeypatch):
+ rester = _empty_table(monkeypatch, BandStructureRester)
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_bandstructure_from_task_id("mp-1")
+ assert str(excinfo.value) == "No bandstructure data found for task_id='mp-1'"
+
+
+def test_dos_task_id_message_has_separator(monkeypatch):
+ rester = _empty_table(monkeypatch, DosRester)
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_dos_from_task_id("mp-1", run_type="GGA")
+ assert str(excinfo.value) == "No DOS data found for task_id='mp-1' and run_type=GGA"
+
+
+# --- status lines ----------------------------------------------------------------
+
+
+@pytest.fixture
+def caplog():
+ """Records that reach the application's root handlers (a plain recorder:
+ pytest's own handlers would see the client's records more than once)."""
+ records: list[logging.LogRecord] = []
+
+ class Recorder(logging.Handler):
+ def emit(self, record):
+ records.append(record)
+
+ root = logging.getLogger()
+ handler = Recorder(level=logging.DEBUG)
+ root.addHandler(handler)
+ old_level = root.level
+ root.setLevel(logging.DEBUG)
+ yield records
+ root.removeHandler(handler)
+ root.setLevel(old_level)
+
+
+def _statuses(rester_call, records):
+ display.set_console(Console(file=io.StringIO(), force_terminal=False))
+ try:
+ rester_call()
+ finally:
+ display.set_console(None)
+ return [r.getMessage() for r in records if r.name == "mp_api.client"]
+
+
+def test_bandstructure_shows_one_status_line(make, caplog):
+ rester = make(
+ BandStructureRester, _summary(bandstructure={"hinuma": {"task_id": "mp-1"}})
+ )
+ messages = _statuses(
+ lambda: rester.get_bandstructure_from_material_id("mp-x", path_type="hinuma"),
+ caplog,
+ )
+ assert messages == ["Fetching the hinuma band structure for mp-x..."]
+
+
+def test_uniform_bandstructure_status_line(make, caplog):
+ rester = make(BandStructureRester, _summary(dos={"total": {}, "task_id": "mp-1"}))
+ messages = _statuses(
+ lambda: rester.get_bandstructure_from_material_id("mp-x", line_mode=False),
+ caplog,
+ )
+ assert messages == ["Fetching the uniform band structure for mp-x..."]
+
+
+def test_dos_shows_one_status_line(make, caplog):
+ rester = make(DosRester, _summary(dos={"task_id": "mp-1"}))
+ messages = _statuses(lambda: rester.get_dos_from_material_id("mp-x"), caplog)
+ assert messages == ["Fetching the density of states for mp-x..."]
+
+
+def test_task_id_calls_show_their_own_status_line(monkeypatch, caplog):
+ rester = _empty_table(monkeypatch, DosRester)
+
+ def call():
+ with pytest.raises(MPRestError):
+ rester.get_dos_from_task_id("mp-1")
+
+ assert _statuses(call, caplog) == ["Fetching the density of states for mp-1..."]
+
+
+def test_muted_progress_bars_show_no_status_line(make, caplog):
+ rester = make(DosRester, _summary(dos={"task_id": "mp-1"}))
+ rester.mute_progress_bars = True
+ assert _statuses(lambda: rester.get_dos_from_material_id("mp-x"), caplog) == []
+
+
+def test_es_rester_is_unaffected():
+ assert ElectronicStructureRester.suffix == "materials/electronic_structure"
diff --git a/tests/client/materials/test_phonon.py b/tests/client/materials/test_phonon.py
index ef8545b6..d225776e 100644
--- a/tests/client/materials/test_phonon.py
+++ b/tests/client/materials/test_phonon.py
@@ -42,13 +42,56 @@ def test_get_bandstructure_from_material_id(use_document_model):
with pytest.raises(
MPRestError,
- match="No phonon bandstructure data found for material ID mp-0",
+ match="No phonon data found for material ID mp-0",
):
rester.get_bandstructure_from_material_id(
material_id="mp-0", phonon_method="dfpt"
)
+@requires_api_key
+@pytest.mark.parametrize("use_document_model", [True, False])
+def test_phonon_method_is_chosen_from_the_data(use_document_model):
+ """Most materials only have pheasy data, a few only dfpt, a few both."""
+ rester = PhononRester(use_document_model=use_document_model)
+ expected = PhononBS if use_document_model else dict
+
+ # pheasy only
+ assert isinstance(
+ rester.get_bandstructure_from_material_id("mp-aaahikjt"), expected
+ )
+ # dfpt only
+ assert isinstance(rester.get_bandstructure_from_material_id("mp-2172"), expected)
+ # both: either can be asked for
+ assert isinstance(rester.get_bandstructure_from_material_id("mp-149"), expected)
+ assert isinstance(
+ rester.get_bandstructure_from_material_id("mp-149", phonon_method="dfpt"),
+ expected,
+ )
+
+ # a method that was asked for is never replaced by another
+ with pytest.raises(
+ MPRestError, match=r"No dfpt phonon data for mp-aaahikjt \(available: pheasy\)"
+ ):
+ rester.get_bandstructure_from_material_id("mp-aaahikjt", phonon_method="dfpt")
+
+
+@requires_api_key
+def test_phonon_bandstructure_path_types():
+ rester = PhononRester()
+
+ # pheasy should have all k-path conventions
+ for path_type in ("setyawan_curtarolo", "hinuma", "latimer_munro"):
+ bs = rester.get_bandstructure_from_material_id(
+ "mp-aaahikjt", path_type=path_type
+ )
+ assert isinstance(bs, PhononBS)
+
+ # dfpt only has one
+ with pytest.raises(MPRestError, match="only available with path_type"):
+ rester.get_bandstructure_from_material_id("mp-2172", path_type="hinuma")
+
+
@requires_api_key
@pytest.mark.parametrize("use_document_model", [True, False])
def test_get_dos_from_material_id(use_document_model):
@@ -57,9 +100,14 @@ def test_get_dos_from_material_id(use_document_model):
dos = rester.get_dos_from_material_id(material_id="mp-149", phonon_method="dfpt")
assert isinstance(dos, PhononDOS if use_document_model else dict)
+ # the method defaults to what the material has
+ for material_id in ("mp-aaahikjt", "mp-2172", "mp-149"):
+ dos = rester.get_dos_from_material_id(material_id=material_id)
+ assert isinstance(dos, PhononDOS if use_document_model else dict)
+
with pytest.raises(
MPRestError,
- match="No phonon dos data found for material ID mp-0",
+ match="No phonon data found for material ID mp-0",
):
rester.get_dos_from_material_id(material_id="mp-0", phonon_method="dfpt")
@@ -77,10 +125,17 @@ def test_get_forceconstants_from_material_id(use_document_model):
with pytest.raises(
MPRestError,
- match="No phonon force constants data found for material ID mp-0",
+ match="No phonon data found for material ID mp-0",
):
rester.get_forceconstants_from_material_id(
- material_id="mp-0", phonon_method="dfpt"
+ material_id="mp-0", phonon_method="pheasy"
+ )
+
+ with pytest.raises(
+ MPRestError, match="dfpt phonon calculations have no force constants"
+ ):
+ rester.get_forceconstants_from_material_id(
+ material_id="mp-149", phonon_method="dfpt"
)
@@ -92,13 +147,17 @@ def test_phonon_thermo(use_document_model):
with pytest.raises(MPRestError, match="No phonon data found for material ID mp-0"):
rester.compute_thermo_quantities(material_id="mp-0", phonon_method="dfpt")
- thermo_props = rester.compute_thermo_quantities(
- material_id="mp-149", phonon_method="dfpt"
- )
-
# Default set in the method
num_vals = 100
- assert all(
- isinstance(v, list) and len(v) == num_vals for v in thermo_props.values()
- )
+ # with and without choosing the method (pheasy-only, dfpt-only, both)
+ for kwargs in (
+ {"material_id": "mp-149", "phonon_method": "dfpt"},
+ {"material_id": "mp-149"},
+ {"material_id": "mp-aaahikjt"},
+ {"material_id": "mp-2172"},
+ ):
+ thermo_props = rester.compute_thermo_quantities(**kwargs)
+ assert all(
+ isinstance(v, list) and len(v) == num_vals for v in thermo_props.values()
+ )
diff --git a/tests/client/materials/test_phonon_methods.py b/tests/client/materials/test_phonon_methods.py
new file mode 100644
index 00000000..e76a4183
--- /dev/null
+++ b/tests/client/materials/test_phonon_methods.py
@@ -0,0 +1,311 @@
+"""Choosing the phonon method for a material. No network access.
+
+The summary lookup (`phonon_IDs`) and the S3 reads are replaced, so these test
+the choice of method, the fall-through and the messages.
+"""
+
+import logging
+
+import pytest
+from emmet.core.band_theory import BSPathType
+
+from mp_api.client.core.exceptions import MPRestError
+from mp_api.client.routes.materials.phonon import PhononRester
+
+PHEASY_ONLY = {"pheasy": ["aaahikjt"]}
+DFPT_ONLY = {"dfpt": ["aaaaadfo"]}
+BOTH = {"dfpt": ["aaaaaaft"], "pheasy": ["aaaeguxu"]}
+
+
+class Calls:
+ """What the fake S3 reads were asked for, and what they hold."""
+
+ def __init__(self):
+ self.fetched: list[tuple[str, str, str]] = [] # (kind, phonon id, method)
+ self.missing: set[tuple[str, str, str]] = set() # reads that find no row
+
+
+@pytest.fixture
+def make(monkeypatch):
+ """Build a `PhononRester` for a material with the given `phonon_IDs`."""
+
+ def build(phonon_ids, *, missing=()):
+ calls = Calls()
+ calls.missing = set(missing)
+
+ rester = PhononRester(api_key="a" * 32, use_document_model=False)
+
+ class FakeSummary:
+ @staticmethod
+ def search(material_ids, fields):
+ return [{"material_id": material_ids, "phonon_IDs": phonon_ids}]
+
+ monkeypatch.setattr(PhononRester, "summary_rester", FakeSummary())
+
+ def fetch(kind):
+ def fake(identifier, phonon_method, *args):
+ calls.fetched.append((kind, identifier, phonon_method))
+ if (kind, identifier, phonon_method) in calls.missing:
+ return None
+ return {"kind": kind, "id": identifier, "method": phonon_method}
+
+ return fake
+
+ monkeypatch.setattr(rester, "_fetch_bandstructure", fetch("bs"))
+ monkeypatch.setattr(rester, "_fetch_dos", fetch("dos"))
+ monkeypatch.setattr(rester, "_fetch_forceconstants", fetch("fc"))
+ return rester, calls
+
+ return build
+
+
+# --- choosing the method ---------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+ "phonon_ids, method",
+ [(PHEASY_ONLY, "pheasy"), (DFPT_ONLY, "dfpt"), (BOTH, "pheasy")],
+)
+def test_default_method_follows_the_data(make, phonon_ids, method):
+ rester, calls = make(phonon_ids)
+ assert rester.get_dos_from_material_id("mp-x")["method"] == method
+ assert rester.get_bandstructure_from_material_id("mp-x")["method"] == method
+ assert {m for *_, m in calls.fetched} == {method}
+
+
+def test_explicit_method_is_honoured(make):
+ rester, _ = make(BOTH)
+ assert rester.get_dos_from_material_id("mp-x", "dfpt")["method"] == "dfpt"
+ assert rester.get_dos_from_material_id("mp-x", "pheasy")["method"] == "pheasy"
+
+
+def test_method_can_still_be_passed_positionally(make):
+ rester, _ = make(BOTH)
+ assert rester.get_dos_from_material_id("mp-x", "dfpt")["id"] == "aaaaaaft"
+ assert rester.get_bandstructure_from_material_id("mp-x", "dfpt")["method"] == "dfpt"
+
+
+def test_choice_is_logged_at_debug(make, caplog):
+ rester, _ = make(BOTH)
+ with caplog.at_level(logging.DEBUG, logger="mp_api.client"):
+ rester.get_dos_from_material_id("mp-x")
+ record = next(r for r in caplog.records if "Using pheasy" in r.getMessage())
+ assert record.levelno == logging.DEBUG
+ assert "available: dfpt, pheasy" in record.getMessage()
+
+
+# --- explicit methods never fall through -----------------------------------------
+
+
+def test_explicit_method_missing_names_what_is_available(make):
+ rester, calls = make(PHEASY_ONLY)
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_bandstructure_from_material_id("mp-x", "dfpt")
+ message = str(excinfo.value)
+ assert "No dfpt phonon data for mp-x" in message
+ assert "available: pheasy" in message
+ assert 'phonon_method="pheasy"' in message
+ assert calls.fetched == []
+
+
+def test_explicit_method_does_not_fall_through_on_a_missing_row(make):
+ rester, calls = make(BOTH, missing={("dos", "aaaeguxu", "pheasy")})
+ with pytest.raises(MPRestError, match="No phonon DOS found for mp-x"):
+ rester.get_dos_from_material_id("mp-x", "pheasy")
+ assert [m for *_, m in calls.fetched] == ["pheasy"]
+
+
+# --- falling through to another method (default method only) ---------------------
+
+
+def test_missing_row_falls_through_with_a_warning(make, caplog):
+ rester, calls = make(BOTH, missing={("bs", "aaaeguxu", "pheasy")})
+ with caplog.at_level(logging.INFO, logger="mp_api.client"):
+ bs = rester.get_bandstructure_from_material_id("mp-x")
+ assert bs["method"] == "dfpt"
+ assert [m for *_, m in calls.fetched] == ["pheasy", "dfpt"]
+
+ record = next(r for r in caplog.records if "using dfpt" in r.getMessage())
+ assert record.levelno == logging.WARNING
+ assert "No pheasy phonon band structure for mp-x (aaaeguxu)" in record.getMessage()
+ assert "aaaaaaft" in record.getMessage()
+
+
+def test_no_warning_without_a_fall_through(make, caplog):
+ rester, _ = make(BOTH)
+ with caplog.at_level(logging.INFO, logger="mp_api.client"):
+ rester.get_dos_from_material_id("mp-x")
+ assert not [r for r in caplog.records if r.levelno >= logging.WARNING]
+
+
+def test_all_candidates_missing_lists_what_was_tried(make):
+ rester, _ = make(
+ BOTH, missing={("dos", "aaaeguxu", "pheasy"), ("dos", "aaaaaaft", "dfpt")}
+ )
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_dos_from_material_id("mp-x")
+ assert "tried pheasy aaaeguxu, dfpt aaaaaaft" in str(excinfo.value)
+
+
+# --- path types ------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("path_type", ["hinuma", BSPathType.latimer_munro])
+def test_dfpt_has_only_one_path_type(make, path_type):
+ rester, calls = make(DFPT_ONLY)
+ with pytest.raises(MPRestError, match="only available with path_type"):
+ rester.get_bandstructure_from_material_id("mp-x", path_type=path_type)
+ assert calls.fetched == []
+
+
+def test_explicit_dfpt_with_other_path_type_fails_before_any_lookup(make):
+ rester, calls = make(BOTH)
+ with pytest.raises(MPRestError, match="setyawan_curtarolo"):
+ rester.get_bandstructure_from_material_id(
+ "mp-x", "dfpt", path_type=BSPathType.hinuma
+ )
+ assert calls.fetched == []
+
+
+def test_default_method_skips_dfpt_for_other_path_types(make):
+ rester, calls = make(BOTH, missing={("bs", "aaaeguxu", "pheasy")})
+ with pytest.raises(MPRestError, match="No phonon band structure found"):
+ rester.get_bandstructure_from_material_id("mp-x", path_type="hinuma")
+ # never silently a different k-path
+ assert [m for *_, m in calls.fetched] == ["pheasy"]
+
+
+def test_default_method_uses_pheasy_for_other_path_types(make):
+ rester, _ = make(BOTH)
+ bs = rester.get_bandstructure_from_material_id("mp-x", path_type="hinuma")
+ assert bs["method"] == "pheasy"
+
+
+def test_path_type_is_not_a_constraint_on_the_dos(make):
+ rester, _ = make(DFPT_ONLY)
+ assert rester.get_dos_from_material_id("mp-x")["method"] == "dfpt"
+
+
+# --- materials without usable data -----------------------------------------------
+
+
+@pytest.mark.parametrize("phonon_ids", [None, {}, {"dfpt": [], "pheasy": []}])
+def test_material_without_phonon_data(make, phonon_ids):
+ """Used to raise TypeError for `None`."""
+ rester, calls = make(phonon_ids)
+ with pytest.raises(MPRestError, match="No phonon data found for material ID mp-x"):
+ rester.get_dos_from_material_id("mp-x")
+ with pytest.raises(MPRestError, match="No phonon data found for material ID mp-x"):
+ rester.get_bandstructure_from_material_id("mp-x", "pheasy")
+ assert calls.fetched == []
+
+
+def test_unknown_material(monkeypatch):
+ rester = PhononRester(api_key="a" * 32, use_document_model=False)
+
+ class Empty:
+ @staticmethod
+ def search(material_ids, fields):
+ return []
+
+ monkeypatch.setattr(PhononRester, "summary_rester", Empty())
+ with pytest.raises(MPRestError, match="No phonon data found for material ID mp-0"):
+ rester.get_dos_from_material_id("mp-0")
+
+
+# --- force constants -------------------------------------------------------------
+
+
+def test_force_constants_from_dfpt_fail_before_any_lookup(make):
+ rester, calls = make(BOTH)
+ with pytest.raises(MPRestError) as excinfo:
+ rester.get_forceconstants_from_material_id("mp-x", "dfpt")
+ assert "no force constants" in str(excinfo.value)
+ assert 'phonon_method="pheasy"' in str(excinfo.value)
+ assert calls.fetched == []
+
+
+def test_force_constants_come_from_pheasy(make):
+ rester, _ = make(BOTH)
+ assert rester.get_forceconstants_from_material_id("mp-x", "pheasy")["id"] == (
+ "aaaeguxu"
+ )
+
+
+def test_force_constants_of_a_dfpt_only_material(make):
+ rester, _ = make(DFPT_ONLY)
+ with pytest.raises(MPRestError, match="No pheasy phonon data for mp-x"):
+ rester.get_forceconstants_from_material_id("mp-x", "pheasy")
+
+
+# --- thermo quantities -----------------------------------------------------------
+
+
+def test_thermo_quantities_resolve_the_method(make, monkeypatch):
+ rester, calls = make(PHEASY_ONLY)
+ seen = {}
+
+ def fake_search(identifiers, phonon_method):
+ seen.update(identifiers=identifiers, phonon_method=phonon_method)
+ return [{"identifier": identifiers}]
+
+ class FakeDoc:
+ def __init__(self, **kwargs):
+ seen["doc"] = kwargs
+
+ def compute_thermo_quantities(self, temps):
+ return {"temps": temps}
+
+ monkeypatch.setattr(rester, "search", fake_search)
+ monkeypatch.setattr("mp_api.client.routes.materials.phonon.PhononBSDOSDoc", FakeDoc)
+
+ assert len(rester.compute_thermo_quantities(material_id="mp-x")["temps"]) == 100
+ assert seen["identifiers"] == "aaahikjt"
+ assert seen["phonon_method"] == "pheasy"
+ assert rester.use_document_model is False # restored
+
+
+def test_thermo_quantities_need_a_method_with_an_identifier(make):
+ rester, _ = make(BOTH)
+ with pytest.raises(MPRestError, match="Could not resolve"):
+ rester.compute_thermo_quantities(identifier="aaaeguxu")
+
+
+# --- MPRester shortcuts ----------------------------------------------------------
+
+
+@pytest.fixture
+def mpr(monkeypatch):
+ from mp_api.client import MPRester
+ from mp_api.client.core.client import _Rester
+
+ monkeypatch.setattr(
+ _Rester, "_get_heartbeat_info", staticmethod(lambda ep: ("2026.04.13", []))
+ )
+ monkeypatch.setattr(MPRester, "get_emmet_version", staticmethod(lambda ep: None))
+ return MPRester(api_key="a" * 32)
+
+
+def test_mprester_shortcuts_pass_everything_through(mpr, monkeypatch):
+ seen = {}
+
+ def bs(self, material_id, phonon_method=None, path_type=None):
+ seen["bs"] = (material_id, phonon_method, path_type)
+ return "bs"
+
+ def dos(self, material_id, phonon_method=None):
+ seen["dos"] = (material_id, phonon_method)
+ return "dos"
+
+ monkeypatch.setattr(PhononRester, "get_bandstructure_from_material_id", bs)
+ monkeypatch.setattr(PhononRester, "get_dos_from_material_id", dos)
+
+ assert mpr.get_phonon_bandstructure_by_material_id("mp-x") == "bs"
+ assert seen["bs"] == ("mp-x", None, BSPathType.setyawan_curtarolo)
+ mpr.get_phonon_bandstructure_by_material_id("mp-x", "dfpt", "hinuma")
+ assert seen["bs"] == ("mp-x", "dfpt", "hinuma")
+
+ assert mpr.get_phonon_dos_by_material_id("mp-x") == "dos"
+ assert seen["dos"] == ("mp-x", None)
+ mpr.get_phonon_dos_by_material_id("mp-x", phonon_method="pheasy")
+ assert seen["dos"] == ("mp-x", "pheasy")
diff --git a/tests/client/test_mprester.py b/tests/client/test_mprester.py
index f487f578..7f217303 100644
--- a/tests/client/test_mprester.py
+++ b/tests/client/test_mprester.py
@@ -613,11 +613,24 @@ def test_get_ion_entries(self, mpr):
assert np.allclose(so4_two_minus.energy, solid_energy + 5.542, atol=1e-3)
def test_get_phonon_data_by_material_id(self, mpr):
- bs = mpr.get_phonon_bandstructure_by_material_id("mp-2172")
+ # dfpt only, pheasy only (most materials), and both
+ for material_id in ("mp-2172", "mp-aaahikjt", "mp-149"):
+ bs = mpr.get_phonon_bandstructure_by_material_id(material_id)
+ assert isinstance(bs, PhononBS)
+
+ dos = mpr.get_phonon_dos_by_material_id(material_id)
+ assert isinstance(dos, PhononDOS)
+
+ bs = mpr.get_phonon_bandstructure_by_material_id(
+ "mp-aaahikjt", path_type="hinuma"
+ )
+ assert isinstance(bs, PhononBS)
+
+ bs = mpr.get_phonon_bandstructure_by_material_id("mp-149", phonon_method="dfpt")
assert isinstance(bs, PhononBS)
- dos = mpr.get_phonon_dos_by_material_id("mp-2172")
- assert isinstance(dos, PhononDOS)
+ with pytest.raises(MPRestError, match="No dfpt phonon data for mp-aaahikjt"):
+ mpr.get_phonon_dos_by_material_id("mp-aaahikjt", phonon_method="dfpt")
def test_get_charge_density_from_material_id(self, mpr):
chgcar = mpr.get_charge_density_from_material_id("mp-149")