Plotting a pourbaix diagram using the Materials Project API

The Materials Project REST interface includes functionality to construct pourbaix diagrams from computed entries. Note that the Pourbaix infrastructure is still undergoing revision, but now includes a simplified interface that enables MP and pymatgen users to fetch entries that have been processed according to the Materials Project Aqueous Compatibility scheme. Thus, users can reproduce web Pourbaix diagrams in two or three steps in pymatgen.

In [1]:
# Import necessary tools from pymatgen
from pymatgen import MPRester
from pymatgen.analysis.pourbaix.maker import PourbaixDiagram
from pymatgen.analysis.pourbaix.analyzer import PourbaixAnalyzer
from pymatgen.analysis.pourbaix.plotter import PourbaixPlotter
%matplotlib inline

# Initialize the MP Rester
mpr = MPRester()

To retrieve entries necessary to construct a Pourbaix Diagram use MPRester.get_pourbaix_entries(LIST_OF_ENTRIES) with a list of entries comprising your chemical system. It is not necessary to include 'O' and 'H' in your list, as they are added automatically. This function also contains all of necessary preprocessing to ensure the PourbaixEntries are compatible with the pymatgen PourbaixDiagram constructor.

In [2]:
# Get all pourbaix entries corresponding to the Cu-O-H chemical system.
entries = mpr.get_pourbaix_entries(["Cu"])

Pourbaix diagrams can be constructed using PourbaixDiagram(RETRIEVED_ENTRIES) as below. Note that a comp_dict keyword argument may also be supplied to the PourbaixDiagram constructor if a fixed composition for a multi-element pourbaix diagram is desired.

In [3]:
# Construct the PourbaixDiagram object
pd = PourbaixDiagram(entries)

The PourbaixAnalyzer includes a number of useful functions for determining stable species and stability of entries relative to a given pourbaix facet (i.e. as a function of pH and V).

In [4]:
# Construct the pourbaix analyzer
pa = PourbaixAnalyzer(pd)

# Get an entry stability as a function of pH and V
entry = [e for e in entries if e.entry_id == 'mp-1692'][0]
print("CuO's potential energy per atom relative to the most",
      "stable decomposition product is {} eV/atom".format(
          pa.get_entry_stability(entry, pH=7, V=-0.2)))
CuO's potential energy per atom relative to the most stable decomposition product is 0.4404188837500014 eV/atom

This suggests that CuO, for example, has a large driving force for decomposition at neutral pH and mildly reducing conditions.

To see this in more detail, we can plot the pourbaix diagram. The PourbaixPlotter object is also initialized using an instance of the PourbaixDiagram object.

In [5]:
plotter = PourbaixPlotter(pd)
In [6]:

The PourbaixPlotter object can also plot the relative stability of an entry across the pourbaix diagram. To do this, use the PourbaixPlotter.plot_entry_stability method.

In [7]:
plt = plotter.plot_entry_stability(entry)

Plotting k-nary systems

Pymatgen also supports binary/ternary pourbaix diagrams with fixed compositions of the non-H or O elements. This is achieved by finding all possible combinations of entries that fulfill the composition constraint and treating them as individual entries in pourbaix space. Note that you can supply a composition dictionary and to further tune the pourbaix diagram.

In [8]:
# Get all pourbaix entries corresponding to the Fe-O-H chemical system.
entries = mpr.get_pourbaix_entries(["Bi", "V"])
# Construct the PourbaixDiagram object
pd = PourbaixDiagram(entries, comp_dict={"Bi": 0.5, "V": 0.5},
                     conc_dict={"Bi": 1e-8, "V": 1e-8})
In [9]:
# Construct the pourbaix analyzer
pa = PourbaixAnalyzer(pd)
plotter = PourbaixPlotter(pd)
plt = plotter.get_pourbaix_plot()

Getting the heatmaps for a solid entry in these cases is a bit more involved, because many of the regions of the pourbaix diagram include multiphase entries. Here's an example for this case.

In [10]:
bivo4_entry = [entry for entry in entries if entry.entry_id=="mp-613172"][0]
plt = plotter.plot_entry_stability(bivo4_entry)
/Users/josephmontoya/pylib/pymatgen/pymatgen/analysis/pourbaix/ UserWarning: VBiO4(s) is not a multi-entry, calculating stability of representative multientries
  "representative multientries".format(

If a compound is provided that doesn't meet the constraints of the composition (in this case, equal parts Bi and V), the plotter will attempt to find the most stable entry containing that solid and any spectating ions. In this case, it estimates the stability of BiO$_2$(s) + VO$_4$-.

In [11]:
bio2_entry = [entry for entry in entries if entry.entry_id=="mp-557993"][0]
plt = plotter.plot_entry_stability(bio2_entry)
/Users/josephmontoya/pylib/pymatgen/pymatgen/analysis/pourbaix/ UserWarning: BiO2(s) is not a multi-entry, calculating stability of representative multientries
  "representative multientries".format(