0
# Phase Diagrams & Thermodynamics
1
2
Phase diagram construction and analysis, Pourbaix diagrams, chemical potential diagrams, and thermodynamic property calculations. These tools enable the analysis of phase stability, chemical reactions, and electrochemical behavior in materials systems.
3
4
## Capabilities
5
6
### Phase Diagram Construction
7
8
Classes for constructing and analyzing multi-component phase diagrams from computed entries.
9
10
```python { .api }
11
class PhaseDiagram:
12
"""
13
Multi-component phase diagram construction and analysis.
14
15
Parameters:
16
- entries: List of ComputedEntry objects
17
- elements: List of elements to include (optional)
18
"""
19
def __init__(self, entries, elements=None): ...
20
21
def get_hull_energy(self, composition):
22
"""
23
Get energy above convex hull for a composition.
24
25
Parameters:
26
composition: Composition object or dict
27
28
Returns:
29
float: Energy above hull in eV/atom
30
"""
31
32
def get_hull_energy_per_atom(self, composition):
33
"""
34
Get energy above hull per atom.
35
36
Parameters:
37
composition: Composition object or dict
38
39
Returns:
40
float: Energy above hull in eV/atom
41
"""
42
43
def get_equilibrium_reaction_energy(self, entry):
44
"""
45
Get reaction energy for entry to equilibrium phases.
46
47
Parameters:
48
entry: ComputedEntry object
49
50
Returns:
51
float: Reaction energy in eV/atom
52
"""
53
54
def get_decomposition(self, composition):
55
"""
56
Get decomposition of composition into stable phases.
57
58
Parameters:
59
composition: Composition object or dict
60
61
Returns:
62
dict: {entry: amount} decomposition dictionary
63
"""
64
65
def get_decomp_and_e_above_hull(self, entry, allow_negative=False):
66
"""
67
Get decomposition and energy above hull for entry.
68
69
Parameters:
70
entry: ComputedEntry object
71
allow_negative: Whether to allow negative formation energies
72
73
Returns:
74
tuple: (decomposition_dict, energy_above_hull)
75
"""
76
77
def get_decomp_and_phase_separation_energy(self, entry):
78
"""
79
Get decomposition and phase separation energy.
80
81
Parameters:
82
entry: ComputedEntry object
83
84
Returns:
85
tuple: (decomposition_dict, phase_separation_energy)
86
"""
87
88
def get_phase_separation_energy(self, entry):
89
"""
90
Get phase separation energy for entry.
91
92
Parameters:
93
entry: ComputedEntry object
94
95
Returns:
96
float: Phase separation energy in eV/atom
97
"""
98
99
def get_form_energy(self, entry):
100
"""
101
Get formation energy for entry.
102
103
Parameters:
104
entry: ComputedEntry object
105
106
Returns:
107
float: Formation energy in eV/atom
108
"""
109
110
def get_form_energy_per_atom(self, entry):
111
"""
112
Get formation energy per atom.
113
114
Parameters:
115
entry: ComputedEntry object
116
117
Returns:
118
float: Formation energy in eV/atom
119
"""
120
121
def get_critical_compositions(self, comp1, comp2):
122
"""
123
Get critical compositions along tie line.
124
125
Parameters:
126
comp1, comp2: End-point compositions
127
128
Returns:
129
list: Critical compositions along tie line
130
"""
131
132
def get_element_profile(self, element, comp, comp_tol=1e-5):
133
"""
134
Get element profile across composition space.
135
136
Parameters:
137
element: Element of interest
138
comp: Reference composition
139
comp_tol: Composition tolerance
140
141
Returns:
142
list: Element profile data
143
"""
144
145
def get_chempot_range_map(self, elements, referenced=True, joggle=True):
146
"""
147
Get chemical potential range map.
148
149
Parameters:
150
elements: Elements for chemical potential analysis
151
referenced: Whether to reference to pure elements
152
joggle: Whether to joggle duplicate points
153
154
Returns:
155
dict: Chemical potential ranges by phase
156
"""
157
158
def get_all_chempots(self, comp):
159
"""
160
Get all possible chemical potentials for composition.
161
162
Parameters:
163
comp: Composition object or dict
164
165
Returns:
166
dict: Chemical potentials by element
167
"""
168
169
def getmu_vertices_stability_phase(self, target_comp, dep_elt, tol_en=1e-2):
170
"""
171
Get chemical potential vertices for stability analysis.
172
173
Parameters:
174
target_comp: Target composition
175
dep_elt: Dependent element
176
tol_en: Energy tolerance
177
178
Returns:
179
list: Chemical potential vertices
180
"""
181
182
@property
183
def elements(self):
184
"""Elements in the phase diagram."""
185
186
@property
187
def all_entries(self):
188
"""All entries in the phase diagram."""
189
190
@property
191
def stable_entries(self):
192
"""Entries on the convex hull (stable phases)."""
193
194
@property
195
def unstable_entries(self):
196
"""Entries above the convex hull (unstable phases)."""
197
198
@property
199
def el_refs(self):
200
"""Elemental reference entries."""
201
202
@property
203
def facets(self):
204
"""Facets of the convex hull."""
205
206
@property
207
def qhull_data(self):
208
"""QHull convex hull data."""
209
210
@property
211
def dim(self):
212
"""Dimensionality of the phase diagram."""
213
214
@property
215
def volume(self):
216
"""Volume of the convex hull."""
217
```
218
219
```python { .api }
220
class CompoundPhaseDiagram:
221
"""
222
Phase diagram for compound systems with terminal compounds.
223
224
Parameters:
225
- entries: List of ComputedEntry objects
226
- terminal_compositions: Terminal compound compositions
227
"""
228
def __init__(self, entries, terminal_compositions): ...
229
230
def get_compound_pd(self):
231
"""
232
Get compound phase diagram.
233
234
Returns:
235
PhaseDiagram: Phase diagram for compound system
236
"""
237
238
@property
239
def terminal_compositions(self):
240
"""Terminal compound compositions."""
241
242
@property
243
def original_entries(self):
244
"""Original entries before transformation."""
245
```
246
247
```python { .api }
248
class GrandPotentialPhaseDiagram:
249
"""
250
Grand potential phase diagram with open elements.
251
252
Parameters:
253
- entries: List of ComputedEntry objects
254
- chempots: Chemical potentials dict {element: potential}
255
- elements: Elements to include in diagram
256
"""
257
def __init__(self, entries, chempots, elements=None): ...
258
259
@property
260
def chempots(self):
261
"""Chemical potentials dictionary."""
262
263
@property
264
def original_entries(self):
265
"""Original entries before grand potential transformation."""
266
```
267
268
### Pourbaix Diagrams
269
270
Electrochemical phase diagrams showing stable phases as functions of pH and potential.
271
272
```python { .api }
273
class PourbaixDiagram:
274
"""
275
Pourbaix (pH-potential) diagram construction and analysis.
276
277
Parameters:
278
- entries: List of PourbaixEntry objects
279
- comp_dict: Composition dictionary for normalization
280
- conc_dict: Concentration dictionary for species
281
- filter_solids: Whether to filter out solids
282
- nproc: Number of processes for parallel computation
283
"""
284
def __init__(self, entries, comp_dict=None, conc_dict=None,
285
filter_solids=True, nproc=None): ...
286
287
def get_stable_entry(self, pH, V):
288
"""
289
Get stable entry at given pH and potential.
290
291
Parameters:
292
pH: pH value
293
V: Potential in V vs SHE
294
295
Returns:
296
PourbaixEntry: Stable entry at (pH, V)
297
"""
298
299
def get_decomposition_energy(self, entry, pH, V):
300
"""
301
Get decomposition energy for entry at pH and potential.
302
303
Parameters:
304
entry: PourbaixEntry to analyze
305
pH: pH value
306
V: Potential in V vs SHE
307
308
Returns:
309
float: Decomposition energy in eV
310
"""
311
312
def solve_equilibrium_point(self, entry1, entry2, pH=None, V=None):
313
"""
314
Solve equilibrium point between two entries.
315
316
Parameters:
317
entry1, entry2: PourbaixEntry objects
318
pH: Fixed pH (if V is variable)
319
V: Fixed potential (if pH is variable)
320
321
Returns:
322
tuple: (pH, V) at equilibrium
323
"""
324
325
def get_pourbaix_domains(self, limits=None):
326
"""
327
Get Pourbaix stability domains.
328
329
Parameters:
330
limits: [(pH_min, pH_max), (V_min, V_max)] limits
331
332
Returns:
333
list: List of stability domains
334
"""
335
336
def get_hull_energy(self, pH, V):
337
"""
338
Get hull energy at pH and potential.
339
340
Parameters:
341
pH: pH value
342
V: Potential in V vs SHE
343
344
Returns:
345
float: Hull energy
346
"""
347
348
@property
349
def stable_entries(self):
350
"""Stable entries in the Pourbaix diagram."""
351
352
@property
353
def unstable_entries(self):
354
"""Unstable entries in the Pourbaix diagram."""
355
356
@property
357
def all_entries(self):
358
"""All entries in the Pourbaix diagram."""
359
```
360
361
```python { .api }
362
class PourbaixEntry:
363
"""
364
Entry for Pourbaix diagram analysis.
365
366
Parameters:
367
- entry: ComputedEntry or other entry object
368
- entry_id: Unique identifier for the entry
369
- concentration: Species concentration
370
"""
371
def __init__(self, entry, entry_id=None, concentration=1e-6): ...
372
373
def g(self, pH, V, ionic_strength=0):
374
"""
375
Get Gibbs free energy at pH and potential.
376
377
Parameters:
378
pH: pH value
379
V: Potential in V vs SHE
380
ionic_strength: Ionic strength
381
382
Returns:
383
float: Gibbs free energy
384
"""
385
386
def get_element_fraction(self, element):
387
"""
388
Get fraction of element in entry.
389
390
Parameters:
391
element: Element object or symbol
392
393
Returns:
394
float: Element fraction
395
"""
396
397
@property
398
def name(self):
399
"""Entry name."""
400
401
@property
402
def charge(self):
403
"""Entry charge."""
404
405
@property
406
def composition(self):
407
"""Entry composition."""
408
409
@property
410
def energy(self):
411
"""Entry energy."""
412
413
@property
414
def elements(self):
415
"""Elements in entry."""
416
417
@property
418
def concentration(self):
419
"""Species concentration."""
420
421
@property
422
def npH(self):
423
"""Number of H+ in formation reaction."""
424
425
@property
426
def nPhi(self):
427
"""Number of electrons in formation reaction."""
428
429
@property
430
def conc_term(self):
431
"""Concentration term contribution."""
432
```
433
434
### Chemical Potential Diagrams
435
436
Analysis of chemical potential relationships and stability regions.
437
438
```python { .api }
439
class ChemicalPotentialDiagram:
440
"""
441
Chemical potential diagram construction and analysis.
442
443
Parameters:
444
- entries: List of ComputedEntry objects
445
- limits: Chemical potential limits
446
- default_min_limit: Default minimum chemical potential limit
447
"""
448
def __init__(self, entries, limits=None, default_min_limit=-50.0): ...
449
450
def get_plot(self, elements=None, label_stable=True, colormap="plasma",
451
label_unstable=True, process_attributes=False, plt_kwargs=None):
452
"""
453
Get chemical potential plot.
454
455
Parameters:
456
elements: Elements to plot (default: first 2-3)
457
label_stable: Whether to label stable regions
458
colormap: Matplotlib colormap
459
label_unstable: Whether to label unstable phases
460
process_attributes: Whether to process phase attributes
461
plt_kwargs: Additional plot arguments
462
463
Returns:
464
matplotlib.pyplot: Plot object
465
"""
466
467
def get_hyperplane_intersection(self, hyperplanes, open_el):
468
"""
469
Get intersection of hyperplanes.
470
471
Parameters:
472
hyperplanes: List of hyperplane equations
473
open_el: Open element
474
475
Returns:
476
numpy.ndarray: Intersection coordinates
477
"""
478
479
def get_critical_original_kinks_multipleopen(self, element_list):
480
"""
481
Get critical kinks for multiple open elements.
482
483
Parameters:
484
element_list: List of open elements
485
486
Returns:
487
list: Critical kink points
488
"""
489
490
@property
491
def elements(self):
492
"""Elements in the diagram."""
493
494
@property
495
def entries(self):
496
"""Entries in the diagram."""
497
498
@property
499
def limits(self):
500
"""Chemical potential limits."""
501
```
502
503
### Thermodynamic Analysis
504
505
Tools for thermodynamic property calculations and analysis.
506
507
```python { .api }
508
class ThermoData:
509
"""
510
Thermochemical data representation and analysis.
511
512
Parameters:
513
- data_type: Type of thermodynamic data
514
- temps: Temperature array
515
- values: Property values at each temperature
516
"""
517
def __init__(self, data_type, temps, values): ...
518
519
def get_interp_value(self, temp):
520
"""
521
Get interpolated value at temperature.
522
523
Parameters:
524
temp: Temperature in K
525
526
Returns:
527
float: Interpolated property value
528
"""
529
530
@property
531
def data_type(self):
532
"""Type of thermodynamic data."""
533
534
@property
535
def temps(self):
536
"""Temperature array."""
537
538
@property
539
def values(self):
540
"""Property values."""
541
```
542
543
```python { .api }
544
class QuasiHarmonicDebyeApprox:
545
"""
546
Quasi-harmonic Debye approximation for thermodynamic properties.
547
548
Parameters:
549
- energies: Total energies at different volumes
550
- volumes: Volume array
551
- structure: Structure object
552
- t_min: Minimum temperature
553
- t_max: Maximum temperature
554
- t_step: Temperature step
555
- eos: Equation of state to use
556
- pressure: Applied pressure
557
- poisson: Poisson ratio
558
- use_mie_gruneisen: Whether to use Mie-Grüneisen parameter
559
- anharmonic_contribution: Whether to include anharmonic effects
560
"""
561
def __init__(self, energies, volumes, structure, t_min=300.0, t_max=300.0,
562
t_step=100.0, eos="vinet", pressure=0.0, poisson=0.363,
563
use_mie_gruneisen=False, anharmonic_contribution=False): ...
564
565
def get_summary_dict(self):
566
"""
567
Get summary of thermodynamic properties.
568
569
Returns:
570
dict: Summary of calculated properties
571
"""
572
573
def get_thermal_expansion(self):
574
"""
575
Get thermal expansion coefficient.
576
577
Returns:
578
numpy.ndarray: Thermal expansion vs temperature
579
"""
580
581
def get_gruneisen_parameter(self):
582
"""
583
Get Grüneisen parameter.
584
585
Returns:
586
float: Grüneisen parameter
587
"""
588
589
def get_bulk_modulus(self):
590
"""
591
Get bulk modulus vs temperature.
592
593
Returns:
594
numpy.ndarray: Bulk modulus vs temperature
595
"""
596
597
def get_heat_capacity(self):
598
"""
599
Get heat capacity at constant volume and pressure.
600
601
Returns:
602
tuple: (Cv, Cp) heat capacities vs temperature
603
"""
604
605
def get_entropy(self):
606
"""
607
Get entropy vs temperature.
608
609
Returns:
610
numpy.ndarray: Entropy vs temperature
611
"""
612
613
def get_helmholtz_energy(self):
614
"""
615
Get Helmholtz free energy vs temperature.
616
617
Returns:
618
numpy.ndarray: Helmholtz energy vs temperature
619
"""
620
621
def get_gibbs_energy(self):
622
"""
623
Get Gibbs free energy vs temperature.
624
625
Returns:
626
numpy.ndarray: Gibbs energy vs temperature
627
"""
628
629
@property
630
def temperatures(self):
631
"""Temperature array."""
632
633
@property
634
def optimum_volumes(self):
635
"""Optimum volumes at each temperature."""
636
```
637
638
### Reaction Analysis
639
640
Analysis of chemical reactions and reaction energetics.
641
642
```python { .api }
643
class Reaction:
644
"""
645
Chemical reaction representation and analysis.
646
647
Parameters:
648
- reactants: List of reactant Composition objects
649
- products: List of product Composition objects
650
"""
651
def __init__(self, reactants, products): ...
652
653
def copy(self):
654
"""
655
Create a copy of the reaction.
656
657
Returns:
658
Reaction: Copy of the reaction
659
"""
660
661
def reverse(self):
662
"""
663
Get reverse reaction.
664
665
Returns:
666
Reaction: Reversed reaction
667
"""
668
669
def normalize_to(self, comp, factor=1):
670
"""
671
Normalize reaction to a composition.
672
673
Parameters:
674
comp: Composition to normalize to
675
factor: Normalization factor
676
677
Returns:
678
Reaction: Normalized reaction
679
"""
680
681
def normalize_to_element(self, element, factor=1):
682
"""
683
Normalize reaction to an element.
684
685
Parameters:
686
element: Element to normalize to
687
factor: Normalization factor
688
689
Returns:
690
Reaction: Normalized reaction
691
"""
692
693
def get_el_amount(self, element):
694
"""
695
Get net amount of element in reaction.
696
697
Parameters:
698
element: Element object or symbol
699
700
Returns:
701
float: Net amount of element
702
"""
703
704
@property
705
def reactants(self):
706
"""Reactant compositions."""
707
708
@property
709
def products(self):
710
"""Product compositions."""
711
712
@property
713
def elements(self):
714
"""Elements involved in reaction."""
715
716
@property
717
def coeffs(self):
718
"""Reaction coefficients."""
719
720
@property
721
def all_comp(self):
722
"""All compositions in reaction."""
723
724
@property
725
def normalized_repr(self):
726
"""Normalized string representation."""
727
```
728
729
```python { .api }
730
class BalancedReaction:
731
"""
732
Balanced chemical reaction with automatic balancing.
733
734
Parameters:
735
- reactants_coeffs: Dict of {Composition: coefficient} for reactants
736
- products_coeffs: Dict of {Composition: coefficient} for products
737
"""
738
def __init__(self, reactants_coeffs, products_coeffs): ...
739
740
@classmethod
741
def from_string(cls, rxn_string):
742
"""
743
Create balanced reaction from string.
744
745
Parameters:
746
rxn_string: Reaction string (e.g., "2 H2 + O2 -> 2 H2O")
747
748
Returns:
749
BalancedReaction: Balanced reaction object
750
"""
751
752
def calculate_energy(self, energies):
753
"""
754
Calculate reaction energy from formation energies.
755
756
Parameters:
757
energies: Dict of {Composition: formation_energy}
758
759
Returns:
760
float: Reaction energy
761
"""
762
763
@property
764
def normalized_repr_and_factor(self):
765
"""Normalized representation and normalization factor."""
766
```
767
768
```python { .api }
769
class ComputedReaction:
770
"""
771
Computed chemical reaction with energies from DFT calculations.
772
773
Parameters:
774
- reactant_entries: List of reactant ComputedEntry objects
775
- product_entries: List of product ComputedEntry objects
776
"""
777
def __init__(self, reactant_entries, product_entries): ...
778
779
def calculate_energy(self):
780
"""
781
Calculate reaction energy from computed entries.
782
783
Returns:
784
float: Reaction energy in eV per formula unit
785
"""
786
787
@property
788
def calculated_reaction_energy(self):
789
"""Calculated reaction energy."""
790
791
@property
792
def calculated_reaction_energy_per_atom(self):
793
"""Calculated reaction energy per atom."""
794
```
795
796
### Plotting and Visualization
797
798
Classes for plotting phase diagrams and thermodynamic data.
799
800
```python { .api }
801
class PDPlotter:
802
"""
803
Phase diagram plotting utility.
804
805
Parameters:
806
- phasediagram: PhaseDiagram object to plot
807
- show_unstable: Whether to show unstable phases
808
- backend: Plotting backend ("plotly" or "matplotlib")
809
"""
810
def __init__(self, phasediagram, show_unstable=0, backend="plotly"): ...
811
812
def get_plot(self, limits=None, title="", label_stable=True,
813
label_unstable=True, ordering=None, energy_colormap=None,
814
process_attributes=False, label_uncertainties=False):
815
"""
816
Get phase diagram plot.
817
818
Parameters:
819
limits: Plot limits
820
title: Plot title
821
label_stable: Whether to label stable phases
822
label_unstable: Whether to label unstable phases
823
ordering: Ordering of elements for ternary plots
824
energy_colormap: Colormap for energy above hull
825
process_attributes: Whether to process entry attributes
826
label_uncertainties: Whether to label energy uncertainties
827
828
Returns:
829
matplotlib.pyplot or plotly.graph_objects: Plot object
830
"""
831
832
def show(self, *args, **kwargs):
833
"""Show phase diagram plot."""
834
835
def get_contour_pd_plot(self, limits=None):
836
"""
837
Get contour plot for 3+ component phase diagrams.
838
839
Parameters:
840
limits: Plot limits
841
842
Returns:
843
matplotlib.pyplot: Contour plot
844
"""
845
846
def get_chempot_range_map_plot(self, elements, referenced=True):
847
"""
848
Get chemical potential range map plot.
849
850
Parameters:
851
elements: Elements for chemical potential analysis
852
referenced: Whether to reference to pure elements
853
854
Returns:
855
matplotlib.pyplot: Chemical potential range map
856
"""
857
858
def write_image(self, stream, fmt="png"):
859
"""
860
Write plot image to stream.
861
862
Parameters:
863
stream: Output stream
864
fmt: Image format
865
"""
866
```
867
868
```python { .api }
869
class PourbaixPlotter:
870
"""
871
Pourbaix diagram plotting utility.
872
873
Parameters:
874
- pourbaix_diagram: PourbaixDiagram object to plot
875
"""
876
def __init__(self, pourbaix_diagram): ...
877
878
def get_pourbaix_plot(self, limits=None, title="", label_domains=True,
879
label_fontsize=20, show_water_lines=True,
880
show_neutral_axes=True, alpha=0.2, ax=None):
881
"""
882
Get Pourbaix diagram plot.
883
884
Parameters:
885
limits: [(pH_min, pH_max), (V_min, V_max)] limits
886
title: Plot title
887
label_domains: Whether to label stability domains
888
label_fontsize: Font size for labels
889
show_water_lines: Whether to show water stability lines
890
show_neutral_axes: Whether to show neutral pH/V axes
891
alpha: Transparency for domain colors
892
ax: Matplotlib axes object
893
894
Returns:
895
matplotlib.pyplot: Pourbaix plot
896
"""
897
898
def plot_entry_stability(self, entry, pH_range=None, pH_resolution=100,
899
V_range=None, V_resolution=100, e_hull_max=1,
900
cmap="RdYlBu_r", ax=None, **kwargs):
901
"""
902
Plot stability of specific entry across pH-V space.
903
904
Parameters:
905
entry: PourbaixEntry to analyze
906
pH_range: pH range for analysis
907
pH_resolution: pH resolution
908
V_range: Potential range for analysis
909
V_resolution: Potential resolution
910
e_hull_max: Maximum energy above hull to show
911
cmap: Colormap for stability
912
ax: Matplotlib axes object
913
914
Returns:
915
matplotlib.pyplot: Entry stability plot
916
"""
917
918
def show(self, *args, **kwargs):
919
"""Show Pourbaix plot."""
920
```
921
922
### Utility Functions
923
924
Helper functions for thermodynamic calculations and phase analysis.
925
926
```python { .api }
927
def unique_lines(list1, list2, prec=3):
928
"""
929
Find unique lines between two lists of points.
930
931
Parameters:
932
list1, list2: Lists of points
933
prec: Precision for uniqueness determination
934
935
Returns:
936
list: Unique lines
937
"""
938
939
def order_phase_diagram(lines, stable_entries, unstable_entries, ordering):
940
"""
941
Order phase diagram for consistent plotting.
942
943
Parameters:
944
lines: Phase diagram lines
945
stable_entries: Stable phase entries
946
unstable_entries: Unstable phase entries
947
ordering: Element ordering
948
949
Returns:
950
tuple: Ordered diagram components
951
"""
952
953
def triangular_coord(coord):
954
"""
955
Convert 3D coordinates to triangular coordinates for ternary plots.
956
957
Parameters:
958
coord: 3D coordinates
959
960
Returns:
961
numpy.ndarray: Triangular coordinates
962
"""
963
964
def tet_coord(coord):
965
"""
966
Convert 4D coordinates to tetrahedral coordinates for quaternary plots.
967
968
Parameters:
969
coord: 4D coordinates
970
971
Returns:
972
numpy.ndarray: Tetrahedral coordinates
973
"""
974
```