pymatgen.analysis.pourbaix_diagram module
This module is intended to be used to compute Pourbaix diagrams of arbitrary compositions and formation energies. If you use this module in your work, please consider citing the following:
- General formalism for solid-aqueous equilibria from DFT:
Persson et al., DOI: 10.1103/PhysRevB.85.235438
- Decomposition maps, or Pourbaix hull diagrams
Singh et al., DOI: 10.1021/acs.chemmater.7b03980
- Fast computation of many-element Pourbaix diagrams:
Patel et al., https://arxiv.org/abs/1909.00035 (submitted)
- class IonEntry(ion, energy, name=None, attribute=None)[source]
Bases:
pymatgen.analysis.phase_diagram.PDEntryObject similar to PDEntry, but contains an Ion object instead of a Composition object.
- name[source]
A name for the entry. This is the string shown in the phase diagrams. By default, this is the reduced formula for the composition, but can be set to some other string for display purposes.
- Parameters
ion – Ion object
energy – Energy for composition.
name – Optional parameter to name the entry. Defaults to the chemical formula.
- class MultiEntry(entry_list, weights=None)[source]
Bases:
pymatgen.analysis.pourbaix_diagram.PourbaixEntryPourbaixEntry-like object for constructing multi-elemental Pourbaix diagrams.
Initializes a MultiEntry.
- Parameters
entry_list ([PourbaixEntry]) – List of component PourbaixEntries
weights ([float]) – Weights associated with each entry. Default is None
- class PourbaixDiagram(entries: list[PourbaixEntry] | list[MultiEntry], comp_dict: dict[str, float] | None = None, conc_dict: dict[str, float] | None = None, filter_solids: bool = True, nproc: int | None = None)[source]
Bases:
monty.json.MSONableClass to create a Pourbaix diagram from entries
- Parameters
entries ([PourbaixEntry] or [MultiEntry]) – Entries list containing Solids and Ions or a list of MultiEntries
comp_dict (dict[str, float]) – Dictionary of compositions, defaults to equal parts of each elements
conc_dict (dict[str, float]) – Dictionary of ion concentrations, defaults to 1e-6 for each element
filter_solids (bool) – applying this filter to a Pourbaix diagram ensures all included solid phases are filtered by stability on the compositional phase diagram. Defaults to True. The practical consequence of this is that highly oxidized or reduced phases that might show up in experiments due to kinetic limitations on oxygen/hydrogen evolution won’t appear in the diagram, but they are not actually “stable” (and are frequently overstabilized from DFT errors). Hence, including only the stable solid phases generally leads to the most accurate Pourbaix diagrams.
nproc (int) – number of processes to generate multientries with in parallel. Defaults to None (serial processing)
- as_dict(include_unprocessed_entries=None)[source]
- Parameters
() (include_unprocessed_entries) – DEPRECATED. Whether to include unprocessed entries (equivalent to filter_solids=False). Serialization now includes all unprocessed entries by default. Set filter_solids=False before serializing to include unstable solids from the generated Pourbaix Diagram.
- Returns
MSONable dict.
- find_stable_entry(pH, V)[source]
Finds stable entry at a pH,V condition :param pH: pH to find stable entry :type pH: float :param V: V to find stable entry :type V: float
Returns:
- get_decomposition_energy(entry, pH, V)[source]
Finds decomposition to most stable entries in eV/atom, supports vectorized inputs for pH and V
- Parameters
entry (PourbaixEntry) – PourbaixEntry corresponding to compound to find the decomposition for
pH (float, [float]) – pH at which to find the decomposition
V (float, [float]) – voltage at which to find the decomposition
- Returns
- Decomposition energy for the entry, i. e. the energy above
the “Pourbaix hull” in eV/atom at the given conditions
- get_hull_energy(pH, V)[source]
Gets the minimum energy of the Pourbaix “basin” that is formed from the stable Pourbaix planes. Vectorized.
- Parameters
pH (float or [float]) – pH at which to find the hull energy
V (float or [float]) – V at which to find the hull energy
- Returns
(float or [float]) minimum Pourbaix energy at conditions
- static get_pourbaix_domains(pourbaix_entries, limits=None)[source]
Returns a set of Pourbaix stable domains (i. e. polygons) in pH-V space from a list of pourbaix_entries
This function works by using scipy’s HalfspaceIntersection function to construct all of the 2-D polygons that form the boundaries of the planes corresponding to individual entry gibbs free energies as a function of pH and V. Hyperplanes of the form a*pH + b*V + 1 - g(0, 0) are constructed and supplied to HalfspaceIntersection, which then finds the boundaries of each Pourbaix region using the intersection points.
- Parameters
pourbaix_entries ([PourbaixEntry]) – Pourbaix entries with which to construct stable Pourbaix domains
limits ([[float]]) – limits in which to do the pourbaix analysis
- Returns
[boundary_points]}. The list of boundary points are the sides of the N-1 dim polytope bounding the allowable ph-V range of each entry.
- Return type
Returns a dict of the form {entry
- get_stable_entry(pH, V)[source]
Gets the stable entry at a given pH, V condition
- Parameters
pH (float) – pH at a given condition
V (float) – V at a given condition
- Returns
- Pourbaix or multi-entry
corresponding ot the minimum energy entry at a given pH, V condition
- Return type
(PourbaixEntry or MultiEntry)
- static process_multientry(entry_list, prod_comp, coeff_threshold=0.0001)[source]
Static method for finding a multientry based on a list of entries and a product composition. Essentially checks to see if a valid aqueous reaction exists between the entries and the product composition and returns a MultiEntry with weights according to the coefficients if so.
- Parameters
entry_list ([Entry]) – list of entries from which to create a MultiEntry
prod_comp (Composition) – composition constraint for setting weights of MultiEntry
coeff_threshold (float) – threshold of stoichiometric coefficients to filter, if weights are lower than this value, the entry is not returned
- class PourbaixEntry(entry, entry_id=None, concentration=1e-06)[source]
Bases:
monty.json.MSONable,pymatgen.util.string.StringifyAn object encompassing all data relevant to a solid or ion in a Pourbaix diagram. Each bulk solid/ion has an energy g of the form: e = e0 + 0.0591 log10(conc) - nO mu_H2O + (nH - 2nO) pH + phi (-nH + 2nO + q)
Note that the energies corresponding to the input entries should be formation energies with respect to hydrogen and oxygen gas in order for the Pourbaix diagram formalism to work. This may be changed to be more flexible in the future.
- Parameters
entry (ComputedEntry/ComputedStructureEntry/PDEntry/IonEntry) – An entry object
() (concentration) –
() –
- as_dict()[source]
Returns dict which contains Pourbaix Entry data. Note that the pH, voltage, H2O factors are always calculated when constructing a PourbaixEntry object.
- property conc_term[source]
Returns the concentration contribution to the free energy, and should only be present when there are ions in the entry
- property energy[source]
returns energy
- Returns (float): total energy of the Pourbaix
entry (at pH, V = 0 vs. SHE)
- energy_at_conditions(pH, V)[source]
Get free energy for a given pH and V
- Parameters
pH (float) – pH at which to evaluate free energy
V (float) – voltage at which to evaluate free energy
- Returns
free energy at conditions
- property energy_per_atom[source]
energy per atom of the Pourbaix entry
Returns (float): energy per atom
- get_element_fraction(element)[source]
Gets the elemental fraction of a given non-OH element
- Parameters
element (Element or str) – string or element corresponding to element to get from composition
- Returns
fraction of element / sum(all non-OH elements)
- property normalization_factor[source]
Sum of number of atoms minus the number of H and O in composition
- property normalized_energy[source]
Returns: energy normalized by number of non H or O atoms, e. g. for Zn2O6, energy / 2 or for AgTe3(OH)3, energy / 4
- class PourbaixPlotter(pourbaix_diagram)[source]
Bases:
objectA plotter class for phase diagrams.
- Parameters
pourbaix_diagram (PourbaixDiagram) – A PourbaixDiagram object.
- domain_vertices(entry)[source]
Returns the vertices of the Pourbaix domain.
- Parameters
entry – Entry for which domain vertices are desired
- Returns
list of vertices
- get_pourbaix_plot(limits=None, title='', label_domains=True, label_fontsize=20, show_water_lines=True, show_neutral_axes=True, plt=None)[source]
Plot Pourbaix diagram.
- Parameters
limits – 2D list containing limits of the Pourbaix diagram of the form [[xlo, xhi], [ylo, yhi]]
title (str) – Title to display on plot
label_domains (bool) – whether to label Pourbaix domains
label_fontsize – font size for domain labels
show_water_lines – whether to show dashed lines indicating the region of water stability.
lines (show_neutral_axes; whether to show dashed horizontal and vertical) – at 0 V and pH 7, respectively.
plt (pyplot) – Pyplot instance for plotting
- Returns
plt (pyplot) - matplotlib plot object with Pourbaix diagram
- generate_entry_label(entry)[source]
Generates a label for the Pourbaix plotter
- Parameters
entry (PourbaixEntry or MultiEntry) – entry to get a label for