/
mprester.py
1449 lines (1264 loc) · 59.6 KB
/
mprester.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
from __future__ import annotations
import itertools
import warnings
from functools import cache, lru_cache
from json import loads
from os import environ
from typing import Literal
from emmet.core.electronic_structure import BSPathType
from emmet.core.mpid import MPID
from emmet.core.settings import EmmetSettings
from emmet.core.tasks import TaskDoc
from emmet.core.vasp.calc_types import CalcType
from packaging import version
from pymatgen.analysis.phase_diagram import PhaseDiagram
from pymatgen.analysis.pourbaix_diagram import IonEntry
from pymatgen.core import SETTINGS, Element, Structure
from pymatgen.core.ion import Ion
from pymatgen.entries.computed_entries import ComputedStructureEntry
from pymatgen.io.vasp import Chgcar
from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
from requests import Session, get
from mp_api.client.core import BaseRester, MPRestError
from mp_api.client.core.settings import MAPIClientSettings
from mp_api.client.core.utils import validate_ids
from mp_api.client.routes import GeneralStoreRester, MessagesRester, UserSettingsRester
from mp_api.client.routes.materials import (
AbsorptionRester,
AlloysRester,
BandStructureRester,
BondsRester,
ChargeDensityRester,
ChemenvRester,
DielectricRester,
DOIRester,
DosRester,
ElasticityRester,
ElectrodeRester,
ElectronicStructureRester,
EOSRester,
FermiRester,
GrainBoundaryRester,
MagnetismRester,
OxidationStatesRester,
PhononRester,
PiezoRester,
ProvenanceRester,
RobocrysRester,
SimilarityRester,
SubstratesRester,
SummaryRester,
SurfacePropertiesRester,
SynthesisRester,
TaskRester,
ThermoRester,
XASRester,
)
from mp_api.client.routes.materials.materials import MaterialsRester
from mp_api.client.routes.molecules import MoleculeRester
_DEPRECATION_WARNING = (
"MPRester is being modernized. Please use the new method suggested and "
"read more about these changes at https://docs.materialsproject.org/api. The current "
"methods will be retained until at least January 2022 for backwards compatibility."
)
_EMMET_SETTINGS = EmmetSettings()
_MAPI_SETTINGS = MAPIClientSettings()
DEFAULT_API_KEY = environ.get("MP_API_KEY", None)
DEFAULT_ENDPOINT = environ.get("MP_API_ENDPOINT", "https://api.materialsproject.org/")
class MPRester:
"""Access the new Materials Project API."""
# Type hints for all routes
# To re-generate this list, use:
# for rester in MPRester()._all_resters:
# print(f"{rester.suffix.replace('/', '_')}: {rester.__class__.__name__}")
# Materials
eos: EOSRester
materials: MaterialsRester
similarity: SimilarityRester
tasks: TaskRester
xas: XASRester
fermi: FermiRester
grain_boundary: GrainBoundaryRester
substrates: SubstratesRester
surface_properties: SurfacePropertiesRester
phonon: PhononRester
elasticity: ElasticityRester
thermo: ThermoRester
dielectric: DielectricRester
piezoelectric: PiezoRester
magnetism: MagnetismRester
summary: SummaryRester
robocrys: RobocrysRester
synthesis: SynthesisRester
insertion_electrodes: ElectrodeRester
charge_density: ChargeDensityRester
electronic_structure: ElectronicStructureRester
electronic_structure_bandstructure: BandStructureRester
electronic_structure_dos: DosRester
oxidation_states: OxidationStatesRester
provenance: ProvenanceRester
bonds: BondsRester
alloys: AlloysRester
absorption: AbsorptionRester
chemenv: ChemenvRester
# Molecules
molecules: MoleculeRester
# Generic
doi: DOIRester
_user_settings: UserSettingsRester
_general_store: GeneralStoreRester
_messages: MessagesRester
def __init__(
self,
api_key: str | None = None,
endpoint: str = DEFAULT_ENDPOINT,
notify_db_version: bool = False,
include_user_agent: bool = True,
monty_decode: bool = True,
use_document_model: bool = True,
session: Session = None,
headers: dict = None,
mute_progress_bars: bool = _MAPI_SETTINGS.MUTE_PROGRESS_BARS,
):
"""Args:
api_key (str): A String API key for accessing the MaterialsProject
REST interface. Please obtain your API key at
https://next-gen.materialsproject.org/api. If this is None,
the code will check if there is a "MP_API_KEY" setting.
If so, it will use that environment variable. This makes
easier for heavy users to simply add this environment variable to
their setups and MPRester can then be called without any arguments.
endpoint (str): Url of endpoint to access the MaterialsProject REST
interface. Defaults to the standard Materials Project REST
address at "https://api.materialsproject.org", but
can be changed to other urls implementing a similar interface.
notify_db_version (bool): If True, the current MP database version will
be retrieved and logged locally in the ~/.mprester.log.yaml. If the database
version changes, you will be notified. The current database version is
also printed on instantiation. These local logs are not sent to
materialsproject.org and are not associated with your API key, so be
aware that a notification may not be presented if you run MPRester
from multiple computing environments.
include_user_agent (bool): If True, will include a user agent with the
HTTP request including information on pymatgen and system version
making the API request. This helps MP support pymatgen users, and
is similar to what most web browsers send with each page request.
Set to False to disable the user agent.
monty_decode: Decode the data using monty into python objects
use_document_model: If False, skip the creating the document model and return data
as a dictionary. This can be simpler to work with but bypasses data validation
and will not give auto-complete for available fields.
session (Session): Session object to use. By default (None), the client will create one.
headers (dict): Custom headers for localhost connections.
mute_progress_bars (bool): Whether to mute progress bars.
"""
# SETTINGS tries to read API key from ~/.config/.pmgrc.yaml
api_key = api_key or DEFAULT_API_KEY or SETTINGS.get("PMG_MAPI_KEY")
if api_key and len(api_key) != 32:
raise ValueError(
"Please use a new API key from https://materialsproject.org/api "
"Keys for the new API are 32 characters, whereas keys for the legacy "
"API are 16 characters."
)
self.api_key = api_key
self.endpoint = endpoint
self.headers = headers or {}
self.session = session or BaseRester._create_session(
api_key=self.api_key,
include_user_agent=include_user_agent,
headers=self.headers,
)
self.use_document_model = use_document_model
self.monty_decode = monty_decode
self.mute_progress_bars = mute_progress_bars
self._contribs = None
self._deprecated_attributes = [
"eos",
"similarity",
"tasks",
"xas",
"fermi",
"grain_boundary",
"substrates",
"surface_properties",
"phonon",
"elasticity",
"thermo",
"dielectric",
"piezoelectric",
"magnetism",
"summary",
"robocrys",
"synthesis",
"insertion_electrodes",
"charge_density",
"electronic_structure",
"electronic_structure_bandstructure",
"electronic_structure_dos",
"oxidation_states",
"provenance",
"bonds",
"alloys",
"absorption",
"chemenv",
]
# Check if emmet version of server is compatible
emmet_version = MPRester.get_emmet_version(self.endpoint)
if version.parse(emmet_version.base_version) < version.parse(
_MAPI_SETTINGS.MIN_EMMET_VERSION
):
warnings.warn(
"The installed version of the mp-api client may not be compatible with the API server. "
"Please install a previous version if any problems occur."
)
if notify_db_version:
raise NotImplementedError("This has not yet been implemented.")
if not self.endpoint.endswith("/"):
self.endpoint += "/"
# Dynamically set rester attributes.
# First, materials and molecules top level resters are set.
# Nested rested are then setup to be loaded dynamically with custom __getattr__ functions.
self._all_resters = []
# Get all rester classes
for _cls in BaseRester.__subclasses__():
sub_resters = _cls.__subclasses__()
if sub_resters:
self._all_resters.extend(sub_resters)
else:
self._all_resters.append(_cls)
# Instantiate top level molecules and materials resters and set them as attributes
core_suffix = ["molecules/core", "materials/core"]
core_resters = {
cls.suffix.split("/")[0]: cls(
api_key=api_key,
endpoint=endpoint,
include_user_agent=include_user_agent,
session=self.session,
monty_decode=monty_decode,
use_document_model=use_document_model,
headers=self.headers,
mute_progress_bars=self.mute_progress_bars,
)
for cls in self._all_resters
if cls.suffix in core_suffix
}
# Set remaining top level resters, or get an attribute-class name mapping
# for all sub-resters
_sub_rester_suffix_map = {"materials": {}, "molecules": {}}
for cls in self._all_resters:
if cls.suffix not in core_suffix:
suffix_split = cls.suffix.split("/")
if len(suffix_split) == 1:
rester = cls(
api_key=api_key,
endpoint=endpoint,
include_user_agent=include_user_agent,
session=self.session,
monty_decode=monty_decode
if cls not in [TaskRester, ProvenanceRester] # type: ignore
else False, # Disable monty decode on nested data which may give errors
use_document_model=use_document_model,
headers=self.headers,
mute_progress_bars=self.mute_progress_bars,
) # type: BaseRester
setattr(
self,
suffix_split[0],
rester,
)
else:
attr = "_".join(suffix_split[1:])
if "materials" in suffix_split:
_sub_rester_suffix_map["materials"][attr] = cls
elif "molecules" in suffix_split:
_sub_rester_suffix_map["molecules"][attr] = cls
# Allow lazy loading of nested resters under materials and molecules using custom __getattr__ methods
def __core_custom_getattr(_self, _attr, _rester_map):
if _attr in _rester_map:
cls = _rester_map[_attr]
rester = cls(
api_key=api_key,
endpoint=endpoint,
include_user_agent=include_user_agent,
session=self.session,
monty_decode=monty_decode
if cls not in [TaskRester, ProvenanceRester] # type: ignore
else False, # Disable monty decode on nested data which may give errors
use_document_model=use_document_model,
headers=self.headers,
mute_progress_bars=self.mute_progress_bars,
) # type: BaseRester
setattr(
_self,
_attr,
rester,
)
return rester
else:
raise AttributeError(
f"{_self.__class__.__name__!r} object has no attribute {attr!r}"
)
def __materials_getattr__(_self, attr):
_rester_map = _sub_rester_suffix_map["materials"]
rester = __core_custom_getattr(_self, attr, _rester_map)
return rester
def __molecules_getattr__(_self, attr):
_rester_map = _sub_rester_suffix_map["molecules"]
rester = __core_custom_getattr(_self, attr, _rester_map)
return rester
MaterialsRester.__getattr__ = __materials_getattr__
MoleculeRester.__getattr__ = __molecules_getattr__
for attr, rester in core_resters.items():
setattr(
self,
attr,
rester,
)
@property
def contribs(self):
if self._contribs is None:
try:
from mpcontribs.client import Client
self._contribs = Client(
self.api_key, headers=self.headers, session=self.session
)
except ImportError:
self._contribs = None
warnings.warn(
"mpcontribs-client not installed. "
"Install the package to query MPContribs data, or construct pourbaix diagrams: "
"'pip install mpcontribs-client'"
)
except Exception as error:
self._contribs = None
warnings.warn(f"Problem loading MPContribs client: {error}")
return self._contribs
def __enter__(self):
"""Support for "with" context."""
return self
def __exit__(self, exc_type, exc_val, exc_tb):
"""Support for "with" context."""
self.session.close()
def __getattr__(self, attr):
if attr in self._deprecated_attributes:
warnings.warn(
f"Accessing {attr} data through MPRester.{attr} is deprecated. "
f"Please use MPRester.materials.{attr} instead.",
DeprecationWarning,
stacklevel=2,
)
return getattr(super().__getattribute__("materials"), attr)
else:
raise AttributeError(
f"{self.__class__.__name__!r} object has no attribute {attr!r}"
)
def __getattribute__(self, attr):
if "molecules" in attr:
warnings.warn(
"NOTE: You are accessing a new set of molecules data to be officially released very soon. "
"This dataset includes many new properties, and is designed to be more easily expanded. "
"For the previous (legacy) molecules data, use the MPRester.molecules.jcesr rester. "
)
return super().__getattribute__(attr)
def __dir__(self):
return dir(MPRester) + self._deprecated_attributes + ["materials", "molecules"]
def get_task_ids_associated_with_material_id(
self, material_id: str, calc_types: list[CalcType] | None = None
) -> list[str]:
""":param material_id:
:param calc_types: if specified, will restrict to certain task types, e.g. [CalcType.GGA_STATIC]
:return:
"""
tasks = self.materials.get_data_by_id(
material_id, fields=["calc_types"]
).calc_types
if calc_types:
return [
task for task, calc_type in tasks.items() if calc_type in calc_types
]
else:
return list(tasks.keys())
def get_structure_by_material_id(
self, material_id: str, final: bool = True, conventional_unit_cell: bool = False
) -> Structure | list[Structure]:
"""Get a Structure corresponding to a material_id.
Args:
material_id (str): Materials Project material_id (a string,
e.g., mp-1234).
final (bool): Whether to get the final structure, or the list of initial
(pre-relaxation) structures. Defaults to True.
conventional_unit_cell (bool): Whether to get the standard
conventional unit cell for the final or list of initial structures.
Returns:
Structure object or list of Structure objects.
"""
structure_data = self.materials.get_structure_by_material_id(
material_id=material_id, final=final
)
if conventional_unit_cell and structure_data:
if final:
structure_data = SpacegroupAnalyzer(
structure_data
).get_conventional_standard_structure()
else:
structure_data = [
SpacegroupAnalyzer(structure).get_conventional_standard_structure()
for structure in structure_data
]
return structure_data
def get_database_version(self):
"""The Materials Project database is periodically updated and has a
database version associated with it. When the database is updated,
consolidated data (information about "a material") may and does
change, while calculation data about a specific calculation task
remains unchanged and available for querying via its task_id.
The database version is set as a date in the format YYYY_MM_DD,
where "_DD" may be optional. An additional numerical suffix
might be added if multiple releases happen on the same day.
Returns: database version as a string
"""
return get(url=self.endpoint + "heartbeat").json()["db_version"]
@staticmethod
@cache
def get_emmet_version(endpoint):
"""Get the latest version emmet-core and emmet-api used in the
current API service.
Returns: version as a string
"""
response = get(url=endpoint + "heartbeat").json()
error = response.get("error", None)
if error:
raise MPRestError(error)
return version.parse(response["version"])
def get_material_id_from_task_id(self, task_id: str) -> str | None:
"""Returns the current material_id from a given task_id. The
material_id should rarely change, and is usually chosen from
among the smallest numerical id from the group of task_ids for
that material. However, in some circumstances it might change,
and this method is useful for finding the new material_id.
Args:
task_id (str): A task id.
Returns:
material_id (MPID)
"""
docs = self.materials.search(task_ids=[task_id], fields=["material_id"])
if len(docs) == 1: # pragma: no cover
return str(docs[0].material_id) # type: ignore
elif len(docs) > 1: # pragma: no cover
raise ValueError(
f"Multiple documents return for {task_id}, this should not happen, please report it!"
)
else: # pragma: no cover
warnings.warn(
f"No material found containing task {task_id}. Please report it if you suspect a task has gone missing."
)
return None
def get_materials_id_from_task_id(self, task_id: str) -> str | None:
"""This method is deprecated, please use get_material_id_from_task_id."""
warnings.warn(
"This method is deprecated, please use get_material_id_from_task_id.",
DeprecationWarning,
)
return self.get_material_id_from_task_id(task_id)
def get_material_id_references(self, material_id: str) -> list[str]:
"""Returns all references for a material id.
Args:
material_id (str): A material id.
Returns:
List of BibTeX references ([str])
"""
return self.provenance.get_data_by_id(material_id).references
def get_materials_id_references(self, material_id: str) -> list[str]:
"""This method is deprecated, please use get_material_id_references."""
warnings.warn(
"This method is deprecated, please use get_material_id_references instead.",
DeprecationWarning,
)
return self.get_material_id_references(material_id)
def get_material_ids(
self,
chemsys_formula: str | list[str],
) -> list[MPID]:
"""Get all materials ids for a formula or chemsys.
Args:
chemsys_formula (str, List[str]): A chemical system, list of chemical systems
(e.g., Li-Fe-O, Si-*, [Si-O, Li-Fe-P]), or single formula (e.g., Fe2O3, Si*).
Returns:
List of all materials ids ([MPID])
"""
if isinstance(chemsys_formula, list) or (
isinstance(chemsys_formula, str) and "-" in chemsys_formula
):
input_params = {"chemsys": chemsys_formula}
else:
input_params = {"formula": chemsys_formula}
return sorted(
doc.material_id
for doc in self.materials.search(
**input_params, # type: ignore
all_fields=False,
fields=["material_id"],
)
)
def get_materials_ids(
self,
chemsys_formula: str | list[str],
) -> list[MPID]:
"""This method is deprecated, please use get_material_ids."""
warnings.warn(
"This method is deprecated, please use get_material_ids.",
DeprecationWarning,
)
return self.get_material_ids(chemsys_formula)
def get_structures(
self, chemsys_formula: str | list[str], final=True
) -> list[Structure]:
"""Get a list of Structures corresponding to a chemical system or formula.
Args:
chemsys_formula (str, List[str]): A chemical system, list of chemical systems
(e.g., Li-Fe-O, Si-*, [Si-O, Li-Fe-P]), or single formula (e.g., Fe2O3, Si*).
final (bool): Whether to get the final structure, or the list of initial
(pre-relaxation) structures. Defaults to True.
Returns:
List of Structure objects. ([Structure])
"""
if isinstance(chemsys_formula, list) or (
isinstance(chemsys_formula, str) and "-" in chemsys_formula
):
input_params = {"chemsys": chemsys_formula}
else:
input_params = {"formula": chemsys_formula}
if final:
return [
doc.structure
for doc in self.materials.search(
**input_params, # type: ignore
all_fields=False,
fields=["structure"],
)
]
else:
structures = []
for doc in self.materials.search(
**input_params, # type: ignore
all_fields=False,
fields=["initial_structures"],
):
structures.extend(doc.initial_structures)
return structures
def find_structure(
self,
filename_or_structure: str | Structure,
ltol: float = _EMMET_SETTINGS.LTOL,
stol: float = _EMMET_SETTINGS.STOL,
angle_tol: float = _EMMET_SETTINGS.ANGLE_TOL,
allow_multiple_results: bool = False,
) -> list[str] | str:
"""Finds matching structures from the Materials Project database.
Multiple results may be returned of "similar" structures based on
distance using the pymatgen StructureMatcher algorithm, however only
a single result should match with the same spacegroup, calculated to the
default tolerances.
Args:
filename_or_structure: filename or Structure object
ltol: fractional length tolerance
stol: site tolerance
angle_tol: angle tolerance in degrees
allow_multiple_results: changes return type for either
a single material_id or list of material_ids
Returns:
A matching material_id if one is found or list of results if allow_multiple_results
is True
Raises:
MPRestError
"""
return self.materials.find_structure(
filename_or_structure,
ltol=ltol,
stol=stol,
angle_tol=angle_tol,
allow_multiple_results=allow_multiple_results,
)
def get_entries(
self,
chemsys_formula_mpids: str | list[str],
compatible_only: bool = True,
inc_structure: bool = None,
property_data: list[str] = None,
conventional_unit_cell: bool = False,
additional_criteria: dict = None,
) -> list[ComputedStructureEntry]:
"""Get a list of ComputedEntries or ComputedStructureEntries corresponding
to a chemical system or formula. This returns entries for all thermo types
represented in the database. Each type corresponds to a different mixing scheme
(i.e. GGA/GGA+U, GGA/GGA+U/R2SCAN, R2SCAN). By default the thermo_type of the
entry is also returned.
Args:
chemsys_formula_mpids (str, List[str]): A chemical system, list of chemical systems
(e.g., Li-Fe-O, Si-*, [Si-O, Li-Fe-P]), formula, list of formulas
(e.g., Fe2O3, Si*, [SiO2, BiFeO3]), Materials Project ID, or list of Materials
Project IDs (e.g., mp-22526, [mp-22526, mp-149]).
compatible_only (bool): Whether to return only "compatible"
entries. Compatible entries are entries that have been
processed using the MaterialsProject2020Compatibility class,
which performs adjustments to allow mixing of GGA and GGA+U
calculations for more accurate phase diagrams and reaction
energies. This data is obtained from the core "thermo" API endpoint.
inc_structure (str): *This is a deprecated argument*. Previously, if None, entries
returned were ComputedEntries. If inc_structure="initial",
ComputedStructureEntries with initial structures were returned.
Otherwise, ComputedStructureEntries with final structures
were returned. This is no longer needed as all entries will contain
structure data by default.
property_data (list): Specify additional properties to include in
entry.data. If None, only default data is included. Should be a subset of
input parameters in the 'MPRester.thermo.available_fields' list.
conventional_unit_cell (bool): Whether to get the standard
conventional unit cell
additional_criteria (dict): Any additional criteria to pass. The keys and values should
correspond to proper function inputs to `MPRester.thermo.search`. For instance,
if you are only interested in entries on the convex hull, you could pass
{"energy_above_hull": (0.0, 0.0)} or {"is_stable": True}.
Returns:
List ComputedStructureEntry objects.
"""
if inc_structure is not None:
warnings.warn(
"The 'inc_structure' argument is deprecated as structure "
"data is now always included in all returned entry objects."
)
if isinstance(chemsys_formula_mpids, str):
chemsys_formula_mpids = [chemsys_formula_mpids]
try:
input_params = {"material_ids": validate_ids(chemsys_formula_mpids)}
except ValueError:
if any("-" in entry for entry in chemsys_formula_mpids):
input_params = {"chemsys": chemsys_formula_mpids}
else:
input_params = {"formula": chemsys_formula_mpids}
if additional_criteria:
input_params = {**input_params, **additional_criteria}
entries = []
fields = (
["entries", "thermo_type"]
if not property_data
else ["entries", "thermo_type"] + property_data
)
docs = self.thermo.search(
**input_params,
all_fields=False,
fields=fields, # type: ignore
)
for doc in docs:
entry_list = (
doc.entries.values()
if self.use_document_model
else doc["entries"].values()
)
for entry in entry_list:
entry_dict = entry.as_dict() if self.monty_decode else entry
if not compatible_only:
entry_dict["correction"] = 0.0
entry_dict["energy_adjustments"] = []
if property_data:
for property in property_data:
entry_dict["data"][property] = (
doc.model_dump()[property]
if self.use_document_model
else doc[property]
)
if conventional_unit_cell:
entry_struct = Structure.from_dict(entry_dict["structure"])
s = SpacegroupAnalyzer(
entry_struct
).get_conventional_standard_structure()
site_ratio = len(s) / len(entry_struct)
new_energy = entry_dict["energy"] * site_ratio
entry_dict["energy"] = new_energy
entry_dict["structure"] = s.as_dict()
entry_dict["correction"] = 0.0
for element in entry_dict["composition"]:
entry_dict["composition"][element] *= site_ratio
for correction in entry_dict["energy_adjustments"]:
if "n_atoms" in correction:
correction["n_atoms"] *= site_ratio
entry = (
ComputedStructureEntry.from_dict(entry_dict)
if self.monty_decode
else entry_dict
)
entries.append(entry)
return entries
def get_pourbaix_entries(
self,
chemsys: str | list,
solid_compat="MaterialsProject2020Compatibility",
use_gibbs: Literal[300] | None = None,
):
"""A helper function to get all entries necessary to generate
a Pourbaix diagram from the rest interface.
Args:
chemsys (str or [str]): Chemical system string comprising element
symbols separated by dashes, e.g., "Li-Fe-O" or List of element
symbols, e.g., ["Li", "Fe", "O"].
solid_compat: Compatibility scheme used to pre-process solid DFT energies prior
to applying aqueous energy adjustments. May be passed as a class (e.g.
MaterialsProject2020Compatibility) or an instance
(e.g., MaterialsProject2020Compatibility()). If None, solid DFT energies
are used as-is. Default: MaterialsProject2020Compatibility
use_gibbs: Set to 300 (for 300 Kelvin) to use a machine learning model to
estimate solid free energy from DFT energy (see GibbsComputedStructureEntry).
This can slightly improve the accuracy of the Pourbaix diagram in some
cases. Default: None. Note that temperatures other than 300K are not
permitted here, because MaterialsProjectAqueousCompatibility corrections,
used in Pourbaix diagram construction, are calculated based on 300 K data.
"""
# imports are not top-level due to expense
from pymatgen.analysis.pourbaix_diagram import PourbaixEntry
from pymatgen.entries.compatibility import (
Compatibility,
MaterialsProject2020Compatibility,
MaterialsProjectAqueousCompatibility,
MaterialsProjectCompatibility,
)
from pymatgen.entries.computed_entries import ComputedEntry
if solid_compat == "MaterialsProjectCompatibility":
solid_compat = MaterialsProjectCompatibility()
elif solid_compat == "MaterialsProject2020Compatibility":
solid_compat = MaterialsProject2020Compatibility()
elif isinstance(solid_compat, Compatibility):
pass
else:
raise ValueError(
"Solid compatibility can only be 'MaterialsProjectCompatibility', "
"'MaterialsProject2020Compatibility', or an instance of a Compatibility class"
)
pbx_entries = []
if isinstance(chemsys, str):
chemsys = chemsys.split("-")
# capitalize and sort the elements
chemsys = sorted(e.capitalize() for e in chemsys)
# Get ion entries first, because certain ions have reference
# solids that aren't necessarily in the chemsys (Na2SO4)
# download the ion reference data from MPContribs
ion_data = self.get_ion_reference_data_for_chemsys(chemsys)
# build the PhaseDiagram for get_ion_entries
ion_ref_comps = [
Ion.from_formula(d["data"]["RefSolid"]).composition for d in ion_data
]
ion_ref_elts = set(
itertools.chain.from_iterable(i.elements for i in ion_ref_comps)
)
# TODO - would be great if the commented line below would work
# However for some reason you cannot process GibbsComputedStructureEntry with
# MaterialsProjectAqueousCompatibility
ion_ref_entries = self.get_entries_in_chemsys(
list([str(e) for e in ion_ref_elts] + ["O", "H"]),
# use_gibbs=use_gibbs
)
# suppress the warning about supplying the required energies; they will be calculated from the
# entries we get from MPRester
with warnings.catch_warnings():
warnings.filterwarnings(
"ignore",
message="You did not provide the required O2 and H2O energies.",
)
compat = MaterialsProjectAqueousCompatibility(solid_compat=solid_compat)
# suppress the warning about missing oxidation states
with warnings.catch_warnings():
warnings.filterwarnings(
"ignore", message="Failed to guess oxidation states.*"
)
ion_ref_entries = compat.process_entries(ion_ref_entries)
# TODO - if the commented line above would work, this conditional block
# could be removed
if use_gibbs:
# replace the entries with GibbsComputedStructureEntry
from pymatgen.entries.computed_entries import GibbsComputedStructureEntry
ion_ref_entries = GibbsComputedStructureEntry.from_entries(
ion_ref_entries, temp=use_gibbs
)
ion_ref_pd = PhaseDiagram(ion_ref_entries)
ion_entries = self.get_ion_entries(ion_ref_pd, ion_ref_data=ion_data)
pbx_entries = [PourbaixEntry(e, f"ion-{n}") for n, e in enumerate(ion_entries)]
# Construct the solid pourbaix entries from filtered ion_ref entries
extra_elts = (
set(ion_ref_elts)
- {Element(s) for s in chemsys}
- {Element("H"), Element("O")}
)
for entry in ion_ref_entries:
entry_elts = set(entry.composition.elements)
# Ensure no OH chemsys or extraneous elements from ion references
if not (
entry_elts <= {Element("H"), Element("O")}
or extra_elts.intersection(entry_elts)
):
# Create new computed entry
form_e = ion_ref_pd.get_form_energy(entry)
new_entry = ComputedEntry(
entry.composition, form_e, entry_id=entry.entry_id
)
pbx_entry = PourbaixEntry(new_entry)
pbx_entries.append(pbx_entry)
return pbx_entries
@lru_cache
def get_ion_reference_data(self) -> list[dict]:
"""Download aqueous ion reference data used in the construction of Pourbaix diagrams.
Use this method to examine the ion reference data and to add additional
ions if desired. The data returned from this method can be passed to
get_ion_entries().
Data are retrieved from the Aqueous Ion Reference Data project
hosted on MPContribs. Refer to that project and its associated documentation
for more details about the format and meaning of the data.
Returns:
[dict]: Among other data, each record contains 1) the experimental ion free energy, 2) the
formula of the reference solid for the ion, and 3) the experimental free energy of the
reference solid. All energies are given in kJ/mol. An example is given below.
{'identifier': 'Li[+]',
'formula': 'Li[+]',
'data': {'charge': {'display': '1.0', 'value': 1.0, 'unit': ''},
'ΔGᶠ': {'display': '-293.71 kJ/mol', 'value': -293.71, 'unit': 'kJ/mol'},
'MajElements': 'Li',
'RefSolid': 'Li2O',
'ΔGᶠRefSolid': {'display': '-561.2 kJ/mol',
'value': -561.2,
'unit': 'kJ/mol'},
'reference': 'H. E. Barner and R. V. Scheuerman, Handbook of thermochemical data for
compounds and aqueous species, Wiley, New York (1978)'}}
"""
return self.contribs.query_contributions(
query={"project": "ion_ref_data"},
fields=["identifier", "formula", "data"],
paginate=True,
).get("data")
def get_ion_reference_data_for_chemsys(self, chemsys: str | list) -> list[dict]:
"""Download aqueous ion reference data used in the construction of Pourbaix diagrams.
Use this method to examine the ion reference data and to add additional
ions if desired. The data returned from this method can be passed to
get_ion_entries().
Data are retrieved from the Aqueous Ion Reference Data project
hosted on MPContribs. Refer to that project and its associated documentation
for more details about the format and meaning of the data.
Args:
chemsys (str or [str]): Chemical system string comprising element
symbols separated by dashes, e.g., "Li-Fe-O" or List of element
symbols, e.g., ["Li", "Fe", "O"].
Returns:
[dict]: Among other data, each record contains 1) the experimental ion free energy, 2) the
formula of the reference solid for the ion, and 3) the experimental free energy of the
reference solid. All energies are given in kJ/mol. An example is given below.
{'identifier': 'Li[+]',
'formula': 'Li[+]',
'data': {'charge': {'display': '1.0', 'value': 1.0, 'unit': ''},
'ΔGᶠ': {'display': '-293.71 kJ/mol', 'value': -293.71, 'unit': 'kJ/mol'},
'MajElements': 'Li',
'RefSolid': 'Li2O',
'ΔGᶠRefSolid': {'display': '-561.2 kJ/mol',
'value': -561.2,
'unit': 'kJ/mol'},
'reference': 'H. E. Barner and R. V. Scheuerman, Handbook of thermochemical data for
compounds and aqueous species, Wiley, New York (1978)'}}
"""
ion_data = self.get_ion_reference_data()
if isinstance(chemsys, str):
chemsys = chemsys.split("-")
return [d for d in ion_data if d["data"]["MajElements"] in chemsys]
def get_ion_entries(
self, pd: PhaseDiagram, ion_ref_data: list[dict] = None
) -> list[IonEntry]:
"""Retrieve IonEntry objects that can be used in the construction of
Pourbaix Diagrams. The energies of the IonEntry are calculaterd from
the solid energies in the provided Phase Diagram to be
consistent with experimental free energies.
NOTE! This is an advanced method that assumes detailed understanding
of how to construct computational Pourbaix Diagrams. If you just want
to build a Pourbaix Diagram using default settings, use get_pourbaix_entries.