pmutt.reaction.phasediagram.PhaseDiagram

class pmutt.reaction.phasediagram.PhaseDiagram(reactions, norm_factors=None)

Bases: Reactions

Generate phase diagrams based on reactions specified. Inherits from Reactions

reactions

Formation reactions for each phase. Reactions should be written with consistent reference species to obtain meaningful data.

Type:

list of Reaction objects

norm_factors

Used for normalizing Gibbs energies. These factors could be surface areas when calculating surface energies or if the reactions stoichiometry is not consistent. Default is an array of 1. It should have the same length as reactions.

Type:

(N,) numpy.ndarray of float, optional

__init__(reactions, norm_factors=None)

Methods

__init__(reactions[, norm_factors])

from_dict(json_obj)

Recreate an object from the JSON representation.

get_E_span(units, **kwargs)

Gets the energy span of a set of reactions.

get_GoRT_1D(x_name, x_values[, G_units])

Calculates the Gibbs free energy for all the reactions for 1 varying parameter

get_GoRT_2D(x1_name, x1_values, x2_name, ...)

Calculates the Gibbs free energy for all the reactions for two varying parameters

get_species([include_TS, key])

Returns the unique species included in the reactions.

plot_1D(x_name, x_values[, G_units])

Make a 1D phase diagram.

plot_2D(x1_name, x1_values, x2_name, x2_values)

Make a 2D phase diagram.

plot_coordinate_diagram(method_name[, ...])

Plots a reaction coordinate diagram.

to_dict()

Represents object as dictionary with JSON-accepted datatypes
classmethod from_dict(json_obj)

Recreate an object from the JSON representation.

Parameters:

json_obj (dict) – JSON representation

Returns:

PhaseDiagram

Return type:

PhaseDiagram object

get_E_span(units, **kwargs)

Gets the energy span of a set of reactions. Equations sourced from

\(\delta E = T_{TDTS} - I_{TDI}\)

if the TOF-determining transition state (TSTS) appears after the TOF-determining intermediate (TDI):

\(\delta E = T_{TDTS} - I_{TDI} + \Delta G_r\)

if the TSTS appears before the TDI:

Parameters:

  • units (str) – Units as string. See R() for accepted units but omit the ‘/K’ (e.g. J/mol).

  • kwargs (keyword arguments) – Parameters to evaluate Gibbs energy at each state.

Returns:

E_span – Energy span of the Reactions

Return type:

float

get_GoRT_1D(x_name, x_values, G_units=None, **kwargs)

Calculates the Gibbs free energy for all the reactions for 1 varying parameter

Parameters:

  • x_name (str) – Name of variable to vary

  • x_values (iterable object) – x values to use

  • G_units (str, optional) – Units for G. If None, uses GoRT. Default is None

  • kwargs (keyword arguments) – Other variables to use in the calculation

Returns:

  • GoRT ((M, N) numpy.ndarray of float) – GoRT values. The first index corresponds to the number of reactions. The second index corresponds to the conditions specified by x_values.

  • stable_phases ((N,) numpy.ndarray of int) – Each element of the array corresponds to the index of the most stable phase at the x_values.

get_GoRT_2D(x1_name, x1_values, x2_name, x2_values, G_units=None, **kwargs)

Calculates the Gibbs free energy for all the reactions for two varying parameters

Parameters:

  • x1_name (str) – Name of first variable to vary

  • x1_values (iterable object) – x1 values to use

  • x2_name (str) – Name of second variable to vary

  • x2_values (iterable object) – x2 values to use

  • G_units (str, optional) – Units for G. If None, uses GoRT. Default is None

  • kwargs (keyword arguments) – Other variables to use in the calculation

Returns:

  • GoRT ((M, N, O) numpy.ndarray of float) – GoRT values. The first index corresponds to the number of reactions. The second index corresponds to the conditions specified by x_values.

  • stable_phases ((N, O) numpy.ndarray of int) – Each element of the array corresponds to the index of the most stable phase at the x_values.

get_species(include_TS=True, key='name')

Returns the unique species included in the reactions.

Parameters:

  • include_TS (bool, optional) – Whether transition states should be included. Default is True

  • key (str, optional) – Attribute to use as the key in the output dictionary. Default is name

Returns:

species – Unique species in the reactions

Return type:

dict

plot_1D(x_name, x_values, G_units=None, **kwargs)

Make a 1D phase diagram.

Parameters:

  • x_name (str) – Name of variable to vary

  • x_values (iterable object) – x values to use

  • G_units (str, optional) – Units for G. If None, uses GoRT. Default is None

  • kwargs (keyword arguments) – Other variables to use in the calculation

Returns:

plot_2D(x1_name, x1_values, x2_name, x2_values, G_units=None, **kwargs)

Make a 2D phase diagram.

Parameters:

  • x1_name (str) – Name of first variable to vary

  • x1_values (iterable object) – x1 values to use

  • x2_name (str) – Name of first variable to vary

  • x2_values (iterable object) – x2 values to use

  • G_units (str, optional) – Units for G. If None, uses GoRT. Default is None

  • kwargs (keyword arguments) – Other variables to use in the calculation

Returns:

plot_coordinate_diagram(method_name, ref_index=0, ref_state='reactants', x_offset=1.0, include_TS=True, x_scale_TS=0.5, y_scale_TS=0.5, include_TS_labels=True, y_TS_label_offset=0.1, x_TS_label_offset=0.0, TS_label_format='.2f', figure=None, axes=None, plt_kwargs={}, **reaction_kwargs)

Plots a reaction coordinate diagram.

Parameters:

  • method_name (str) – Name of method to use to calculate quantity. Calculates any quantity as long as the relevant objects have the same method name. Some examples include: get_HoRT, get_H, get_EoRT, get_E

  • ref_index (int, optional) – Reaction index to use to reference states. Default is the first reaction (i.e. ref_index = 0)

  • ref_state (str, optional) –

    State of the reference to use. Supported options include:

    • reactants (default)

    • products

    • transition state

    • ts (same as transition state)

  • x_offset (float, optional) – Spacing between reaction states. Shape of curve likely does not change with this parameter since the x axis would rescale appropriately

  • include_TS (bool, optional) – Whether transition states should be included. Default is True

  • x_scale_TS (float, optional) – Value between 0 and 1 that controls curvature of transition state peaks. Higher values produce sharper peaks. Default is 0.5

  • y_scale_TS (float, optional) – Value between 0 and 1 that controls curvature of transition state peaks. Higher values produce sharper peaks. Default is 0.5

  • include_TS_labels (bool, optional) – If True, adds a label to the peaks indicating the difference between the reactants and the transition state. Default is True

  • y_TS_label_offset (float, optional) – Vertical value to offset TS_label from the TS position. This value scales with the difference between major ticks. Negative values will shift the label downwards. Default is 0.10

  • x_TS_label_offset (float, optional) – Horizontal value to offset TS_label from the TS_position. This value scales with the x_offset value. Negative values will shift the label rightward. Default is 0 (i.e. labels are directly above peaks by default)

  • TS_label_format (str, optional) – String format to print TS_labels. Uses the str.format syntax. Default is ‘.2f’ (i.e. a floating point value rounded to the second decimal place)

  • figure (matplotlib.figure.Figure) – Add plot to this figure. If not specified, one will be generated

  • axes (matplotlib.axes.Axes.axis, optional) – Adds plot to this axis. If not specified, one will be generated

  • plt_kwargs (dict, optional) – Extra arguments that will be fed to matplotlib.pyplot.subplots

  • reaction_kwargs (keyword arguments) – Extra arguments that will be fed to the reactions

Returns:

to_dict()

Represents object as dictionary with JSON-accepted datatypes

Returns:

obj_dict

Return type:

dict