phasediagram Package

phasediagram Package

The phasediagram package implements the analysis tools to perform phase stability analyses, including the constructing of phase diagrams, determination of decomposition products, etc. The package is designed to be fairly modular and standalone.

entries Module

This module defines PDEntry, which wraps information (composition and energy) necessary to create phase diagrams.

class GrandPotPDEntry(entry, chempots, name=None)

Bases: pymatgen.phasediagram.entries.PDEntry

A grand potential pd entry object encompassing all relevant data for phase diagrams. Chemical potentials are given as a element-chemical potential dict.

Args:

entry:

A PDEntry-like object.

chempots:

Chemical potential specification as {Element: float}.

name:

Optional parameter to name the entry. Defaults to the reduced chemical formula of the original entry.

classmethod from_dict(d)

is_element

True if the entry is an element.

original_entry

Original entry.

to_dict

class PDEntry(composition, energy, name=None)

Bases: pymatgen.serializers.json_coders.MSONable

An object encompassing all relevant data for phase diagrams.

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.

Args:

comp:

Composition as a pymatgen.core.structure.Composition

energy:

Energy for composition.

name:

Optional parameter to name the entry. Defaults to the reduced chemical formula.

composition

Returns the composition.

energy

Returns the final energy.

energy_per_atom

Returns the final energy per atom.

classmethod from_dict(d)

is_element

True if the entry is an element.

to_dict

class PDEntryIO

Bases: object

Utility class to export and import PDEntry to and from csv files, as well as to and from json.

static from_csv(filename)

Imports PDEntries from a csv

Args:

filename - Filename to import from.

Returns:

List of Elements, List of PDEntries

static to_csv(filename, entries, latexify_names=False)

Exports PDEntries to a csv

Args:

filename:

Filename to write to.

entries:

PDEntries to export.

latexify_names:

Format entry names to be LaTex compatible, e.g., Li_{2}O

class TransformedPDEntry(comp, original_entry)

Bases: pymatgen.phasediagram.entries.PDEntry

This class repesents a TransformedPDEntry, which allows for a PDEntry to be transformed to a different composition coordinate space. It is used in the construction of phase diagrams that do not have elements as the terminal compositions.

Args:

comp:

Transformed composition as a Composition.

energy:

Energy for composition.

original_entry:

Original entry that this entry arose from.

classmethod from_dict(d)

original_entry

Original PDEntry object.

to_dict

pdanalyzer Module

This module provides classes for analyzing phase diagrams.

class PDAnalyzer(pd)

Bases: object

A class for performing analyses on Phase Diagrams.

The algorithm is based on the work in the following papers:

1. S. P. Ong, L. Wang, B. Kang, and G. Ceder, Li-Fe-P-O2 Phase Diagram from First Principles Calculations. Chem. Mater., 2008, 20(5), 1798-1807. doi:10.1021/cm702327g
2. S. P. Ong, A. Jain, G. Hautier, B. Kang, G. Ceder, Thermal stabilities of delithiated olivine MPO4 (M=Fe, Mn) cathodes investigated using first principles calculations. Electrochem. Comm., 2010, 12(3), 427-430. doi:10.1016/j.elecom.2010.01.010

Args:

pd:

Phase Diagram to analyze.

get_chempot_range_map(elements)

Returns a chemical potential range map for each stable entry.

Args:

elements:

Sequence of elements to be considered as independent variables. E.g., if you want to show the stability ranges of all Li-Co-O phases wrt to uLi and uO, you will supply [Element(“Li”), Element(“O”)]

Returns:

Returns a dict of the form {entry: [simplices]}. The list of simplices are the sides of the N-1 dim polytope bounding the allowable chemical potential range of each entry.

get_decomp_and_e_above_hull(entry, allow_negative=False)

Provides the decomposition and energy above convex hull for an entry

Args:

entry:

A PDEntry like object

allow_negative:

Whether to allow negative e_above_hulls. Used to calculate equilibrium reaction energies. Default False.

Returns:

(decomp, energy above convex hull) Stable entries should have energy above hull of 0. The decomposition is provided as a dict of {Entry: amount}.

get_decomposition(comp)

Provides the decomposition at a particular composition

Args:

comp:

A composition

Returns:

Decomposition as a dict of {Entry: amount}

get_e_above_hull(entry)

Provides the energy above convex hull for an entry

Args:

entry - A PDEntry like object

Returns:

Energy above convex hull of entry. Stable entries should have energy above hull of 0.

get_element_profile(element, comp, comp_tol=1e-05)

Provides the element evolution data for a composition. For example, can be used to analyze Li conversion voltages by varying uLi and looking at the phases formed. Also can be used to analyze O2 evolution by varying uO2.

Args:

element:

An element. Must be in the phase diagram.

comp:

A Composition

comp_tol:

The tolerance to use when calculating decompositions. Phases with amounts less than this tolerance are excluded. Defaults to 1e-5.

Returns:

Evolution data as a list of dictionaries of the following format: [ {‘chempot’: -10.487582010000001, ‘evolution’: -2.0, ‘reaction’: Reaction Object], ...]

get_equilibrium_reaction_energy(entry)

Provides the reaction energy of a stable entry from the neighboring equilibrium stable entries (also known as the inverse distance to hull).

Args:

entry:

A PDEntry like object

Returns:

Equilibrium reaction energy of entry. Stable entries should have equilibrium reaction energy <= 0.

get_facet_chempots(facet)

Calculates the chemical potentials for each element within a facet.

Args:

facet:

Facet of the phase diagram.

Returns:

{ element: chempot } for all elements in the phase diagram.

get_transition_chempots(element)

Get the critical chemical potentials for an element in the Phase Diagram.

Args:

element:

An element. Has to be in the PD in the first place.

Returns:

A sorted sequence of critical chemical potentials, from less negative to more negative.

numerical_tol = 1e-08

pdmaker Module

This module provides classes to create phase diagrams.

class CompoundPhaseDiagram(entries, terminal_compositions, normalize_terminal_compositions=True)

Bases: pymatgen.phasediagram.pdmaker.PhaseDiagram

Generates phase diagrams from compounds as terminations instead of elements.

Args:

entries:

Sequence of input entries. For example, if you want a Li2O-P2O5 phase diagram, you might have all Li-P-O entries as an input.

terminal_compositions:

Terminal compositions of phase space. In the Li2O-P2O5 example, these will be the Li2O and P2O5 compositions.

normalize_terminal_compositions:

Whether to normalize the terminal compositions to a per atom basis. If normalized, the energy above hulls will be consistent for comparison across systems. Non-normalized terminals are more intuitive in terms of compositional breakdowns.

amount_tol = 1e-05

transform_entries(entries, terminal_compositions)

Method to transform all entries to the composition coordinate in the terminal compositions. If the entry does not fall within the space defined by the terminal compositions, they are excluded. For example, Li3PO4 is mapped into a Li2O:1.5, P2O5:0.5 composition. The terminal compositions are represented by DummySpecies.

Args:

entries:

Sequence of all input entries

terminal_compositions:

Terminal compositions of phase space.

Returns:

Sequence of TransformedPDEntries falling within the phase space.

class GrandPotentialPhaseDiagram(entries, chempots, elements=None)

Bases: pymatgen.phasediagram.pdmaker.PhaseDiagram

A class representing a Grand potential phase diagram. Grand potential phase diagrams are essentially phase diagrams that are open to one or more components. To construct such phase diagrams, the relevant free energy is the grand potential, which can be written as the Legendre transform of the Gibbs free energy as follows

Grand potential = G - u_X N_X The algorithm is based on the work in the following papers:

1. S. P. Ong, L. Wang, B. Kang, and G. Ceder, Li-Fe-P-O2 Phase Diagram from First Principles Calculations. Chem. Mater., 2008, 20(5), 1798-1807. doi:10.1021/cm702327g
2. S. P. Ong, A. Jain, G. Hautier, B. Kang, G. Ceder, Thermal stabilities of delithiated olivine MPO4 (M=Fe, Mn) cathodes investigated using first principles calculations. Electrochem. Comm., 2010, 12(3), 427-430. doi:10.1016/j.elecom.2010.01.010

Standard constructor for grand potential phase diagram.

Args:

entries:

A list of PDEntry-like objects having an energy, energy_per_atom and composition.

chempots:

A dict of {element: float} to specify the chemical potentials of the open elements.

elements:

Optional list of elements in the phase diagram. If set to None, the elements are determined from the entries themselves.

class PhaseDiagram(entries, elements=None)

Bases: object

Simple phase diagram class taking in elements and entries as inputs. The algorithm is based on the work in the following papers:

1. S. P. Ong, L. Wang, B. Kang, and G. Ceder, Li-Fe-P-O2 Phase Diagram from First Principles Calculations. Chem. Mater., 2008, 20(5), 1798-1807. doi:10.1021/cm702327g
2. S. P. Ong, A. Jain, G. Hautier, B. Kang, G. Ceder, Thermal stabilities of delithiated olivine MPO4 (M=Fe, Mn) cathodes investigated using first principles calculations. Electrochem. Comm., 2010, 12(3), 427-430. doi:10.1016/j.elecom.2010.01.010

..attribute: all_entries

All entries provided for Phase Diagram construction. Note that this does not mean that all these entries are actually used in the phase diagram. For example, this includes the positive formation energy entries that are filtered out before Phase Diagram construction.

Standard constructor for phase diagram.

Args:

entries:

A list of PDEntry-like objects having an energy, energy_per_atom and composition.

elements:

Optional list of elements in the phase diagram. If set to None, the elements are determined from the the entries themselves.

formation_energy_tol = 1e-11

get_form_energy(entry)

Returns the formation energy for an entry (NOT normalized) from the elemental references.

Args:

entry:

A PDEntry-like object.

Returns:

Formation energy from the elemental references.

get_form_energy_per_atom(entry)

Returns the formation energy per atom for an entry from the elemental references.

Args:

entry:

An PDEntry-like object

Returns:

Formation energy per atom from the elemental references.

stable_entries

Returns the stable entries in the phase diagram.

unstable_entries

Entries that are unstable in the phase diagram. Includes positive formation energy entries.

exception PhaseDiagramError

Bases: exceptions.Exception

An exception class for Phase Diagram generation.

plotter Module

This module provides classes for plotting PhaseDiagram objects.

class PDPlotter(phasediagram, show_unstable=False)

Bases: object

A plotter class for phase diagrams.

Args:

phasediagram:

A PhaseDiagram object.

show_unstable:

Whether unstable phases will be plotted as well as red crosses. Defaults to False.

get_chempot_range_map_plot(elements)

Returns a plot of the chemical potential range map. Currently works only for 3-component PDs.

Args:

elements:

Sequence of elements to be considered as independent variables. E.g., if you want to show the stability ranges of all Li-Co-O phases wrt to uLi and uO, you will supply [Element(“Li”), Element(“O”)]

Returns:

A matplotlib plot object.

get_contour_pd_plot()

Plot a contour phase diagram plot, where phase triangles are colored according to degree of instability by interpolation. Currently only works for 3-component phase diagrams.

Returns:

A matplotlib plot object.

pd_plot_data

Plot data for phase diagram. 2-comp - Full hull with energies 3/4-comp - Projection into 2D or 3D Gibbs triangle.

Returns:

(lines, stable_entries, unstable_entries):

• lines is a list of list of coordinates for lines in the PD.
• stable_entries is a {coordinate : entry} for each stable node in the phase diagram. (Each coordinate can only have one stable phase)
• unstable_entries is a {entry: coordinates} for all unstable nodes in the phase diagram.

plot_chempot_range_map(elements)

Plot the chemical potential range map. Currently works only for 3-component PDs.

Args:

elements:

Sequence of elements to be considered as independent variables. E.g., if you want to show the stability ranges of all Li-Co-O phases wrt to uLi and uO, you will supply [Element(“Li”), Element(“O”)]

show(label_stable=True, label_unstable=True)

Draws the phase diagram using Matplotlib and show it.

write_image(stream, image_format='svg')

Writes the phase diagram to an image in a stream.

Args:

stream:

stream to write to. Can be a file stream or a StringIO stream.

image_format

format for image. Can be any of matplotlib supported formats. Defaults to svg for best results for vector graphics.

tet_coord(coord)

Convert a 3D coordinate into a tetrahedron based coordinate system for a prettier phase diagram.

Args:

coordinate:

coordinate used in the convex hull computation.

Returns:

coordinates in a tetrahedron-based coordinate system.

triangular_coord(coord)

Convert a 2D coordinate into a triangle-based coordinate system for a prettier phase diagram.

Args:

coordinate:

coordinate used in the convex hull computation.

Returns:

coordinates in a triangular-based coordinate system.

uniquelines(q)

Given all the facets, convert it into a set of unique lines. Specifically used for converting convex hull facets into line pairs of coordinates.

Args:

q:

A 2-dim sequence, where each row represents a facet. E.g., [[1,2,3],[3,6,7],...]

Returns:

setoflines:

A set of tuple of lines. E.g., ((1,2), (1,3), (2,3), ....)