pymatgen.analysis.surface_analysis module

class SurfaceEnergyAnalyzer(material_id, vasprun_dict, ref_element, exclude_ids=[], custom_entries=[], mapi_key=None)

Bases: object

A class used for analyzing the surface energies of a material of a given

material_id. By default, this will use entries calculated from the Materials Project to obtain chemical potential and bulk energy. As a result, the difference in VASP parameters between the user’s entry (vasprun_dict) and the parameters used by Materials Project, may lead to a rough estimate of the surface energy. For best results, it is recommend that the user calculates all decomposition components first, and insert the results into their own database as a pymatgen-db entry and use those entries instead (custom_entries). In addition, this code will only use one bulk entry to calculate surface energy. Ideally, to get the most accurate surface energy, the user should compare their slab energy to the energy of the oriented unit cell with both calculations containing consistent k-points to avoid converegence problems as the slab size is varied. See:

Sun, W.; Ceder, G. Efficient creation and convergence of surface slabs,

Surface Science, 2013, 617, 53–59, doi:10.1016/j.susc.2013.05.016.

and

Rogal, J., & Reuter, K. (2007). Ab Initio Atomistic Thermodynamics for

Surfaces : A Primer. Experiment, Modeling and Simulation of Gas-Surface Interactions for Reactive Flows in Hypersonic Flights, 2–1 – 2–18.

ref_element

All chemical potentials cna be written in terms of the range of chemical

potential of this element which will be used to calculate surface energy.

mprester

Materials project rester for querying entries from the materials project.

Requires user MAPIKEY.

ucell_entry

Materials Project entry of the material of the slab.

x

Reduced amount composition of decomposed compound A in the bulk.

y

Reduced amount composition of ref_element in the bulk.

gbulk

Gibbs free energy of the bulk per formula unit

chempot_range

List of the min and max chemical potential of ref_element.

e_of_element

Energy per atom of ground state ref_element, eg. if ref_element=O,

than e_of_element=1/2*E_O2.

vasprun_dict

Dictionary containing a list of Vaspruns for slab calculations as

items and the corresponding Miller index of the slab as the key

Analyzes surface energies and Wulff shape of a particular

material using the chemical potential.

Parameters:

• material_id (str) – Materials Project material_id (a string, e.g., mp-1234).
• vasprun_dict (dict) – Dictionary containing a list of Vaspruns for slab calculations as items and the corresponding Miller index of the slab as the key. eg. vasprun_dict = {(1,1,1): [vasprun_111_1, vasprun_111_2, vasprun_111_3], (1,1,0): [vasprun_111_1, vasprun_111_2], …}
• element – element 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
• exclude_ids (list of material_ids) – List of material_ids to exclude when obtaining the decomposition components to calculate the chemical potential
• custom_entries (list of pymatgen-db type entries) – List of user specified pymatgen-db type entries to use in finding decomposition components for the chemical potential
• mapi_key (str) – Materials Project API key for accessing the MP database via MPRester

area_frac_vs_chempot_plot(cmap=<matplotlib.colors.LinearSegmentedColormap object>, at_intersections=False, increments=10)

Plots the change in the area contribution of each facet as a function of chemical potential. :param cmap: A matplotlib colormap object, defaults to jet. :type cmap: cm :param at_intersections: Whether to generate a Wulff shape for each

intersection of surface energy for a specific facet (eg. at the point where a (111) stoichiometric surface energy plot intersects with the (111) nonstoichiometric plot) or to just generate two Wulff shapes, one at the min and max chemical potential.

Parameters:increments (bool) – Number of data points between min/max or point of intersection. Defaults to 5 points.

broken_bond_vs_gamma()

calculate_gamma(vasprun)

Calculates the surface energy for a single slab. :param vasprun: A Vasprun object :type vasprun: Vasprun

Returns (list): The surface energy for the minimum/maximun

chemical potential and the second list gives the range of the chemical potential

chempot_vs_gamma_plot(cmap=<matplotlib.colors.LinearSegmentedColormap object>, show_unstable_points=False)

Plots the surface energy of all facets as a function of chemical potential.

Each facet will be associated with its own distinct colors. Dashed lines will represent stoichiometries different from that of the mpid’s compound.

Parameters:

• cmap (cm) – A matplotlib colormap object, defaults to jet.
• show_unstable_points (bool) – For each facet, there may be various terminations or stoichiometries and the relative stability of these different slabs may change with chemical potential. This option will only plot the most stable surface energy for a given chemical potential.

get_intersections(miller_index)

Returns a all intersections for a specific facet. Useful for

finding when the configuration of a particular facet changes.

Parameters:miller_index ((h, k, l)) – Miller index of the facet we are interested in

get_slope_and_intercept(surf_e_pair)

Returns the slope and intercept of the surface

energy vs chemical potential line

Parameters:surf_e_pair ([e_at_min_u, e_at_max_u]) – The surface energy at the minimum chemical potential and maximum chemical potential

wulff_shape_dict(symprec=1e-05, at_intersections=False)

As the surface energy is a function of chemical potential, so too is the

Wulff shape. This methods generates a dictionary of Wulff shapes at certain chemical potentials where a facet goes through a transition. Returns a dict, eg. {chempot1: WulffShape1, chempot2: WulffShape2}

Parameters:

• symprec (float) – for recp_operation, default is 1e-5.
• at_intersections (bool) – Whether to generate a Wulff shape for each intersection of surface energy for a specific facet (eg. at the point where a (111) stoichiometric surface energy plot intersects with the (111) nonstoichiometric plot) or to just generate two Wulff shapes, one at the min and max chemical potential.

wulff_shape_from_chempot(chempot, symprec=1e-05)

Method to get the Wulff shape at a specific chemical potential. :param chempot: The chemical potential the Wulff Shape exist in. :type chempot: float