tessl/pypi-pymatgen
Comprehensive materials science analysis library for crystal structures, molecules, and materials data with extensive computational chemistry integration.
—
Pending
phase-diagrams.mddocs/
Phase Diagrams & Thermodynamics
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.
Capabilities
Phase Diagram Construction
Classes for constructing and analyzing multi-component phase diagrams from computed entries.
class PhaseDiagram:
"""
Multi-component phase diagram construction and analysis.
Parameters:
- entries: List of ComputedEntry objects
- elements: List of elements to include (optional)
"""
def __init__(self, entries, elements=None): ...
def get_hull_energy(self, composition):
"""
Get energy above convex hull for a composition.
Parameters:
composition: Composition object or dict
Returns:
float: Energy above hull in eV/atom
"""
def get_hull_energy_per_atom(self, composition):
"""
Get energy above hull per atom.
Parameters:
composition: Composition object or dict
Returns:
float: Energy above hull in eV/atom
"""
def get_equilibrium_reaction_energy(self, entry):
"""
Get reaction energy for entry to equilibrium phases.
Parameters:
entry: ComputedEntry object
Returns:
float: Reaction energy in eV/atom
"""
def get_decomposition(self, composition):
"""
Get decomposition of composition into stable phases.
Parameters:
composition: Composition object or dict
Returns:
dict: {entry: amount} decomposition dictionary
"""
def get_decomp_and_e_above_hull(self, entry, allow_negative=False):
"""
Get decomposition and energy above hull for entry.
Parameters:
entry: ComputedEntry object
allow_negative: Whether to allow negative formation energies
Returns:
tuple: (decomposition_dict, energy_above_hull)
"""
def get_decomp_and_phase_separation_energy(self, entry):
"""
Get decomposition and phase separation energy.
Parameters:
entry: ComputedEntry object
Returns:
tuple: (decomposition_dict, phase_separation_energy)
"""
def get_phase_separation_energy(self, entry):
"""
Get phase separation energy for entry.
Parameters:
entry: ComputedEntry object
Returns:
float: Phase separation energy in eV/atom
"""
def get_form_energy(self, entry):
"""
Get formation energy for entry.
Parameters:
entry: ComputedEntry object
Returns:
float: Formation energy in eV/atom
"""
def get_form_energy_per_atom(self, entry):
"""
Get formation energy per atom.
Parameters:
entry: ComputedEntry object
Returns:
float: Formation energy in eV/atom
"""
def get_critical_compositions(self, comp1, comp2):
"""
Get critical compositions along tie line.
Parameters:
comp1, comp2: End-point compositions
Returns:
list: Critical compositions along tie line
"""
def get_element_profile(self, element, comp, comp_tol=1e-5):
"""
Get element profile across composition space.
Parameters:
element: Element of interest
comp: Reference composition
comp_tol: Composition tolerance
Returns:
list: Element profile data
"""
def get_chempot_range_map(self, elements, referenced=True, joggle=True):
"""
Get chemical potential range map.
Parameters:
elements: Elements for chemical potential analysis
referenced: Whether to reference to pure elements
joggle: Whether to joggle duplicate points
Returns:
dict: Chemical potential ranges by phase
"""
def get_all_chempots(self, comp):
"""
Get all possible chemical potentials for composition.
Parameters:
comp: Composition object or dict
Returns:
dict: Chemical potentials by element
"""
def getmu_vertices_stability_phase(self, target_comp, dep_elt, tol_en=1e-2):
"""
Get chemical potential vertices for stability analysis.
Parameters:
target_comp: Target composition
dep_elt: Dependent element
tol_en: Energy tolerance
Returns:
list: Chemical potential vertices
"""
@property
def elements(self):
"""Elements in the phase diagram."""
@property
def all_entries(self):
"""All entries in the phase diagram."""
@property
def stable_entries(self):
"""Entries on the convex hull (stable phases)."""
@property
def unstable_entries(self):
"""Entries above the convex hull (unstable phases)."""
@property
def el_refs(self):
"""Elemental reference entries."""
@property
def facets(self):
"""Facets of the convex hull."""
@property
def qhull_data(self):
"""QHull convex hull data."""
@property
def dim(self):
"""Dimensionality of the phase diagram."""
@property
def volume(self):
"""Volume of the convex hull."""class CompoundPhaseDiagram:
"""
Phase diagram for compound systems with terminal compounds.
Parameters:
- entries: List of ComputedEntry objects
- terminal_compositions: Terminal compound compositions
"""
def __init__(self, entries, terminal_compositions): ...
def get_compound_pd(self):
"""
Get compound phase diagram.
Returns:
PhaseDiagram: Phase diagram for compound system
"""
@property
def terminal_compositions(self):
"""Terminal compound compositions."""
@property
def original_entries(self):
"""Original entries before transformation."""class GrandPotentialPhaseDiagram:
"""
Grand potential phase diagram with open elements.
Parameters:
- entries: List of ComputedEntry objects
- chempots: Chemical potentials dict {element: potential}
- elements: Elements to include in diagram
"""
def __init__(self, entries, chempots, elements=None): ...
@property
def chempots(self):
"""Chemical potentials dictionary."""
@property
def original_entries(self):
"""Original entries before grand potential transformation."""Pourbaix Diagrams
Electrochemical phase diagrams showing stable phases as functions of pH and potential.
class PourbaixDiagram:
"""
Pourbaix (pH-potential) diagram construction and analysis.
Parameters:
- entries: List of PourbaixEntry objects
- comp_dict: Composition dictionary for normalization
- conc_dict: Concentration dictionary for species
- filter_solids: Whether to filter out solids
- nproc: Number of processes for parallel computation
"""
def __init__(self, entries, comp_dict=None, conc_dict=None,
filter_solids=True, nproc=None): ...
def get_stable_entry(self, pH, V):
"""
Get stable entry at given pH and potential.
Parameters:
pH: pH value
V: Potential in V vs SHE
Returns:
PourbaixEntry: Stable entry at (pH, V)
"""
def get_decomposition_energy(self, entry, pH, V):
"""
Get decomposition energy for entry at pH and potential.
Parameters:
entry: PourbaixEntry to analyze
pH: pH value
V: Potential in V vs SHE
Returns:
float: Decomposition energy in eV
"""
def solve_equilibrium_point(self, entry1, entry2, pH=None, V=None):
"""
Solve equilibrium point between two entries.
Parameters:
entry1, entry2: PourbaixEntry objects
pH: Fixed pH (if V is variable)
V: Fixed potential (if pH is variable)
Returns:
tuple: (pH, V) at equilibrium
"""
def get_pourbaix_domains(self, limits=None):
"""
Get Pourbaix stability domains.
Parameters:
limits: [(pH_min, pH_max), (V_min, V_max)] limits
Returns:
list: List of stability domains
"""
def get_hull_energy(self, pH, V):
"""
Get hull energy at pH and potential.
Parameters:
pH: pH value
V: Potential in V vs SHE
Returns:
float: Hull energy
"""
@property
def stable_entries(self):
"""Stable entries in the Pourbaix diagram."""
@property
def unstable_entries(self):
"""Unstable entries in the Pourbaix diagram."""
@property
def all_entries(self):
"""All entries in the Pourbaix diagram."""class PourbaixEntry:
"""
Entry for Pourbaix diagram analysis.
Parameters:
- entry: ComputedEntry or other entry object
- entry_id: Unique identifier for the entry
- concentration: Species concentration
"""
def __init__(self, entry, entry_id=None, concentration=1e-6): ...
def g(self, pH, V, ionic_strength=0):
"""
Get Gibbs free energy at pH and potential.
Parameters:
pH: pH value
V: Potential in V vs SHE
ionic_strength: Ionic strength
Returns:
float: Gibbs free energy
"""
def get_element_fraction(self, element):
"""
Get fraction of element in entry.
Parameters:
element: Element object or symbol
Returns:
float: Element fraction
"""
@property
def name(self):
"""Entry name."""
@property
def charge(self):
"""Entry charge."""
@property
def composition(self):
"""Entry composition."""
@property
def energy(self):
"""Entry energy."""
@property
def elements(self):
"""Elements in entry."""
@property
def concentration(self):
"""Species concentration."""
@property
def npH(self):
"""Number of H+ in formation reaction."""
@property
def nPhi(self):
"""Number of electrons in formation reaction."""
@property
def conc_term(self):
"""Concentration term contribution."""Chemical Potential Diagrams
Analysis of chemical potential relationships and stability regions.
class ChemicalPotentialDiagram:
"""
Chemical potential diagram construction and analysis.
Parameters:
- entries: List of ComputedEntry objects
- limits: Chemical potential limits
- default_min_limit: Default minimum chemical potential limit
"""
def __init__(self, entries, limits=None, default_min_limit=-50.0): ...
def get_plot(self, elements=None, label_stable=True, colormap="plasma",
label_unstable=True, process_attributes=False, plt_kwargs=None):
"""
Get chemical potential plot.
Parameters:
elements: Elements to plot (default: first 2-3)
label_stable: Whether to label stable regions
colormap: Matplotlib colormap
label_unstable: Whether to label unstable phases
process_attributes: Whether to process phase attributes
plt_kwargs: Additional plot arguments
Returns:
matplotlib.pyplot: Plot object
"""
def get_hyperplane_intersection(self, hyperplanes, open_el):
"""
Get intersection of hyperplanes.
Parameters:
hyperplanes: List of hyperplane equations
open_el: Open element
Returns:
numpy.ndarray: Intersection coordinates
"""
def get_critical_original_kinks_multipleopen(self, element_list):
"""
Get critical kinks for multiple open elements.
Parameters:
element_list: List of open elements
Returns:
list: Critical kink points
"""
@property
def elements(self):
"""Elements in the diagram."""
@property
def entries(self):
"""Entries in the diagram."""
@property
def limits(self):
"""Chemical potential limits."""Thermodynamic Analysis
Tools for thermodynamic property calculations and analysis.
class ThermoData:
"""
Thermochemical data representation and analysis.
Parameters:
- data_type: Type of thermodynamic data
- temps: Temperature array
- values: Property values at each temperature
"""
def __init__(self, data_type, temps, values): ...
def get_interp_value(self, temp):
"""
Get interpolated value at temperature.
Parameters:
temp: Temperature in K
Returns:
float: Interpolated property value
"""
@property
def data_type(self):
"""Type of thermodynamic data."""
@property
def temps(self):
"""Temperature array."""
@property
def values(self):
"""Property values."""class QuasiHarmonicDebyeApprox:
"""
Quasi-harmonic Debye approximation for thermodynamic properties.
Parameters:
- energies: Total energies at different volumes
- volumes: Volume array
- structure: Structure object
- t_min: Minimum temperature
- t_max: Maximum temperature
- t_step: Temperature step
- eos: Equation of state to use
- pressure: Applied pressure
- poisson: Poisson ratio
- use_mie_gruneisen: Whether to use Mie-Grüneisen parameter
- anharmonic_contribution: Whether to include anharmonic effects
"""
def __init__(self, energies, volumes, structure, t_min=300.0, t_max=300.0,
t_step=100.0, eos="vinet", pressure=0.0, poisson=0.363,
use_mie_gruneisen=False, anharmonic_contribution=False): ...
def get_summary_dict(self):
"""
Get summary of thermodynamic properties.
Returns:
dict: Summary of calculated properties
"""
def get_thermal_expansion(self):
"""
Get thermal expansion coefficient.
Returns:
numpy.ndarray: Thermal expansion vs temperature
"""
def get_gruneisen_parameter(self):
"""
Get Grüneisen parameter.
Returns:
float: Grüneisen parameter
"""
def get_bulk_modulus(self):
"""
Get bulk modulus vs temperature.
Returns:
numpy.ndarray: Bulk modulus vs temperature
"""
def get_heat_capacity(self):
"""
Get heat capacity at constant volume and pressure.
Returns:
tuple: (Cv, Cp) heat capacities vs temperature
"""
def get_entropy(self):
"""
Get entropy vs temperature.
Returns:
numpy.ndarray: Entropy vs temperature
"""
def get_helmholtz_energy(self):
"""
Get Helmholtz free energy vs temperature.
Returns:
numpy.ndarray: Helmholtz energy vs temperature
"""
def get_gibbs_energy(self):
"""
Get Gibbs free energy vs temperature.
Returns:
numpy.ndarray: Gibbs energy vs temperature
"""
@property
def temperatures(self):
"""Temperature array."""
@property
def optimum_volumes(self):
"""Optimum volumes at each temperature."""Reaction Analysis
Analysis of chemical reactions and reaction energetics.
class Reaction:
"""
Chemical reaction representation and analysis.
Parameters:
- reactants: List of reactant Composition objects
- products: List of product Composition objects
"""
def __init__(self, reactants, products): ...
def copy(self):
"""
Create a copy of the reaction.
Returns:
Reaction: Copy of the reaction
"""
def reverse(self):
"""
Get reverse reaction.
Returns:
Reaction: Reversed reaction
"""
def normalize_to(self, comp, factor=1):
"""
Normalize reaction to a composition.
Parameters:
comp: Composition to normalize to
factor: Normalization factor
Returns:
Reaction: Normalized reaction
"""
def normalize_to_element(self, element, factor=1):
"""
Normalize reaction to an element.
Parameters:
element: Element to normalize to
factor: Normalization factor
Returns:
Reaction: Normalized reaction
"""
def get_el_amount(self, element):
"""
Get net amount of element in reaction.
Parameters:
element: Element object or symbol
Returns:
float: Net amount of element
"""
@property
def reactants(self):
"""Reactant compositions."""
@property
def products(self):
"""Product compositions."""
@property
def elements(self):
"""Elements involved in reaction."""
@property
def coeffs(self):
"""Reaction coefficients."""
@property
def all_comp(self):
"""All compositions in reaction."""
@property
def normalized_repr(self):
"""Normalized string representation."""class BalancedReaction:
"""
Balanced chemical reaction with automatic balancing.
Parameters:
- reactants_coeffs: Dict of {Composition: coefficient} for reactants
- products_coeffs: Dict of {Composition: coefficient} for products
"""
def __init__(self, reactants_coeffs, products_coeffs): ...
@classmethod
def from_string(cls, rxn_string):
"""
Create balanced reaction from string.
Parameters:
rxn_string: Reaction string (e.g., "2 H2 + O2 -> 2 H2O")
Returns:
BalancedReaction: Balanced reaction object
"""
def calculate_energy(self, energies):
"""
Calculate reaction energy from formation energies.
Parameters:
energies: Dict of {Composition: formation_energy}
Returns:
float: Reaction energy
"""
@property
def normalized_repr_and_factor(self):
"""Normalized representation and normalization factor."""class ComputedReaction:
"""
Computed chemical reaction with energies from DFT calculations.
Parameters:
- reactant_entries: List of reactant ComputedEntry objects
- product_entries: List of product ComputedEntry objects
"""
def __init__(self, reactant_entries, product_entries): ...
def calculate_energy(self):
"""
Calculate reaction energy from computed entries.
Returns:
float: Reaction energy in eV per formula unit
"""
@property
def calculated_reaction_energy(self):
"""Calculated reaction energy."""
@property
def calculated_reaction_energy_per_atom(self):
"""Calculated reaction energy per atom."""Plotting and Visualization
Classes for plotting phase diagrams and thermodynamic data.
class PDPlotter:
"""
Phase diagram plotting utility.
Parameters:
- phasediagram: PhaseDiagram object to plot
- show_unstable: Whether to show unstable phases
- backend: Plotting backend ("plotly" or "matplotlib")
"""
def __init__(self, phasediagram, show_unstable=0, backend="plotly"): ...
def get_plot(self, limits=None, title="", label_stable=True,
label_unstable=True, ordering=None, energy_colormap=None,
process_attributes=False, label_uncertainties=False):
"""
Get phase diagram plot.
Parameters:
limits: Plot limits
title: Plot title
label_stable: Whether to label stable phases
label_unstable: Whether to label unstable phases
ordering: Ordering of elements for ternary plots
energy_colormap: Colormap for energy above hull
process_attributes: Whether to process entry attributes
label_uncertainties: Whether to label energy uncertainties
Returns:
matplotlib.pyplot or plotly.graph_objects: Plot object
"""
def show(self, *args, **kwargs):
"""Show phase diagram plot."""
def get_contour_pd_plot(self, limits=None):
"""
Get contour plot for 3+ component phase diagrams.
Parameters:
limits: Plot limits
Returns:
matplotlib.pyplot: Contour plot
"""
def get_chempot_range_map_plot(self, elements, referenced=True):
"""
Get chemical potential range map plot.
Parameters:
elements: Elements for chemical potential analysis
referenced: Whether to reference to pure elements
Returns:
matplotlib.pyplot: Chemical potential range map
"""
def write_image(self, stream, fmt="png"):
"""
Write plot image to stream.
Parameters:
stream: Output stream
fmt: Image format
"""class PourbaixPlotter:
"""
Pourbaix diagram plotting utility.
Parameters:
- pourbaix_diagram: PourbaixDiagram object to plot
"""
def __init__(self, pourbaix_diagram): ...
def get_pourbaix_plot(self, limits=None, title="", label_domains=True,
label_fontsize=20, show_water_lines=True,
show_neutral_axes=True, alpha=0.2, ax=None):
"""
Get Pourbaix diagram plot.
Parameters:
limits: [(pH_min, pH_max), (V_min, V_max)] limits
title: Plot title
label_domains: Whether to label stability domains
label_fontsize: Font size for labels
show_water_lines: Whether to show water stability lines
show_neutral_axes: Whether to show neutral pH/V axes
alpha: Transparency for domain colors
ax: Matplotlib axes object
Returns:
matplotlib.pyplot: Pourbaix plot
"""
def plot_entry_stability(self, entry, pH_range=None, pH_resolution=100,
V_range=None, V_resolution=100, e_hull_max=1,
cmap="RdYlBu_r", ax=None, **kwargs):
"""
Plot stability of specific entry across pH-V space.
Parameters:
entry: PourbaixEntry to analyze
pH_range: pH range for analysis
pH_resolution: pH resolution
V_range: Potential range for analysis
V_resolution: Potential resolution
e_hull_max: Maximum energy above hull to show
cmap: Colormap for stability
ax: Matplotlib axes object
Returns:
matplotlib.pyplot: Entry stability plot
"""
def show(self, *args, **kwargs):
"""Show Pourbaix plot."""Utility Functions
Helper functions for thermodynamic calculations and phase analysis.
def unique_lines(list1, list2, prec=3):
"""
Find unique lines between two lists of points.
Parameters:
list1, list2: Lists of points
prec: Precision for uniqueness determination
Returns:
list: Unique lines
"""
def order_phase_diagram(lines, stable_entries, unstable_entries, ordering):
"""
Order phase diagram for consistent plotting.
Parameters:
lines: Phase diagram lines
stable_entries: Stable phase entries
unstable_entries: Unstable phase entries
ordering: Element ordering
Returns:
tuple: Ordered diagram components
"""
def triangular_coord(coord):
"""
Convert 3D coordinates to triangular coordinates for ternary plots.
Parameters:
coord: 3D coordinates
Returns:
numpy.ndarray: Triangular coordinates
"""
def tet_coord(coord):
"""
Convert 4D coordinates to tetrahedral coordinates for quaternary plots.
Parameters:
coord: 4D coordinates
Returns:
numpy.ndarray: Tetrahedral coordinates
"""Install with Tessl CLI
npx tessl i tessl/pypi-pymatgen