# 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)

  Bases: `pymatgen.analysis.phase_diagram.PDEntry`

  Object similar to PDEntry, but contains an Ion object instead of a Composition object.

  name

    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.

  as_dict()

    Creates a dict of composition, energy, and ion name

  classmethod from_dict(d)

    Returns an IonEntry object from a dict.

class MultiEntry(entry_list, weights=None)

  Bases: `pymatgen.analysis.pourbaix_diagram.PourbaixEntry`

  PourbaixEntry-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

  as_dict()

    Returns: MSONable dict

  classmethod from_dict(d)
    Parameters

      () (d) – Dict representation

    Returns

      MultiEntry

  property name

    MultiEntry name, i. e. the name of each entry joined by ‘ + ‘

class PourbaixDiagram(entries: Union[List[pymatgen.analysis.pourbaix_diagram.PourbaixEntry], List[pymatgen.analysis.pourbaix_diagram.MultiEntry]], comp_dict: Optional[Dict[str, float]] = None, conc_dict: Optional[Dict[str, float]] = None, filter_solids: bool = True, nproc: Optional[int] = None)

  Bases: `monty.json.MSONable`

  Class to create a Pourbaix diagram from entries

  Parameters

    - entries ([PourbaixEntry] or [MultiEntry]) – Entries list containing Solids and Ions or a list of MultiEntries

    - ({str (conc_dict) – float}): Dictionary of compositions, defaults to equal parts of each elements

    - ({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)

  property all_entries

    Return all entries used to generate the pourbaix diagram

  as_dict(include_unprocessed_entries=None)
    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)

    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:

  classmethod from_dict(d)
    Parameters

      () (d) – Dict representation.

    Returns

      PourbaixDiagram

  get_decomposition_energy(entry, pH, V)

    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)

    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)

    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)

    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)

    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

  property stable_entries

    Returns the stable entries in the Pourbaix diagram.

  property unprocessed_entries

    Return unprocessed entries

  property unstable_entries

    Returns all unstable entries in the Pourbaix diagram

class PourbaixEntry(entry, entry_id=None, concentration=1e-06)

  Bases: `monty.json.MSONable`, `pymatgen.util.string.Stringify`

  An 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()

    Returns dict which contains Pourbaix Entry data. Note that the pH, voltage, H2O factors are always calculated when constructing a PourbaixEntry object.

  property composition

    Returns composition

  property conc_term

    Returns the concentration contribution to the free energy, and should only be present when there are ions in the entry

  property energy

    returns energy

    Returns (float): total energy of the pourbaix

      entry (at pH, V = 0 vs. SHE)

  energy_at_conditions(pH, V)

    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

    energy per atom of the pourbaix entry

    Returns (float): energy per atom

  classmethod from_dict(d)

    Invokes a PourbaixEntry from a dictionary

  get_element_fraction(element)

    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 nH2O

    Number of H2O.

    Type

      Returns

  property nPhi

    Number of H2O.

    Type

      Returns

  property name

    Name for entry

    Type

      Returns

  property normalization_factor

    Sum of number of atoms minus the number of H and O in composition

  property normalized_energy

    Returns: energy normalized by number of non H or O atoms, e. g. for Zn2O6, energy / 2 or for AgTe3(OH)3, energy / 4

  normalized_energy_at_conditions(pH, V)

    Energy at an electrochemical condition, compatible with numpy arrays for pH/V input

    Parameters

      - pH (float) – pH at condition

      - V (float) – applied potential at condition

    Returns

      energy normalized by number of non-O/H atoms at condition

  property npH

    Returns:

  property num_atoms

    Return number of atoms in current formula. Useful for normalization

  to_pretty_string() → str
    Returns

      A pretty string representation.

class PourbaixPlotter(pourbaix_diagram)

  Bases: `object`

  A plotter class for phase diagrams.

  Parameters

    pourbaix_diagram (PourbaixDiagram) – A PourbaixDiagram object.

  domain_vertices(entry)

    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, plt=None)

    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

      - plt (pyplot) – Pyplot instance for plotting

    Returns

      plt (pyplot) - matplotlib plot object with pourbaix diagram

  plot_entry_stability(entry, pH_range=None, pH_resolution=100, V_range=None, V_resolution=100, e_hull_max=1, cmap='RdYlBu_r', **kwargs)
    Parameters

      - () (**kwargs) –

      - () –

      - () –

      - () –

      - () –

      - () –

      - () –

      - () –

    Returns:

  show(*args, **kwargs)

    Shows the pourbaix plot

    Parameters

      - *args – args to get_pourbaix_plot

      - **kwargs – kwargs to get_pourbaix_plot

    Returns

      None

generate_entry_label(entry)

  Generates a label for the pourbaix plotter

  Parameters

    entry (PourbaixEntry or MultiEntry) – entry to get a label for

ion_or_solid_comp_object(formula)

  Returns either an ion object or composition object given a formula.

  Parameters

    formula – String formula. Eg. of ion: NaOH(aq), Na[+]; Eg. of solid: Fe2O3(s), Fe(s), Na2O

  Returns

    Composition/Ion object