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: 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:

1. Determine “surface sites” by finding those within

   a height threshold along the miller index of the highest site

2. Create a network of surface sites using the Delaunay

   triangulation of the surface sites

3. Assign on-top, bridge, and hollow adsorption sites

   at the nodes, edges, and face centers of the Del. Triangulation

4. 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: Molecule, ads_coord, repeat=None, translate=True, reorient=True)[source]

Add 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]

Generate 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: Slab, height=0.9)[source]

Assign site properties.

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

Find 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[Site]) – sites from which to select

• indices (list[int]) – indices of sites 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]

Find 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: Slab, height=0.9, xy_tol=0.05)[source]

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

Parameters:

• slab (Slab) – slab for which to find 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) → Self[source]

Construct 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]

Generate 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]

Perform 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) – 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]

Get 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]

Prune 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]

Reduce 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: Slab) → SymmOp[source]

Get the transformation to rotate the z axis into the miller index.

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

Help 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]

Convert a Cartesian coordinate such that it is inside the unit cell.

reorient_z(structure)[source]

Reorient 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.

The provided entries 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[dict]) – 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: list, bonds: list) → list[source]

Build a new entry for bond dissociation that will be returned to the user.

Parameters:

• frags (list) – Fragments involved in the bond dissociation.

• bonds (list) – Bonds broken in the dissociation process.

Returns:

Formatted bond dissociation entries.

Return type:

list

filter_fragment_entries(fragment_entries: list) → None[source]

Filter the fragment entries.

Parameters:

fragment_entries (List) – Fragment entries to be filtered.

fragment_and_process(bonds)[source]

Fragment and process bonds.

Parameters:

bonds (list) – bonds to process.

search_fragment_entries(frag) → list[source]

Search all fragment entries for those isomorphic to the given fragment. We distinguish between entries where both initial and final MoleculeGraphs are isomorphic to the given fragment (entries) vs those where only the initial MoleculeGraph is isomorphic to the given fragment (initial_entries) vs those where only the final MoleculeGraph 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.

Initialize 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]

get_oxi_state_decorated_structure(structure: Structure) → Structure[source]

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

Parameters:

structure – Structure to analyze

Returns:

modified with oxidation state decorations.

Return type:

Structure

Raises:

ValueError if the valences cannot be determined. –

get_valences(structure: Structure)[source]

Get 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: Structure, oxidation_states: list[list[int]]) → Structure[source]

Add oxidation states to a structure by fractional site.

Parameters:

oxidation_states (list[list[int]]) – 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]

Calculate 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]

Calculate 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).

property border_hyperplanes: ndarray[source]

Bordering hyperplanes.

property chemical_system: str[source]

The chemical system (A-B-C-…) of diagram object.

property domains: dict[str, ndarray][source]

Mapping of formulas to array of domain boundary points.

property el_refs: dict[Element, PDEntry][source]

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:

plotly.graph_objects.Figure

property hyperplane_entries: list[PDEntry][source]

List of entries corresponding to hyperplanes.

property hyperplanes: ndarray[source]

Array of hyperplane data.

property lims: ndarray[source]

Array of limits used in constructing hyperplanes.

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:

Giving 2-d centroid coordinates.

Return type:

np.ndarray

simple_pca(data: ndarray, k: int = 2) → tuple[ndarray, ndarray, 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:

projected data, eigenvalues, eigenvectors

Return type:

tuple

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: CostDB)[source]

Bases: object

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

Parameters:

costdb (CostDB) – Cost database to use.

get_cost_per_kg(comp)[source]

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

Parameters:

comp (CompositionLike) – chemical formula

Returns:

energy cost/kg

Return type:

float

get_cost_per_mol(comp: CompositionLike) → float[source]

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

Parameters:

comp (CompositionLike) – chemical formula

Returns:

energy cost/mol

Return type:

float

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: ABC

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

abstract get_entries(chemsys)[source]

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

Parameters:

chemsys (list[SpeciesLike]) – Elements defining the chemical system.

Returns:

list[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.

get_entries(chemsys)[source]

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

Parameters:

chemsys (list[Element]) – 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) – chemical composition of the entry

• cost (float) – per mol, NOT per kg of the full Composition

• name (str) – Optional parameter to name the entry. Defaults to the reduced chemical formula as in PDEntry.

• reference (str) – Reference data as BiBTeX string.

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]

Calculate 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 | tuple

find_clusters(struct, connected_matrix)[source]

Find 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]

Find 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 (dict[tuple, float]) – bonds are specified as a dict of 2-tuples of Species mapped to floats, the max bonding distance. For example, PO4 groups may be defined as {(“P”, “O”): 3}.

Returns:

the dimensionality of the structure - 1 (molecules/chains),

2 (layered), or 3 (3D)

Return type:

int

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[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, ABC

Abstract structure filter class.

classmethod from_dict(dct: dict) → Self[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.

Initialize 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 automatically using the formula given in gulp 3.1 documentation.

• recip_space_cut (float) – Reciprocal space cutoff radius. Defaults to None, which means determine automatically 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.

as_dict()[source]

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.

as_dict()[source]

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.

as_dict()[source]

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 negative of the spacegroup number. Higher symmetry => lower “energy”.

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

Parameters:

• symprec (float) – Symmetry tolerance. Defaults to 0.1.

• angle_tolerance (float) – Tolerance for angles. Defaults to 5 degrees.

as_dict()[source]

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 (Sequence[float]) – in Ang^3.

• energies (Sequence[float]) – in eV.

class BirchMurnaghan(volumes, energies)[source]

Bases: EOSBase

BirchMurnaghan EOS.

Parameters:

• volumes (Sequence[float]) – in Ang^3.

• energies (Sequence[float]) – in eV.

class DeltaFactor(volumes, energies)[source]

Bases: PolynomialEOS

Fitting a polynomial EOS using delta factor.

Parameters:

• volumes (Sequence[float]) – in Ang^3.

• energies (Sequence[float]) – in eV.

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: ClassVar = {'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 (Sequence[float]) – in Ang^3

• energies (Sequence[float]) – in eV

Returns:

EOSBase object

Return type:

EOSBase

class EOSBase(volumes, energies)[source]

Bases: ABC

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

Parameters:

• volumes (Sequence[float]) – in Ang^3.

• energies (Sequence[float]) – in eV.

property b0: float[source]

The bulk modulus in units of energy/unit of volume^3.

property b0_GPa: FloatWithUnit[source]

The bulk modulus in GPa. This assumes the energy and volumes are in eV and Ang^3.

property b1[source]

The derivative of bulk modulus w.r.t. pressure(dimensionless).

property e0: float[source]

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 (float | list[float]) – volumes in Ang^3

Returns:

numpy.array

plot(width=8, height=None, ax: plt.Axes = 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.

• ax (plt.Axes) – If supplied, changes will be made to the existing Axes. Otherwise, new Axes will be created.

• dpi

• kwargs (dict) – additional args fed to pyplot.plot. supported keys: style, color, text, label

Returns:

The matplotlib axes.

Return type:

plt.Axes

plot_ax(ax: plt.Axes = 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.

Return type:

plt.Figure

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]

A summary dict.

property v0[source]

The minimum or the reference volume in Ang^3.