pymatgen.analysis namespace

Subpackages

Submodules

pymatgen.analysis.adsorption module

This module provides classes used to enumerate surface sites and to find adsorption sites on slabs.

class AdsorbateSiteFinder(slab, selective_dynamics: bool = False, height: float = 0.9, mi_vec: ArrayLike | None = None)[source]

Bases: object

This class finds adsorbate sites on slabs and generates adsorbate structures according to user-defined criteria.

The algorithm for finding sites is essentially as follows:

Determine “surface sites” by finding those within
a height threshold along the miller index of the highest site
Create a network of surface sites using the Delaunay
triangulation of the surface sites
Assign on-top, bridge, and hollow adsorption sites
at the nodes, edges, and face centers of the Del. Triangulation
Generate structures from a molecule positioned at
these sites

Create an AdsorbateSiteFinder object.

Parameters:

slab (Slab) – slab object for which to find adsorbate sites
selective_dynamics (bool) – flag for whether to assign non-surface sites as fixed for selective dynamics
height (float) – height criteria for selection of surface sites
mi_vec (3-D array-like) – vector corresponding to the vector concurrent with the miller index, this enables use with slabs that have been reoriented, but the miller vector must be supplied manually

add_adsorbate(molecule, ads_coord, repeat=None, translate=True, reorient=True)[source]

Adds an adsorbate at a particular coordinate. Adsorbate represented by a Molecule object and is translated to (0, 0, 0) if translate is True, or positioned relative to the input adsorbate coordinate if translate is False.

Parameters:

molecule (Molecule) – molecule object representing the adsorbate
ads_coord (array) – coordinate of adsorbate position
repeat (3-tuple or list) – input for making a supercell of slab prior to placing the adsorbate
translate (bool) – flag on whether to translate the molecule so that its CoM is at the origin prior to adding it to the surface
reorient (bool) – flag on whether to reorient the molecule to have its z-axis concurrent with miller index

adsorb_both_surfaces(molecule, repeat=None, min_lw=5.0, translate=True, reorient=True, find_args=None)[source]

Function that generates all adsorption structures for a given molecular adsorbate on both surfaces of a slab. This is useful for calculating surface energy where both surfaces need to be equivalent or if we want to calculate nonpolar systems.

Parameters:

molecule (Molecule) – molecule corresponding to adsorbate
repeat (3-tuple or list) – repeat argument for supercell generation
min_lw (float) – minimum length and width of the slab, only used if repeat is None
reorient (bool) – flag on whether or not to reorient adsorbate along the miller index
find_args (dict) – dictionary of arguments to be passed to the call to self.find_adsorption_sites, e.g. {“distance”:2.0}

classmethod assign_selective_dynamics(slab)[source]

Helper function to assign selective dynamics site_properties based on surface, subsurface site properties.

Parameters:: slab (Slab) – slab for which to assign selective dynamics

assign_site_properties(slab, height=0.9)[source]: Assigns site properties.

classmethod ensemble_center(site_list, indices, cartesian=True)[source]

Finds the center of an ensemble of sites selected from a list of sites. Helper method for the find_adsorption_sites algorithm.

Parameters:

site_list (list of sites) – list of sites
indices (list of ints) – list of ints from which to select sites from site list
cartesian (bool) – whether to get average fractional or Cartesian coordinate

find_adsorption_sites(distance=2.0, put_inside=True, symm_reduce=0.01, near_reduce=0.01, positions=('ontop', 'bridge', 'hollow'), no_obtuse_hollow=True)[source]

Finds surface sites according to the above algorithm. Returns a list of corresponding Cartesian coordinates.

Parameters:

distance (float) – distance from the coordinating ensemble of atoms along the miller index for the site (i. e. the distance from the slab itself)
put_inside (bool) – whether to put the site inside the cell
symm_reduce (float) – symm reduction threshold
near_reduce (float) – near reduction threshold
positions (list) –
which positions to include in the site finding “ontop”: sites on top of surface sites “bridge”: sites at edges between surface sites in Delaunay

triangulation of surface sites in the miller plane

”hollow”: sites at centers of Delaunay triangulation faces “subsurface”: subsurface positions projected into miller plane
no_obtuse_hollow (bool) – flag to indicate whether to include obtuse triangular ensembles in hollow sites

find_surface_sites_by_height(slab, height=0.9, xy_tol=0.05)[source]

This method finds surface sites by determining which sites are within a threshold value in height from the topmost site in a list of sites.

Parameters:

site_list (list) – list of sites from which to select surface sites
height (float) – threshold in angstroms of distance from topmost site in slab along the slab c-vector to include in surface site determination
xy_tol (float) – if supplied, will remove any sites which are within a certain distance in the miller plane.

Returns:

list of sites selected to be within a threshold of the highest

classmethod from_bulk_and_miller(structure, miller_index, min_slab_size=8.0, min_vacuum_size=10.0, max_normal_search=None, center_slab=True, selective_dynamics=False, undercoord_threshold=0.09)[source]

This method constructs the adsorbate site finder from a bulk structure and a miller index, which allows the surface sites to be determined from the difference in bulk and slab coordination, as opposed to the height threshold.

Parameters:

structure (Structure) – structure from which slab input to the ASF is constructed
miller_index (3-tuple or list) – miller index to be used
min_slab_size (float) – min slab size for slab generation
min_vacuum_size (float) – min vacuum size for slab generation
max_normal_search (int) – max normal search for slab generation
center_slab (bool) – whether to center slab in slab generation
dynamics (selective) – whether to assign surface sites to selective dynamics
undercoord_threshold (float) – threshold of “undercoordation” to use for the assignment of surface sites. Default is 0.1, for which surface sites will be designated if they are 10% less coordinated than their bulk counterpart

generate_adsorption_structures(molecule, repeat=None, min_lw=5.0, translate=True, reorient=True, find_args=None)[source]

Function that generates all adsorption structures for a given molecular adsorbate. Can take repeat argument or minimum length/width of precursor slab as an input.

Parameters:

molecule (Molecule) – molecule corresponding to adsorbate
repeat (3-tuple or list) – repeat argument for supercell generation
min_lw (float) – minimum length and width of the slab, only used if repeat is None
translate (bool) – flag on whether to translate the molecule so that its CoM is at the origin prior to adding it to the surface
reorient (bool) – flag on whether or not to reorient adsorbate along the miller index
find_args (dict) – dictionary of arguments to be passed to the call to self.find_adsorption_sites, e.g. {“distance”:2.0}

generate_substitution_structures(atom, target_species=None, sub_both_sides=False, range_tol=0.01, dist_from_surf=0)[source]

Function that performs substitution-type doping on the surface and returns all possible configurations where one dopant is substituted per surface. Can substitute one surface or both.

Parameters:

atom (str) – atom corresponding to substitutional dopant
sub_both_sides (bool) – If true, substitute an equivalent site on the other surface
target_species (list) – List of specific species to substitute
range_tol (float) – Find viable substitution sites at a specific distance from the surface +- this tolerance
dist_from_surf (float) – Distance from the surface to find viable substitution sites, defaults to 0 to substitute at the surface

get_extended_surface_mesh(repeat=(5, 5, 1))[source]

Gets an extended surface mesh for to use for adsorption site finding by constructing supercell of surface sites.

Parameters:: repeat (3-tuple) – repeat for getting extended surface mesh

near_reduce(coords_set, threshold=0.0001)[source]

Prunes coordinate set for coordinates that are within threshold.

Parameters:

coords_set (Nx3 array-like) – list or array of coordinates
threshold (float) – threshold value for distance

subsurface_sites()[source]: Convenience method to return list of subsurface sites.

property surface_sites[source]: Convenience method to return a list of surface sites.

symm_reduce(coords_set, threshold=1e-06)[source]

Reduces the set of adsorbate sites by finding removing symmetrically equivalent duplicates.

Parameters:

coords_set – coordinate set in Cartesian coordinates
threshold – tolerance for distance equivalence, used as input to in_coord_list_pbc for dupl. checking

get_mi_vec(slab)[source]: Convenience function which returns the unit vector aligned with the miller index.

get_rot(slab)[source]: Gets the transformation to rotate the z axis into the miller index.

plot_slab(slab, ax, scale=0.8, repeat=5, window=1.5, draw_unit_cell=True, decay=0.2, adsorption_sites=True, inverse=False)[source]

Function that helps visualize the slab in a 2-D plot, for convenient viewing of output of AdsorbateSiteFinder.

Parameters:

slab (slab) – Slab object to be visualized
ax (axes) – matplotlib axes with which to visualize
scale (float) – radius scaling for sites
repeat (int) – number of repeating unit cells to visualize
window (float) – window for setting the axes limits, is essentially a fraction of the unit cell limits
draw_unit_cell (bool) – flag indicating whether or not to draw cell
decay (float) – how the alpha-value decays along the z-axis
inverse (bool) – invert z axis to plot opposite surface

put_coord_inside(lattice, cart_coordinate)[source]: Converts a Cartesian coordinate such that it is inside the unit cell.

reorient_z(structure)[source]: Reorients a structure such that the z axis is concurrent with the normal to the A-B plane.

pymatgen.analysis.bond_dissociation module

Module for BondDissociationEnergies.

class BondDissociationEnergies(molecule_entry: dict[str, str | dict[str, str | int]], fragment_entries: list[dict[str, str | dict[str, str | int]]], allow_additional_charge_separation: bool = False, multibreak: bool = False)[source]

Bases: MSONable

Standard constructor for bond dissociation energies. All bonds in the principle molecule are looped through and their dissociation energies are calculated given the energies of the resulting fragments, or, in the case of a ring bond, from the energy of the molecule obtained from breaking the bond and opening the ring. This class should only be called after the energies of the optimized principle molecule and all relevant optimized fragments have been determined, either from quantum chemistry or elsewhere. It was written to provide the analysis after running an Atomate fragmentation workflow.

Note that the entries passed by the user must have the following keys: formula_pretty, initial_molecule, final_molecule. If a PCM is present, all entries should also have a pcm_dielectric key.

Parameters:

molecule_entry (dict) – Entry for the principle molecule. Should have the keys mentioned above.
fragment_entries (list of dicts) – List of fragment entries. Each should have the keys mentioned above.
allow_additional_charge_separation (bool) – If True, consider larger than normal charge separation among fragments. Defaults to False. See the definition of self.expected_charges below for more specific information.
multibreak (bool) – If True, additionally attempt to break pairs of bonds. Defaults to False.

build_new_entry(frags, bonds)[source]

Simple function to format a bond dissociation entry that will eventually be returned to the user.

Parameters:

frags –
bonds –

Returns:

filter_fragment_entries(fragment_entries)[source]

Filter the fragment entries.

Parameters:: fragment_entries –
Returns:

fragment_and_process(bonds)[source]

Fragment and process bonds.

Parameters:: bonds – Bonds to process.
Returns:

search_fragment_entries(frag)[source]

Search all fragment entries for those isomorphic to the given fragment. We distinguish between entries where both initial and final molgraphs are isomorphic to the given fragment (entries) vs those where only the initial molgraph is isomorphic to the given fragment (initial_entries) vs those where only the final molgraph is isomorphic (final_entries).

Parameters:: frag – Fragment

pymatgen.analysis.bond_valence module

This module implements classes to perform bond valence analyses.

class BVAnalyzer(symm_tol=0.1, max_radius=4, max_permutations=100000, distance_scale_factor=1.015, charge_neutrality_tolerance=1e-05, forbidden_species=None)[source]

Bases: object

This class implements a maximum a posteriori (MAP) estimation method to determine oxidation states in a structure. The algorithm is as follows: 1) The bond valence sum of all symmetrically distinct sites in a structure is calculated using the element-based parameters in M. O’Keefe, & N. Brese, JACS, 1991, 113(9), 3226-3229. doi:10.1021/ja00009a002. 2) The posterior probabilities of all oxidation states is then calculated using: P(oxi_state/BV) = K * P(BV/oxi_state) * P(oxi_state), where K is a constant factor for each element. P(BV/oxi_state) is calculated as a Gaussian with mean and std deviation determined from an analysis of the ICSD. The posterior P(oxi_state) is determined from a frequency analysis of the ICSD. 3) The oxidation states are then ranked in order of decreasing probability and the oxidation state combination that result in a charge neutral cell is selected.

Initializes the BV analyzer, with useful defaults.

Parameters:

symm_tol – Symmetry tolerance used to determine which sites are symmetrically equivalent. Set to 0 to turn off symmetry.
max_radius – Maximum radius in Angstrom used to find nearest neighbors.
max_permutations – The maximum number of permutations of oxidation states to test.
distance_scale_factor – A scale factor to be applied. This is useful for scaling distances, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA). The default of 1.015 works for GGA. For experimental structure, set this to 1.
charge_neutrality_tolerance – Tolerance on the charge neutrality when unordered structures are at stake.
forbidden_species – List of species that are forbidden (example : [“O-”] cannot be used) It is used when e.g. someone knows that some oxidation state cannot occur for some atom in a structure or list of structures.

CHARGE_NEUTRALITY_TOLERANCE = 1e-05[source]

_calc_site_probabilities(site, nn)[source]

_calc_site_probabilities_unordered(site, nn)[source]

get_oxi_state_decorated_structure(structure: Structure)[source]

Get an oxidation state decorated structure. This currently works only for ordered structures only.

Parameters:: structure – Structure to analyze
Returns:: A modified structure that is oxidation state decorated.
Raises:: ValueError if the valences cannot be determined. –

get_valences(structure: Structure)[source]

Returns a list of valences for each site in the structure.

Parameters:: structure – Structure to analyze
Returns:: A list of valences for each site in the structure (for an ordered structure), e.g., [1, 1, -2] or a list of lists with the valences for each fractional element of each site in the structure (for an unordered structure), e.g., [[2, 4], [3], [-2], [-2], [-2]]
Raises:: A ValueError if the valences cannot be determined. –

add_oxidation_state_by_site_fraction(structure, oxidation_states)[source]

Add oxidation states to a structure by fractional site.

Parameters:: oxidation_states (list) – List of list of oxidation states for each site fraction for each site. E.g., [[2, 4], [3], [-2], [-2], [-2]]

calculate_bv_sum(site, nn_list, scale_factor=1.0)[source]

Calculates the BV sum of a site.

Parameters:

site (PeriodicSite) – The central site to calculate the bond valence
nn_list ([Neighbor]) – A list of namedtuple Neighbors having “distance” and “site” attributes
scale_factor (float) – A scale factor to be applied. This is useful for scaling distance, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA).

calculate_bv_sum_unordered(site, nn_list, scale_factor=1)[source]

Calculates the BV sum of a site for unordered structures.

Parameters:

site (PeriodicSite) – The central site to calculate the bond valence
nn_list ([Neighbor]) – A list of namedtuple Neighbors having “distance” and “site” attributes
scale_factor (float) – A scale factor to be applied. This is useful for scaling distance, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA).

get_z_ordered_elmap(comp)[source]

Arbitrary ordered element map on the elements/species of a composition of a given site in an unordered structure. Returns a list of tuples ( element_or_specie: occupation) in the arbitrary order.

The arbitrary order is based on the Z of the element and the smallest fractional occupations first. Example : {“Ni3+”: 0.2, “Ni4+”: 0.2, “Cr3+”: 0.15, “Zn2+”: 0.34, “Cr4+”: 0.11} will yield the species in the following order : Cr4+, Cr3+, Ni3+, Ni4+, Zn2+ … or Cr4+, Cr3+, Ni4+, Ni3+, Zn2+

pymatgen.analysis.chempot_diagram module

This module implements the construction and plotting of chemical potential diagrams from a list of entries within a chemical system containing 2 or more elements. The chemical potential diagram is the mathematical dual to the traditional compositional phase diagram.

For more information, please cite/reference the paper below:

Todd, P. K., McDermott, M. J., Rom, C. L., Corrao, A. A., Denney, J. J., Dwaraknath, S. S., Khalifah, P. G., Persson, K. A., & Neilson, J. R. (2021). Selectivity in Yttrium Manganese Oxide Synthesis via Local Chemical Potentials in Hyperdimensional Phase Space. Journal of the American Chemical Society, 143(37), 15185-15194. https://doi.org/10.1021/jacs.1c06229

Please also consider referencing the original 1999 paper by H. Yokokawa, who outlined many of its possible uses:

Yokokawa, H. “Generalized chemical potential diagram and its applications to chemical reactions at interfaces between dissimilar materials.” JPE 20, 258 (1999). https://doi.org/10.1361/105497199770335794

class ChemicalPotentialDiagram(entries: list[PDEntry], limits: dict[Element, tuple[float, float]] | None = None, default_min_limit: float = -50.0, formal_chempots: bool = True)[source]

Bases: MSONable

The chemical potential diagram is the mathematical dual to the compositional phase diagram. To create the diagram, convex minimization is performed in energy (E) vs. chemical potential (μ) space by taking the lower convex envelope of hyperplanes. Accordingly, “points” on the compositional phase diagram become N-dimensional convex polytopes (domains) in chemical potential space.

For more information on this specific implementation of the algorithm, please cite/reference the paper below:

Todd, P. K., McDermott, M. J., Rom, C. L., Corrao, A. A., Denney, J. J., Dwaraknath, S. S., Khalifah, P. G., Persson, K. A., & Neilson, J. R. (2021). Selectivity in Yttrium Manganese Oxide Synthesis via Local Chemical Potentials in Hyperdimensional Phase Space. Journal of the American Chemical Society, 143(37), 15185-15194. https://doi.org/10.1021/jacs.1c06229

Parameters:

entries (list[PDEntry]) – PDEntry-like objects containing a composition and energy. Must contain elemental references and be suitable for typical phase diagram construction. Entries must be within a chemical system of with 2+ elements.
limits (dict[Element, float] | None) – Bounds of elemental chemical potentials (min, max), which are used to construct the border hyperplanes used in the HalfSpaceIntersection algorithm; these constrain the space over which the domains are calculated and also determine the size of the plotted diagram. Any elemental limits not specified are covered in the default_min_limit argument. e.g., {Element(“Li”): [-12.0, 0.0], …}
default_min_limit (float) – Default minimum chemical potential limit (i.e., lower bound) for unspecified elements within the “limits” argument.
formal_chempots (bool) – Whether to plot the formal (‘reference’) chemical potentials (i.e. μ_X - μ_X^0) or the absolute DFT reference energies (i.e. μ_X(DFT)). Default is True (i.e. plot formal chemical potentials).

static _get_2d_domain_lines(draw_domains) → list[plotly.graph_objs._scatter.Scatter][source]: Returns a list of Scatter objects tracing the domain lines on a 2-dimensional chemical potential diagram.

_get_2d_plot(elements: list[Element], label_stable: bool | None, element_padding: float | None) → Figure[source]: Returns a Plotly figure for a 2-dimensional chemical potential diagram.

static _get_3d_domain_lines(domains: dict[str, list[Simplex] | None]) → list[Scatter3d][source]: Returns a list of Scatter3d objects tracing the domain lines on a 3-dimensional chemical potential diagram.

static _get_3d_domain_simplexes_and_ann_loc(points_3d: ndarray) → tuple[list[pymatgen.util.coord.Simplex], numpy.ndarray][source]: Returns a list of Simplex objects and coordinates of annotation for one domain in a 3-d chemical potential diagram. Uses PCA to project domain into 2-dimensional space so that ConvexHull can be used to identify the bounding polygon.

static _get_3d_formula_lines(draw_domains: dict[str, np.ndarray], formula_colors: list[str] | None) → list[Scatter3d][source]: Returns a list of Scatter3d objects defining the bounding polyhedra.

static _get_3d_formula_meshes(draw_domains: dict[str, np.ndarray], formula_colors: list[str] | None) → list[Mesh3d][source]: Returns a list of Mesh3d objects for the domains specified by the user (i.e., draw_domains).

_get_3d_plot(elements: list[Element], label_stable: bool | None, formulas_to_draw: list[str] | None, draw_formula_meshes: bool | None, draw_formula_lines: bool | None, formula_colors: list[str] | None, element_padding: float | None) → Figure[source]: Returns a Plotly figure for a 3-dimensional chemical potential diagram.

static _get_annotation(ann_loc: np.ndarray, formula: str) → dict[str, str | float][source]: Returns a Plotly annotation dict given a formula and location.

static _get_axis_layout_dict(elements: list[pymatgen.core.periodic_table.Element]) → dict[str, str][source]: Returns a Plotly layout dict for either 2-d or 3-d axes.

_get_border_hyperplanes() → ndarray[source]: Returns an array of the bounding hyperplanes given by elemental limits.

_get_domains() → dict[str, numpy.ndarray][source]: Returns a dictionary of domains as {formula: np.ndarray}.

_get_hyperplanes_and_entries() → tuple[numpy.ndarray, list[pymatgen.analysis.phase_diagram.PDEntry]][source]: Returns both the array of hyperplanes, as well as a list of the minimum entries.

static _get_min_entries_and_el_refs(entries: list[pymatgen.analysis.phase_diagram.PDEntry]) → tuple[list[pymatgen.analysis.phase_diagram.PDEntry], dict[pymatgen.core.periodic_table.Element, pymatgen.analysis.phase_diagram.PDEntry]][source]: Returns a list of the minimum-energy entries at each composition and the entries corresponding to the elemental references.

static _get_new_limits_from_padding(domains: dict[str, numpy.ndarray], elem_indices: list[int], element_padding: float, default_min_limit: float)[source]: Gets new minimum limits for each element by subtracting specified padding from the minimum for each axis found in any of the domains.

property border_hyperplanes: ndarray[source]: Returns bordering hyperplanes.

property chemical_system: str[source]: Returns the chemical system (A-B-C-…) of diagram object.

property domains: dict[str, numpy.ndarray][source]: Mapping of formulas to array of domain boundary points.

property el_refs: dict[pymatgen.core.periodic_table.Element, pymatgen.analysis.phase_diagram.PDEntry][source]: Returns a dictionary of elements and reference entries.

property entry_dict: dict[str, ComputedEntry][source]: Mapping between reduced formula and ComputedEntry.

get_plot(elements: list[Element | str] | None = None, label_stable: bool | None = True, formulas_to_draw: list[str] | None = None, draw_formula_meshes: bool | None = True, draw_formula_lines: bool | None = True, formula_colors: list[str] = ['rgb(27,158,119)', 'rgb(217,95,2)', 'rgb(117,112,179)', 'rgb(231,41,138)', 'rgb(102,166,30)', 'rgb(230,171,2)', 'rgb(166,118,29)', 'rgb(102,102,102)'], element_padding: float | None = 1.0) → Figure[source]

Plot the 2-dimensional or 3-dimensional chemical potential diagram using an interactive Plotly interface.

Elemental axes can be specified; if none provided, will automatically default to first 2-3 elements within the “elements” attribute.

In 3D, this method also allows for plotting of lower-dimensional “slices” of hyperdimensional polytopes (e.g., the LiMnO2 domain within a Y-Mn-O diagram). This allows for visualization of some of the phase boundaries that can only be seen fully in high dimensional space; see the “formulas_to_draw” argument.

Parameters:

elements – list of elements to use as axes in the diagram. If None, automatically defaults to the first 2 or elements within the object’s “elements” attribute.
label_stable – whether to label stable phases by their reduced formulas. Defaults to True.
formulas_to_draw – for 3-dimensional diagrams, an optional list of formulas to plot on the diagram; if these are from a different chemical system a 3-d polyhedron “slice” will be plotted. Defaults to None.
draw_formula_meshes – whether to draw a colored mesh for the optionally specified formulas_to_draw. Defaults to True.
draw_formula_lines – whether to draw bounding lines for the optionally specified formulas_to_draw. Defaults to True.
formula_colors – a list of colors to use in the plotting of the optionally specified formulas_to-draw. Defaults to the Plotly Dark2 color scheme.
element_padding – if provided, automatically adjusts chemical potential axis limits of the plot such that elemental domains have the specified padding (in eV/atom), helping provide visual clarity. Defaults to 1.0.

Returns:

A Plotly Figure object

property hyperplane_entries: list[pymatgen.analysis.phase_diagram.PDEntry][source]: Returns list of entries corresponding to hyperplanes.

property hyperplanes: ndarray[source]: Returns array of hyperplane data.

property lims: ndarray[source]: Returns array of limits used in constructing hyperplanes.

_renormalize_entry(entry: PDEntry, renormalization_energy_per_atom: float) → PDEntry[source]: Regenerate the input entry with an energy per atom decreased by renormalization_energy_per_atom.

get_2d_orthonormal_vector(line_pts: ndarray) → ndarray[source]

Calculates a vector that is orthonormal to a line given by a set of points. Used for determining the location of an annotation on a 2-d chemical potential diagram.

Parameters:: line_pts – a 2x2 array in the form of [[x0, y0], [x1, y1]] giving the coordinates of a line
Returns:: A length-2 vector that is orthonormal to the line.
Return type:: np.ndarray

get_centroid_2d(vertices: ndarray) → ndarray[source]

A bare-bones implementation of the formula for calculating the centroid of a 2D polygon. Useful for calculating the location of an annotation on a chemical potential domain within a 3D chemical potential diagram.

NOTE: vertices must be ordered circumferentially!

Parameters:: vertices – array of 2-d coordinates corresponding to a polygon, ordered circumferentially
Returns:: Array giving 2-d centroid coordinates

simple_pca(data: ndarray, k: int = 2) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

A bare-bones implementation of principal component analysis (PCA) used in the ChemicalPotentialDiagram class for plotting.

Parameters:

data – array of observations
k – Number of principal components returned

Returns:

Tuple of projected data, eigenvalues, eigenvectors

pymatgen.analysis.cost module

This module is used to estimate the cost of various compounds. Costs are taken from the a CostDB instance, for example a CSV file via CostDBCSV. For compounds with no cost listed, a Phase Diagram style convex hull optimization is performed to determine a set of compositions that can be mixed to give the desired compound with lowest total cost.

class CostAnalyzer(costdb)[source]

Bases: object

Given a CostDB, figures out the minimum cost solutions via convex hull.

Parameters:: () (costdb) – Cost database.

get_cost_per_kg(comp)[source]

Get best estimate of minimum cost/kg based on known data.

Parameters:: comp – Composition as a pymatgen.core.structure.Composition
Returns:: float of cost/kg

get_cost_per_mol(comp)[source]

Get best estimate of minimum cost/mol based on known data.

Parameters:: comp – Composition as a pymatgen.core.structure.Composition
Returns:: float of cost/mol

get_lowest_decomposition(composition)[source]

Get the decomposition leading to lowest cost.

Parameters:: composition – Composition as a pymatgen.core.structure.Composition
Returns:: amount}
Return type:: Decomposition as a dict of {Entry

class CostDB[source]

Bases: object

Abstract class for representing a Cost database. Can be extended, e.g. for file-based or REST-based databases.

_abc_impl = <_abc._abc_data object>[source]

abstract get_entries(chemsys)[source]

For a given chemical system, return an array of CostEntries.

Parameters:: chemsys – array of Elements defining the chemical system.
Returns:: array of CostEntries

class CostDBCSV(filename)[source]

Bases: CostDB

Read a CSV file to get costs Format is formula,cost_per_kg,name,BibTeX.

Parameters:: filename (str) – Filename of cost database.

_abc_impl = <_abc._abc_data object>[source]

get_entries(chemsys)[source]

For a given chemical system, return an array of CostEntries.

Parameters:: chemsys – array of Elements defining the chemical system.
Returns:: array of CostEntries

class CostEntry(composition, cost, name, reference)[source]

Bases: PDEntry

Extends PDEntry to include a BibTeX reference and include language about cost.

Parameters:

composition – Composition as a pymatgen.core.structure.Composition
cost – Cost (per mol, NOT per kg) of the full Composition
name – Optional parameter to name the entry. Defaults to the reduced chemical formula as in PDEntry.
reference – Reference data as BiBTeX string.

_abc_impl = <_abc._abc_data object>[source]

pymatgen.analysis.dimensionality module

This module provides functions to get the dimensionality of a structure.

A number of different algorithms are implemented. These are based on the following publications:

get_dimensionality_larsen:

P. M. Larsen, M. Pandey, M. Strange, K. W. Jacobsen. Definition of a scoring parameter to identify low-dimensional materials components. Phys. Rev. Materials 3, 034003 (2019).

get_dimensionality_cheon:

Cheon, G.; Duerloo, K.-A. N.; Sendek, A. D.; Porter, C.; Chen, Y.; Reed, E. J. Data Mining for New Two- and One-Dimensional Weakly Bonded Solids and Lattice-Commensurate Heterostructures. Nano Lett. 2017.

get_dimensionality_gorai:

Gorai, P., Toberer, E. & Stevanovic, V. Computational Identification of Promising Thermoelectric Materials Among Known Quasi-2D Binary Compounds. J. Mater. Chem. A 2, 4136 (2016).

calculate_dimensionality_of_site(bonded_structure, site_index, inc_vertices=False)[source]

Calculates the dimensionality of the component containing the given site.

Implements directly the modified breadth-first-search algorithm described in Algorithm 1 of:

P. M. Larsen, M. Pandey, M. Strange, K. W. Jacobsen. Definition of a scoring parameter to identify low-dimensional materials components. Phys. Rev. Materials 3, 034003 (2019).

Parameters:

bonded_structure (StructureGraph) – A structure with bonds, represented as a pymatgen structure graph. For example, generated using the CrystalNN.get_bonded_structure() method.
site_index (int) – The index of a site in the component of interest.
inc_vertices (bool, optional) – Whether to return the vertices (site images) of the component.

Returns:

If inc_vertices is False, the dimensionality of the component will be returned as an int. If inc_vertices is true, the function will return a tuple of (dimensionality, vertices), where vertices is a list of tuples. E.g. [(0, 0, 0), (1, 1, 1)].

Return type:

(int or tuple)

find_clusters(struct, connected_matrix)[source]

Finds bonded clusters of atoms in the structure with periodic boundary conditions.

If there are atoms that are not bonded to anything, returns [0,1,0]. (For faster computation time)

Author: Gowoon Cheon Email: gcheon@stanford.edu

Parameters:

struct (Structure) – Input structure
connected_matrix – Must be made from the same structure with find_connected_atoms() function.

Returns:

the size of the largest cluster in the crystal structure min_cluster: the size of the smallest cluster in the crystal structure clusters: list of bonded clusters found here, clusters are formatted as sets of indices of atoms

Return type:

max_cluster

find_connected_atoms(struct, tolerance=0.45, ldict=None)[source]

Finds bonded atoms and returns a adjacency matrix of bonded atoms.

Author: “Gowoon Cheon” Email: “gcheon@stanford.edu”

Parameters:

struct (Structure) – Input structure
tolerance – length in angstroms used in finding bonded atoms. Two atoms are considered bonded if (radius of atom 1) + (radius of atom 2) + (tolerance) < (distance between atoms 1 and 2). Default value = 0.45, the value used by JMol and Cheon et al.
ldict – dictionary of bond lengths used in finding bonded atoms. Values from JMol are used as default

Returns:

A numpy array of shape (number of atoms, number of atoms); If any image of atom j is bonded to atom i with periodic boundary conditions, the matrix element [atom i, atom j] is 1.

Return type:

(np.ndarray)

get_dimensionality_cheon(structure_raw, tolerance=0.45, ldict=None, standardize=True, larger_cell=False)[source]

Algorithm for finding the dimensions of connected subunits in a structure. This method finds the dimensionality of the material even when the material is not layered along low-index planes, or does not have flat layers/molecular wires.

Author: “Gowoon Cheon” Email: “gcheon@stanford.edu”

See details at :

Cheon, G.; Duerloo, K.-A. N.; Sendek, A. D.; Porter, C.; Chen, Y.; Reed, E. J. Data Mining for New Two- and One-Dimensional Weakly Bonded Solids and Lattice-Commensurate Heterostructures. Nano Lett. 2017.

Parameters:

structure_raw (Structure) – A pymatgen Structure object.
tolerance (float) – length in angstroms used in finding bonded atoms. Two atoms are considered bonded if (radius of atom 1) + (radius of atom 2) + (tolerance) < (distance between atoms 1 and 2). Default value = 0.45, the value used by JMol and Cheon et al.
ldict (dict) – dictionary of bond lengths used in finding bonded atoms. Values from JMol are used as default
standardize – works with conventional standard structures if True. It is recommended to keep this as True.
larger_cell –
tests with 3x3x3 supercell instead of 2x2x2. Testing with 2x2x2 supercell is faster but misclassifies rare interpenetrated 3D

structures. Testing with a larger cell circumvents this problem

Returns:

dimension of the largest cluster as a string. If there are ions or molecules it returns ‘intercalated ion/molecule’

Return type:

(str)

get_dimensionality_gorai(structure, max_hkl=2, el_radius_updates=None, min_slab_size=5, min_vacuum_size=5, standardize=True, bonds=None)[source]

This method returns whether a structure is 3D, 2D (layered), or 1D (linear chains or molecules) according to the algorithm published in Gorai, P., Toberer, E. & Stevanovic, V. Computational Identification of Promising Thermoelectric Materials Among Known Quasi-2D Binary Compounds. J. Mater. Chem. A 2, 4136 (2016).

Note that a 1D structure detection might indicate problems in the bonding algorithm, particularly for ionic crystals (e.g., NaCl)

Users can change the behavior of bonds detection by passing either el_radius_updates to update atomic radii for auto-detection of max bond distances, or bonds to explicitly specify max bond distances for atom pairs. Note that if you pass both, el_radius_updates are ignored.

Parameters:

structure – (Structure) structure to analyze dimensionality for
max_hkl – (int) max index of planes to look for layers
el_radius_updates – (dict) symbol->float to update atomic radii
min_slab_size – (float) internal surface construction parameter
min_vacuum_size – (float) internal surface construction parameter
standardize (bool) – whether to standardize the structure before analysis. Set to False only if you already have the structure in a convention where layers / chains will be along low <hkl> indexes.
bonds ({(specie1, specie2) – max_bond_dist}: bonds are specified as a dict of tuples: float of specie1, specie2 and the max bonding distance. For example, PO4 groups may be defined as {(“P”, “O”): 3}.

Returns: (int) the dimensionality of the structure - 1 (molecules/chains),: 2 (layered), or 3 (3D)

get_dimensionality_larsen(bonded_structure)[source]

Gets the dimensionality of a bonded structure.

The dimensionality of the structure is the highest dimensionality of all structure components. This method is very robust and can handle many tricky structures, regardless of structure type or improper connections due to periodic boundary conditions.

Requires a StructureGraph object as input. This can be generated using one of the NearNeighbor classes. For example, using the CrystalNN class:

bonded_structure = CrystalNN().get_bonded_structure(structure)

Based on the modified breadth-first-search algorithm described in:

P. M. Larsen, M. Pandey, M. Strange, K. W. Jacobsen. Definition of a scoring parameter to identify low-dimensional materials components. Phys. Rev. Materials 3, 034003 (2019).

Parameters:: bonded_structure (StructureGraph) – A structure with bonds, represented as a pymatgen structure graph. For example, generated using the CrystalNN.get_bonded_structure() method.
Returns:: The dimensionality of the structure.
Return type:: (int)

get_structure_components(bonded_structure, inc_orientation=False, inc_site_ids=False, inc_molecule_graph=False)[source]

Gets information on the components in a bonded structure.

Correctly determines the dimensionality of all structures, regardless of structure type or improper connections due to periodic boundary conditions.

Requires a StructureGraph object as input. This can be generated using one of the NearNeighbor classes. For example, using the CrystalNN class:

bonded_structure = CrystalNN().get_bonded_structure(structure)

Based on the modified breadth-first-search algorithm described in:

P. M. Larsen, M. Pandey, M. Strange, K. W. Jacobsen. Definition of a scoring parameter to identify low-dimensional materials components. Phys. Rev. Materials 3, 034003 (2019).

Parameters:

bonded_structure (StructureGraph) – A structure with bonds, represented as a pymatgen structure graph. For example, generated using the CrystalNN.get_bonded_structure() method.
inc_orientation (bool, optional) – Whether to include the orientation of the structure component. For surfaces, the miller index is given, for one-dimensional structures, the direction of the chain is given.
inc_site_ids (bool, optional) – Whether to include the site indices of the sites in the structure component.
inc_molecule_graph (bool, optional) – Whether to include MoleculeGraph objects for zero-dimensional components.

Returns:

Information on the components in a structure as a list of dictionaries with the keys:

”structure_graph”: A pymatgen StructureGraph object for the
component.
”dimensionality”: The dimensionality of the structure component as an
int.
”orientation”: If inc_orientation is True, the orientation of the
component as a tuple. E.g. (1, 1, 1)
”site_ids”: If inc_site_ids is True, the site indices of the
sites in the component as a tuple.
”molecule_graph”: If inc_molecule_graph is True, the site a
MoleculeGraph object for zero-dimensional components.

Return type:

(list of dict)

zero_d_graph_to_molecule_graph(bonded_structure, graph)[source]

Converts a zero-dimensional networkx Graph object into a MoleculeGraph.

Implements a similar breadth-first search to that in calculate_dimensionality_of_site().

Parameters:

bonded_structure (StructureGraph) – A structure with bonds, represented as a pymatgen structure graph. For example, generated using the CrystalNN.get_bonded_structure() method.
graph (nx.Graph) – A networkx Graph object for the component of interest.

Returns:

A MoleculeGraph object of the component.

Return type:

(MoleculeGraph)

pymatgen.analysis.disorder module

This module provides various methods to analyze order/disorder in materials.

get_warren_cowley_parameters(structure: Structure, r: float, dr: float) → dict[tuple, float][source]

Warren-Crowley parameters.

Parameters:

structure – Pymatgen Structure.
r – Radius
dr – Shell width

Returns:

-1.0, …}

Return type:

Warren-Crowley parameters in the form of a dict, e.g., {(Element Mo, Element W)

pymatgen.analysis.energy_models module

This module implements a EnergyModel abstract class and some basic implementations. Basically, an EnergyModel is any model that returns an “energy” for any given structure.

class EnergyModel[source]

Bases: MSONable

Abstract structure filter class.

_abc_impl = <_abc._abc_data object>[source]

classmethod from_dict(dct)[source]

Parameters:: dct (dict) – Dict representation.
Returns:: EnergyModel

abstract get_energy(structure) → float[source]

Parameters:: structure – Structure
Returns:: Energy value

class EwaldElectrostaticModel(real_space_cut=None, recip_space_cut=None, eta=None, acc_factor=8.0)[source]

Bases: EnergyModel

Wrapper around EwaldSum to calculate the electrostatic energy.

Initializes the model. Args have the same definitions as in pymatgen.analysis.ewald.EwaldSummation.

Parameters:

real_space_cut (float) – Real space cutoff radius dictating how many terms are used in the real space sum. Defaults to None, which means determine automagically using the formula given in gulp 3.1 documentation.
recip_space_cut (float) – Reciprocal space cutoff radius. Defaults to None, which means determine automagically using the formula given in gulp 3.1 documentation.
eta (float) – Screening parameter. Defaults to None, which means determine automatically.
acc_factor (float) – No. of significant figures each sum is converged to.

_abc_impl = <_abc._abc_data object>[source]

as_dict()[source]

Returns:: MSONable dict

get_energy(structure: Structure)[source]

Parameters:: structure – Structure
Returns:: Energy value

class IsingModel(j, max_radius)[source]

Bases: EnergyModel

A very simple Ising model, with r^2 decay.

Parameters:

j (float) – The interaction parameter. E = J * spin1 * spin2.
radius (float) – max_radius for the interaction.

_abc_impl = <_abc._abc_data object>[source]

as_dict()[source]

Returns:: MSONable dict

get_energy(structure: Structure)[source]

Parameters:: structure – Structure
Returns:: Energy value

class NsitesModel[source]

Bases: EnergyModel

Sets the energy to the number of sites. More sites => higher “energy”. Used to rank structures from smallest number of sites to largest number of sites after enumeration.

_abc_impl = <_abc._abc_data object>[source]

as_dict()[source]

Returns:: MSONable dict

get_energy(structure: Structure)[source]

Parameters:: structure – Structure
Returns:: Energy value

class SymmetryModel(symprec: float = 0.1, angle_tolerance=5)[source]

Bases: EnergyModel

Sets the energy to the -ve of the spacegroup number. Higher symmetry => lower “energy”.

Args have same meaning as in pymatgen.symmetry.finder.SpacegroupAnalyzer.

Parameters:

symprec (float) – Symmetry tolerance. Defaults to 0.1.
angle_tolerance (float) – Tolerance for angles. Defaults to 5 degrees.

_abc_impl = <_abc._abc_data object>[source]

as_dict()[source]

Returns:: MSONable dict

get_energy(structure: Structure)[source]

Parameters:: structure – Structure
Returns:: Energy value

pymatgen.analysis.eos module

This module implements various equation of states.

Note: Most of the code were initially adapted from ASE and deltafactor by @gmatteo but has since undergone major refactoring.

class Birch(volumes, energies)[source]

Bases: EOSBase

Birch EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]: From Intermetallic compounds: Principles and Practice, Vol. I: Principles Chapter 9 pages 195-210 by M. Mehl. B. Klein, D. Papaconstantopoulos. case where n=0.

class BirchMurnaghan(volumes, energies)[source]

Bases: EOSBase

BirchMurnaghan EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]: BirchMurnaghan equation from PRB 70, 224107.

class DeltaFactor(volumes, energies)[source]

Bases: PolynomialEOS

Fitting a polynomial EOS using delta factor.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]

The equation of state function. This must be implemented by all classes that derive from this abstract class.

Parameters:

volume (float/numpy.array) –

params (list/tuple): values for the parameters other than the: volume used by the eos.

_set_params()[source]: Overridden to account for the fact the fit with volume**(2/3) instead of volume.

fit(order=3)[source]: Overridden since this eos works with volume**(2/3) instead of volume.

class EOS(eos_name='murnaghan')[source]

Bases: object

Convenient wrapper. Retained in its original state to ensure backward compatibility.

Fit equation of state for bulk systems.

The following equations are supported:

murnaghan: PRB 28, 5480 (1983)

birch: Intermetallic compounds: Principles and Practice, Vol I:
    Principles. pages 195-210

birch_murnaghan: PRB 70, 224107

pourier_tarantola: PRB 70, 224107

vinet: PRB 70, 224107

deltafactor

numerical_eos: 10.1103/PhysRevB.90.174107.

Usage:

eos = EOS(eos_name='murnaghan')
eos_fit = eos.fit(volumes, energies)
eos_fit.plot()

Parameters:: eos_name (str) – Type of EOS to fit.

MODELS = {'birch': <class 'pymatgen.analysis.eos.Birch'>, 'birch_murnaghan': <class 'pymatgen.analysis.eos.BirchMurnaghan'>, 'deltafactor': <class 'pymatgen.analysis.eos.DeltaFactor'>, 'murnaghan': <class 'pymatgen.analysis.eos.Murnaghan'>, 'numerical_eos': <class 'pymatgen.analysis.eos.NumericalEOS'>, 'pourier_tarantola': <class 'pymatgen.analysis.eos.PourierTarantola'>, 'vinet': <class 'pymatgen.analysis.eos.Vinet'>}[source]

fit(volumes, energies)[source]

Fit energies as function of volumes.

Parameters:

volumes (list/np.array) –
energies (list/np.array) –

Returns:

EOSBase object

Return type:

EOSBase

class EOSBase(volumes, energies)[source]

Bases: object

Abstract class that must be subclassed by all equation of state implementations.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

abstract _func(volume, params)[source]

The equation of state function. This must be implemented by all classes that derive from this abstract class.

Parameters:

volume (float/numpy.array) –

params (list/tuple): values for the parameters other than the: volume used by the eos.

_initial_guess()[source]

Quadratic fit to get an initial guess for the parameters.

Returns:: (e0, b0, b1, v0)
Return type:: tuple

property b0[source]: Returns the bulk modulus. Note: the units for the bulk modulus: unit of energy/unit of volume^3.

property b0_GPa[source]: Returns the bulk modulus in GPa. Note: This assumes that the energy and volumes are in eV and Ang^3

respectively.

property b1[source]: Returns the derivative of bulk modulus wrt pressure(dimensionless).

property e0[source]: Returns the min energy.

fit()[source]: Do the fitting. Does least square fitting. If you want to use custom fitting, must override this.

func(volume)[source]

The equation of state function with the parameters other than volume set to the ones obtained from fitting.

Parameters:: volume (list/numpy.array) –
Returns:: numpy.array

plot(width=8, height=None, plt=None, dpi=None, **kwargs)[source]

Plot the equation of state.

Parameters:

width (float) – Width of plot in inches. Defaults to 8in.
height (float) – Height of plot in inches. Defaults to width * golden ratio.
plt (matplotlib.pyplot) – If plt is supplied, changes will be made to an existing plot. Otherwise, a new plot will be created.
dpi –
kwargs (dict) – additional args fed to pyplot.plot. supported keys: style, color, text, label

Returns:

Matplotlib plot object.

plot_ax(ax=None, fontsize=12, **kwargs)[source]

Plot the equation of state on axis ax.

Parameters:

ax – matplotlib Axes or None if a new figure should be created.
fontsize – Legend fontsize.
color (str) – plot color.
label (str) – Plot label
text (str) – Legend text (options)

Returns:

Matplotlib figure object.

Keyword arguments controlling the display of the figure:

kwargs	Meaning
title	Title of the plot (Default: None).
show	True to show the figure (default: True).
savefig	“abc.png” or “abc.eps” to save the figure to a file.
size_kwargs	Dictionary with options passed to fig.set_size_inches e.g. size_kwargs=dict(w=3, h=4)
tight_layout	True to call fig.tight_layout (default: False)
ax_grid	True (False) to add (remove) grid from all axes in fig. Default: None i.e. fig is left unchanged.
ax_annotate	Add labels to subplots e.g. (a), (b). Default: False
fig_close	Close figure. Default: False.

property results[source]

Returns a summary dict.

Returns:: dict

property v0[source]: Returns the minimum or the reference volume in Ang^3.

exception EOSError[source]

Bases: Exception

Error class for EOS fitting.

class Murnaghan(volumes, energies)[source]

Bases: EOSBase

Murnaghan EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]: From PRB 28,5480 (1983).

class NumericalEOS(volumes, energies)[source]

Bases: PolynomialEOS

A numerical EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

fit(min_ndata_factor=3, max_poly_order_factor=5, min_poly_order=2)[source]

Fit the input data to the ‘numerical eos’, the equation of state employed in the quasiharmonic Debye model described in the paper: 10.1103/PhysRevB.90.174107.

credits: Cormac Toher

Parameters:

min_ndata_factor (int) –
parameter that controls the minimum number of data points that will be used for fitting. minimum number of data points =

total data points-2*min_ndata_factor
max_poly_order_factor (int) –
parameter that limits the max order of the polynomial used for fitting. max_poly_order = number of data points used for fitting -

max_poly_order_factor
min_poly_order (int) – minimum order of the polynomial to be considered for fitting.

class PolynomialEOS(volumes, energies)[source]

Bases: EOSBase

Derives from EOSBase. Polynomial based equations of states must subclass this.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]

The equation of state function. This must be implemented by all classes that derive from this abstract class.

Parameters:

volume (float/numpy.array) –

params (list/tuple): values for the parameters other than the: volume used by the eos.

_set_params()[source]: Use the fit polynomial to compute the parameter e0, b0, b1 and v0 and set to the _params attribute.

fit(order)[source]

Do polynomial fitting and set the parameters. Uses numpy polyfit.

Parameters:: order (int) – order of the fit polynomial

class PourierTarantola(volumes, energies)[source]

Bases: EOSBase

PourierTarantola EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]: Pourier-Tarantola equation from PRB 70, 224107.

class Vinet(volumes, energies)[source]

Bases: EOSBase

Vinet EOS.

Parameters:

volumes (list/numpy.array) – volumes in Ang^3
energies (list/numpy.array) – energy in eV.

_abc_impl = <_abc._abc_data object>[source]

_func(volume, params)[source]: Vinet equation from PRB 70, 224107.

pymatgen.analysis.ewald module

This module provides classes for calculating the Ewald sum of a structure.

class EwaldMinimizer(matrix, m_list, num_to_return=1, algo=0)[source]

Bases: object

This class determines the manipulations that will minimize an Ewald matrix, given a list of possible manipulations. This class does not perform the manipulations on a structure, but will return the list of manipulations that should be done on one to produce the minimal structure. It returns the manipulations for the n lowest energy orderings. This class should be used to perform fractional species substitution or fractional species removal to produce a new structure. These manipulations create large numbers of candidate structures, and this class can be used to pick out those with the lowest Ewald sum.

An alternative (possibly more intuitive) interface to this class is the order disordered structure transformation.

Author - Will Richards

Parameters:

matrix – A matrix of the Ewald sum interaction energies. This is stored in the class as a diagonally symmetric array and so self._matrix will not be the same as the input matrix.
m_list – list of manipulations. each item is of the form (multiplication fraction, number_of_indices, indices, species) These are sorted such that the first manipulation contains the most permutations. this is actually evaluated last in the recursion since I’m using pop.
num_to_return – The minimizer will find the number_returned lowest energy structures. This is likely to return a number of duplicate structures so it may be necessary to overestimate and then remove the duplicates later. (duplicate checking in this process is extremely expensive).

ALGO_BEST_FIRST = 2[source]

Slowly increases the speed (with the cost of decreasing accuracy) as the minimizer runs. Attempts to limit the run time to approximately 30 minutes.

Type:: ALGO_TIME_LIMIT

ALGO_COMPLETE = 1[source]

ALGO_FAST = 0[source]

ALGO_TIME_LIMIT = 3[source]

_recurse(matrix, m_list, indices, output_m_list=None)[source]

This method recursively finds the minimal permutations using a binary tree search strategy.

Parameters:

matrix – The current matrix (with some permutations already performed).
m_list – The list of permutations still to be performed
indices – Set of indices which haven’t had a permutation performed on them.

add_m_list(matrix_sum, m_list)[source]: This adds an m_list to the output_lists and updates the current minimum if the list is full.

best_case(matrix, m_list, indices_left)[source]

Computes a best case given a matrix and manipulation list.

Parameters:

matrix – the current matrix (with some permutations already performed)
m_list – [(multiplication fraction, number_of_indices, indices, species)] describing the manipulation
indices – Set of indices which haven’t had a permutation performed on them.

property best_m_list[source]

Best m_list found.

Type:: Returns

classmethod get_next_index(matrix, manipulation, indices_left)[source]: Returns an index that should have the most negative effect on the matrix sum.

minimize_matrix()[source]: This method finds and returns the permutations that produce the lowest Ewald sum calls recursive function to iterate through permutations.

property minimized_sum[source]

Minimized sum.

Type:: Returns

property output_lists[source]

output lists.

Type:: Returns

class EwaldSummation(structure, real_space_cut=None, recip_space_cut=None, eta=None, acc_factor=12.0, w=0.7071067811865475, compute_forces=False)[source]

Bases: MSONable

Calculates the electrostatic energy of a periodic array of charges using the Ewald technique.

Ref:: Ewald summation techniques in perspective: a survey Abdulnour Y. Toukmaji and John A. Board Jr. DOI: 10.1016/0010-4655(96)00016-1 URL: http://www.ee.duke.edu/~ayt/ewaldpaper/ewaldpaper.html

This matrix can be used to do fast calculations of Ewald sums after species removal.

E = E_recip + E_real + E_point

Atomic units used in the code, then converted to eV.

Initializes and calculates the Ewald sum. Default convergence parameters have been specified, but you can override them if you wish.

Parameters:

structure (Structure) – Input structure that must have proper Species on all sites, i.e. Element with oxidation state. Use Structure.add_oxidation_state… for example.
real_space_cut (float) – Real space cutoff radius dictating how many terms are used in the real space sum. Defaults to None, which means determine automagically using the formula given in gulp 3.1 documentation.
recip_space_cut (float) – Reciprocal space cutoff radius. Defaults to None, which means determine automagically using the formula given in gulp 3.1 documentation.
eta (float) – The screening parameter. Defaults to None, which means determine automatically.
acc_factor (float) – No. of significant figures each sum is converged to.
w (float) – Weight parameter, w, has been included that represents the relative computational expense of calculating a term in real and reciprocal space. Default of 0.7 reproduces result similar to GULP 4.2. This has little effect on the total energy, but may influence speed of computation in large systems. Note that this parameter is used only when the cutoffs are set to None.
compute_forces (bool) – Whether to compute forces. False by default since it is usually not needed.

CONV_FACT = 14.39964547842567[source]

_calc_ewald_terms()[source]: Calculates and sets all Ewald terms (point, real and reciprocal).

_calc_real_and_point()[source]: Determines the self energy -(eta/pi)**(1/2) * sum_{i=1}^{N} q_i**2.

_calc_recip()[source]

Perform the reciprocal space summation. Calculates the quantity E_recip = 1/(2PiV) sum_{G < Gmax} exp(-(G.G/4/eta))/(G.G) S(G)S(-G) where S(G) = sum_{k=1,N} q_k exp(-i G.r_k) S(G)S(-G) = |S(G)|**2.

This method is heavily vectorized to utilize numpy’s C backend for speed.

as_dict(verbosity: int = 0) → dict[source]

Json-serialization dict representation of EwaldSummation.

Parameters:: verbosity (int) – Verbosity level. Default of 0 only includes the matrix representation. Set to 1 for more details.

compute_partial_energy(removed_indices)[source]: Gives total Ewald energy for certain sites being removed, i.e. zeroed out.

compute_sub_structure(sub_structure, tol: float = 0.001)[source]

Gives total Ewald energy for an sub structure in the same lattice. The sub_structure must be a subset of the original structure, with possible different charges.

Parameters:

substructure (Structure) – Substructure to compute Ewald sum for.
tol (float) – Tolerance for site matching in fractional coordinates.

Returns:

Ewald sum of substructure.

property eta[source]

eta value used in Ewald summation.

Type:: Returns

property forces[source]: The forces on each site as a Nx3 matrix. Each row corresponds to a site.

classmethod from_dict(d: dict[str, Any], fmt: str | None = None, **kwargs) → EwaldSummation[source]

Create an EwaldSummation instance from JSON-serialized dictionary.

Parameters:

d (dict) – Dictionary representation
fmt (str, optional) – Unused. Defaults to None.

Returns:

class instance

Return type:

EwaldSummation

get_site_energy(site_index)[source]

Compute the energy for a single site in the structure.

Parameters:: site_index (int) – Index of site

ReturnS: (float) - Energy of that site

property point_energy[source]: The point energy.

property point_energy_matrix[source]: The point space matrix. A diagonal matrix with the point terms for each site in the diagonal elements.

property real_space_energy[source]: The real space energy.

property real_space_energy_matrix[source]: The real space energy matrix. Each matrix element (i, j) corresponds to the interaction energy between site i and site j in real space.

property reciprocal_space_energy[source]: The reciprocal space energy.

property reciprocal_space_energy_matrix[source]: The reciprocal space energy matrix. Each matrix element (i, j) corresponds to the interaction energy between site i and site j in reciprocal space.

property total_energy[source]: The total energy.

property total_energy_matrix[source]

The total energy matrix. Each matrix element (i, j) corresponds to the total interaction energy between site i and site j.

Note that this does not include the charged-cell energy, which is only important when the simulation cell is not charge balanced.

compute_average_oxidation_state(site)[source]

Calculates the average oxidation state of a site.

Parameters:: site – Site to compute average oxidation state
Returns:: Average oxidation state of site.

pymatgen.analysis.excitation module

This module defines an excitation spectrum class.

class ExcitationSpectrum(x, y)[source]

Bases: Spectrum

Basic excitation spectrum object.

Parameters:

x – A sequence of x-ray energies in eV
y – A sequence of intensity values.

XLABEL = 'Energy (eV)'[source]

YLABEL = 'Intensity'[source]

pymatgen.analysis.fragmenter module

Perform fragmentation of molecules.

class Fragmenter(molecule, edges=None, depth=1, open_rings=False, use_metal_edge_extender=False, opt_steps=10000, prev_unique_frag_dict=None, assume_previous_thoroughness=True)[source]

Bases: MSONable

Molecule fragmenter class.

Standard constructor for molecule fragmentation.

Parameters:

molecule (Molecule) – The molecule to fragment.
edges (list) – List of index pairs that define graph edges, aka molecule bonds. If not set, edges will be determined with OpenBabel. Defaults to None.
depth (int) – The number of levels of iterative fragmentation to perform, where each level will include fragments obtained by breaking one bond of a fragment one level up. Defaults to 1. However, if set to 0, instead all possible fragments are generated using an alternative, non-iterative scheme.
open_rings (bool) – Whether or not to open any rings encountered during fragmentation. Defaults to False. If true, any bond that fails to yield disconnected graphs when broken is instead removed and the entire structure is optimized with OpenBabel in order to obtain a good initial guess for an opened geometry that can then be put back into QChem to be optimized without the ring just reforming.
use_metal_edge_extender (bool) – Whether or not to attempt to add additional edges from O, N, F, or Cl to any Li or Mg atoms present that OpenBabel may have missed. Defaults to False. Most important for ionic bonding. Note that additional metal edges may yield new “rings” (e.g. -C-O-Li-O- in LiEC) that will not play nicely with ring opening.
opt_steps (int) – Number of optimization steps when opening rings. Defaults to 10000.
prev_unique_frag_dict (dict) – A dictionary of previously identified unique fragments. Defaults to None. Typically only used when trying to find the set of unique fragments that come from multiple molecules.
assume_previous_thoroughness (bool) – Whether or not to assume that a molecule / fragment provided in prev_unique_frag_dict has all of its unique subfragments also provided in prev_unique_frag_dict. Defaults to True. This is an essential optimization when trying to find the set of unique fragments that come from multiple molecules if all of those molecules are being fully iteratively fragmented. However, if you’re passing a prev_unique_frag_dict which includes a molecule and its fragments that were generated at insufficient depth to find all possible subfragments to a fragmentation calculation of a different molecule that you aim to find all possible subfragments of and which has common subfragments with the previous molecule, this optimization will cause you to miss some unique subfragments.

_fragment_one_level(old_frag_dict)[source]: Perform one step of iterative fragmentation on a list of molecule graphs. Loop through the graphs, then loop through each graph’s edges and attempt to remove that edge in order to obtain two disconnected subgraphs, aka two new fragments. If successful, check to see if the new fragments are already present in self.unique_fragments, and append them if not. If unsuccessful, we know that edge belongs to a ring. If we are opening rings, do so with that bond, and then again check if the resulting fragment is present in self.unique_fragments and add it if it is not.

_open_all_rings()[source]: Having already generated all unique fragments that did not require ring opening, now we want to also obtain fragments that do require opening. We achieve this by looping through all unique fragments and opening each bond present in any ring we find. We also temporarily add the principle molecule graph to self.unique_fragments so that its rings are opened as well.

open_ring(mol_graph, bond, opt_steps)[source]: Function to actually open a ring using OpenBabel’s local opt. Given a molecule graph and a bond, convert the molecule graph into an OpenBabel molecule, remove the given bond, perform the local opt with the number of steps determined by self.steps, and then convert the resulting structure back into a molecule graph to be returned.

pymatgen.analysis.functional_groups module

Determine functional groups present in a Molecule.

class FunctionalGroupExtractor(molecule, optimize=False)[source]

Bases: object

This class is used to algorithmically parse a molecule (represented by an instance of pymatgen.analysis.graphs.MoleculeGraph) and determine arbitrary functional groups.

Instantiation method for FunctionalGroupExtractor.

Parameters:

molecule – Either a filename, a pymatgen.core.structure.Molecule object, or a pymatgen.analysis.graphs.MoleculeGraph object.
optimize – Default False. If True, then the input molecule will be modified, adding Hydrogens, performing a simple conformer search, etc.

categorize_functional_groups(groups)[source]

Determine classes of functional groups present in a set.

Parameters:: groups – Set of functional groups.
Returns:: dict containing representations of the groups, the indices of where the group occurs in the MoleculeGraph, and how many of each type of group there is.

get_all_functional_groups(elements=None, func_groups=None, catch_basic=True)[source]

Identify all functional groups (or all within a certain subset) in the molecule, combining the methods described above.

Parameters:

elements – List of elements that will qualify a carbon as special (if only certain functional groups are of interest). Default None.
func_groups – List of strs representing the functional groups of interest. Default to None, meaning that all of the functional groups defined in this function will be sought.
catch_basic – bool. If True, use get_basic_functional_groups and other methods

Returns:

list of sets of ints, representing groups of connected atoms

get_basic_functional_groups(func_groups=None)[source]

Identify functional groups that cannot be identified by the Ertl method of get_special_carbon and get_heteroatoms, such as benzene rings, methyl groups, and ethyl groups.

TODO: Think of other functional groups that are important enough to be added (ex: do we need ethyl, butyl, propyl?)

Parameters:: func_groups – List of strs representing the functional groups of interest. Default to None, meaning that all of the functional groups defined in this function will be sought.
Returns:: list of sets of ints, representing groups of connected atoms

get_heteroatoms(elements=None)[source]

Identify non-H, non-C atoms in the MoleculeGraph, returning a list of their node indices.

Parameters:: elements – List of elements to identify (if only certain functional groups are of interest).
Returns:: set of ints representing node indices

get_special_carbon(elements=None)[source]

Identify Carbon atoms in the MoleculeGraph that fit the characteristics defined Ertl (2017), returning a list of their node indices.

The conditions for marking carbon atoms are (quoted from Ertl):: “- atoms connected by non-aromatic double or triple bond to any heteroatom - atoms in nonaromatic carbon-carbon double or triple bonds - acetal carbons, i.e. sp3 carbons connected to two or more oxygens, nitrogens or sulfurs; these O, N or S atoms must have only single bonds - all atoms in oxirane, aziridine and thiirane rings”

Parameters:: elements – List of elements that will qualify a carbon as special (if only certain functional groups are of interest). Default None.
Returns:: set of ints representing node indices

link_marked_atoms(atoms)[source]

Take a list of marked “interesting” atoms (heteroatoms, special carbons) and attempt to connect them, returning a list of disjoint groups of special atoms (and their connected hydrogens).

Parameters:: atoms – set of marked “interesting” atoms, presumably identified using other functions in this class.
Returns:: list of sets of ints, representing groups of connected atoms

pymatgen.analysis.graphs module

Module for graph representations of crystals and molecules.

class ConnectedSite(site, jimage, index, weight, dist)[source]

Bases: tuple

Create new instance of ConnectedSite(site, jimage, index, weight, dist)

_asdict()[source]: Return a new dict which maps field names to their values.

_field_defaults = {}[source]

_fields = ('site', 'jimage', 'index', 'weight', 'dist')[source]

classmethod _make(iterable)[source]: Make a new ConnectedSite object from a sequence or iterable

_replace(**kwds)[source]: Return a new ConnectedSite object replacing specified fields with new values

dist[source]: Alias for field number 4

index[source]: Alias for field number 2

jimage[source]: Alias for field number 1

site[source]: Alias for field number 0

weight[source]: Alias for field number 3

exception MolGraphSplitError[source]

Bases: Exception

Raised when a molecule graph is failed to split into two disconnected subgraphs.

class MoleculeGraph(molecule, graph_data=None)[source]

Bases: MSONable

This is a class for annotating a Molecule with bond information, stored in the form of a graph. A “bond” does not necessarily have to be a chemical bond, but can store any kind of information that connects two Sites.

If constructing this class manually, use the with_empty_graph method or with_local_env_strategy method (using an algorithm provided by the local_env module, such as O’Keeffe).

This class that contains connection information: relationships between sites represented by a Graph structure, and an associated structure object.

This class uses the NetworkX package to store and operate on the graph itself, but contains a lot of helper methods to make associating a graph with a given molecule easier.

Use cases for this include storing bonding information, NMR J-couplings, Heisenberg exchange parameters, etc.

Parameters:

molecule – Molecule object
graph_data – dict containing graph information in dict format (not intended to be constructed manually, see as_dict method for format)

classmethod _edges_to_string(g)[source]

add_edge(from_index, to_index, weight=None, warn_duplicates=True, edge_properties=None)[source]

Add edge to graph.

Since physically a ‘bond’ (or other connection between sites) doesn’t have a direction, from_index, from_jimage can be swapped with to_index, to_jimage.

However, images will always be shifted so that from_index < to_index and from_jimage becomes (0, 0, 0).

Parameters:

from_index – index of site connecting from
to_index – index of site connecting to
(float) (weight) – e.g. bond length
(bool) (warn_duplicates) – if True, will warn if trying to add duplicate edges (duplicate edges will not be added in either case)
(dict) (edge_properties) – any other information to store on graph edges, similar to Structure’s site_properties

Returns:

alter_edge(from_index, to_index, new_weight=None, new_edge_properties=None)[source]

Alters either the weight or the edge_properties of an edge in the MoleculeGraph.

Parameters:

from_index – int
to_index – int
new_weight – alter_edge does not require that weight be altered. As such, by default, this is None. If weight is to be changed, it should be a float.
new_edge_properties – alter_edge does not require that edge_properties be altered. As such, by default, this is None. If any edge properties are to be changed, it should be a dictionary of edge properties to be changed.

Returns:

as_dict()[source]: As in pymatgen.core.Molecule except with using to_dict_of_dicts from NetworkX to store graph information.

break_edge(from_index, to_index, allow_reverse=False)[source]

Remove an edge from the MoleculeGraph.

Parameters:

from_index – int
to_index – int
allow_reverse – If allow_reverse is True, then break_edge will attempt to break both (from_index, to_index) and, failing that, will attempt to break (to_index, from_index).

Returns:

build_unique_fragments()[source]

Find all possible fragment combinations of the MoleculeGraphs (in other words, all connected induced subgraphs).

Returns:

diff(other, strict=True)[source]

Compares two MoleculeGraphs. Returns dict with keys ‘self’, ‘other’, ‘both’ with edges that are present in only one MoleculeGraph (‘self’ and ‘other’), and edges that are present in both.

The Jaccard distance is a simple measure of the dissimilarity between two MoleculeGraphs (ignoring edge weights), and is defined by 1 - (size of the intersection / size of the union) of the sets of edges. This is returned with key ‘dist’.

Important note: all node indices are in terms of the MoleculeGraph this method is called from, not the ‘other’ MoleculeGraph: there is no guarantee the node indices will be the same if the underlying Molecules are ordered differently.

Parameters:

other – MoleculeGraph
strict – if False, will compare bonds from different Molecules, with node indices replaced by Species strings, will not count number of occurrences of bonds

Returns:

draw_graph_to_file(filename='graph', diff=None, hide_unconnected_nodes=False, hide_image_edges=True, edge_colors=False, node_labels=False, weight_labels=False, image_labels=False, color_scheme='VESTA', keep_dot=False, algo='fdp')[source]

Draws graph using GraphViz.

The networkx graph object itself can also be drawn with networkx’s in-built graph drawing methods, but note that this might give misleading results for multigraphs (edges are super-imposed on each other).

If visualization is difficult to interpret, hide_image_edges can help, especially in larger graphs.

Parameters:

filename – filename to output, will detect filetype from extension (any graphviz filetype supported, such as pdf or png)
(StructureGraph) (diff) – an additional graph to compare with, will color edges red that do not exist in diff and edges green that are in diff graph but not in the reference graph
hide_unconnected_nodes – if True, hide unconnected nodes
hide_image_edges – if True, do not draw edges that go through periodic boundaries
(bool) (keep_dot) – if True, use node colors to color edges
(bool) – if True, label nodes with species and site index
(bool) – if True, label edges with weights
(bool) – if True, label edges with their periodic images (usually only used for debugging, edges to periodic images always appear as dashed lines)
(str) (color_scheme) – “VESTA” or “JMOL”
(bool) – keep GraphViz .dot file for later visualization
algo – any graphviz algo, “neato” (for simple graphs) or “fdp” (for more crowded graphs) usually give good outputs

Returns:

property edge_weight_name[source]

Name of the edge weight property of graph

Type:: return

property edge_weight_unit[source]

Units of the edge weight property of graph

Type:: return

find_rings(including=None) → list[list[tuple[int, int]]][source]

Find ring structures in the MoleculeGraph.

Parameters:

including (list[int]) – list of site indices. If including is not None, then find_rings
default (will only return those rings including the specified sites. By) –
parameter (this) –
None (is) –
returned. (and all rings will be) –

Returns:

Each entry will be a ring (cycle, in graph theory terms): including the index found in the Molecule. If there is no cycle including an index, the value will be an empty list.

Return type:

list[list[tuple[int, int]]]

classmethod from_dict(dct)[source]: As in pymatgen.core.Molecule except restoring graphs using from_dict_of_dicts from NetworkX to restore graph information.

get_connected_sites(n)[source]: Returns a named tuple of neighbors of site n: periodic_site, jimage, index, weight. Index is the index of the corresponding site in the original structure, weight can be None if not defined. :param n: index of Site in Molecule :param jimage: lattice vector of site :return: list of ConnectedSite tuples,

sorted by closest first.

get_coordination_of_site(n)[source]: Returns the number of neighbors of site n. In graph terms, simply returns degree of node corresponding to site n. :param n: index of site :return (int):

get_disconnected_fragments(return_index_map: bool = False)[source]

Determine if the MoleculeGraph is connected. If it is not, separate the MoleculeGraph into different MoleculeGraphs, where each resulting MoleculeGraph is a disconnected subgraph of the original. Currently, this function naively assigns the charge of the total molecule to a single submolecule. A later effort will be to actually accurately assign charge.

Parameters:: return_index_map (bool) – If True, return a dictionary that maps the new indices to the original indices. Defaults to False.

NOTE: This function does not modify the original MoleculeGraph. It creates a copy, modifies that, and returns two or more new MoleculeGraph objects.

Returns:: Each MoleculeGraph is a disconnected subgraph of the original MoleculeGraph.
Return type:: list[MoleculeGraph]

insert_node(i, species, coords, validate_proximity=False, site_properties=None, edges=None)[source]

A wrapper around Molecule.insert(), which also incorporates the new site into the MoleculeGraph.

Parameters:

i – Index at which to insert the new site
species – Species for the new site
coords – 3x1 array representing coordinates of the new site
validate_proximity – For Molecule.insert(); if True (default False), distance will be checked to ensure that site can be safely added.
site_properties – Site properties for Molecule
edges – List of dicts representing edges to be added to the MoleculeGraph. These edges must include the index of the new site i, and all indices used for these edges should reflect the MoleculeGraph AFTER the insertion, NOT before. Each dict should at least have a “to_index” and “from_index” key, and can also have a “weight” and a “properties” key.

Returns:

isomorphic_to(other)[source]

Checks if the graphs of two MoleculeGraphs are isomorphic to one another. In order to prevent problems with misdirected edges, both graphs are converted into undirected nx.Graph objects.

Parameters:: other – MoleculeGraph object to be compared.
Returns:: bool

property name[source]

Name of graph

Type:: return

remove_nodes(indices)[source]

A wrapper for Molecule.remove_sites().

Parameters:: indices – list of indices in the current Molecule (and graph) to be removed.
Returns:

replace_group(index, func_grp, strategy, bond_order=1, graph_dict=None, strategy_params=None)[source]

Builds off of Molecule.substitute and MoleculeGraph.substitute_group to replace a functional group in self.molecule with a functional group. This method also amends self.graph to incorporate the new functional group.

TODO: Figure out how to replace into a ring structure.

Parameters:

index – Index of atom to substitute.
func_grp –
Substituent molecule. There are three options:
1. Providing an actual molecule as the input. The first atom must be a DummySpecies X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_grp should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
2. A string name. The molecule will be obtained from the relevant template in func_groups.json.
3. A MoleculeGraph object.
strategy – Class from pymatgen.analysis.local_env.
bond_order – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.
graph_dict – Dictionary representing the bonds of the functional group (format: {(u, v): props}, where props is a dictionary of properties, including weight. If None, then the algorithm will attempt to automatically determine bonds using one of a list of strategies defined in pymatgen.analysis.local_env.
strategy_params – dictionary of keyword arguments for strategy. If None, default parameters will be used.

Returns:

set_node_attributes()[source]

Replicates molecule site properties (specie, coords, etc.) in the MoleculeGraph.

Returns:

sort(key: Callable[[Molecule], float] | None = None, reverse: bool = False) → None[source]

Same as Molecule.sort(). Also remaps nodes in graph.

Parameters:

key (callable, optional) – Sort key. Defaults to None.
reverse (bool, optional) – Reverse sort order. Defaults to False.

split_molecule_subgraphs(bonds, allow_reverse=False, alterations=None)[source]

Split MoleculeGraph into two or more MoleculeGraphs by breaking a set of bonds. This function uses MoleculeGraph.break_edge repeatedly to create disjoint graphs (two or more separate molecules). This function does not only alter the graph information, but also changes the underlying Molecules. If the bonds parameter does not include sufficient bonds to separate two molecule fragments, then this function will fail. Currently, this function naively assigns the charge of the total molecule to a single submolecule. A later effort will be to actually accurately assign charge. NOTE: This function does not modify the original MoleculeGraph. It creates a copy, modifies that, and returns two or more new MoleculeGraph objects. :param bonds: list of tuples (from_index, to_index)

representing bonds to be broken to split the MoleculeGraph.

Parameters:

alterations – a dict {(from_index, to_index): alt}, where alt is a dictionary including weight and/or edge properties to be changed following the split.
allow_reverse – If allow_reverse is True, then break_edge will attempt to break both (from_index, to_index) and, failing that, will attempt to break (to_index, from_index).

Returns:

list of MoleculeGraphs.

substitute_group(index, func_grp, strategy, bond_order=1, graph_dict=None, strategy_params=None)[source]

Builds off of Molecule.substitute to replace an atom in self.molecule with a functional group. This method also amends self.graph to incorporate the new functional group.

NOTE: using a MoleculeGraph will generally produce a different graph compared with using a Molecule or str (when not using graph_dict).

Parameters:

index – Index of atom to substitute.
func_grp –
Substituent molecule. There are three options:
1. Providing an actual molecule as the input. The first atom
  must be a DummySpecies X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_grp should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
2. A string name. The molecule will be obtained from the
  relevant template in func_groups.json.
3. A MoleculeGraph object.
strategy – Class from pymatgen.analysis.local_env.
bond_order – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.
graph_dict – Dictionary representing the bonds of the functional group (format: {(u, v): props}, where props is a dictionary of properties, including weight. If None, then the algorithm will attempt to automatically determine bonds using one of a list of strategies defined in pymatgen.analysis.local_env.
strategy_params – dictionary of keyword arguments for strategy. If None, default parameters will be used.

Returns:

static with_edges(molecule, edges)[source]

Constructor for MoleculeGraph, using pre-existing or pre-defined edges with optional edge parameters.

Parameters:

molecule – Molecule object
edges – dict representing the bonds of the functional group (format: {(u, v): props}, where props is a dictionary of properties, including weight. Props should be None if no additional properties are to be specified.

Returns:

mg, a MoleculeGraph

classmethod with_empty_graph(molecule, name='bonds', edge_weight_name=None, edge_weight_units=None)[source]

Constructor for MoleculeGraph, returns a MoleculeGraph object with an empty graph (no edges, only nodes defined that correspond to Sites in Molecule).

Parameters:

(Molecule) (molecule) –
(str) (edge_weight_units) – name of graph, e.g. “bonds”
(str) – name of edge weights, e.g. “bond_length” or “exchange_constant”
(str) – name of edge weight units e.g. “Å” or “eV”

Return (MoleculeGraph):

static with_local_env_strategy(molecule, strategy)[source]

Constructor for MoleculeGraph, using a strategy from pymatgen.analysis.local_env.

Parameters:

molecule – Molecule object
strategy – an instance of a pymatgen.analysis.local_env.NearNeighbors object

Returns:

mg, a MoleculeGraph

class StructureGraph(structure: Structure, graph_data=None)[source]

Bases: MSONable

This is a class for annotating a Structure with bond information, stored in the form of a graph. A “bond” does not necessarily have to be a chemical bond, but can store any kind of information that connects two Sites.

If constructing this class manually, use the with_empty_graph method or with_local_env_strategy method (using an algorithm provided by the local_env module, such as O’Keeffe).

This class that contains connection information: relationships between sites represented by a Graph structure, and an associated structure object.

This class uses the NetworkX package to store and operate on the graph itself, but contains a lot of helper methods to make associating a graph with a given crystallographic structure easier.

Use cases for this include storing bonding information, NMR J-couplings, Heisenberg exchange parameters, etc.

For periodic graphs, class stores information on the graph edges of what lattice image the edge belongs to.

Parameters:

structure – a Structure object
graph_data – dict containing graph information in dict format (not intended to be constructed manually,

see as_dict method for format)

classmethod _edges_to_string(g)[source]

add_edge(from_index, to_index, from_jimage=(0, 0, 0), to_jimage=None, weight=None, warn_duplicates=True, edge_properties=None)[source]

Add edge to graph.

Since physically a ‘bond’ (or other connection between sites) doesn’t have a direction, from_index, from_jimage can be swapped with to_index, to_jimage.

However, images will always be shifted so that from_index < to_index and from_jimage becomes (0, 0, 0).

Parameters:

from_index – index of site connecting from
to_index – index of site connecting to
ints) (to_jimage (tuple of) – lattice vector of periodic image, e.g. (1, 0, 0) for periodic image in +x direction
ints) – lattice vector of image
(float) (weight) – e.g. bond length
(bool) (warn_duplicates) – if True, will warn if trying to add duplicate edges (duplicate edges will not be added in either case)
(dict) (edge_properties) – any other information to store on graph edges, similar to Structure’s site_properties

Returns:

alter_edge(from_index, to_index, to_jimage=None, new_weight=None, new_edge_properties=None)[source]

Alters either the weight or the edge_properties of an edge in the StructureGraph.

Parameters:

from_index – int
to_index – int
to_jimage – tuple
new_weight – alter_edge does not require that weight be altered. As such, by default, this is None. If weight is to be changed, it should be a float.
new_edge_properties – alter_edge does not require that edge_properties be altered. As such, by default, this is None. If any edge properties are to be changed, it should be a dictionary of edge properties to be changed.

Returns:

as_dict()[source]: As in pymatgen.core.Structure except with using to_dict_of_dicts from NetworkX to store graph information.

break_edge(from_index, to_index, to_jimage=None, allow_reverse=False)[source]

Remove an edge from the StructureGraph. If no image is given, this method will fail.

Parameters:

from_index – int
to_index – int
to_jimage – tuple
allow_reverse – If allow_reverse is True, then break_edge will attempt to break both (from_index, to_index) and, failing that, will attempt to break (to_index, from_index).

Returns:

diff(other, strict=True)[source]

Compares two StructureGraphs. Returns dict with keys ‘self’, ‘other’, ‘both’ with edges that are present in only one StructureGraph (‘self’ and ‘other’), and edges that are present in both.

The Jaccard distance is a simple measure of the dissimilarity between two StructureGraphs (ignoring edge weights), and is defined by 1 - (size of the intersection / size of the union) of the sets of edges. This is returned with key ‘dist’.

Important note: all node indices are in terms of the StructureGraph this method is called from, not the ‘other’ StructureGraph: there is no guarantee the node indices will be the same if the underlying Structures are ordered differently.

Parameters:

other – StructureGraph
strict – if False, will compare bonds from different Structures, with node indices replaced by Species strings, will not count number of occurrences of bonds

Returns:

draw_graph_to_file(filename='graph', diff=None, hide_unconnected_nodes=False, hide_image_edges=True, edge_colors=False, node_labels=False, weight_labels=False, image_labels=False, color_scheme='VESTA', keep_dot=False, algo='fdp')[source]

Draws graph using GraphViz.

The networkx graph object itself can also be drawn with networkx’s in-built graph drawing methods, but note that this might give misleading results for multigraphs (edges are super-imposed on each other).

If visualization is difficult to interpret, hide_image_edges can help, especially in larger graphs.

Parameters:

filename – filename to output, will detect filetype from extension (any graphviz filetype supported, such as pdf or png)
(StructureGraph) (diff) – an additional graph to compare with, will color edges red that do not exist in diff and edges green that are in diff graph but not in the reference graph
hide_unconnected_nodes – if True, hide unconnected nodes
hide_image_edges – if True, do not draw edges that go through periodic boundaries
(bool) (keep_dot) – if True, use node colors to color edges
(bool) – if True, label nodes with species and site index
(bool) – if True, label edges with weights
(bool) – if True, label edges with their periodic images (usually only used for debugging, edges to periodic images always appear as dashed lines)
(str) (color_scheme) – “VESTA” or “JMOL”
(bool) – keep GraphViz .dot file for later visualization
algo – any graphviz algo, “neato” (for simple graphs) or “fdp” (for more crowded graphs) usually give good outputs

Returns:

property edge_weight_name[source]

Name of the edge weight property of graph

Type:: return

property edge_weight_unit[source]

Units of the edge weight property of graph

Type:: return

classmethod from_dict(d)[source]: As in pymatgen.core.Structure except restoring graphs using from_dict_of_dicts from NetworkX to restore graph information.

get_connected_sites(n, jimage=(0, 0, 0))[source]: Returns a named tuple of neighbors of site n: periodic_site, jimage, index, weight. Index is the index of the corresponding site in the original structure, weight can be None if not defined. :param n: index of Site in Structure :param jimage: lattice vector of site :return: list of ConnectedSite tuples,

sorted by closest first.

get_coordination_of_site(n)[source]: Returns the number of neighbors of site n. In graph terms, simply returns degree of node corresponding to site n. :param n: index of site :return (int):

get_subgraphs_as_molecules(use_weights=False)[source]

Retrieve subgraphs as molecules, useful for extracting molecules from periodic crystals.

Will only return unique molecules, not any duplicates present in the crystal (a duplicate defined as an isomorphic subgraph).

Parameters:: (bool) (use_weights) – If True, only treat subgraphs as isomorphic if edges have the same weights. Typically, this means molecules will need to have the same bond lengths to be defined as duplicates, otherwise bond lengths can differ. This is a fairly robust approach, but will treat e.g. enantiomers as being duplicates.
Returns:: list of unique Molecules in Structure

insert_node(i, species, coords, coords_are_cartesian=False, validate_proximity=False, site_properties=None, edges=None)[source]

A wrapper around Molecule.insert(), which also incorporates the new site into the MoleculeGraph.

Parameters:

i – Index at which to insert the new site
species – Species for the new site
coords – 3x1 array representing coordinates of the new site
coords_are_cartesian – Whether coordinates are cartesian. Defaults to False.
validate_proximity – For Molecule.insert(); if True (default False), distance will be checked to ensure that site can be safely added.
site_properties – Site properties for Molecule
edges – List of dicts representing edges to be added to the MoleculeGraph. These edges must include the index of the new site i, and all indices used for these edges should reflect the MoleculeGraph AFTER the insertion, NOT before. Each dict should at least have a “to_index” and “from_index” key, and can also have a “weight” and a “properties” key.

Returns:

property name[source]

Name of graph

Type:: return

remove_nodes(indices)[source]

A wrapper for Molecule.remove_sites().

Parameters:: indices – list of indices in the current Molecule (and graph) to be removed.
Returns:

set_node_attributes()[source]

Gives each node a “specie” and a “coords” attribute, updated with the current species and coordinates.

Returns:

sort(key=None, reverse=False)[source]

Same as Structure.sort(). Also remaps nodes in graph.

Parameters:

key – key to sort by
reverse – reverse sort order

substitute_group(index, func_grp, strategy, bond_order=1, graph_dict=None, strategy_params=None)[source]

Builds off of Structure.substitute to replace an atom in self.structure with a functional group. This method also amends self.graph to incorporate the new functional group.

NOTE: Care must be taken to ensure that the functional group that is substituted will not place atoms to close to each other, or violate the dimensions of the Lattice.

Parameters:

index – Index of atom to substitute.
func_grp –
Substituent molecule. There are two options:
1. Providing an actual Molecule as the input. The first atom
  must be a DummySpecies X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_grp should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
2. A string name. The molecule will be obtained from the
  relevant template in func_groups.json.
strategy – Class from pymatgen.analysis.local_env.
bond_order – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.
graph_dict – Dictionary representing the bonds of the functional group (format: {(u, v): props}, where props is a dictionary of properties, including weight. If None, then the algorithm will attempt to automatically determine bonds using one of a list of strategies defined in pymatgen.analysis.local_env.
strategy_params – dictionary of keyword arguments for strategy. If None, default parameters will be used.

Returns:

property types_and_weights_of_connections[source]

Extract a dictionary summarizing the types and weights of edges in the graph.

Returns:: A dictionary with keys specifying the species involved in a connection in alphabetical order (e.g. string ‘Fe-O’) and values which are a list of weights for those connections (e.g. bond lengths).

types_of_coordination_environments(anonymous=False)[source]

Extract information on the different co-ordination environments present in the graph.

Parameters:: anonymous – if anonymous, will replace specie names with A, B, C, etc.
Returns:: a list of co-ordination environments, e.g. [‘Mo-S(6)’, ‘S-Mo(3)’]

property weight_statistics[source]

Extract a statistical summary of edge weights present in the graph.

Returns:: A dict with an ‘all_weights’ list, ‘minimum’, ‘maximum’, ‘median’, ‘mean’, ‘std_dev’

static with_edges(structure, edges)[source]

Constructor for MoleculeGraph, using pre-existing or pre-defined edges with optional edge parameters.

Parameters:

molecule – Molecule object
edges – dict representing the bonds of the functional group (format: {(from_index, to_index, from_image, to_image): props}, where props is a dictionary of properties, including weight. Props should be None if no additional properties are to be specified.

Returns:

sg, a StructureGraph

classmethod with_empty_graph(structure: Structure, name='bonds', edge_weight_name=None, edge_weight_units=None)[source]

Constructor for StructureGraph, returns a StructureGraph object with an empty graph (no edges, only nodes defined that correspond to Sites in Structure).

Parameters:

(Structure) (structure) –
(str) (edge_weight_units) – name of graph, e.g. “bonds”
(str) – name of edge weights, e.g. “bond_length” or “exchange_constant”
(str) – name of edge weight units e.g. “Å” or “eV”

Return (StructureGraph):

static with_local_env_strategy(structure, strategy, weights=False, edge_properties=False)[source]

Constructor for StructureGraph, using a strategy from pymatgen.analysis.local_env.

Parameters:

structure – Structure object
strategy – an instance of a pymatgen.analysis.local_env.NearNeighbors object
weights – if True, use weights from local_env class (consult relevant class for their meaning)
edge_properties – if True, edge_properties from neighbors will be used

Returns:

_compare(g1, g2, i1, i2)[source]: Helper function called by isomorphic to ensure comparison of node identities.

_igraph_from_nxgraph(graph)[source]: Helper function that converts a networkx graph object into an igraph graph object.

_isomorphic(frag1, frag2)[source]: Internal function to check if two graph objects are isomorphic, using igraph if if is available and networkx if it is not.

pymatgen.analysis.hhi module

This module is used to estimate the Herfindahl-Hirschman Index, or HHI, of chemical compounds. The HHI is a measure of how geographically confined or dispersed the elements comprising a compound are. A low HHI is desirable because it means the component elements are geographically dispersed.

Data/strategy from “Data-Driven Review of Thermoelectric Materials: Performance and Resource Considerations” by Gaultois et al., published in Chemistry of Materials (2013).

pymatgen.analysis.interface module

This module provides classes to store, generate, and manipulate material interfaces.

pymatgen.analysis.interface_reactions module

This module provides a class to predict and analyze interfacial reactions between two solids, with or without an open element (e.g., flowing O2).

class GrandPotentialInterfacialReactivity(c1: Composition, c2: Composition, grand_pd: GrandPotentialPhaseDiagram, pd_non_grand: PhaseDiagram, include_no_mixing_energy: bool = False, norm: bool = True, use_hull_energy: bool = True)[source]

Bases: InterfacialReactivity

Extends upon InterfacialReactivity to allow for modelling possible reactions at the interface between two solids in the presence of an open element. The thermodynamics of the open system are provided by the user via the GrandPotentialPhaseDiagram class.

Parameters:

c1 – Reactant 1 composition
c2 – Reactant 2 composition
grand_pd – Grand potential phase diagram object built from all elements in composition c1 and c2.
include_no_mixing_energy – No_mixing_energy for a reactant is the opposite number of its energy above grand potential convex hull. In cases where reactions involve elements reservoir, this param determines whether no_mixing_energy of reactants will be included in the final reaction energy calculation. By definition, if pd is not a GrandPotentialPhaseDiagram object, this param is False.
pd_non_grand – PhaseDiagram object but not GrandPotentialPhaseDiagram object built from elements in c1 and c2.
norm – Whether or not the total number of atoms in composition of reactant will be normalized to 1.
use_hull_energy – Whether or not use the convex hull energy for a given composition for reaction energy calculation. If false, the energy of ground state structure will be used instead. Note that in case when ground state can not be found for a composition, convex hull energy will be used associated with a warning message.

_get_grand_potential(composition: Composition) → float[source]

Computes the grand potential Phi at a given composition and chemical potential(s).

Parameters:: composition – Composition object.
Returns:: Grand potential at a given composition at chemical potential(s).

_get_reactants(x: float) → list[pymatgen.core.composition.Composition][source]: Returns a list of relevant reactant compositions given an x coordinate.

get_no_mixing_energy()[source]

Generates the opposite number of energy above grand potential convex hull for both reactants.

Returns:: [(reactant1, no_mixing_energy1),(reactant2,no_mixing_energy2)].

class InterfacialReactivity(c1: Composition, c2: Composition, pd: PhaseDiagram, norm: bool = True, use_hull_energy: bool = False, **kwargs)[source]

Bases: MSONable

Class for modeling an interface between two solids and its possible reactions. The two reactants are provided as Composition objects (c1 and c2), along with the relevant compositional PhaseDiagram object. Possible reactions are calculated by finding all points along a tie-line between c1 and c2 where there is a “kink” in the phase diagram; i.e. a point or facet of the phase diagram.

Please consider citing one or both of the following papers if you use this code in your own work.

References

Richards, W. D., Miara, L. J., Wang, Y., Kim, J. C., & Ceder, G. (2015). Interface stability in solid-state batteries. Chemistry of Materials, 28(1), 266-273. https://doi.org/10.1021/acs.chemmater.5b04082

Xiao, Y., Wang, Y., Bo, S.-H., Kim, J. C., Miara, L. J., & Ceder, G. (2019). Understanding interface stability in solid-state batteries. Nature Reviews Materials, 5(2), 105-126. https://doi.org/10.1038/s41578-019-0157-5

Parameters:

c1 – Reactant 1 composition
c2 – Reactant 2 composition
pd – Phase diagram object built from all elements in composition c1 and c2.
norm – Whether or not the total number of atoms in composition of reactant will be normalized to 1.
use_hull_energy – Whether or not use the convex hull energy for a given composition for reaction energy calculation. If false, the energy of ground state structure will be used instead. Note that in case when ground state can not be found for a composition, convex hull energy will be used associated with a warning message.

EV_TO_KJ_PER_MOL = 96.4853[source]

static _convert(x: float, factor1: float, factor2: float)[source]

Converts mixing ratio x in comp1 - comp2 tie line to that in c1 - c2 tie line.

Parameters:

x – Mixing ratio x in comp1 - comp2 tie line, a float between 0 and 1.
factor1 – Compositional ratio between composition c1 and processed composition comp1. E.g., factor for Composition(‘SiO2’) and Composition(‘O’) is 2.0.
factor2 – Compositional ratio between composition c2 and processed composition comp2.

Returns:

Mixing ratio in c1 - c2 tie line, a float between 0 and 1.

_get_elmt_amt_in_rxn(rxn: Reaction) → int[source]

Computes total number of atoms in a reaction formula for elements not in external reservoir. This method is used in the calculation of reaction energy per mol of reaction formula.

Parameters:: rxn – a Reaction object.
Returns:: Total number of atoms for non_reservoir elements.

_get_energy(x)[source]

Computes reaction energy in eV/atom at mixing ratio x : (1-x) for self.comp1 : self.comp2.

Parameters:: x (float) – Mixing ratio x of reactants, a float between 0 and 1.
Returns:: Reaction energy.

static _get_entry_energy(pd: PhaseDiagram, composition: Composition)[source]

Finds the lowest entry energy for entries matching the composition. Entries with non-negative formation energies are excluded. If no entry is found, use the convex hull energy for the composition.

Parameters:

pd – Phase diagram object
composition – Composition object that the target entry should match

Returns:

The lowest entry energy among entries matching the composition.

_get_matplotlib_figure() → Figure[source]: Returns a matplotlib figure of reaction kinks diagram.

_get_original_composition_ratio(reaction)[source]

Returns the molar mixing ratio between the reactants with ORIGINAL ( instead of processed) compositions for a reaction.

Parameters:: reaction (Reaction) – Reaction object that contains the original reactant compositions.
Returns:: The molar mixing ratio between the original reactant compositions for a reaction.

static _get_plotly_annotations(x: list[float], y: list[float], reactions: list[pymatgen.analysis.reaction_calculator.Reaction])[source]: Returns dictionary of annotations for the Plotly figure layout.

_get_plotly_figure() → Figure[source]: Returns a Plotly figure of reaction kinks diagram.

_get_reactants(x: float) → list[pymatgen.core.composition.Composition][source]: Returns a list of relevant reactant compositions given an x coordinate.

_get_reaction(x: float) → Reaction[source]

Generates balanced reaction at mixing ratio x : (1-x) for self.comp1 : self.comp2.

Parameters:: x (float) – Mixing ratio x of reactants, a float between 0 and 1.
Returns:: Reaction object.

_get_xaxis_title(latex: bool = True) → str[source]: Returns the formatted title of the x axis (using either html/latex).

static _reverse_convert(x: float, factor1: float, factor2: float)[source]

Converts mixing ratio x in c1 - c2 tie line to that in comp1 - comp2 tie line.

Parameters:

x – Mixing ratio x in c1 - c2 tie line, a float between 0 and 1.
factor1 – Compositional ratio between composition c1 and processed composition comp1. E.g., factor for Composition(‘SiO2’) and Composition(‘O’) is 2.
factor2 – Compositional ratio between composition c2 and processed composition comp2.

Returns:

Mixing ratio in comp1 - comp2 tie line, a float between 0 and 1.

classmethod get_chempot_correction(element: str, temp: float, pres: float)[source]

Get the normalized correction term Δμ for chemical potential of a gas phase consisting of element at given temperature and pressure, referenced to that in the standard state (T_std = 298.15 K, T_std = 1 bar). The gas phase is limited to be one of O2, N2, Cl2, F2, H2. Calculation formula can be found in the documentation of Materials Project website.

Parameters:

element – The string representing the element.
temp – The temperature of the gas phase in Kelvin.
pres – The pressure of the gas phase in Pa.

Returns:

The correction of chemical potential in eV/atom of the gas phase at given temperature and pressure.

get_critical_original_kink_ratio()[source]

Returns a list of molar mixing ratio for each kink between ORIGINAL (instead of processed) reactant compositions. This is the same list as mixing ratio obtained from get_kinks method if self.norm = False.

Returns:: A list of floats representing molar mixing ratios between the original reactant compositions for each kink.

get_dataframe() → DataFrame[source]: Returns a pandas DataFrame representation of the data produced by the get_kinks() method.

get_kinks() → list[tuple[int, float, float, pymatgen.analysis.reaction_calculator.Reaction, float]][source]

Finds all the kinks in mixing ratio where reaction products changes along the tie-line of composition self.c1 and composition self.c2.

Returns:: (index, mixing ratio, reaction energy in eV/atom, Reaction object, reaction energy per mol of formula in kJ/mol).
Return type:: List object of tuples, each of which contains 5 elements

property labels[source]: Returns a dictionary containing kink information: {index: ‘x= mixing_ratio energy= reaction_energy reaction_equation’}. E.g., {1: ‘x= 0 energy = 0 Mn -> Mn’,

2: ‘x= 0.5 energy = -15 O2 + Mn -> MnO2’, 3: ‘x= 1 energy = 0 O2 -> O2’}.

property minimum[source]

Finds the minimum reaction energy E_min and corresponding mixing ratio x_min.

Returns:: Tuple (x_min, E_min).

plot(backend: Literal['plotly', 'matplotlib'] = 'plotly') → Figure | plt.Figure[source]

Plots reaction energy as a function of mixing ratio x in self.c1 - self.c2 tie line.

Parameters:: backend ("plotly" | "matplotlib") – Plotting library used to create the plot. Defaults to “plotly” but can also be “matplotlib”.
Returns:: Plot of reaction energies as a function of mixing ratio

property products[source]: List of formulas of potential products. E.g., [‘Li’,’O2’,’Mn’].

pymatgen.analysis.local_env module

This module provides classes to perform analyses of the local environments (e.g., finding near neighbors) of single sites in molecules and structures.

class BrunnerNN_real(tol: float = 0.0001, cutoff=8.0)[source]

Bases: NearNeighbors

Determine coordination number using Brunner’s algorithm which counts the atoms that are within the largest gap in differences in real space interatomic distances. This algorithm uses Brunner’s method of largest gap in interatomic distances.

Parameters:

tol (float) – tolerance parameter for bond determination (default: 1E-4).
cutoff (float) – cutoff radius in Angstrom to look for near-neighbor atoms. Defaults to 8.0.

get_nn_info(structure: Structure, n: int)[source]

Get all near-neighbor sites as well as the associated image locations and weights of the site with index n in structure.

Parameters:

structure (Structure) – input structure.
n (int) – index of site for which to determine near-neighbor sites.

Returns:

tuples, each one: of which represents a coordinated site, its image location, and its weight.

Return type:

siw (list of tuples (Site, array, float))

property molecules_allowed[source]

can this NearNeighbors class be used with Molecule objects?

Type:: Boolean property

property structures_allowed[source]

can this NearNeighbors class be used with Structure objects?

Type:: Boolean property

class BrunnerNN_reciprocal(tol: float = 0.0001, cutoff=8.0)[source]

Bases: NearNeighbors

Determine coordination number using Brunner’s algorithm which counts the atoms that are within the largest gap in differences in real space interatomic distances. This algorithm uses Brunner’s method of largest reciprocal gap in interatomic distances.

Parameters:

tol (float) – tolerance parameter for bond determination (default: 1E-4).
cutoff (float) – cutoff radius in Angstrom to look for near-neighbor atoms. Defaults to 8.0.

get_nn_info(structure: Structure, n: int)[source]

Get all near-neighbor sites as well as the associated image locations and weights of the site with index n in structure.

Parameters:

structure (Structure) – input structure.
n (int) – index of site for which to determine near-neighbor sites.

Returns:

tuples, each one: of which represents a coordinated site, its image location, and its weight.

Return type:

siw (list of tuples (Site, array, float))

property molecules_allowed[source]

can this NearNeighbors class be used with Molecule objects?

Type:: Boolean property

property structures_allowed[source]

can this NearNeighbors class be used with Structure objects?

Type:: Boolean property

class BrunnerNN_relative(tol: float = 0.0001, cutoff=8.0)[source]

Bases: NearNeighbors

Determine coordination number using Brunner’s algorithm which counts the atoms that are within the largest gap in differences in real space interatomic distances. This algorithm uses Brunner’s method of of largest relative gap in interatomic distances.

Parameters:

tol (float) – tolerance parameter for bond determination (default: 1E-4).
cutoff (float) – cutoff radius in Angstrom to look for near-neighbor atoms. Defaults to 8.0.

get_nn_info(structure: Structure, n: int)[source]

Get all near-neighbor sites as well as the associated image locations and weights of the site with index n in structure.

Parameters:

structure (Structure) – input structure.
n (int) – index of site for which to determine near-neighbor sites.

Returns:

tuples, each one: of which represents a coordinated site, its image location, and its weight.

Return type:

siw (list of tuples (Site, array, float))

property molecules_allowed[source]

can this NearNeighbors class be used with Molecule objects?

Type:: Boolean property

property structures_allowed[source]

can this NearNeighbors class be used with Structure objects?

Type:: Boolean property

class CovalentBondNN(tol: float = 0.2, order=True)[source]

Bases: NearNeighbors

Determine near-neighbor sites and bond orders using built-in pymatgen.Molecule CovalentBond functionality.

NOTE: This strategy is only appropriate for molecules, and not for structures.

Parameters:

tol (float) – Tolerance for covalent bond checking.
order (bool) – If True (default), this class will compute bond orders. If False, bond lengths will be computed.

property extend_structure_molecules[source]

Do Molecules need to be converted to Structures to use this NearNeighbors class? Note: this property is not defined for classes for which molecules_allowed is False.

Type:: Boolean property

get_bonded_structure(structure: Structure, decorate: bool = False) → MoleculeGraph[source]

Obtain a MoleculeGraph object using this NearNeighbor class.

Parameters:

structure – Molecule object.
decorate (bool) – whether to annotate site properties
by (with order parameters using neighbors determined) –
class (this NearNeighbor) –

Returns: a pymatgen.analysis.graphs.MoleculeGraph object

get_nn_info(structure: Structure, n: int)[source]

Get all near-neighbor sites and weights (orders) of bonds for a given atom.

Parameters:

structure – input Molecule.
n – index of site for which to determine near neighbors.

Returns:

[dict] representing a neighboring site and the type of bond present between site n and the neighboring site.

get_nn_shell_info(structure: Structure, site_idx, shell)[source]

Get a certain nearest neighbor shell for a certain site.

Determines all non-backtracking paths through the neighbor network computed by get_nn_info. The weight is determined by multiplying the weight of the neighbor at each hop through the network. For example, a 2nd-nearest-neighbor that has a weight of 1 from its 1st-nearest-neighbor and weight 0.5 from the original site will be assigned a weight of 0.5.

As this calculation may involve computing the nearest neighbors of atoms multiple times, the calculation starts by computing all of the neighbor info and then calling _get_nn_shell_info. If you are likely to call this method for more than one site, consider calling get_all_nn first and then calling this protected method yourself.

Parameters:

structure (Molecule) – Input structure
site_idx (int) – index of site for which to determine neighbor information.
shell (int) – Which neighbor shell to retrieve (1 == 1st NN shell)

Returns:

list of dictionaries. Each entry in the list is information about: a certain neighbor in the structure, in the same format as get_nn_info.

property molecules_allowed[source]

can this NearNeighbors class be used with Molecule objects?

Type:: Boolean property

property structures_allowed[source]

can this NearNeighbors class be used with Structure objects?

Type:: Boolean property

class Critic2NN[source]

Bases: NearNeighbors

Performs a topological analysis using critic2 to obtain neighbor information, using a sum of atomic charge densities. If an actual charge density is available (e.g. from a VASP CHGCAR), see Critic2Caller directly instead.

Init for Critic2NN.

property extend_structure_molecules[source]

Do Molecules need to be converted to Structures to use this NearNeighbors class? Note: this property is not defined for classes for which molecules_allowed is False.

Type:: Boolean property

get_bonded_structure(structure: Structure, decorate: bool = False) → StructureGraph[source]

Parameters:

structure (Structure) – Input structure
decorate (bool, optional) – Whether to decorate the structure. Defaults to False.

Returns:

Bonded structure

Return type:

StructureGraph

get_nn_info(structure: Structure, n: int)[source]

Get all near-neighbor sites as well as the associated image locations and weights of the site with index n in structure.

Parameters:

structure (Structure) – input structure.
n (int) – index of site for which to determine near-neighbor sites.

Returns:

tuples, each one: of which represents a coordinated site, its image location, and its weight.

Return type:

siw (list of tuples (Site, array, float))

property molecules_allowed[source]

can this NearNeighbors class be used with Molecule objects?

Type:: Boolean property

property structures_allowed[source]

can this NearNeighbors class be used with Structure objects?

Type:: Boolean property

class CrystalNN(weighted_cn=False, cation_anion=False, distance_cutoffs=(0.5, 1), x_diff_weight=3.0, porous_adjustment=True, search_cutoff=7, fingerprint_length=None)[source]

Bases: NearNeighbors

This is a custom near-neighbor method intended for use in all kinds of periodic structures (metals, minerals, porous structures, etc). It is based on a Voronoi algorithm and uses the solid angle weights to determine the probability of various coordination environments. The algorithm can also modify probability using smooth distance cutoffs as well as Pauling electronegativity differences. The output can either be the most probable coordination environment or a weighted list of coordination environments.

Initialize CrystalNN with desired parameters. Default parameters assume “chemical bond” type behavior is desired. For geometric neighbor finding (e.g., structural framework), set (i) distance_cutoffs=None, (ii) x_diff_weight=0 and (optionally) (iii) porous_adjustment=False which will disregard the atomic identities and perform best for a purely geometric match.

Parameters:

weighted_cn – (bool) if set to True, will return fractional weights for each potential near neighbor.
cation_anion – (bool) if set True, will restrict bonding targets to sites with opposite or zero charge. Requires an oxidation states on all sites in the structure.
distance_cutoffs – ([float, float]) - if not None, penalizes neighbor distances greater than sum of covalent radii plus distance_cutoffs[0]. Distances greater than covalent radii sum plus distance_cutoffs[1] are enforced to have zero weight.
x_diff_weight – (float) - if multiple types of neighbor elements are possible, this sets preferences for targets with higher electronegativity difference.
porous_adjustment – (bool) - if True, readjusts Voronoi weights to better describe layered / porous structures
search_cutoff – (float) cutoff in Angstroms for initial neighbor search; this will be adjusted if needed internally
fingerprint_length – (int) if a fixed_length CN “fingerprint” is desired from get_nn_data(), set this parameter

class NNData(all_nninfo, cn_weights, cn_nninfo)[source]

Bases: tuple

Create new instance of NNData(all_nninfo, cn_weights, cn_nninfo)

_asdict()[source]: Return a new dict which maps field names to their values.

_field_defaults = {}[source]

_fields = ('all_nninfo', 'cn_weights', 'cn_nninfo')[source]

classmethod _make(iterable)